From e65dcc2d398b7a1e89f6d00b16c40acca8abf452 Mon Sep 17 00:00:00 2001 From: chenjw28 <792430652@qq.com> Date: Sat, 26 Sep 2026 20:45:38 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=20build(deploy):=20=E7=AB=AF?= =?UTF-8?q?=E5=8F=A3=E9=BB=98=E8=AE=A4=E5=80=BC=E7=BB=9F=E4=B8=80=2010003/?= =?UTF-8?q?10004=E2=80=94=E2=80=94=E5=89=8D=E7=AB=AF=E5=85=A5=E5=8F=A3?= =?UTF-8?q?=E5=9B=BA=E5=AE=9A=2010003?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 约定"容器内部端口无所谓，重要的是宿主机端口；前端 = 10003"。 - .env.example 端口段重写：移除冗余 HOST/PORT（uvicorn 命令硬编码， 无人读 env）+ 移除误导注释；FRONTEND_PORT/BACKEND_PORT/MOLDINSIGHT_PORT 默认 10003，INVENTORY_PORT 默认 10004 - docker-compose.yml frontend 默认 80→10003、backend 8000→10003，删除 backend service 内冗余 HOST/PORT env - docker-compose.moldinsight.yml / docker-compose.inventory.yml 默认 端口同步 - DEPLOY_PORT §3 / PORT_CONFIG §1 §2 端口映射示例同步 - STATUS 补录 验证：yaml 渲染端口映射 unified frontend 10003→80、backend 10003→8000， moldinsight 10003→8000，inventory 10004→8001。 Co-Authored-By: Claude Code --- .env.example | 26 +++++++++++--------------- docker-compose.inventory.yml | 2 +- docker-compose.moldinsight.yml | 2 +- docker-compose.yml | 8 ++++---- docs/STATUS.md | 2 ++ docs/deployment/DEPLOY_PORT.md | 14 +++++++------- docs/deployment/PORT_CONFIG.md | 16 ++++++++-------- 7 files changed, 34 insertions(+), 36 deletions(-) diff --git a/.env.example b/.env.example index 7a83fee..b1451e8 100644 --- a/.env.example +++ b/.env.example @@ -1,22 +1,18 @@ -# 服务配置 -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 +# 容器内部端口无所谓，重要的是映射到宿主机的端口。 +# 约定：前端页面 = 10003；后端 API 不直接暴露（仅经前端 Nginx 反代）。 +# gemold（moldinsight）API 对外端口（仅 moldinsight-only / 直接调试时用） +MOLDINSIGHT_PORT=10003 +# inventory API 对外端口（仅 inventory-only 模式用） +INVENTORY_PORT=10004 +# unified 模式下 frontend Nginx 对外端口（即浏览器入口） +FRONTEND_PORT=10003 +# 兼容旧字段名（部分部署脚本仍引用） +BACKEND_PORT=10003 # ================================ -# 应用内部监听端口（通常无需修改；compose 内已固定为 8000/8001） -PORT=8000 - DEBUG=false # 日志配置 diff --git a/docker-compose.inventory.yml b/docker-compose.inventory.yml index 6616d35..5f6ec90 100644 --- a/docker-compose.inventory.yml +++ b/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:-10004}:8001" environment: <<: *inventory_env HOST: 0.0.0.0 diff --git a/docker-compose.moldinsight.yml b/docker-compose.moldinsight.yml index 7a4cc7d..a3a8ae6 100644 --- a/docker-compose.moldinsight.yml +++ b/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:-10003}:8000" environment: <<: *base_env HOST: 0.0.0.0 diff --git a/docker-compose.yml b/docker-compose.yml index df9cc1a..73e3f98 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -61,7 +61,8 @@ services: image: gemold-frontend:latest container_name: gemold_frontend ports: - - "${FRONTEND_PORT:-80}:80" + # 浏览器入口端口（默认 10003；容器内 nginx 仍监听 80，反代到 backend 8000） + - "${FRONTEND_PORT:-10003}:80" depends_on: - backend restart: unless-stopped @@ -76,11 +77,10 @@ services: container_name: gemold_backend command: ["python", "-m", "uvicorn", "entrypoints.unified:app", "--host", "0.0.0.0", "--port", "8000"] ports: - - "${BACKEND_PORT:-8000}:8000" + # 不推荐直接访问（应通过 frontend 反代同域访问 /api）；保留端口供调试 + - "${BACKEND_PORT:-10003}: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} diff --git a/docs/STATUS.md b/docs/STATUS.md index adb287f..033600c 100644 --- a/docs/STATUS.md +++ b/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 连通性，不通时需配镜像加速。 diff --git a/docs/deployment/DEPLOY_PORT.md b/docs/deployment/DEPLOY_PORT.md index dc4e27b..2ad24be 100644 --- a/docs/deployment/DEPLOY_PORT.md +++ b/docs/deployment/DEPLOY_PORT.md @@ -68,24 +68,24 @@ - [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 外部端口（浏览器入口，推荐直接访问） +- `BACKEND_PORT` → unified backend 外部端口（一般不直接访问，经前端 /api 反代同域访问） - `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` --- diff --git a/docs/deployment/PORT_CONFIG.md b/docs/deployment/PORT_CONFIG.md index 363ef5a..6787993 100644 --- a/docs/deployment/PORT_CONFIG.md +++ b/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 # 浏览器入口（前端 Nginx 对外端口） +BACKEND_PORT=10003 # unified backend 对外端口（一般不直接访问，经前端反代） +MOLDINSIGHT_PORT=10003 # moldinsight-only 独立部署时使用 +INVENTORY_PORT=10004 # inventory-only 独立部署时使用 ``` 其余基础设施通常为： @@ -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 宿主机暴露端口（浏览器入口） | +| `BACKEND_PORT`（默认 10003） | unified backend 宿主机暴露端口（一般不直接访问，经前端 /api 反代） | +| `MOLDINSIGHT_PORT`（默认 10003） | moldinsight-only 独立部署端口 | +| `INVENTORY_PORT`（默认 10004） | inventory-only 独立部署端口 | | `DB_PORT` | PostgreSQL 端口 | | `REDIS_PORT` | Redis 端口 | | `9000` | MinIO/RustFS S3 兼容 API |