备份和恢复

单机部署模式下，FinClaw 的所有有状态数据都在 Docker 命名卷里（chatkit_* 前缀）。本节给出一种最简单可行的备份方案：停服 → 整卷打包 → 启服。生产环境如需 RPO/RTO 更严格的方案，可再叠加 pg_dump 逻辑备份或卷快照。

一、需要备份的内容

1. 配置文件

路径	说明
deploy/.env	LLM 凭证、JWT 密钥、内部 token、并发参数
deploy/config/	services.yaml、ai-infra.yaml、idp.yaml 等 yaml 配置
deploy/docker-compose.override.yml（如有）	自定义端口等覆写

2. Docker 数据卷

chatkit_* 系列卷，全部由 docker-compose.yml 声明为 external: true：

卷名	内容
chatkit_postgres_data	PostgreSQL 数据（identity / inbox / persona / skill / document / pulse 等）
chatkit_timescaledb_data	TimescaleDB 数据（conversation-store 会话历史）
chatkit_ai_infra_data	AI 运行时持久化数据（审计日志、记忆索引、会话状态、mcp-servers.yaml）
chatkit_workspaces	用户工作区（已安装技能、记忆文件）
chatkit_skills_data	平台技能数据（由 skills-init 写入）
chatkit_persona_uploads	画像服务上传文件
chatkit_identity_uploads	Identity 服务上传文件（头像等）
chatkit_doc_toolkit_cache	文档工具缓存
chatkit_nats_data	NATS JetStream（事件流，短期消息）
chatkit_redis_data	Redis 缓存与协调状态
chatkit_restate_data	Restate 定时器与 cron 状态
chatkit_tei_models	TEI 模型缓存

单机部署的简单原则：chatkit_* 全打包 —— 不要试图人工筛选，漏掉一个就可能丢数据。

二、备份操作

步骤 1：停服

数据卷在容器运行期备份会得到不一致快照（特别是 PostgreSQL）。先停服再备份。

cd /data/chatkit-offline-release-1.0.xx-linux-amd64/deploy
./scripts/fleet.sh basic down

down 只停容器，不删卷。

步骤 2：打包配置 + 数据卷

# 准备备份目录
BACKUP_DIR=/data/backups/finclaw-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"

# 1) 配置：直接 tar 打包 deploy 目录里的关键文件
tar -czf "$BACKUP_DIR/deploy-config.tar.gz"   -C /data/chatkit-offline-release-1.0.xx-linux-amd64/deploy   .env config docker-compose.override.yml 2>/dev/null || true

# 2) 数据卷：用一次性容器把每个卷的内容打包到备份目录
for vol in $(docker volume ls -q | grep '^chatkit_'); do
  echo ">> backing up volume: $vol"
  docker run --rm     -v "$vol":/source:ro     -v "$BACKUP_DIR":/backup     alpine     tar -czf "/backup/${vol}.tar.gz" -C /source .
done

# 3) 记录卷清单 + 版本信息
docker volume ls --filter "name=chatkit_" --format '{{.Name}}' > "$BACKUP_DIR/volumes.txt"
echo "release_dir=$(realpath /data/chatkit-offline-release-1.0.xx-linux-amd64)" > "$BACKUP_DIR/meta.txt"
date -u +"backup_time=%Y-%m-%dT%H:%M:%SZ" >> "$BACKUP_DIR/meta.txt"

# 4) 看看备份目录
ls -lh "$BACKUP_DIR"

步骤 3：启服

./scripts/fleet.sh basic up -d
./scripts/doctor.sh

备份产物示例

/data/backups/finclaw-20260625-030000/
├── deploy-config.tar.gz           # .env + config/ + override
├── chatkit_postgres_data.tar.gz
├── chatkit_timescaledb_data.tar.gz
├── chatkit_ai_infra_data.tar.gz
├── chatkit_workspaces.tar.gz
├── chatkit_skills_data.tar.gz
├── chatkit_persona_uploads.tar.gz
├── chatkit_identity_uploads.tar.gz
├── chatkit_doc_toolkit_cache.tar.gz
├── chatkit_nats_data.tar.gz
├── chatkit_redis_data.tar.gz
├── chatkit_restate_data.tar.gz
├── chatkit_tei_models.tar.gz
├── volumes.txt                    # 卷名清单
└── meta.txt                       # 版本与备份时间戳

三、恢复操作

步骤 1：停服并清空旧卷

cd /data/chatkit-offline-release-1.0.xx-linux-amd64/deploy
./scripts/fleet.sh basic down

# 删除所有 chatkit_* 卷（确认要回滚到备份状态再执行！）
docker volume ls -q | grep '^chatkit_' | xargs -r docker volume rm

⚠️ 这步会丢失当前未备份的数据，确认无误再执行。

步骤 2：恢复配置

BACKUP_DIR=/data/backups/finclaw-20260625-030000   # 替换为你的备份目录

tar -xzf "$BACKUP_DIR/deploy-config.tar.gz"   -C /data/chatkit-offline-release-1.0.xx-linux-amd64/deploy

步骤 3：恢复数据卷

# 逐个还原卷：先创建空卷，再把 tar.gz 解到卷里
for tarball in "$BACKUP_DIR"/chatkit_*.tar.gz; do
  vol=$(basename "$tarball" .tar.gz)
  echo "<< restoring volume: $vol"
  docker volume create "$vol" >/dev/null
  docker run --rm     -v "$vol":/target     -v "$BACKUP_DIR":/backup:ro     alpine     tar -xzf "/backup/${vol}.tar.gz" -C /target
done

步骤 4：启服 + 验证

./scripts/fleet.sh basic up -d
./scripts/doctor.sh
curl http://127.0.0.1:26100/health

预期 doctor.sh 全 ✅、/health 返回 200 OK。若个别服务首次启动较慢，等 2–5 分钟再跑一次。