配置校验与排错

首选命令

本地配置文件：

synctv config --config synctv.yaml validate --strict

开发环境使用 cargo：

cargo run -p synctv --bin synctv -- config --config synctv.yaml validate --strict

config validate 默认会把未知配置项和不支持的 SYNCTV_ 环境变量作为 warning 输出。部署前预检建议使用 --strict，因为 synctv serve 启动时也会使用同一套严格未知输入策略。

常见错误

服务已经启动但访问、认证、媒体播放或 Ingress 行为异常时，先看 排障入口。

OPAQUE secret 为空

错误含义：security.opaque_server_setup_secret 没有设置。

设置 secret：

export SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET="$(openssl rand -base64 48)"

生产环境要保存这个值，不要每次重新生成。

credential key 格式错误

security.credential_encryption_key 必须是 64 个十六进制字符。

正确生成：

openssl rand -hex 32

错误示例：

• base64 字符串。
• 普通密码。
• 长度不是 64。

CORS origin 不合法

正确：

server:
  cors_allowed_origins:
    - "https://app.example.com"

错误：

server:
  cors_allowed_origins:
    - "https://app.example.com/path"

origin 不能包含路径。

WebAuthn origin 不合法

webauthn.rp_origin 也必须是 origin，不包含路径。

集群开启但 Redis 为空

cluster.enabled=true 时 Redis 必须配置。

配置 Redis：

redis:
  url: "redis://redis:6379"

集群开启但 cluster secret 为空

设置 cluster secret：

export SYNCTV_CLUSTER_SECRET="$(openssl rand -hex 32)"

Compose 排错

先确认你已经按 Docker Compose 部署 获取生产 Compose 文件，并在同一目录生成 .env.postgres、.env.redis 和 .env.synctv。

查看最终 Compose 配置：

docker compose config

查看日志：

docker compose logs -f synctv

如果 Compose 报 required variable missing，说明生产 compose 需要显式设置 secret。回到 Compose 文件所在目录，运行 ./scripts/init-compose-env.sh 并填写 .env.synctv 中的 root 密码。

Helm 排错

渲染：

helm template synctv ./helm/synctv --values my-values.yaml

检查：

helm lint ./helm/synctv

查看运行时配置：

kubectl get configmap synctv-config -n synctv -o yaml

查看 Secret key 是否存在：

kubectl get secret synctv-secrets -n synctv -o jsonpath='{.data}' | jq 'keys'

不要把 Secret 值直接贴到 issue 或聊天窗口。