cjw
0e6b3b1811
按 ROADMAP §3.1 治理批次推进的后端设计审查整改：
- 批次 0（安全）：/api/status/{task_id} 补 JWT 鉴权与任务归属校验；
pythonocc_available 真实探测；bcrypt 超 72 字节显式拒绝；
SECRET_KEY/RUSTFS_* 惰性校验，代码侧弱默认移除
- 批次 1（部署正确性）：主处理链路改走 RustFS（分派入参 stp_file_id 化，
worker 按 object_key 下载）；AUTO_MIGRATE 开关 + 迁移目录 alembic/→migrations/
修复包遮蔽（自动迁移此前从未真正生效）；OCC 镜像改 conda 原生执行 +
基础镜像 tag 锁定；compose 关键项改 ${VAR:?} 强制显式配置
- 批次 2（任务一致性）：删除 Redis 进程内存回退，PG 为任务状态单一事实源；
批量元数据入库（processing_tasks.batch_id，迁移 a3f8c2d91e47）；
型腔失败任务标 failed 不再静默 completed；事务边界收口
（数据本体写 flush-only、失败先回滚再置 failed、进度更新保留即时 commit）
- 批次 3（API 与代码结构）：592 行 advanced_router 拆为 design/cost/machining/
export 四子路由，请求体全量 Pydantic 化；ROUTE_MODULES + route_registry
（/api/health 呈现 degraded，DEBUG fail fast）；纯计算端点统一 to_thread；
StorageIntegrationService 按职责三拆；MAX_FILE_SIZE 接线生效、
celery 复用 Settings.redis_url；管理员重置密码改 JSON body（端到端断裂修复）；
openapi.json 重导出（76 paths）+ 前端 gen:api
- 批次 4（架构演进）：共享 ORM 按模块拆分（shared/models/base.py + identity.py、
moldinsight/models/、inventory/models/，删除三条无使用方的跨模块
relationship，跨模块桥接收敛为裸 FK 硬规则，无兼容 facade）；
OCC executor 重建补 cancel_futures=True（消除旧队列被慢恢复线程
并行消化的数据竞争）；OCC 吞吐方案设计先行
（docs/topics/performance/OCC_THROUGHPUT.md）；顺手清偿 D15
（vite.config.ts 未用参数致 npm run build 失败）
测试基线：125 passed, 2 skipped（pytest + sqlite+aiosqlite；归属边界、
路由契约、配置治理、鉴权回归等随批新增）
文档同步：STATUS / TECH_DEBT / ROADMAP / ARCHITECTURE / API_CONTRACT /
OPERATIONS / AGENTS
Co-Authored-By: Claude Code <noreply@anthropic.com>
6.4 KiB
6.4 KiB
配置与运行（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注入容器环境变量（见 docker-compose.yml）。 - 键值约定：
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）。无 OCC 环境时项目可启动，但几何分析契约测试自动 skip。 - 前端：
cd frontend && npm install。 - 数据库迁移：
migrations/（alembic.ini在仓库根；2026-09-16 由alembic/改名——原目录名与 alembic 包重名，应用内 import 会被遮蔽导致启动期迁移静默失败）；数据修复类一次性脚本在scripts/migrations/与scripts/db/，不是运行时代码，勿在服务内引用。
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 通道，见 topics/performance/OCC_THROUGHPUT.md 方案 A）；调大时预算好每子进程内存与 PG 连接数。- 建议生产加
--max-tasks-per-child=M（如 50）：子进程定期重启，兜底回收 OCC 超时后滞留的线程。
前端：
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
docker compose --profile full up -d # frontend + unified backend + moldinsight-celery（推荐）
docker compose --profile moldinsight up -d # moldinsight 单模块栈
docker compose --profile inventory up -d # inventory 单模块栈
- 镜像构建：
deploy/build.bat/deploy/build.sh（base → 各服务镜像，见deploy/Dockerfile.*）。 - 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/ 为运行时产物目录，不提交、不作为配置源头。
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 |