安装向导与无人值守安装
校对日期:2026-11-06。适用于社区版及全部商业版(多站点需商业版标准版,演示审核流程需商业版基础版)。
全新部署使用空数据库。首次启动后,系统按以下流程完成初始化并进入安装阶段:
- 初始化核心数据:创建系统配置、组织、管理员初始记录、站点 1 的初始记录,以及系统模型和字典。 安装状态变为
CORE_READY,系统生成一次性安装令牌,输出到启动日志并写入令牌文件。 - 选择安装方式:可根据部署场景选择以下任一方式。
- 控制台安装向导:浏览器打开
/cp/,按步骤完成(需要安装令牌,见启动日志或令牌文件); - 无人值守清单:配置
ujcms.install.*后,系统会在启动时自动完成安装(适合开发、演示和 Docker 环境); - Docker:通过环境变量提供安装配置,执行
docker compose up后即可创建可访问的演示站,见 Docker 部署。
- 控制台安装向导:浏览器打开
安装完成后安装状态变为 INSTALLED,全部安装接口(/api/install/**)自动关闭,安装令牌作废。
中断后继续安装:如果安装中途失败或程序退出,状态会保持为 CORE_READY。启动日志中的 InstallReport 会逐项说明执行结果和失败原因。使用清单安装时,下次启动会自动重试; 使用安装向导时,重新进入向导即可继续。各步骤支持重复执行,不会重复创建数据。
一、控制台安装向导
启动后端,获取安装令牌(由 32 位随机字符组成)。令牌有两个来源,内容相同:
- 启动日志:前后有醒目的分隔线;
- 令牌文件
WEB-INF/:看不到日志时(Tomcat WAR 部署、Windows 服务、 日志重定向到文件等)在服务器上打开该文件即可。JAR 方式位于程序静态资源目录下的install-token. txt WEB-INF(与lucene、backup同级),WAR 方式位于应用目录下的WEB-INF;向导第一步会显示 该文件的完整路径。文件仅服务器本地可读,不会通过网页访问到,安装完成后自动删除。
重启会重新生成令牌,日志与文件同步更新——以最后一次为准。也可通过
ujcms.预设令牌(此时日志不打印明文,也不写令牌文件)。install. token 浏览器打开
/cp/,未安装时自动进入安装向导。按步骤填写:
- 安装令牌;
- 站点设置:站点名称、协议、域名和端口(根据当前访问地址预先填写,可修改;端口留空时使用默认 端口 80 或 443);
- 管理员:用户名与密码(SM2 加密传输,与登录时使用相同的加密方式);
- 主题与数据:
- 主题来源可选择以下四种方式之一:内置默认主题(推荐)/主题包库(选择库内已有包)/ 应用市场(填条目标识,如
corporate或corporate@1.2.0)/上传主题包 (ZIP 先登记入主题包库再安装,包内清单须声明themeName); - 演示数据:导入演示数据(完整演示站)或空站点(跳过演示数据,高级选项)。 向导只能向前,没有“上一步”:每一步提交即保存,表单上方会回显已保存的站点与管理员信息 (密码不回显)。填错了不必重来,安装完成后在控制台的站点设置、用户管理中修改即可。
- 主题来源可选择以下四种方式之一:内置默认主题(推荐)/主题包库(选择库内已有包)/ 应用市场(填条目标识,如
完成后点击“进入登录”。
二、无人值守清单(ujcms.install.*)
无人值守安装通过配置清单自动完成安装,无需在页面中逐项操作。以下为 YAML 示例, 可写入对应运行环境的配置文件,或写入挂载的配置文件:
ujcms:
install:
auto: true # 空库首启自动安装;已安装则为空操作
# token: ${UJCMS_INSTALL_TOKEN:} # 可选:预设安装令牌(仅交互向导需要)
# library-dir: /ujcms/theme-packages # 可选:启动时把该目录下 *.zip 摄取入主题包库
admin:
username: admin
password: ${UJCMS_ADMIN_PASSWORD} # 建议环境变量/secret 注入,勿写明文
must-change-password: false
sites:
- name: "UJCMS 演示站" # 第 1 条:配置站点 1(不新建)
protocol: http
domain: demo.ujcms.com
# port 留空 = 清除端口(80/443)
theme: { source: bundled, seed: all }
- name: "English Site" # 第 2 条起:新建站点(商业版标准版起;社区版会明确报错)
sub-dir: en # 子目录寻址:demo.ujcms.com/en/(域名留空即继承主站点域名)
lang: en # 语言变体:lang 与 lang-of 必须成对出现
lang-of: "UJCMS 演示站" # 挂入该站点的语言组(按站点名引用,须为站点 1 或更早条目)
theme: { source: library, ref: corporate-en@1.2.0, seed: all }
users: # 可选:追加用户(各版本可用)
- username: demo
password: ${UJCMS_DEMO_PASSWORD}
read-only-demo: true # 演示站只读账号(固定 ID 10,见下文说明)
roles: ["管理角色"]
demo: # 可选:演示工作流层(商业版基础版起;社区版自动跳过)
workflow: true
review-states: true
register: # 可选:会员注册开关(缺省保持关闭)
enabled: true
oauth: # 可选:第三方登录凭据(商业版标准版起;社区版、基础版自动跳过)
weixin: # 服务商:weixin / qq / weibo,给出凭据的即启用
client-id: ${UJCMS_OAUTH_WEIXIN_CLIENT_ID}
client-secret: ${UJCMS_OAUTH_WEIXIN_CLIENT_SECRET} # 建议环境变量/secret 注入,勿写明文
ai: # 可选:AI 服务商(商业版标准版起;社区版、基础版自动跳过)
provider: # 一个 OpenAI 兼容协议的服务商,安装后即默认服务商
name: DeepSeek # 可省略,缺省取模型名
base-url: https://api.deepseek.com/v1
api-key: ${UJCMS_AI_API_KEY} # 建议环境变量/secret 注入,勿写明文;内网部署可留空
model: deepseek-chat
# extra-params: '{"enable_thinking": false}' # 可选:请求附加参数(JSON 对象)
mt: # 可选:机器翻译引擎,安装后即翻译服务商
baidu: # 百度翻译开放平台
app-id: ${UJCMS_BAIDU_TRANSLATE_APP_ID}
secret: ${UJCMS_BAIDU_TRANSLATE_SECRET} # 建议环境变量/secret 注入,勿写明文要点:
未填写的字段使用默认值。省略整个
sites时,系统会按默认配置安装站点 1:保留站点名称和 网络设置,使用站点当前主题(内置默认主题),并导入全部演示数据。开发环境的最简配置如下:yamlujcms.install.auto: true ujcms.install.admin.username: admin ujcms.install.admin.password: password主题来源(
theme.source):来源 ref写法说明 bundled可省略 内置默认主题包(构建期打包、引导时入库) library名称或名称@版本主题包库中已有的主题包(含从 library-dir导入的包);找不到时会提示错误marketplace条目标识或条目标识@版本从应用市场下载,通过 SHA-256 校验后存入主题包库;库中已有时无需重复下载,也可离线安装 seed:all导入主题全部演示数据;none创建不含演示数据的站点。多站点:第 2 条起的站点必须有
name(同名站点已存在则视为已建,续装跳过); 需要商业版标准版及以上,社区版启动会在报告中明确报错(站点 1 的安装不受影响)。子目录(
sub-dir,任意条目可用):通过子目录访问站点(如demo.)。 单域名模式下,同域名的第二个站点只能通过子目录区分;保留字 (uploads/themes/WEB-INF/cp/api/frontend/m)会明确报错。ujcms. com/ en/ 语言变体(
lang+lang-of,商业版标准版起):将该站点加入已有站点的语言组。lang为 BCP-47 语言标签(如en、zh-TW),lang-of按站点名引用组主站点 (站点 1 或清单中更早的条目;引用后面的条目会明确报错)。两者必须成对出现。 变体域名留空即继承主站点域名(推荐采用同一域名加子目录的方式,如demo.)。 语言变体导入同一主题的演示数据后,栏目别名自动对齐,前台语言切换与 hreflang 标记即生效; 首条(站点 1)可单独设ujcms. com/ en/ lang(缺省zh-CN),不可设lang-of。 同名站点已存在时,继续安装时会将清单中声明的语言关联设置应用到该站点(修正清单后重启即可补齐)。 演示数据里的文章也会自动关联译文:语言组内两个站点上来源相同的演示文章(同一主题的同一篇, 或两个主题中作者标为同一篇的文章)在安装时互相关联为译文,安装报告中对应langLinks[站点名]: linked=… already=…一行。安装后新写的文章仍需在控制台关联。追加用户(
users:,各版本可用):按用户名识别已有用户;同名用户已存在时自动跳过,不会覆盖其数据。 每条可设置username/password(必填)、roles(角色名列表,按站点 1 的角色解析, 名称不存在会明确报错;全新安装时系统预置的角色为“管理角色”)、rank/org-id/group-id(缺省 0 / 1 总部 / 8 管理组)。read-only-demo: true:演示站只读账号。以固定 ID 10 创建;配合顶层配置ujcms.时,后台对该账号强制只读(仅允许 GET 请求,任何数据操作返回 403)。适合公开演示环境:给它“管理角色”即可浏览全部控制台界面(含审核任务), 但无法修改数据。demo: true
演示审核流程(
demo:,商业版基础版起;社区版启动时自动跳过并在报告中说明, 安装照常完成):workflow: true:把预制的两级审核流程(文章审核article-review/ 表单审核form-review)部署到站点 1,并绑定演示栏目“新闻 › 国内”和演示表单类型的审核流程。 流程在控制台“流程模型”中可见、可再编辑;根据流程标识判断是否已部署,重启不会重复部署。review-states: true(需同时开workflow):调用系统服务生成可实际操作的演示审核数据——三篇 待审核文章(真实审核任务,控制台“文章审核”可认领处理)、一篇已退回 (含退回原因)、一篇审核中(已过初审、停在终审)。根据标题识别已生成的数据,重启不会重复生成。 默认主题演示数据在“新闻 › 国内”下自带的两篇草稿也会送入流程:百米决赛的赛前预告提交为 待审核,百米决赛的赛后侧记提交后退回并附退回原因。社区版没有审核流程,这两篇保持草稿。
注册开关(
register.,各版本可用):写入“全局设置 › 注册设置”的“是否启用”;不填则保持 全新安装的默认值(关闭)。enabled 第三方登录(
oauth:,商业版标准版起;社区版、基础版启动时自动跳过并在报告中说明, 安装照常完成):把微信(weixin)、QQ(qq)、微博(weibo)的应用凭据写入“全局设置 › 第三方登录” 并启用,登录、注册页面随即显示对应入口。每个服务商的client-id与client-secret必须同时填写 (只填一个会明确报错);没有填写的服务商保持原样。回调地址无需配置:系统按默认站点的协议和域名 生成({站点地址}/,可在“第三方登录”设置页查看),请在各开放平台登记同一地址。 通过第三方登录首次进入的访客需要注册用户名,因此应同时设置oauth/ code/ {服务商} register.,否则会停在 404 页面。 凭据加密保存在数据库中,安装完成后在控制台修改即可,清单不会再次覆盖。enabled: true AI 服务商(
ai.provider,商业版标准版起;社区版、基础版启动时自动跳过并在报告中说明, 安装照常完成):把一个 OpenAI 兼容协议的大模型服务商写入“全局设置 › AI服务商”,设为默认服务商并打开 “是否开启”。各站点的 AI 功能开关默认开启,因此安装完成后智能SEO、写作助手、AI 审核、AI 预翻译等即可使用。base-url(接口地址,不含/chat/)与completions model必须同时填写(只填一个会明确报错);api-key在 Ollama、vLLM 等内网部署时可以留空;name省略时取模型名;extra-params为请求附加参数 (JSON 对象,格式不对会明确报错),使用推理模型时用它关闭深度思考,各服务商的写法见 AI 功能的“配置 AI 服务商”一节。清单只配置这一个大模型服务商:更多服务商、写作与审核的 服务商分工和每日 token 上限在控制台设置。密钥加密保存在数据库中,安装完成后在控制台修改即可, 清单不会再次覆盖。公开站点请留意:开启后访客提交的评论、留言会按站点的审核模式调用模型,建议安装后在 “AI服务商”页设置全局每日 token 上限。机器翻译引擎(
ai.mt.baidu,级别与跳过规则同 AI 服务商):把百度翻译开放平台的app-id与secret写入“全局设置 › AI服务商”的机器翻译引擎凭证,设为翻译服务商并打开“是否开启”——AI 预翻译、批量新增译文 默认使用百度翻译而不调用大模型;写作、审核等其余功能仍使用默认服务商。两项必须同时填写(只填一个会 明确报错)。可以单独配置,不要求同时给出ai.provider。清单目前只支持百度翻译,有道翻译、DeepL 在控制台配置; 安装完成后想改回大模型翻译,在该设置页把“翻译服务商”改为留空或其他服务商即可。失败与重试:任一步失败则不完成安装,系统会将
InstallReport写入启动日志,逐项说明原因, 下次启动自动重试;修正配置后重启即可。
三、常见问题
- 令牌在哪里? 启动日志里(
docker logs <容器>),或服务器上的WEB-INF/(向导第一步显示完整路径)。重启会重新生成,以最后一次为准。install-token. txt - 忘记导入演示数据,或选错了主题? 控制台“设计 → 主题”可随时安装/切换主题、导入或 移除演示数据;安装向导只是首次配置的快捷通道。
- 安装中途失败,如何继续? 查看启动日志中的
InstallReport,找到失败的步骤并修正问题。 使用清单安装时重启应用,使用安装向导时重新进入向导;已完成的步骤会自动跳过。 - 社区版能装多站点吗? 不能。多站点需要商业版标准版;清单中第 2 条起的站点会 提示明确的错误,不会直接忽略。