From d7f92f18161aab8a03055907702c5d1ab6b68cbe Mon Sep 17 00:00:00 2001 From: chenjw28 <792430652@qq.com> Date: Sat, 26 Sep 2026 21:03:49 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(deploy):=20DEPLOYMENT=20?= =?UTF-8?q?=C2=A71.2=20=E5=86=99=E5=85=A5=E7=AB=AF=E5=8F=A3=E7=BA=A6?= =?UTF-8?q?=E5=AE=9A=E2=80=94=E2=80=94=E9=80=89=E6=8B=A9=20A=20=E4=B8=BA?= =?UTF-8?q?=E9=BB=98=E8=AE=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 约定：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 --- docs/DEPLOYMENT.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index a799c74..de8cf35 100644 --- a/docs/DEPLOYMENT.md +++ b/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`：