> 本文整理自平台文档 docs/wujies/5.x/platform/settings/storage.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-49501aa5c612-cover.svg)
存储配置维护平台的文件存储服务,数据保存在 sys_oss_config。上传头像、应用截图、应用安装包、插件前端产物都依赖它。
> 全新部署默认没有启用任何存储。不配置也能登录后台,但上传会失败。这是刻意设计,避免把演示环境的密钥带进交付物。
src="/images/docs/settings-storage.png" caption="系统配置 · 存储配置" />
配置项
| 字段 | 说明 |
|---|---|
| 配置 key | 服务商标识,如 minio、aliyun、qcloud、qiniu,也用作本地存储的访问路径段 |
| 存储方式 | oss 对象存储(默认)/ local 本地磁盘,见下节;这一列在 sys_oss_config.storage_type |
| 访问站点 | 对象存储填服务端点,例如 oss-cn-hangzhou.aliyuncs.com;本地存储填这台部署对外可达的地址 |
| 自定义域名 | 对外访问域名,可与访问站点不同(仅对象存储) |
| accessKey | 访问密钥 ID(仅对象存储必填) |
| secretKey | 访问密钥 Secret,加密存储(仅对象存储必填) |
| 桶名称 | 对象存储填 Bucket;本地存储填落盘目录,两列复用同一份数据 |
| 前缀 | 对象键前缀,用于隔离环境或租户 |
| 是否 HTTPS | 生成 URL 时使用 https:// 或 http:// |
| 桶权限类型 | private / public / custom;本地存储只能是 public |
| 区域 | 服务商 Region(仅对象存储) |
| 备注 | 运维备注 |
本地存储
不需要对象存储也能把文件存在这台机器上:新增(或修改)一条配置,存储方式选「本地存储」, 把「桶名称」填成落盘目录、「访问站点」填这台部署对外可达的地址,保存后到列表里启用这一行。
| 字段 | 本地存储下是什么 |
|---|---|
| 桶名称 | 落盘目录。相对路径按进程启动目录(user.dir)解析,容器里要填容器内路径,例如 /app/data/upload |
| 访问站点 | 文件地址的前缀。带协议就原样用,不带就按「是否 HTTPS」补 http:// 或 https:// |
| accessKey / secretKey / 自定义域名 / 区域 | 用不到,页面上不显示,也不会被写进库 |
文件地址形如 https://<访问站点>/resource/local/<配置 key>/2026/11/06/<uuid>.png,由 SysLocalFileController 每次现读配置后直出字节 —— 刻意不做成静态资源映射,否则改目录必须重启。
> [!WARNING] > 本地存储的三个硬限制: > > 1. 只能公开读。落库的地址是不带签名的直链,所以「桶权限类型」选 private 会在保存时被拒绝;需要私有请用对象存储 + 120 秒预签名。 > 2. 读取端点免登录,与公开桶同一件事。落盘目录里不要放不该公开的文件。 > 3. 切换方式不搬旧文件。只对之后的新上传生效,历史行仍指向原来的桶或目录。
存量库要先加这一列再升级,否则启动时加载 OSS 配置会报 Unknown column 'storage_type':
mysql -h<主机> -P<端口> -u<用户> -p <库名> < script/sql/update/oss_storage_type.sql
脚本幂等,跑第二次只报「已存在」;存量行默认成 oss,行为与升级前一致。
启用流程
1. 在云厂商或 MinIO 创建 Bucket; 2. 创建最小权限的 AccessKey(只允许该 Bucket 的读写); 3. 在「存储配置」新增一条配置,填写端点、密钥、桶名; 4. 在列表中启用该配置(同一时间只有一个启用项); 5. 到「文件管理」上传一个测试文件,确认可访问。
常见服务商
| 服务商 | 配置 key | 端点示例 | Region |
|---|---|---|---|
| MinIO | minio | minio.example.com | us-east-1 |
| 阿里云 OSS | aliyun | oss-cn-hangzhou.aliyuncs.com | oss-cn-hangzhou |
| 腾讯云 COS | qcloud | cos.ap-guangzhou.myqcloud.com | ap-guangzhou |
| 七牛云 | qiniu | s3-cn-east-1.qiniucs.com | cn-east-1 |
具体驱动以 wujies-common-oss 中已注册的实现为准;不在列表中的服务商需要自行扩展。
私有桶与预览
private:对象默认不可匿名访问,后端生成带签名的临时 URL。public:对象可直接通过 URL 访问,适合头像、商品图等公开资源。custom:由自定义域名 / CDN 控制访问策略。
安全配置中的「OSS 预览列表资源」只控制文件管理页是否展示预览,不改变桶的访问权限。
多租户
sys_oss_config 带租户维度。不同租户可以使用不同的桶或前缀;上传时按当前租户选择启用配置。
应用包与前端产物
应用市场部署时会把安装包与前端目录落到宿主本地磁盘(plugin-dir / frontend-dir),不经过 OSS。OSS 只负责上架时的安装包存储与页面图片。
安全
secretKey加密存储,列表不返回明文;查看明文需要system:ossConfig:secretQuery。- 使用最小权限密钥,不要用主账号 AccessKey。
- 私有桶不要为了方便改成公开;需要公开的资源单独放公共桶或 CDN。
- 定期轮换密钥,轮换后同步更新配置并重新上传验证。
排错
| 现象 | 原因 | 处理 |
|---|---|---|
| 上传报「未配置存储」 | 没有启用的配置 | 在列表中启用一条 |
AccessDenied | 密钥权限不足 / 桶策略拒绝 | 检查 RAM 策略与桶 ACL |
| 上传成功但图片 404 | 自定义域名未解析 / 桶私有 | 检查域名与访问策略 |
The specified bucket does not exist | 桶名或 Region 错误 | 核对服务商控制台 |
| HTTPS 证书错误 | 自定义域名未配证书 | 使用服务商域名或补证书 |
| 保存本地存储报「桶权限只能选 public」 | 本地这一路是公开直链 | 保持 public,需要私有改用对象存储 |
| 本地存储上传成功但图片 404 | 落盘目录不可写 / 访问站点不是浏览器可达的地址 / 旧文件在别的存储上 | 看日志里的「本地文件读取被拒绝」,核对目录权限与访问站点 |
启动报 Unknown column 'storage_type' | 存量库没跑升级脚本 | script/sql/update/oss_storage_type.sql |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-49501aa5c612-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。