主题安全与部署约束
校对日期:2026-11-04。适用于社区版及全部商业版。 本文面向运维人员和管理员,介绍主题安装的安全要求及多节点部署时的操作限制。
一、主题包信任边界(必读)
安装主题意味着在服务器上执行该主题的模板代码。
FreeMarker 模板在渲染时可以访问站点数据模型(站点、栏目、文章、用户上下文等)。系统已内置 以下两项保护措施,使用时需了解各自的作用范围:
- 模板沙箱:禁止
?new等反射类内建指令,限制模板访问 Java 运行时。模板仍可读取和展示 已向其开放的数据。 - 敏感字段访问限制(
TemplateMemberAccessPolicy):禁止模板读取密钥和密码哈希值,包括 存储、短信、邮件服务的密钥和密码(config.sms.*、config.email.*、config.及其加密字段原始值)、 AI 服务商的接口密钥、用户当前和历史密码的哈希值,以及个人信息盲索引。尝试读取时会直接报错,不会仅返回空值。 使用*Storage.* ${config}、${user}等方式输出整个对象时,也不会输出其字段。这项限制独立于模板沙箱, 对恶意模板同样有效。
仍可访问的个人信息: 模板可以读取用户的手机号和邮箱(user.mobile / user.email), 以便在会员“账号设置”页显示当前会员的信息。模板访问机制无法区分所读取的信息属于当前会员还是其他用户。 因此,主题也可能通过 article. 等关联对象访问并公开输出文章作者的手机号或邮箱。 系统将主题代码视为可信代码,主题作者和管理员需负责控制这些数据的使用范围。具体要求如下:
theme:install(上传安装/更新主题)、marketplace:(从应用市场安装/更新)、install theme:sandbox(沙箱试装——会在沙箱子站点上运行该主题包)与webFileTemplate:*(模板文件管理)权限只应授予 与服务器代码维护人员同等可信的管理员。 这几类权限具有代码执行能力,应按相应级别管理。- 只安装来源可信的主题包。 官方应用市场(
market.,见应用市场) 分发的包在下载后按市场签发的下载授权做 SHA-256 比对,不一致即拒绝安装;上传安装的 ZIP 则完全依赖管理员对 来源的判断。系统目前不校验主题包的数字签名或证书:市场现阶段只分发官方主题,待通过市场分发第三方包时再引入签名 校验。ujcms. com - 通过独立的可信渠道核对 SHA-256。 安装或更新完成后,控制台会显示所安装 ZIP 的 SHA-256 摘要: 上传安装时显示在通知窗口中,从市场安装时显示在安装报告中,更新时显示在更新报告中;后台日志也会同步记录。 请将其与发布方通过可信渠道公布的摘要进行人工比对。不一致时,主题包可能已被替换或损坏,应立即卸载并排查来源。
- 主题中的 JSON 文件(清单、组件定义、种子数据)在安装时会进行结构校验。通过校验只能说明格式符合要求, 无法保证内容可信。导入种子数据会向数据库写入栏目、文章、区块和区域等内容,也应先确认主题包来源可信。
二、多节点部署约束:主题操作单写者
模板存储可以被多个应用节点共享(远端对象存储 ujcms.,或共享磁盘挂载), 但主题管理操作必须固定在一个节点执行,即采用“单写者”方式。此要求适用于安装、更新、激活、卸载、 跨站点复制主题实例(包括沙箱试装)、从目录登记主题、导出演示数据,以及演示数据的导入、更新未修改项、 还原和移除。上述操作均通过按站点设置的进程内锁(ThemeLifecycleLock)控制:
- 生命周期互斥锁(
ThemeLifecycleLock)仅在单个进程内生效,能防止同一节点上的安装操作与文件监听触发的重新扫描 相互干扰,但无法保护两个节点同时操作同一主题目录的情况。 - 主题安装或更新后,各节点需要分别重新扫描主题注册表,通常由本地文件监听器触发。远端 对象存储没有文件监听;共享挂载的监听延迟不确定。即便文件操作本身不冲突,其他节点也会继续 使用旧的主题注册表,包括组件定义、页面清单和设置结构,直到各节点完成重新扫描或重启。
操作规程:
- 多节点部署时,上述主题管理操作(含沙箱站点的创建和清理)只在一个节点上执行。可指定一台“运维节点”, 或临时将控制台请求全部转发到同一个节点。
- 操作完成后,重启其余节点(或确认其文件监听已完成重扫——本地共享挂载下观察日志中的 registry reload 记录)后,再恢复正常流量。
- 模板文件的控制台在线编辑(模板文件管理器)同理属于单写者操作;日常编辑建议固定在同一节点 进行。模板编辑历史记录在数据库中,全节点共享,不受此限。
分布式互斥和跨节点注册表重新加载。仅增加分布式锁不足以解决注册表更新问题。
三、主题文件的对外访问范围
模板存储点和主题包存储点默认都在程序的静态文件目录里(/themes、/theme-packages)。程序对这两个路径做了限制, 访客用浏览器只能取到页面真正要用的文件,取不到主题的源文件:
| 路径 | 能否直接访问 |
|---|---|
/themes/、thumbnails/…,旧主题的 _files/… | 可以:样式、脚本、字体、图片,组件缩略图 |
主题目录下其它位置的图片(png jpg jpeg gif webp avif svg ico bmp) | 可以:主题封面、截图 |
主题目录下的其它文件:templates/、layout/、snippets/ 里的模板,theme.,pages/、shapes/、seed/,package.json、_src/ 等 | 不可以,返回 404 |
/themes/error/ 等存储路径下不属于任何主题的内容 | 不可以,返回 404 |
/theme-packages/…(主题安装包) | 不可以,返回 404 |
模板由程序读取后渲染,后台的模板管理、主题安装与导出走后台接口,都不受这项限制影响。
旧主题把样式、脚本放在别的目录时(既不在 assets/ 也不在 _files/,例如 static/),升级后这些文件会返回 404, 页面表现为样式丢失。把目录名加进配置文件后重启即可:
# 主题目录下允许直接访问的目录,逗号分隔;默认 assets,thumbnails,_files
ujcms.theme-public-dirs: assets,thumbnails,_files,static不要把 templates、layout、snippets 这类存放模板的目录加进去。新做的主题请按 主题开发把静态资源统一放在 assets/。
这项限制只对经过程序的请求有效。 下面几种部署方式下,文件由别的服务直接发送,需要在那一侧做同样的限制:
- Nginx 的
root指向程序的静态文件目录:按 Nginx 反向代理的“由 Nginx 直接发送静态文件”一节的写法,把/themes/、/theme-packages/交回程序处理。 - 存储路径用
file:前缀放在程序目录之外,由 Nginx 或 Tomcat 虚拟目录提供访问:只对外提供各主题的assets/、thumbnails/和图片;主题包目录不需要对外提供。 - 模板放在对象存储上(集群部署的
ujcms.): 存储桶里的模板文件能否被访客读取由存储桶的访问策略决定。程序是用普通的 HTTP 请求(不带访问密钥)从template-loader-url template-loader-url读取模板的,所以不能简单地把模板设为私有。可行的做法是让template-loader-url使用内网地址,并用存储桶策略把模板等文件的读取限制在应用节点所在的内网,对公网只开放各主题的assets/、thumbnails/和图片;具体写法以所用对象存储的文档为准。
在后台修改了这两个存储点的存储路径后,限制随新的路径生效,不需要另外配置。