跳转到内容
SyncTV 文档

排障入口

先判断问题层级

Section titled “先判断问题层级”

不要一开始就翻所有配置项。先把问题归到一个层级，再进入对应页面。

进程没起来

先看配置校验、必填 secret、数据库连接、Redis 依赖和端口占用。

服务起来但访问异常

先看反向代理、CORS、可信代理、Ingress、HTTP/gRPC 协议和端口映射。

登录或账号异常

先看 SMTP、OAuth2 redirect、WebAuthn origin、2FA 可用验证方式和限流。

媒体播放异常

先看 Provider 请求头、Range、slice cache、HLS 存储、RTMP/FLV/STUN 端口。

最短排查路径

Section titled “最短排查路径”

  1. 查看最终配置：

    Terminal window
    synctv --config /etc/synctv/synctv.yaml config show --output yaml

  2. 校验配置：

    Terminal window
    synctv --config /etc/synctv/synctv.yaml config validate

  3. 前台启动并看日志：

    Terminal window
    synctv --config /etc/synctv/synctv.yaml serve

  4. 检查管理端点：

    Terminal window
    synctv system stats

常见现象

Section titled “常见现象”
现象优先检查入口
启动时报 JWT secret、OPAQUE secret 或 credential key 错误secret 是否为空、是否占位值、格式是否正确、是否每次部署重新生成安全与密钥
开启 cluster.enabled=true 后启动失败Redis 是否配置、server.cluster_secret 是否配置、节点是否能互访集群配置
synctv system stats 连不上management.enabled、management.transport、Unix socket 路径、TCP token、SYNCTV_MANAGEMENT_ENDPOINT服务监听与运行时路径
浏览器跨域失败server.cors_allowed_origins 是否是 origin，不能带 path；反向代理是否处理 OPTIONS/HEAD服务监听与运行时路径
gRPC 经 Ingress 失败但 HTTP 正常是否使用独立 gRPC Service/Ingress，Nginx 是否设置 nginx.ingress.kubernetes.io/backend-protocol: "GRPC"Helm 部署
Swagger UI 或 OpenAPI JSON 不存在二进制是否启用 openapi feature，反向代理是否放行 /swagger-ui/ 和 /api-docs/openapi.jsonOpenAPI 文档入口
WebAuthn/passkey 注册或登录失败rp_id 是否为可注册域，rp_origin 是否精确匹配客户端 origin，是否 HTTPSWebAuthn 配置
OAuth2 登录出现 state 或 callback 问题runtime oauth2.providers.*.config.redirect_url、多副本 Redis、客户端 callback URI邮件与 OAuth2
邮件验证码、密码找回或邮箱 2FA 不工作SMTP host、port、TLS、用户名、密码、from_email，邮件限流邮件与 OAuth2
登录、验证码或管理接口被频繁拒绝HTTP/gRPC rate limit、brute-force 保护、客户端重试策略限流与连接限制
Provider 直连可用但代理不可用，或反过来Provider 返回给客户端的 header 与代理上游 header 是否一致，特别是 UA、Referer、Range媒体 Provider
Range 播放、seek 或 HLS byterange 异常Provider 是否提供 Range header、上游是否支持 Range、slice cache 是否启用缓存与代理 slice cache
HLS 多副本播放偶发 404 或不连续publisher 节点是否可达、Pod 间 gRPC 是否通、hls_shared_storage 是否与实际挂载一致；高流量场景是否应改用 file 共享文件系统或 oss直播配置
RTMP 推流或 HTTP-FLV 拉流失败端口暴露、LoadBalancer/NodePort、反向代理超时、FLV 写超时直播配置
STUN/WebRTC 连接失败webrtc.mode、stun_external_addr、UDP 3478 暴露、私网 candidate 过滤WebRTC 配置

配置类问题

Section titled “配置类问题”

配置问题优先用命令确认最终值，不要只看 YAML 文件。环境变量和 CLI 参数可能覆盖 YAML。

Terminal window
synctv --config /etc/synctv/synctv.yaml config show --output yaml
synctv --config /etc/synctv/synctv.yaml config validate

如果最终配置和你预期不一致，按顺序检查：

  • 是否加载了正确的配置文件。
  • .env 是否被加载，或者是否用了 --no-dotenv。
  • 环境变量是否覆盖了 YAML。
  • *_file secret 路径是否相对配置文件目录，而不是 data_dir。
  • data_dir 是否只影响运行时输出路径。

详细规则见 配置文件如何工作。

部署类问题

Section titled “部署类问题”

Docker Compose

Section titled “Docker Compose”

生产 Compose 会要求显式 secret，这是预期行为。不要为了让服务启动而把弱 secret 写入 compose 文件。

Terminal window
export SYNCTV_JWT_SECRET="$(openssl rand -base64 32)"
export SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET="$(openssl rand -base64 48)"
export SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY="$(openssl rand -hex 32)"
export SYNCTV_BOOTSTRAP_ROOT_PASSWORD="replace-with-a-strong-password"
docker compose up -d

更多内容见 Docker Compose 部署。

Helm

Section titled “Helm”

Helm 渲染成功只代表 Kubernetes manifest 语法成立，不代表业务配置安全。生产上线前仍要看启动日志，确认配置校验通过。

重点检查：

  • HTTP 和 gRPC 是否是两个独立 Service。
  • HTTP 和 gRPC 是否是两个独立 Ingress。
  • gRPC Ingress 是否有独立 annotation。
  • metrics ServiceMonitor/VMServiceScrape 是否抓对 Service。
  • 多副本 HLS 是否使用共享存储。
  • existingSecret 是否包含 chart 需要的全部 key。

更多内容见 Helm 部署。

认证与账号问题

Section titled “认证与账号问题”

本地两步验证只在 password、webauthn/passkey、verified email 这些本地验证方式之间生效。OAuth2 不参与本地 2FA，但开启 2FA 的用户仍然可以使用 OAuth2 登录。

如果用户开启 2FA 后登录异常，检查：

  • 用户是否仍有至少两种可用本地验证方式。
  • 邮箱作为第二因素时，SMTP 是否可用。
  • passkey 作为第二因素时，WebAuthn origin 是否正确。
  • 刷新 token 是否来自满足当前 2FA 策略的登录上下文。

相关页面：

需要收集哪些信息

Section titled “需要收集哪些信息”

提交问题或内部排查时，建议收集：

  • SyncTV 版本和部署方式。
  • synctv config show --output yaml 的输出。提交前删除敏感值，即使命令会打码，也要复查。
  • synctv config validate 的完整错误。
  • Compose/Helm 渲染结果中相关 Service、Ingress、ConfigMap 和 Secret key 名称。
  • 服务日志中第一个错误，而不是最后一个级联错误。
  • 触发问题的客户端请求路径、方法、状态码和必要 header。不要提交 token、cookie、密码、SMTP 密码或 provider 凭据。