cjw
d7f92f1816
约定：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>
7.1 KiB
geMoldInsight 部署总览（DEPLOYMENT）
文档定位：唯一的部署主题入口文档。 本文负责说明当前推荐部署模式、部署文档分工与历史文档去向；不承担全部 Linux 操作细节。详细 Linux 部署步骤见 deployment/LINUX_SETUP.md，当前状态见 STATUS.md，架构边界见 ARCHITECTURE.md。
1. 当前推荐部署模式
当前推荐模式为：
- unified：frontend + unified backend + moldinsight Celery worker
原因：
- 适合本地开发与集成环境
- 前端同域反代可以面对单一 backend
- 比按路径把前端网关分流到两套后端更易维护
1.1 一键 Compose 部署（按文件名切换模式）
项目按"模式 ↔ Compose 文件"一一对应的方式支持一键部署。换文件名即可换模式：
| 模式 | Compose 文件 | 一键命令 |
|---|---|---|
| unified（默认） | docker-compose.yml | docker compose up -d |
| moldinsight-only | docker-compose.moldinsight.yml | docker compose -f docker-compose.moldinsight.yml up -d |
| inventory-only | docker-compose.inventory.yml | docker compose -f docker-compose.inventory.yml up -d |
模式切换唯一入口是
-f文件名。各 service 均未声明profiles（compose 规则：声明了 profiles 的服务在不带--profile时不会被选中，裸up会报no service selected）；历史--profile full/moldinsight/inventory写法随本次拆分失效，请统一改用上表命令。
1.2 宿主机端口约定（默认 = 选择 A）
部署约定：unified 模式下前端独占宿主端口，backend 不暴露宿主端口——浏览器始终只面对一个源，由前端 Nginx 同域反代到 backend，彻底消除 CORS。
# .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 §端口配置、docs/deployment/PORT_CONFIG.md。
1.3 镜像构建
首次部署或更新代码后先构建，再 up：
bash deploy/build.sh # 显式构建 base / backend / frontend 3 个镜像（celery 复用 backend）
或让 compose 构建：
docker compose up -d --build
注意：
docker compose up -d在本地已有同名镜像（如gemold-backend:latest）时不会自动重建，会直接复用旧镜像启动。更新代码或 Dockerfile 后，必须docker compose build或docker compose up -d --build才会生效。
详细 Linux 部署步骤：
2. 支持的部署模式
2.1 unified
一个统一后端同时挂载 moldinsight + inventory。
适合：
- 本地开发
- 测试/集成环境
- 小团队统一部署
Compose 文件：docker-compose.yml（默认入口）
一键命令：
docker compose up -d
包含服务：frontend + backend（unified 入口）+ moldinsight-celery。
2.2 moldinsight-only
只部署模具分析后端。
适合：
- 独立开放分析能力
- 异步任务与文件处理独立扩容
Compose 文件：docker-compose.moldinsight.yml
一键命令：
docker compose -f docker-compose.moldinsight.yml up -d
包含服务：moldinsight（独立 API）+ moldinsight-celery（异步 worker）。
2.3 inventory-only
只部署进销存后端。
适合：
- 独立部署 ERP / 库存能力
- 与 moldinsight 分开发布节奏
Compose 文件：docker-compose.inventory.yml
一键命令：
docker compose -f docker-compose.inventory.yml up -d
包含服务：仅 inventory。不挂任何命名卷（inventory 无文件分析链路），不依赖 RustFS / MinIO。
部署模式的结构含义见 ARCHITECTURE.md。
3. 部署文档分工
3.1 当前权威文档
- DEPLOYMENT.md
- 部署入口与文档导航
- deployment/LINUX_SETUP.md
- Linux 环境下的详细部署操作说明
3.2 端口与配置说明
以下文档作为当前部署补充说明保留：
它们的职责分别是：
DEPLOY_PORT.md：端口暴露、端口规划与 Nginx / 防火墙层面的说明PORT_CONFIG.md：环境变量、端口配置项与 direct run / compose 映射补充
它们是部署入口文档的补充参考，不替代本文或 deployment/LINUX_SETUP.md。
3.3 历史/阶段性部署材料
以下材料属于迁移期或历史说明，不应再视为当前部署权威：
这些材料已迁入 docs/archive/，仅用于历史追溯，不替代当前的 DEPLOYMENT.md 、 deployment/LINUX_SETUP.md 与 deployment/DEPLOY_PORT.md。
4. 当前部署事实
当前部署上的几个关键事实：
- 项目保持单仓库、单数据库
- frontend 是独立前端工程
- 后端支持模块化入口
- moldinsight 的异步分析链路依赖 celery
- PostgreSQL / Redis / 对象存储通常复用服务器已有服务，而不是必须由项目 compose 自带
这些事实的当前版本以 STATUS.md 和 deployment/LINUX_SETUP.md 为准。
5. 相关专题文档
以下文档可作为部署/存储方向的补充参考，但不替代部署入口文档：
- deployment/DEPLOY_PORT.md
- deployment/PORT_CONFIG.md
- topics/storage/RUSTFS_STORAGE.md
- topics/storage/STORAGE_SETUP.md
6. 后续整理原则
部署文档后续将遵循以下规则：
- 部署入口信息只在本文维护
- 操作步骤只在 deployment/LINUX_SETUP.md 维护
- 历史迁移说明与阶段计划迁入
docs/archive/ - README 只保留最短启动说明，不再承担部署手册职责