集群部署
校对日期:2026-11-16。适用于社区版及全部商业版;Redis 缓存、Elasticsearch 全文检索需要商业版高级版,对象存储、FTP 存储点、后台定时任务需要商业版标准版。单机部署不需要本页的配置。
本指南面向运维人员和系统管理员,介绍 UJCMS 多节点集群部署的配置方法和运维注意事项, 包括统一节点密钥、分配雪花算法节点编号、配置 Redis 分布式缓存和 Elasticsearch 全文检索、 共享文件存储、设置会话保持,以及启用 Quartz 集群调度。
一、使用前须知
- 基本架构:集群至少需要一个负载均衡器(如 Nginx)、两个应用节点、一个共享数据库, 以及所有节点均可访问的文件存储(共享挂载或对象存储)。数据库、Redis 和 Elasticsearch 自身的高可用配置不在本指南范围内。
- 配置文件位置:本文中的应用配置项均写入
application.。JAR 部署使用yaml config/或 JAR 包内的application. yaml BOOT-INF/;WAR 部署使用classes/ application. yaml WEB-INF/。 配置项名称后的冒号须使用英文半角冒号,冒号后须保留一个半角空格。classes/ application. yaml - 时钟同步:系统使用雪花算法生成主键,主键中包含时间戳。请为所有节点配置 NTP 时间同步,避免时钟回拨。
- 存储规划:附件、静态页、模板和主题包四个存储点切换至共享存储或对象存储时, 需要同时迁移已有文件。建议在上线前完成配置和迁移,避免在系统运行期间切换。
二、单机部署与集群部署的差异
| 配置内容 | 单机默认配置 | 集群部署要求 | 适用版本 |
|---|---|---|---|
| 签名与加密密钥 | 启动时随机生成 | 各节点必须配置相同的固定值(“统一各节点的密钥”一节) | 全部 |
| 主键生成 | 根据网卡、主机名和进程 ID 自动推算节点编号 | 为每个节点配置唯一的 ujcms. 与 ujcms.workerId 组合(“雪花算法节点编号”一节) | 全部 |
| 缓存 | 节点内存缓存(Caffeine) | 切换为 Redis;否则,数据变更在其他节点生效最多需要 10 分钟,登录失败等限流计数也会按节点分别累计(“Redis 分布式缓存”一节) | 高级版 |
| 全文检索 | 节点本地的 Lucene 索引文件 | 切换为 Elasticsearch,否则各节点的索引不一致(“Elasticsearch 全文检索”一节) | 高级版 |
| 附件、静态页、模板、主题包 | 应用目录下的本地文件夹 | 使用共享挂载或对象存储(“文件存储:共享目录与对象存储”一节) | 对象存储、FTP 需标准版 |
| 后台登录 | 无状态 JWT 认证 | 无需额外配置,确保各节点密钥一致即可 | 全部 |
| 前台会员登录 | 服务器端会话 | 在负载均衡器上开启会话保持(“会话保持与登录”一节) | 全部 |
| 定时任务 | Quartz 内存调度 | 切换为数据库调度并开启集群模式,否则每个节点都会执行相同任务(“定时任务与后台作业”一节) | 后台定时任务功能需标准版 |
| 页面构成缓存 | 本地缓存 | 通过数据库中的缓存版本标记自动同步,无需额外配置(“页面构成缓存的跨节点同步”一节) | 全部 |
| 主题安装、模板在线编辑 | 在本机执行 | 固定在同一个节点执行(“主题操作与模板编辑:固定在同一节点执行”一节) | 全部 |
三、统一各节点的密钥
单机环境下,以下密钥可以留空,系统会在启动时自动生成随机值。集群环境下,各节点独立生成的密钥不同, 可能导致用户在 A 节点登录后,请求转发至 B 节点时校验失败。因此,以下各项均须配置固定值,且同一配置项在所有节点上的值必须完全一致:
| 配置项 | 要求 | 用途 |
|---|---|---|
jwt.secret | 不少于 64 个字符的随机字符串 | 后台登录令牌签名;双因子登录的两个步骤由不同节点处理时,也需要使用同一密钥 |
captcha.secret | 32 个字符的随机字符串 | 验证码校验 |
ujcms. | 32 个字符的随机字符串 | 附件下载认证 |
ujcms. / ujcms. | 一对 SM2 密钥,QD 值采用十六进制(HEX)编码 | 登录密码传输加密 |
ujcms. | 长度必须为 16 个字符 | 短信、邮件、对象存储等凭据写入数据库前的加密 |
ujcms. | 通常不少于 32 个字符 | 用户密码哈希计算 |
随机字符串可使用大小写字母、数字和特殊字符。SM2 公钥和私钥须按上表要求成对生成。 后台右上角账号菜单中的 “密钥生成器” 可一次生成上表全部密钥,复制后粘贴到配置文件即可,无需手工拼凑。
配置示例如下,请将占位文本替换为符合要求的实际值:
jwt.secret: 请替换为不少于64个字符的随机字符串
captcha.secret: 请替换为32个字符的随机字符串
ujcms.download-secret: 请替换为32个字符的随机字符串
ujcms.client-sm2-public-key: 请替换为SM2公钥
ujcms.client-sm2-private-key: 请替换为SM2私钥
ujcms.data-secret-key: 请替换为16个字符的随机字符串
ujcms.password-pepper: 请替换为不少于32个字符的随机字符串注意事项:
- 修改
ujcms.后,已加密的历史数据将无法解密,需要在后台的短信、邮件及存储点设置中重新录入凭据。 用户手机号、邮箱的盲索引也需要重建,方法见用户个人信息盲索引重建。data-secret-key - 修改
ujcms.后,所有用户的原密码将失效,需要手动重置。password-pepper - 从已有单机环境扩展为集群时,请在新节点上沿用原节点的密钥,不要重新生成。
四、雪花算法节点编号
系统使用雪花算法生成主键,主键由时间戳、数据中心 ID、工作节点 ID 和序列号组成。 如果两个节点的数据中心 ID 和工作节点 ID 均相同,就可能在同一毫秒内生成重复主键,导致数据写入失败。
未配置节点编号时,系统会根据网卡 MAC 地址、主机名和进程 ID 自动推算。在容器或 Kubernetes 环境中, 各节点可能使用相同的 MAC 地址(如 Calico 的固定地址 ee:ee:)和进程 ID(如均为 1)。 此时仅依靠主机名区分,仍存在编号重复的风险。因此,集群部署时应为每个节点明确指定编号:
# 两项须同时设置,取值范围均为 0~31,各节点的取值组合不能重复
ujcms.datacenterId: 0
ujcms.workerId: 1建议使用数据中心 ID 区分机房,使用工作节点 ID 区分同一机房内的节点。 例如,同一机房内的两个节点可分别配置为 datacenterId=0, workerId=1 和 datacenterId=0, workerId=2。
如需通过启动日志确认实际使用的编号,请将以下类的日志级别设置为 INFO(生产环境配置默认仅输出 ERROR 级别日志):
logging.level.com.ujcms.common.db.identifier.SnowflakeSequence: INFO配置生效后,启动日志中会出现 Snowflake node id configured: datacenterId=0, workerId=1。 如果日志中出现 auto-derived from MAC/,则说明系统仍在自动推算编号,手动配置未生效。
五、Redis 分布式缓存(商业版高级版)
5.1 为什么集群需要 Redis
系统缓存主要分为以下两类,默认均保存在各节点的内存中:
- 数据缓存:包括全局配置、站点、栏目、模型、用户组等数据的查询缓存,以及内容统计缓存。 数据修改后,系统会立即清除本机缓存;但在集群环境中,其他节点仍会使用旧缓存,直到缓存过期(10 分钟)。 例如,在 A 节点修改站点设置后,转发至 B 节点的请求仍可能读取到旧值。
- 限流计数:包括验证码错误次数、同一 IP 的登录失败次数和短信发送次数、验证码发送冷却时间、匿名互动次数,以及好友申请次数。 如果各节点分别计数,集群整体允许的尝试次数会随节点数量增加,登录失败锁定等限制将无法在整个集群内统一生效。
切换为 Redis 后,所有节点共享上述缓存,数据变更和限流计数可在整个集群内统一生效。
5.2 配置方法
在
application.的yaml spring.列表中,删除或注释掉autoconfigure. exclude RedisAutoConfiguration所在行。 默认配置如下:yamlspring.autoconfigure.exclude: - org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration - org.springframework.boot.autoconfigure.elasticsearch.ElasticsearchRestClientAutoConfiguration如果仅启用 Redis,暂不启用 Elasticsearch,修改后的配置如下:
yamlspring.autoconfigure.exclude: - org.springframework.boot.autoconfigure.elasticsearch.ElasticsearchRestClientAutoConfiguration将缓存类型设置为
redis,并填写连接信息:yaml# 缓存类型,默认为 caffeine(节点内存缓存) spring.cache.type: redis # Redis 连接 spring.data.redis.host: 192.168.0.10 spring.data.redis.port: 6379 spring.data.redis.password: 请替换为Redis密码 # 多个应用共用一个 Redis 时,请使用不同的数据库编号以免冲突。默认为 0 spring.data.redis.database: 0也可以通过 URL 指定主机、端口和密码:
yamlspring.data.redis.url: redis://:密码@192.168.0.10:6379如果使用哨兵模式或 Redis 集群模式,请参考以下配置。 直连、哨兵、集群三种连接方式只需选择一种,不要同时配置:
yaml# 哨兵模式 spring.data.redis.sentinel.master: mymaster spring.data.redis.sentinel.nodes: 192.168.0.11:26379,192.168.0.12:26379,192.168.0.13:26379 spring.data.redis.sentinel.password: 请替换为哨兵密码 # Redis 集群模式 spring.data.redis.cluster.nodes: 192.168.0.21:6379,192.168.0.22:6379,192.168.0.23:6379确认所有应用节点使用相同的 Redis 配置,然后依次重启各节点。
5.3 验证配置
- 登录后台并浏览几个页面,再在 Redis 中执行
KEYS globalSpringCache*,应能看到缓存键。 - 在一个节点修改站点名称,再直接访问另一个节点(绕过负载均衡),应能立即看到修改后的名称。
版本升级注意事项:缓存采用 Java 序列化方式存储。升级 UJCMS 时,请先清理 Redis 中的 UJCMS 缓存键,再启动新版本, 否则可能无法读取旧版本序列化的缓存对象。
5.4 页面构成缓存的跨节点同步
可视化构建器的投放解析缓存不使用 Redis。保存内容时,系统会在同一事务中递增数据库中的缓存版本标记; 各节点定期检查该标记,发现变化后清除本地缓存。该机制默认开启,不依赖 Redis,社区版也可使用:
# 跨节点缓存失效同步,默认开启;单节点部署可关闭
#ujcms.composition.cache-sync-enabled: true
# 轮询间隔,单位为毫秒,默认为 3000;后台编辑结果在其他节点最迟约 3 秒可见
#ujcms.composition.cache-sync-poll-millis: 3000
# 解析缓存写入后的过期时间,单位为秒,默认为 60;用于在同步未生效时自动清除旧缓存
#ujcms.composition.resolve-cache-ttl-seconds: 60六、Elasticsearch 全文检索(商业版高级版)
6.1 为什么集群需要 Elasticsearch
默认情况下,Lucene 全文索引保存在各节点的本地目录中(ujcms.)。集群部署时需要注意:
- 文章在哪个节点保存,就只会更新该节点的索引。因此,其他节点的搜索结果可能缺少新文章,或仍然包含已删除的文章。
- 多个节点不能同时使用共享挂载中的同一个索引目录:Lucene 会对索引目录加写锁,第二个节点启动时可能报锁定错误,或出现索引损坏。
如果暂不使用 Elasticsearch,各节点需保留独立的本地索引目录,并定期重建索引。 对于支持后台“定时任务”功能的版本(商业版标准版及以上),可配置周期性的“生成本站索引”任务, 同时保留 Quartz 内存调度模式(不启用“定时任务与后台作业”一节的集群调度),使各节点分别重建索引。 采用此方案时,新文章需要等到下一次索引重建后才能在其他节点搜索到;静态页更新等其他定时任务也会在各节点重复执行。
6.2 环境要求
- 服务端版本:Elasticsearch 8.x。系统使用的客户端版本为 8.18,建议服务端也使用 8.x 系列版本。
- 分析插件:需要安装以下两个插件,且插件版本必须与 Elasticsearch 服务端版本一致:
analysis-ik:用于 IK 中文分词,字段使用ik_max_word分词器。analysis-pinyin:用于拼音检索,索引设置中定义了pinyinAnalyzer。
未安装上述插件时,索引将创建失败,错误信息中会出现 Unknown tokenizer type [pinyin] 或 analyzer [ik_。
6.3 配置方法
在
application.的yaml spring.列表中,删除autoconfigure. exclude ElasticsearchRestClientAutoConfiguration所在行 (参见“配置方法”一节第 1 步)。如果同时启用 Redis,请一并删除RedisAutoConfiguration所在行。 删除这两项后,如果列表中没有其他排除项,可将spring.的值留空。autoconfigure. exclude: 开启 Elasticsearch 并配置连接:
yaml# 开启后,全文检索切换为 Elasticsearch,Lucene 相关配置不再使用。默认为 false spring.data.elasticsearch.repositories.enabled: true spring.elasticsearch.uris: http://192.168.0.30:9200 spring.elasticsearch.username: elastic spring.elasticsearch.password: 请替换为密码 # 索引名前缀,默认为 ujcms。索引名为 <前缀>-article;多个应用共用一个 Elasticsearch 时,请使用不同前缀 ujcms.es-prefix: ujcms多个 Elasticsearch 节点地址用英文逗号分隔,例如:
spring.。elasticsearch. uris: http: / / es1: 9200, http: / / es2: 9200 确认所有应用节点使用相同的 Elasticsearch 配置,然后依次重启各节点。
重启后进入后台 系统 → 生成管理 → 文章全文索引,点击 更新全部索引。 首次切换至 Elasticsearch 时,需要通过此操作创建索引并导入全部文章。 此后新增或修改文章时,系统会自动更新索引,无需再次手动生成。
切换至 Elasticsearch 无需修改模板和接口,前台搜索页可继续使用。
6.4 验证配置
- 执行
curl http:,应能看到索引及文档数量。/ / 192. 168. 0. 30: 9200/ _ cat/ indices/ ujcms-article - 在一个节点新增一篇文章,再访问另一个节点的前台搜索页,应能立即搜索到该文章。
- 如需排查问题,可开启查询日志:
logging.。level. org. springframework. data. elasticsearch. client. WIRE: DEBUG
七、文件存储:共享目录与对象存储
7.1 存储点说明
系统提供四个独立的存储点,可在后台 配置 → 全局设置 → 存储设置 中分别配置:
| 存储点 | 默认存储路径 | 存储内容 | 集群部署要求 |
|---|---|---|---|
| 附件存储点 | /uploads | 上传的图片、附件和视频 | 必须共享,否则通过 B 节点访问在 A 节点上传的文件时,会返回 404 错误 |
| 静态页存储点 | 应用根目录 | 开启静态化后生成的 HTML 页面 | 必须共享,或通过 Nginx 统一访问共享目录或对象存储 |
| 模板存储点 | /themes | 主题模板、样式和脚本 | 必须共享,并遵守“主题操作与模板编辑:固定在同一节点执行”一节中固定节点执行操作的要求 |
| 主题包存储点 | /theme-packages | ZIP 格式的主题包 | 建议共享,否则各节点显示的主题包库内容不一致 |
每个存储点支持三种存储类型:本地服务器、FTP 服务器(标准版)和对象存储(标准版)。 在社区版中,本地服务器的凭据字段仅可查看,不可修改。
7.2 方案一:共享挂载(NFS 等)
将共享目录挂载到各节点的相同路径(如 /data/ujcms),存储类型保持为“本地服务器”, 存储路径改为以 file: 开头的绝对路径。具体步骤如下:
在
application.中配置允许使用的路径前缀,多个前缀用英文逗号分隔。 如果未配置,后台保存时会提示“以 file: 开头的路径需要在配置文件(application.yaml)的 ujcms.storageFilePrefix 中列入白名单”:yaml yamlujcms.storageFilePrefix: file:/data/ujcms在 存储设置 中,将各存储点的存储路径改为白名单允许的路径。 例如,附件存储点使用
file:,访问路径保留为/ data/ ujcms/ uploads /uploads,也可改为包含静态资源域名的完整地址。配置文件访问方式,使浏览器能够访问这些文件。以下两种方式任选其一:
通过 Nginx 提供访问:配置
location /,模板目录的配置方式相同。uploads/ { alias / data/ ujcms/ uploads/; } 通过应用提供访问:在
application.中,将共享目录加入静态资源路径列表:yaml yamlspring.web.resources.static-locations: - classpath:/META-INF/resources/ - classpath:/resources/ - classpath:/static/ - classpath:/public/ - file:/data/ujcms/
模板存储点切换至共享目录后,还需将各节点的 FreeMarker 模板加载路径指向同一目录:
yaml# 路径末尾必须保留 / spring.freemarker.template-loader-path: file:/data/ujcms/themes/ujcms.仅在附件保存在应用目录下(默认为uploads-location /uploads)时生效,用于绕过 Tomcat 资源缓存。 附件存储路径改为file:路径后,无需修改此项。
注意:共享挂载的文件监听可能存在延迟,主题目录的变更不一定能被其他节点及时检测到。 模板修改后最迟约 5 秒生效;主题安装后,需要重启其他节点或确认其已完成重新扫描,详见“主题操作与模板编辑:固定在同一节点执行”一节。
7.3 方案二:对象存储(商业版标准版)
系统通过兼容 S3 的协议访问对象存储,支持 MinIO、阿里云 OSS、腾讯云 COS、七牛云 Kodo 和 AWS S3。 在 存储设置 中选择“对象存储”,并填写以下信息:
| 字段 | 说明 | 示例 |
|---|---|---|
| Endpoint(服务地址) | 对象存储服务的访问地址,须包含协议 | MinIO:http:;阿里云 OSS:https:;腾讯云 COS:https: |
| Region(区域) | 服务所在区域;MinIO 可填写 us-east-1 | cn-hangzhou、ap-beijing |
| Bucket(存储桶) | 存储桶名称 | ujcms |
| AccessKey / SecretKey(访问密钥) | 访问凭据以密文存储,再次打开设置页面时显示为空;留空表示不修改。改了 Endpoint 须重新填写:已保存的密钥只发往原地址 | |
| 存储路径 | 存储桶内的对象前缀 | /uploads |
| 访问路径 | 浏览器访问文件时使用的地址前缀,通常由存储桶的公网地址或 CDN 域名加上对象前缀组成 | https: |
保存配置后,新上传的文件会直接写入对象存储,文件访问地址以所配置的“访问路径”开头。 已有文件需要自行迁移至存储桶内对应的对象前缀下。
访问凭据在写入数据库前,会使用 ujcms. 加密(见“统一各节点的密钥”一节)。各节点的密钥保持一致后,即可在任意节点读取凭据。
各存储点使用对象存储时,还需注意以下事项:
附件存储点:存储桶需要允许匿名读取,或通过 CDN 提供访问。存储路径与访问路径的末尾部分应保持一致,例如均以
/uploads结尾。静态页存储点:生成的 HTML 页面写入存储桶,站点域名需通过 CDN 或 Nginx 访问该存储桶。 站点地图、
robots.txt等仍由应用动态生成,对应请求需转发至应用节点,配置规则见站点地图与搜索引擎提交的“静态化站点与反向代理”一节。模板存储点:模板写入存储桶后,各节点须改为从对象存储加载模板,否则页面渲染时会提示找不到模板:
yaml# 模板 URL 前缀须与模板存储点的访问路径一致,末尾保留 / ujcms.template-loader-url: https://ujcms.oss-cn-hangzhou.aliyuncs.com/themes/对象存储不支持文件监听,模板修改后最迟约 5 秒生效,具体取决于 FreeMarker 的模板更新延迟;新建模板也需等待一个更新周期。 主题安装或更新后,需要重启其他节点,详见“主题操作与模板编辑:固定在同一节点执行”一节。存储桶还需允许应用节点通过匿名读取或内网访问的方式读取模板文件。
主题包存储点:ZIP 文件按
<主题名>/<版本>.zip存放,只需允许应用节点读写,无需开放公网访问。
7.4 本地目录与节点依赖
除上述存储点外,集群部署时还需分别处理以下本地目录和运行环境:
- 备份目录(
/WEB-INF/backup):模板备份、上传备份、上传增量备份和数据库备份(见备份管理)默认保存在执行操作的节点上,查看和恢复也只能在同一节点进行; 系统 → 定时任务 中的定时备份同样写入执行该任务的节点,“保留份数”也只清理该节点的备份目录。 建议将备份操作固定在运维节点执行,或将该目录配置为共享挂载。 - Lucene 索引目录(
ujcms.):必须保留在各节点本地,不可共享(见“为什么集群需要 Elasticsearch”一节)。切换至 Elasticsearch 后,此目录不再使用。lucene-path - Office 文档转换(
jodconverter):DOC 导入的 .docx/.doc 由内置引擎处理,不需要 LibreOffice;素材库的 Office 转 PDF 与 .wps/.rtf/.odt 的导入需要。可以各节点都安装 LibreOffice(jodconverter.),也可以只运行一个local. enabled jodconverter/容器,各节点通过jodconverter-rest jodconverter.+remote. enabled jodconverter.连接它。remote. url
八、会话保持与登录
后台管理:后台接口使用无状态 JWT 认证,不依赖服务器端会话。只要“统一各节点的密钥”一节中的密钥保持一致,请求就可以由任意节点处理。
前台会员:前台登录状态、验证码和表单 CSRF 令牌保存在服务器端会话中,系统未启用会话共享。 请在负载均衡器上开启会话保持(Nginx 使用
ip_hash或基于 Cookie 的sticky),将同一访客的请求固定转发至同一节点。 用户勾选“记住我”后,登录令牌会保存在数据库中,切换节点后可自动恢复登录,但原会话中的其他状态不会保留。应用市场账号连接:授权流程中的临时数据保存在单个节点的内存中,因此也依赖会话保持。 连接建立后,凭据保存在数据库中,由所有节点共享。
双因子登录:两个步骤可以由不同节点处理,但各节点的
jwt.secret必须一致,否则会提示验证超时。真实 IP:应用前端部署负载均衡器后,登录失败次数限制、管理终端白名单和访问统计仍需获取访客的真实 IP。 请配置负载均衡器,使其写入
X-Forwarded-For请求头,并按代理层数设置以下配置项(仅有一层反向代理时为1,CDN 加一层反向代理时为2):yamlujcms.ip-proxy-depth: 1
Nginx 配置示例:
upstream ujcms {
ip_hash;
server 192.168.0.1:8080;
server 192.168.0.2:8080;
}
server {
listen 80;
server_name www.example.com;
location / {
proxy_pass http://ujcms;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}九、定时任务与后台作业
9.1 Quartz 集群调度
后台 系统 → 定时任务(标准版)中的任务,以及系统内置的访问统计汇总、微信日志清理等作业,均由 Quartz 调度。 默认采用内存调度模式,各节点启动时都会注册全部任务,因此同一任务会在每个节点各执行一次, 导致静态页重复生成、全文索引重复重建,定时备份则在每个节点各自生成一份备份文件(保存在各节点本地,见“本地目录与节点依赖”一节)。 采集任务通过数据库中的状态抢占机制避免重复执行,其他任务没有这一保护机制。
集群环境下,应切换为数据库调度并开启集群模式。系统在初始化数据库时已创建 Quartz 所需的数据表(表名以 qrtz_ 开头),无需手动建表:
# 集群环境需使用 jdbc,默认为 memory
spring.quartz.job-store-type: jdbc
# 开启 Quartz 集群
spring.quartz.properties.org.quartz.jobStore.isClustered: true
# 集群中各节点的实例 ID 须保持唯一,AUTO 表示自动生成
spring.quartz.properties.org.quartz.scheduler.instanceId: AUTO
# jdbc 模式需指定驱动委托类,请根据数据库类型选择其中一项
spring.quartz.properties.org.quartz.jobStore.driverDelegateClass: org.quartz.impl.jdbcjobstore.StdJDBCDelegate
#spring.quartz.properties.org.quartz.jobStore.driverDelegateClass: org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
#spring.quartz.properties.org.quartz.jobStore.driverDelegateClass: org.quartz.impl.jdbcjobstore.oracle.OracleDelegateMySQL、MariaDB、达梦等数据库使用 StdJDBCDelegate;PostgreSQL、人大金仓和 openGauss 使用 PostgreSQLDelegate。 以下两项请保留默认值,不要修改:
spring.quartz. overwrite-existing-jobs: true spring.quartz. jdbc. initialize-schema: never
完成配置后,同一任务在同一时刻只会由一个节点执行;节点发生故障时,其他节点会接管任务。 Quartz 集群要求各节点时钟保持同步,时钟偏差过大可能导致任务未触发或重复触发。
9.2 各节点独立执行的作业
以下作业按设计会在各节点独立运行,不受 Quartz 集群配置影响,无需额外调整:
- 将缓存中的浏览次数和访问日志写入数据库(在每分钟内的随机时刻执行,避免各节点同时写入)。
- 系统负载采样(高级版系统监控功能,各节点分别采集自身负载)。
- 轮询页面构成缓存的版本标记(见“页面构成缓存的跨节点同步”一节)。
十、主题操作与模板编辑:固定在同一节点执行
主题安装、更新、激活、卸载、演示数据导入,以及模板文件的在线编辑,都会直接修改模板存储点中的文件。 这些操作的互斥锁仅在单个进程内生效,无法阻止多个节点同时修改同一文件。 此外,其他节点需要重新扫描主题注册表,才能识别新主题。因此,集群部署时须采用“单写者”方式,将上述操作固定在同一节点执行:
- 指定一个“运维节点”执行上述操作,或在操作期间将所有后台请求临时转发至同一节点。
- 操作完成后,重启其余节点,或通过日志确认其已重新加载主题注册表。
- 日常模板在线编辑也应固定在同一节点进行。编辑历史保存在数据库中,由所有节点共享。
详细说明见主题安全与部署约束的“多节点部署约束:主题操作单写者”一节。
十一、其他功能的集群部署注意事项
- 敏感词、易错词:词库快照保存在各节点的内存中,不使用 Redis。修改后,在执行操作的节点上立即生效,在其他节点上最多延迟 5 分钟生效。
- 微信公众号(高级版):请在微信开发者平台的 IP 白名单中添加所有节点的公网出口 IP。各节点分别缓存
access_token,微信允许这些令牌同时有效。 - 网站普查、采集、AI 批量任务:任务由发起操作的节点执行,状态保存在数据库中,因此可在任意节点的后台查看进度。
- 日志文件:各节点分别记录本地日志。排查问题时,需要先确认请求由哪个节点处理,建议在负载均衡日志中记录后端节点地址。
- Docker / Kubernetes:镜像使用
/ujcms/static卷存储附件、模板和静态页。多副本部署时,请将该卷改为共享存储(如 NFS、CephFS),或改用对象存储。 同时,通过环境变量或挂载的application.设置“统一各节点的密钥”一节中的密钥和“雪花算法节点编号”一节中的节点编号。Docker 部署方式见 Docker 部署。yaml
十二、上线检查清单
上线前,请逐项确认以下内容:
- 各节点的
application.配置保持一致,仅yaml ujcms.与datacenterId ujcms.workerId的组合按节点分别设置,且各节点之间不重复。 - “统一各节点的密钥”一节中的密钥均已配置为固定值;如果由单机扩展为集群,已沿用原节点的密钥。
- 附件、模板、静态页和主题包存储点已切换至共享挂载或对象存储,已有文件已完成迁移。
- 已配置 Redis(高级版);如未配置,已确认可接受数据缓存最多 10 分钟不一致,以及限流按节点分别计数的影响。
- 已配置 Elasticsearch(高级版)并执行“更新全部索引”;如未配置,已按“为什么集群需要 Elasticsearch”一节安排各节点定期重建索引。
- Quartz 已切换为数据库集群调度;如保留内存调度模式,已确认可接受同一任务在各节点重复执行的影响。
- 负载均衡器已开启会话保持,并传递
X-Forwarded-For请求头;ujcms.已按代理层数设置。ip-proxy-depth - 所有节点均已配置 NTP 时间同步。
- 已指定执行主题安装和模板编辑的运维节点,并告知相关管理员。
十三、常见问题
| 问题现象 | 可能原因 | 处理方法 |
|---|---|---|
| 后台登录后,偶尔提示未登录或令牌无效 | 各节点的 jwt.secret 不一致 | 按“统一各节点的密钥”一节统一密钥配置,并重启所有节点 |
| 双因子登录提示验证超时 | 两个步骤由不同节点处理,且各节点的 jwt.secret 不一致 | 按“统一各节点的密钥”一节统一 jwt.secret,并重启所有节点 |
| 前台会员登录后,刷新页面又提示未登录;或提交表单时提示令牌失效 | 负载均衡器未开启会话保持 | 开启 ip_hash 或基于 Cookie 的会话保持 |
| 保存数据时报主键冲突(Duplicate entry) | 节点编号重复 | 按“雪花算法节点编号”一节为各节点配置唯一的 ujcms. 与 ujcms.workerId 组合 |
| 修改站点或栏目设置后,部分请求仍返回旧值 | 未使用 Redis,其他节点的缓存尚未过期 | 配置 Redis,或等待缓存过期(最多 10 分钟) |
| 修改敏感词或易错词后,其他节点仍使用旧词库 | 词库快照保存在各节点本地,最多 5 分钟后重建 | 等待最多 5 分钟,或重启其他节点 |
| 新文章在部分节点上搜索不到 | 未使用 Elasticsearch,各节点的 Lucene 索引相互独立 | 配置 Elasticsearch,或按“为什么集群需要 Elasticsearch”一节安排索引重建 |
| 节点启动时提示 Lucene 索引目录被锁定(Lock held by another program) | 多个节点共用了同一个 ujcms. 目录 | 改用各节点独立的本地目录,或切换至 Elasticsearch |
Elasticsearch 创建索引失败,提示 Unknown tokenizer type [pinyin] 或 ik_max_word 未配置 | 未安装 analysis-pinyin 或 analysis-ik 插件,或插件版本与服务端不一致 | 安装匹配版本的插件,重启 Elasticsearch 后再执行“更新全部索引” |
| 升级后读取 Redis 缓存时出现反序列化错误 | 新版本无法读取旧版本序列化的缓存对象 | 清理 Redis 中的 UJCMS 缓存键后重启应用 |
| 上传的图片在部分节点上返回 404 错误 | 附件仍保存在各节点的本地目录中 | 切换至共享挂载或对象存储,并迁移已有文件 |
| 保存存储路径时提示需要配置白名单 | file: 路径未加入白名单 | 在 ujcms. 中添加该路径前缀,并重启应用 |
| 使用对象存储保存模板后,前台提示找不到模板 | 未配置 ujcms. | 按“方案二:对象存储”一节完成配置,并重启所有节点 |
| 静态页重复生成,或定时任务重复执行 | Quartz 仍使用内存调度模式 | 按“Quartz 集群调度”一节切换为数据库集群调度 |
| 主题安装后,其他节点看不到新主题或组件 | 其他节点尚未重新加载主题注册表 | 重启其余节点 |
| 登录失败次数限制未在整个集群内生效 | 未使用 Redis,计数在各节点分别累计 | 配置 Redis |
| 登录日志和访问统计中的 IP 均为负载均衡器地址 | ujcms. 为 0 | 按代理层数设置为 1 或 2,并确认代理写入了 X-Forwarded-For 请求头 |