cjw
b934b737e8
上一版把 frontend 与 backend 都映射 10003:8000，会触发 docker 启动时 "bind: address already in use"。修正： - docker-compose.yml backend ports 改为 expose: ["8000"]——不映射宿主机， 仅在 docker 网络 gemold_network 内被 frontend 经 backend:8000 反代访问 - .env.example 删除 BACKEND_PORT 字段（不再需要） - PORT_CONFIG / DEPLOY_PORT 端口映射表/示例同步：unified backend 不暴露 宿主机端口，统一经前端 /api 反代 验证：yaml 渲染后无任何 service 对抢宿主端口（unified 仅 frontend 暴露 $FRONTEND_PORT=10003；moldinsight-only 仅 moldinsight 暴露 10003； inventory-only 仅 inventory 暴露 10004）。 Co-Authored-By: Claude Code <noreply@anthropic.com>
212 lines
5.3 KiB
Markdown
212 lines
5.3 KiB
Markdown
# 模块化部署端口说明
|
||
|
||
> 文档定位：**当前部署下的端口规划补充说明**。
|
||
> 部署入口与当前推荐方案见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
|
||
> 本文档负责 **当前模块化部署模式** 下的端口暴露、端口规划与 Nginx / 防火墙层面的补充说明，不再以历史单体 `src.main:app` 作为默认前提。
|
||
|
||
当前推荐部署对象：
|
||
|
||
- frontend（Nginx，同域入口）
|
||
- unified backend
|
||
- moldinsight Celery worker（无 HTTP 端口）
|
||
|
||
以下基础设施默认由服务器现有服务提供，不在本项目 compose 中重复部署：
|
||
|
||
- PostgreSQL
|
||
- Redis
|
||
- MinIO / RustFS（moldinsight 需要）
|
||
|
||
---
|
||
|
||
## 1. 推荐端口规划
|
||
|
||
| 组件 | 默认端口 | 说明 |
|
||
|---|---:|---|
|
||
| frontend | 80 | 前端 Nginx，同域入口 |
|
||
| unified backend | 8000 | 当前推荐统一后端 |
|
||
| moldinsight API | 8000 | 模具分析独立部署时使用 |
|
||
| inventory API | 8001 | 进销存独立部署时使用 |
|
||
| PostgreSQL | 5432 | 共享数据库 |
|
||
| Redis | 6379 | 共享队列/缓存 |
|
||
| MinIO API | 9000 | 对象存储接口 |
|
||
| MinIO Console | 9001 | 对象存储控制台 |
|
||
|
||
> Celery worker 不直接暴露 HTTP 端口。
|
||
|
||
---
|
||
|
||
## 2. 三种部署模式下的端口
|
||
|
||
### 2.1 moldinsight-only
|
||
|
||
- 对外开放：`8000`
|
||
- 依赖：PostgreSQL、Redis、MinIO/RustFS
|
||
- 可选：前置 Nginx 暴露 80/443
|
||
|
||
### 2.2 inventory-only
|
||
|
||
- 对外开放：`8001`
|
||
- 依赖：PostgreSQL、Redis
|
||
- 不要求对象存储
|
||
|
||
### 2.3 unified
|
||
|
||
当前推荐由 unified backend 提供单一后端入口：
|
||
|
||
- 对外开放：`8000`（或由前置 Nginx / 网关统一暴露 80/443）
|
||
- 依赖：PostgreSQL、Redis、MinIO / RustFS
|
||
- 配套：moldinsight Celery worker 不直接暴露 HTTP 端口
|
||
|
||
在生产环境中，仍推荐通过同域 Nginx / 网关统一对外暴露 80/443，再反代到 unified backend。
|
||
|
||
---
|
||
|
||
## 3. Docker Compose 端口来源
|
||
|
||
当前主部署文件：
|
||
- [docker-compose.yml](../../docker-compose.yml)（unified，默认入口）
|
||
- [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 外部端口（浏览器入口，推荐直接访问）
|
||
- unified backend → **不暴露宿主机端口**，经前端 /api 反代同域访问（docker 网络内 `backend:8000` 互通）
|
||
- `MOLDINSIGHT_PORT` → moldinsight-only 模式宿主机端口
|
||
- `INVENTORY_PORT` → inventory-only 模式宿主机端口
|
||
- `MOLDINSIGHT_PORT` → moldinsight-only 独立部署端口
|
||
- `INVENTORY_PORT` → inventory-only 独立部署端口
|
||
|
||
示例：
|
||
|
||
```env
|
||
MOLDINSIGHT_PORT=10003
|
||
INVENTORY_PORT=10004
|
||
```
|
||
|
||
对应 compose 行为：
|
||
|
||
- moldinsight：`${MOLDINSIGHT_PORT:-10003}:8000`
|
||
- inventory：`${INVENTORY_PORT:-10004}:8001`
|
||
|
||
---
|
||
|
||
## 4. 直接运行时的端口约定
|
||
|
||
### moldinsight-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
|
||
```
|
||
|
||
如果改端口：
|
||
- moldinsight 改 `--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://moldinsight.example.com
|
||
VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
|
||
```
|
||
|
||
当前详细策略见：
|
||
- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
|
||
|
||
---
|
||
|
||
## 6. Nginx 示例
|
||
|
||
### moldinsight-only
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name moldinsight.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
|
||
# moldinsight
|
||
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. 结论
|
||
|
||
在当前模块化架构下：
|
||
|
||
- moldinsight 与 inventory 应视为两个独立后端模块
|
||
- `unified` 是当前推荐部署模式，由 unified backend 提供单一后端入口
|
||
- 端口应按模块与部署模式清晰分配；生产环境通常通过同域 Nginx / 网关统一对外暴露 80/443
|