跳转到内容
SyncTV 文档

观测与运行手册

观测目标

Section titled “观测目标”

生产环境的观测不是只看进程是否存活，而是要确认：

  • HTTP/gRPC/API 能处理请求。
  • PostgreSQL 和 Redis 可用。
  • 登录、2FA、OAuth2、WebAuthn、邮箱验证码可用。
  • WebSocket 和房间实时同步可用。
  • Provider、proxy、slice cache 和直播路径没有持续错误。
  • 集群节点注册、事件发布和 catch-up 正常。

健康检查

Section titled “健康检查”

主服务健康检查：

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

建议：

  • readiness probe 使用 ready 语义，不要只检查 TCP 端口。
  • liveness probe 不要过于激进，避免依赖短暂抖动导致反复重启。
  • 滚动更新时 readiness 应在 shutdown 开始后尽快失败，让流量停止进入旧 Pod。

Metrics

Section titled “Metrics”

开启 metrics：

metrics:
  enabled: true
  host: "0.0.0.0"
  port: 9090
  auth:
    mode: "bearer_token"
    bearer_token_file: "/run/secrets/metrics_token"

抓取测试：

Terminal window
curl -fsS \
  -H "Authorization: Bearer $METRICS_TOKEN" \
  http://localhost:9090/metrics

生产要求：

  • 不要把 metrics 直接暴露公网。
  • Kubernetes 中优先使用 ServiceMonitor、VMServiceScrape 或受控抓取。
  • 如果使用 Kubernetes auth，确保抓取方 service account 有对应权限。

日志

Section titled “日志”

生产建议使用 JSON 日志：

logging:
  level: "info"
  format: "json"

排障时可以临时调高：

logging:
  level: "debug"
  filter: "synctv=debug,tower_http=info"

注意：

  • trace 级别可能输出大量日志，不适合长期开启。
  • 文件日志路径如果是相对路径，会按配置规则解析，不要误放到只读目录。
  • secret 在配置展示中会打码，但不要把包含真实 secret 的环境变量或 values 文件贴到公共 issue。

关键监控项

Section titled “关键监控项”

依赖健康

PostgreSQL 连接、连接池耗尽、Redis 连接、Redis 延迟和 Redis key 前缀是否混用。

认证安全

登录失败率、MFA 失败率、邮箱验证码发送失败、OAuth2 state 错误和 brute-force 锁定。

实时连接

WebSocket 连接数、每用户/房间连接限制、消息限流和断开重连峰值。

媒体路径

Provider 错误率、上游超时、proxy bypass、slice cache 命中率、Range 异常和直播拉流重试。

常见告警建议

Section titled “常见告警建议”
告警可能原因第一检查点
readiness 持续失败DB/Redis 不可用、migration 问题、配置错误synctv db status、服务日志
登录失败率突增密码爆破、OAuth2 回调错误、JWT secret 错误轮换限流日志、OAuth2 配置、secret 变更
邮件发送失败SMTP 凭据错误、TLS 错误、发送频率限制synctv settings test-email、SMTP 日志
WebSocket 大量断开Ingress 超时、Pod 滚动更新、连接限制过低Ingress timeout、shutdown drain、连接限制
Provider 错误突增上游不可用、header 不一致、凭据过期Provider 配置、代理 header、上游响应
Redis 错误Redis 重启、网络抖动、Sentinel 配置错误Redis 日志、redis.deployment_mode、连接串

事故信息收集

Section titled “事故信息收集”

排查生产问题时，先收集可共享信息，不要直接贴 secret。

  1. 记录版本、部署方式、是否启用集群。
  2. 保存 synctv config show --output yaml 的打码输出。
  3. 保存最近的服务日志和重启事件。
  4. 保存 /health/ready 和 /metrics 的可用性结果。
  5. 保存 synctv db status 输出。
  6. 对 Kubernetes，保存 kubectl describe pod、kubectl get ingress,svc,pod 和 rollout 状态。
  7. 对媒体问题，记录 Provider 类型、直连/代理模式、是否 Range 请求、上游 HTTP 状态码。

Kubernetes 快速检查

Section titled “Kubernetes 快速检查”
Terminal window
kubectl -n synctv get pod -o wide
kubectl -n synctv describe pod <pod>
kubectl -n synctv logs <pod> --tail=200

运行手册入口

Section titled “运行手册入口”