Docker Compose 部署

仓库提供的 docker-compose.example.yml 是一套完整的单机部署,全部配置都直接写在这一个文件里:API、两个控制台、邮件投递、PostgreSQL、Redis 以及两项每日备份。

环境要求

项目要求
主机Linux x86_64,建议 2 核 4 GB 起
软件Docker、Docker Compose v2、Git、OpenSSL
网络可访问 Docker Hub、SMTP 服务器与所需的上游 API
域名API、配置管理、账户管理各一个,HTTPS 由反向代理提供

1. 获取部署文件

git clone https://github.com/xabcstack/xsi.git
cd xsi

umask 077
cp docker-compose.example.yml docker-compose.yml
sed -i "s/CHANGE_ME_POSTGRES_PASSWORD/$(openssl rand -hex 24)/g" docker-compose.yml
sed -i "s/CHANGE_ME_ROOT_KEY/sk-Xvs$(openssl rand -hex 24 | cut -c1-45)/" docker-compose.yml

两条 sed 命令分别生成数据库密码与 root 账号的 API Key。root Key 写在 INIT_USERS 中,必须恰好 51 个字符(sk-Xvs 前缀 6 位 + 45 位随机字符)。docker-compose.yml 与备份目录已被 .gitignore 排除。

2. 编辑 docker-compose.yml

需要修改的只有以下几处,其余保持模板值即可:

位置配置说明
顶部 x-siteXAI_SVC、XAI_API、XAI_ADMIN、XAI_MANAGE、XAI_DOCS站点、API、配置管理、账户管理与文档站的域名,只写主机名,不带协议、路径或 /v1。API 与控制台两个服务共用这一处
顶部 x-tz时区默认 Asia/Shanghai,影响日期统计与日额度的切换时间;如修改,请同步 POSTGRES_DSN 中的 TimeZone
xsirouter-xsiINIT_USERS、XAI_MAIL把 [email protected] 换成你的 root 邮箱,它同时接收平台通知
xsirouter-xsiTRUSTED_PROXY_CIDRS受信任的反向代理网段,见《反向代理》
xsirouter-xsiSIGN_ENABLE是否开放自助注册,默认 true;开放前请先完成邮件配置
xsirouter-mailEMAIL_SMTP、EMAIL_PORT、EMAIL_TLS、EMAIL_AUTH、EMAIL_PASS你的 SMTP 服务;EMAIL_TLS: "true" 对应隐式 TLS(通常为 465 端口)
xsirouter-pagesBRAND_NAME、LICENSE_ID、XPAY_API、SUPPORT_QR_URL控制台品牌名,以及可选的商业授权编号、支付网关地址(形如 https://pay.example.com/t/my-tenant)与客服二维码
备份服务BACKUP_RETENTION_DAYS备份保留天数,默认 3

端口默认绑定 127.0.0.1,供同机反向代理访问;反向代理在其他主机时,改为可达的地址并配置访问控制。值中的 $ 需写成 $$。完整的环境变量说明见《配置参考》。

3. 启动

docker compose config --quiet   # 校验配置
docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:5443/healthz   # 返回 OK

模板使用 pull_policy: always,每次启动都会拉取最新镜像。/healthz 返回 OK 只表示 HTTP 服务已就绪;调用模型还需完成下文的上游配置。

服务清单

服务镜像端口说明
xsirouter-xsiproxyxai/xsi5443 → 3443API;停止宽限期 60 秒,文件描述符上限 1048576
xsirouter-pagesproxyxai/xsi-pages5080 → 8080、5081 → 8081配置管理与账户管理控制台
xsirouter-mailproxyxai/mail—消费 Redis DB 1 的邮件队列并通过 SMTP 投递;停止宽限期 40 秒
xsirouter-postgrespostgres:18—业务数据,命名卷挂载至 /var/lib/postgresql
xsirouter-redisredis:alpine—配置、缓存、用量与队列,命名卷挂载至 /data
xsirouter-postgres-backuppostgres:18—每日 pg_dump 至 backups/postgres/
xsirouter-redis-backupredis:alpine—每日 RDB 快照至 backups/redis/

PostgreSQL 与 Redis 只在 Compose 内部网络中可达,不发布主机端口。

模板为 API 固定设置了以下运行参数,可按需在 docker-compose.yml 中调整:

变量模板值说明
USER_MIN_BALANCE2余额低于 1.99 时冻结调用
XAI_CREDIT0自助注册不赠送额度
MODEL_FAILOVER_THRESHOLD2模型连续失败 2 次触发分组切换或故障替换
EMAIL_SMTP、EMAIL_AUTH、EMAIL_PASS空API 不设默认 SMTP,由邮件服务统一投递;租户可另配自有 SMTP

4. 配置 HTTPS 入口

将三个域名解析到反向代理并配置证书:

入口对外地址同机转发目标
APIhttps://api.example.comhttp://127.0.0.1:5443
配置管理https://admin.example.comhttp://127.0.0.1:5080
账户管理https://manage.example.comhttp://127.0.0.1:5081

API 入口必须支持流式响应与 WebSocket 升级,Nginx 与 Caddy 示例见《反向代理》。控制台英文界面位于各自的 /en/。

5. 接入上游并创建调用账号

  1. 打开配置管理控制台,使用 root Key(INIT_USERS 中的 sk-Xvs...)登录。
  2. 在“模型服务”中添加上游 Key,填写 Provider、SecretKey 与 Level,例如 OpenAI 放 Level 1、Anthropic 放 Level 2。XSI 会按服务商自动生成 LEVEL_MAPPER。
  3. 在“系统配置”中核对 LEVEL_MAPPER,按需设置 MODEL_MAPPER、SWITCH_OVER 等,见《路由与故障转移》。
  4. 核对 默认价格表,需要时通过租户 PRICING 覆盖。
  5. 在账户管理控制台创建实际调用用的子账号并分配额度,应用使用子账号的 Key。
root Key 拥有平台的全部权限,只用于管理,不要用于日常模型调用或分发给应用。INIT_USERS 只创建尚不存在的账号;修改 docker-compose.yml 不会重置已有 root 的 Key,轮换请使用 POST /x-self。

6. 验证

export XSI_BASE_URL="https://api.example.com"
export XSI_API_KEY="<子账号 Key>"

curl "$XSI_BASE_URL/dashboard/status" -H "Authorization: Bearer $XSI_API_KEY"

curl "$XSI_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.2-sol", "messages": [{"role": "user", "content": "Hello"}]}'

多租户与多实例

需求设置
自助注册用户成为独立租户(自带上游 Key)API 环境变量 SINGLE_TENANT=false
多个 API 实例横向扩展所有实例共享同一 PostgreSQL 与 Redis,并设置 SINGLE_MODE=false

多实例部署时,所有 API 实例共享同一 PostgreSQL 与 Redis,并在每个 API 容器的 environment 中显式设置 SINGLE_MODE: "false"(模板默认不传递该变量);粘性绑定、限速计数与变更通知随即通过 Redis 共享。在同一主机上扩容前,需移除模板中固定的 container_name 与 5443 端口映射。

相关文档