77 lines
4.6 KiB
Markdown
77 lines
4.6 KiB
Markdown
# 架构与边界
|
||
|
||
## 启动流程
|
||
|
||
```text
|
||
dev.ts / main.ts
|
||
-> parseRuntimeArgs(cli args) — 必须指定 config.yaml
|
||
-> bootstrap({ configPath, mode })
|
||
-> loadServerConfig(configPath) — 加载并校验配置（config.ts）
|
||
-> createRuntimeLogger(config.logging) — 创建 Logger 实例
|
||
-> mkdirSync(dataDir)
|
||
-> 加载 migrations（生产：嵌入 bytes；开发：磁盘 drizzle/）
|
||
-> createDatabase(dataDir)
|
||
-> runMigrations(db, migrations) — pending 时先备份 DB
|
||
-> startServer({ config, logger, db })
|
||
-> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit
|
||
```
|
||
|
||
## HTTP 请求流程
|
||
|
||
```text
|
||
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 集成除外）。
|
||
|
||
## 配置定位
|
||
|
||
| 配置类型 | 来源 | 内容 | 可变性 |
|
||
| -------- | ------------------------------------------------------------------------ | ------------------------------ | ---------- |
|
||
| 启动配置 | CLI 传入的 `config.yaml` | 监听地址、端口、日志、数据目录 | 进程内只读 |
|
||
| 业务设置 | 管理台 `/settings` 页面 → `GET/PUT /api/settings` → SQLite `settings` 表 | 主题偏好等 UI/业务开关 | 运行时可变 |
|
||
|
||
启动配置由 `src/server/config.ts` 的 `loadServerConfig()` 在启动时加载并校验，运行时不可更改。业务设置通过独立 API 持久化，与启动配置在存储和生命周期上完全解耦。
|
||
|
||
## 主要模块
|
||
|
||
| 模块 | 职责 |
|
||
| ------------------------- | --------------------------------------------------------------- |
|
||
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排 |
|
||
| `src/server/config.ts` | 配置加载入口：YAML 解析、规范化、契约校验、运行时校验 |
|
||
| `src/server/config/` | 配置子系统：types、variables、issues、normalizer、schema |
|
||
| `src/server/logger.ts` | Logger 接口 + Pino 实现 + 测试替身 |
|
||
| `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/helpers/` | 响应格式化、URL 工具 |
|
||
| `src/server/middleware/` | 参数校验 + 错误处理 |
|
||
| `src/web/layouts/` | 前端布局组件（AdminLayout / WorkbenchLayout） |
|
||
| `src/web/features/` | 前端功能模块（dashboard / projects / models / chat / settings） |
|
||
| `src/web/shared/` | 前端共享代码（components / hooks / utils） |
|
||
| `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/` |
|
||
| settings | `/api/settings` | `routes/settings.ts` |
|
||
|
||
## 更新触发条件
|
||
|
||
修改项目结构、启动流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。
|