系统架构

代码如何分层、业务代码为什么从不接触 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/所有读写,对外是与方言无关的契约
Schemasrc/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 证明这些切片能逐字节还原为原仓库,并且底座在没有任何模块时仍能编译。见底座仓库里有什么。

相关文件

src/routes
src/server/functions
src/server/services
src/server/db/repositories
src/server/auth
scripts/validate/auth-boundary.ts
src/server/agent-host/availability.ts
scripts/validate/optional-agent.ts
src/plugins/installed.ts
src/plugins/slots.ts
src/plugins/foundation/plugin.ts
src/server/jobs/scheduled.ts
packages/beui
apps/agent-service
deploy.config.json
src/server/platform/deployment.ts

下一步