跳转到内容
SyncTV SyncTV 文档

Docker Compose 部署

生产 Compose

Section titled “生产 Compose”

单机部署优先使用 docker-compose.yml。它使用预构建镜像、显式生产 secret、持久化 env 文件和数据卷，适合一台服务器或本机长期运行。

开发 Compose 只用于改代码或临时本地试用。它会从本地 Dockerfile 构建镜像，并内置仅供本地使用的开发配置；不要复用于生产。

还没有确定部署方式时，先读 部署路径选择。

Compose 文件区别

Section titled “Compose 文件区别”
文件用途特点
docker-compose.yml预构建镜像部署使用 zijiren/synctv:latest，需要显式提供生产 secret
docker-compose.dev.yml本地开发从本地 Dockerfile 构建，内置仅供本地使用的开发配置

获取生产 Compose 文件

Section titled “获取生产 Compose 文件”

在空目录下载单机生产部署所需的最少文件：

运行初始化脚本前，确认主机已安装 Docker Compose、openssl 和 python3。脚本使用 openssl 生成 PostgreSQL、Redis、JWT、cluster、credential-encryption 和 OPAQUE secret，并用 python3 安全地 URL-encode 数据库密码。

Terminal window
mkdir synctv-compose
cd synctv-compose
curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/.env.postgres.example
curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/.env.redis.example
curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/.env.synctv.example
mkdir -p scripts
curl -fsSL https://raw.githubusercontent.com/zijiren233/synctv/next/scripts/init-compose-env.sh -o scripts/init-compose-env.sh
chmod +x scripts/init-compose-env.sh

文件也可以从源码仓库页面查看：源码仓库。开发 Compose 文件地址是 docker-compose.dev.yml。

生产 Compose 启动

Section titled “生产 Compose 启动”

首次启动前生成持久化环境文件：

Terminal window
./scripts/init-compose-env.sh

编辑 .env.synctv，至少设置：

SYNCTV_BOOTSTRAP_ROOT_PASSWORD=replace-with-a-strong-password
# 如果前端和 API 不同 origin，使用 JSON 数组。
SYNCTV_SERVER_CORS_ALLOWED_ORIGINS=["https://app.example.com"]

然后启动：

Terminal window
docker compose config
docker compose up -d

启动成功后立即验证：

Terminal window
docker compose ps
curl -fsS http://localhost:8080/health/ready

浏览器打开 http://localhost:8080。默认 root 用户名是 root，密码来自 .env.synctv 里的 SYNCTV_BOOTSTRAP_ROOT_PASSWORD。

Docker Compose 会通过 env_file 分别加载必需的 .env.postgres、.env.redis 和 .env.synctv：PostgreSQL 只读取数据库变量，Redis 只读取 REDIS_PASSWORD，synctv 只读取 SYNCTV_* 应用配置。初始化脚本会把同一个 Redis 密码写入 .env.redis 的 REDIS_PASSWORD，并写入 .env.synctv 中带认证信息的 SYNCTV_REDIS_URL。请备份这三个文件；重启、换 shell、服务器重启或升级时都应复用同一组环境文件。缺少任一文件时，docker compose config 会直接失败。

升级镜像时，在运行 Compose 前将 SYNCTV_IMAGE_TAG 设置为目标发布版本，或在自己的 Compose 覆盖文件中指定镜像版本。示例 Compose 文件默认使用文档对应的应用版本而不是 latest，以保证部署可复现。

开发 Compose

Section titled “开发 Compose”

开发 Compose 依赖仓库中的 Dockerfile 和源码。只有需要本地构建或改代码时，才先获取完整仓库：

Terminal window
git clone https://github.com/zijiren233/synctv.git synctv
cd synctv

启动：

Terminal window
docker compose -f docker-compose.dev.yml up -d

这个文件会启动：

  • PostgreSQL 18
  • Redis 8
  • SyncTV 本地构建镜像

它内置仅供本地开发使用的凭据和配置，完整源码仓库可以直接启动，不需要先生成 env 文件。

数据卷

Section titled “数据卷”

Compose 使用 volume 保存数据：

  • PostgreSQL 数据。
  • Redis 数据。
  • SyncTV /data 运行时目录。

/data 对应：

Terminal window
SYNCTV_DATA_DIR=/data

这个目录可能包含：

  • 管理 socket 相关运行时文件。
  • HLS 文件。
  • proxy slice cache 文件。
  • 其他运行时输出。

端口

Section titled “端口”

默认暴露：

宿主端口容器端口用途
80808080HTTP REST + gRPC + 健康检查
19351935RTMP
3478/udp3478/udpSTUN

如果宿主机端口冲突，可以修改 Compose ports。

健康检查

Section titled “健康检查”

Compose 使用：

http://localhost:8080/health/ready

如果健康检查失败，先看日志：

Terminal window
docker compose logs -f synctv

故障与边界

Section titled “故障与边界”

生产 Compose 为什么要求显式 secret？

Section titled “生产 Compose 为什么要求显式 secret？”

因为这些值如果自动用默认弱值，服务可能看起来能跑，但安全性不可接受。

我改了 SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET 后用户不能登录？

Section titled “我改了 SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET 后用户不能登录？”

这是预期风险。这个 secret 必须长期稳定。不要在每次部署时重新生成。

需要备份什么？

Section titled “需要备份什么？”

至少备份：

  • PostgreSQL volume。
  • 生产 secret。
  • 如果启用了持久化 slice cache 或 HLS 文件，也按需求备份 /data。

Redis 通常是缓存和共享状态，但如果你依赖 token blacklist、OAuth2 state 等短期状态，重启影响也要考虑。