部署 · 文档

开通 Clauve 后，坐席由 Clauve 提供，系统部署在你自己的环境里。这一篇给负责部署的工程师看，Clauve 团队会和你一起完成首次上线。

部署形态

组件	形态	说明
服务端 + 管理控制台	一个容器镜像	FastAPI 服务，默认监听 `8000` 端口，控制台由同一服务渲染
数据库	PostgreSQL	账号、组织、团队、租约、审计记录的统一存储
客户端入口	内网负载均衡	桌面版和 `clauve-cli` 通过它连接服务端

服务端附带 Helm Chart，部署在你的 K8s 集群里。

前置条件

一个可用的 K8s 集群，以及能操作它的 kubeconfig。
helm，以及用于变更预览的 helm-diff 插件：

helm plugin install https://github.com/databus23/helm-diff

数据库口令 Secret 需要在部署前创建好，Chart 不会自动生成它。

构建并推送镜像

bash deployment/build-push.sh

脚本会自动生成镜像 tag，并校验镜像架构为 linux/amd64，最后输出这次的 tag。

预览并部署

先预览变更，确认后再正式部署：

bash deployment/helm-deploy.sh --tag <上一步输出的 tag> --diff true
bash deployment/helm-deploy.sh --tag <上一步输出的 tag> --diff false

选项	说明
`--tag`	镜像 tag，必填
`--target`	部署到的 namespace，同时决定使用 `helm/values-<target>.yaml`
`--diff`	为 `true` 时先 `helm diff` 再确认，默认 `true`

集群由当前 kubeconfig 的 context 决定，换集群只需要切换 context。

如果本机出网走代理，而集群 API server 按来源 IP 做了白名单，kubectl / helm 需要绕开代理连接，否则会被拒成 Forbidden。

初始化数据库与管理员

表结构定义在 server/scripts/init.sql。新库执行建库脚本即可：

python server/scripts/create_db.py

组织和第一个平台管理员需要手动创建（创建组织没有对外接口）：

python server/scripts/create_admin.py --org-name "你的组织" --user-name admin

不传 --password 时会随机生成密码并打印出来。之后用这个账号登录控制台的 /login，在「坐席成员」里给成员建号。

打包客户端

客户端的服务端地址是编译期写死进安装包的，所以要用你的内网入口地址打包：

client/scripts/build-dmg.sh http://<服务端内网地址>:8000          # macOS 桌面版
client/scripts/build-linux.sh http://<服务端内网地址>:8000        # Linux 命令行版（x86_64 + arm64）
client/scripts/build-linux-desktop.sh http://<服务端内网地址>:8000 # Linux 桌面版 deb / rpm / AppImage

产物统一放在 client/dist/ 下按系统分目录。服务端地址变了需要重新打包分发。

升级

服务端：重新构建镜像，用新 tag 跑一遍「预览并部署」。给已存在的库加字段时，按发布说明执行对应的迁移 SQL。
客户端：成员用 clauve-cli restart --install <新版 Clauve.app>（macOS）升级，坐席会保留，正在用的 Claude Code 不会断线。