9.8 KiB
geMoldInsight Linux 部署指南
文档定位：Linux 环境下的详细部署操作文档。 当前部署主题入口见 ../DEPLOYMENT.md，当前项目状态见 ../STATUS.md，当前架构边界见 ../ARCHITECTURE.md。 本文档描述的是 当前模块化架构 下的 Linux 部署方式，而不是历史单体入口方案。
当前项目支持三种部署模式：
- unified：frontend + unified backend + celery，统一对外部署（当前推荐）
- gemold-only：仅部署模具分析后端
- inventory-only：仅部署进销存后端
项目保持：
- 同一 Git 仓库
- 同一 PostgreSQL 数据库
- 共享认证体系
- 按模块独立部署
- 复用服务器上已存在的 PostgreSQL / Redis / RustFS(或 MinIO 兼容存储)
详细架构蓝图见：
1. 系统要求
基础要求
- Linux（Ubuntu 22.04+ / Debian 12+ / CentOS Stream 9+）
- Python 3.12
- Git
- 服务器上已可访问的 PostgreSQL 15+
- 服务器上已可访问的 Redis 7+
按模块附加要求
gemold / unified 需要
- 服务器上已可访问的 MinIO 或 RustFS 兼容对象存储
- PythonOCC 运行环境
- Celery worker（推荐与 gemold 一起部署）
inventory-only 需要
- PostgreSQL
- Redis
- 不依赖 MinIO / RustFS
- 不依赖 Celery worker
2. 代码获取与目录约定
cd /opt
sudo git clone <your-repo-url> geMoldInsight
sudo chown -R $USER:$USER geMoldInsight
cd geMoldInsight
后续示例默认项目位于：
/opt/geMoldInsight
3. Python 环境准备
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
如果需要 gemold 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
4. 环境变量配置
复制模板：
cp .env.example .env
或部署场景参考：
cp deploy/.env.example .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_*仅 gemold / unified 模式需要inventory-only可不使用对象存储- 当前配置读取实现见 settings.py
5. 数据库初始化
项目当前使用 Alembic 管理迁移，应用启动时也会执行初始化流程。
首次部署建议：
- 确保服务器上的 PostgreSQL / Redis / 对象存储服务已可访问
- 启动应用前确认
.env中的DB_HOST/REDIS_HOST/RUSTFS_ENDPOINT指向真实服务地址 - 让应用执行初始化/升级逻辑
相关实现参考：
当前项目是 单数据库 设计，因此 unified / gemold-only / inventory-only 都连接到同一个数据库与同一 migration head。
6. 启动方式
6.0 frontend（同域反代入口）
当前推荐把前端作为独立静态站点部署，并通过同域 Nginx 反代到 unified backend：
/→ 前端静态资源与 SPA 路由/api→ unified backend/health→ unified backend/html→ unified backend（内部再提供 gemold 分析产物）
如果使用根目录 docker-compose.yml 的 frontend 服务，则该入口已经内置在前端 Nginx 镜像中。
6.1 inventory-only
source .venv/bin/activate
uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
适合：
- 只提供进销存能力
- 不需要模具分析与异步任务
6.2 gemold-only
source .venv/bin/activate
uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
适合：
- 单独部署模具分析能力
- 文件上传 / 分析 / 导出 / 批量分析
gemold Celery worker
建议同时启动 worker：
source .venv/bin/activate
celery -A src.celery_app.celery_app worker --loglevel=info
gemold 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
6.3 unified
当前仓库历史上存在过统一入口，但它更适合作为过渡参考，不建议再作为长期标准入口。
在正式完成组合层重构前，如需统一部署，可优先使用反向代理或部署编排层统一暴露 gemold 与 inventory；后续会演进为显式 unified_app.py。
蓝图参考：
7. systemd 部署示例
7.1 inventory-only 服务
创建：
sudo nano /etc/systemd/system/gemold-inventory.service
[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
启用：
sudo systemctl daemon-reload
sudo systemctl enable gemold-inventory
sudo systemctl start gemold-inventory
7.2 gemold-only API 服务
创建：
sudo nano /etc/systemd/system/gemold-moldinsight.service
[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 gemold Celery worker 服务
创建：
sudo nano /etc/systemd/system/gemold-celery.service
[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 配置：
如果不使用仓库内 frontend 容器，也应遵循同样原则：
/提供前端静态资源与 SPA fallback/api/反代后端/health反代后端/html/反代 gemold
8.1 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;
}
}
8.2 gemold-only
server {
listen 80;
server_name gemold.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：
curl http://127.0.0.1:8001/health
gemold-only：
curl http://127.0.0.1:8000/health
9.2 基础能力验证
inventory-only
- 登录接口可用
/api/products返回数据/api/inventory返回数据
gemold-only
- 登录接口可用
/api/upload可访问- 上传后 worker 能正常消费任务
/api/status/{task_id}能看到进度
10. 常见问题
1. 为什么不再推荐 src.main:app？
因为当前项目已演进为模块化结构，src.main:app 更适合作为过渡兼容入口，而不是长期部署标准。应优先围绕 entrypoints/ 部署。
2. inventory-only 为什么不需要对象存储？
因为对象存储主要服务于 gemold 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
3. gemold-only 为什么建议同时部署 Celery？
因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。
11. Docker Compose 说明
当前 docker-compose.yml 会启动：
frontendbackendmoldinsight-celery- 可选：
moldinsight/inventory（独立模块模式）
它不会再拉起：
- PostgreSQL
- Redis
- MinIO
这些基础设施应由服务器现有服务提供，并通过 .env 传入连接信息；前端则由 frontend 容器独立提供，并通过同域反代转发到后端。
示例：
docker compose --profile full up -d