VPS 使用 Docker Compose 部署 Sub2API 简洁教程

Sub2API 是一个 AI API 网关平台，用于分发和管理 AI 产品订阅的 API 配额，支持 API Key 管理、计费、负载均衡、请求转发等功能。官方提供 Docker Compose 部署方式，可以一次性部署 Sub2API、PostgreSQL 和 Redis。

一、准备环境

本文以 Ubuntu / Debian VPS 为例，先安装 Docker：

curl -fsSL https://get.docker.com | bash

systemctl enable docker
systemctl start docker

docker --version
docker compose version

官方 Docker Compose 部署要求 Docker 20.10+ 和 Docker Compose v2+。

二、创建部署目录

建议把项目统一放到 /opt/sub2api-deploy：

mkdir -p /opt/sub2api-deploy
cd /opt/sub2api-deploy

三、执行官方 Docker 部署脚本

官方提供了一键 Docker 部署准备脚本，会自动下载 Compose 文件、生成 .env 配置、创建数据目录，并生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 等必要密钥。

执行命令：

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

执行完成后，当前目录下通常会生成：

docker-compose.yml
.env
data/
postgres_data/
redis_data/

其中 .env 中保存了 PostgreSQL 密码和应用密钥。

可以查看：

cat .env

四、启动服务

在部署目录下执行：

docker compose up -d

查看容器状态：

docker compose ps

正常情况下会启动三个主要服务：

sub2api
postgres
redis

Docker Compose 部署方式会包含 PostgreSQL 和 Redis 容器。

五、访问后台

默认访问地址：

http://你的服务器IP:8080

如果服务器开启了防火墙，需要放行 8080 端口：

ufw allow 8080/tcp
ufw reload

云服务器还需要在安全组中放行对应端口。

六、查看管理员密码

如果初始化时自动生成了管理员密码，可以查看 sub2api 日志：

docker compose logs sub2api | grep -i "admin password"

如果日志中没有找到，可以进入网页后按初始化向导创建管理员账号。

七、修改访问端口

如果不想使用默认的 8080 端口，可以修改 .env 或 docker-compose.yml 中的端口配置。

更推荐只修改外部映射端口，例如：

ports:
  - "3008:8080"

含义是：

VPS 的 3008 端口 -> 容器内部的 8080 端口

修改后重新启动：

cd /opt/sub2api-deploy

docker compose down
docker compose up -d

然后访问：

http://你的服务器IP:3008

如果修改的是 PostgreSQL 或 Redis 的端口，一般不建议暴露到公网。数据库和 Redis 只需要在 Docker 内部网络中给 Sub2API 使用即可。

八、常用维护命令

查看日志：

cd /opt/sub2api-deploy
docker compose logs -f sub2api

重启服务：

cd /opt/sub2api-deploy
docker compose restart

停止服务：

cd /opt/sub2api-deploy
docker compose down

更新服务：

cd /opt/sub2api-deploy
docker compose pull
docker compose up -d

查看最终 Compose 配置：

cd /opt/sub2api-deploy
docker compose config

九、Nginx 反向代理注意事项

如果使用 Nginx 反代到 Sub2API，官方文档提醒需要在 http 块中开启：

underscores_in_headers on;

否则像 session_id 这类带下划线的请求头可能被 Nginx 丢弃，影响粘性会话。

简单反代示例：

server {
    listen 80;
    server_name 你的域名;

    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;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

然后重载 Nginx：

nginx -t
systemctl reload nginx

十、完整快速命令汇总

如果只是快速部署，可以直接执行下面这一组命令：

curl -fsSL https://get.docker.com | bash
systemctl enable docker
systemctl start docker

mkdir -p /opt/sub2api-deploy
cd /opt/sub2api-deploy

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

docker compose up -d
docker compose ps
docker compose logs -f sub2api

部署完成后访问：

http://你的服务器IP:8080

如果修改了外部端口，例如改成 3008:8080，则访问：

http://你的服务器IP:3008

总结

Sub2API 的 Docker Compose 部署方式比较适合 VPS 自建使用。官方脚本会自动准备 Compose 文件、环境变量和数据目录，并同时部署 PostgreSQL、Redis 和 Sub2API。实际使用时，建议只开放 Web 访问端口，不要把 PostgreSQL 的 5432 和 Redis 的 6379 暴露到公网，这样整体会更安全。