geMoldInsight/docs/OPERATIONS.md

配置与运行（OPERATIONS）

文档定位：配置 / 启动 / 环境 / 运维硬性要求的唯一归属。 部署入口与部署文档分工见 DEPLOYMENT.md，Linux 详细步骤见 deployment/LINUX_SETUP.md；当前状态见 STATUS.md，架构见 ARCHITECTURE.md。

---

1. 配置来源与优先级

• 配置统一走环境变量，代码侧由 src/shared/config/settings.py 的 Settings 单例经 dotenv + os.getenv 读取。
• 本地运行：仓库根 .env（load_dotenv() 自动加载；不在仓库内，参照 .env.example 复制编辑）。
• Compose 运行：compose 文件用 ${VAR} 从同目录 .env 注入容器环境变量；按模式对应不同文件名（见 DEPLOYMENT.md §1.1）。
• 键值约定：
  • DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD：惰性校验、无代码默认——缺失时 import 不报错（便于测试/静态分析），真正连库时才失败。生产必须显式配置。
  • AUTO_MIGRATE：应用启动时是否自动执行 alembic 迁移，默认 true（单机开发语义）；多副本 / 容器编排部署应设 false，改由部署流程单点执行 alembic upgrade head 或 python -m shared.database.init_db（迁移脚本已随镜像分发于 /app/migrations/）。
  • SECRET_KEY：JWT 签名密钥，无默认；生产必须 ≥32 字符强随机。
  • ADMIN_PASSWORD：初始管理员密码，无默认；首次建库前必须设置。
  • RUSTFS_*：对象存储（兼容 MINIO_* 别名写法）；本地开发缺省值仅为占位，连不上会在用到存储的链路报错。
  • REDIS_*：默认 localhost:6379 无密码（本地开发语义），生产必须显式覆盖；连接串唯一拼装点为 Settings.redis_url（Celery broker/backend 复用）。
  • MAX_FILE_SIZE：上传文件大小上限（字节），默认 104857600（100MB）；此前为死配置（处理器硬编码 50MB），2026-09-17 起真实生效，收紧上限需同步调整该值。
  • CORS_ORIGINS：逗号分隔白名单；不设默认放行 *，生产必须显式设置。
  • LOG_FORMAT：json（生产默认，结构化）/ text（开发人可读）；LOG_LEVEL：DEBUG/INFO/WARNING/ERROR。
  • DEBUG：true 时额外注册 /api/debug/* 调试路由（仍需登录），生产必须为 false。
• 新增配置项的规则：只加 settings.py + .env.example，关键依赖项不给 localhost/弱口令兜底（见 AGENTS.md §2）。

2. 安装与环境

• 后端依赖：pip install -r requirements.txt。
• OCC 几何能力：PythonOCC 不走 pip 主路径，通过 conda 环境提供（本项目实践环境名 gemold 或 moldinsight）。无 OCC 环境时项目可启动，但几何分析契约测试自动 skip。
• 前端：cd frontend && npm install。
• 数据库迁移：migrations/（alembic.ini 在仓库根；2026-09-16 由 alembic/ 改名——原目录名与 alembic 包重名，应用内 import 会被遮蔽导致启动期迁移静默失败）；数据修复类一次性脚本在 scripts/migrations/ 与 scripts/db/，不是运行时代码，勿在服务内引用。

2.1 pip 锁文件生成（D13 流程）

deploy/requirements-{base,moldinsight}.lock.txt 是项目依赖的版本锁，由 conda 环境首次构建成功后一次性落盘：

• 生成时机：在 moldinsight / gemold conda 环境（仅含项目依赖 + conda 基础库，不能在混装全开发栈的本机 pip 环境跑）执行 pip freeze
• 生成命令：
  • Linux / macOS：bash deploy/generate_lockfiles.sh
  • Windows：deploy\generate_lockfiles.bat
• 产物：
  • deploy/requirements-base.lock.txt
  • deploy/requirements-moldinsight.lock.txt
• 消费方：CI、离线构建、生产复现部署；pip install -r deploy/requirements-base.lock.txt 可直接锁定安装而不依赖 >= 解析
• 提交策略：两个 lock.txt 提交到仓库；版本下限（requirements-{base,moldinsight}.txt）按团队策略同步或保留 >= 灵活解析

3. 本地启动

后端三入口（均含 sys.path 修正，可从仓库根直接跑）：

# unified（moldinsight + inventory，推荐）：8000
uvicorn src.entrypoints.unified:app --reload --host 0.0.0.0 --port 8000
# moldinsight-only：8000
uvicorn src.entrypoints.moldinsight:app --reload --host 0.0.0.0 --port 8000
# inventory-only：8001
uvicorn src.entrypoints.inventory:app --reload --host 0.0.0.0 --port 8001

Celery worker（moldinsight 异步分析链路；本地从 src 目录跑，与 deploy/Dockerfile.celery CMD 同参）：

cd src && celery -A celery_app worker --concurrency=2 --loglevel=info

• --concurrency=N 即 OCC 并行分析数：每个 prefork 子进程持一个常驻 OCC 工作进程（方案 B，见 topics/performance/OCC_THROUGHPUT.md）——每个 OCC 工作进程是独立的 Python + OCC 运行时，N 增大时按「worker 子进程 + OCC 子进程」双份预算内存，并预留 PG 连接数（按 celery 角色池随子进程倍增）。
• --max-tasks-per-child=M（如 50）：worker 子进程定期重启，连带回收其 OCC 子进程（进程级兜底，方案 A）。

前端：

cd frontend
npm run dev        # Vite 开发服务器
npm run gen:api    # 从根目录 openapi.json 重新生成 src/types/api.ts（见 API_CONTRACT §4）

探活：unified/moldinsight GET /health 与 GET /api/health；inventory GET /health。

4. Docker Compose

按"模式 ↔ 文件名"一一对应：

# unified（默认；frontend + backend + moldinsight-celery）
docker compose up -d
# 或（profile 双保险）
docker compose --profile full up -d

# moldinsight-only（moldinsight + moldinsight-celery）
docker compose -f docker-compose.moldinsight.yml up -d
# 或
docker compose --profile moldinsight up -d

# inventory-only（仅 inventory）
docker compose -f docker-compose.inventory.yml up -d
# 或
docker compose --profile inventory up -d

• 镜像构建：bash deploy/build.sh（base → backend → celery → frontend 4 个 tag）；首次部署或更新代码后必须先 build 再 up。
• PostgreSQL / Redis / RustFS 通常复用服务器已有服务，不由项目 compose 自带；容器只注入连接配置。

5. 运行时硬性要求

• 生产环境必须显式设置：SECRET_KEY、ADMIN_PASSWORD、DB_*、CORS_ORIGINS、RUSTFS_*、REDIS_PASSWORD、DEBUG=false、LOG_FORMAT=json。
• 单数据库：moldinsight 与 inventory 共享同一 PostgreSQL（刻意设计，不拆库）。
• 后台任务一律走 task_dispatcher 与 Celery，不要在路由里 fire-and-forget。
• uploads/ 与 html_output/ 为运行时产物目录，不提交、不作为配置源头。html_output/ 自 D11 起仅作 /html 报告代理的存量兜底读（新产物直传 RustFS 报告键 html/reports/，worker 不再写本地卷）。
• scripts/ 下的一次性脚本执行前先确认目标环境（多为不可逆数据迁移）。

6. 排障指针

症状	先看
起服务连不上数据库	.env 的 DB_* 是否与服务器一致（惰性校验：import 成功 ≠ 连接正常）
上传/导出报对象存储错误	RUSTFS_* 四项 + topics/storage/RUSTFS_STORAGE.md
分析任务一直 pending	Celery worker 是否在跑；Redis 连通性；task_dispatcher 日志
前端类型与接口对不上	openapi.json 是否重新导出、npm run gen:api 是否执行（API_CONTRACT.md §4）
登录 401	SECRET_KEY 是否跨进程一致（JWT 校验依赖同一密钥）
部署端口/反代问题	deployment/DEPLOY_PORT.md、deployment/PORT_CONFIG.md