🐛 fix(deploy): 修 unified backend 与 frontend 抢占宿主 10003 冲突

上一版把 frontend 与 backend 都映射 10003:8000，会触发 docker 启动时
"bind: address already in use"。修正：

- docker-compose.yml backend ports 改为 expose: ["8000"]——不映射宿主机，
  仅在 docker 网络 gemold_network 内被 frontend 经 backend:8000 反代访问
- .env.example 删除 BACKEND_PORT 字段（不再需要）
- PORT_CONFIG / DEPLOY_PORT 端口映射表/示例同步：unified backend 不暴露
  宿主机端口，统一经前端 /api 反代

验证：yaml 渲染后无任何 service 对抢宿主端口（unified 仅 frontend 暴露
$FRONTEND_PORT=10003；moldinsight-only 仅 moldinsight 暴露 10003；
inventory-only 仅 inventory 暴露 10004）。

Co-Authored-By: Claude Code <noreply@anthropic.com>

.env.example

@@ -1,16 +1,16 @@
 # ================================
 # 端口配置 — 唯一修改宿主机端口的地方
 # ================================
-# 容器内部端口无所谓，重要的是映射到宿主机的端口。
-# 约定：前端页面 = 10003；后端 API 不直接暴露（仅经前端 Nginx 反代）。
-# gemold（moldinsight）API 对外端口（仅 moldinsight-only / 直接调试时用）
-MOLDINSIGHT_PORT=10003
-# inventory API 对外端口（仅 inventory-only 模式用）
-INVENTORY_PORT=10004
-# unified 模式下 frontend Nginx 对外端口（即浏览器入口）
+# 容器内部端口统一 8000（frontend=8000 / backend=8000 / inventory=8001）；
+# 服务间通过 docker 网络 gemold_network 上的服务名（如 backend:8000）互通，
+# 不绕宿主。宿主机端口仅暴露浏览器入口与独立模式 API：
+#
+# 浏览器入口（unified 模式：frontend Nginx 对外）
 FRONTEND_PORT=10003
-# 兼容旧字段名（部分部署脚本仍引用）
-BACKEND_PORT=10003
+# moldinsight-only 独立部署时使用
+MOLDINSIGHT_PORT=10003
+# inventory-only 独立部署时使用
+INVENTORY_PORT=10004
 # ================================
 
 DEBUG=false

docker-compose.yml

@@ -76,9 +76,10 @@ services:
     image: gemold-backend:latest
     container_name: gemold_backend
     command: ["python", "-m", "uvicorn", "entrypoints.unified:app", "--host", "0.0.0.0", "--port", "8000"]
-    ports:
-      # 不推荐直接访问（应通过 frontend 反代同域访问 /api）；保留端口供调试
-      - "${BACKEND_PORT:-10003}:8000"
+    # 不映射端口到宿主机：backend 仅供 frontend 反代（docker 网络内 backend:8000 互通），
+    # 避免与 frontend 抢占宿主 10003。BACKEND_PORT 仍保留以便调试时临时开放。
+    expose:
+      - "8000"
     environment:
       <<: *base_env
       ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}

docs/deployment/DEPLOY_PORT.md

@@ -71,7 +71,9 @@
 关键端口映射（默认 10003 / 10004，详见 [.env.example](../../.env.example)）：
 
 - `FRONTEND_PORT` → frontend Nginx 外部端口（浏览器入口，推荐直接访问）
-- `BACKEND_PORT` → unified backend 外部端口（一般不直接访问，经前端 /api 反代同域访问）
+- unified backend → **不暴露宿主机端口**，经前端 /api 反代同域访问（docker 网络内 `backend:8000` 互通）
+- `MOLDINSIGHT_PORT` → moldinsight-only 模式宿主机端口
+- `INVENTORY_PORT` → inventory-only 模式宿主机端口
 - `MOLDINSIGHT_PORT` → moldinsight-only 独立部署端口
 - `INVENTORY_PORT` → inventory-only 独立部署端口
 

docs/deployment/PORT_CONFIG.md

@@ -27,10 +27,10 @@
 核心环境变量：
 
 ```env
-FRONTEND_PORT=10003    # 浏览器入口（前端 Nginx 对外端口）
-BACKEND_PORT=10003     # unified backend 对外端口（一般不直接访问，经前端反代）
+FRONTEND_PORT=10003    # unified 模式浏览器入口（前端 Nginx 对外）
 MOLDINSIGHT_PORT=10003 # moldinsight-only 独立部署时使用
 INVENTORY_PORT=10004   # inventory-only 独立部署时使用
+# 注意：unified backend 不暴露宿主机端口，仅经前端 /api 反代（docker 网络内部 backend:8000 互通）
 ```
 
 其余基础设施通常为：
@@ -53,7 +53,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
 | 变量 / 端口 | 用途 |
 |---|---|
 | `FRONTEND_PORT`（默认 10003） | 前端 Nginx 宿主机暴露端口（浏览器入口） |
-| `BACKEND_PORT`（默认 10003） | unified backend 宿主机暴露端口（一般不直接访问，经前端 /api 反代） |
+| unified backend | **不暴露宿主机端口**——经前端 /api 反代，docker 网络内 `backend:8000` 互通 |
 | `MOLDINSIGHT_PORT`（默认 10003） | moldinsight-only 独立部署端口 |
 | `INVENTORY_PORT`（默认 10004） | inventory-only 独立部署端口 |
 | `DB_PORT` | PostgreSQL 端口 |