> 本文整理自平台文档 docs/wujies/5.x/plugins/gallery.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-c8fcd745501b-cover.svg)
应用编码 gallery,本页对应应用版本 1.0.6(引擎要求 >=5.6.2 <6.0.0),许可 MIT,仓库 [wujies-gallery-plugin](https://gitee.com/wujies/wujies-gallery-plugin)。
图床管的是「文件存到哪、图片这条记录怎么归类、谁能看」。文件的实际存储归平台的对象存储(sys_oss + 存储配置),图床只在自己的表里存一条指向 oss_id 的记录,再套上分类、标签、相册、访问日志四层组织关系。装完图床不会自动获得可用的存储,那是平台侧要先配好的事,见 [存储配置](/docs/wujies/5.x/platform/settings/storage)。
装它
没有应用级依赖,任何部署都能直接装。装之前确认这两件事:
1. 平台侧至少有一个启用的存储配置,否则上传接口会报存储相关错误而不是空列表。 2. 前台那三屏(/site/gallery、/site/gallery/square、/site/gallery/image/{id})由 cms 的主题直出。没装 cms 时后台页面与接口全部可用,前台路径取不到。
安装过程与「装完菜单为什么没立刻出现」见 [在部署里使用应用](/docs/wujies/5.x/platform/app-market/using-apps)。装成功后侧栏多一个「图床管理」,下面六项:
| 菜单 | 路由 | 需要的权限码 |
|---|---|---|
| 图床配置 | gallerySettings | gallery:settings:list |
| 分类管理 | imageCategory | gallery:category:list |
| 标签管理 | tag | gallery:tag:list |
| 图片管理 | image | gallery:image:list |
| 相册管理 | album | gallery:album:list |
| 图片访问日志 | imageAccessLog | picturebed:imageAccessLog:list |
最后一项的权限码前缀是 picturebed:,与其余五项的 gallery: 不一致,那是图床还是宿主内置模块时留下的历史串,菜单与后端注解都按这个值发,改它会同时对不上老授权。
配它
「图床配置」页两个页签,写的是 sys_config 里 config_category = 'gallery' 的那批行,页面保存即生效。前台游客上传与限额判断读的是同一批键。
| 键 | 默认值 | 什么时候要改 |
|---|---|---|
gallery.name / gallery.nameEn / gallery.description | 无界图床 / Wujie Image Hosting / 无界图床系统 | 前台标题与分享文案,换成自己的品牌 |
gallery.copyright / gallery.icp | 见种子脚本 | 对外服务必须填自己主体的备案号 |
gallery.logo / gallery.favicon / gallery.backgroundImage | 空 | 存的是 OSS 行 id。从别处导库带过来的值指向的是那台机器的文件,换部署后是死引用,要在本页重新上传 |
gallery.uploadEnabled | true | 关掉后前台与会员端都不能上传,后台管理不受影响 |
gallery.reviewBeforePublish | false | 决定新图是否先进待审核。默认不审核,公开站建议开 |
gallery.maxUploadSizeMb | 20 | 单文件上限。它只能比平台存储配置与网关的 body 上限更严,放宽不会让你突破那两层 |
gallery.dailyUploadCountLimit | 50 | 每人每天几张 |
gallery.dailyUploadSizeLimitMb | 200 | 每人每天多少容量 |
后两项按「人 + 自然日」累计,超限的报错来自应用自己的校验,与对象存储的配额是两套。
用它
管理员在「图床管理 → 图片管理」里批量上传、改相册、导出清单;「图片访问日志」记录每次前台取图,可按条件导出或清空。
相册列表点「查看详情」跳的 /gallery/imageAlbum/detail/:id 不是菜单项,而图床前端清单(plugins/wujies-gallery-plugin/frontend/src/index.ts)刻意不声明 routes —— 声明了会被远程应用加载器注册成没有 Layout 的裸顶级路由。所以这条路径由宿主 wujies-admin/src/router/index.ts 里的一条隐藏常量路由承接(createRemoteViewComponent('gallery/imageAlbumDetail', 'gallery') + meta.activeMenu)。回退或重做远程路由时漏掉这条,点详情就是 404。
会员在会员中心用两屏:「我的图片」(/member/gallery)管自己上传的图,「我的相册」(/member/albums)管相册并可新建。接口一律走 /portal/gallery/**,只回本人的数据。
新建相册走 POST /portal/gallery/album,请求体只认 albumName(必填、≤50 字)、description(≤200 字)、isPublic(Y/N,其余值按 Y):albumId、封面、编码、统计这类字段传了也不生效 —— 会员没有 gallery:imageAlbum:add,这条接口不查权限码,归属由服务端写死成当前登录用户,所以后台那条 POST /gallery/imageAlbum 在会员中心用不了。
一张图的归置走两条会员接口,各自只写自己那几列,不存在「不传就当没改」的含糊:PUT /portal/gallery/image/organize(albumId,其中 0 是未归相册;categoryId 不传即清空;tags 是标签 id 逗号串,空串即清空,最多 10 个)与 PUT /portal/gallery/image/public(isPublic 只认 Y/N)。三条边界都在服务层:相册必须是本人建的且启用中,分类与标签必须在启用清单里,非法值当场报错而不是静默丢掉;相册的图片数与总大小、分类的图片数、标签的使用次数按后台那套同一口径连带增减。状态(启用/停用)不在会员的可写面里,那是后台管理的口径 —— 一张被后台停用的图不会因为会员点了「转为公开」就回到广场上。
会员端选择框里的分类与标签取自匿名开放接口 /open/gallery/category/list、/open/gallery/tag/list:会员没有 gallery:imageCategory:list / gallery:imageTag:list,走后台那两个 /gallery/** 列表接口会直接 403。
游客能看广场与单图详情,也能匿名上传(/open/gallery/image/guest/upload)。匿名上传受 gallery.uploadEnabled 控制,落库归属仍是游客身份,所以「关上传」这一刀要在那个页签里切,删菜单挡不住接口。
原图下载(GET /site/gallery/image/{id}/file)绕本站一道再回传,前台那条链接写成 download 指对象存储直链是无效的:跨域响应上浏览器不认 download 属性(安全限制),点了只会就地打开或者存成一串没有后缀的名字。要「点了就存盘」,得由拿得到原图地址的这一侧在这份响应上补 Content-Disposition。
这一条只写计数不写图:download_count 与访问日志跟开放接口 POST /open/gallery/image/download/{id} 共用同一对动作(Redis 累加后批量回写、日志进消息队列),图本身一个字节都不入库。计数发生在取到图之后,取图失败还往上加次数,等于把一个坏链接刷成有人下载过。
转发出去的那个地址取自库里那条记录,访客传不上来,所以这里没有 SSRF 入口;把本站当管道仍有两道闸,都要在写出第一个字节之前判掉(响应头一发出去就改不了状态码):只放行 image/*,其余出 415,挡住有人把 sys_oss.url 指到内网接口、把这条变成读内网的窗口;长度未知或者超过上限出 413,挡住一次点击拖出一条几百 MB 的长连接。
出问题查什么
| 现象 | 先看 |
|---|---|
| 上传报存储错误、列表里图片没有可访问地址 | 平台「存储配置」里有没有启用的配置、该配置的桶是否公开读 |
前台 /site/gallery 打不开 | 是否装了 cms;没装则这几屏本就不存在 |
| 改了配置前台不变 | 前台读的是 /open/gallery/config,浏览器有缓存;确认 sys_config 里那行的值真的写进去了 |
| 会员上传被拒但没提示原因 | 查那三个限额键与 gallery.uploadEnabled,再看该会员当天的累计 |
| 装完侧栏没有「图床管理」 | 菜单树在登录时生 |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-c8fcd745501b-guide.svg)


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