架构与边界

启动流程

dev.ts / main.ts
  -> parseRuntimeArgs(cli args) — 必须指定 config.yaml
  -> bootstrap({ configPath, mode })
     -> loadServerConfig(configPath)
     -> createRuntimeLogger(config.logging)
     -> mkdirSync(dataDir)
     -> 加载 migrations（生产：嵌入 bytes；开发：磁盘 drizzle/）
     -> createDatabase(dataDir)
     -> runMigrations(db, migrations) — pending 时先备份 DB
     -> startServer({ config, logger, db })
  -> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit

HTTP 请求流程

Request -> Bun.serve routes 声明式匹配 -> routes/*.ts handler -> helpers/ 响应格式化 -> Response

生产模式：非 API 路径由 fetch fallback 处理，有扩展名返回静态资源或 404，无扩展名返回 SPA index.html。
开发模式：Vite proxy 将 /api 转发到 Bun。

前后端边界

前端只通过 HTTP /api/* 调用后端。
共享类型在 src/shared/。
前端禁止 import src/server/ 运行时实现；后端禁止依赖 src/web/ 运行时代码（HTML import 集成除外）。

主要模块

模块	职责
`src/server/bootstrap.ts`	统一启动引导、DB 初始化、shutdown 编排
`src/server/server.ts`	Bun HTTP server + routes 注册
`src/server/routes/`	API handler，按资源端点拆分
`src/server/db/`	SQLite 连接、schema、migration、data access
`src/server/ai/`	AI Provider Registry + Agent 流式调用
`src/server/config/`	配置解析（types、variables、normalizer、schema）
`src/server/helpers/`	响应格式化、URL 工具
`src/server/middleware/`	参数校验 + 错误处理
`src/shared/api.ts`	前后端共享 API 类型
`src/shared/app.ts`	应用全局常量

路由分组

资源	路径前缀	文件目录
meta	`/api/meta`	`routes/meta.ts`
providers	`/api/providers`	`routes/providers/`
models	`/api/models`	`routes/models/`
projects	`/api/projects`	`routes/projects/`
chat	`/api/projects/:id/conversations` 和 `:id/chat`	`routes/chat/`

更新触发条件

修改项目结构、启动流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。

2.9 KiB Raw Blame History Unescape Escape

架构与边界

启动流程

HTTP 请求流程

前后端边界

主要模块

路由分组

更新触发条件

2.9 KiB

Raw Blame History