常见问题 FAQ

部署类

Q1：docker compose up --build -d 失败 / 构建很慢？

• 网络原因：Go 模块下载走 GOPROXY，可在构建时指定国内代理：

  docker compose build --build-arg GOPROXY=https://goproxy.cn,direct

• Docker Desktop 内存不足：转码构建（FFmpeg）较吃资源，建议给 Docker 分配 ≥ 8GB 内存。

Q2：启动后 API 报「connect: connection refused」？

依赖服务未就绪。compose.yml 已配置 depends_on 健康检查，但若中间件启动失败（如端口被占用），请依次排查：

docker compose ps                    # 查看各服务状态
docker compose logs postgres         # 看具体报错
lsof -i :5432                        # 检查端口占用

Q3：如何确认全套服务都起来了？

docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
curl http://localhost:8080/health
curl http://localhost/api/v1/health

Q4：transcoder 扩容后 worker 没发现新节点？

检查 etcd 中的注册列表：

docker compose exec etcd etcdctl get /vistack/transcoders --prefix

正常情况下每扩容一个 transcoder 就多一个 key；若无，检查 transcoder 日志中 etcd 连接是否成功。

转码类

Q5：视频一直处于 processing 状态？

可能原因与排查：

1. 任务卡死：Watchdog 每 60s 扫描 processing 超 15 分钟的任务并重投；若长时间未恢复，检查 video_transcodes 状态：

   docker compose exec postgres psql -U postgres -c \
     "SELECT id, status, updated_at FROM video_transcodes ORDER BY id DESC LIMIT 10;"

2. transcoder 不可用：查看 docker compose logs worker 是否有 ProcessVideo 调用失败；
3. FFmpeg 崩溃：docker compose logs transcoder 查看转码日志；
4. 重试超限：超过 7 次重试后任务被放弃（attempts:transcode:{id} 计数），需要重新上传或手动重置状态。

Q6：转码产物如何查看？

MinIO 桶 vistack 下：

dash/{videoID}/manifest.mpd        # DASH 清单
dash/{videoID}/init-*.m4s          # 初始化分片
dash/{videoID}/chunk-*.m4s         # 媒体分片
covers/{videoID}.jpg               # 封面

可在 MinIO 控制台（http://localhost:9001）直接浏览。

缓存 / 限流类

Q7：修改了缓存/限流配置不生效？

配置在启动时加载，修改 conf/*.toml 后需要重启对应角色：

docker compose up -d --build api
# 或本地：重新 go run ./cmd/vistack api

Q8：接口返回 429？

命中限流。默认登录后接口按用户 ID 限流（滑动窗口 60s / 100 次）。调整 [ratelimit] 配置后重启 api 即可。

认证类

Q9：登录报 token 无效？

• 确认前端 VITE_API_BASE 指向的入口正确（Docker 场景应为 http://localhost/api/v1，走 Traefik 分流到 auth）；
• 确认 api 能访问 auth 的 JWKS 端点：curl http://localhost:8081/.well-known/jwks.json；
• 若 auth 重启过且未注入固定私钥（开发模式临时密钥），已签发的 token 会全部失效，需重新登录。生产环境务必注入固定 RSA 私钥。

Q10：生产环境如何注入 Auth 私钥？

export VISTACK_AUTH_RSA_PRIVATE_KEY="$(cat private.pem | tr '\n' '\\n')"
docker compose up -d auth

或挂载文件：VISTACK_AUTH_RSA_PRIVATE_KEY_FILE=/run/secrets/private.pem。

开发类

Q11：本地开发时前端连不上后端？

• 检查 web/web-client/.env.development 的 VITE_API_BASE 是否指向实际后端地址；
• 本地直连（不经 Traefik）时确认 CORS：conf/app.toml 的 [cors].allow_origins 需包含前端来源（默认已含 http://localhost:8334/8335）；
• 前端改完环境变量需重启 dev server。

Q12：本地起 transcoder 提示找不到 ffmpeg？

transcoder 角色依赖本机 FFmpeg/FFprobe：

ffmpeg -version   # 验证
brew install ffmpeg   # macOS
apt install ffmpeg    # Debian/Ubuntu

或者干脆用 Docker 跑 transcoder（docker compose up -d transcoder），本地只跑 api / worker / auth。

Q13：如何清理重试队列 / 重置任务状态？

# 清空转码重试延迟队列
docker compose exec redis redis-cli DEL transcode:retry:zset

# 手动重置卡死的转码任务为 pending（触发 watchdog 重新投递）
docker compose exec postgres psql -U postgres -c \
  "UPDATE video_transcodes SET status='pending', updated_at=now() WHERE id=<id>;"