部署形态总览

本指南以 12.0.2 为准（发布日期 2026-10-26）。安装包名为 powercms-12.0.2-windows-x64.zip / powercms-12.0.2-linux-x64.tar.gz，包名版本取自 pom.xml；历史版本与下载入口见《版本发布记录》。

PowerCMS 12 提供原生可执行文件（免 JDK/JRE）与容器化两种交付方式，按规模与合规要求可选择以下部署形态：

形态	适用场景	组成
单机（内置库）	演示、试点、开发自测	应用 + 内置 H2 数据库 + 内存检索，零外部依赖，开箱即用
单机（外部库）	常规生产	应用 + PostgreSQL / MySQL + 可选 OpenSearch + Nginx 反代
容器 / 分布式	多实例、弹性伸缩	应用镜像 + 外部数据库 + OpenSearch 集群，通过 docker-compose 或编排平台组装
托管云服务	无运维团队、快速上线	由服务方托管应用与基础设施，用户通过管理端与 API 使用（见下文）

所有形态共享同一套管理端（/）、Headless API（/api/v1）与站点渲染服务，应用架构和操作方式完全一致，迁移成本低。

环境要求

项目	要求
操作系统	Windows：Windows 10 1803+ / Windows Server 2016+（x64）；Linux：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / RHEL 8+ / openEuler / 统信 UOS 等（x86_64 或 aarch64）
内存	≥ 4 GB（同时安装 OpenSearch 建议 ≥ 8 GB）
磁盘	≥ 5 GB（建议 ≥ 10 GB；安装 OpenSearch 建议 ≥ 20 GB）
端口	8080（应用）、80（Nginx，可选）、9200（OpenSearch，仅本机）
数据库	无需预装（默认内置 H2）；选择 PostgreSQL / MySQL 时需先就绪实例
运行账户	Windows 需管理员 PowerShell（注册开机自启计划任务）；Linux 需 root（创建系统用户与 systemd 单元）

私有化部署

3.1 安装包内容

安装包为自包含目录，主要结构如下（Windows 与 Linux 一致）：

powercms-12.0.2-windows-x64.zip     # Linux 为 powercms-12.0.2-linux-x64.tar.gz
├── install.ps1 / install.sh      一键安装（数据库可选，默认 H2）
├── uninstall.ps1 / uninstall.sh  卸载（默认保留数据，含服务化卸载）
├── bin/powercms(.exe)            原生可执行文件，免 JDK/JRE
├── ui/admin-ui/dist/             管理端静态资源（已整体内嵌进原生二进制）
├── config/
│   ├── nginx.conf                Nginx 反代配置模板
│   └── application.example.yml   外部配置参考模板
├── plugins/                      OpenSearch 中文分词插件（smartcn）
├── components/                   第三方组件离线安装包放置目录（含 WinSW-x64.exe）
└── docs/                         部署文档

3.2 Windows 服务化安装（12.0.1 起）

除默认的计划任务自启外，12.0.1 新增 -Service 参数，通过 WinSW 将应用注册为 Windows 服务，获得开机自启 + 崩溃自动拉起：

# 需管理员 PowerShell；一行完成服务化安装
.\install.ps1 -Db mysql -DbHost db01 -DbName powercms12 `
              -DbUser root -DbPassword '******' -Service

WinSW 包装器优先取 components\WinSW-x64.exe，缺失时联网下载（GitHub 直连慢会走镜像回退），并做体积校验 → 完全离线可安装；
注册成功后可在「服务」中看到 PowerCMS：Start-Service PowerCMS / Stop-Service PowerCMS；
卸载时执行 uninstall.ps1，脚本会先停服务再停进程（服务带崩溃自拉起，直接杀进程会被重启），随后删除服务；
去掉 -Service 则沿用旧的计划任务自启方式。

3.3 一键安装

解压安装包后，在包根目录执行安装脚本。交互模式会依次询问数据库与可选组件：

# Windows（管理员 PowerShell）
.\install.ps1

# Linux（root）
chmod +x install.sh uninstall.sh
./install.sh

3.4 无人值守安装与参数表

通过参数指定数据库与组件即可无人值守安装，常用示例：

# Windows：MySQL + OpenSearch + Git + Nginx
.\install.ps1 -Db mysql -DbHost db01 -DbName powercms12 `
              -DbUser root -DbPassword '******' `
              -Search opensearch -WithGit -WithNginx -OpenFirewall

# Linux 等价命令
./install.sh --db mysql --db-host db01 --db-name powercms12 \
             --db-user root --db-password '******' \
             --search opensearch --with-git --with-nginx --open-firewall

参数（Windows / Linux）	默认值	说明
`-InstallDir` / `--install-dir`	`C:\PowerCMS` / `/opt/powercms`	安装目录，数据与日志在其 `data/` 下
`-Db` / `--db`	`h2`	`h2` / `postgres` / `mysql`
`-DbHost/-DbPort/-DbName/-DbUser/-DbPassword` / `--db-*`	—	外部数据库连接信息
`-ServerPort` / `--server-port`	`8080`	应用端口
`-Search` / `--search`	`memory`	`memory`（内置检索）或 `opensearch`
`-WithGit / -WithNginx / -WithOpenSearch` / `--with-*`	未指定	跳过交互直接安装对应组件
`-Offline` / `--offline`	关	完全离线安装，组件仅从 `components/` 目录获取
`-NoStart` / `--no-start`	关	安装完成后不启动、不做健康检查
`-Service`（仅 Windows）	关	注册为 Windows 服务（WinSW，开机自启 + 崩溃自动拉起），需管理员

3.5 数据库选择

选项	说明
H2（默认）	零依赖，开箱即用；备份即拷贝 `data\` 目录。适合演示与小规模场景
PostgreSQL 14+	生产推荐；需先建库建用户
MySQL 8.0.19+	字符集需为 utf8mb4
金仓 KingbaseES / 达梦	数据库 profile（`db-kingbase`、`db-dameng`）已内置；需在源码侧启用 `-Pvendor-drivers` 重新构建原生二进制，详见安装包 `docs/native-image.md`

安装后改库：编辑 <安装目录>\config\application.yml（参考包内 application.example.yml），重启服务生效。也可用环境变量覆盖（如 POWERCMS_DB_PROFILE、POWERCMS_DB_HOST 等）。

3.6 可选组件

Git：模板仓库 / 发布分支版本化所需，安装脚本可自动安装（支持离线包）。
Nginx：站点反代与静态提速。默认将 80 端口反代到 127.0.0.1:8080，配置模板已含 client_max_body_size 4g、gzip 与关闭代理缓冲；以计划任务（Windows）或系统配置（Linux）自启，支持 nginx -s reload 热加载。
OpenSearch 3.8.0：可选全文检索后端。预置单节点、中文分词插件（smartcn，需与 OpenSearch 版本一致）、堆内存 512 MB；memory 模式下应用完全不依赖 OpenSearch。

安装脚本预置的 OpenSearch 关闭了安全插件，仅限内网使用；需要暴露时必须启用其 security 插件并配置 TLS，或以防火墙 + 反代限制 9200 端口访问。

3.7 安装后验证

# 状态与健康检查
powershell -File C:\PowerCMS\status.ps1        # Linux: systemctl status powercms
http://localhost:8080/actuator/health          # 返回 {"status":"UP"}
http://localhost:8080/swagger-ui.html          # API 文档
http://localhost:8080/                         # 管理端

日志位于 <安装目录>\data\logs\powercms.log。首次启动会自动执行数据库迁移（H2 约十余秒，PostgreSQL / MySQL 视数据规模而定）。

托管云服务

选择托管形态时，应用部署、版本升级、备份与基础设施监控由服务方负责，用户通过管理端与 API 使用平台，适合缺少专职运维团队或希望快速上线的组织。

环境隔离：每个站点默认提供 preview / staging / production 三套环境（对应 API 中的 PREVIEW / STAGING / PRODUCTION），内容创作、预览与正式发布互不干扰，与环境相关的域名可按站点绑定。
职责边界：服务方负责应用可用性、版本升级与基础数据备份；用户负责账号与权限管理、内容运营及自身集成代码。
数据可迁移：内容模型与内容可通过管理 API 导出，站点前台可通过公开 Delivery API 取数，后续如转为私有化部署，迁移路径清晰。

托管服务的方案配置与报价因规模而异，欢迎联系我们获取针对你所在行业的托管方案。

日常运维

5.1 服务管理

操作	Windows	Linux
启动 / 停止 / 状态	安装目录下 `start.bat` / `stop.bat` / `status.ps1`；服务化安装时用 `Start-Service PowerCMS` / `Stop-Service PowerCMS`	`systemctl start\|stop\|status powercms`
开机自启	Windows 服务 `PowerCMS`（`-Service` 安装，支持崩溃自动拉起）或计划任务 `PowerCMS`（管理员安装 = 系统启动时）	systemd 单元 `powercms.service`（`enable`）
OpenSearch	服务 `PowerCMS-OpenSearch` 或 `opensearch-service.bat`	systemd 单元 `powercms-opensearch`
Nginx	计划任务 `PowerCMS-Nginx`；`nginx -s reload`	`systemctl reload nginx`

5.2 监控与日志

健康检查：GET /actuator/health，返回 {"status":"UP"} 即正常，可接入现有监控平台的 HTTP 探针。
应用日志：<安装目录>\data\logs\powercms.log，后台控制台隐藏启动，一切以日志文件为准。
API 文档：/swagger-ui.html 可随时核对本环境开放的接口清单。

5.3 备份与恢复

H2（内置库）：停止服务后整体拷贝 data\ 目录即可；恢复 = 将目录放回原位后启动。
PostgreSQL / MySQL：按数据库常规方式做实例级备份（逻辑备份或快照），并同步备份 data\ 下的媒体等运行数据。
建议在业务低峰执行全量备份，并将备份文件保存到独立存储；重要变更（升级、改库）前先做一次手动备份。

升级与卸载

6.1 升级（12.0.0 → 12.0.1）

备份现有 data\（或数据库实例）与 config\application.yml；
停止服务（stop.bat / systemctl stop powercms；服务化安装的 Windows 先 Stop-Service PowerCMS）；
用 12.0.1 安装包覆盖 bin\powercms(.exe)（原生二进制已整体内嵌管理端 admin-ui\dist\）与 components\WinSW-x64.exe（需服务化时）；
需要服务化的环境重跑 .\install.ps1 -Service 注册 / 重建 Windows 服务；Linux 执行 install.sh；
启动服务，Flyway 自动执行 V138 → V158 共 20 个迁移（均为向前兼容的增量变更）。

升级过程不要删除 data\ 目录——内容、媒体索引与运行数据都在其中。

源码侧自行构建原生二进制时，务必先构建管理端前端（admin-ui/dist），否则 Maven 会跳过拷贝而不报错，导致打包出的二进制缺少管理端资源。

6.2 升级（12.0.1 → 12.0.2）

备份数据库（或 data\）与 config\ 目录；
停止服务（stop.bat / systemctl stop powercms；服务化安装的 Windows 先 Stop-Service PowerCMS）；
用 12.0.2 安装包覆盖 bin\powercms(.exe)（原生二进制已整体内嵌管理端 admin-ui\dist\，请使用本次分发包）与 components\WinSW-x64.exe（需服务化时）；
需要服务化的环境重跑 .\install.ps1 -Service 注册 / 重建 Windows 服务；Linux 执行 install.sh；
启动服务，Flyway 自动执行 V159 → V162 共 4 个迁移（均为向前兼容的增量变更）。
启用版本分层时，确认 powercms.license.enabled / enforce-edition-boundaries 配置（参考 config\application.example.yml），并在管理端「版本与授权」导入离线授权。

12.0.2 起版本分层能力位与配额门禁生产默认开启：能力位越界返回 403、配额超限 409、授权到期转为只读 402。若升级后出现上述状态码，先核对「版本与授权」页的授权状态与配额用量。

6.3 卸载

Windows 执行 .\uninstall.ps1（Linux 为 ./uninstall.sh），默认保留数据；加 -Purge 参数连数据一起删除。脚本会先停 Windows 服务 / 进程，再卸载 OpenSearch 服务、删除计划任务或 systemd 单元、清理防火墙规则并移除程序目录。

故障排查

现象	处理
端口被占用	更换 `-ServerPort` 重新安装，或排查占用进程（Windows：`Get-NetTCPConnection -LocalPort 8080 -State Listen`）
健康检查不过	查看 `data\logs\powercms.log`；多为数据库不可达、账号密码错误或库未创建
首次启动即退出	迁移失败或配置语法错误；确认 `config\application.yml` 为 UTF-8 且 YAML 缩进正确
管理端 404	`admin-ui\dist` 缺失（安装包未含 UI 构建产物），补入后重启
OpenSearch 起不来	查看对应服务状态与 `components\opensearch-*\logs\`；内存不足时下调堆大小
计划任务未生效	非管理员安装只能"登录时启动"；以管理员重装或手动修改任务触发器
防火墙拦截	重跑安装脚本带 `-OpenFirewall` / `--open-firewall`，或手工添加入站规则
服务化安装失败	未以管理员运行，或 WinSW 未获取成功：先以管理员重跑 `install.ps1 -Service`；仍失败可手动下载 `WinSW-x64.exe` 放入 `components\` 后重试，或去掉 `-Service` 改用计划任务自启
换库后起不来	核对 `config\application.yml` 的 profile 与连接串；可先切回 H2 验证应用本身正常

安全基线

首次登录管理端立即修改默认账号 admin 的密码；
替换 config\application.yml 中的数据库密码与 powercms.play-token 等默认密钥，支持通过环境变量注入；
OpenSearch 安全插件处于关闭状态，仅限内网使用；对外暴露必须启用 security 插件并配置 TLS，或以防火墙 + 反代限制 9200 端口；
生产环境在 Nginx 层启用 TLS（listen 443 ssl），应用端口 8080 仅绑定内网；
定期备份 data\（H2）或数据库实例（PostgreSQL / MySQL），并做恢复演练。

部署与运维指南