适用场景云服务器部署 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 容器为什么要加 NginxSub2API 默认 Web 服务在8080端口。生产或团队共享时不建议直接把8080暴露给公网而是让 Nginx 监听公网80/443再转发到本机127.0.0.1:8080。这样做的好处公网只开放标准端口80和443Sub2API 的内部端口不直接暴露以后加域名、HTTPS、Cloudflare、访问日志、限速都更方便Nginx 对流式响应、长连接、反代配置更灵活。2. 选择服务器推荐配置个人或小团队测试CPU2 核 内存4 GB 系统盘40 GB 系统Ubuntu 22.04 LTS / Ubuntu 24.04 LTS 带宽5 Mbps 起步团队共享建议更高团队共享建议CPU2 核起步推荐 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端口外部浏览器也打不开。入方向规则建议协议端口来源用途注意事项TCP22你的本机公网 IP/32测试阶段可临时0.0.0.0/0SSH 登录长期建议限制为自己的 IPTCP800.0.0.0/0HTTP 访问后台本教程测试阶段需要TCP4430.0.0.0/0HTTPS后续加域名和证书用不要开放 8080不要添加TCP 8080 0.0.0.0/0原因Sub2API 的 8080 端口只应给本机 Nginx 访问公网访问走 Nginx 的 80/443直接暴露 8080 会增加攻击面。5. 连接服务器方法 A云厂商 Workbench / Web 终端如果你使用阿里云 Workbench新建连接时一般这样填连接方式终端连接 认证方式密码认证 用户名root 密码你给 ECS 设置或重置的 root 密码登录成功后会看到类似rootyour-server:~#方法 B本地 SSHWindows PowerShell、macOS Terminal 或 Linux Terminal 都可以sshroot你的服务器公网IP首次连接输入yes然后输入 root 密码。6. 初始化 Ubuntu 系统登录服务器后先设置时区、更新系统、安装常用工具timedatectl set-timezone Asia/Shanghaiaptupdateaptupgrade-yaptinstall-ycurlwgetgitnanoufw nginx openssl ca-certificates为什么要做这一步timedatectl让日志时间和你的本地时间一致方便排错apt update apt upgrade更新软件源和系统包curl/wget/git下载脚本和文件nano编辑.env和 Nginx 配置ufw服务器内部防火墙nginx公网反向代理ca-certificates让系统能正常验证 HTTPS 证书。7. 确认或安装 Docker先检查系统是否已经带 Dockerdocker-vdockercompose version systemctl statusdocker--no-pager如果能看到 Docker 版本和active (running)说明 Docker 已经可用。如果没有 Docker则安装curl-fsSLhttps://get.docker.com|bashsystemctlenabledockersystemctl startdockerdocker-vdockercompose version为什么用 Docker ComposeSub2API 需要主程序、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 镜像改成 GHCRcd/opt/sub2apicpdocker-compose.yml docker-compose.yml.bak.$(date%F-%H%M%S)sed-is#weishaw/sub2api:latest#ghcr.io/wei-shaw/sub2api:0.1.145#gdocker-compose.ymlgrep-nimage: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 经常不稳定有些镜像加速源会对部分镜像返回 403GHCR 有时比 Docker Hub 更容易拉取成功固定版本号比latest更可控出问题时也更容易复现。10. 配置.env编辑配置文件cd/opt/sub2apinano.env重点确认这些配置BIND_HOST127.0.0.1 SERVER_PORT8080 TZAsia/Shanghai SERVER_MODErelease AUTO_SETUPtrue ADMIN_EMAILyour_admin_emailexample.com ADMIN_PASSWORDYour_New_Strong_Password每个配置的理由BIND_HOST127.0.0.1让 Sub2API 只监听本机地址由 Nginx 转发访问。这样公网不能直接访问8080安全性更好。SERVER_PORT8080Sub2API 内部服务端口。Nginx 会转发到这个端口。TZAsia/Shanghai日志、任务调度、后台时间更符合中文用户习惯。SERVER_MODErelease生产运行模式避免开发模式下过多调试信息。AUTO_SETUPtrue非常关键。它表示首次启动时自动初始化数据库、执行迁移、创建管理员账号。如果没有这个配置可能出现users 表为空 登录页有但管理员账号不存在 注册功能关闭无法注册 管理员登录一直 401ADMIN_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--tail150sub2api如果看到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-enabled13.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转发到 Sub2APIproxy_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 successful13.4 检查 Nginx 是否能访问 Sub2APIcurl-Ihttp://127.0.0.1正常应看到HTTP/1.1 200 OK Server: nginx14. 浏览器访问后台在浏览器打开http://你的服务器公网IP如果页面能打开说明公网 IP → 安全组 80 端口 → Nginx → 127.0.0.1:8080 → Sub2API这条链路已经成功。登录账号使用.env中的ADMIN_EMAILyour_admin_emailexample.com ADMIN_PASSWORDYour_New_Strong_Password15. 管理员登录成功前的关键排错问题 1页面打不开检查云安全组是否放行TCP 80 0.0.0.0/0检查服务器防火墙ufw allow OpenSSH ufw allow80/tcp ufw allow443/tcp ufw status如果ufw没启用可以先不急着启用。关键是云安全组和 Nginx 正常。检查 Nginxnginx-tsystemctl status nginx --no-pagercurl-Ihttp://127.0.0.1问题 2Sub2API 容器没有 healthy查看cd/opt/sub2apidockercomposepsdockercompose logs--tail150sub2api常见原因镜像没拉下来数据库未启动Redis 未启动.env配置错误数据目录权限或初始化异常。问题 3管理员账号密码看起来正确但登录 401日志里如果看到/api/v1/auth/login status_code401说明后台登录请求到了服务但认证失败。先查数据库里有没有用户cd/opt/sub2apidockercomposeexecpostgressh-lcpsql -U $POSTGRES_USER -d $POSTGRES_DB -c select id,email,role,status,created_at from users;如果显示(0 rows)说明数据库中没有管理员用户。此时登录必然失败注册关闭也正常。解决方法确保.env有AUTO_SETUPtrue ADMIN_EMAILyour_admin_emailexample.com ADMIN_PASSWORDYour_New_Strong_Password然后彻底重建初始化数据cd/opt/sub2apidockercompose down-vrm-rfdata postgres_data redis_datadockercompose up-dsleep30dockercomposeps再查用户表dockercomposeexecpostgressh-lcpsql -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--tail100sub2api~报错no such service: sub2api~原因是服务名后面多了~。正确命令dockercompose logs--tail100sub2api16. 管理员登录成功后的安全建议登录成功后建议立刻做这些事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/3217. 常用维护命令进入部署目录cd/opt/sub2api查看容器dockercomposeps查看日志dockercompose logs-fsub2api查看最近日志dockercompose logs--tail150sub2api重启服务dockercompose restart停止服务dockercompose down启动服务dockercompose up-d检查健康接口curl-vhttp://127.0.0.1:8080/health检查 Nginxnginx-tsystemctl status nginx --no-pagercurl-Ihttp://127.0.0.1查看管理员配置grep-nEAUTO_SETUP|ADMIN_EMAIL|ADMIN_PASSWORD/opt/sub2api/.env查看用户表cd/opt/sub2apidockercomposeexecpostgressh-lcpsql -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.mdSub2API 官方 READMEhttps://github.com/Wei-Shaw/sub2apiDocker 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-scenariosCloudflare 添加域名文档https://developers.cloudflare.com/fundamentals/manage-domains/add-site/最终成功标志当你看到以下结果就说明部署成功dockercomposeps输出中三个服务均为 healthysub2api healthy sub2api-postgres healthy sub2api-redis healthy健康检查curl-vhttp://127.0.0.1:8080/health返回HTTP/1.1 200 OKNginx 检查curl-Ihttp://127.0.0.1返回HTTP/1.1 200 OK Server: nginx浏览器访问http://服务器公网IP可以打开 Sub2API 登录页并用.env中的管理员邮箱和密码成功登录后台。
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 容器为什么要加 NginxSub2API 默认 Web 服务在8080端口。生产或团队共享时不建议直接把8080暴露给公网而是让 Nginx 监听公网80/443再转发到本机127.0.0.1:8080。这样做的好处公网只开放标准端口80和443Sub2API 的内部端口不直接暴露以后加域名、HTTPS、Cloudflare、访问日志、限速都更方便Nginx 对流式响应、长连接、反代配置更灵活。2. 选择服务器推荐配置个人或小团队测试CPU2 核 内存4 GB 系统盘40 GB 系统Ubuntu 22.04 LTS / Ubuntu 24.04 LTS 带宽5 Mbps 起步团队共享建议更高团队共享建议CPU2 核起步推荐 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端口外部浏览器也打不开。入方向规则建议协议端口来源用途注意事项TCP22你的本机公网 IP/32测试阶段可临时0.0.0.0/0SSH 登录长期建议限制为自己的 IPTCP800.0.0.0/0HTTP 访问后台本教程测试阶段需要TCP4430.0.0.0/0HTTPS后续加域名和证书用不要开放 8080不要添加TCP 8080 0.0.0.0/0原因Sub2API 的 8080 端口只应给本机 Nginx 访问公网访问走 Nginx 的 80/443直接暴露 8080 会增加攻击面。5. 连接服务器方法 A云厂商 Workbench / Web 终端如果你使用阿里云 Workbench新建连接时一般这样填连接方式终端连接 认证方式密码认证 用户名root 密码你给 ECS 设置或重置的 root 密码登录成功后会看到类似rootyour-server:~#方法 B本地 SSHWindows PowerShell、macOS Terminal 或 Linux Terminal 都可以sshroot你的服务器公网IP首次连接输入yes然后输入 root 密码。6. 初始化 Ubuntu 系统登录服务器后先设置时区、更新系统、安装常用工具timedatectl set-timezone Asia/Shanghaiaptupdateaptupgrade-yaptinstall-ycurlwgetgitnanoufw nginx openssl ca-certificates为什么要做这一步timedatectl让日志时间和你的本地时间一致方便排错apt update apt upgrade更新软件源和系统包curl/wget/git下载脚本和文件nano编辑.env和 Nginx 配置ufw服务器内部防火墙nginx公网反向代理ca-certificates让系统能正常验证 HTTPS 证书。7. 确认或安装 Docker先检查系统是否已经带 Dockerdocker-vdockercompose version systemctl statusdocker--no-pager如果能看到 Docker 版本和active (running)说明 Docker 已经可用。如果没有 Docker则安装curl-fsSLhttps://get.docker.com|bashsystemctlenabledockersystemctl startdockerdocker-vdockercompose version为什么用 Docker ComposeSub2API 需要主程序、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 镜像改成 GHCRcd/opt/sub2apicpdocker-compose.yml docker-compose.yml.bak.$(date%F-%H%M%S)sed-is#weishaw/sub2api:latest#ghcr.io/wei-shaw/sub2api:0.1.145#gdocker-compose.ymlgrep-nimage: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 经常不稳定有些镜像加速源会对部分镜像返回 403GHCR 有时比 Docker Hub 更容易拉取成功固定版本号比latest更可控出问题时也更容易复现。10. 配置.env编辑配置文件cd/opt/sub2apinano.env重点确认这些配置BIND_HOST127.0.0.1 SERVER_PORT8080 TZAsia/Shanghai SERVER_MODErelease AUTO_SETUPtrue ADMIN_EMAILyour_admin_emailexample.com ADMIN_PASSWORDYour_New_Strong_Password每个配置的理由BIND_HOST127.0.0.1让 Sub2API 只监听本机地址由 Nginx 转发访问。这样公网不能直接访问8080安全性更好。SERVER_PORT8080Sub2API 内部服务端口。Nginx 会转发到这个端口。TZAsia/Shanghai日志、任务调度、后台时间更符合中文用户习惯。SERVER_MODErelease生产运行模式避免开发模式下过多调试信息。AUTO_SETUPtrue非常关键。它表示首次启动时自动初始化数据库、执行迁移、创建管理员账号。如果没有这个配置可能出现users 表为空 登录页有但管理员账号不存在 注册功能关闭无法注册 管理员登录一直 401ADMIN_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--tail150sub2api如果看到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-enabled13.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转发到 Sub2APIproxy_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 successful13.4 检查 Nginx 是否能访问 Sub2APIcurl-Ihttp://127.0.0.1正常应看到HTTP/1.1 200 OK Server: nginx14. 浏览器访问后台在浏览器打开http://你的服务器公网IP如果页面能打开说明公网 IP → 安全组 80 端口 → Nginx → 127.0.0.1:8080 → Sub2API这条链路已经成功。登录账号使用.env中的ADMIN_EMAILyour_admin_emailexample.com ADMIN_PASSWORDYour_New_Strong_Password15. 管理员登录成功前的关键排错问题 1页面打不开检查云安全组是否放行TCP 80 0.0.0.0/0检查服务器防火墙ufw allow OpenSSH ufw allow80/tcp ufw allow443/tcp ufw status如果ufw没启用可以先不急着启用。关键是云安全组和 Nginx 正常。检查 Nginxnginx-tsystemctl status nginx --no-pagercurl-Ihttp://127.0.0.1问题 2Sub2API 容器没有 healthy查看cd/opt/sub2apidockercomposepsdockercompose logs--tail150sub2api常见原因镜像没拉下来数据库未启动Redis 未启动.env配置错误数据目录权限或初始化异常。问题 3管理员账号密码看起来正确但登录 401日志里如果看到/api/v1/auth/login status_code401说明后台登录请求到了服务但认证失败。先查数据库里有没有用户cd/opt/sub2apidockercomposeexecpostgressh-lcpsql -U $POSTGRES_USER -d $POSTGRES_DB -c select id,email,role,status,created_at from users;如果显示(0 rows)说明数据库中没有管理员用户。此时登录必然失败注册关闭也正常。解决方法确保.env有AUTO_SETUPtrue ADMIN_EMAILyour_admin_emailexample.com ADMIN_PASSWORDYour_New_Strong_Password然后彻底重建初始化数据cd/opt/sub2apidockercompose down-vrm-rfdata postgres_data redis_datadockercompose up-dsleep30dockercomposeps再查用户表dockercomposeexecpostgressh-lcpsql -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--tail100sub2api~报错no such service: sub2api~原因是服务名后面多了~。正确命令dockercompose logs--tail100sub2api16. 管理员登录成功后的安全建议登录成功后建议立刻做这些事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/3217. 常用维护命令进入部署目录cd/opt/sub2api查看容器dockercomposeps查看日志dockercompose logs-fsub2api查看最近日志dockercompose logs--tail150sub2api重启服务dockercompose restart停止服务dockercompose down启动服务dockercompose up-d检查健康接口curl-vhttp://127.0.0.1:8080/health检查 Nginxnginx-tsystemctl status nginx --no-pagercurl-Ihttp://127.0.0.1查看管理员配置grep-nEAUTO_SETUP|ADMIN_EMAIL|ADMIN_PASSWORD/opt/sub2api/.env查看用户表cd/opt/sub2apidockercomposeexecpostgressh-lcpsql -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.mdSub2API 官方 READMEhttps://github.com/Wei-Shaw/sub2apiDocker 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-scenariosCloudflare 添加域名文档https://developers.cloudflare.com/fundamentals/manage-domains/add-site/最终成功标志当你看到以下结果就说明部署成功dockercomposeps输出中三个服务均为 healthysub2api healthy sub2api-postgres healthy sub2api-redis healthy健康检查curl-vhttp://127.0.0.1:8080/health返回HTTP/1.1 200 OKNginx 检查curl-Ihttp://127.0.0.1返回HTTP/1.1 200 OK Server: nginx浏览器访问http://服务器公网IP可以打开 Sub2API 登录页并用.env中的管理员邮箱和密码成功登录后台。
