系统架构
代码如何分层、业务代码为什么从不接触 SQL 方言,以及让模板便于 fork 的约定。
Kernlift 是供他人 fork 的模板,所以它的结构要在功能不断增加时仍保持可预期。服务端代码分层组织,运行时能力在应用运行时检测,另有几条约定适用于整个仓库。目录地图见项目结构。
分层
routes/ 路由组件与 API 处理器
└── functions/ 可从路由调用的服务端函数
└── services/ 跨能力的编排
└── repositories/ 所有数据库访问
└── schema/ 按方言定义的表
platform/ 运行时能力:缓存、存储驱动、边缘绑定
jobs/ 定时任务,由部署平台每分钟触发一轮
agent-host/ 可选 agent 服务在 Web 一侧的部分
plugins/ 每个已安装插件为后台增加的内容每一层只调用它的下一层。路由保持精简,服务负责协调跨能力的工作(例如一笔结算完成的支付会发放积分并签发授权),仓储是唯一与数据库交互的地方。
| 层 | 位置 | 职责 |
|---|---|---|
| 路由 | src/routes/ | 页面、布局与 API 处理器;在边界处检查身份 |
| 服务端函数 | src/server/functions/ | 供 loader 与组件调用,每个函数先解析调用者 |
| 服务 | src/server/services/ | 跨能力的编排、限流与副作用 |
| 仓储 | src/server/db/repositories/ | 所有读写,对外是与方言无关的契约 |
| Schema | src/server/db/schema/ | sqlite.ts 与 postgres.ts,声明相同的表 |
业务代码为什么看不到方言
业务代码只调用 repositories/,不直接使用 SQL 方言,所以同一份代码可以运行在 SQLite、Cloudflare D1、Turso 和 Postgres 上。两个 schema 文件声明相同的表,withRepositoryDialect 根据当前连接把对应的 schema 传给仓储。
方言差异只存在于 schema、迁移和适配器层。迁移在 drizzle/migrations/<dialect> 下手工维护,因此 schema 变更需要在每种方言下各有一条匹配的迁移。连接与适配器如何选择,见运行时与数据库适配器。
运行时能力是事实,不是偏好
src/server/platform/ 暴露的是运行时要么具备、要么不具备的能力:用于缓存的 KV 命名空间、用于存储的存储桶绑定、用于边缘 AI 的推理绑定。每一项都在运行时检测。缺失的能力会连同原因报告为不可用,并且无法在后台中选择。
凡是存在原生绑定的地方,旁边都有一条可移植的路径。存储在同一接口后面同时提供 S3 兼容驱动和存储桶绑定驱动,所以模板在 Cloudflare 之外同样可以部署。
缓存
每个缓存域维护自己的键和失效时机。所有缓存域都从后台配置读取策略(启用状态、TTL 和后端),因此排查问题时无需部署即可关闭某个缓存域。策略在 /admin/config/cache 中编辑。
后台由插件填充
后台侧边栏、工作台侧边栏、工作台首页卡片和账单页操作都是插槽,在 src/plugins/slots.ts 中声明,由已安装插件填充。src/plugins/installed.ts 明确列出一份构建里的插件:内置的 foundation 插件承载底座自带的全部后台入口,每个已安装模块各有一个插件。只在服务端生效的贡献单独列在 src/plugins/installed.server.ts 中。
插件可以在 /admin/plugins 中停用。停用后它的入口消失,/admin 与 /app 布局对它的页面返回 not found。数据保留。见插件。
后台任务在 Web 应用内运行
周期性工作统一放在 src/server/jobs/scheduled.ts 的 runScheduledJobs() 中:积分过期、支付履约重试、未完成的 AI 任务。每分钟执行一轮,由平台提供的机制触发:Node 服务器上是进程内循环,Cloudflare 上是 Worker 的 Cron Trigger,也可以由外部 cron 调用 pnpm jobs:run。配置表里的一行锁保证多副本时也只执行一轮,每一轮都会写入心跳记录,供 /setup 读取。见后台任务。
agent 是独立的可选服务
agent 工作台运行在 apps/agent-service 中,这是由 packages/ 下的 agent-* workspace 包构建出的第二个进程。Web 应用从不加载 agent 运行时,也没有任何 Web 请求依赖这个服务。src/server/agent-host/ 是边界在 Web 一侧的部分:availability.ts 中的 getAgentAvailability() 返回这套部署是否有 agent,导航、页面和 /api/agent/* 都以这个结果为准。没有该服务的部署仍是完整的 Web 应用,AI 走普通的渠道调用。见 Agent 运行时。
每个部署目标一份构建
deploy.config.json 记录部署平台(cloudflare、fly、railway 或 docker)、数据库以及是否部署 agent。它在构建时被打包进产物,同时决定使用哪种构建:以 src/server-entry.ts 为入口的 Worker 构建,或以 src/server-entry.node.ts 为入口的 Node 构建。kernlift deploy-target 负责重写它。见运行时与数据库适配器。
多语言
路由在 src/routes/{-$locale}/ 下按语言组织:同一个页面在 /… 提供英文,在 /zh/… 提供中文。文案保存在 src/i18n/locales/{en,zh}/messages.ts 中,两边的键完全一致,组件从这些字典中读取文案。只属于某一块后台区域的文案可以放在 src/i18n/ 下单独的文件里,同样带有键一致的 en 和 zh。见新增与修改文案。
贯穿全局的约定
| 约定 | 含义 |
|---|---|
| 规格驱动的变更 | 每个非小改动都先在 openspec/changes/ 中建立 OpenSpec 变更,包含提案、设计、规格和任务,完成后归档 |
| 配置在数据库中 | 服务商凭据与业务设置在 /admin/config/* 中;环境变量只负责启动与基础设施。见配置模型 |
| 不使用 mock 服务商 | 集成调用真实的测试或沙箱环境。缺少凭据时显示未配置状态,绝不伪造成功 |
| 唯一的身份边界 | 只有 src/server/auth/ 读取会话。见认证与授权模型 |
| 每项能力一个校验器 | scripts/validate/*.ts 断言行为与接线。见校验器与发布门禁 |
| 全站一套设计系统 | 后台、工作台、登录与系统页以及公开站都用 beUI(packages/beui、src/components/motion)配合 Tailwind 工具类。令牌挂在 :root 上,页面不需要声明就在设计系统里,也没有自己的类名前缀。src/styles/app.css 中历史遗留的 !important 债务不能被新文件效仿。见使用设计系统 |
| agent 是可选的 | 任何 Web 请求路径都不依赖 agent 服务,也不导入 agent 运行时。由 pnpm validate:optional-agent 强制 |
| agent 技能随代码发布 | skills/<name>/SKILL.md 保存开发项目用的技能,只引用真实存在的命令、路径和路由 |
模块是同一仓库的切片
代码仓库只有一个。每个模块由 modules/<key>/module.json 描述,共享文件中带有 @module:<key> 区域。pnpm registry:build 把仓库切分为一个底座条目和每个模块各一个条目,pnpm validate:registry 证明这些切片能逐字节还原为原仓库,并且底座在没有任何模块时仍能编译。见底座仓库里有什么。