geMoldInsight/docs/deployment/DEPLOY_PORT.md

模块化部署端口说明

文档定位：当前部署下的端口规划补充说明。 部署入口与当前推荐方案见 ../DEPLOYMENT.md，Linux 部署步骤见 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

关键端口映射：

• FRONTEND_PORT → frontend Nginx 外部端口
• BACKEND_PORT → unified backend 外部端口
• MOLDINSIGHT_PORT → moldinsight-only 独立部署端口
• INVENTORY_PORT → inventory-only 独立部署端口

示例：

MOLDINSIGHT_PORT=8000
INVENTORY_PORT=8001

对应 compose 行为：

• moldinsight：${MOLDINSIGHT_PORT:-8000}:8000
• inventory：${INVENTORY_PORT:-8001}:8001

---

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

moldinsight-only

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

inventory-only

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

如果改端口：

• moldinsight 改 --port
• inventory 改 --port
• 同步更新 Nginx / 防火墙 / 前端 base URL

---

5. 前端联动

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

建议前端支持：

unified 模式

VITE_API_BASE_URL=https://api.example.com

split 模式

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

---

6. Nginx 示例

moldinsight-only

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

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 统一入口而是直接暴露服务端口，则应显式开放：

# moldinsight
sudo ufw allow 8000/tcp

# inventory
sudo ufw allow 8001/tcp

生产环境更推荐：

• 外部只开放 80/443
• 内部仅开放 8000/8001 给 Nginx 或内网访问

---

8. 快速检查

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