【无标题】Sub2API 云服务器部署完整教程目录部署前先理解整体架构选择服务器创建服务器后的基础检查配置云服

Sub2API 云服务器部署完整教程

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

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

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. 选择服务器

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

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

只用公网 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 端口，外部浏览器也打不开。

入方向规则建议

协议	端口	来源	用途	注意事项
TCP	22	你的本机公网 IP/32，测试阶段可临时 `0.0.0.0/0`	SSH 登录	长期建议限制为自己的 IP
TCP	80	`0.0.0.0/0`	HTTP 访问后台	本教程测试阶段需要
TCP	443	`0.0.0.0/0`	HTTPS	后续加域名和证书用

不要开放 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 都可以：

ssh root@<你的服务器公网IP>

首次连接输入：

yes

然后输入 root 密码。

6. 初始化 Ubuntu 系统

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

timedatectl set-timezone Asia/Shanghai

apt update && apt upgrade -y

apt install -y curl wget git nano ufw nginx openssl ca-certificates

为什么要做这一步？

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

7. 确认或安装 Docker

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

docker -v
docker compose version
systemctl status docker --no-pager

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

如果没有 Docker，则安装：

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

systemctl enable docker
systemctl start docker

docker -v
docker compose version

为什么用 Docker Compose？

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

8. 下载 Sub2API 部署文件

创建部署目录：

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

执行官方部署脚本：

curl -sSL https://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，后续命令就直接用：

docker compose up -d
docker compose ps

不要机械照搬 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/sub2api

cp docker-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.yml

grep -n "image:" docker-compose.yml

确认能看到：

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

然后拉取镜像：

docker pull ghcr.io/wei-shaw/sub2api:0.1.145

为什么要这样改？

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

10. 配置 `.env`

编辑配置文件：

cd /opt/sub2api
nano .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/sub2api

docker compose up -d

查看状态：

docker compose ps

正常应看到类似：

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 -v http://127.0.0.1:8080/health

正常应看到：

HTTP/1.1 200 OK

注意

不要只用：

curl -I http://127.0.0.1:8080

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

curl -v http://127.0.0.1:8080/health

查看日志：

docker compose logs --tail=150 sub2api

如果看到：

Server started on 0.0.0.0:8080

说明 Sub2API 主服务已经启动。

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

13.1 确认 Nginx 安装

apt install -y nginx
systemctl enable nginx

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

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

手动创建：

mkdir -p /etc/nginx/sites-available
mkdir -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/sub2api
rm -f /etc/nginx/sites-enabled/default

nginx -t
systemctl restart nginx

正常应看到：

syntax is ok
test is successful

13.4 检查 Nginx 是否能访问 Sub2API

curl -I http://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 allow 80/tcp
ufw allow 443/tcp
ufw status

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

检查 Nginx：

nginx -t
systemctl status nginx --no-pager
curl -I http://127.0.0.1

问题 2：Sub2API 容器没有 healthy

查看：

cd /opt/sub2api
docker compose ps
docker compose logs --tail=150 sub2api

常见原因：

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

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

日志里如果看到：

/api/v1/auth/login status_code=401

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

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

cd /opt/sub2api

docker compose exec postgres sh -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/sub2api

docker compose down -v
rm -rf data postgres_data redis_data

docker compose up -d
sleep 30

docker compose ps

再查用户表：

docker compose exec postgres sh -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

错误示例：

docker compose logs --tail=100 sub2api~

报错：

no such service: sub2api~

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

正确命令：

docker compose logs --tail=100 sub2api

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

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

16.1 更换管理员密码

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

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

建议：

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

这样方便：

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

16.3 继续保持 8080 不开放公网

确认：

ss -tulpen | grep 8080

理想结果：

127.0.0.1:8080

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

16.4 收紧 SSH 访问来源

测试阶段可以临时：

22  0.0.0.0/0

正式使用时建议改成：

22  你的固定公网IP/32

17. 常用维护命令

进入部署目录：

cd /opt/sub2api

查看容器：

docker compose ps

查看日志：

docker compose logs -f sub2api

查看最近日志：

docker compose logs --tail=150 sub2api

重启服务：

docker compose restart

停止服务：

docker compose down

启动服务：

docker compose up -d

检查健康接口：

curl -v http://127.0.0.1:8080/health

检查 Nginx：

nginx -t
systemctl status nginx --no-pager
curl -I http://127.0.0.1

查看管理员配置：

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

查看用户表：

cd /opt/sub2api

docker compose exec postgres sh -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/

最终成功标志

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

docker compose ps

输出中三个服务均为 healthy：

sub2api            healthy
sub2api-postgres   healthy
sub2api-redis      healthy

健康检查：

curl -v http://127.0.0.1:8080/health

HTTP/1.1 200 OK

Nginx 检查：

curl -I http://127.0.0.1

HTTP/1.1 200 OK
Server: nginx

浏览器访问：

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

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

【无标题】

Sub2API 云服务器部署完整教程

目录

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

为什么要加 Nginx？

2. 选择服务器

推荐配置

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

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

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

4. 配置云服务器安全组

入方向规则建议

不要开放 8080

5. 连接服务器

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

方法 B：本地 SSH

6. 初始化 Ubuntu 系统

为什么要做这一步？

7. 确认或安装 Docker

为什么用 Docker Compose？

8. 下载 Sub2API 部署文件

注意事项

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

解决思路

为什么要这样改？

10. 配置 .env

每个配置的理由

BIND_HOST=127.0.0.1

SERVER_PORT=8080

TZ=Asia/Shanghai

SERVER_MODE=release

AUTO_SETUP=true

ADMIN_EMAIL / ADMIN_PASSWORD

在 nano 里查找配置

11. 启动 Sub2API

状态解释

12. 检查 Sub2API 是否正常

注意

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

13.1 确认 Nginx 安装

13.2 创建 Nginx 配置

配置理由

13.3 启用配置

13.4 检查 Nginx 是否能访问 Sub2API

14. 浏览器访问后台

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

问题 1：页面打不开

问题 2：Sub2API 容器没有 healthy

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

为什么要 docker compose down -v？

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

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

16.1 更换管理员密码

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

16.3 继续保持 8080 不开放公网

16.4 收紧 SSH 访问来源

17. 常用维护命令

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

中国大陆服务器注意

免费域名注意

19. 参考资料

最终成功标志

10. 配置 `.env`

`BIND_HOST=127.0.0.1`

`SERVER_PORT=8080`

`TZ=Asia/Shanghai`

`SERVER_MODE=release`

`AUTO_SETUP=true`

`ADMIN_EMAIL` / `ADMIN_PASSWORD`

为什么要 `docker compose down -v`？