快速安装指南（离线包单机部署）
FinClaw 提供官方一键部署脚本 install-finclaw.sh，向导式收集所有选项后自动完成 Docker 安装、离线包下载解压、镜像加载、.env 初始化、LLM 配置写入、服务启动与健康检查。
一、一键安装（推荐）
前置条件
| 项 | 要求 |
|---|---|
| 权限 | root（或可 sudo） |
| 系统 | CentOS 8+ / RHEL 8+ / Ubuntu 22.04+，x86_64 |
| 网络 | 能访问 static.finogeeks.club 和发布包 URL（脚本自动下载） |
| 基础工具 | curl、tar、openssl（脚本会检测） |
| Docker | 可选 —— 未安装时脚本自动下载离线包安装 |
一行命令安装
bash
curl -fsSL https://static.finogeeks.club/deploy/init_env/install-finclaw.sh -o install-finclaw.sh \
&& sudo bash install-finclaw.sh非 root 用户务必加
sudo。脚本检测到非 root 会直接报错退出。
安装向导会问什么
脚本会先收集所有选项再确认开始，避免长时间下载中途被打断。需要回答的内容：
| 问题 | 默认值 | 说明 |
|---|---|---|
| 是否安装 Docker | （未装才问） | 自动从 static.finogeeks.club 下载 Docker 离线包 |
| Docker 数据目录 | /data/docker | 留空 = 默认；输 /data/2026 自动追加 /docker |
| 发布包 URL | 无 | 必填，必须 http(s):// 开头 |
| 安装/解压目录 | /data | 离线包会解压到此目录下 |
| 目标目录已存在 | — | 1）跳过解压用现有目录 / 2）中止 |
LLM_PROVIDER | openai | OpenAI 兼容协议（含 Xinference / vLLM / 自建网关） |
LLM_MODEL | deepseek-v4-flash | 与上游模型名一致 |
LLM_BASE_URL | https://api.deepseek.com/v1 | OpenAI 兼容 Base URL，需含 /v1 |
LLM_API_KEY | 无 | 必填，无鉴权可填 not-empty |
确认后脚本不再打断，自动执行 6 步：
| 步骤 | 内容 |
|---|---|
| 1/6 | 安装 Docker（如需） |
| 2/6 | 下载并解压发布包（缓存到 <install_root>/.cache/） |
| 3/6 | load-images.sh basic 加载镜像 |
| 4/6 | init-env.sh 从 .env.example 生成 .env、签发 Identity JWT 密钥 |
| 5/6 | 写入 LLM 配置 + 探测 LLM 连通性 |
| 6/6 | fleet.sh basic up -d 启动 + 等 10 秒 + doctor.sh 健康检查 |
完成后输出访问信息：
text
用户端: http://<服务器IP>:26100/
管理端: http://<服务器IP>:26100/admin/
本地健康检查:
curl http://127.0.0.1:26100/health
curl http://127.0.0.1:26450/health
更新 LLM: sudo ./install-finclaw.sh update-llm状态文件
脚本会把本次安装信息写入 <install_root>/.finclaw-install.state（默认 /data/.finclaw-install.state），便于后续 update-llm 自动定位 deploy 目录：
bash
INSTALL_ROOT=/data
RELEASE_DIR=/data/chatkit-offline-release-1.0.96-linux-amd64
DEPLOY_DIR=/data/chatkit-offline-release-1.0.96-linux-amd64/deploy
EDITION=basic
INSTALLED_AT=2026-06-23T08:00:00Z
RELEASE_URL=https://temp-...../chatkit-offline-release-1.0.96-linux-amd64.tar.gz二、脚本其他命令
更新 LLM 配置
修改 LLM_* 并自动 fleet.sh basic down && up -d：
bash
# 自动从 /data/.finclaw-install.state 找 deploy 目录
sudo bash install-finclaw.sh update-llm
# 明确指定 deploy 目录
sudo bash install-finclaw.sh update-llm -d /data/chatkit-offline-release-1.0.96-linux-amd64/deploy查看帮助
bash
bash install-finclaw.sh --help三、环境变量
| 变量 | 默认值 | 用途 |
|---|---|---|
FINCLAW_DOCKER_CACHE_DIR | <Docker数据目录>/.cache | Docker 离线包缓存目录（脚本只下载不删除） |
DOCKER_INIT_URL | https://static.finogeeks.club/deploy/init_env/init/docker29.tar.gz | Docker 离线包下载地址 |
四、手工部署流程（备选）
适用场景：
- 离线环境无法访问
static.finogeeks.club与发布包 URL（需手工把发布包传到目标机）。
bash
# 1. 解压发布包
tar -xzf chatkit-offline-release-<version>-linux-amd64.tar.gz
cd chatkit-offline-release-<version>-linux-amd64/deploy
# 2. 校验包完整性
sha256sum -c CHECKSUMS.sha256
# 3. 加载镜像
./scripts/load-images.sh basic
# 4. 初始化环境（生成 .env 与 JWT 密钥）
./scripts/init-env.sh
# 5. 编辑 .env，至少配置 LLM
vi .env
# LLM_PROVIDER=deepseek
# LLM_MODEL=deepseek-v4-flash
# LLM_API_KEY=<你的密钥>
# LLM_BASE_URL=https://api.deepseek.com/v1
# 6. 启动
./scripts/fleet.sh basic up -d
# 7. 健康检查
./scripts/doctor.sh五、常见问题
| 现象 | 原因 / 处理 |
|---|---|
需要 root 权限 | 用 sudo bash install-finclaw.sh |
不支持的 CPU 架构 | 脚本仅支持 amd64 / arm64；其他架构报错 |
URL 必须以 http:// 或 https:// 开头 | 发布包 URL 必须完整 |
文件不是有效的 gzip 压缩包 | 下载被中断或 URL 错误，重试 |
LLM 连通性检查未通过 (HTTP xxx) | 容器内不能用 localhost 访问宿主机 LLM，需用宿主机 IP 或 Docker 网关地址 |
doctor.sh 报告异常 | 首次启动约 2–5 分钟，稍等后重新执行 ./scripts/doctor.sh |
| 目标目录已存在 | 选 1 跳过解压复用现有目录；选 2 中止后手工清理 |
六、卸载与重装
脚本不提供 uninstall 命令，手工卸载：
bash
# 1. 停止服务
cd /data/chatkit-offline-release-<version>-linux-amd64/deploy
./scripts/fleet.sh basic down
# 2. 删除数据卷（如需彻底清理）
docker volume ls | grep chatkit
docker volume rm <对应卷名>
# 3. 删除发布包目录与状态文件
rm -rf /data/chatkit-offline-release-<version>-linux-amd64
rm -f /data/.finclaw-install.state
rm -f /data/.cache/chatkit-offline-release-*.tar.gz # 如需释放缓存重装时直接再跑一次一键脚本，目标目录存在时选「中止」并手工清理后重试。