跳到主要内容

备份与恢复

即使容器丢失,也必须保留下来的内容有三项。其余内容(已注册的 MCP 服务器、工作流、用户、系统设置)都是数据库中的行,备份数据库时会一并保留。

内容备份方式恢复方式
数据库pg_dump,或复制 SQLite 文件pg_restore,或把文件放回原处
代理技能存储库复制 SKILLS_DIR 目录树解压回原处
密钥加密密钥SECRET_ENCRYPTION_KEY 的值,或 SECRET_KEY_FILE 指向的文件设置相同的值,或放回同一个文件

数据库和加密密钥必须一起恢复。这个加密密钥既用于解密本地密钥,也用于解密审批 CA 的签名密钥,而这两者都存放在数据库中。如果恢复的数据库搭配了另一个加密密钥,启动后所有密钥都将无法读取。

数据库​

PostgreSQL:

pg_dump --format=custom --file=a2flow-$(date +%F).dump "postgresql://user:password@host:5432/a2flow"
pg_restore --clean --if-exists --dbname="postgresql://user:password@host:5432/a2flow" a2flow-2026-01-31.dump

使用 Docker Compose 时,直接访问 db 服务:

docker compose exec -T db pg_dump -U a2flow -Fc a2flow > a2flow-$(date +%F).dump
docker compose exec -T db pg_restore -U a2flow -d a2flow --clean --if-exists < a2flow-2026-01-31.dump

SQLite 只有一个文件,路径由 DB_URL 指定。应用运行期间请使用 sqlite3 a2flow.db ".backup out.db",不要直接复制文件。

恢复后的数据库无需单独执行迁移:后端启动时会应用所有待执行的 Alembic 迁移,因此把旧的转储恢复到新版本后再启动,架构就会自动升级到最新。

代理技能存储库​

重新注册技能无法重建 SKILLS_DIR。拉取技能时克隆的是仓库当前的 HEAD,因此固定在旧修订版本上的运行拿不回那个修订版本,会一直无法加载其技能。请备份这个目录。

已发布的修订版本目录此后不会再被修改,因此在应用运行期间复制的内容也是一致的:

tar -czf skills-$(date +%F).tgz -C /var/lib/a2flow/skills .

使用 Docker Compose 时,存储库是名为 skills 的命名卷:

docker run --rm -v a2flow_skills:/skills -v "$PWD:/backup" alpine \
tar -czf /backup/skills-$(date +%F).tgz -C /skills .

恢复时,把归档解压到空的存储库中,然后启动后端。

密钥加密密钥​

如果显式设置了 SECRET_ENCRYPTION_KEY,加密密钥已经保存在存放部署配置的地方,这里无需额外操作,只需确保该配置存储本身有备份。

如果没有设置,后端会在首次使用时生成一个,并写入 SECRET_KEY_FILE 指向的文件(默认为 .secret_key,与 SQLite 数据库文件相邻)。这个文件是唯一的副本。请把它备份到所在机器以外的地方,并像对待凭据一样妥善保管,因为它本身就是凭据。

使用 Docker Compose 时,该文件位于名为 secret-key 的命名卷中:

docker run --rm -v a2flow_secret-key:/key -v "$PWD:/backup" alpine cp /key/.secret_key /backup/secret_key-$(date +%F)

不支持轮换加密密钥,因为现有的密钥都是用旧加密密钥加密的。请参阅密钥管理。

检查恢复结果​

  1. 启动后端,确认 GET /api/v1/health 返回 200。这说明数据库可以访问,且架构是最新的。
  2. 在管理界面中打开一个 local 类型的密钥。能正常加载而不报错,说明加密密钥与数据库匹配。
  3. 打开一个原本正在进行的工作流执行。能够继续运行而不报告 SKILL_NOT_READY,说明技能存储库已恢复,且仍在使用的修订版本都在。