备份与恢复
Zeno 的有效备份必须同时包含运行配置、SQLite 数据和文件型 secrets。只备份数据库、只复制镜像或只保存 .env 都不能保证可恢复。
最小备份范围
text
/opt/zeno/.zeno-installation
/opt/zeno/.env
/opt/zeno/docker-compose.yml
/opt/zeno/data/
/opt/zeno/secrets/.zeno-installation 是安装目录身份标记；恢复时不要把它复制到无关目录。
安装器自动备份
重复运行官方安装器升级时，会先做路径、磁盘和镜像预检，再短暂停止 Controller，创建完整离线备份：
text
/opt/zeno/backups/install-YYYYmmdd-HHMMSS-PID/备份带完成标记和 SHA-256 manifest，默认保留最近 5 份。安装器会检查备份数据库和当前数据库，启动后等待 /ready，失败时自动恢复旧镜像和完整快照。
自动备份不能替代异机备份；Controller 主机磁盘损坏时，同机备份会一起丢失。
手工离线备份
下面的示例会短暂停服，以获得 SQLite、通知 keyring 和配置一致的快照：
bash
sudo sh -eu -c '
cd /opt/zeno
docker compose stop zeno
trap "docker compose start zeno" EXIT
dst="/var/backups/zeno/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$dst"
cp -a -- .zeno-installation .env docker-compose.yml data secrets "$dst/"
(cd "$dst" && find . -type f -print0 | sort -z | xargs -0 sha256sum > MANIFEST.sha256)
'备份后验证：
bash
cd /var/backups/zeno/<backup-directory>
sha256sum -c MANIFEST.sha256
curl -fsS http://127.0.0.1:18980/ready再把完整目录复制到另一台受控主机或对象存储。异机副本需要加密、限制访问并保留恢复所需的权限信息。
恢复前检查
- 确认备份来自目标 Zeno 实例和正确时间点。
- 验证
MANIFEST.sha256。 - 确认
.env、Compose、data/和secrets/来自同一快照。 - 记录当前运行镜像和失败现场。
- 停止 Controller；禁止覆盖在线 SQLite。
- 准备独立回滚目录，避免恢复失败后无路可退。
恢复流程
- 停止 Controller。
- 把当前
/opt/zeno另存为失败现场。 - 恢复同一备份中的安装标记、
.env、Compose、data/和secrets/。 - 恢复权限：
bash
cd /opt/zeno
chown -R 10001:10001 data
find data -type d -exec chmod 700 {} +
find data -type f \( -name '*.db' -o -name '*.db-wal' -o -name '*.db-shm' -o -name '*-wal' -o -name '*-shm' \) -exec chmod 600 {} +
chown -R 0:10001 secrets
find secrets -type d -exec chmod 750 {} +
find secrets -type f -exec chmod 640 {} +- 使用备份记录的不可变镜像 reference 启动。
- 验证：
bash
curl -fsS http://127.0.0.1:18980/health
curl -fsS http://127.0.0.1:18980/ready
curl -fsS http://127.0.0.1:18980/api/public/v1/summary- 登录后台，核对服务器、设置、延迟目标、通知渠道和最近数据。
- 确认 Agent 恢复上报，通知凭据可解密且测试通知能送达。
不要拆分恢复
不要把一个时间点的数据库与另一个时间点的 secrets/、.env 或 Compose 混合。通知 keyring/authority 与数据库状态不一致时，可能导致凭据不可用或错误路由。
恢复验收
只有以下项目全部成立，恢复才算完成：
- manifest 通过；
- 文件属主和模式正确；
- 容器运行固定的目标镜像；
/health、/ready和 Public API 正常；- SQLite 可读，页面数据与快照时间相符；
- Agent 重新上报；
- Admin 登录和通知测试正常；
- 失败现场与恢复前副本仍保留，直到观察期结束。
升级专用流程和安装器自动回滚见 升级与回滚。