更新与恢复

简体中文 | English

更新 Center

从 v0.1.1 升级到 v0.1.2

先升级 Center，再更新 Agent。升级前停止 Center，将 ./data/config 和 ./data/history 作为一组一致备份，并保留节点的 /var/lib/ipchronicle-agent。 Center 自动执行新增迁移，保留账户、节点身份、代理、计划和历史；Agent 本地状态 schema 仍为 9。

新版 Compose 增加 ./data/logs:/var/lib/ipchronicle/logs。自定义 Compose 也应 补上这个挂载，避免重建容器丢失日志。Cloudflare Tunnel 部署继续使用对应文件， 保留现有 .env 中的 token。

配置库迁移后，不能直接换回旧 Center 镜像。需要降级时，停止 Center，恢复升级前 配套备份后再运行旧版本；升级后产生的新数据不在旧备份中。

更新命令

更新前查看目标版本的 Release 说明。普通部署重新下载 compose.yaml：

curl --proto '=https' --tlsv1.2 -fL \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/compose.yaml" \
  -o compose.yaml
docker compose pull
docker compose up -d

Cloudflare Tunnel 部署使用对应文件：

curl --proto '=https' --tlsv1.2 -fL \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/compose.cloudflare-tunnel.yaml" \
  -o compose.yaml
docker compose pull
docker compose up -d

同时查看最新的 default.env.example，把新增的必要变量加入现有 .env。

当前数据边界

v0.1.1 已于 2026-09-04 投入正式使用，是首个持久数据兼容基线。现有 v0.1.1 部署的 ./data/config、./data/history 和各节点 /var/lib/ipchronicle-agent 必须在 后续同一主版本的受支持升级中保留。

v0.1.1 不迁移开发版、候选版或 v0.1.0 的配置库、历史库和 Agent 本地状态。 从这些版本首次部署 v0.1.1 时使用空的 Center 数据目录，并先通过安装器 --uninstall --purge 清理旧 Agent 状态后重新注册。

Center 会在开始服务前执行目标版本包含的数据库迁移。涉及持久格式的 Release 会 说明升级和回滚要求；回滚时使用与目标版本匹配的数据备份。

更新 Agent

在 设置 > 系统 选择 stable 或 RC 版本发现渠道。该设置只控制版本发现，不会 自动更新 Center。

在节点页面勾选存在可用版本的在线节点，可以批量请求更新。结果逐节点显示。 Agent 在原子替换前校验平台、版本、能力、清单、大小和校验和。 新 Agent 无法启动或回报健康时，root supervisor 会恢复旧二进制和状态检查点。更新与完整探测共享节点唯一的即时任务槽。

重装后恢复同一节点

重装前在节点设置中复制专属恢复安装命令，重装后以 root 执行。它会保留同一 节点及其 Center 配置和历史，并立即撤销旧 Agent 凭据。恢复密钥长期有效，可在 节点设置中轮换；持有这条命令的人可以接管节点，应按凭据保管。

旧系统盘上尚未上传的数据需要单独保存 Agent 状态，Center 无法恢复这部分数据。

备份边界

IPChronicle 当前没有内置备份或恢复命令。复制 SQLite 数据库前停止 Center，或 使用理解 SQLite WAL 的快照机制。

需要保留 Center 数据时，把以下目录作为一组一致备份：

• ./data/config：账户、节点身份、代理和通知秘密、计划、历史代次以及 master.key；
• ./data/history：地址事件、探测运行、快照和历史缺口。

需要在主机恢复后保留 Agent 身份和离线队列时，同时备份各节点的 /var/lib/ipchronicle-agent。

清除历史

设置 > 历史与存储 > 清除观察历史会删除地址事件、探测运行、执行、快照和 历史缺口，同时保留账户、节点、公网 IP 设置、隐藏路径、代理、计划、通知配置和 待处理任务状态。操作会推进历史代次，使 Agent 丢弃旧代次的排队数据；清除后不会 自动执行完整探测。