cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

x

Browse Source
This commit is contained in:
chenjw28
2026-09-02 18:18:42 +08:00
parent 5e531ffe1e
commit 4fbff0761a
18 changed files with 239 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment/DEPLOY_PORT.md
+21 -24
View File
@@ -2,19 +2,19 @@
> 文档定位：**当前部署下的端口规划补充说明**。
> 部署入口与当前推荐方案见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
> 本文档描述的是 **当前模块化部署模式** 下的端口规划，不再以历史单体 `src.main:app` 作为默认前提。
> 本文档负责 **当前模块化部署模式** 下的端口暴露、端口规划与 Nginx / 防火墙层面的补充说明，不再以历史单体 `src.main:app` 作为默认前提。
当前推荐部署对象：
- frontend（Nginx，同域入口）
- unified backend
- gemold Celery worker（无 HTTP 端口）
- moldinsight Celery worker（无 HTTP 端口）
以下基础设施默认由服务器现有服务提供，不在本项目 compose 中重复部署：
- PostgreSQL
- Redis
- MinIO / RustFS（gemold 需要）
- MinIO / RustFS（moldinsight 需要）
---
@@ -24,7 +24,7 @@
|---|---:|---|
| frontend | 80 | 前端 Nginx，同域入口 |
| unified backend | 8000 | 当前推荐统一后端 |
| gemold API | 8000 | 模具分析独立部署时使用 |
| moldinsight API | 8000 | 模具分析独立部署时使用 |
| inventory API | 8001 | 进销存独立部署时使用 |
| PostgreSQL | 5432 | 共享数据库 |
| Redis | 6379 | 共享队列/缓存 |
@@ -37,7 +37,7 @@
## 2. 三种部署模式下的端口
### 2.1 gemold-only
### 2.1 moldinsight-only
- 对外开放：`8000`
- 依赖：PostgreSQL、Redis、MinIO/RustFS
@@ -51,16 +51,13 @@
### 2.3 unified
两种常见实现：
当前推荐由 unified backend 提供单一后端入口：
1. **统一网关模式**
- 外部只开放 80/443
- 网关转发到 gemold / inventory
2. **统一应用组合模式**
- 统一后端监听单一端口
- 后续组合层重构完成后更适合采用
- 对外开放：`8000`（或由前置 Nginx / 网关统一暴露 80/443）
- 依赖：PostgreSQL、Redis、MinIO / RustFS
- 配套：moldinsight Celery worker 不直接暴露 HTTP 端口
当前阶段，如果需要统一对外，更推荐**网关统一**而不是继续依赖历史单体入口。
在生产环境中，仍推荐通过同域 Nginx / 网关统一对外暴露 80/443，再反代到 unified backend。
---
@@ -73,7 +70,7 @@
- `FRONTEND_PORT` → frontend Nginx 外部端口
- `BACKEND_PORT` → unified backend 外部端口
- `MOLDINSIGHT_PORT` → gemold-only 独立部署端口
- `MOLDINSIGHT_PORT` → moldinsight-only 独立部署端口
- `INVENTORY_PORT` → inventory-only 独立部署端口
示例：
@@ -85,14 +82,14 @@ INVENTORY_PORT=8001
对应 compose 行为：
- gemold：`${MOLDINSIGHT_PORT:-8000}:8000`
- moldinsight：`${MOLDINSIGHT_PORT:-8000}:8000`
- inventory：`${INVENTORY_PORT:-8001}:8001`
---
## 4. 直接运行时的端口约定
### gemold-only
### moldinsight-only
```bash
uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
@@ -105,7 +102,7 @@ uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
```
如果改端口：
- gemold 改 `--port`
- moldinsight 改 `--port`
- inventory 改 `--port`
- 同步更新 Nginx / 防火墙 / 前端 base URL
@@ -125,7 +122,7 @@ 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_MOLDINSIGHT_API_BASE_URL=https://moldinsight.example.com
VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
```
@@ -136,12 +133,12 @@ VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
## 6. Nginx 示例
### gemold-only
### moldinsight-only
```nginx
server {
listen 80;
server_name gemold.example.com;
server_name moldinsight.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
@@ -177,7 +174,7 @@ server {
如果不通过 Nginx 统一入口而是直接暴露服务端口，则应显式开放：
```bash
# gemold
# moldinsight
sudo ufw allow 8000/tcp
# inventory
@@ -205,6 +202,6 @@ curl http://127.0.0.1:8001/health
在当前模块化架构下：
- gemold 与 inventory 应视为**两个独立后端模块**
- 端口应按模块分配，而不是继续沿用单体“一个后端一个端口”的思路
- unified 更适合通过**组合层或网关**实现，而不是继续让历史单体入口承载全部语义
- moldinsight 与 inventory 应视为两个独立后端模块
- `unified` 是当前推荐部署模式，由 unified backend 提供单一后端入口
- 端口应按模块与部署模式清晰分配；生产环境通常通过同域 Nginx / 网关统一对外暴露 80/443
docs/deployment/LINUX_SETUP.md
+30 -29
View File
@@ -6,8 +6,8 @@
当前项目支持三种部署模式：
- **unified**：frontend + unified backend + celery，统一对外部署（当前推荐）
- **gemold-only**：仅部署模具分析后端
- **unified**：frontend + unified backend + moldinsight Celery worker，统一对外部署（当前推荐）
- **moldinsight-only**：仅部署模具分析后端
- **inventory-only**：仅部署进销存后端
项目保持：
@@ -34,10 +34,10 @@
### 按模块附加要求
#### gemold / unified 需要
#### moldinsight / unified 需要
- 服务器上已可访问的 MinIO 或 RustFS 兼容对象存储
- PythonOCC 运行环境
- Celery worker（推荐与 gemold 一起部署）
- Celery worker（推荐与 moldinsight 一起部署）
#### inventory-only 需要
- PostgreSQL
@@ -73,7 +73,7 @@ pip install --upgrade pip
pip install -r requirements.txt
```
> 如果需要 gemold 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
> 如果需要 moldinsight 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
---
@@ -117,7 +117,7 @@ RUSTFS_SECRET_KEY=minioadmin
```
说明：
- `RUSTFS_*` 仅 **gemold / unified** 模式需要
- `RUSTFS_*` 仅 **moldinsight / unified** 模式需要
- `inventory-only` 可不使用对象存储
- 当前配置读取实现见 [settings.py](../../src/shared/config/settings.py)
@@ -136,7 +136,7 @@ RUSTFS_SECRET_KEY=minioadmin
相关实现参考：
- [init_db.py](../../src/shared/database/init_db.py)
> 当前项目是 **单数据库** 设计，因此 unified / gemold-only / inventory-only 都连接到同一个数据库与同一 migration head。
> 当前项目是 **单数据库** 设计，因此 unified / moldinsight-only / inventory-only 都连接到同一个数据库与同一 migration head。
---
@@ -149,7 +149,7 @@ RUSTFS_SECRET_KEY=minioadmin
- `/` → 前端静态资源与 SPA 路由
- `/api` → unified backend
- `/health` → unified backend
- `/html` → unified backend（内部再提供 gemold 分析产物）
- `/html` → unified backend（内部再提供 moldinsight 分析产物）
如果使用根目录 [docker-compose.yml](../../docker-compose.yml) 的 `frontend` 服务，则该入口已经内置在前端 Nginx 镜像中。
@@ -168,7 +168,7 @@ uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
---
## 6.2 gemold-only
## 6.2 moldinsight-only
```bash
source .venv/bin/activate
@@ -179,7 +179,7 @@ uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
- 单独部署模具分析能力
- 文件上传 / 分析 / 导出 / 批量分析
### gemold Celery worker
### moldinsight Celery worker
建议同时启动 worker：
@@ -188,18 +188,19 @@ source .venv/bin/activate
celery -A src.celery_app.celery_app worker --loglevel=info
```
> gemold 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
> moldinsight 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
---
## 6.3 unified
当前仓库历史上存在过统一入口，但它更适合作为**过渡参考**，不建议再作为长期标准入口。
`unified` 是当前推荐的默认部署方式，适合 frontend 同域反代到单一 backend 的本地开发、集成环境与统一部署场景。
在正式完成组合层重构前，如需统一部署，可优先使用反向代理或部署编排层统一暴露 gemold 与 inventory；后续会演进为显式 `unified_app.py`。
如需按模块独立部署，则使用 `moldinsight-only` 或 `inventory-only` 入口；它们仍共享同一个仓库、同一个数据库与同一套基础设施。
蓝图参考：
- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
当前入口与部署编排见：
- [../../docker-compose.yml](../../docker-compose.yml)
- [../../src/entrypoints/unified.py](../../src/entrypoints/unified.py)
---
@@ -210,7 +211,7 @@ celery -A src.celery_app.celery_app worker --loglevel=info
创建：
```bash
sudo nano /etc/systemd/system/gemold-inventory.service
sudo nano /etc/systemd/system/moldinsight-inventory.service
```
```ini
@@ -236,18 +237,18 @@ WantedBy=multi-user.target
```bash
sudo systemctl daemon-reload
sudo systemctl enable gemold-inventory
sudo systemctl start gemold-inventory
sudo systemctl enable moldinsight-inventory
sudo systemctl start moldinsight-inventory
```
---
## 7.2 gemold-only API 服务
## 7.2 moldinsight-only API 服务
创建：
```bash
sudo nano /etc/systemd/system/gemold-moldinsight.service
sudo nano /etc/systemd/system/moldinsight-moldinsight.service
```
```ini
@@ -271,12 +272,12 @@ WantedBy=multi-user.target
---
## 7.3 gemold Celery worker 服务
## 7.3 moldinsight Celery worker 服务
创建：
```bash
sudo nano /etc/systemd/system/gemold-celery.service
sudo nano /etc/systemd/system/moldinsight-celery.service
```
```ini
@@ -309,7 +310,7 @@ WantedBy=multi-user.target
- `/` 提供前端静态资源与 SPA fallback
- `/api/` 反代后端
- `/health` 反代后端
- `/html/` 反代 gemold
- `/html/` 反代 moldinsight
### 8.1 inventory-only
@@ -328,12 +329,12 @@ server {
}
```
### 8.2 gemold-only
### 8.2 moldinsight-only
```nginx
server {
listen 80;
server_name gemold.example.com;
server_name moldinsight.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
@@ -361,7 +362,7 @@ inventory-only：
curl http://127.0.0.1:8001/health
```
gemold-only：
moldinsight-only：
```bash
curl http://127.0.0.1:8000/health
@@ -374,7 +375,7 @@ curl http://127.0.0.1:8000/health
- `/api/products` 返回数据
- `/api/inventory` 返回数据
#### gemold-only
#### moldinsight-only
- 登录接口可用
- `/api/upload` 可访问
- 上传后 worker 能正常消费任务
@@ -388,9 +389,9 @@ curl http://127.0.0.1:8000/health
因为当前项目已演进为模块化结构，`src.main:app` 更适合作为过渡兼容入口，而不是长期部署标准。应优先围绕 [entrypoints/](../../src/entrypoints/) 部署。
### 2. inventory-only 为什么不需要对象存储？
因为对象存储主要服务于 gemold 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
因为对象存储主要服务于 moldinsight 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
### 3. gemold-only 为什么建议同时部署 Celery？
### 3. moldinsight-only 为什么建议同时部署 Celery？
因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。
---
docs/deployment/PORT_CONFIG.md
+17 -37
View File
@@ -2,17 +2,15 @@
> 文档定位：**模块化部署下的端口与环境变量配置补充说明**。
> 当前部署主题入口见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，详细 Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
> 本文档说明当前 geMoldInsight 在**模块化部署**下的端口配置方式。
> 本文只补充环境变量、端口配置项与 direct run / compose 的映射；端口规划与对外暴露方式以 [DEPLOY_PORT.md](./DEPLOY_PORT.md) 为准。
当前架构中应区分：
当前配置中主要需要区分：
- **gemold API 端口**
- **moldinsight API 端口**
- **inventory API 端口**
- **数据库/Redis/对象存储端口**
- **数据库 / Redis / 对象存储端口**
- **前端访问地址**
不再推荐把所有部署场景都抽象成“单应用单端口”。
---
## 1. 当前主配置位置
@@ -54,7 +52,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
|---|---|
| `FRONTEND_PORT` | 前端 Nginx 宿主机暴露端口 |
| `BACKEND_PORT` | unified backend 宿主机暴露端口 |
| `MOLDINSIGHT_PORT` | gemold-only 独立部署端口 |
| `MOLDINSIGHT_PORT` | moldinsight-only 独立部署端口 |
| `INVENTORY_PORT` | inventory-only 独立部署端口 |
| `DB_PORT` | PostgreSQL 端口 |
| `REDIS_PORT` | Redis 端口 |
@@ -65,7 +63,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
## 3. 推荐配置方式
### 3.1 gemold-only
### 3.1 moldinsight-only
```env
MOLDINSIGHT_PORT=8000
@@ -92,30 +90,13 @@ REDIS_PORT=6379
---
## 4. 为什么不再强调单一 `PORT` 变量
## 4. direct run 与 Compose 的映射
历史单体部署通常只有一个后端入口，因此 `PORT=8000` 足够。
通过直接运行或 Docker Compose 部署时，端口含义保持一致，但映射方式不同。
当前项目已经是：
- gemold 独立入口
- inventory 独立入口
- unified 作为组合模式而非默认单体入口
### direct run
因此端口配置必须模块化：
- gemold 一个端口
- inventory 一个端口
- 如果 unified 对外存在，可以由网关统一暴露 80/443
这比继续强行把所有模式压成一个 `PORT` 更清晰，也更符合真实部署方式。
---
## 5. 直接运行与 Compose 的区别
### 直接运行
gemold：
moldinsight：
```bash
uvicorn src.entrypoints.moldinsight:app --port 8000
@@ -131,7 +112,7 @@ uvicorn src.entrypoints.inventory:app --port 8001
Compose 通过端口映射暴露服务：
- gemold → `${MOLDINSIGHT_PORT}:8000`
- moldinsight → `${MOLDINSIGHT_PORT}:8000`
- inventory → `${INVENTORY_PORT}:8001`
当前实际定义见：
@@ -139,7 +120,7 @@ Compose 通过端口映射暴露服务：
---
## 6. 与前端配置的关系
## 5. 与前端配置的关系
前端是否使用 unified / split deployment，会影响前端 API 地址配置。
@@ -147,7 +128,7 @@ Compose 通过端口映射暴露服务：
- 一个 API 基地址
### split
- gemold 与 inventory 各自基地址
- moldinsight 与 inventory 各自基地址
因此，修改后端端口后，可能还需要同步：
@@ -157,22 +138,21 @@ Compose 通过端口映射暴露服务：
---
## 7. 推荐实践
## 6. 推荐实践
1. **本地开发**
- gemold：8000
- moldinsight：8000
- inventory：8001
2. **服务器部署**
- 外网只暴露 80/443
- Nginx 反代到 8000 / 8001
3. **不要继续把所有部署模式都写成 `src.main:app + PORT=8000`**
- 这已不符合当前架构
3. 修改端口后，同步检查 `.env`、Compose 端口映射、前端环境变量与反向代理配置
---
## 8. 关联文档
## 7. 关联文档
- [LINUX_SETUP.md](./LINUX_SETUP.md)
- [DEPLOY_PORT.md](./DEPLOY_PORT.md)