架构决策记录（ADR）

ADR-001: 同仓同域部署

状态：已采纳（2026-05-14）

上下文

流水线最终产物需要部署前端（用户端 + 管理后台）和后端（CloudBase 云函数）。有两种方案：

方案	结构	域名	资源消耗	复杂度
A 同仓同域	1仓库 / 1域名	{项目名}.yunjinhong.cn	低	低
B 多仓多域	3仓库 / 3域名	用户端 / admin / api 各一	高	高

决策

选择方案 A（同仓同域），理由：

1. 节省资源——个人项目/小团队不需要多域名多仓库
2. 部署简单——一次 EdgeOne Pages 部署同时搞定用户端和管理后台
3. 前后端共享类型定义，减少沟通成本
4. yunjinhong.cn 已备案，子域名直接可用

路由设计

• / → client/ 构建产物（用户端）
• /admin → admin/ 构建产物（管理后台）
• /api/* → CloudBase 云函数（HTTP 触发）

实现方式

• admin 的 vite.config.ts 设置 base: '/admin/'
• admin 构建产物复制到 client/public/admin/
• client/public/_routes.json 做 SPA fallback

何时迁移到方案 B

• 日活 > 10 万，需要独立扩缩容
• 管理后台需要独立权限体系（不同域名隔离 Cookie）
• 团队 > 5 人，需要独立代码仓库权限管理
• 需要独立的 CDN 策略（用户端全球加速，管理后台仅国内）

迁移路径

1. 拆仓库：client/ → 独立仓库，admin/ → 独立仓库，server/ 保留
2. 拆域名：{项目名}.yunjinhong.cn（用户端）、admin-{项目名}.yunjinhong.cn（管理后台）
3. API 跨域：CloudBase 云函数配置 CORS 允许两个域名
4. CI/CD：每个仓库独立流水线

---

ADR-002: CloudBase 云函数作为后端

状态：已采纳

理由

1. 免费额度覆盖个人项目（5万次调用/月）
2. 天然免运维，自动扩缩容
3. 内置 NoSQL 数据库、身份认证
4. 与腾讯云生态（EdgeOne、DNSPod）无缝集成

局限

• 冷启动延迟（~200ms）
• 单函数内存上限 1GB
• Node.js 运行时版本受限

何时考虑迁移

• 需要长连接（WebSocket）
• 需要自定义运行时（Go / Python / Rust）
• 需要更高性能（CloudRun 容器部署）