安装与维护
准备交付包、部署网关、配置 HTTPS 与员工域名,并保持数据安全更新。
准备环境与交付包
客户服务器运行网关、PostgreSQL 和 Redis。使用 Linux/amd64,准备 Docker Engine 与 Compose 插件;Ubuntu 可按 Docker 官方步骤安装。
服务器需要能获取 Compose 中固定版本的依赖镜像。普通交付包不是完整离线包;客户不需要安装 Go、Node 或获取源代码编译。
将可信渠道交付的以下文件放在同一目录,例如 /opt/claude-gateway:
compose.gateway.yaml
compose.gateway.nginx.yaml
gateway.env.example
gateway-image.tar
SHA256SUMS
nginx.gateway.conf.example
THIRD_PARTY_NOTICES.md确认文件与本次交付版本一致。校验和用于检查文件完整性,交付来源仍须可信。
cd "/opt/claude-gateway"
docker version
docker compose version
sha256sum -c "SHA256SUMS"
docker load -i "gateway-image.tar"
umask 077
cp "gateway.env.example" ".env".env 只在首次安装时创建;已有安装保留原配置。
填写配置
在 .env 中填写交付镜像名、自己的主站访问源站,以及独立的 PostgreSQL 和 Redis 密码。镜像名应与交付结果一致,不使用来源不明的 latest。
GATEWAY_PUBLIC_ORIGIN=https://gateway.example.com
GATEWAY_BIND_IP=127.0.0.1
GATEWAY_PORT=8088使用 openssl rand -hex 32 分别生成数据库和 Redis 密码。模板将密码放入连接 URL,建议使用生成的十六进制值,避免 @、:、/、#、% 等保留字符带来解析问题;不要在文档或聊天中发送真实密码。
新库管理员未配置时,初始账号为 admin、密码为 admin;登录后立即在系统配置一起修改。已有管理员记录以数据库为准,修改初始化环境值不能重置已有密码。
部署后在“系统配置”激活软件许可,并按需添加自定义调用 Key。客户不需要填写运营签名私钥或授权服务地址。
选择直连或宿主 Nginx
直连
使用基础 Compose。默认只绑定宿主 127.0.0.1:8088,可用于本机检查;正式远程访问需要按实际场景配置 HTTPS。
docker compose --env-file ".env" -f "compose.gateway.yaml" config --quiet
docker compose --env-file ".env" -f "compose.gateway.yaml" up -d --wait --wait-timeout 180标准宿主 Nginx
使用基础文件和 Nginx 叠加文件。叠加模板需要 Compose 2.24.4 或更新版本;安装和日常维护始终使用同一组文件。
docker compose --env-file ".env" \
-f "compose.gateway.yaml" -f "compose.gateway.nginx.yaml" config --quiet
docker compose --env-file ".env" \
-f "compose.gateway.yaml" -f "compose.gateway.nginx.yaml" \
up -d --wait --wait-timeout 180模板使用 10.243.89.0/24 网段、桥接网关 10.243.89.1。先核对是否与现有网络冲突;需要更改时,成对调整网段、网关及网关配置中的可信单 IP,不扩大为信任全部内网。
将 nginx.gateway.conf.example 中域名、证书和端口替换为自己的值,经 nginx -t 检查后按服务器原有方式加载配置。应用端口只供本机 Nginx 访问,PG 和 Redis 不发布宿主端口。
保留示例中的 Host 和来源转发设置,以及关闭缓冲、缓存和代理层请求重试的 SSE 配置。宿主 Nginx 使用示例中的 127.0.0.1:8088;Nginx 如果自己运行在容器中,需要按真实网络另行配置,不能把容器的回环地址当成宿主机。
Docker 网关的标准叠加模板已配置可信宿主桥接来源。直接在宿主运行网关时,可信 Nginx 地址才是 127.0.0.1/32,两种场景不能混用。自定义 CDN 或多层反向代理需按实际链路核验。
安装后核验
- 查看 Compose 状态和 gateway 日志,确认依赖健康。
- 通过实际 HTTPS 主站登录,核对页面地址与
GATEWAY_PUBLIC_ORIGIN一致。 - 修改初始管理员密码,填写并激活软件授权码。
- 使用有效调用 Key 查询 模型列表,确认认证与目录可用。
docker compose --env-file ".env" -f "compose.gateway.yaml" ps
docker compose --env-file ".env" -f "compose.gateway.yaml" logs --tail 100 gateway
curl --fail-with-body "http://127.0.0.1:8088/readyz"使用标准 Nginx 的部署,在上面的 Compose 命令中继续加上 -f "compose.gateway.nginx.yaml"。
/healthz 表示进程可响应;/readyz 检查程序是否就绪以及 PG/Redis 是否可用。健康不代表软件许可已激活,也不代替真实模型调用检查。
模型接口白名单
在“系统配置”填写允许调用的实际公网出口 IP,一行一个 IP 或 CIDR。留空表示不限,保存后对新请求生效;不要填写标准 Nginx 使用的内部桥接地址。
从允许和不允许的来源分别使用有效 Key 访问 /v1/models,核对允许来源可用、拒绝来源返回 403。先排除 401 鉴权失败,再判断白名单;模型目录未就绪等错误需要单独处理。无需真实生成请求来验证 IP 规则。
填错规则后仍可登录管理后台修正。来源显示不正确时,依次核对真实公网出口、是否遗漏叠加文件、可信代理地址和 Nginx 来源头设置。
员工端域名
员工端与主站使用同一个网关程序,配置单独的访问源站。
- 将员工域名,例如
team.example.com,解析到同一台服务器。 - 配置有效 HTTPS 证书;可以与主站使用一张多域名证书。
- 复制主站 Nginx server 段,只改域名和证书,转发到同一个网关端口,保留 Host 设置。
- 在
.env设置GATEWAY_PORTAL_ORIGIN=https://team.example.com,使用原文件组合执行docker compose up -d gateway使环境变化生效。
员工源站必须使用 HTTPS,不能带路径或与主站相同;错误配置会使程序启动失败。没有第二个域名时,可使用同一域名的另一端口并配置 HTTPS、Nginx 和防火墙。不能使用同域名加 /team 路径代替。
配置后核验:主站用管理员登录,员工端用员工或主管登录;同一浏览器可同时保持两侧登录,互不覆盖,并能完成授权链接上号。模型接口白名单不影响员工端登录。详情见 员工管理。
配置通知
在“系统配置”选择邮件、Telegram 或飞书,保存整组参数后主动测试。通知使用全局默认代理;核对 SMTP 端口、机器人权限、Webhook 签名和关键词等要求,见 通知设置。
服务方确认接受不代表收件人已读。CPU、内存取程序可见范围,空间告警针对应用卷;程序或整机停止时不能依靠自身保证发信。
更新与正常停止
网关应用通过账号菜单中的“版本更新”选择兼容版本。下载及校验期间旧程序继续运行,准备完成后正常退出并由 Docker 重启;网页恢复后核对实际版本和任务结果。
插件单独下载、替换目录并在浏览器重新加载。网页应用更新不会升级 PostgreSQL、Redis 引擎或自动修改旧 Compose 的资源配置;运行底座升级按对应版本维护说明执行。
需要停止整套服务时先停止网关,确认退出后再停止依赖,保持原数据卷:
docker compose --env-file ".env" -f "compose.gateway.yaml" stop gateway
docker compose --env-file ".env" -f "compose.gateway.yaml" stop postgres redis标准 Nginx 部署继续使用两个 Compose 文件。不要缩短正常退出等待时间,也不要通过删除卷或清库处理更新失败。
备份、迁移与已有安装切换
备份包括 PostgreSQL、完整程序卷、原 .env 与镜像资料;这些材料可能包含明文凭证,应限制访问。数据库使用 pg_dump / pg_restore,不要直接复制运行中的 PG 数据目录。
迁移前停止旧网关,在隔离的新部署中恢复,保留原安装身份、管理员和业务数据;不要让同一安装的新旧网关同时连接真实上游。需要连同 Redis 运行状态迁移时,正常停止后保存完整 /data 及权限。
新装没有原安装备份时,先联系运营确认软件许可绑定与新出口,不能仅复制授权码期待自动接管。软件许可恢复不会代替 Token、日志和用量备份。
已有安装从直连切到标准 Nginx、改网段或调整端口前,先核对现有项目名、网络、数据卷及配置,按维护窗口重建受影响服务;使用原卷和同一文件组合,不照搬首次安装覆盖 .env。
应用升级涉及不兼容的数据结构时,不能仅换回旧程序回退。先核对该版本说明,保留错误现场并联系维护方确认恢复路径。


