cjw
b03431b511
- DEPLOYMENT §1.2 / LINUX_SETUP §11 / README / OPERATIONS 补充： docker compose up -d 对本地已有同名镜像不会自动重建，更新代码后 需 up -d --build 或先 build（部署机实测复用旧镜像后澄清） - build.sh 描述由四步修正为 base → backend → frontend 三步（celery 复用 backend 镜像，随 Dockerfile.celery 移除的文档收尾） Co-Authored-By: Claude Code <noreply@anthropic.com>
443 lines
11 KiB
Markdown
443 lines
11 KiB
Markdown
# geMoldInsight Linux 部署指南
|
||
|
||
> 文档定位：**Linux 环境下的详细部署操作文档**。
|
||
> 当前部署主题入口见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，当前项目状态见 [../STATUS.md](../STATUS.md)，当前架构边界见 [../ARCHITECTURE.md](../ARCHITECTURE.md)。
|
||
> 本文档描述的是 **当前模块化架构** 下的 Linux 部署方式，而不是历史单体入口方案。
|
||
|
||
当前项目支持三种部署模式：
|
||
|
||
- **unified**：frontend + unified backend + moldinsight Celery worker，统一对外部署（当前推荐）
|
||
- **moldinsight-only**：仅部署模具分析后端
|
||
- **inventory-only**：仅部署进销存后端
|
||
|
||
项目保持：
|
||
|
||
- **同一 Git 仓库**
|
||
- **同一 PostgreSQL 数据库**
|
||
- **共享认证体系**
|
||
- **按模块独立部署**
|
||
- **复用服务器上已存在的 PostgreSQL / Redis / RustFS(或 MinIO 兼容存储)**
|
||
|
||
详细架构蓝图见：
|
||
- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
|
||
|
||
---
|
||
|
||
## 1. 系统要求
|
||
|
||
### 基础要求
|
||
- Linux（Ubuntu 22.04+ / Debian 12+ / CentOS Stream 9+）
|
||
- Python 3.12
|
||
- Git
|
||
- 服务器上已可访问的 PostgreSQL 15+
|
||
- 服务器上已可访问的 Redis 7+
|
||
|
||
### 按模块附加要求
|
||
|
||
#### moldinsight / unified 需要
|
||
- 服务器上已可访问的 MinIO 或 RustFS 兼容对象存储
|
||
- PythonOCC 运行环境
|
||
- Celery worker（推荐与 moldinsight 一起部署）
|
||
|
||
#### inventory-only 需要
|
||
- PostgreSQL
|
||
- Redis
|
||
- 不依赖 MinIO / RustFS
|
||
- 不依赖 Celery worker
|
||
|
||
---
|
||
|
||
## 2. 代码获取与目录约定
|
||
|
||
```bash
|
||
cd /opt
|
||
sudo git clone <your-repo-url> geMoldInsight
|
||
sudo chown -R $USER:$USER geMoldInsight
|
||
cd geMoldInsight
|
||
```
|
||
|
||
后续示例默认项目位于：
|
||
|
||
```bash
|
||
/opt/geMoldInsight
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Python 环境准备
|
||
|
||
```bash
|
||
python3.12 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
> 如果需要 moldinsight 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
|
||
|
||
---
|
||
|
||
## 4. 环境变量配置
|
||
|
||
复制模板：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
或部署场景参考：
|
||
|
||
```bash
|
||
cp deploy/.env.example .env
|
||
```
|
||
|
||
至少需要配置（并指向服务器上已存在的基础设施）：
|
||
|
||
```env
|
||
HOST=0.0.0.0
|
||
PORT=8000
|
||
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=5432
|
||
DB_NAME=moldinsight
|
||
DB_USER=moldinsight_user
|
||
DB_PASSWORD=change-me
|
||
|
||
REDIS_HOST=127.0.0.1
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=
|
||
|
||
SECRET_KEY=change-me-in-production
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=change-me
|
||
|
||
RUSTFS_ENDPOINT=http://127.0.0.1:9000
|
||
RUSTFS_ACCESS_KEY=minioadmin
|
||
RUSTFS_SECRET_KEY=minioadmin
|
||
```
|
||
|
||
说明：
|
||
- `RUSTFS_*` 仅 **moldinsight / unified** 模式需要
|
||
- `inventory-only` 可不使用对象存储
|
||
- 当前配置读取实现见 [settings.py](../../src/shared/config/settings.py)
|
||
|
||
---
|
||
|
||
## 5. 数据库初始化
|
||
|
||
项目当前使用 Alembic 管理迁移，应用启动时也会执行初始化流程。
|
||
|
||
首次部署建议：
|
||
|
||
1. 确保服务器上的 PostgreSQL / Redis / 对象存储服务已可访问
|
||
2. 启动应用前确认 `.env` 中的 `DB_HOST` / `REDIS_HOST` / `RUSTFS_ENDPOINT` 指向真实服务地址
|
||
3. 让应用执行初始化/升级逻辑
|
||
|
||
相关实现参考：
|
||
- [init_db.py](../../src/shared/database/init_db.py)
|
||
|
||
> 当前项目是 **单数据库** 设计，因此 unified / moldinsight-only / inventory-only 都连接到同一个数据库与同一 migration head。
|
||
|
||
---
|
||
|
||
## 6. 启动方式
|
||
|
||
## 6.0 frontend（同域反代入口）
|
||
|
||
当前推荐把前端作为独立静态站点部署，并通过同域 Nginx 反代到 unified backend：
|
||
|
||
- `/` → 前端静态资源与 SPA 路由
|
||
- `/api` → unified backend
|
||
- `/health` → unified backend
|
||
- `/html` → unified backend（内部再提供 moldinsight 分析产物）
|
||
|
||
如果使用 [docker-compose.yml](../../docker-compose.yml)（unified 模式）的 `frontend` 服务，则该入口已经内置在前端 Nginx 镜像中。
|
||
|
||
---
|
||
|
||
## 6.1 inventory-only
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
|
||
```
|
||
|
||
适合：
|
||
- 只提供进销存能力
|
||
- 不需要模具分析与异步任务
|
||
|
||
---
|
||
|
||
## 6.2 moldinsight-only
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
适合：
|
||
- 单独部署模具分析能力
|
||
- 文件上传 / 分析 / 导出 / 批量分析
|
||
|
||
### moldinsight Celery worker
|
||
|
||
建议同时启动 worker：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
celery -A src.celery_app.celery_app worker --loglevel=info
|
||
```
|
||
|
||
> moldinsight 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
|
||
|
||
---
|
||
|
||
## 6.3 unified
|
||
|
||
`unified` 是当前推荐的默认部署方式，适合 frontend 同域反代到单一 backend 的本地开发、集成环境与统一部署场景。
|
||
|
||
如需按模块独立部署，则使用 `moldinsight-only` 或 `inventory-only` 入口；它们仍共享同一个仓库、同一个数据库与同一套基础设施。
|
||
|
||
当前入口与部署编排见：
|
||
- [../../docker-compose.yml](../../docker-compose.yml)（默认 unified）
|
||
- [../../docker-compose.moldinsight.yml](../../docker-compose.moldinsight.yml)
|
||
- [../../docker-compose.inventory.yml](../../docker-compose.inventory.yml)
|
||
- [../../src/entrypoints/unified.py](../../src/entrypoints/unified.py)
|
||
|
||
---
|
||
|
||
## 7. systemd 部署示例
|
||
|
||
## 7.1 inventory-only 服务
|
||
|
||
创建：
|
||
|
||
```bash
|
||
sudo nano /etc/systemd/system/moldinsight-inventory.service
|
||
```
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=geMoldInsight Inventory API
|
||
After=network.target postgresql.service redis.service
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=www-data
|
||
Group=www-data
|
||
WorkingDirectory=/opt/geMoldInsight
|
||
Environment=PATH=/opt/geMoldInsight/.venv/bin
|
||
ExecStart=/opt/geMoldInsight/.venv/bin/uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
启用：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable moldinsight-inventory
|
||
sudo systemctl start moldinsight-inventory
|
||
```
|
||
|
||
---
|
||
|
||
## 7.2 moldinsight-only API 服务
|
||
|
||
创建：
|
||
|
||
```bash
|
||
sudo nano /etc/systemd/system/moldinsight-moldinsight.service
|
||
```
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=geMoldInsight MoldInsight API
|
||
After=network.target postgresql.service redis.service
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=www-data
|
||
Group=www-data
|
||
WorkingDirectory=/opt/geMoldInsight
|
||
Environment=PATH=/opt/geMoldInsight/.venv/bin
|
||
ExecStart=/opt/geMoldInsight/.venv/bin/uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
---
|
||
|
||
## 7.3 moldinsight Celery worker 服务
|
||
|
||
创建：
|
||
|
||
```bash
|
||
sudo nano /etc/systemd/system/moldinsight-celery.service
|
||
```
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=geMoldInsight MoldInsight Celery Worker
|
||
After=network.target postgresql.service redis.service
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=www-data
|
||
Group=www-data
|
||
WorkingDirectory=/opt/geMoldInsight
|
||
Environment=PATH=/opt/geMoldInsight/.venv/bin
|
||
ExecStart=/opt/geMoldInsight/.venv/bin/celery -A src.celery_app.celery_app worker --loglevel=info
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Nginx / 前端同域反代示例
|
||
|
||
当前仓库已提供前端 Nginx 配置：
|
||
- [deploy/nginx/frontend.conf](../../deploy/nginx/frontend.conf)
|
||
|
||
如果不使用仓库内 `frontend` 容器，也应遵循同样原则：
|
||
- `/` 提供前端静态资源与 SPA fallback
|
||
- `/api/` 反代后端
|
||
- `/health` 反代后端
|
||
- `/html/` 反代 moldinsight
|
||
|
||
### 8.1 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;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 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;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.3 unified（示意）
|
||
|
||
统一对外时，可由网关做模块路由，也可直接暴露统一组合后的应用入口。组合层标准化完成前，更推荐通过部署编排或网关来实现统一对外访问。
|
||
|
||
---
|
||
|
||
## 9. 验证部署
|
||
|
||
### 9.1 健康检查
|
||
|
||
inventory-only：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8001/health
|
||
```
|
||
|
||
moldinsight-only：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/health
|
||
```
|
||
|
||
### 9.2 基础能力验证
|
||
|
||
#### inventory-only
|
||
- 登录接口可用
|
||
- `/api/products` 返回数据
|
||
- `/api/inventory` 返回数据
|
||
|
||
#### moldinsight-only
|
||
- 登录接口可用
|
||
- `/api/upload` 可访问
|
||
- 上传后 worker 能正常消费任务
|
||
- `/api/status/{task_id}` 能看到进度
|
||
|
||
---
|
||
|
||
## 10. 常见问题
|
||
|
||
### 1. 为什么不再推荐 `src.main:app`？
|
||
因为当前项目已演进为模块化结构，`src.main:app` 更适合作为过渡兼容入口，而不是长期部署标准。应优先围绕 [entrypoints/](../../src/entrypoints/) 部署。
|
||
|
||
### 2. inventory-only 为什么不需要对象存储？
|
||
因为对象存储主要服务于 moldinsight 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
|
||
|
||
### 3. moldinsight-only 为什么建议同时部署 Celery？
|
||
因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。
|
||
|
||
---
|
||
|
||
## 11. Docker Compose 说明
|
||
|
||
仓库根目录维护 3 个独立 compose 文件，按文件名映射部署模式：
|
||
|
||
| 模式 | Compose 文件 | 一键命令 |
|
||
|---|---|---|
|
||
| unified（默认） | [docker-compose.yml](../../docker-compose.yml) | `docker compose up -d` |
|
||
| moldinsight-only | [docker-compose.moldinsight.yml](../../docker-compose.moldinsight.yml) | `docker compose -f docker-compose.moldinsight.yml up -d` |
|
||
| inventory-only | [docker-compose.inventory.yml](../../docker-compose.inventory.yml) | `docker compose -f docker-compose.inventory.yml up -d` |
|
||
|
||
> 注意：各 service 均未声明 `profiles`，旧 `--profile full/moldinsight/inventory` 写法不再是模式开关（声明了 profiles 的服务在裸 `up` 下不会被选中，会报 `no service selected`）；模式切换统一用上表 `-f` 命令。
|
||
|
||
不同模式分别包含的服务：
|
||
|
||
- **unified**：`frontend` + `backend`（unified 入口）+ `moldinsight-celery`
|
||
- **moldinsight-only**：`moldinsight`（独立 API）+ `moldinsight-celery`
|
||
- **inventory-only**：仅 `inventory`
|
||
|
||
任一 compose 文件**都不会**再拉起：
|
||
|
||
- PostgreSQL
|
||
- Redis
|
||
- MinIO / RustFS
|
||
|
||
这些基础设施应由服务器现有服务提供，并通过 `.env` 传入连接信息；前端则由 `frontend` 容器独立提供（仅 unified 模式包含），通过同域反代转发到后端。
|
||
|
||
镜像构建：
|
||
|
||
```bash
|
||
bash deploy/build.sh # base → backend → frontend（celery 复用 backend 镜像）
|
||
# 或让 compose 构建：docker compose up -d --build
|
||
# 注意：docker compose up -d 对本地已有同名镜像不会自动重建，更新代码后需 --build
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 推荐阅读
|
||
|
||
- [README.md](../../README.md)
|
||
- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
|
||
- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
|
||
- [PORT_CONFIG.md](./PORT_CONFIG.md)
|