Docker Compose 部署
Docker Compose 是新部署的首选方式。官方脚本使用本地目录保存应用、PostgreSQL 和 Redis 数据，便于备份与迁移。
一键准备
bash
mkdir -p sub2api-deploy
cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash脚本会：
- 把
docker-compose.local.yml下载为当前目录的docker-compose.yml。 - 下载
.env.example并生成.env。 - 自动生成
POSTGRES_PASSWORD、JWT_SECRET和TOTP_ENCRYPTION_KEY。 - 创建
data/、postgres_data/和redis_data/。
记录脚本最后输出的密钥，然后启动服务：
bash
docker compose up -d
docker compose ps
docker compose logs -f sub2api默认访问地址为 http://服务器IP:8080。
如果没有显式设置管理员密码，首次启动生成的密码会写入日志：
bash
docker compose logs sub2api | grep "admin password"手动部署
适合希望逐项检查配置的人：
bash
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
cp .env.example .env
mkdir -p data postgres_data redis_data生成密钥：
bash
openssl rand -hex 32 # POSTGRES_PASSWORD
openssl rand -hex 32 # JWT_SECRET
openssl rand -hex 32 # TOTP_ENCRYPTION_KEY编辑 .env，至少设置：
dotenv
POSTGRES_PASSWORD=替换为随机密码
JWT_SECRET=替换为固定的64位十六进制字符串
TOTP_ENCRYPTION_KEY=替换为固定的64位十六进制字符串
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=替换为管理员强密码
SERVER_PORT=8080
TZ=Asia/Shanghai启动本地目录版：
bash
docker compose -f docker-compose.local.yml up -d
docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs -f sub2api两种存储方式
| Compose 文件 | 数据位置 | 推荐场景 |
|---|---|---|
docker-compose.local.yml | ./data、./postgres_data、./redis_data | 生产、备份、迁移 |
docker-compose.yml | Docker named volumes | 快速试用、无需直接管理文件 |
不要混用命令
同一套部署要始终使用同一个 Compose 文件。先用 -f docker-compose.local.yml 启动，之后却执行不带 -f 的 docker compose down，操作的可能是另一套项目定义。
自动初始化
Compose 配置通过 AUTO_SETUP=true 启用自动初始化。第一次启动时，应用会：
- 连接 PostgreSQL 和 Redis。
- 执行未应用的数据库迁移。
- 创建管理员账号。
- 生成运行配置并启动服务。
数据库密码错误、目录权限异常或数据库迁移失败时，应用容器会反复重启。优先查看 docker compose logs sub2api，不要重复删除数据目录。
常用命令
下面以脚本生成的 docker-compose.yml 为例：
bash
# 状态
docker compose ps
# 应用日志
docker compose logs -f --tail=200 sub2api
# 重启应用，不重启数据库
docker compose restart sub2api
# 停止整套服务，保留数据
docker compose down
# 拉取新镜像并重建
docker compose pull
docker compose up -d使用外部 PostgreSQL 和 Redis
仓库提供 docker-compose.standalone.yml，只运行应用容器：
bash
cp .env.example .env
nano .env
docker compose -f docker-compose.standalone.yml up -d需要在 .env 中提供：
dotenv
DATABASE_HOST=db.internal
DATABASE_PORT=5432
DATABASE_USER=sub2api
DATABASE_PASSWORD=数据库密码
DATABASE_DBNAME=sub2api
DATABASE_SSLMODE=require
REDIS_HOST=redis.internal
REDIS_PORT=6379
REDIS_PASSWORD=Redis密码
REDIS_ENABLE_TLS=true确保容器能解析并访问这些内网地址。托管数据库的 CA、SSL 模式和连接数限制应按服务商要求配置。
自定义配置文件
多数配置可以通过环境变量设置。如果需要完整 YAML 配置：
bash
cp config.example.yaml config.yaml然后在 Compose 的 sub2api.volumes 中挂载：
yaml
volumes:
- ./data:/app/data
- ./config.yaml:/app/data/config.yaml:ro修改后重建应用容器：
bash
docker compose up -d --force-recreate sub2api下一步
不要直接把 8080 裸露为正式入口。继续配置反向代理与 HTTPS，然后逐项完成生产环境检查表。