快速开始

克隆仓库、安装依赖、构建数据库、创建管理员,在本地把项目跑起来。

本页带你从「购买已激活」走到「本地项目已运行,并以管理员身份登录」。全程使用本地的 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-typegen

pnpm 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 为每个变量做了标记:[必填] 必须设置,[可选] 有可用的默认值,[开发] 只用于开发环境。

构建数据库

pnpm db:migrate

它会应用迁移链并记录每一步。完成后,项目根目录下会出现 local.db。这是构建 schema 唯一受支持的方式。

创建第一位管理员

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 状态页、通知渠道和限流规则)。不包含演示数据。

启动应用

pnpm dev

Vite 会打印本地地址,默认是 http://localhost:5173。保持它运行。

登录

打开 /auth/sign-in,用上一步的管理员邮箱和密码登录。你登录的是超级管理员账号,所以可以直接打开管理后台 /admin。

安装完得到了什么

src/routes
src/server
src/components
drizzle/migrations/sqlite
drizzle/migrations/postgres
modules
scripts/validate

运行 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。原因见运行时与数据库适配器。

下一步