跳转到内容
SyncTVSyncTV 文档

使用 Docker Compose 安装

此方法使用预构建镜像，在一台服务器、NAS 或虚拟机上运行 SyncTV、PostgreSQL 和 Redis。Kubernetes 环境使用 Helm 部署。

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

前置条件

Section titled “前置条件”
  • Docker Engine 和 Docker Compose v2。
  • 一个长期保留的工作目录，用于保存 Compose 配置、环境文件和数据卷。
  • 一个密码管理器，用于保存生成的 root 密码和长期密钥。

生成环境文件

Section titled “生成环境文件”

生成 Compose 环境文件

填写需要控制的参数。数据库凭据和应用密钥只在当前页面内存中生成，并写入下载的 TAR 压缩包。

部署参数

下载文件

压缩包已经生成，可以下载。

生成器通过 TAR 压缩包提供三个环境文件：

  • .env.synctv：SyncTV 数据库连接、认证密钥和 root 初始化参数。
  • .env.postgres：PostgreSQL 用户、密码和数据库名。
  • .env.redis：Redis AUTH 密码。

“下载 TAR”会生成包含上述三个环境文件的 TAR 压缩包。随机密钥只在当前页面内存中生成，不写入浏览器存储或服务端。

安装

Section titled “安装”

  1. 创建工作目录并下载生产 Compose 配置：

    终端窗口
    mkdir -p synctv && cd synctv
    curl -fsSL https://raw.githubusercontent.com/synctv-org/synctv/main/docker-compose.yml -o docker-compose.yml

  2. 返回“生成环境文件”，下载 synctv-compose-env.tar 并放到当前目录。

  3. 解压环境文件。三个文件名以 . 开头，在 Linux 上属于隐藏文件，使用 ls -a 查看：

    终端窗口
    tar -xf synctv-compose-env.tar
    ls -a

  4. 检查最终 Compose 配置：

    终端窗口
    docker compose -f docker-compose.yml config --quiet

  5. 拉取镜像并在后台启动服务：

    终端窗口
    docker compose -f docker-compose.yml up -d

Compose 固定使用镜像 synctvorg/synctv:latest。发布版本由维护者更新 Compose 文件中的镜像 tag。

验证

Section titled “验证”

查看容器状态，并在 SyncTV 容器内部请求 readiness endpoint：

终端窗口
docker compose -f docker-compose.yml ps
docker compose -f docker-compose.yml exec synctv \
  curl -fsS http://localhost:8081/health/ready

HTTP API 使用 http://localhost:8080。首次启动数据库为空时，root 用户名和密码来自 .env.synctv。

环境文件与版本

Section titled “环境文件与版本”

Docker Compose 通过 env_file 分别加载必需的 .env.postgres、.env.redis 和 .env.synctv：PostgreSQL 读取数据库变量，Redis 读取 REDIS_PASSWORD，SyncTV 读取 SYNCTV_* 应用配置。Compose 文件另外固定将 SYNCTV_DATA_DIR 设置为 /data，让运行数据写入命名卷。重启、换 shell、服务器重启或升级时都应复用同一组环境文件。缺少任一文件时，docker compose config 会直接失败。

生产 Compose 文件固定使用 latest 镜像以及 HTTP 8080、RTMP 1935 宿主机端口。内置 STUN 默认关闭。容器内的健康端口 8081、metrics 端口 9090 不会被默认 Compose 文件映射到宿主机。

数据卷

Section titled “数据卷”

Compose 使用 volume 保存数据：

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

Compose 文件将 SyncTV 的数据目录固定为 /data：

environment:
  SYNCTV_DATA_DIR: /data

这个目录可能包含管理 socket 相关运行时文件、HLS 文件、proxy slice cache 文件和其他运行时输出。

端口

Section titled “端口”

宿主机映射和容器内部监听端口分开管理：

宿主机端口 容器端口 用途
8080 8080 HTTP REST + public gRPC
1935 1935 RTMP
无宿主机映射 8081 liveness/readiness，供容器 healthcheck 使用
无宿主机映射 9090 Prometheus metrics，供容器网络内的 Prometheus 抓取

需要自行提供内置 STUN 时，在 .env.synctv 中设置 SYNCTV_WEBRTC_ENABLE_BUILTIN_STUN=true 和客户端可达的 SYNCTV_WEBRTC_STUN_EXTERNAL_ADDR，并在 SyncTV 服务的 ports 列表中添加 3478:3478/udp。

宿主机端口冲突时，修改 Compose 文件中的宿主机端口映射并重新执行 docker compose config。

备份

Section titled “备份”

备份 PostgreSQL volume、三个环境文件，以及启用了持久化 HLS 或 proxy slice cache 时的 /data。以下值需要长期保存：

环境变量 用途
SYNCTV_JWT_SECRET 签发 access token、refresh token 和 guest token
SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET OPAQUE 密码认证的服务端长期 secret
SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY 加密 Provider 凭据
SYNCTV_SECURITY_EMAIL_OUTBOX_ENCRYPTION_KEY 加密 PostgreSQL 中的待发邮件载荷
SYNCTV_BOOTSTRAP_ROOT_PASSWORD 首次创建 root 用户

Redis 保存缓存和共享状态。恢复或清空 Redis 会影响 OAuth2 state、token blacklist、限流计数器等短期状态。

常见失败

Section titled “常见失败”
现象 处理
docker compose config 提示变量或文件缺失 确认三个环境文件和 docker-compose.yml 位于同一目录。
/health/ready 失败 查看 docker compose logs synctv，检查第一条启动错误。
root 用户无法登录 确认首次启动数据库前已经设置 root 密码，并检查 bootstrap 日志。
宿主机端口冲突 修改 Compose 文件中的宿主机端口，然后重新执行 docker compose config。
Prometheus 无法抓取 metrics 将 Prometheus 放入同一 Docker 网络，或为受信任的采集器显式增加 9090 映射。

上线前

Section titled “上线前”