geMoldInsight/docs/deployment/LINUX_SETUP.md

geMoldInsight Linux 部署指南

文档定位：Linux 环境下的详细部署操作文档。 当前部署主题入口见 ../DEPLOYMENT.md，当前项目状态见 ../STATUS.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

---

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. 代码获取与目录约定

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

如果需要 moldinsight 分析能力，请额外准备 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_* 仅 moldinsight / unified 模式需要
• inventory-only 可不使用对象存储
• 当前配置读取实现见 settings.py

---

5. 数据库初始化

项目当前使用 Alembic 管理迁移，应用启动时也会执行初始化流程。

首次部署建议：

1. 确保服务器上的 PostgreSQL / Redis / 对象存储服务已可访问
2. 启动应用前确认 .env 中的 DB_HOST / REDIS_HOST / RUSTFS_ENDPOINT 指向真实服务地址
3. 让应用执行初始化/升级逻辑

相关实现参考：

• 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（unified 模式）的 frontend 服务，则该入口已经内置在前端 Nginx 镜像中。

---

6.1 inventory-only

source .venv/bin/activate
uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001

适合：

• 只提供进销存能力
• 不需要模具分析与异步任务

---

6.2 moldinsight-only

source .venv/bin/activate
uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000

适合：

• 单独部署模具分析能力
• 文件上传 / 分析 / 导出 / 批量分析

moldinsight Celery worker

建议同时启动 worker：

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（默认 unified）
• ../../docker-compose.moldinsight.yml
• ../../docker-compose.inventory.yml
• ../../src/entrypoints/unified.py

---

7. systemd 部署示例

7.1 inventory-only 服务

创建：

sudo nano /etc/systemd/system/moldinsight-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 moldinsight-inventory
sudo systemctl start moldinsight-inventory

---

7.2 moldinsight-only API 服务

创建：

sudo nano /etc/systemd/system/moldinsight-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 moldinsight Celery worker 服务

创建：

sudo nano /etc/systemd/system/moldinsight-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 配置：

• deploy/nginx/frontend.conf

如果不使用仓库内 frontend 容器，也应遵循同样原则：

• / 提供前端静态资源与 SPA fallback
• /api/ 反代后端
• /health 反代后端
• /html/ 反代 moldinsight

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 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;
    }
}

8.3 unified（示意）

统一对外时，可由网关做模块路由，也可直接暴露统一组合后的应用入口。组合层标准化完成前，更推荐通过部署编排或网关来实现统一对外访问。

---

9. 验证部署

9.1 健康检查

inventory-only：

curl http://127.0.0.1:8001/health

moldinsight-only：

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/ 部署。

2. inventory-only 为什么不需要对象存储？

因为对象存储主要服务于 moldinsight 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。

3. moldinsight-only 为什么建议同时部署 Celery？

因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。

---

11. Docker Compose 说明

仓库根目录维护 3 个独立 compose 文件，按文件名映射部署模式：

模式	Compose 文件	一键命令
unified（默认）	docker-compose.yml	docker compose up -d
moldinsight-only	docker-compose.moldinsight.yml	docker compose -f docker-compose.moldinsight.yml up -d
inventory-only	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 deploy/build.sh        # base → backend → frontend（celery 复用 backend 镜像）
# 或让 compose 构建：docker compose up -d --build
# 注意：docker compose up -d 对本地已有同名镜像不会自动重建，更新代码后需 --build

---

12. 推荐阅读

• README.md
• archive/BACKEND_MODULARIZATION_BLUEPRINT.md
• DEPLOY_PORT.md
• PORT_CONFIG.md