存储配置
平台的文件（网站素材、对账单等）统一通过 S3 兼容协议存储，支持 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等 S3 兼容的对象存储。 配置入口：管理端 → 系统配置 → 平台配置 → 存储。
上传机制
平台使用「预签名直传」方式上传文件，分三步：
- 管理端向后端申请一个预签名上传地址；
- 浏览器拿地址直接把文件传到对象存储（文件不经过后端服务器）；
- 后端确认文件存在后登记文件记录。
因此有一个必须提前完成的动作：在存储桶上配置跨域(CORS)规则，否则「测试连接」通过、真正上传时仍然失败。配置方法与排查见 存储跨域(CORS)配置与上传排查。
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| 服务端点 | 是 | 存储服务的 API 地址，必须带 https://，且不要带桶名 |
| 存储区域 | 视情况 | 见下方「存储区域要不要填」 |
| 访问密钥 / 私有密钥 | 是 | 存储服务的 AccessKey / SecretKey |
| 路径样式访问 | 是 | 地址风格开关，见下方说明 |
| 公开存储桶 / 私有存储桶 | 是 | 桶名，可以填同一个桶，见「单桶说明」 |
| 公开访问域名 | 建议 | 公开桶文件的对外访问地址，必须以 http:// 或 https:// 开头，填法随「URL 拼接方式」而定，见下方说明 |
| URL 拼接方式 | 建议 | 公开文件地址的拼接形态：桶级域名（缺省）/ 带桶名，见下方说明 |
| 基础存储路径 | 否 | 对象键的统一前缀，如 daxpay |
| 上传预签名URL有效期 | 否 | 上传地址的有效分钟数，默认 10 分钟 |
| 下载或查看预签名URL有效期 | 否 | 私有文件访问地址的有效小时数，默认 72 小时 |
存储区域要不要填
「存储区域」只参与请求签名，不决定访问哪个数据中心，真正决定访问地址的是「服务端点」。所以多数场景这个参数可以不填：
| 存储服务 | 是否需要填写 | 示例值 |
|---|---|---|
| MinIO / 自建 S3 兼容存储 | 不需要，留空即可 | — |
| 阿里云 OSS | 留空即可，报签名区域错误时填写 | cn-beijing |
| 华为云 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 一律开启；云厂商多数两种都支持，参照下方实例中的推荐值即可。
关于公开访问域名与 URL 拼接方式
公开文件的最终地址由「公开访问域名 + URL 拼接方式」共同决定，两种拼接形态：
- 桶级域名（缺省）：URL =
域名/对象键。适用于域名直接绑定在桶上的形态，如 R2 桶级自定义域、给单个桶绑定的 CDN 域名。域名直接填桶级域名。 - 带桶名：URL =
域名/桶名/对象键。适用于一个根地址下多个桶共存的形态，如 MinIO、阿里云 OSS、腾讯云 COS 的原生域名。域名填根地址，桶名由系统自动拼接。
域名必须以 http:// 或 https:// 开头（配置页与后端都会校验拦截）：无协议前缀的地址在文件访问跳转时会被浏览器当作相对路径，公开文件将无法访问。
配置页会随表单值实时预览拼接出的完整地址，可直接核对形态是否选对；「测试连接」在公开访问探测 404 时会自动换另一种拼法重试，另一种能通时会直接提示切换拼接方式。
单桶说明
公开桶和私有桶可以填同一个桶名，此时桶的读写权限建议设为「公共读」：公开文件可以直接访问，私有文件通过预签名地址访问也正常。
代价是「私有」变为名义私有：拿到完整地址的任何人都能读取该文件。生产环境建议分建两个桶，让权限语义真实成立。
配置实例
TIP
实例中的端点地址、地域代码等取自各云平台官方文档。云厂商可能调整 S3 兼容端点形式与配置要求，实际填写时请以官方最新文档为准。
实例一：MinIO 自建
| 参数 | 值 |
|---|---|
| 服务端点 | https://minio.example.com（MinIO 的 API 端口，不是控制台端口） |
| 存储区域 | 留空 |
| 路径样式访问 | 开启 |
| 公开访问域名 | https://minio.example.com（或该 MinIO 对外的公开访问域名） |
| URL 拼接方式 | 带桶名（MinIO 多桶共用根地址，桶名由系统拼接） |
密钥为 MinIO 的 AccessKey / SecretKey（通过 mc admin 创建用户时生成）。
实例二：阿里云 OSS（以华北2北京为例）
| 参数 | 值 |
|---|---|
| 服务端点 | https://s3.oss-cn-beijing.aliyuncs.com（S3 兼容端点，带 s3. 前缀，见下方「S3 兼容说明」） |
| 存储区域 | 留空；报签名区域错误时填 cn-beijing |
| 路径样式访问 | 开启 |
| 公开存储桶 / 私有存储桶 | 如 daxpay-pub / daxpay-priv（或填同一个桶名） |
| 公开访问域名 | https://oss-cn-beijing.aliyuncs.com（原生域名，不带 s3. 前缀） |
| URL 拼接方式 | 带桶名（原生域名下多桶共根；若给桶单独绑定了自定义域名则改选桶级域名并填该域名） |
密钥为 RAM 用户的 AccessKey，最小权限需要两个桶上的 PutObject、GetObject、DeleteObject、ListObjects、GetBucketInfo。
注意：即使后端部署在阿里云 ECS 上，也不要把服务端点换成内网地址（-internal 结尾）。上传是浏览器直传，用户的浏览器访问不到内网地址。
实例三：腾讯云 COS（以上海为例）
| 参数 | 值 |
|---|---|
| 服务端点 | https://cos.ap-shanghai.myqcloud.com |
| 存储区域 | ap-shanghai（必须填写） |
| 路径样式访问 | 关闭 |
| 公开访问域名 | https://cos.ap-shanghai.myqcloud.com |
| URL 拼接方式 | 带桶名（原生域名多桶共根；默认 CDN 加速域名同理） |
密钥为腾讯云子账号的 SecretId / SecretKey。
实例四：Cloudflare R2（桶级自定义域）
| 参数 | 值 |
|---|---|
| 服务端点 | https://<账户ID>.r2.cloudflarestorage.com（S3 兼容端点，账户 ID 在 R2 控制台概览页查看） |
| 存储区域 | auto |
| 路径样式访问 | 开启 |
| 公开访问域名 | https://cdn.example.com（在 R2 控制台绑定到桶的自定义域） |
| URL 拼接方式 | 桶级域名（缺省），R2 自定义域直接指向桶，URL 不含桶名 |
密钥为 R2 的 AccessKey / SecretKey（对象存储 → 管理 API 令牌创建）。注意「桶级域名」正是为 R2 这类形态准备的：自定义域绑定在桶上，地址直接是 域名/对象键；不要选「带桶名」，否则地址多出桶段必然 404。若暂时没有自定义域，R2 也提供 https://pub-<哈希>.r2.dev 形式的公开访问域（需在桶设置中启用），同样按桶级域名填。
S3 兼容说明
各家对象存储都有自己的原生接口，但 S3 协议是事实标准，主流厂商都提供兼容层。系统统一用 S3 协议对接所有存储，配置时要分清两个用途不同的地址：
- API 端点（服务端点）：系统向它发起 S3 请求（测试连接、生成上传地址）。多数厂商的原生地址本身就是 S3 兼容端点，直接填。
- 文件访问域名（公开访问域名）：浏览器直接访问文件用的地址，与 API 端点无关，填厂商的原生域名或绑定的 CDN 域名。
阿里云 OSS 为什么要用 s3. 前缀端点
阿里云 OSS 是个例外：早期它靠原生地址「顺带」兼容 S3 协议，两边行为差异带来不少问题，例如新版 AWS SDK 上传时默认启用的校验与分块传输方式，OSS 的兼容层不支持，直接报错。阿里云后来上线了专门的 S3 兼容端点（https://s3.oss-<地域>.aliyuncs.com），官方文档目前推荐一律使用它，并把不带前缀的原生地址列为配置错误的典型例子。
两点实践中的坑已经内置处理，正常情况下不需要关心：
- 上述「SDK 默认校验与分块传输」已在上传链路中禁用，不会再触发 OSS 报错；
- 签名区域留空时按默认值参与签名，若「测试连接」报
SignatureDoesNotMatch（签名不匹配），在「存储区域」填入地域代码（如cn-beijing）即可。
服务端点换成 s3. 前缀地址后，公开访问域名仍然填原生地址（如 https://oss-cn-beijing.aliyuncs.com）。前者是给系统发请求用的，后者是给浏览器访问文件用的，两者本就是不同的东西。
对比：腾讯云 COS 的地址（cos.ap-xxx.myqcloud.com）本身就是 S3 兼容端点，直接填即可，没有单独的前缀形式。
测试与排错
保存配置后点「测试连接」，系统会对两个桶各执行「桶存在 → 写入探测文件 → 读取 → 删除」的完整闭环，通过即说明读写权限就绪。测试用的是表单当前值（未保存的修改也即时参与探测），不必先保存。
常见报错对照：
| 现象 | 原因 | 处理 |
|---|---|---|
| 测试通过，上传文件失败 | 存储桶未配置 CORS 跨域规则 | 配置方法与排查见 FAQ - 存储跨域配置与上传排查 |
| 写入失败，请检查密钥是否具备上传权限 | 密钥缺少写权限 / 桶策略拒绝写入 / 桶开启了 KMS 加密但密钥无 KMS 权限 | 后端日志搜「探测写入失败」看真实状态码；给密钥临时挂完全权限二分定位 |
| 文件已上传但图片显示不出来 | 「URL 拼接方式」与域名形态不匹配（桶级域名选了带桶名 / 多桶共根域名选了桶级），或公开桶权限为私有 | 按域名形态切换拼接方式（测试连接会自动纠偏提示）；公开桶权限设为公共读 |
| 公开文件访问 302 后 404 | 公开访问域名缺 http(s):// 协议前缀，跳转被浏览器当作相对路径解析 | 域名补全协议前缀（配置页已强制校验，存量配置注意排查） |
| 上传成功但文件记录一直处理中 | 密钥能写不能读 | 补充读权限（GetObject） |
测试连接报 SignatureDoesNotMatch | 签名时使用的区域与存储要求的区域不一致 | 「存储区域」填地域代码，如 cn-beijing |
WARNING
「系统文件列表里有一条记录」不代表上传成功：记录在申请上传地址时就会创建，文件真正可访问才算完成。