文件配置

一句话：决定「上传的文件落到哪里」：数据库 / 本地磁盘 / FTP / SFTP / S3 五种存储器各建一套配置，其中标为主配置的那一套是当前生效的——头像、富文本插图、附件上传全都走它。

功能在哪

• 菜单路径：基础设施 → 文件管理 → 文件配置
• 地址栏路由：/infra/file/file-config
• 主要权限：infra:file-config:query / create / update / delete

界面认识

区域	作用	常用操作
查询区	配置名 / 存储器 / 创建时间	「搜索」「重置」
工具条	整页级动作	「新增」
列表	序号 / 配置名 / 存储器 / 备注 / 主配置 / 创建时间	行内「编辑」「主配置」「测试」「删除」
主配置列	标签「是」标记当前生效的一套	全表有且仅有一行为是

常用操作

新增一套存储配置

1. 点「新增」，填「配置名」（如「公司 MinIO」）与备注；
2. 选「存储器」：数据库 / 本地磁盘 / FTP 服务器 / SFTP 服务器 / S3 对象存储；
3. 表单会按所选存储器动态展开对应的连接字段（见「字段说明」）；
4. 点「确定」。

结果：列表多一行，「主配置」为否——新建不影响现有上传，只有手动切主配置后才生效。

切换主配置

行内点「主配置」，确认框会把后果说清楚：

确认将「本地存储（示例）」设为主配置吗？此后上传的文件都会存到它这里，原来的主配置会被取消。

点「确定」后全站上传的落地位置立即切换。

切主配置是全站动作，先想清楚两件事

1. 旧文件不会搬家：切换前上传的文件仍留在原存储器里，文件列表中它们的 URL 继续指向原处（只要原配置还在就能访问）；切换只影响之后的上传。
2. 新配置必须先「测试」通过：密钥或路径填错的主配置会让全站上传立刻失败。先测试、再切主，是固定顺序。

测试：验证配置填没填对

行内点「测试」：系统用这套配置真传一个测试文件，成功后提示「测试上传成功」并询问「是否要访问该文件？」，点确定会新开窗口打开该文件 URL——能打开图片，说明连接、密钥、路径、域名全链路都通。

删除

行内「删除」，二次确认后删除。主配置不允许删除：「该文件配置不允许删除，原因：它是主配置，删除会导致无法上传文件」——先把主配置切到别套，再删它。

字段说明

通用字段：配置名（必填）、备注、存储器（必填）、自定义域名（必填，文件 URL 的前缀域名）。连接字段按存储器动态展开：

字段	出现的存储器	说明
基础路径	本地磁盘 / FTP / SFTP	文件落盘的根目录
主机地址 / 主机端口 / 用户名 / 密码	FTP / SFTP	服务器连接四要素
连接模式	仅 FTP	主动 / 被动，按服务器侧配置选
节点地址	S3	服务端点（MinIO、各家云的对象存储地址）
存储 bucket	S3	桶名
accessKey / accessSecret	S3	访问密钥；secret 只在编辑时回填掩码，注意保管
是否 Path Style	S3	启用 / 禁用；MinIO 等自建服务通常启用
公开访问	S3	公开 / 私有；私有桶的文件 URL 需要签名才能访问
区域	S3	一般仅 AWS 需要填写

视角对照

视角	看到什么
超管 admin / 租户管理员 docadmin	全部配置，可新增、切主、测试、删除
套餐未含此菜单的租户	侧边栏「文件管理」下没有「文件配置」，上传仍按当前主配置正常工作
普通员工	无此菜单；只在业务页面里「用」上传，不关心落在哪

进阶

• 选哪种存储器：单机演示/小规模用本地磁盘最省事；多实例部署必须用共享存储（S3 / FTP / NAS 挂载），否则各实例各存一份会互相看不到；
• 上传上来的文件在文件列表查台账；业务表单里怎么用附件，见各业务页说明；
• 存储器字典取值：1=数据库、10=本地磁盘、11=FTP 服务器、12=SFTP 服务器、20=S3 对象存储（接口与排查日志里会看到这个编号）。

常见问题

Q：为什么删不掉某套配置？ A：它是主配置。先把主配置切到另一套测试通过的配置，再回来删它。

Q：切了主配置，旧文件会打不开吗？ A：不会。旧文件的 URL 仍指向原存储器，只要原配置没被删除就能继续访问；切换只影响新上传。

Q：测试成功但业务上传仍失败？ A：确认测试的是当前主配置那一行。测试只对单套配置负责，业务上传走的是主配置。

Q：S3 的「公开访问」选私有后，用户看图片会 403 吗？ A：私有桶的文件需要带签名访问；若业务侧直接拼裸 URL 会失败。没有签名读取需求的场景选公开更省事。

Q：配置里的密码/密钥安全吗？ A：存在后端配置表中，本页编辑时掩码回填。不要把演示配置的密钥用在生产；生产密钥建议走独立的密钥管理渠道。