Sub2API 本地部署学习笔记：Docker 构建与启动教程
提示：本文仅用于本地学习、技术研究和自用测试。请使用自己合法拥有、符合相关服务条款的账号、订阅或 API 凭证。部署和使用过程中请遵守平台规则、社区规范及相关法律法规。
本文以 Sub2API 为例，记录如何在 Windows 本地通过 Docker 构建并启动一个测试环境。
一、Sub2API 是什么？
Sub2API 是一个开源项目，可以用于统一管理和接入个人已有的订阅账号或相关凭证，并在本地提供统一的服务入口。
项目地址：
GitHub – Wei-Shaw/sub2api
如果你使用的是上游 API Key，也可以了解 New API 这类项目：
GitHub – QuantumNous/new-api
简单理解：
- New API 更偏向管理 API Key。
- Sub2API 更偏向管理个人已有的订阅账号或相关凭证。
二、准备环境
本教程使用 Windows + Docker Desktop。
需要准备：
- Windows 电脑
- Docker Desktop
- Sub2API 项目源码
- 可正常访问 GitHub 和 Docker 镜像源的网络环境
Docker Desktop 不会安装的，可以参考：
Docker Desktop 下载安装保姆级教程
三、下载并解压项目
1. 下载 Sub2API 压缩包
到 GitHub 下载 Sub2API 项目压缩包。
2. 解压项目
将压缩包解压到你想放的位置。
注意：解压之后通常会有两层文件夹，例如：
sub2api-main\\sub2api-main
3. 确认项目根目录
项目根目录大致如下：
四、进入 deploy 文件夹
后续命令都在 deploy 文件夹下执行。
例如你的项目路径是：
E:\\GitHub\\sub2api-main2\\sub2api-main
那么进入目录的命令就是：
cd /d E:\\GitHub\\sub2api-main2\\sub2api-main\\deploy
如果你的路径不一样，把上面的路径换成你自己的项目路径即可。
五、创建 .env 配置文件
Sub2API 的 Docker 配置需要读取 .env 文件。没有这个文件，启动时可能会提示：
POSTGRES_PASSWORD is required
在 Windows CMD 命令行中执行下面这段命令：
(
echo POSTGRES_USER=sub2api
echo POSTGRES_PASSWORD=sub2api_test_password
echo POSTGRES_DB=sub2api
echo REDIS_PASSWORD=
echo ADMIN_EMAIL=admin@test.local
echo ADMIN_PASSWORD=admin123456
echo JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
echo TOTP_ENCRYPTION_KEY=abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
echo TZ=Asia/Shanghai
echo SERVER_PORT=8090
echo BIND_HOST=127.0.0.1
echo RUN_MODE=standard
echo SERVER_MODE=release
) > .env
说明：
- 这段命令适用于 Windows CMD。
- SERVER_PORT=8090 表示本地访问端口是 8090。
- 如果不是本地测试，请把 ADMIN_PASSWORD、JWT_SECRET、TOTP_ENCRYPTION_KEY 改成更安全的随机值。
六、检查 .env 是否写入成功
输入：
type .env
如果能看到刚才写入的配置，就说明 .env 文件创建成功。 
七、构建并启动 Sub2API
继续在 deploy 文件夹下执行：
docker compose -f docker-compose.dev.yml up -d –build
这个命令会自动完成构建和启动。
第一次执行会比较慢，因为 Docker 需要拉取基础镜像并下载构建依赖。看到较长的构建日志是正常情况，耐心等待即可。 
当终端中出现 Started、Healthy 等提示时，说明服务已经正常启动。
八、查看服务状态
执行：
docker compose -f docker-compose.dev.yml ps
正常情况下可以看到类似状态：
sub2api-dev Started
sub2api-postgres-dev Healthy
sub2api-redis-dev Healthy
如果需要查看运行日志，可以执行：
docker compose -f docker-compose.dev.yml logs -f sub2api
九、访问本地服务
浏览器打开：
http://127.0.0.1:8090
登录信息来自前面 .env 文件：
账号：admin@test.local
密码：admin123456
到这里，Sub2API 的本地 Docker 测试环境就搭建完成了。
十、后台基础配置
进入后台之后，常用的配置模块主要有两个：
1. 分组管理
分组管理可以用于配置不同分组的规则，例如：
- 平台选择
- 倍率设置
- 代理设置
- 路由策略
2. 账号管理
账号管理用于添加自己合法拥有的订阅账号或相关凭证。
添加账号之后，记得给账号选择对应分组。没有选择分组时，账号可能无法正常调用。
十一、常用命令
停止服务
docker compose -f docker-compose.dev.yml down
重新启动
docker compose -f docker-compose.dev.yml up -d
重新构建并启动
docker compose -f docker-compose.dev.yml up -d –build
查看日志
docker compose -f docker-compose.dev.yml logs -f sub2api
删除测试容器和数据卷
docker compose -f docker-compose.dev.yml down -v
如果还想删除本地生成的数据目录，可以手动删除：
data
postgres_data
redis_data
十二、注意事项
十三、总结
完整流程可以概括为：
核心命令：
docker compose -f docker-compose.dev.yml up -d –build
只要 .env 配置正确，Docker 构建完成后就可以在本地访问 Sub2API。
