中国 帮助

存储配置

存储配置维护平台的文件存储服务,数据保存在 sys_oss_config。上传头像、应用截图、应用安装包、插件前端产物都依赖它。 全新部署默认没有启用任何存储。不配置也能登录后台,但上传会失败。这是刻意设计,避免把演示环境的密钥带进交付

存储配置
封面

> 本文整理自平台文档 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
MinIOminiominio.example.comus-east-1
阿里云 OSSaliyunoss-cn-hangzhou.aliyuncs.comoss-cn-hangzhou
腾讯云 COSqcloudcos.ap-guangzhou.myqcloud.comap-guangzhou
七牛云qinius3-cn-east-1.qiniucs.comcn-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)

章节导览
THE END

喜欢就支持以下吧

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

回到内容