升级流程

FinClaw 升级流程整体与首次部署相同：解压新包 → 加载镜像 → 初始化环境 → 迁移 .env 配置 → 停旧版 → 启新版。区别仅在于第 4 步要对照旧 .env 把改过的关键配置写到新 .env 里，避免遗漏。LLM 模型配置持久化在数据库（管理后台维护），升级不受影响、无需迁移。

一、升级步骤

1. 解压新版离线包

最新版本地址由凡泰人员提供。

# 进入数据盘
cd /data

# 解压（文件名按实际版本替换）
tar -xzf chatkit-offline-release-1.0.xx-linux-amd64-xxxxxxxx.tar.gz
cd chatkit-offline-release-1.0.xx-linux-amd64/deploy

2. 加载镜像

./scripts/load-images.sh

3. 初始化环境

自动从 .env.example 生成 .env、生成 Identity 服务的 JWT 密钥与各类内部 token：

./scripts/init-env.sh

4. 对比旧 .env，迁移配置

新生成的 .env 只有默认值。需把旧版本里改过的项对照迁移到新 .env。

# 假设旧版部署目录是 /data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
OLD_DEPLOY=/data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
NEW_DEPLOY=$(pwd)

# 直接对比两份 .env，快速定位需要迁移的差异项
diff "$OLD_DEPLOY/.env" "$NEW_DEPLOY/.env" | less

最少要保留 / 同步的内容：

类别	变量	来自旧 .env
管理员	ADMIN_EMAILS	✅
并发限制	AI_INFRA_RS_*	✅（如有调过）

JWT 密钥可以使用 init-env.sh 新生成的随机值，无需强制沿用旧值；只是已登录用户需要重新登录，业务数据不受影响。

编辑新 .env，按上表迁移差异项：

vim .env

5. 停止旧版服务

cd /data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
./scripts/fleet.sh down

down 只停容器，不会删除数据卷（PostgreSQL / TimescaleDB / NATS / Redis / chatkit_ai_infra_data 等）。新版会复用这些卷，会话历史、用户数据、向量记忆都保留。

6. 启动新版服务

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

7. 健康检查

./scripts/doctor.sh
curl http://127.0.0.1:26100/health

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

二、一键升级脚本（可选）

发布包内有自动脚本，能把上述 2~6 步合并：自动加载镜像、复制旧 .env、启动、健康检查。

# 从**新版** deploy 目录执行；指向旧 deploy 目录
OLD_DEPLOY_DIR=/data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy \
  ./scripts/upgrade-offline-release.sh

脚本流程：加载新镜像 → 复制旧 .env（保留 JWT / 内部 Token 等所有改过的项）→ fleet.sh up → doctor.sh → 输出升级摘要。

三、K8s 集群升级

关键差异：

• 基础层（PG/Timescale/Restate/Redis/TEI/NATS）通过 ansible deploy.yaml 重跑滚动升级
• 应用层通过 helm upgrade 滚动更新