升级与回滚
升级会替换二进制文件；它不会把你迁移到另一个产品。数据目录、审计签名密钥和 TLS 材料会留在原处，引擎在启动时自行应用所有新架构迁移。本页是操作员完成整个过程的路径， 从“我应该采用这个版本吗？”直到“我需要恢复上一个版本”。
选择升级路径
Section titled “选择升级路径”二进制文件有四种升级方式，最终结果相同。
| 你的安装方式 | 路径 |
|---|---|
| deb、rpm、apk 或 AUR 软件包 | 包管理器。从软件包安装 |
| 主机上的二进制文件、systemd（非软件包安装） | olivares upgrade——本页 |
| Docker 或 Podman 容器 | 运行 docker compose exec olivares olivares upgrade，然后重新创建容器。镜像无法更改，因此该版本会保存在数据卷中（数据目录下的 ota/），镜像中的二进制文件每次启动时，只要该版本比镜像新或是同一版本的另一种构建，就会启动它。删除 ota/ 即可让容器回到其镜像中的二进制文件。命令见 Docker 与 Compose。 |
| Kubernetes / Helm | 设置镜像，让 operator 执行滚动更新。不要在 pod 内运行 olivares upgrade：部署是声明式的，下一次协调会撤销它。 |
首先阅读计划
Section titled “首先阅读计划”--check 会下载并验证渠道清单，将其与已安装版本比较，然后输出将要发生的操作。
它不会替换任何内容。
olivares upgrade --check输出包括已安装版本、可用版本，以及以下状态之一：up to date、
upgrade available、DOWNGRADE (blocked unless --force-rollback) 或 UNKNOWN。
请阅读状态行，不要自行比较两个版本号。
UNKNOWN 并不表示“应该没问题”。 它表示无法测量已安装版本——例如跨架构
暂存目录、noexec 挂载点或源码构建。防回滚保护和最低版本门槛都是针对
已安装版本作出的判断，因此两者都无法求值。命令会拒绝继续，不会猜测。声明你确定
已经安装的版本，所有保护仍会启用：
olivares upgrade --check --current-version 0.4olivares upgrade 跟随一个发布渠道。共有 3 个，按稳定性递增顺序声明在
core/release/manifest.go 中：
--channel 值 |
声明为 |
|---|---|
stable |
release.ChannelStable |
security |
release.ChannelSecurity |
lts |
release.ChannelLTS |
不在此表中的值会在下载任何内容前被拒绝（release.ValidChannel）。
stable 是正式发布渠道，也是默认值。security 只携带带外安全修复，不含其他内容；
跟随它的部署会采用安全版本，而不会采用功能版本。
选择符合运维方式的渠道，并持续使用它：
olivares upgrade --channel security安全版本会在清单中标记，--check 会输出它修复的安全公告。如果使用 security 渠道，
你会在正式发布线之外接收这些版本。
olivares upgrade在软件包安装（deb、rpm、apk、AUR）上，该命令会在下载任何内容之前以退出码 2 被拒绝：请按上表使用包管理器。
--check 仍会显示计划。
命令依次执行以下操作，每一步都有明确目的：
- 下载渠道清单并离线验证其签名，验证依据是构建中嵌入的 Ed25519 发布密钥。
信任锚是签名，不是传输。没有嵌入密钥的构建要求通过
--pubkey提供密钥；不存在 未验证路径。 - 拒绝后退。 安装比当前运行版本更旧的版本会被阻止，除非传入
--force-rollback；该操作会写入审计记录。 - 在执行任何字节前，将制品绑定到清单签名的 SHA-256。
- 探测候选文件，然后进行原子替换，并保留被替换二进制文件的带时间戳备份。 如果新安装的二进制文件无法运行，命令会自行恢复该备份。
- 不干扰正在运行的进程。 替换只改变磁盘上的文件。服务重启后，新代码才会接管。
如果脚本正在驱动升级且无人响应确认提示，请添加 --yes。
步骤 4 的自动回滚只测试 version，不测试服务启动或数据库兼容性。
它不会恢复在下次重启时已迁移的存储。
隔离网络安装
Section titled “隔离网络安装”隔离网络部署绝不会连接更新主机。使用你已经信任的方式移入发布包，再从本地文件安装； 验证过程完全相同，因为受信任的从来都不是网络。
离线安装需要 Enterprise。Community 使用 --bundle --check 验证包，不读取许可证，也不进行安装。
olivares upgrade --bundle ./olivares-release.tar.gz --check分阶段发布和无人值守检查
Section titled “分阶段发布和无人值守检查”清单可以指定分阶段发布群组，让版本先到达一部分基础设施。--if-eligible 使节点只在
属于该群组时执行操作，否则什么也不做：
olivares upgrade --if-eligible --yes内置计时器运行的就是这种形式。要生成在维护窗口内调用它的 systemd 计时器和服务：
olivares upgrade --install-timer --timer-schedule 'Sun *-*-* 03:00:00'它默认输出 unit；--timer-dir 会将它们写入指定位置。这是选择加入功能——不会自行安排。
在软件包安装上，该命令会拒绝：/usr/bin/olivares 归软件包管理器所有，因此它以退出码 2 结束，
不写入任何 unit，并指出升级途径：主机的软件包管理器；在 Olivares 设备上则是
systemctl start olivares-appliance-update.service。带 --enterprise --connect 时还会指出
olivares license connect refresh。检查按路径进行，因此由 install.sh --bindir /usr/bin 放在那里的
二进制文件同样会被拒绝。
控制台提供相同信息的只读部分：Settings → update status 调用
POST /v1/console/update-check，按需检查配置的渠道。隔离网络部署或未配置渠道的部署会
返回 501 并说明原因，而不会报告没有更新。
olivares versionolivares upgrade --check此时 --check 应报告 up to date。然后确认服务本身健康：查看控制台的 Health
屏幕（/health），或按照使用 Prometheus 监控
检查引擎的就绪端点。
上一个可执行文件会保存在新文件旁边，命令会输出其路径。这份副本不是数据的恢复点。
旧二进制文件会拒绝高于其支持上限的 core 架构版本，增量迁移也不例外。 重新安装旧二进制文件或镜像无法撤销架构版本提升。不要修改迁移历史或绕过该拒绝。
- 停止所有使用该存储的引擎，保留升级后的数据、服务配置、TLS 材料和外部封存密钥。
- 使用上一版本的二进制文件恢复升级前创建的 DR 发布包，遵循
备份与恢复。SQLite：恢复到新的数据目录，或使用
dr restore --in-place并指定--operator和--reason；确认恢复成功前保留自动保存的文件。 PostgreSQL：用olivares db init创建空目标，提供目标的--dsn、--owner-dsn、--admin-dsn， 并为恢复的签名密钥准备新的目录。 - 必须确认账本和审计密钥验证成功。启动上一版本前，将服务的数据目录、卷和 PostgreSQL DSN 指向恢复后的存储及对应的签名密钥。
- 登录并检查恢复的数据和服务健康状态。
恢复会回到保存时点。升级前备份之后的写入不会出现在恢复的存储中；保留升级后的存储以便核对。 没有发布包及其口令或 KEK，仅替换可执行文件无法完成这种恢复。
--force-rollback 允许安装旧可执行文件，并将覆盖操作记入审计日志。它不会绕过 core 架构检查
或最低版本门槛，也不会恢复数据。已安装版本低于门槛时，请先经过中间版本。
生产升级前测试恢复路径
Section titled “生产升级前测试恢复路径”使用临时 SQLite 数据目录启动经过验证的上一版本，完成设置和登录，然后停止它。
用该版本的 dr backup 和 dr verify 创建并验证发布包。让候选版本打开同一存储，登录后停止它。
如果架构版本超过旧版本上限，旧版本必须以 core schema version newer than this binary supports 失败。
用旧版本的 dr restore 恢复到新的目录。要求退出码为零且账本验证成功，再在那里启动旧版本，
检查登录、原审计公钥和保存的数据。恢复或登录失败就表示恢复测试失败。
SQLite 恢复实测（2026-10-08）：官方 26.10.1 创建了 core 架构 18，较新的候选版本将其提升至 27。
旧版本以退出码 1（database=27 binary=18）拒绝升级后的存储。旧版本的 dr backup、dr verify、
dr restore 均以退出码 0 完成。将升级前的发布包恢复到新目录后，原账户可以登录，原审计公钥保持一致。
| 症状 | 含义 | 处理方式 |
|---|---|---|
--check 输出 UNKNOWN |
无法测量已安装版本，因此无法判断版本顺序 | 通过 --current-version 传入你确定已安装的版本 |
min_ver 表示版本过旧 |
该版本拒绝直接覆盖你的版本安装 | 先升级到指定的中间版本 |
已安装的可执行文件未通过替换后的 version 探测 |
可执行文件检查失败 | 命令恢复保存的可执行文件；检查日志 |
| 重启后服务启动失败，或旧版本报告 core 架构过新 | 不在可执行文件探测范围内 | 停止服务，按照回滚流程恢复升级前的 DR 发布包 |
--install-timer 触发但没有操作 |
节点不在分阶段发布群组中 | 使用 --if-eligible 时属于预期行为；群组会随发布进展扩大 |
| “another olivares upgrade is already installing”，退出码 5 | 每个二进制文件一次只能进行一项升级。整个下载和替换过程都会持有锁 | 等待正在运行的升级，再重新执行。如果没有进程在运行，内核已经释放锁，立即重试即可 |
| “it CHANGED while this upgrade was downloading” | 制定计划后，有其他机制替换了二进制文件——包管理器、镜像发布或配置管理作业 | 重新运行：保护会根据实际安装内容重新求值。如果持续发生，则有两个机制在管理同一个二进制文件 |
每个二进制文件只能有一个升级进程。 olivares upgrade 在整个准备—下载—替换
过程中对目标加独占锁，因此第二次运行会以退出码 5 退出，而不会执行安装。请只安装
一个计时器并更改其中的 --channel，不要为每个渠道运行一个计时器：过去，两个在
同一秒完成的安装会覆盖彼此的回滚备份，失败一方的自动回滚随后会恢复另一个二进制
文件并报告成功。就在替换前，命令还会重新读取目标字节；如果它们不是计划所依据的
字节，命令就会拒绝继续，因为防回滚和最低版本判断是针对某个特定已安装文件的判断。
其他问题请使用通用故障排除路径；控制台的 Logs
屏幕（/logs）会流式显示引擎自己的日志。