主题
版本升级
每个平台部署页末尾都有该平台的升级命令，本页讲清楚所有平台共同遵守的原则、升级前检查和回滚。
原则
升级只替换可执行文件。 config.yaml 和整个 data/ 目录属于你方，一律保留。
| 绝不能覆盖的路径 | 内容 |
|---|---|
config.yaml | 密钥、端口、告警与在线文档配置 |
data/apexpm.db | 全部业务数据（SQLite） |
data/uploads/ | 上传的附件 |
data/documents/ | 在线文档（本地存储模式） |
data/license.lic | 授权文件 |
data/license_state.json | 宽限期起点与已发送的告警记录 |
新版本首次启动时会自动升级数据库结构，不需要手工执行 SQL。这一步不可逆，所以升级前必须备份。
升级前检查
- 读版本说明。 交付包里的
changelog/vX.Y.Z.md，尤其是「升级注意」一节——需要改配置、有不兼容变更时都写在这里。跨多个版本升级时，把中间每个版本的「升级注意」都看一遍。 - 确认平台一致。 新包的平台要和原来的一致（Linux 仍用
linux-amd64）。 - 安排停机窗口。 升级期间服务不可用，一般几分钟；数据量大时结构升级可能更久。安排在业务低峰期。
- 准备备份位置。 备份要放到另一块盘或另一台机器，见备份与恢复。
- 使用外部数据库时，同时用数据库自己的工具备份（
pg_dump、mysqldump），只备份data/不包含业务数据。
升级步骤
各平台命令不同，步骤一致：
- 停止服务
- 备份
data/（外部数据库同时做数据库备份） - 只替换可执行文件（Docker 还要替换
Dockerfile并重建镜像） - 启动服务，等待自动结构升级完成
- 验证
| 平台 | 命令 |
|---|---|
| Linux（systemd / start.sh） | Linux → 升级 |
| Linux（deploy.sh） | 在新交付包目录里执行 SERVER=... ./deploy.sh，自动备份 |
| Linux（Docker） | Docker → 升级 |
| Windows | Windows → 升级 |
| macOS | macOS → 升级 |
升级后验证
bash
curl -fsS http://127.0.0.1:9000/health
curl -fsS http://127.0.0.1:9000/api/v1/license/status/health 返回的 version 应为新版本号。然后登录系统，抽查几个常用页面，确认历史数据都在、附件能打开。
常见错误
| 现象 | 原因 | 处理 |
|---|---|---|
启动后立即退出，日志 migrations failed | 数据库结构升级失败 | 不要反复重启。保留完整日志联系我方；需要尽快恢复业务就按下文回滚 |
日志 automigrate failed | 同上 | 同上 |
升级后页面还是旧版本，或 /health 的 version 仍是旧版本号 | 浏览器缓存；Docker 没带 --build；替换到了别的目录 | 浏览器 Ctrl+F5 强制刷新；Docker 重新 up -d --build |
| 升级后部分功能提示需要新配置 | 新版本新增了配置项 | 对照新包里的 config.example.yaml 与版本说明，把新增项补进 config.yaml（不要整个覆盖） |
启动后提示 IP 未授权 或授权失效 | 升级时误覆盖了 data/license.lic，或换了服务器 | 从备份恢复 data/license.lic；换过服务器则联系我方重新签发 |
| 升级后数据全部不见 | 覆盖了 data/ 或 config.yaml（数据库配置丢失，回落到空的 SQLite） | 停服，从备份恢复 data/ 与 config.yaml |
回滚
只换回旧的可执行文件是不行的
新版本启动后数据库结构已经变了，旧程序面对不认识的结构，行为不可预期，可能损坏数据。交付的程序没有回退数据库结构的命令。
回滚 = 换回旧可执行文件 + 用升级前的备份覆盖 data/（外部数据库则用升级前的数据库备份恢复）。升级之后产生的数据会丢失。
以 Linux systemd 为例：
bash
cd /opt/apexpm
sudo systemctl stop apexpm
sudo mv data "data.failed-$(date +%Y%m%d-%H%M%S)" # 留存现场，便于排查
sudo cp -a data.bak-20260101-020000 data # 换成升级前的备份
sudo cp /path/to/old/apexpm apexpm && sudo chmod +x apexpm
sudo chown -R apexpm:apexpm data apexpm
sudo systemctl start apexpm其他平台同理：停服 → 旧 data/ 改名留存 → 恢复备份 → 放回旧可执行文件 → 启动。
所以升级前一定要保留旧版本的交付包，直到确认新版本稳定运行。
跨版本升级
可以从任意旧版本直接升到最新版本，不需要逐个版本升级：结构升级会按顺序依次执行所有中间版本的变更。但要注意：
- 中间每个版本的「升级注意」都要看；
- 跨度越大，结构升级耗时越长，停机窗口要留足。
更换服务器
授权与服务器 IP 绑定，换机前先把新服务器的 IP 告知我方重新签发授权。
- 新服务器按对应平台文档完成部署，但先不要启动
- 停止旧服务器上的服务
- 把旧服务器的整个
data/目录和config.yaml拷到新服务器部署目录 - 用新签发的授权文件覆盖
data/license.lic - 检查
config.yaml里和旧机器相关的地址（server.public_base_url、onlyoffice.public_base、数据库 DSN），改成新地址 - 启动并验证
跨平台迁移（如 Windows → Linux）同样适用：data/ 与 config.yaml 在各平台之间通用，只是可执行文件要换成对应平台的。