Sub2API 云服务器部署完整教程

适用场景：云服务器部署 Sub2API，先通过公网 IP 测试访问，后续可再接入域名、Cloudflare 和 HTTPS。
本文以Ubuntu 22.04 64 位 + 2 核 4G 云服务器 + Docker Compose + Nginx 反向代理为例。
目标结果：浏览器可打开http://<服务器公网IP>，并使用管理员账号成功登录 Sub2API 后台。

目录

1. 部署前先理解整体架构
2. 选择服务器
3. 创建服务器后的基础检查
4. 配置云服务器安全组
5. 连接服务器
6. 初始化 Ubuntu 系统
7. 确认或安装 Docker
8. 下载 Sub2API 部署文件
9. 处理国内服务器拉镜像失败的问题
10. 配置.env
11. 启动 Sub2API
12. 检查 Sub2API 是否正常
13. 安装并配置 Nginx 反向代理
14. 浏览器访问后台
15. 管理员登录成功前的关键排错
16. 管理员登录成功后的安全建议
17. 常用维护命令
18. 后续接入域名与 Cloudflare 的建议
19. 参考资料

1. 部署前先理解整体架构

本教程采用下面的访问链路：

浏览器 / 团队成员 / API 客户端 ↓ http://服务器公网IP ↓ Nginx 监听 80 端口 ↓ 127.0.0.1:8080 ↓ Sub2API 容器 ↓ PostgreSQL 容器 + Redis 容器

为什么要加 Nginx？

Sub2API 默认 Web 服务在8080端口。生产或团队共享时，不建议直接把8080暴露给公网，而是让 Nginx 监听公网80/443，再转发到本机127.0.0.1:8080。

这样做的好处：

• 公网只开放标准端口80和443；
• Sub2API 的内部端口不直接暴露；
• 以后加域名、HTTPS、Cloudflare、访问日志、限速都更方便；
• Nginx 对流式响应、长连接、反代配置更灵活。

2. 选择服务器

推荐配置

个人或小团队测试：

CPU：2 核 内存：4 GB 系统盘：40 GB 系统：Ubuntu 22.04 LTS / Ubuntu 24.04 LTS 带宽：5 Mbps 起步，团队共享建议更高

团队共享建议：

CPU：2 核起步，推荐 4 核 内存：4 GB 起步，推荐 8 GB 系统盘：40 GB 起步 地区：海外、香港、日本、新加坡更适合长期接入外部 AI 服务

中国大陆服务器的注意事项

如果服务器在中国大陆，例如北京、上海、杭州等区域：

• 只用公网 IP 测试通常可以先跑通；
• 如果后续要用域名正式提供 Web 服务，通常会涉及 ICP 备案；
• 免费域名一般不适合大陆备案；
• 如果目标是“免费域名 + Cloudflare + 免备案”，通常建议选香港、日本、新加坡、美国等大陆以外地区。

为什么本教程先用公网 IP？

因为公网 IP 测试最简单，可以先验证：

• Docker 是否正常；
• Sub2API 是否能启动；
• PostgreSQL / Redis 是否健康；
• Nginx 反向代理是否成功；
• 管理员登录是否成功。

等系统跑通后，再加域名和 HTTPS，排错会简单很多。

3. 创建服务器后的基础检查

服务器创建后，在云厂商控制台确认以下信息：

系统：Ubuntu 22.04 64 位 公网 IP：<你的服务器公网IP> CPU / 内存：例如 2 核 4 GB 状态：运行中

如果是阿里云 ECS，可以在实例详情页看到：

• 公网 IP；
• 私网 IP；
• 操作系统；
• 安全组；
• 远程连接入口。

4. 配置云服务器安全组

安全组是云服务器外层防火墙。即使服务器里 Nginx 正常运行，如果安全组没放行80端口，外部浏览器也打不开。

入方向规则建议

不要开放 8080

不要添加：

TCP 8080 0.0.0.0/0

原因：

• Sub2API 的 8080 端口只应给本机 Nginx 访问；
• 公网访问走 Nginx 的 80/443；
• 直接暴露 8080 会增加攻击面。

5. 连接服务器

方法 A：云厂商 Workbench / Web 终端

如果你使用阿里云 Workbench，新建连接时一般这样填：

连接方式：终端连接 认证方式：密码认证 用户名：root 密码：你给 ECS 设置或重置的 root 密码

登录成功后，会看到类似：

root@your-server:~#

方法 B：本地 SSH

Windows PowerShell、macOS Terminal 或 Linux Terminal 都可以：

sshroot@<你的服务器公网IP>

首次连接输入：

yes

然后输入 root 密码。

6. 初始化 Ubuntu 系统

登录服务器后，先设置时区、更新系统、安装常用工具：

timedatectl set-timezone Asia/Shanghaiaptupdate&&aptupgrade-yaptinstall-ycurlwgetgitnanoufw nginx openssl ca-certificates

为什么要做这一步？

• timedatectl：让日志时间和你的本地时间一致，方便排错；
• apt update && apt upgrade：更新软件源和系统包；
• curl/wget/git：下载脚本和文件；
• nano：编辑.env和 Nginx 配置；
• ufw：服务器内部防火墙；
• nginx：公网反向代理；
• ca-certificates：让系统能正常验证 HTTPS 证书。

7. 确认或安装 Docker

先检查系统是否已经带 Docker：

docker-vdockercompose version systemctl statusdocker--no-pager

如果能看到 Docker 版本和active (running)，说明 Docker 已经可用。

如果没有 Docker，则安装：

curl-fsSLhttps://get.docker.com|bashsystemctlenabledockersystemctl startdockerdocker-vdockercompose version

为什么用 Docker Compose？

Sub2API 需要主程序、PostgreSQL、Redis 多个服务。Docker Compose 可以用一个配置文件同时启动这些容器，便于维护、重启和迁移。

8. 下载 Sub2API 部署文件

创建部署目录：

mkdir-p/opt/sub2apicd/opt/sub2api

执行官方部署脚本：

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

执行完成后，你通常会看到类似目录结构：

docker-compose.yml - Docker Compose configuration .env - Environment variables data/ - Application data postgres_data/ - PostgreSQL data redis_data/ - Redis data

注意事项

不同版本可能生成：

docker-compose.yml

也可能文档里提到：

docker-compose.local.yml

你的实际目录里如果是docker-compose.yml，后续命令就直接用：

dockercompose up-ddockercomposeps

不要机械照搬docker-compose.local.yml。

9. 处理国内服务器拉镜像失败的问题

在中国大陆服务器上，直接拉 Docker Hub 可能失败，例如：

failed to resolve reference "docker.io/weishaw/sub2api:latest" i/o timeout

或者镜像加速源返回：

403 Forbidden

解决思路

优先把 Sub2API 镜像改成 GHCR：

cd/opt/sub2apicpdocker-compose.yml docker-compose.yml.bak.$(date+%F-%H%M%S)sed-i's#weishaw/sub2api:latest#ghcr.io/wei-shaw/sub2api:0.1.145#g'docker-compose.ymlgrep-n"image:"docker-compose.yml

确认能看到：

image: ghcr.io/wei-shaw/sub2api:0.1.145 image: postgres:18-alpine image: redis:8-alpine

然后拉取镜像：

dockerpull ghcr.io/wei-shaw/sub2api:0.1.145

为什么要这样改？

• 国内服务器访问 Docker Hub 经常不稳定；
• 有些镜像加速源会对部分镜像返回 403；
• GHCR 有时比 Docker Hub 更容易拉取成功；
• 固定版本号比latest更可控，出问题时也更容易复现。

10. 配置.env

编辑配置文件：

cd/opt/sub2apinano.env

重点确认这些配置：

BIND_HOST=127.0.0.1 SERVER_PORT=8080 TZ=Asia/Shanghai SERVER_MODE=release AUTO_SETUP=true ADMIN_EMAIL=your_admin_email@example.com ADMIN_PASSWORD=Your_New_Strong_Password

每个配置的理由

BIND_HOST=127.0.0.1

让 Sub2API 只监听本机地址，由 Nginx 转发访问。

这样公网不能直接访问8080，安全性更好。

SERVER_PORT=8080

Sub2API 内部服务端口。Nginx 会转发到这个端口。

TZ=Asia/Shanghai

日志、任务调度、后台时间更符合中文用户习惯。

SERVER_MODE=release

生产运行模式，避免开发模式下过多调试信息。

AUTO_SETUP=true

非常关键。它表示首次启动时自动初始化数据库、执行迁移、创建管理员账号。

如果没有这个配置，可能出现：

users 表为空 登录页有，但管理员账号不存在 注册功能关闭，无法注册 管理员登录一直 401

ADMIN_EMAIL/ADMIN_PASSWORD

管理员登录账号和密码。

建议：

• 使用真实可控邮箱；
• 密码不要截图、不要发给别人；
• 密码尽量不要用过于复杂的 shell 特殊字符开头，避免复制或解析出错；
• 如果密码曾经暴露，立刻换新。

保存退出：

Ctrl + O Enter Ctrl + X

在 nano 里查找配置

如果文件很长，按：

Ctrl + W

输入：

ADMIN_EMAIL

回车即可跳转。

11. 启动 Sub2API

执行：

cd/opt/sub2apidockercompose up-d

查看状态：

dockercomposeps

正常应看到类似：

NAME IMAGE SERVICE STATUS sub2api ghcr.io/wei-shaw/sub2api:0.1.145 sub2api Up ... healthy sub2api-postgres postgres:18-alpine postgres Up ... healthy sub2api-redis redis:8-alpine redis Up ... healthy

状态解释

• healthy：健康检查通过；
• starting：刚启动，等待一会儿再看；
• exited：容器退出，需要看日志；
• unhealthy：服务启动了但健康检查没过，需要排查配置或日志。

12. 检查 Sub2API 是否正常

先本机检查健康接口：

curl-vhttp://127.0.0.1:8080/health

正常应看到：

HTTP/1.1 200 OK

注意

不要只用：

curl-Ihttp://127.0.0.1:8080

因为有些服务对HEAD请求响应不完整，可能出现连接 reset，但GET /health正常。优先用：

curl-vhttp://127.0.0.1:8080/health

查看日志：

dockercompose logs--tail=150sub2api

如果看到：

Server started on 0.0.0.0:8080

说明 Sub2API 主服务已经启动。

13. 安装并配置 Nginx 反向代理

13.1 确认 Nginx 安装

aptinstall-ynginx systemctlenablenginx

如果遇到目录不存在，例如：

/etc/nginx/sites-available/sub2api: No such file or directory

手动创建：

mkdir-p/etc/nginx/sites-availablemkdir-p/etc/nginx/sites-enabled

13.2 创建 Nginx 配置

nano/etc/nginx/sites-available/sub2api

写入：

server { listen 80; server_name _; client_max_body_size 256m; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; 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_buffering off; proxy_cache off; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }

保存退出。

配置理由

• listen 80：公网 HTTP 入口；
• server_name _：没有域名时也能接收 IP 访问；
• proxy_pass http://127.0.0.1:8080：转发到 Sub2API；
• proxy_buffering off：对流式输出更友好；
• proxy_read_timeout 3600s：减少长请求被 Nginx 提前断开；
• client_max_body_size 256m：允许较大的请求体。

13.3 启用配置

ln-sf/etc/nginx/sites-available/sub2api /etc/nginx/sites-enabled/sub2apirm-f/etc/nginx/sites-enabled/default nginx-tsystemctl restart nginx

正常应看到：

syntax is ok test is successful

13.4 检查 Nginx 是否能访问 Sub2API

curl-Ihttp://127.0.0.1

正常应看到：

HTTP/1.1 200 OK Server: nginx

14. 浏览器访问后台

在浏览器打开：

http://<你的服务器公网IP>

如果页面能打开，说明：

公网 IP → 安全组 80 端口 → Nginx → 127.0.0.1:8080 → Sub2API

这条链路已经成功。

登录账号使用.env中的：

ADMIN_EMAIL=your_admin_email@example.com ADMIN_PASSWORD=Your_New_Strong_Password

15. 管理员登录成功前的关键排错

问题 1：页面打不开

检查云安全组是否放行：

TCP 80 0.0.0.0/0

检查服务器防火墙：

ufw allow OpenSSH ufw allow80/tcp ufw allow443/tcp ufw status

如果ufw没启用，可以先不急着启用。关键是云安全组和 Nginx 正常。

检查 Nginx：

nginx-tsystemctl status nginx --no-pagercurl-Ihttp://127.0.0.1

问题 2：Sub2API 容器没有 healthy

查看：

cd/opt/sub2apidockercomposepsdockercompose logs--tail=150sub2api

常见原因：

• 镜像没拉下来；
• 数据库未启动；
• Redis 未启动；
• .env配置错误；
• 数据目录权限或初始化异常。

问题 3：管理员账号密码看起来正确，但登录 401

日志里如果看到：

/api/v1/auth/login status_code=401

说明后台登录请求到了服务，但认证失败。

先查数据库里有没有用户：

cd/opt/sub2apidockercomposeexecpostgressh-lc'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select id,email,role,status,created_at from users;"'

如果显示：

(0 rows)

说明数据库中没有管理员用户。此时登录必然失败，注册关闭也正常。

解决方法：确保.env有：

AUTO_SETUP=true ADMIN_EMAIL=your_admin_email@example.com ADMIN_PASSWORD=Your_New_Strong_Password

然后彻底重建初始化数据：

cd/opt/sub2apidockercompose down-vrm-rfdata postgres_data redis_datadockercompose up-dsleep30dockercomposeps

再查用户表：

dockercomposeexecpostgressh-lc'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select id,email,role,status,created_at from users;"'

这次应能看到管理员邮箱。

为什么要docker compose down -v？

如果使用的是 Docker Compose 的 named volumes，单纯删除目录不一定能清掉数据库卷。down -v会同时删除 Compose 创建的 volumes，适合刚部署、没有正式数据时重置初始化。

注意：这会删除数据库。正式使用后不要随便执行。

问题 4：执行日志命令时提示 no such service

错误示例：

dockercompose logs--tail=100sub2api~

报错：

no such service: sub2api~

原因是服务名后面多了~。

正确命令：

dockercompose logs--tail=100sub2api

16. 管理员登录成功后的安全建议

登录成功后，建议立刻做这些事：

16.1 更换管理员密码

如果密码曾经被截图、发给别人、出现在聊天记录里，必须换掉。

16.2 不要让团队共用管理员账号

建议：

管理员账号：只给你自己 团队成员：每人一个普通用户 API Key：每人一个或每个项目一个 额度：按人/项目设置

这样方便：

• 统计谁用了多少；
• 单独限制额度；
• 某个 Key 泄露时只停一个 Key；
• 排查失败请求。

16.3 继续保持 8080 不开放公网

确认：

ss-tulpen|grep8080

理想结果：

127.0.0.1:8080

不要让云安全组开放8080/8080。

16.4 收紧 SSH 访问来源

测试阶段可以临时：

22 0.0.0.0/0

正式使用时建议改成：

22 你的固定公网IP/32

17. 常用维护命令

进入部署目录：

cd/opt/sub2api

查看容器：

dockercomposeps

查看日志：

dockercompose logs-fsub2api

查看最近日志：

dockercompose logs--tail=150sub2api

重启服务：

dockercompose restart

停止服务：

dockercompose down

启动服务：

dockercompose up-d

检查健康接口：

curl-vhttp://127.0.0.1:8080/health

检查 Nginx：

nginx-tsystemctl status nginx --no-pagercurl-Ihttp://127.0.0.1

查看管理员配置：

grep-nE"AUTO_SETUP|ADMIN_EMAIL|ADMIN_PASSWORD"/opt/sub2api/.env

查看用户表：

cd/opt/sub2apidockercomposeexecpostgressh-lc'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select id,email,role,status,created_at from users;"'

18. 后续接入域名与 Cloudflare 的建议

当前教程先用：

http://<服务器公网IP>

后续可以升级为：

https://api.example.com

推荐链路：

用户 ↓ Cloudflare DNS / 代理 ↓ Nginx 443 HTTPS ↓ 127.0.0.1:8080 ↓ Sub2API

中国大陆服务器注意

如果域名解析到中国大陆服务器并启用 Web 服务，通常需要 ICP 备案。若想使用免费域名、Cloudflare 并尽量减少备案流程，建议长期迁移到香港、日本、新加坡或美国等非中国大陆地区服务器。

免费域名注意

免费域名必须满足：

• 你能控制 DNS；
• 最好能改 nameserver；
• 能添加 A 记录指向服务器 IP；
• 域名服务商稳定可靠。

Cloudflare Free / Pro 的常见完整接入方式是：添加域名、检查 DNS 记录、修改 nameserver、完成 SSL/TLS 设置。

19. 参考资料

• Sub2API 官方部署文档：https://github.com/Wei-Shaw/sub2api/blob/main/deploy/README.md
• Sub2API 官方 README：https://github.com/Wei-Shaw/sub2api
• Docker Compose volumes 文档：https://docs.docker.com/reference/compose-file/volumes/
• Ubuntu UFW 手册：https://manpages.ubuntu.com/manpages/focal/man8/ufw.8.html
• 阿里云 ECS 安全组文档：https://www.alibabacloud.com/help/en/ecs/user-guide/security-group-rules
• 阿里云 ICP 备案场景说明：https://www.alibabacloud.com/help/en/icp-filing/basic-icp-service/product-overview/faq-about-icp-filing-applications-in-different-scenarios
• Cloudflare 添加域名文档：https://developers.cloudflare.com/fundamentals/manage-domains/add-site/

最终成功标志

当你看到以下结果，就说明部署成功：

dockercomposeps

输出中三个服务均为 healthy：

sub2api healthy sub2api-postgres healthy sub2api-redis healthy

健康检查：

curl-vhttp://127.0.0.1:8080/health

返回：

HTTP/1.1 200 OK

Nginx 检查：

curl-Ihttp://127.0.0.1

返回：

HTTP/1.1 200 OK Server: nginx

浏览器访问：

http://<服务器公网IP>

可以打开 Sub2API 登录页，并用.env中的管理员邮箱和密码成功登录后台。