ci: enforce WEB_PORT 3000 in deploy workflow

.github/workflows/main.yml

@@ -481,31 +481,19 @@ jobs:
             fi
 
             ensure_web_port_available() {
-              local configured_web_port
-              configured_web_port="${WEB_PORT:-}"
-              if [ -z "${configured_web_port}" ] && [ -f .env ]; then
-                configured_web_port="$(grep -E '^WEB_PORT=' .env | tail -n 1 | cut -d= -f2- || true)"
+              local target_web_port=3000
+              if grep -q '^WEB_PORT=' .env; then
+                sed -i "s/^WEB_PORT=.*/WEB_PORT=${target_web_port}/" .env
+              else
+                echo "WEB_PORT=${target_web_port}" >> .env
               fi
-              configured_web_port="${configured_web_port:-3000}"
 
               local conflicting_web_containers
-              conflicting_web_containers="$(docker ps --filter "publish=${configured_web_port}" --format '{{.Names}}' | grep -Ev '^fquiz-web$' || true)"
+              conflicting_web_containers="$(docker ps --filter "publish=${target_web_port}" --format '{{.Names}}' | grep -Ev '^fquiz-web$' || true)"
               if [ -n "${conflicting_web_containers}" ]; then
-                if [ -n "${WEB_PORT:-}" ]; then
-                  echo "[error] WEB_PORT=${configured_web_port} 已被其他容器占用，请调整后重试。"
-                  echo "[error] 冲突容器: ${conflicting_web_containers//$'\n'/, }"
-                  return 1
-                fi
-                local fallback_web_port=13000
-                while docker ps --filter "publish=${fallback_web_port}" --format '{{.ID}}' | grep -q .; do
-                  fallback_web_port=$((fallback_web_port + 1))
-                done
-                if grep -q '^WEB_PORT=' .env; then
-                  sed -i "s/^WEB_PORT=.*/WEB_PORT=${fallback_web_port}/" .env
-                else
-                  echo "WEB_PORT=${fallback_web_port}" >> .env
-                fi
-                echo "[warn] WEB 端口 ${configured_web_port} 被占用，已自动切换到 ${fallback_web_port}。"
+                echo "[error] WEB 端口 ${target_web_port} 已被其他容器占用，停止部署。"
+                echo "[error] 冲突容器: ${conflicting_web_containers//$'\n'/, }"
+                return 1
               fi
             }
 

memory/2026-05-02.md

@@ -32,3 +32,22 @@
 - 风险与影响：
   - 影响面：`api` 镜像新增 `flower` 依赖，镜像体积与构建时长略有增加。
   - 当前运行中的 `api/celery-worker/celery-beat/scheduler/web` 仍为既有镜像；本次仅重建并替换了 `flower`。
+
+## Work Log - 固定 workflow WEB 端口为 3000（2026-05-02）
+
+- 背景：
+  - 发布后 `fquiz-web` 宿主机端口出现 `13000->3000`，与 Nginx 固定代理 `127.0.0.1:3000` 不一致。
+  - 根因是 workflow 的 `ensure_web_port_available` 在 3000 冲突时会自动回退到 13000+ 并写回 `.env`。
+
+- 本次改动（最小闭环）：
+  - 文件：`.github/workflows/main.yml`
+  - 调整 `ensure_web_port_available`：
+    - 每次部署前强制写入 `WEB_PORT=3000`（存在则覆盖，不存在则追加）。
+    - 移除自动回退到 `13000+` 逻辑。
+    - 若 `3000` 被其它容器占用，直接输出错误并终止部署。
+
+- 预期效果：
+  - workflow 部署后，`fquiz-web` 宿主机端口稳定为 `3000`，避免与 Nginx 前端代理端口漂移。
+
+- 风险与影响：
+  - 若服务器上已有其他容器占用 `3000`，本次部署会失败（可预期失败），需先释放端口或手动调整冲突容器。