geMoldInsight/docs/deployment/DEPLOY_PORT.md

# 模块化部署端口说明

> 本文档描述的是 **当前模块化部署模式** 下的端口规划，不再以历史单体 `src.main:app` 作为默认前提。

当前推荐部署对象：

- gemold API
- gemold Celery worker（无 HTTP 端口）
- inventory API

以下基础设施默认由服务器现有服务提供，不在本项目 compose 中重复部署：

- PostgreSQL
- Redis
- MinIO / RustFS（gemold 需要）

---

## 1. 推荐端口规划

| 组件 | 默认端口 | 说明 |
|---|---:|---|
| gemold API | 8000 | 模具分析后端 |
| inventory API | 8001 | 进销存后端 |
| PostgreSQL | 5432 | 共享数据库 |
| Redis | 6379 | 共享队列/缓存 |
| MinIO API | 9000 | 对象存储接口 |
| MinIO Console | 9001 | 对象存储控制台 |

> Celery worker 不直接暴露 HTTP 端口。

---

## 2. 三种部署模式下的端口

### 2.1 gemold-only

- 对外开放：`8000`
- 依赖：PostgreSQL、Redis、MinIO/RustFS
- 可选：前置 Nginx 暴露 80/443

### 2.2 inventory-only

- 对外开放：`8001`
- 依赖：PostgreSQL、Redis
- 不要求对象存储

### 2.3 unified

两种常见实现：

1. **统一网关模式**
   - 外部只开放 80/443
   - 网关转发到 gemold / inventory
2. **统一应用组合模式**
   - 统一后端监听单一端口
   - 后续组合层重构完成后更适合采用

当前阶段，如果需要统一对外，更推荐**网关统一**而不是继续依赖历史单体入口。

---

## 3. Docker Compose 端口来源

当前主部署文件：
- [docker-compose.yml](../../docker-compose.yml)

关键端口映射：

- `MOLDINSIGHT_PORT` → gemold API 外部端口
- `INVENTORY_PORT` → inventory API 外部端口

示例：

```env
MOLDINSIGHT_PORT=8000
INVENTORY_PORT=8001
```

对应 compose 行为：

- gemold：`${MOLDINSIGHT_PORT:-8000}:8000`
- inventory：`${INVENTORY_PORT:-8001}:8001`

---

## 4. 直接运行时的端口约定

### gemold-only

```bash
uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
```

### inventory-only

```bash
uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
```

如果改端口：
- gemold 改 `--port`
- inventory 改 `--port`
- 同步更新 Nginx / 防火墙 / 前端 base URL

---

## 5. 前端联动

如果前端与后端分开部署，需要与前端环境变量保持一致。

建议前端支持：

### unified 模式
```env
VITE_API_BASE_URL=https://api.example.com
```

### split 模式
```env
VITE_AUTH_API_BASE_URL=https://auth.example.com
VITE_MOLDINSIGHT_API_BASE_URL=https://gemold.example.com
VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
```

当前详细策略见：
- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)

---

## 6. Nginx 示例

### gemold-only

```nginx
server {
    listen 80;
    server_name gemold.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### inventory-only

```nginx
server {
    listen 80;
    server_name inventory.example.com;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

---

## 7. 防火墙建议

如果不通过 Nginx 统一入口而是直接暴露服务端口，则应显式开放：

```bash
# gemold
sudo ufw allow 8000/tcp

# inventory
sudo ufw allow 8001/tcp
```

生产环境更推荐：
- 外部只开放 80/443
- 内部仅开放 8000/8001 给 Nginx 或内网访问

---

## 8. 快速检查

```bash
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8001/health
```

如果只部署单模块，只检查对应服务即可。

---

## 9. 结论

在当前模块化架构下：

- gemold 与 inventory 应视为**两个独立后端模块**
- 端口应按模块分配，而不是继续沿用单体“一个后端一个端口”的思路
- unified 更适合通过**组合层或网关**实现，而不是继续让历史单体入口承载全部语义