infra/docker/api.Dockerfile

@@ -30,6 +30,10 @@ COPY deploy/configs/douyin_cookies.txt /app/configs/douyin_cookies.txt
 # 强制升级 yt-dlp 到最新（抖音反爬经常变更，旧版 cookies 支持失效；#1968/#1963）
 RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com --upgrade "yt-dlp>=2026.8.19"
 
+# API 启动入口（幂等迁移 + uvicorn）—— #2129: watchtower 自动部署兜底
+COPY infra/docker/entrypoint-api.sh /usr/local/bin/entrypoint-api.sh
+RUN chmod +x /usr/local/bin/entrypoint-api.sh
+
 # 设置环境变量
 ENV PATH="/opt/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
 ENV PYTHONPATH=/app:/app/apps/api
@@ -41,4 +45,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"
 
 # API 入口点
-CMD ["uvicorn", "apps.api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+ENTRYPOINT ["/usr/local/bin/entrypoint-api.sh"]

infra/docker/entrypoint-api.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# API 启动入口：先幂等执行数据库迁移，再启动传入的 CMD（默认 uvicorn）
+# 解决 watchtower 自动拉取新镜像后容器重启、未跑 alembic upgrade head 导致新列缺失 500 的问题（#2129）
+set -e
+
+cd /app
+
+echo "[entrypoint-api] Running alembic upgrade head..."
+if alembic upgrade head; then
+  echo "[entrypoint-api] Migrations ok."
+else
+  echo "[entrypoint-api] WARNING: alembic upgrade failed, continuing (existing columns should be fine)..." >&2
+fi
+
+# 若有显式 CMD（CI 部署时 docker compose run --rm api sh -c '...' 传入），直接 exec 它
+if [ "$#" -gt 0 ]; then
+  echo "[entrypoint-api] Exec custom command: $*"
+  exec "$@"
+fi
+
+echo "[entrypoint-api] Starting uvicorn..."
+exec uvicorn apps.api.main:app --host 0.0.0.0 --port 8000

infra/docker/entrypoint-worker.sh

@@ -18,6 +18,17 @@
 
 set -e
 
+# #2129: 幂等执行数据库迁移（watchtower 自动部署兜底）
+# worker 容器独立启动，不能依赖 API 容器先跑迁移
+cd /app
+echo "[entrypoint-worker] Running alembic upgrade head..."
+if alembic upgrade head; then
+  echo "[entrypoint-worker] Migrations ok."
+else
+  echo "[entrypoint-worker] WARNING: alembic upgrade failed, continuing to start workers..." >&2
+fi
+cd - >/dev/null
+
 MAX_TASKS="${WORKER_MAX_TASKS_PER_CHILD:-100}"
 
 # ── 并发计算：显式 env 优先；否则从 WORKER_CONCURRENCY 按比例推导 ──

infra/docker/worker.Dockerfile

@@ -34,6 +34,7 @@ ENV APP_VERSION=$APP_VERSION
 
 # 复制文件（按变化频率从低到高排序，最大化层缓存命中）
 COPY alembic.ini /app/alembic.ini
+COPY alembic/ /app/alembic/
 COPY migrations/ /app/migrations/
 COPY packages/ /app/packages/
 # PR #1844 起，worker 还需要加载 apps.api.app.tasks.lipsync_tts，