备份、恢复与升级

大约 7 分钟

备份、恢复与升级

1. 需要备份什么

对象	内容
平台 PostgreSQL	用户、会话、模型配置、审批、审计、用量、知识库、文档附件文字、工作区、托管数据库口令、API Token 和外部服务配置
backend-data	对话图片、导出文件，以及可能自动生成的密钥等
cli-config	数据库 Context 配置
.env、override 和相关密钥	密码、加密密钥、登录签名、指标令牌等
镜像和部署材料	同版本恢复所需镜像、模板、发布记录及反代配置

密钥加密单独保管，备份复制异地并定期恢复演练。backend-data 若含自动生成密钥，也属于敏感材料。

平台备份不包含 TimechoDB/IoTDB 的业务数据。 恢复平台也不会撤销已经执行的业务数据库写入，目标库由 DBA 独立备份。

2. 内置业务库的备份示例

验证范围：内置 PostgreSQL 的备份与恢复已在内部测试环境演练；外部 PostgreSQL 的备份命令和定时备份任务尚未验证。实际部署前，应在目标环境完成一次备份恢复演练。升级的验证范围见升级与回滚。

日常在线备份

在同一 Bash 会话执行，目录需可写且空间充足：

set -euo pipefail
umask 077
cd /opt/timecho-agent/deploy
B="/var/backups/timecho-agent/$(date +%F-%H%M%S)"
mkdir -p "$B"
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > "$B/db.dump"
docker compose exec -T backend tar czf - -C /app/data . > "$B/backend-data.tgz"
docker compose exec -T backend tar czf - -C /app/home/.config/timecho-cli . > "$B/cli-config.tgz"
docker compose exec -T postgres pg_restore --list < "$B/db.dump" > "$B/db-manifest.txt"
tar tzf "$B/backend-data.tgz" > /dev/null
tar tzf "$B/cli-config.tgz" > /dev/null
(cd "$B" && sha256sum db.dump backend-data.tgz cli-config.tgz > SHA256SUMS)

另行安全备份 .env、override、密钥及部署材料。备份完成后复制到异地，并定期进行恢复演练。

升级前的停写备份

在线备份中的数据库与随后打包的附件不是同一瞬间的快照。升级前或要求严格恢复点时，通知用户暂停使用，保持 postgres 运行，停止前后端后备份：

set -euo pipefail
umask 077
cd /opt/timecho-agent/deploy
B="/var/backups/timecho-agent/maintenance-$(date +%F-%H%M%S)"
mkdir -p "$B"
docker compose stop frontend backend
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > "$B/db.dump"
docker compose run --rm -T --no-deps --entrypoint tar backend czf - -C /app/data . > "$B/backend-data.tgz"
docker compose run --rm -T --no-deps --entrypoint tar backend czf - -C /app/home/.config/timecho-cli . > "$B/cli-config.tgz"
docker compose exec -T postgres pg_restore --list < "$B/db.dump" > "$B/db-manifest.txt"
tar tzf "$B/backend-data.tgz" > /dev/null
tar tzf "$B/cli-config.tgz" > /dev/null
(cd "$B" && sha256sum db.dump backend-data.tgz cli-config.tgz > SHA256SUMS)

备份完成后
- 保存材料：另行保存同一恢复点的密钥、.env、override 和部署文件。
- 校验失败：保留日志、先解决问题，不继续升级。
- 仅做备份：成功后运行 docker compose up -d 并验证。
- 接着升级：保持应用停止。

外部 PostgreSQL：由 DBA 按其规范备份，仍要保存附件、Context 和密钥，不使用内置 postgres 容器命令。

3. 恢复示例

恢复会覆盖目标平台数据。 先确认恢复点、目标环境和当前数据的保存方案，再执行。

开始前确认：

同版本镜像和配置已准备，密钥与备份一致。
使用新环境或已准备好的空数据卷。
目标附件和 CLI 配置卷必须为空；不能把文件直接解包到正在使用或已有数据的卷中，以免混入其他时间点的文件。

内置 PostgreSQL 示例：

set -euo pipefail
cd /opt/timecho-agent/deploy
B="/var/backups/timecho-agent/<已确认的备份目录>"
(cd "$B" && sha256sum -c SHA256SUMS)
docker compose config -q
docker compose down
docker compose up -d --wait postgres

# 以下删除并重建当前项目的业务库，必须先确认目标
docker compose exec -T postgres sh -c 'dropdb -U "$POSTGRES_USER" --if-exists "$POSTGRES_DB" && createdb -U "$POSTGRES_USER" "$POSTGRES_DB"'
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner --exit-on-error' < "$B/db.dump"

# 目标卷须为空；一次性容器只解包，不启动后端
docker compose run --rm -T --no-deps --entrypoint tar backend xzf - -C /app/data < "$B/backend-data.tgz"
docker compose run --rm -T --no-deps --entrypoint tar backend xzf - -C /app/home/.config/timecho-cli < "$B/cli-config.tgz"
docker compose up -d
docker compose ps

外部业务库：先由 DBA 恢复到空库，再恢复两个应用卷并启动。日常停止不要使用 docker compose down -v，以免删卷。

恢复后检查：

原账号能登录，会话、知识库、附件和工作区完整。
模型 Key、托管数据库口令与外部服务授权能解密。
数据连接可用，真实只读查询成功。
使用 API Token 或外部工具时，再核对对应配置和调用。

恢复边界：备份之后的平台数据不会自动回来，待审批请求也不会继续执行。

4. 升级与回滚

升级前准备

升级前应完成以下工作：

阅读目标版本发布说明；
在测试环境完成升级和恢复验证；
确认新旧版本的 Compose 模板和 PostgreSQL 大版本；
通知用户停写并安排维护窗口；
备份平台 PostgreSQL、backend-data、cli-config、.env、密钥和部署材料；
保留旧镜像、旧配置和旧数据卷；
确认同一个平台数据库不会同时被两个后端实例使用。

同一 PostgreSQL 大版本下升级

cd /opt/timecho-agent/deploy

docker compose stop frontend backend
docker load -i /path/to/timecho-agent-<新版本>-images.tar.gz
# 按发布说明更新 .env 和 Compose 模板
docker compose config -q
docker compose up -d
docker compose logs --tail=200 backend
docker compose ps

启动后依次验证：

后端和前端状态；
/api/v1/system/info 或系统状态接口；
管理员登录；
模型连通性；
Context 和只读查询；
知识库、会话、附件和工作区；
审批、审计和 API Token。

PostgreSQL 16 升级到 18

PostgreSQL 大版本升级不能只替换镜像并复用旧数据卷，必须执行导出和恢复：

停止前端和后端，保留旧 PostgreSQL 服务；
使用 pg_dump 导出旧数据库；
创建 PostgreSQL 18 的新空数据库；
使用 pg_restore 导入备份；
恢复 backend-data、cli-config 和同一恢复点的密钥；
更新 Compose 配置并启动新服务；
验证登录、模型、Context、知识库、附件和审计；
验证通过后再安排旧环境下线。

升级前必须保留旧镜像、旧配置和旧数据卷。不能把 PostgreSQL 18 镜像直接挂载到 PostgreSQL 16 的数据目录上。

回滚

应用数据库结构发生迁移后，不能依赖新版本自动降级。回滚应使用：

升级前的旧镜像；
升级前的旧 Compose 模板和 .env；
升级前的完整数据库备份；
升级前的 backend-data 和 cli-config；
与备份匹配的加密密钥。

恢复前先保存升级后产生的新数据，再按照恢复示例恢复流程处理。回滚完成后必须验证管理员登录、数据库只读查询、模型调用、知识库和附件。

升级和回滚会中断对话，并可能使未处理的审批失效。操作完成后，应通知用户恢复使用。

5. 主机故障后的冷备切换

切换前提：一个平台数据库只能运行一个后端，不支持多副本同时工作。外部业务库仍正常时，先判断是否只需切换应用主机，不为了切换主动恢复旧备份。

确认原后端已停止或隔离。
在备机恢复同版本配置和数据。
按恢复示例检查通过后，切换访问入口。
原主机恢复后，保持旧后端停止。

仍无法启动时：若确认原主已停止或隔离后，仍提示另一个实例在使用业务库，请由数据库管理员排查，或联系天谋团队协助。问题解决后再启动新实例。