跳转到内容
SyncTV SyncTV 文档

排障入口

先跑这些命令

Section titled “先跑这些命令”
Terminal window
synctv --config /etc/synctv/synctv.yaml config show --output yaml
synctv --config /etc/synctv/synctv.yaml config validate
synctv --config /etc/synctv/synctv.yaml serve

排障时优先看第一条错误。后续错误经常只是依赖失败后的级联结果。

错误文本速查

Section titled “错误文本速查”
现象或错误原因处理
jwt.secret 是占位值或太弱生产仍使用示例 secret生成强 secret，并通过 secret/env 注入
opaque_server_setup_secret 为空或无效OPAQUE 长期 secret 未配置生成并长期保存 security.opaque_server_setup_secret
credential_encryption_key 格式错误不是 64 个十六进制字符用 openssl rand -hex 32 生成
required variable ... is missing生产 Compose 缺 .env.postgres、.env.redis 或 .env.synctv运行 ./scripts/init-compose-env.sh
/health/ready 不是 200数据库、Redis 或启动依赖未就绪看 readiness 响应体和启动日志第一条错误
浏览器 CORS 报错origin 未配置、填了 path 或代理拦截 OPTIONSserver.cors_allowed_origins 只填真实 origin
gRPC Ingress 失败但 HTTP 正常gRPC 没有独立 Ingress 或 backend protocol设置 nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
synctv system stats 连不上management endpoint、socket、TCP token 或环境变量错误检查 management.* 和 SYNCTV_MANAGEMENT_ENDPOINT
WebSocket 401/403token/ticket 失效、不是房间成员或 origin 被拒绝重新申请 ticket，确认成员和 origin
OAuth2 callback/state 错误redirect 不一致或多副本没有共享 Redis对齐 provider 注册值，多副本配置 Redis
WebAuthn/passkey 失败rp_origin 和真实 HTTPS origin 不一致修正 webauthn.rp_origin 和 webauthn.rp_id
Range seek 或代理播放失败Provider header 不完整或上游不支持 Range检查 Provider header 和上游 Accept-Ranges
多副本 HLS 间歇 404publisher 节点不可达或 HLS 存储模型不一致使用 publisher-node proxy、shared_file 或 OSS

快速检查

Section titled “快速检查”

Readiness

Section titled “Readiness”
Terminal window
curl -i http://localhost:8080/health/ready

成功条件是 200。失败时先看响应体，再看服务日志。

CORS

Section titled “CORS”
Terminal window
curl -i \
  -X OPTIONS \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  http://localhost:8080/api/auth/opaque/login/start

响应需要包含：

Access-Control-Allow-Origin: https://app.example.com

Provider Range

Section titled “Provider Range”
Terminal window
curl -I -H 'Range: bytes=0-1023' 'https://upstream.example.com/video.mp4'

支持 Range 的上游通常返回 206 Partial Content。返回 200 OK 时，SyncTV 会绕过 slice cache，不写 full-body cache。

按层级定位

Section titled “按层级定位”
层级检查点页面
配置生效配置、secret、环境变量覆盖、*_file 路径配置文件如何工作
部署Compose env、Helm values、Service、Ingress、Secret keyDocker Compose、Helm
认证SMTP、OAuth2 redirect、WebAuthn origin、2FA、限流安全模型、邮件与 OAuth2、WebAuthn
媒体Provider header、Range、proxy、slice cache、HLS backend播放与代理模型
容量WebSocket、数据库连接池、Redis、Provider、代理带宽、直播容量规划、指标目录

收集信息

Section titled “收集信息”
  • SyncTV 版本和部署方式。
  • synctv config show --output yaml 输出。提交前复查敏感值。
  • synctv config validate 完整错误。
  • Compose/Helm 渲染后的 Service、Ingress、ConfigMap 和 Secret key。
  • 服务日志中的第一条错误。
  • HTTP 错误响应里的 requestId、status 和 code。
  • 触发问题的请求路径、方法、状态码和必要 header。