docs/DEPLOYMENT.md

# geMoldInsight 部署总览（DEPLOYMENT）

> 文档定位：**唯一的部署主题入口文档**。
> 本文负责说明当前推荐部署模式、部署文档分工与历史文档去向；不承担全部 Linux 操作细节。详细 Linux 部署步骤见 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)，当前状态见 [STATUS.md](STATUS.md)，架构边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。

---

## 1. 当前推荐部署模式

当前推荐模式为：

- **unified**：frontend + unified backend + moldinsight Celery worker

原因：
- 适合本地开发与集成环境
- 前端同域反代可以面对单一 backend
- 比按路径把前端网关分流到两套后端更易维护

### 1.1 一键 Compose 部署（按文件名切换模式）

项目按"模式 ↔ Compose 文件"一一对应的方式支持一键部署。换文件名即可换模式：

| 模式 | Compose 文件 | 一键命令 |
|---|---|---|
| **unified**（默认） | [docker-compose.yml](../docker-compose.yml) | `docker compose up -d` |
| moldinsight-only | [docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml) | `docker compose -f docker-compose.moldinsight.yml up -d` |
| inventory-only | [docker-compose.inventory.yml](../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
# .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`：

```bash
bash deploy/build.sh        # 显式构建 base / backend / frontend 3 个镜像（celery 复用 backend）
```

或让 compose 构建：

```bash
docker compose up -d --build
```

> **注意**：`docker compose up -d` 在本地已有同名镜像（如 `gemold-backend:latest`）时**不会自动重建**，会直接复用旧镜像启动。更新代码或 Dockerfile 后，必须 `docker compose build` 或 `docker compose up -d --build` 才会生效。

详细 Linux 部署步骤：
- [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)

---

## 2. 支持的部署模式

### 2.1 unified

一个统一后端同时挂载 moldinsight + inventory。

适合：
- 本地开发
- 测试/集成环境
- 小团队统一部署

**Compose 文件**：[docker-compose.yml](../docker-compose.yml)（**默认入口**）

**一键命令**：

```bash
docker compose up -d
```

包含服务：`frontend` + `backend`（unified 入口）+ `moldinsight-celery`。

### 2.2 moldinsight-only

只部署模具分析后端。

适合：
- 独立开放分析能力
- 异步任务与文件处理独立扩容

**Compose 文件**：[docker-compose.moldinsight.yml](../docker-compose.moldinsight.yml)

**一键命令**：

```bash
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.inventory.yml)

**一键命令**：

```bash
docker compose -f docker-compose.inventory.yml up -d
```

包含服务：仅 `inventory`。不挂任何命名卷（inventory 无文件分析链路），不依赖 RustFS / MinIO。

部署模式的结构含义见 [ARCHITECTURE.md](ARCHITECTURE.md)。

---

## 3. 部署文档分工

### 3.1 当前权威文档

- [DEPLOYMENT.md](DEPLOYMENT.md)
  - 部署入口与文档导航
- [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)
  - Linux 环境下的详细部署操作说明

### 3.2 端口与配置说明

以下文档作为当前部署补充说明保留：
- [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)
- [deployment/PORT_CONFIG.md](deployment/PORT_CONFIG.md)

它们的职责分别是：
- `DEPLOY_PORT.md`：端口暴露、端口规划与 Nginx / 防火墙层面的说明
- `PORT_CONFIG.md`：环境变量、端口配置项与 direct run / compose 映射补充

它们是部署入口文档的补充参考，不替代本文或 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)。

### 3.3 历史/阶段性部署材料

以下材料属于迁移期或历史说明，不应再视为当前部署权威：
- [archive/PORT_REFACTOR_SUMMARY.md](archive/PORT_REFACTOR_SUMMARY.md)
- [archive/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md](archive/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md)

这些材料已迁入 `docs/archive/`，仅用于历史追溯，不替代当前的 [DEPLOYMENT.md](DEPLOYMENT.md) 、 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md) 与 [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)。

---

## 4. 当前部署事实

当前部署上的几个关键事实：

- 项目保持单仓库、单数据库
- frontend 是独立前端工程
- 后端支持模块化入口
- moldinsight 的异步分析链路依赖 celery
- PostgreSQL / Redis / 对象存储通常复用服务器已有服务，而不是必须由项目 compose 自带

这些事实的当前版本以 [STATUS.md](STATUS.md) 和 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md) 为准。

---

## 5. 相关专题文档

以下文档可作为部署/存储方向的补充参考，但不替代部署入口文档：

- [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)
- [deployment/PORT_CONFIG.md](deployment/PORT_CONFIG.md)
- [topics/storage/RUSTFS_STORAGE.md](topics/storage/RUSTFS_STORAGE.md)
- [topics/storage/STORAGE_SETUP.md](topics/storage/STORAGE_SETUP.md)

---

## 6. 后续整理原则

部署文档后续将遵循以下规则：

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