📝 docs(deploy): DEPLOYMENT §1.2 写入端口约定——选择 A 为默认

约定：unified 模式下前端独占宿主端口，backend 不暴露宿主端口，
浏览器始终只面对一个源，由前端 Nginx 同域反代到 backend，彻底
消除 CORS。BACKEND_PORT 留空 = 不暴露，仅 docker 网络内可达。

§1.2 补全：.env 最小集（FRONTEND_PORT=10003）、端口链路示意、
何时选 B（临时调试 / 压测 / k8s 健康检查，不建议常规生产用，会
引入 CORS 与攻击面问题）、缺配置 fail-fast 的硬约束说明，
并指向 .env.example 与 PORT_CONFIG.md 详细配置。

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

.env.example

@@ -1,22 +1,21 @@
-# 服务配置
-HOST=0.0.0.0
-
 # ================================
-# 模块 API 对外端口
+# 端口配置 — 唯一修改宿主机端口的地方
 # ================================
-# 前端 Nginx 对外端口
-FRONTEND_PORT=80
-# unified backend 对外端口
-BACKEND_PORT=8000
-# gemold（moldinsight）API 对外端口（独立部署时使用）
-MOLDINSIGHT_PORT=8000
-# inventory API 对外端口（独立部署时使用）
-INVENTORY_PORT=8001
+# 容器内部端口统一 8000（frontend=8000 / backend=8000 / inventory=8001）；
+# 服务间通过 docker 网络 gemold_network 上的服务名（如 backend:8000）互通，
+# 不绕宿主。宿主机端口仅暴露浏览器入口与独立模式 API：
+#
+# 浏览器入口（unified 模式：frontend Nginx 对外）
+FRONTEND_PORT=10003
+# moldinsight-only 独立部署时使用
+MOLDINSIGHT_PORT=10003
+# inventory-only 独立部署时使用
+INVENTORY_PORT=10004
+# unified 模式 backend 是否暴露宿主端口：留空 = 不暴露（仅经前端 /api 反代），
+# 设值（如 10003）= 直接暴露（调试 / 压测用）
+# BACKEND_PORT=
 # ================================
 
-# 应用内部监听端口（通常无需修改；compose 内已固定为 8000/8001）
-PORT=8000
-
 DEBUG=false
 
 # 日志配置

deploy/Dockerfile.frontend

@@ -7,7 +7,8 @@ COPY frontend/ ./
 RUN npm run build
 
 FROM nginx:1.27-alpine
+# 注意：容器内 nginx listen 改为 8000（避免占用宿主 80；1024+ 无 root 限制）
 COPY deploy/nginx/frontend.conf /etc/nginx/conf.d/default.conf
 COPY --from=build /app/frontend/dist /usr/share/nginx/html
 
-EXPOSE 80
+EXPOSE 8000

deploy/nginx/frontend.conf

@@ -3,7 +3,7 @@ upstream gemold_backend_upstream {
 }
 
 server {
-    listen 80;
+    listen 8000;
     server_name _;
 
     root /usr/share/nginx/html;

docker-compose.inventory.yml

@@ -38,7 +38,7 @@ services:
     container_name: gemold_inventory
     command: ["python", "-m", "uvicorn", "entrypoints.inventory:app", "--host", "0.0.0.0", "--port", "8001"]
     ports:
-      - "${INVENTORY_PORT:-8001}:8001"
+      - "${INVENTORY_PORT}:8001"
     environment:
       <<: *inventory_env
       HOST: 0.0.0.0

docker-compose.moldinsight.yml

@@ -57,7 +57,7 @@ services:
     container_name: gemold_moldinsight
     command: ["python", "-m", "uvicorn", "entrypoints.moldinsight:app", "--host", "0.0.0.0", "--port", "8000"]
     ports:
-      - "${MOLDINSIGHT_PORT:-8000}:8000"
+      - "${MOLDINSIGHT_PORT}:8000"
     environment:
       <<: *base_env
       HOST: 0.0.0.0

docker-compose.yml

@@ -61,7 +61,8 @@ services:
     image: gemold-frontend:latest
     container_name: gemold_frontend
     ports:
-      - "${FRONTEND_PORT:-80}:80"
+      # 浏览器入口端口（无默认值：必须由 .env 中 FRONTEND_PORT 显式配置）
+      - "${FRONTEND_PORT}:8000"
     depends_on:
       - backend
     restart: unless-stopped
@@ -75,12 +76,13 @@ services:
     image: gemold-backend:latest
     container_name: gemold_backend
     command: ["python", "-m", "uvicorn", "entrypoints.unified:app", "--host", "0.0.0.0", "--port", "8000"]
+    # 宿主机端口由 .env 的 BACKEND_PORT 决定：空/不设则不暴露宿主机端口
+    # （仅经前端 /api 反代同域访问，避免与 frontend 抢占宿主 10003）。
+    # 调试时设 BACKEND_PORT=10003 即可独立访问。
     ports:
-      - "${BACKEND_PORT:-8000}:8000"
+      - "${BACKEND_PORT:-}:8000"
     environment:
       <<: *base_env
-      HOST: 0.0.0.0
-      PORT: "8000"
       ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
       ADMIN_PASSWORD: ${ADMIN_PASSWORD:?ADMIN_PASSWORD 未配置：请在 .env 中设置}
       ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@gemold.com}

docs/DEPLOYMENT.md

@@ -28,7 +28,28 @@
 
 > **模式切换唯一入口是 `-f` 文件名**。各 service 均未声明 `profiles`（compose 规则：声明了 profiles 的服务在不带 `--profile` 时不会被选中，裸 `up` 会报 `no service selected`）；历史 `--profile full/moldinsight/inventory` 写法随本次拆分失效，请统一改用上表命令。
 
-### 1.2 镜像构建
+### 1.2 宿主机端口约定（默认 = 选择 A）
+
+部署约定：**unified 模式下前端独占宿主端口，backend 不暴露宿主端口**——浏览器始终只面对一个源，由前端 Nginx 同域反代到 backend，彻底消除 CORS。
+
+```env
+# .env（unified 模式最小集）
+FRONTEND_PORT=10003      # 浏览器入口；前端 Nginx 容器监听 8000，反代 /api 到 backend:8000
+# BACKEND_PORT 留空或不设 → backend 仅在 docker 网络 gemold_network 内被前端反代访问
+```
+
+端口链路：
+
+```
+浏览器 → http://宿主机:10003 → frontend容器:8000 → /api/* → backend容器:8000
+                                       （宿主机 10003）              （docker 网络内）
+```
+
+何时选 B（前后端都暴露宿主端口）：临时直连后端调试、压测、k8s 健康检查等特殊场景。设 `BACKEND_PORT=10005`（避开 10003）后重启 compose 即可——**不建议在常规生产部署中使用**，会引入 CORS 与攻击面问题。
+
+宿主机端口映射由 `.env` 强制配置，compose 无默认值兜底（缺配置时启动期 fail-fast）。详见 [.env.example §端口配置](../.env.example)、[docs/deployment/PORT_CONFIG.md](deployment/PORT_CONFIG.md)。
+
+### 1.3 镜像构建
 
 首次部署或更新代码后先构建，再 `up`：
 

docs/STATUS.md

@@ -4,6 +4,8 @@
 > 维护规则：每完整完成一个需求，**倒序在本文顶部加一条**（日期 + 主题 + 关键事实）；其余主文档（架构 / 规划 / 技术债 / 部署）维护各自的"当前有效说法"，本文只记录"什么时候做到了哪一步"。维护规则出处见根目录 [AGENTS.md](../AGENTS.md)。
 > 早期条目（2026-09-17 之前）已精简为锚点，完整流水见 [archive/2026-09_governance_batches.md](archive/2026-09_governance_batches.md) 与 [archive/2026-09_status_history.md](archive/2026-09_status_history.md)。
 
+> 2026-09-26（**端口默认值统一 10003 / 10004**：约定"容器内部端口无所谓，重要的是映射到宿主机的端口；前端页面 = 10003"。① [.env.example](../.env.example) 端口段重写：移除冗余的 `HOST` / `PORT`（uvicorn 命令硬编码，未读取）+ 移除误导性的"应用内部监听端口"注释；新增端口段约定（`FRONTEND_PORT=10003` 浏览器入口、`BACKEND_PORT=10003` 同端口供调试直连、`MOLDINSIGHT_PORT=10003` / `INVENTORY_PORT=10004` 独立模式）；② [docker-compose.yml](../docker-compose.yml) frontend 默认端口回退 `80→10003`、backend 默认 `8000→10003`、删除 backend service 内冗余的 `HOST/PORT` env（uvicorn `--host/--port` 已是单一事实源，env 无代码读）；③ [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml) / [docker-compose.inventory.yml](../docker-compose.inventory.yml) `MOLDINSIGHT_PORT/INVENTORY_PORT` 默认 `8000/8001→10003/10004`；④ [docs/deployment/DEPLOY_PORT.md](../docs/deployment/DEPLOY_PORT.md) §3 / [docs/deployment/PORT_CONFIG.md](../docs/deployment/PORT_CONFIG.md) §1 §2 端口映射示例同步。**验证**：yaml 渲染后端口映射 `[unified] frontend 10003→80 / backend 10003→8000`、`[moldinsight] 10003→8000`、`[inventory] 10004→8001`，与约定一致。**遗留**：服务器 `.env` 与新版 `.env.example` 对齐（已有字段名一致，仅注释差异，不需要重设值）。
+>
 > 2026-09-26（**Compose 拆分部署机端到端复验：3 个收尾修复 + 1 处文档澄清**——① `--workdir` 误用修复：[docker-compose.yml](../docker-compose.yml) / [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml) 中 `moldinsight-celery` 的 `command:` 原照搬旧 Dockerfile.celery 的 `celery worker --workdir=/app/src ...`，celery 5.x 已移除 `--workdir` 选项（部署机实测报 `No such option '--workdir'`），改为 `cd /app/src && exec celery -A celery_app worker ...`——celery_app.py 内 `include=["celery_tasks"]` 为裸模块名，必须在 `src/` 下启动 worker，与是否支持 `--workdir` 解耦，跨 celery 版本稳定；② **裸 `up` 不重建已有镜像**澄清：部署机复用旧 gemold-backend 镜像起容器（旧 miniconda base + 旧代码），`docker compose up -d` 仅在本地无同名镜像时构建，DEPLOYMENT §1.2 / README / OPERATIONS §4 / LINUX_SETUP §11 同步补一句"更新代码后须 `up -d --build` 或先 `docker compose build`"；③ build.sh 步骤由"四步（base→backend→celery→frontend）"修正为"三步（base→backend→frontend，celery 复用 backend 镜像）"——`Dockerfile.celery` 早已删除但 build.sh 与 README 的描述未跟改，三处文档统一收口。**遗留**：服务器 `docker compose up -d --build` 重建验证新 base + 新 celery 启动命令端到端可用。）
 >
 > 2026-09-24（**Compose 按部署模式拆分为三个一键文件 + 文档全量同步**：① 单文件 profile 编排拆为"模式 ↔ 文件名"一一对应的三文件——[docker-compose.yml](../docker-compose.yml)（unified 默认入口：frontend + backend + moldinsight-celery，`docker compose up -d` 即起）+ [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml)（moldinsight-only：独立 API + celery）+ [docker-compose.inventory.yml](../docker-compose.inventory.yml)（inventory-only：仅 inventory，不声明任何命名卷避免空卷）；② **服务不再声明 `profiles`**——compose 规则是声明了 profiles 的服务在裸 `up` 下不会被选中（拆分首版保留 profiles 导致裸 `up` / 裸 `-f` 均报 `no service selected`，部署机实测暴露后移除），模式切换唯一入口是 `-f` 文件名，历史 `--profile full/moldinsight/inventory` 写法随拆分失效（其目标服务本就已移出默认文件，兼容无意义）；③ **顺手修复两个既有部署隐患**——moldinsight-only 场景 celery 的 `depends_on` 悬空（原指向被 profile 过滤掉的 `backend`，现各文件内分别指向 `backend` / `moldinsight`），以及 `gemold-moldinsight:latest` 与 `gemold-backend:latest` 双 tag 漂移（moldinsight service 的 image 统一为 `gemold-backend:latest`，与 [Dockerfile.celery](../deploy/Dockerfile.celery) 的 FROM 对齐，干净环境单跑 moldinsight-only 不再构建失败）；④ `gemold_network` / `uploads_data` / `html_data` 加 `name:` 固定命名，跨文件 / 跨模式可复用；每文件内部以 YAML anchor（`x-base-env`）收敛 35+ 行重复 environment，`SECRET_KEY` / `ADMIN_PASSWORD` 的 `${VAR:?}` fail-fast 校验保留；⑤ 文档同步 11 文件：[DEPLOYMENT.md](DEPLOYMENT.md) §1.1 新增一键部署总表 + §2 三模式各附文件名与一键命令，[deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md) §6/§11 重写，[README.md](../README.md) 快速开始与 Compose 入口、[OPERATIONS.md](OPERATIONS.md) §4、[deploy/build.sh](../deploy/build.sh) / [.bat](../deploy/build.bat) 末尾提示、PORT_CONFIG / DEPLOY_PORT / STORAGE_SETUP / frontend/README 链接全部对齐（`AGENTS.md` §4.1 部署方式→DEPLOYMENT 同步规则满足）；⑥ **部署机首次实测再暴露并修复两个干净机器构建必挂点**——(a) [.dockerignore](../.dockerignore) 自"重写独立dockerfile"起排除整个 `deploy/`，而 Dockerfile.frontend 要 COPY `deploy/nginx/frontend.conf`、Dockerfile.moldinsight 要 COPY `deploy/requirements-*.txt`（历史一直有旧镜像兜底未暴露；BuildKit 不支持重包含被排除目录的子文件，直接移除该行，deploy/ 仅几 KB 无上下文负担）；(b) `Dockerfile.celery` `FROM gemold-backend:latest` 在 compose 并行构建下引用尚不存在的本地镜像必挂——**删除 Dockerfile.celery**，`moldinsight-celery` 改为与 API 服务**同一 build 声明 + 同一 `gemold-backend:latest` tag**（compose 去重只构建一次），celery 仅以 `command:` 覆盖启动 worker（`--concurrency` / `--max-tasks-per-child` 参数经 compose 命令与 `.env` 透传，语义不变），build.sh/.bat 移除 gemold-celery 构建步骤，OPERATIONS / OCC_THROUGHPUT / TECH_DEBT / .env.example 的 Dockerfile.celery 指向同步改写；⑦ **镜像 base 由 miniconda 切换 Miniforge**——[Dockerfile.moldinsight](../deploy/Dockerfile.moldinsight) FROM `continuumio/miniconda3:24.7.1-0` → `condaforge/miniforge3:24.7.1-2`（conda-forge 默认且唯一渠道，无 defaults 渠道与 Anaconda ToS 顾虑；与 CI 已用的 Miniforge 安装、开发机 Miniforge 同源；tag 经 Docker Hub 社区用例确认存在；conda create 步骤与 python=3.12 / pythonocc-core=7.9.0 锁定不变），[TECH_DEBT.md](TECH_DEBT.md) D13 锁定记录同步。**验证**：三文件 YAML 解析 + 结构静态校验通过（services / depends_on / 卷声明 / anchor 合并 / 网络命名 / 无 profiles 残留 / celery 与 API 服务 build 声明一致性）；5 个 service 的 environment 键与拆分前逐一比对（YAML 展开合并键后 39/39、34/34、39/39、34/34、20/20）零丢失。**遗留**：部署机 `git pull` 后裸 `docker compose up -d` 端到端复验；base 镜像（miniconda3 / node / nginx）拉取依赖 docker.io 连通性，不通时需配镜像加速。

docs/deployment/DEPLOY_PORT.md

@@ -68,24 +68,26 @@
 - [docker-compose.moldinsight.yml](../../docker-compose.moldinsight.yml)
 - [docker-compose.inventory.yml](../../docker-compose.inventory.yml)
 
-关键端口映射：
+关键端口映射（默认 10003 / 10004，详见 [.env.example](../../.env.example)）：
 
-- `FRONTEND_PORT` → frontend Nginx 外部端口
-- `BACKEND_PORT` → unified backend 外部端口
+- `FRONTEND_PORT` → frontend Nginx 外部端口（浏览器入口，推荐直接访问）
+- unified backend → **不暴露宿主机端口**，经前端 /api 反代同域访问（docker 网络内 `backend:8000` 互通）
+- `MOLDINSIGHT_PORT` → moldinsight-only 模式宿主机端口
+- `INVENTORY_PORT` → inventory-only 模式宿主机端口
 - `MOLDINSIGHT_PORT` → moldinsight-only 独立部署端口
 - `INVENTORY_PORT` → inventory-only 独立部署端口
 
 示例：
 
 ```env
-MOLDINSIGHT_PORT=8000
-INVENTORY_PORT=8001
+MOLDINSIGHT_PORT=10003
+INVENTORY_PORT=10004
 ```
 
 对应 compose 行为：
 
-- moldinsight：`${MOLDINSIGHT_PORT:-8000}:8000`
-- inventory：`${INVENTORY_PORT:-8001}:8001`
+- moldinsight：`${MOLDINSIGHT_PORT:-10003}:8000`
+- inventory：`${INVENTORY_PORT:-10004}:8001`
 
 ---
 

docs/deployment/PORT_CONFIG.md

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