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

装闭（RenoPit）是一套面向装修消费者的 AI 装修闭坑系统。用户上传户型图、效果图、合同或报价单后，系统会调用多模态大模型完成装修问题识别、合同风险审查和跨文档核对，最后生成网页报告与 PDF 报告。

RenoPit 已在 GitHub 开源，完整代码可以在 fthux/RenoPit 查看。阅读本系列时可以把仓库作为源码索引，对照文中提到的目录、入口文件和调用关系一起阅读。

这一系列文章将沿着真实源码调用链分析 RenoPit。本篇先从入口文件出发，弄清浏览器、React、FastAPI、Celery、Redis 和 PostgreSQL 之间的关系，为后续分析项目模型、文件处理和 AI 调用流程建立整体视图。

一、系统由哪些部分组成

项目根目录的 docker-compose.yml 定义了五个服务：

服务	主要职责	默认端口
frontend	托管 React 静态资源，通过 Nginx 转发 API	3000
backend	运行 FastAPI，提供项目、文件和报告接口	8000
celery_worker	执行耗时的 AI 分析任务	无外部端口
db	PostgreSQL，保存项目和分析结果	5432
redis	Celery 消息队列和任务结果后端	6379

它们的关系可以概括为：

flowchart LR U[浏览器] --> N[React + Nginx] N -->|/api 请求| F[FastAPI] F --> P[(PostgreSQL)] F -->|投递任务| R[(Redis)] R --> C[Celery Worker] C --> P C --> L[多模态 LLM API] C --> V[(uploads / reports)] F -->|SSE 进度| N

backend 和 celery_worker 使用同一份后端镜像，也挂载相同的 uploads、reports 目录。两者的区别不是代码，而是启动命令：前者运行 Uvicorn，后者运行 Celery Worker。

backend:
  command: uvicorn app.main:app --host 0.0.0.0 --port 8000

celery_worker:
  command: celery -A app.tasks.celery_app worker --loglevel=info

FastAPI 负责接收请求和返回结果，Celery Worker 负责执行可能持续数分钟的 AI 分析。两个进程通过 PostgreSQL 共享业务状态，通过 Redis 传递任务消息。

二、React 前端从哪里启动

前端入口位于 frontend/src/main.tsx。它首先创建 React 根节点，然后用 BrowserRouter 包裹 App：

createRoot(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 实例：

app = FastAPI(
    title="RenoPit",
    description="装修设计图避坑分析器 API",
    version="0.1.0",
    redoc_url=None,
    docs_url=None,
)

app.include_router(projects_router)
app.include_router(health_router)

projects_router 提供项目、上传、分析和报告接口，health_router 提供系统健康检查。项目还重新实现了 /docs 和 /redoc 页面，但 OpenAPI 数据仍由 FastAPI 自动生成。

应用启动时会触发 startup()：先导入全部 SQLAlchemy 模型，再调用 Base.metadata.create_all(bind=engine) 创建数据表。数据库连接集中在 core/database.py，其中 engine 管理连接池，SessionLocal 创建会话，get_db() 则通过 FastAPI 依赖注入为每次请求提供独立会话并在请求结束后关闭。

四、开发与生产环境的请求入口

前端代码统一使用相对地址 /api，因此组件不需要知道后端运行在哪个主机。

开发环境由 Vite 将 /api 代理到 http://localhost:8000；Docker 生产环境则由 Nginx 将同一路径代理到 Compose 网络中的 http://backend:8000。普通页面使用 try_files 回退到 index.html，因此刷新 React 动态路由时仍能进入前端应用。

Nginx 还为分析进度接口关闭了响应缓冲，并将读取超时设置为 3600 秒。这是因为项目详情页会建立 EventSource 长连接，持续接收服务端发送的 SSE 事件。

五、一次 AI 装修分析如何穿过整个系统

以用户点击“开始分析”为例，完整请求链如下：

1. ProjectPage 向 /api/projects/{id}/analyze 发送 POST 请求；
2. Nginx 将请求转发给 FastAPI；
3. FastAPI 校验项目内容，将项目状态更新为 analyzing；
4. 后端调用 run_analysis_task.delay(project_id)，把任务写入 Redis；
5. Celery Worker 从 Redis 取出任务，读取 PostgreSQL 中的项目和素材；
6. Worker 预处理图片与文档，并调用多模态 LLM API；
7. 分析结果写回 PostgreSQL；
8. 前端通过 SSE 接口获得进度和最终状态；
9. 分析完成后，页面跳转到 /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 中找到。后续文章也会继续以仓库中的实际代码为准，沿着这条调用链逐层深入。