geMoldInsight/docs/deployment/PORT_CONFIG.md

# 端口配置说明（模块化架构）

> 文档定位：**模块化部署下的端口与环境变量配置补充说明**。
> 当前部署主题入口见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，详细 Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
> 本文档说明当前 geMoldInsight 在**模块化部署**下的端口配置方式。

当前架构中应区分：

- **gemold API 端口**
- **inventory API 端口**
- **数据库/Redis/对象存储端口**
- **前端访问地址**

不再推荐把所有部署场景都抽象成“单应用单端口”。

---

## 1. 当前主配置位置

对于 Docker Compose 部署，当前主要端口配置来源于：

- [docker-compose.yml](../../docker-compose.yml)
- `.env` / `deploy/.env.example`

注意：该 compose 文件仅负责项目应用容器，不负责 PostgreSQL / Redis / 对象存储容器。

核心环境变量：

```env
FRONTEND_PORT=80
BACKEND_PORT=8000
MOLDINSIGHT_PORT=8000
INVENTORY_PORT=8001
```

其余基础设施通常为：

```env
DB_PORT=5432
REDIS_PORT=6379
```

对象存储常见端口（由服务器既有服务提供）：

```env
RUSTFS_ENDPOINT=http://localhost:9000
```

---

## 2. 各端口的含义

| 变量 / 端口 | 用途 |
|---|---|
| `FRONTEND_PORT` | 前端 Nginx 宿主机暴露端口 |
| `BACKEND_PORT` | unified backend 宿主机暴露端口 |
| `MOLDINSIGHT_PORT` | gemold-only 独立部署端口 |
| `INVENTORY_PORT` | inventory-only 独立部署端口 |
| `DB_PORT` | PostgreSQL 端口 |
| `REDIS_PORT` | Redis 端口 |
| `9000` | MinIO/RustFS S3 兼容 API |
| `9001` | MinIO 控制台 |

---

## 3. 推荐配置方式

### 3.1 gemold-only

```env
MOLDINSIGHT_PORT=8000
DB_PORT=5432
REDIS_PORT=6379
```

### 3.2 inventory-only

```env
INVENTORY_PORT=8001
DB_PORT=5432
REDIS_PORT=6379
```

### 3.3 full / 模块同时部署

```env
MOLDINSIGHT_PORT=8000
INVENTORY_PORT=8001
DB_PORT=5432
REDIS_PORT=6379
```

---

## 4. 为什么不再强调单一 `PORT` 变量

历史单体部署通常只有一个后端入口，因此 `PORT=8000` 足够。

当前项目已经是：
- gemold 独立入口
- inventory 独立入口
- unified 作为组合模式而非默认单体入口

因此端口配置必须模块化：

- gemold 一个端口
- inventory 一个端口
- 如果 unified 对外存在，可以由网关统一暴露 80/443

这比继续强行把所有模式压成一个 `PORT` 更清晰，也更符合真实部署方式。

---

## 5. 直接运行与 Compose 的区别

### 直接运行

gemold：

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

inventory：

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

### Docker Compose

Compose 通过端口映射暴露服务：

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

当前实际定义见：
- [docker-compose.yml](../../docker-compose.yml)

---

## 6. 与前端配置的关系

前端是否使用 unified / split deployment，会影响前端 API 地址配置。

### unified
- 一个 API 基地址

### split
- gemold 与 inventory 各自基地址

因此，修改后端端口后，可能还需要同步：

- 前端 `.env`
- Nginx 反向代理
- 浏览器访问地址

---

## 7. 推荐实践

1. **本地开发**
   - gemold：8000
   - inventory：8001

2. **服务器部署**
   - 外网只暴露 80/443
   - Nginx 反代到 8000 / 8001

3. **不要继续把所有部署模式都写成 `src.main:app + PORT=8000`**
   - 这已不符合当前架构

---

## 8. 关联文档

- [LINUX_SETUP.md](./LINUX_SETUP.md)
- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
- [README.md](../../README.md)