故障排查

Resource Service unhealthy

症状：

dependency failed to start: container markify-resource is unhealthy
EACCES: permission denied, open '/workspace/services/resource/logs/...'

原因是宿主机 bind mount 目录由 root 创建，而容器使用 UID 1000 写日志。

install -d -o 1000 -g 1000 -m 0750 \
  data/logs/resource-service data/logs/api \
  data/logs/image-worker data/logs/video-worker

chown -R 1000:1000 data/logs
docker compose up -d --force-recreate

如果配置了 LOG_DATA_DIR，替换成实际路径。

预览立即返回 503

响应通常是：

{ "code": "WORKER_UNAVAILABLE", "message": "image worker is not configured" }

若耗时只有几毫秒，通常是 API 的 WORKER_ENDPOINTS 为空；若耗时接近超时值，则更可能是网络不可达。

检查：

docker inspect markify-api --format '{{range .Config.Env}}{{println .}}{{end}}' | grep WORKER_ENDPOINTS
docker compose -f docker-compose.yml -f docker-compose.workers.yml ps
docker compose -f docker-compose.yml -f docker-compose.workers.yml logs --tail=100 image-worker

生产图片拓扑必须使用 Worker 叠加文件，或显式配置并启动 Image Worker。

Video Worker 构建长时间不动

若停在：

RUN apk add --no-cache ffmpeg font-noto-cjk

表示服务器正在从 Alpine 仓库下载 FFmpeg 的大量编解码依赖，不是 TypeScript 构建死锁。当前不使用视频功能时只构建 resource-service image-worker markify-api docs。

预览显示上一次结果

确认以下条件：

1. 前端保持同一个 <img src>，不要在每次提交后创建 blob URL。
2. 反向代理为流端点关闭响应缓冲。
3. 客户端只把成功的最新请求标记为“预览已更新”。
4. 409 PREVIEW_SUPERSEDED 是正常的 latest-wins 结果。

API 会对每次发布使用 revision，并连续输出 multipart 帧头以兼容浏览器提交时机。

查看健康与日志

curl http://markify-api/health/ready
curl http://markify-api/health/dependencies

docker compose -f docker-compose.yml -f docker-compose.workers.yml logs --tail=200
docker inspect markify-resource --format '{{json .State.Health}}'

API /health/ready 成功不表示 Worker 正常，应同时检查 /health/dependencies。

文档站 404

docker exec markify-docs nginx -t
docker exec markify-docs wget -qO- http://127.0.0.1/health
docker exec markify-docs ls -la /usr/share/nginx/html

若首页存在但子页面 404，检查网关是否保留请求路径，以及容器是否使用项目提供的 nginx.conf。