快速开始
克隆仓库、安装依赖、构建数据库、创建管理员,在本地把项目跑起来。
本页带你从「购买已激活」走到「本地项目已运行,并以管理员身份登录」。全程使用本地的 SQLite 文件,不需要数据库服务,也不需要云平台账号。业务模板的安装方式相同,只是仓库地址不同。
准备工作
- 前置要求里的工具:Node 22.12 及以上的 22.x 版本、pnpm 和 git。
- 购买已激活,并且已接受 GitHub 邀请。见获取 Kernlift。
- 大约十分钟,大部分时间花在
pnpm install上。
在本地运行
克隆仓库
git clone git@github.com:kernlift/kernlift.git my-app
cd my-app业务模板则克隆 kernlift/<template-key>。准确地址见已购模板页面(/zh/app/licences)。
如果 git 提示 "Repository not found",说明邀请还没有接受,或者 git 用的是另一个 GitHub 账号。
安装依赖并生成类型
pnpm install
pnpm cf-typegenpnpm cf-typegen 生成运行时类型声明 worker-configuration.d.ts。这个文件是生成的,不会提交到仓库,所以在它生成之前,全新克隆的仓库上 pnpm typecheck 会失败。有没有 wrangler.jsonc 它都能运行;在 Cloudflare 项目中,每次修改绑定后都要重新运行。
创建 .env
cp .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"把打印出的值填入 .env 中的 BETTER_AUTH_SECRET。本地开发只需要设置这一项:文件已经把 DATABASE_DIALECT 设为 sqlite,把 DATABASE_URL 设为 ./local.db。
.env.example 为每个变量做了标记:[必填] 必须设置,[可选] 有可用的默认值,[开发] 只用于开发环境。
创建第一位管理员
SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<至少 8 个字符>' pnpm db:bootstrap-super-admin你应该看到 Created the super administrator you@example.com (sqlite).,随后是一行统计插入内容的 Baseline content:。重复运行是安全的:它不会覆盖管理员编辑过的行。
除了管理员,它还会写入权限集合、超级管理员角色和基线内容(邮件模板、营销页面、/system 状态页、通知渠道和限流规则)。不包含演示数据。
登录
打开 /auth/sign-in,用上一步的管理员邮箱和密码登录。你登录的是超级管理员账号,所以可以直接打开管理后台 /admin。
安装完得到了什么
运行 pnpm dev 或 pnpm build 时,路由生成器会按当前页面刷新 src/routeTree.gen.ts。
推送到你自己的仓库
你克隆的仓库是只读的,也不允许 fork。打开 GitHub 新建仓库,创建一个空的私有仓库,把它设为 origin:
git remote set-url origin git@github.com:YOUR-ACCOUNT/my-app.git
git push origin main之后要获取更新,再把模板仓库添加为 upstream。见同步上游更新。
设置部署目标
克隆的仓库带有 deploy.config.json 和某一个平台的部署文件。本地开发不需要动它们。要部署到别处,或者加上 agent 服务,运行:
pnpm kernlift deploy-target fly --no-agent --dialect sqlite把 fly 换成 cloudflare、railway 或 docker。命令会写入该平台的文件,把原来的文件移到 .kernlift/previous-deploy/,在 .env.production 中生成生产环境的密钥,并打印剩余步骤。它不创建任何远端资源。各平台及其允许的数据库见 部署配置。
验证
打开 /setup。会话密钥和登录方式显示已就绪;在接入服务商之前,邮件投递显示未就绪。这就是一个新项目应有的状态。
常见问题
git clone 提示 "Repository not found"
对于你没有读取权限的私有仓库,GitHub 就是这样回答的。到 GitHub 通知里接受邀请,并确认 git 使用的 SSH 密钥或凭据属于激活购买时填写的那个账号。邀请过期的话,见邀请过期了怎么办?
pnpm typecheck 报告缺少路由
运行 pnpm dev 或 pnpm build 时,路由生成器会按当前页面刷新 src/routeTree.gen.ts。
pnpm typecheck 在 Cloudflare 绑定上失败
worker-configuration.d.ts 缺失或已过期,例如修改了 wrangler.jsonc 之后。运行 pnpm cf-typegen。
数据库已存在,但不是由 pnpm db:migrate 构建的
迁移运行器根据自己的历史记录确定要应用哪些迁移,所以用其他方式创建的数据库无法原地迁移。删除 local.db,再运行一次 pnpm db:migrate。原因见运行时与数据库适配器。