存储配置
平台的文件（网站素材、对账单等）统一通过 S3 兼容协议存储，支持 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等 S3 兼容的对象存储。 配置入口：管理端 → 系统配置 → 平台配置 → 存储。
上传机制
平台使用「预签名直传」方式上传文件，分三步：
- 管理端向后端申请一个预签名上传地址；
- 浏览器拿地址直接把文件传到对象存储（文件不经过后端服务器）；
- 后端确认文件存在后登记文件记录。
因此有一个必须提前完成的动作：在存储桶上配置 CORS 跨域规则，否则「测试连接」通过、真正上传时仍然失败。以阿里云 OSS 为例（各云厂商位置类似：桶 → 数据安全 → 跨域设置）：
| 配置项 | 值 |
|---|---|
| 来源 Origin | 管理端访问地址，如 https://admin.example.com |
| 方法 Methods | PUT, GET, HEAD, POST |
| Allow Headers | * |
| Expose Headers | ETag |
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| 服务端点 | 是 | 存储服务的 API 地址，必须带 https://，且不要带桶名 |
| 存储区域 | 视情况 | 见下方「存储区域要不要填」 |
| 访问密钥 / 私有密钥 | 是 | 存储服务的 AccessKey / SecretKey |
| 路径样式访问 | 是 | 地址风格开关，见下方说明 |
| 公开存储桶 / 私有存储桶 | 是 | 桶名，可以填同一个桶，见「单桶说明」 |
| 公开访问域名 | 建议 | 公开桶文件的对外访问地址，不要带桶名（系统自动拼接桶名） |
| 私有访问域名 | 否 | 一般留空，私有文件走预签名地址访问 |
| 基础存储路径 | 否 | 对象键的统一前缀，如 daxpay |
| 上传预签名URL有效期 | 否 | 上传地址的有效分钟数，默认 10 分钟 |
| 下载或查看预签名URL有效期 | 否 | 私有文件访问地址的有效小时数，默认 72 小时 |
存储区域要不要填
「存储区域」只参与请求签名，不决定访问哪个数据中心——真正决定访问地址的是「服务端点」。所以多数场景这个参数可以不填：
| 存储服务 | 是否需要填写 | 示例值 |
|---|---|---|
| MinIO / 自建 S3 兼容存储 | 不需要，留空即可 | — |
| 阿里云 OSS | 建议填写 | cn-beijing、cn-hangzhou |
| 华为云 OBS | 建议填写 | cn-north-4 |
| 腾讯云 COS | 必须填写（校验签名区域） | ap-shanghai、ap-guangzhou |
| AWS S3 | 必须填写 | us-east-1、ap-northeast-1 |
| 七牛云 Kodo | 必须填写 | cn-east-1 |
| Cloudflare R2 | 固定值 | auto |
留空时按 us-east-1 参与签名，MinIO 等不校验签名区域的存储完全不受影响。具体区域代码以各厂商的 S3 兼容文档为准。
路径样式访问
同一个桶有两种地址风格：
- 路径样式（开启）：
https://服务端点/桶名/对象—— MinIO 等自建存储必须开启 - 虚拟主机样式（关闭）：
https://桶名.服务端点域名/对象—— 云厂商的原生风格
怎么选
自建 MinIO 一律开启；云厂商多数两种都支持，参照下方实例中的推荐值即可。
关于公开访问域名
公开文件的最终地址 = 公开访问域名 / 公开桶名 / 对象键，桶名由系统自动追加，所以：
- 这里填不带桶名的服务地址，如
https://oss-cn-beijing.aliyuncs.com - 如果给桶绑定了 CDN / 自定义域名，需保证按「域名/桶名/对象」的路径形态能访问到文件，否则会出现文件已上传但页面上图片裂图
单桶说明
公开桶和私有桶可以填同一个桶名，此时桶的读写权限建议设为「公共读」：公开文件可以直接访问，私有文件通过预签名地址访问也正常。
代价是「私有」变为名义私有——拿到完整地址的任何人都能读取该文件。生产环境建议分建两个桶，让权限语义真实成立。
配置实例
实例一：MinIO 自建
| 参数 | 值 |
|---|---|
| 服务端点 | https://minio.example.com（MinIO 的 API 端口，不是控制台端口） |
| 存储区域 | 留空 |
| 路径样式访问 | 开启 |
| 公开访问域名 | https://minio.example.com（或该 MinIO 对外的公开访问域名） |
密钥为 MinIO 的 AccessKey / SecretKey（通过 mc admin 创建用户时生成）。
实例二：阿里云 OSS（以华北2北京为例）
| 参数 | 值 |
|---|---|
| 服务端点 | https://oss-cn-beijing.aliyuncs.com |
| 存储区域 | cn-beijing |
| 路径样式访问 | 开启 |
| 公开存储桶 / 私有存储桶 | 如 daxpay-pub / daxpay-priv（或填同一个桶名） |
| 公开访问域名 | https://oss-cn-beijing.aliyuncs.com |
密钥为 RAM 用户的 AccessKey，最小权限需要两个桶上的 PutObject、GetObject、DeleteObject、ListObjects、GetBucketInfo。
注意：即使后端部署在阿里云 ECS 上，也不要把服务端点换成内网地址（-internal 结尾）——上传是浏览器直传，用户的浏览器访问不到内网地址。
实例三：腾讯云 COS（以上海为例）
| 参数 | 值 |
|---|---|
| 服务端点 | https://cos.ap-shanghai.myqcloud.com |
| 存储区域 | ap-shanghai（必须填写） |
| 路径样式访问 | 关闭 |
| 公开访问域名 | https://cos.ap-shanghai.myqcloud.com |
密钥为腾讯云子账号的 SecretId / SecretKey。
测试与排错
保存配置后点「测试连接」，系统会对两个桶各执行「桶存在 → 写入探测文件 → 读取 → 删除」的完整闭环，通过即说明读写权限就绪。
常见报错对照：
| 现象 | 原因 | 处理 |
|---|---|---|
| 测试通过，上传文件失败 | 存储桶未配置 CORS 跨域规则 | 按「上传机制」一节的表配置 |
| 写入失败，请检查密钥是否具备上传权限 | 密钥缺少写权限 / 桶策略拒绝写入 / 桶开启了 KMS 加密但密钥无 KMS 权限 | 后端日志搜「探测写入失败」看真实状态码；给密钥临时挂完全权限二分定位 |
| 文件已上传但图片显示不出来 | 公开访问域名带了桶名，或公开桶权限为私有 | 域名去掉桶名；公开桶权限设为公共读 |
| 上传成功但文件记录一直处理中 | 密钥能写不能读 | 补充读权限（GetObject） |
WARNING
「系统文件列表里有一条记录」不代表上传成功——记录在申请上传地址时就会创建，文件真正可访问才算完成。