装闭 RenoPit 源码解析（01）：AI装修闭坑系统整体架构

装闭RenoPit是一套面向装修消费者的 AI 装修闭坑系统。用户上传户型图、效果图、合同或报价单后系统会调用多模态大模型完成装修问题识别、合同风险审查和跨文档核对最后生成网页报告与 PDF 报告。RenoPit 已在 GitHub 开源完整代码可以在 fthux/RenoPit 查看。阅读本系列时可以把仓库作为源码索引对照文中提到的目录、入口文件和调用关系一起阅读。这一系列文章将沿着真实源码调用链分析 RenoPit。本篇先从入口文件出发弄清浏览器、React、FastAPI、Celery、Redis 和 PostgreSQL 之间的关系为后续分析项目模型、文件处理和 AI 调用流程建立整体视图。一、系统由哪些部分组成项目根目录的docker-compose.yml定义了五个服务服务主要职责默认端口frontend托管 React 静态资源通过 Nginx 转发 API3000backend运行 FastAPI提供项目、文件和报告接口8000celery_worker执行耗时的 AI 分析任务无外部端口dbPostgreSQL保存项目和分析结果5432redisCelery 消息队列和任务结果后端6379它们的关系可以概括为/api 请求投递任务SSE 进度浏览器React NginxFastAPIPostgreSQLRedisCelery Worker多模态 LLM APIuploads / reportsbackend和celery_worker使用同一份后端镜像也挂载相同的uploads、reports目录。两者的区别不是代码而是启动命令前者运行 Uvicorn后者运行 Celery Worker。backend:command:uvicorn app.main:app--host 0.0.0.0--port 8000celery_worker:command:celery-A app.tasks.celery_app worker--loglevelinfoFastAPI 负责接收请求和返回结果Celery Worker 负责执行可能持续数分钟的 AI 分析。两个进程通过 PostgreSQL 共享业务状态通过 Redis 传递任务消息。二、React 前端从哪里启动前端入口位于frontend/src/main.tsx。它首先创建 React 根节点然后用BrowserRouter包裹AppcreateRoot(document.getElementById(root)!).render( StrictMode BrowserRouter App / /BrowserRouter /StrictMode, )在挂载 React 之前入口还会检查VITE_DEMO_MODE。演示模式下动态加载demo/mockApi.ts让前端直接使用内置数据正常模式则继续请求真实后端。Demo 模式的具体实现将在后续文章单独分析。App.tsx定义了四条核心业务路由/projects项目列表/projects/new创建项目/project/:id项目详情、素材管理和分析进度/project/:id/analysis装修闭坑分析报告。首页单独使用LandingPage其余页面放在公共Layout下。前端没有额外的全局状态库项目数据和分析状态主要由页面组件通过fetch从/api获取。三、FastAPI 后端如何启动后端入口是backend/app/main.py。Docker 启动 Uvicorn 时app.main:app会导入这里创建的 FastAPI 实例appFastAPI(titleRenoPit,description装修设计图避坑分析器 API,version0.1.0,redoc_urlNone,docs_urlNone,)app.include_router(projects_router)app.include_router(health_router)projects_router提供项目、上传、分析和报告接口health_router提供系统健康检查。项目还重新实现了/docs和/redoc页面但 OpenAPI 数据仍由 FastAPI 自动生成。应用启动时会触发startup()先导入全部 SQLAlchemy 模型再调用Base.metadata.create_all(bindengine)创建数据表。数据库连接集中在core/database.py其中engine管理连接池SessionLocal创建会话get_db()则通过 FastAPI 依赖注入为每次请求提供独立会话并在请求结束后关闭。四、开发与生产环境的请求入口前端代码统一使用相对地址/api因此组件不需要知道后端运行在哪个主机。开发环境由 Vite 将/api代理到http://localhost:8000Docker 生产环境则由 Nginx 将同一路径代理到 Compose 网络中的http://backend:8000。普通页面使用try_files回退到index.html因此刷新 React 动态路由时仍能进入前端应用。Nginx 还为分析进度接口关闭了响应缓冲并将读取超时设置为 3600 秒。这是因为项目详情页会建立EventSource长连接持续接收服务端发送的 SSE 事件。五、一次 AI 装修分析如何穿过整个系统以用户点击“开始分析”为例完整请求链如下ProjectPage向/api/projects/{id}/analyze发送 POST 请求Nginx 将请求转发给 FastAPIFastAPI 校验项目内容将项目状态更新为analyzing后端调用run_analysis_task.delay(project_id)把任务写入 RedisCelery Worker 从 Redis 取出任务读取 PostgreSQL 中的项目和素材Worker 预处理图片与文档并调用多模态 LLM API分析结果写回 PostgreSQL前端通过 SSE 接口获得进度和最终状态分析完成后页面跳转到/project/:id/analysis加载报告。Celery 的 Broker 使用 Redis 0 号库任务结果后端使用 Redis 1 号库。分析任务启用了task_acks_late、单任务预取和 20 分钟时间限制用于约束长耗时任务的执行方式。六、本篇调用链小结RenoPit 并不是浏览器直接调用大模型的单页应用。它以 React 负责交互以 FastAPI 负责业务接口和状态管理以 Celery 承担 AI 分析以 Redis 传递任务以 PostgreSQL 保存项目及结果再由 Nginx 统一暴露页面、API 和 SSE 连接。理解这条主链后后续源码就有了明确位置项目与分析状态属于数据库模型上传素材进入文件处理链Celery 任务进入分析引擎最终结果由 React 报告页和 PDF 生成器共同消费。下一篇将从六张 SQLAlchemy 数据表开始分析 RenoPit 的项目、素材、分析和报告模型。本文涉及的入口文件和服务配置都可以在开源仓库 fthux/RenoPit 中找到。后续文章也会继续以仓库中的实际代码为准沿着这条调用链逐层深入。