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-site | XAI_SVC、XAI_API、XAI_ADMIN、XAI_MANAGE、XAI_DOCS | 站点、API、配置管理、账户管理与文档站的域名,只写主机名,不带协议、路径或 /v1。API 与控制台两个服务共用这一处 |
顶部 x-tz | 时区 | 默认 Asia/Shanghai,影响日期统计与日额度的切换时间;如修改,请同步 POSTGRES_DSN 中的 TimeZone |
xsirouter-xsi | INIT_USERS、XAI_MAIL | 把 [email protected] 换成你的 root 邮箱,它同时接收平台通知 |
xsirouter-xsi | TRUSTED_PROXY_CIDRS | 受信任的反向代理网段,见《反向代理》 |
xsirouter-xsi | SIGN_ENABLE | 是否开放自助注册,默认 true;开放前请先完成邮件配置 |
xsirouter-mail | EMAIL_SMTP、EMAIL_PORT、EMAIL_TLS、EMAIL_AUTH、EMAIL_PASS | 你的 SMTP 服务;EMAIL_TLS: "true" 对应隐式 TLS(通常为 465 端口) |
xsirouter-pages | BRAND_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-xsi | proxyxai/xsi | 5443 → 3443 | API;停止宽限期 60 秒,文件描述符上限 1048576 |
xsirouter-pages | proxyxai/xsi-pages | 5080 → 8080、5081 → 8081 | 配置管理与账户管理控制台 |
xsirouter-mail | proxyxai/mail | — | 消费 Redis DB 1 的邮件队列并通过 SMTP 投递;停止宽限期 40 秒 |
xsirouter-postgres | postgres:18 | — | 业务数据,命名卷挂载至 /var/lib/postgresql |
xsirouter-redis | redis:alpine | — | 配置、缓存、用量与队列,命名卷挂载至 /data |
xsirouter-postgres-backup | postgres:18 | — | 每日 pg_dump 至 backups/postgres/ |
xsirouter-redis-backup | redis:alpine | — | 每日 RDB 快照至 backups/redis/ |
PostgreSQL 与 Redis 只在 Compose 内部网络中可达,不发布主机端口。
模板为 API 固定设置了以下运行参数,可按需在 docker-compose.yml 中调整:
| 变量 | 模板值 | 说明 |
|---|---|---|
USER_MIN_BALANCE | 2 | 余额低于 1.99 时冻结调用 |
XAI_CREDIT | 0 | 自助注册不赠送额度 |
MODEL_FAILOVER_THRESHOLD | 2 | 模型连续失败 2 次触发分组切换或故障替换 |
EMAIL_SMTP、EMAIL_AUTH、EMAIL_PASS | 空 | API 不设默认 SMTP,由邮件服务统一投递;租户可另配自有 SMTP |
4. 配置 HTTPS 入口
将三个域名解析到反向代理并配置证书:
| 入口 | 对外地址 | 同机转发目标 |
|---|---|---|
| API | https://api.example.com | http://127.0.0.1:5443 |
| 配置管理 | https://admin.example.com | http://127.0.0.1:5080 |
| 账户管理 | https://manage.example.com | http://127.0.0.1:5081 |
API 入口必须支持流式响应与 WebSocket 升级,Nginx 与 Caddy 示例见《反向代理》。控制台英文界面位于各自的 /en/。
5. 接入上游并创建调用账号
- 打开配置管理控制台,使用 root Key(
INIT_USERS中的sk-Xvs...)登录。 - 在“模型服务”中添加上游 Key,填写 Provider、SecretKey 与 Level,例如 OpenAI 放 Level 1、Anthropic 放 Level 2。XSI 会按服务商自动生成
LEVEL_MAPPER。 - 在“系统配置”中核对
LEVEL_MAPPER,按需设置MODEL_MAPPER、SWITCH_OVER等,见《路由与故障转移》。 - 核对 默认价格表,需要时通过租户
PRICING覆盖。 - 在账户管理控制台创建实际调用用的子账号并分配额度,应用使用子账号的 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 端口映射。