升级流程

FinClaw 升级流程整体与首次部署相同：解压新包 → 加载镜像 → 初始化环境 → 配置 LLM → 停旧版 → 启新版。区别仅在于第 4 步要对照旧 .env 把改过的关键配置（重点是大模型配置）写到新 .env 里，避免遗漏。

一、升级步骤

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 basic

3. 初始化环境

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

./scripts/init-env.sh

4. 对比旧 .env，迁移配置（重点是大模型配置）

新生成的 .env 只有默认值。需把旧版本里改过的项对照迁移到新 .env，其中最关键的就是 LLM 配置。

# 假设旧版部署目录是 /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
大模型（必须）	LLM_PROVIDER / LLM_MODEL / LLM_BASE_URL / LLM_API_KEY	✅
管理员	ADMIN_EMAILS	✅
并发限制	AI_INFRA_RS_*	✅（如有调过）

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

编辑新 .env（重点核对 LLM 4 项）：

vim .env

LLM_PROVIDER=openai
LLM_MODEL=<模型名称>
LLM_BASE_URL=<LLM 服务地址>
LLM_API_KEY=<你的 API Key>

5. 停止旧版服务

cd /data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
./scripts/fleet.sh basic 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 basic 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 basic

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

仍建议在执行后对照确认 .env 中 LLM 4 项是否正确。