Sub2API 一键部署实战：Docker 部署 AI 网关完整记录

🎯 一句话总结：Sub2API 提供 Docker 一键部署，AUTO_SETUP=true 自动完成数据库初始化、管理员创建和模型价格同步，20 分钟内即可拥有 production-ready 的 AI API 网关。

📌 项目简介

Sub2API 是开源 AI API 网关平台，支持将多个 AI 订阅账号的配额集中管理。本次部署采用 Docker Compose 方案，在一台 Ubuntu 22.04 服务器上完成完整部署。

项目	实际部署值
部署方式	Docker Compose (weishaw/sub2api:latest)
服务器	Ubuntu 22.04 LTS, 4GB RAM, 2 vCPU
服务地址	http://localhost:8080
数据库	PostgreSQL 18-alpine (端口 5432)
缓存	Redis 8-alpine (端口 6379)
启动时间	~ 60 秒（含镜像拉取）
健康状态	✅ 所有容器 `Up (healthy)`

部署规格总结

项目	值
部署日期	2026-04-29
服务地址	http://localhost:8080
管理员	admin@sub2api.local
容器数	3 (sub2api + postgres + redis)
镜像版本	weishaw/sub2api:latest
数据库	PostgreSQL 18-alpine
缓存	Redis 8-alpine
模型价格表	184 个模型（已同步）
API 验证	✅ 登录成功，JWT 返回
健康检查	✅ All containers healthy

⚙️ 部署环境准备

配图	说明
	`docker-compose.yml` - Sub2API 服务定义
	`docker-compose.yml` - PostgreSQL + Redis

系统要求

组件	版本要求	实际环境
Docker	20.10+	29.1.3 ✅
Docker Compose	v2.0+	v5.1.3 ✅
内存	≥ 2GB	4GB ✅
端口	8080 (HTTP)	空闲 ✅
端口	5432 (PostgreSQL)	空闲 ✅
端口	6379 (Redis)	空闲 ✅

端口占用检查（实际执行）

$ ss -tlnp | grep -E ':(80|443|8080|5432|6379)'

LISTEN 0 511 0.0.0.0:443  ... nginx
LISTEN 0 511 0.0.0.0:80   ... nginx
LISTEN 0 2048 0.0.0.0:8082 ... uvicorn
# 8080 / 5432 / 6379 均无占用，可正常使用 ✅

🚀 一键部署（含自动初始化）

自动生成的配置

AUTO_SETUP=true 首次启动后，容器内 /app/data/config.yaml 自动生成：

server:
    host: 0.0.0.0
    port: 8080
    mode: release
database:
    host: postgres
    port: 5432
    user: sub2api
redis:
    host: redis
    port: 6379
jwt:
    secret: f83c2358f4ba206029e899da6099a49e...
    expire_hour: 24

配图	说明
	容器内 `/app/data/config.yaml`

配图	说明
	容器内 `/app/data/config.yaml` (AUTO_SETUP 自动生成)

流程

步骤 1：创建部署目录

$ mkdir -p /opt/sub2api && cd /opt/sub2api

步骤 2：复制官方配置文件

从官方仓库 deploy/ 目录复制配置：

$ cp /tmp/sub2api/deploy/docker-compose.yml .
$ cp /tmp/sub2api/deploy/.env.example .env

docker-compose.yml 核心配置：

services:
  sub2api:
    image: weishaw/sub2api:latest
    restart: unless-stopped
    ports:
      - "0.0.0.0:8080:8080"
    volumes:
      - sub2api_data:/app/data
    environment:
      - AUTO_SETUP=true                    # Docker 自动初始化
      - SERVER_PORT=8080
      - DATABASE_HOST=postgres
      - DATABASE_PORT=5432
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - ADMIN_EMAIL=admin@sub2api.local
      - ADMIN_PASSWORD=***                  # 需手动设置
      - JWT_SECRET=***                      # 需手动设置

  postgres:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: sub2api
      POSTGRES_PASSWORD: ***               # 需与 .env 一致
      POSTGRES_DB: sub2api

  redis:
    image: redis:8-alpine

步骤 3：配置安全凭证

编辑 .env 文件，修改以下关键变量：

# 必须修改的变量
POSTGRES_PASSWORD=change_this_secure_password    # 改为 32 位随机密码
ADMIN_PASSWORD=change_this_admin_password         # 改为 16 位密码
JWT_SECRET=                                         # 留空（自动生成，生产环境需固定）
TOTP_SECRET=                                        # 留空（自动生成，生产环境需固定）
REDIS_PASSWORD=                                     # 本地开发留空

使用随机密码生成器：

$ openssl rand -hex 32  # JWT_SECRET
$ openssl rand -hex 32  # TOTP_SECRET
$ openssl rand -base64 32  # POSTGRES_PASSWORD

步骤 4：启动所有服务

$ docker-compose up -d

实际输出：

✓ Image weishaw/sub2api:latest Pulled
✓ Image postgres:18-alpine Pulled
✓ Image redis:8-alpine Pulled
✓ Network sub2api_sub2api-network Created
✓ Volume sub2api_sub2api_data Created
✓ Container sub2api-redis Started (Healthy)
✓ Container sub2api-postgres Started (Healthy)
✓ Container sub2api Started (Up 24 seconds)

AUTO_SETUP 自动初始化流程

首次启动时 AUTO_SETUP=true 会自动完成：

数据库迁移 — 执行 SQL 初始化脚本
Admin 创建 — 生成管理员账号
配置生成 — 创建 /app/data/config.yaml
价格同步 — 从官方仓库下载 184 个模型价格

完成后容器状态显示 Up (healthy)。

自动生成的配置

配图	说明
	容器内 `/app/data/config.yaml`

✅ 服务验证与安全凭证

容器状态截图

配图	说明
	所有容器健康状态
	日志显示服务正常

默认管理员凭证

字段	值	说明
邮箱	`admin@sub2api.local`	AUTO_SETUP 自动创建
密码	一次性随机密码	查看 `docker logs` 获取
建议	首次登录后修改	防止未授权访问

配图	说明
	所有容器健康状态 (`Up (healthy)`)
	日志显示 CONNECT 200，服务正常

1. Web 界面访问

$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080
200

返回 HTTP 200，且内容为完整的 Vue SPA HTML：

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/png" href="/logo.png" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Sub2API - AI API Gateway</title>
    <script type="module" crossorigin src="/assets/index-Bjh5y-Yy.js"></script>

2. API 登录测试

Endpoint: POST /api/v1/auth/login

请求：

curl -X POST http://127.0.0.1:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@sub2api.local","password":"ad0699061cadb3aa1b2995192ebb749a"}'

响应（200 OK）：

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbG...",
    "refresh_token": "rt_ca4...",
    "expires_in": 86400,
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "email": "admin@sub2api.local",
      "username": "",
      "role": "admin",
      "balance": 0,
      "concurrency": 5,
      "status": "active"
    }
  }
}

✅ 登录成功，获得有效期 24 小时的 JWT Token。

3. 容器健康状态

$ docker ps -a --filter name=sub2api

NAMES              STATUS                    PORTS
sub2api            Up 25 minutes (healthy)   0.0.0.0:8080->8080/tcp
sub2api-postgres   Up 25 minutes (healthy)   0.0.0.0:5432->5432/tcp
sub2api-redis      Up 25 minutes (healthy)   0.0.0.0:6379->6379/tcp

全部 healthy —— PostgreSQL 和 Redis 均通过 Sub2API 内部健康检查。

容器状态截图

配图	说明
	所有容器健康状态
	日志显示服务正常

默认管理员凭证（请修改）

字段	值	说明
邮箱	`admin@sub2api.local`	AUTO_SETUP 自动创建
密码	一次性随机密码	查看 `docker logs` 获取
建议	首次登录后立即修改	防止未授权访问

🔌 Hermes Agent 集成配置

将 Sub2API 作为 Hermes 的 统一 AI 网关 Provider。

Hermes 配置文件

编辑 ~/.hermes/config.yaml：

models:
  - name: "claude-3-7-sonnet"
    provider: "sub2api"
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "sk-sub2api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    priority: 1

  - name: "gpt-4"
    provider: "sub2api"
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "sk-sub2api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    priority: 2

providers:
  sub2api:
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "sk-sub2api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    timeout: 60

调用流程

Hermes Agent (分析任务)
        ↓ 调用 sub2api provider
Sub2API Gateway (http://127.0.0.1:8080)
        ↓ 智能路由（基于 Channel 权重）
上游 Claude / OpenAI / Gemini
        ↓ 返回结果
Hermes Agent (继续执行)

验证集成

# 测试 Sub2API 的 OpenAI 兼容接口
$ curl http://127.0.0.1:8080/v1/models \
  -H "Authorization: Bearer sk-sub2api_xxxxxx"

# 应返回 Sub2API 支持的模型列表（184 个）

🐛 常见问题

Q1：`docker-compose up` 报错 "port already in use"

现象：Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use

解决方案：

# 1. 查找占用端口的进程
$ sudo ss -tlnp | grep 8080

# 2. 停止冲突进程
$ sudo systemctl stop <service-name>

# 3. 或修改 docker-compose.yml 中的端口映射
#    将 "8080:8080" 改为 "8081:8080"

Q2：初始化完成后忘记管理员密码

现象：登录失败，密码不记得。

解决方案：

# 1. 进入 PostgreSQL 容器
$ docker exec -it sub2api-postgres psql -U sub2api -d sub2api

# 2. 重置密码（在 psql 命令行执行）
UPDATE users SET password = '$2a$10$new_hash_here' WHERE email = 'admin@sub2api.local';

# 3. 重新生成 bcrypt hash（在宿主机执行）
$ python3 -c "import bcrypt; print(bcrypt.hashpw(b'new_password', bcrypt.gensalt()).decode())"

Q3：模型价格没有自动下载

现象：启动日志中 Downloading from https://raw.githubusercontent.com/... 失败。

手动触发：

# 进入容器
$ docker exec -it sub2api sh

# 手动运行价格更新
$ /app/sub2api --update-pricing

# 或通过 API 触发
$ curl -X POST http://127.0.0.1:8080/api/v1/admin/pricing/update \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Q4：无法从外部访问（内网可访问，外网不行）

原因：Docker 默认绑定 0.0.0.0 已允许外部访问，但防火墙拦截。

解决：

# Ubuntu 防火墙开放端口
$ sudo ufw allow 8080/tcp
$ sudo ufw reload

# 或使用云平台安全组（腾讯云/阿里云）添加 8080 入站规则

Q5：登录后跳转 404

原因：前端路由配置问题，通常是 server.trusted_proxies 未配置（Nginx 反向代理场景）。

解决：在 config.yaml 中添加：

server:
  trusted_proxies:
    - "192.168.1.0/24"  # 内网段
    - "10.0.0.0/8"

🔄 运维命令与扩展配置

常用 Docker 命令

操作	命令
查看日志	`docker logs -f sub2api`
重启服务	`docker restart sub2api`
进入容器	`docker exec -it sub2api sh`
查看配置	`docker exec sub2api cat /app/data/config.yaml`
备份数据	`docker exec sub2api tar -czf /backup.tar.gz /app/data`

数据持久化

数据存储在 Docker volume sub2api_data 中，独立于容器生命周期。重启容器不会丢失配置和数据库。

Nginx 反向代理（可选）

若需通过域名或 HTTPS 访问，在 Nginx 配置反向代理：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

💎 本站专属福利

RunPod 云 GPU 实例

RunPod 是按秒计费的 GPU 云平台，适合 AI 推理和训练：

💰 成本效益：按秒计费，空闲时可暂停实例
🚀 全球节点：多地区 GPU 可用，低延迟访问
🔧 完全控制：Root 权限，自定义环境配置
📦 模板丰富：支持 Stable Diffusion、LLM 推理镜像

👉 注册 RunPod 享专属优惠

Together AI 模型平台

Together AI 是面向 AI 应用的云服务平台：

🧠 模型 marketplace：数百个开源模型即开即用
💵 透明定价：按 token 计费，无隐藏费用
⚡ 低延迟：全球边缘网络，响应迅速
🔐 企业级：SLA 保证，数据合规

👉 注册 Together AI 开始使用支持

👉 注册 PackyCode 享 10% 折扣

📚 参考资源

官方仓库: https://github.com/Wei-Shaw/sub2api
Docker 部署文档: https://github.com/Wei-Shaw/sub2api/blob/main/deploy/DOCKER.md
配置示例: /opt/sub2api/config.yaml
API 文档: http://localhost:8080/api/docs (部署后访问)
在线 Demo: https://demo.sub2api.org/ (账号: admin@sub2api.org / admin123)
官方仓库: https://github.com/Wei-Shaw/sub2api
Docker 部署文档: https://github.com/Wei-Shaw/sub2api/blob/main/deploy/DOCKER.md
API 文档: http://localhost:8080/api/docs

Sub2API 已成功部署，可开始为 Hermes Agent 提供统一 AI 网关服务！ 🚀

下一步：在 Hermes 配置文件中添加 sub2api Provider，将所有 AI 请求路由至 http://127.0.0.1:8080/v1。

Sub2API 已成功部署，可开始为 Hermes Agent 提供统一 AI 网关服务！ 🚀

📌 项目简介

部署规格总结

⚙️ 部署环境准备

系统要求

端口占用检查（实际执行）

🚀 一键部署（含自动初始化）

自动生成的配置

步骤 1：创建部署目录

步骤 2：复制官方配置文件

步骤 3：配置安全凭证

步骤 4：启动所有服务

AUTO_SETUP 自动初始化流程

自动生成的配置

✅ 服务验证与安全凭证

容器状态截图

默认管理员凭证

1. Web 界面访问

2. API 登录测试

3. 容器健康状态

容器状态截图

默认管理员凭证（请修改）

🔌 Hermes Agent 集成配置

Hermes 配置文件

调用流程

验证集成

🐛 常见问题

Q1：docker-compose up 报错 "port already in use"

Q2：初始化完成后忘记管理员密码

Q3：模型价格没有自动下载

Q4：无法从外部访问（内网可访问，外网不行）

Q5：登录后跳转 404

🔄 运维命令与扩展配置

常用 Docker 命令

数据持久化

Nginx 反向代理（可选）

💎 本站专属福利

RunPod 云 GPU 实例

Together AI 模型平台

📚 参考资源

Related Posts

Q1：`docker-compose up` 报错 "port already in use"