cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bee439cf341bc83fedc8ceda9612f76312534a2c
geMoldInsight/docs/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md
T
cjw bee439cf34 x
2026-08-31 18:01:34 +08:00

7.6 KiB
Raw Blame History

前端独立部署 + 统一后端入口实施计划

目标：在已经切换到“前端独立部署 + 同域反代”的基础上，进一步取消前端 Nginx 对 /api 的路径级分流，改为反代到一个真正的 unified backend，一次性解决长期维护成本。

1. 背景

当前项目已经完成了两项关键演进：

  1. 前端从历史 static/ 托管模式中抽离，开始走独立构建与独立部署
  2. 前端通过同域 Nginx 反代访问后端 API 与分析产物

但当前 Nginx 仍然承担了“后端路由所有权判断”的职责：

  • 一部分 /api/... 被转发到 moldinsight
  • 另一部分 /api/... 被转发到 inventory

这虽然能跑通当前功能，但长期存在明显问题：

  • 每新增一个 gemold API，Nginx 都要同步改配置
  • Nginx 配置承担了业务边界知识，维护成本高
  • /health 只能代表某一套后端，而不是统一入口
  • 与“unified / gemold-only / inventory-only”三种部署模式的目标不完全一致

因此，本轮改造的目标是：

把前端入口反代逻辑从“按路径分流到两套后端”升级为“统一反代到一个 unified backend”。

2. 目标状态

浏览器视角

浏览器始终只访问一个同域入口：

  • / → 前端静态页面
  • /api/* → unified backend
  • /health → unified backend
  • /html/* → unified backend（由 unified backend 再提供 gemold 产物访问）

Nginx 视角

Nginx 不再负责理解 gemold / inventory 的业务边界。

它只做两件事：

  1. 提供前端静态文件与 SPA fallback
  2. 把 /api、/health、/html 统一转发给一个 backend upstream

后端视角

后端新增一个统一入口，负责组合：

  • auth
  • moldinsight routes
  • inventory routes
  • /health
  • /html

同时继续保留：

  • moldinsight-only
  • inventory-only

以满足模块独立部署场景。

3. 设计决策

3.1 为什么要引入 unified backend

因为前端与网关层最适合面对的是一个统一后端，而不是两套需要网关手工分流的内部模块。

收益：

  • Nginx 配置显著简化
  • 新增 API 不需要修改网关规则
  • 文档和运维认知更简单
  • 前端保持统一 /api 契约
  • 更符合模块化蓝图中对 unified 模式的定义

3.2 为什么不直接把 split 模式删掉

因为：

  • gemold-only 和 inventory-only 仍然有独立部署价值
  • 当前仓库已经形成了清晰模块边界
  • 统一入口应该成为前端同域反代的默认方案，而不是抹掉模块部署模式

所以最终保留三类入口：

  • src/entrypoints/unified.py
  • src/entrypoints/moldinsight.py
  • src/entrypoints/inventory.py

4. 需要改动的核心文件

4.1 新增 unified 入口

新增：

  • src/entrypoints/unified.py

职责：

  • 基于 shared.app_factory.create_app() 创建应用
  • 统一挂载：
    • moldinsight.api.router（prefix=/api）
    • inventory.api.inventory_router
  • 使用：
    • mount_html=True
    • serve_frontend_static=False
  • 不额外挂载 auth（交给 app_factory）
  • 不手工重复定义 /health

4.2 简化前端 Nginx

修改：

  • deploy/nginx/frontend.conf

从当前：

  • 双 upstream：moldinsight / inventory
  • 多个 location /api/... 手工分流

改成：

  • 单 upstream：例如 gemold_backend_upstream
  • 统一转发：
    • /api/ → unified backend
    • /health → unified backend
    • /html/ → unified backend

保留：

  • / 的 SPA fallback
  • /assets/ 的静态缓存策略

4.3 调整 Compose

修改：

  • docker-compose.yml

目标：

  • 增加 unified backend 服务
  • frontend 只依赖 unified backend
  • 保留 moldinsight-celery
  • 按需保留 split backend 入口作为独立 profile

建议最终 profile 语义：

  • full：frontend + unified + celery
  • frontend：仅前端入口
  • moldinsight：仅 gemold-only
  • inventory：仅 inventory-only
  • （可选）unified：仅 unified backend

4.4 视实现需要调整 Dockerfile

可能新增：

  • deploy/Dockerfile.unified

或复用已有：

  • deploy/Dockerfile.moldinsight

取决于是否希望 unified backend 使用单独镜像名。

统一要求：

  • unified backend 镜像必须包含：
    • src/moldinsight/
    • src/inventory/
    • src/shared/
    • src/entrypoints/unified.py

4.5 文档同步

需要更新：

  • README.md
  • frontend/README.md
  • docs/deployment/LINUX_SETUP.md
  • docs/deployment/DEPLOY_PORT.md
  • docs/deployment/PORT_CONFIG.md

重点改动：

  • 当前推荐部署方式改为“frontend + unified backend + celery”
  • 说明 split 模式仍保留，但不再是前端同域反代默认方式
  • 端口说明中要区分：
    • 前端入口端口
    • unified backend 内部/对外端口
    • gemold-only / inventory-only 模块端口

5. 路由与冲突评估

根据当前代码结构，unified 模式可行，主要原因：

  • inventory 所有业务路由都挂在 /api 下，并且以独立业务前缀区分
  • moldinsight 业务路由同样挂在 /api 下，但使用不同子路径
  • auth 路由使用 /api/auth
  • top-level /health 由 app_factory 提供
  • moldinsight 内部还有 /api/health，与 top-level /health 不冲突
  • /html 只有 moldinsight 需要

关键约束：

  1. unified 入口中不要重复 include auth
  2. unified 入口中不要手工再定义 top-level /health
  3. unified 入口必须 mount_html=True

6. 风险与控制

风险 1：统一入口与现有 split 入口行为不一致

控制：

  • 保留现有 moldinsight.py 与 inventory.py
  • 只把 unified 作为前端默认 upstream

风险 2：/health 语义变化

当前前端只请求一个 /health，但 split 时代它实际上只代表某个后端。

控制：

  • unified 上的 /health 明确作为“前端默认 backend 健康入口”
  • 文档中明确其语义

风险 3：/html 丢失或不可达

控制：

  • unified backend 继续 mount_html=True
  • 前端 Nginx 保留 /html/ 反代

风险 4：Compose、Nginx、文档不同步

控制：

  • 先写本计划文档
  • 再改 unified 入口、Nginx、Compose
  • 最后统一 README 与 deployment docs

7. 验证方案

7.1 路由验证

unified backend 启动后应验证：

  • /api/auth/login
  • /api/auth/me
  • /api/upload
  • /api/status/{task_id}
  • /api/history
  • /api/cost-estimate
  • /api/products
  • /api/inventory
  • /api/dashboard
  • /api/finance/*
  • /health
  • /html/...

7.2 前端验证

前端同域访问应验证：

  • /login
  • /moldinsight
  • /inventory
  • /moldinsight/result/:taskId

关键交互：

  • 登录
  • 模具上传
  • 任务轮询
  • 成本估算
  • 产品/库存/订单页面加载
  • /html 分析结果页访问

7.3 Compose 验证

完整系统：

docker compose --profile full up -d

应满足：

  • frontend 正常提供页面
  • frontend 只反代一个 unified backend
  • moldinsight-celery 正常运行
  • 不再依赖 Nginx 路径级业务分流

8. 实施顺序

  1. 新增 docs/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md
  2. 新增 src/entrypoints/unified.py
  3. 修改 deploy/nginx/frontend.conf
  4. 修改 docker-compose.yml
  5. 按需要修改 Dockerfile / 构建脚本
  6. 更新 README 与 deployment docs
  7. 做一致性验证

9. 最终预期

完成后，系统对外部署形态将变成：

  • 前端：独立 Nginx 静态站点
  • 网关：同域同入口
  • 后端：一个 unified backend 作为前端默认 upstream
  • worker：保留 gemold Celery 异步处理
  • split 模式：继续作为模块独立部署能力保留

这能一次性解决当前“前端入口依赖 Nginx 路径级业务分流”的长期维护问题。

Reference in New Issue View Git Blame Copy Permalink