# Kernlift 文档 # 审计日志 > 查清谁改了什么:48 处写入路径记录操作者、动作、目标和元数据。 Source: https://kernlift.dev/zh/docs/core/admin/audit-log 需要留痕的写入(发放许可证、退款、保存配置、改派工单、删除文件)都会在执行它的代码路径里向 `audit_logs` 追加一行。后台在 `/admin/audit` 列出最近 500 条,可按动作筛选,每行的元数据可以展开。 ## 准备工作 * 一个有 `audit.read` 的账号。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 无需配置。日志从第一个请求起开始记录,不依赖服务商。 ## 设置 ### 给审计员这一个权限,也只给这一个 `audit.read` 只能读日志。它不隐含 `config.read`、`users.write` 或别的任何权限,所以可以给合规审查人员一个能查看所有变更、但不能做任何修改的账号。 ### 读日志 `/admin/audit` 列出操作者、动作、目标和时间。按动作筛选可以缩小范围。展开一行可以查看写入时记录的元数据,例如订单号、服务商名、权限键。 ### 给自己的写入补记录 新增写入路径时,在执行写入的那个仓储里追加日志,这样记录和变更一起写入: ```ts await recordAudit("billing.refund.created", orderId, { provider, amountCents }); ``` `actor` 是执行这次写入的子系统。元数据是 JSON,之后检索不需要迁移。 ## 今天记录了哪些动作 共有 48 处调用点写入日志,按所属子系统分组: | 前缀 | 例子 | | --------------------------- | ----------------------------------------------------------------------------------------- | | `billing.*` | `checkout.created`、`refund.created`、`licences.issued`、`licences.revoked`、`portal.created` | | `support.*` | `ticket.created`、`ticket.replied`、`ticket.assignment.updated` | | `cms.*` | `entry.upserted`、`taxonomy.created` | | `email.*`、`notification.*` | `template.saved`、`delivery.recorded`、`webhooks.saved`、`preferences.updated` | | `affiliate.*` | `referral.created`、`conversion.recorded`、`payout.requested` | | `newsletter.*`、`waitlist.*` | `subscribed`、`unsubscribed`、`joined` | | `file.*` | `uploaded`、`deleted` | | `analytics.*` | `event.recorded` | ## 一行长什么样 页面快照还包含限流规则及最近 20 条 webhook 校验结果,可同时排查配置变更和被拒绝的事件。 ## 验证 1. 在 `/admin/licences` 手动发放一张许可证。`/admin/audit` 顶部出现一条 `billing.licences.issued`,目标是这张许可证的 id。 2. 按这个动作筛选,只剩这类记录。 3. 展开这一行,元数据里有产品 key 和被授予的用户。 4. 用一个没有 `audit.read` 的角色登录,页面显示无权限。 ## 参考 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [限流](https://kernlift.dev/zh/docs/core/admin/rate-limits.md):同一份快照里的限流规则 * [Drizzle 插入](https://orm.drizzle.team/docs/insert):仓储如何追加这一行 ## 下一步 - [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) 建一个只读的审计角色。 - [限流](https://kernlift.dev/zh/docs/core/admin/rate-limits.md) 哪些请求被限流,由哪条规则触发。 - [工单](https://kernlift.dev/zh/docs/extensions/support.md) 运营对工单的操作同样会被审计。 --- # 缓存 > 十个缓存域,各有自己的 TTL,可放内存或 Cloudflare KV,每个域都能单独清除。 Source: https://kernlift.dev/zh/docs/core/admin/cache 每个涉及支付、邮件、存储或 AI 的请求都会从后台配置表读取服务商配置。这些读取按域缓存,TTL 在 `/admin/config/cache` 设置。改完配置又不想等 TTL 过期时,可以单独清除某一个域。 ## 准备工作 * `config.read` 才能看到页面,`config.write` 才能改 TTL 或清缓存。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 默认使用内存。Cloudflare KV 仅在运行时有 `CACHE` 绑定时可用。Redis 会列出并显示不可用原因,它未接入缓存层。 ## 设置 ### 选后端 内存只在单个进程内缓存。Workers 上每个 isolate 各缓存一份,Node 上每个容器各一份。KV 可在实例间共享。不可用的后端会显示原因。若已配置的后端在运行时不可用,读取会回退到进程内存。 ### 按域设置 TTL 每个域有自己的默认值。配置类的 TTL 短,修改服务商后很快生效。模板类的 TTL 长,很少变化的内容读库次数更少。 保存表单接受 1–86,400 秒。关闭 **启用** 可让该域绕过缓存,TTL 值会保留供再次启用时使用。 ### 改完之后清一下 在 `/admin/config/*` 保存服务商设置后会自动清除对应的域,所以改动不用等 TTL 过期就生效。在后台之外直接改了数据行时,才需要手动清除。 ## 各个域和默认 TTL | 域 | 缓存什么 | 默认 TTL | | --------------------- | ---------- | ------ | | `admin_config` | 后台配置表本身 | 30 秒 | | `auth_config` | 认证服务商与选项 | 30 秒 | | `email_config` | 邮件服务商设置 | 30 秒 | | `email_template` | 渲染后的邮件模板 | 60 秒 | | `payment_config` | 支付服务商设置 | 30 秒 | | `storage_config` | 对象存储设置 | 30 秒 | | `analytics_config` | 分析服务商设置 | 30 秒 | | `newsletter_config` | 订阅服务商设置 | 30 秒 | | `ai_channel_snapshot` | 通道列表 | 30 秒 | | `ai_channel_resolved` | 场景到通道的解析结果 | 15 秒 | `admin_config` 是引导域。其余每个域的策略都通过它读取,所以它不能从自己缓存的那张表里读取自己的策略。它的 TTL 来自 `ADMIN_CONFIG_CACHE_TTL_MS`,这是本项目读取的少数几个环境变量之一。 ## 策略 要增加缓存域,在 `cache-policy.ts` 的 `cacheDomains` 中登记。后台会随之提供 TTL 设置和清除操作。 ## 验证 1. 打开 `/admin/config/cache`,页面列出十个域及其 TTL。 2. 在 `/admin/config/payment` 改一项支付设置,然后进行一次结账。新设置立即生效,不用等 30 秒。 3. 关闭 `email_template` 的 **启用** 并保存,模板读取不再使用缓存。 4. 在没有 `CACHE` 绑定的运行时上,KV 选项会显示,并附不可用原因。 ## 参考 * [配置模型](https://kernlift.dev/zh/docs/core/configuration.md):为什么设置存在数据库里 * [环境变量](https://kernlift.dev/zh/docs/reference/env.md):含 `ADMIN_CONFIG_CACHE_TTL_MS` * [部署](https://kernlift.dev/zh/docs/deploy/runtimes.md):运行时有哪些绑定 * [Cloudflare KV](https://developers.cloudflare.com/kv/):共享后端 ## 下一步 - [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) 被缓存的是什么,在哪里编辑。 - [限流](https://kernlift.dev/zh/docs/core/admin/rate-limits.md) 另一处单进程和多实例表现不同的设置。 - [部署到 Cloudflare](https://kernlift.dev/zh/docs/deploy/cloudflare.md) 创建 KV namespace 并绑定为 CACHE。 - [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md) 这个缓存保存十五秒的场景解析结果。 --- # 按国家查看账号与已付订单 > 在国家统计页按时间范围比较账号和已结算订单。 Source: https://kernlift.dev/zh/docs/core/admin/countries `/admin/countries` 按国家代码汇总账号和已结算订单,用地图与可排序表格展示。数据来自应用数据库,不依赖第三方分析账号。 ## 准备工作 * `countries.read`。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 账号上要有国家信息。国家未知的账号计入 `UNKNOWN`,所以总数不变。 ## 设置 ### 打开页面 打开 `/admin/countries`。页面先加载默认时间范围。范围、开始和结束日期保存在 URL 搜索参数中,复制链接可以保留当前查询窗口。 ### 选择时间范围 选择 **今天**、**昨天**、**7 天**、**30 天** 或自定义范围,然后点击 **应用**。地图和表格同时更新。比较所选时段的 **用户数**、**创建订单数**、**支付订单数** 和 **支付金额**。 页面只显示国家级汇总,不暴露单个用户的位置,也不能下钻到账号。用户登录时,系统从受支持的请求头记录国家;平台没有发送国家请求头的账号计入 `UNKNOWN`。 ## 搜索参数 国家名称由 `src/lib/admin-countries.ts` 根据两位代码本地化,数据库不保存国家名称。 ## 验证 1. 打开 `/admin/countries`,地图和表格都渲染出来,合计和汇总行一致。 2. 缩小时间范围,地图和表格同时变化。 3. 用一个设置了国家的账号下一笔测试订单,webhook 结算后金额出现在这个国家上。 4. 用没有 `countries.read` 的角色登录,页面显示无权限。 ## 参考 * [分析](https://kernlift.dev/zh/docs/extensions/analytics.md):页面与事件分析 * [支付](https://kernlift.dev/zh/docs/extensions/payments.md):订单什么时候算已付 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [MapLibre GL](https://maplibre.org/maplibre-gl-js/docs/):这个页面用的地图库 如果所有行都是 `UNKNOWN`,检查平台是否传入国家请求头,并让用户重新登录。已有会话保留创建时记录的国家。 ## 下一步 - [分析](https://kernlift.dev/zh/docs/extensions/analytics.md) 流量与事件,可以接第三方服务,也可以不接。 - [支付](https://kernlift.dev/zh/docs/extensions/payments.md) 这个页面上已付金额的来源。 - [用户与账号](https://kernlift.dev/zh/docs/core/auth/users.md) 这个页面统计的账号行。 - [管理后台](https://kernlift.dev/zh/docs/core/admin.md) 其他运营页面。 --- # 运行管理后台 > 创建第一个管理员、完成上线检查清单、熟悉侧边栏,并在 /admin 中管理插件、调整缓存和查看审计日志。 Source: https://kernlift.dev/zh/docs/core/admin `/admin` 管理后台是运营人员管理产品的地方。安装完成后先按本指南操作一遍,之后调整缓存或查看审计日志时再回来查阅。 ## 准备工作 * 已完成迁移的数据库(`pnpm db:migrate`)。 * 一台能连上该数据库的机器上的终端。 * 第一个管理员要使用的邮箱和密码。 ## 创建第一个管理员 在有用户具备 `admin.access` 权限之前,没有人能打开 `/admin`,而授权又必须在后台里完成。初始化脚本从命令行创建第一个管理员。 ### 把管理员写入 `.env` ```bash title=".env" SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD=at-least-8-characters SUPER_ADMIN_NAME="Super Admin" ``` `SUPER_ADMIN_EMAIL` 和 `SUPER_ADMIN_PASSWORD` 必填。密码至少 8 位,仅在新建账号时使用。`SUPER_ADMIN_NAME` 可选,默认 `Super Admin`。 ### 运行初始化脚本 ```bash pnpm db:bootstrap-super-admin ``` 脚本会新建该邮箱的账号并标记为已验证;如果账号已存在,则直接提升为管理员,不修改原密码。随后它把访问状态设为 **Active**,写入模板自带的全部权限,全部授予 **Super Admin** 角色并分配给该账号。脚本还会写入基础邮件模板、营销页面和频率限制规则。 ### 删除密码并登录 从 `.env` 中删除 `SUPER_ADMIN_PASSWORD`,这些变量只有该脚本读取。在 `/auth/sign-in` 登录并打开 `/admin`。 升级或安装模块后如果新增了权限,再运行一次脚本,让 Super Admin 角色获得新权限。 ## 完成上线检查清单 ### 打开设置 在工作台侧边栏点击 **设置**(`/setup`)。该页面每次加载都读取实时配置。 ### 处理每个未就绪的条目 每个条目都列出缺少的配置,并提供 **去配置** 按钮跳转到对应页面。 必需项是 **会话密钥**、**登录方式**、**邮件投递** 和 **定时任务**;**支付供应商**、**对象存储**、**AI 渠道**、**订阅供应商**(安装 Newsletter 模块时)和 **分析供应商** 为可选。所有必需项就绪后,徽标显示 **必需项已齐备**。 有两个必需项不在后台中配置。**会话密钥** 是环境变量 `BETTER_AUTH_SECRET`,因为它在读取数据库之前就要用到,见[管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md)。**定时任务** 反映每分钟一轮的后台任务是否在运行。它没有 **去配置** 按钮,提示信息会指出该检查部署平台上的哪个开关。见[排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md)。 ## 熟悉侧边栏 侧边栏按分组组织,用户没有某个入口所需的权限时,该入口不会显示。 | 分组 | 入口 | | ------- | -------------------------------------------------------------------------------- | | **概览** | 工作台(`/admin`)、用户、国家统计 | | **运营** | 角色、权限、工单 | | **商业化** | 套餐(`/admin/plans`)、订单、订阅 | | **平台** | AI Tasks、对话、API Keys、限流配置、资源 | | **内容** | CMS、Waitlist 和推广合作,随各自的模块出现 | | **安全** | Webhooks、审计 | | **设置** | 认证、支付、存储、AI、分析和邮件配置,邮件、通知、插件(`/admin/plugins`),以及随 agent 模块出现的沙箱配置、搜索配置和图片 Agent | **套餐** 用来创建 `/pricing` 列出、结账时实际收费的定价套餐。查看需要 `plans.read`,保存需要 `plans.write`。见[定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)。 ## 启用或停用插件 1. 打开 **设置 → 插件**(`/admin/plugins`,需要 `config.read`)。页面列出这份构建里安装的所有插件及其贡献的内容。 2. 使用模块所在行的开关;保存需要 `config.write`。内置的 foundation 插件始终启用。 停用后,插件在后台的入口消失,它的 `/admin` 和 `/app` 页面返回 not found,数据保留。这个页面不能安装插件,安装插件是把它加进 `src/plugins/installed.ts`。见[后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md)。 ## 调整缓存 ### 打开缓存设置 打开 `/admin/config/cache`。侧边栏中没有入口,保存需要 `config.write`。 ### 逐个区域设置 针对每个区域勾选 **启用**,设置 **存活时长(秒)**,选择当前运行时可用的 **后端**,点击 **保存**。 ### 需要时清空缓存 **清空此域** 会立即清空该区域的缓存。 ## 查看审计日志 打开 **安全 → 审计**(`/admin/audit`,需要 `audit.read`)。页面列出最近 500 条事件,例如用户状态变更、认证与服务商配置保存、API Key 事件和频率限制判定,并提供 CSV 下载。 **配置之前** 不运行初始化脚本,就没有人能进入后台。已登录但不具备 `admin.access` 的用户会被跳转到 `/system/permission-denied`,没有会话的访问者跳转到 `/system/session-expired`。 ## 验证 * 以管理员身份登录:`/admin` 可以打开,侧边栏显示所有分组。 * 必需项就绪后,`/setup` 显示 **必需项已齐备**。 * 在仓库中运行: ```bash pnpm validate:users pnpm validate:auth-boundary ``` ## 常见问题 ### 出现 `SUPER_ADMIN_EMAIL is required.` 脚本没有读到值。把两个变量写入 `.env`,或者在命令前直接传入:`SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='' pnpm db:bootstrap-super-admin`。 ### 页面显示 `Permission denied: <权限>` 用户能进入后台,但缺少该页面检查的权限。仅 `/admin` 仪表盘就需要 `admin.dashboard.read`、`users.read`、`credits.read` 和 `ai.read`。见[管理用户、角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 ### 新权限没有授予 Super Admin 角色权限在运行 `pnpm db:bootstrap-super-admin` 时写入。再运行一次即可。 ### 侧边栏缺少某个菜单 侧边栏会隐藏用户无权访问的菜单项。给该用户分配带有该页面所需权限的角色,见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 ## 参考 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [Base UI](https://base-ui.com) ## 下一步 - [管理用户、角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) - [认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md) --- # 限流 > 设置 API Key 请求限额,并选择内存或 Redis 计数后端。 Source: https://kernlift.dev/zh/docs/core/admin/rate-limits `/admin/rate-limits` 配置 API Key 流量:一条默认限额,以及 AI 生成、AI 状态和资源上传的覆盖值。登录和 Webhook 的保护使用独立运行路径,本页面不编辑这些规则。 ## 准备工作 * 查看页面需要有 `config.read` 的账号,修改后端需要 `config.write`。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 默认后端为进程内内存。多实例需要 Redis 共享计数。 ## 设置 ### 先看已有的规则 打开 `/admin/rate-limits`。表单列出默认限额和三个端点覆盖值。这些值存在后台配置中,不是独立 `rate_limit_rules` 审计表中的记录。 ### 选择后端 内存只在单个进程内计数。不同 Workers isolate 或 Node 容器有各自的计数器。选择 Redis 并填写连接地址后,实例可共享计数。 URL 作为后台配置里的 secret 保存,不会回传给浏览器。页面只显示 URL 是否已配置。 ### 调整规则 设置默认请求上限和时间窗口,再调整需要单独限制的端点。 ## 此页面配置的 API Key 限额 | 键 | 端点模式 | 默认值 | | --------------- | ----------------------- | ------------- | | 默认 API Key 限额 | 其他使用 API Key 的请求 | 每 1 秒最多 100 次 | | `ai_generate` | `/api/{scene}/generate` | 未修改前继承默认值 | | `ai_status` | `/api/status` | 未修改前继承默认值 | | `assets_upload` | `/api/assets/upload` | 未修改前继承默认值 | 各项请求上限允许 1–10,000 次,时间窗口允许 1–3,600 秒。 ## 后端 增加默认规则时,更新 `defaultRateLimitRules` 并调用 `insertMissingRateLimitRules`。已部署环境会补入新规则,不覆盖运营已有的调整。 ## 验证 1. 打开 `/admin/rate-limits`,能看到三个端点覆盖值和一条默认 API Key 限额。 2. 不填 URL 就把后端切到 Redis。页面拒绝保存,不会回退到内存。 3. 填入 Redis URL 后刷新页面。页面显示 URL 已配置,但不显示 URL 本身。 ## 参考 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [API 密钥](https://kernlift.dev/zh/docs/core/auth/api-keys.md):校验限流保护的 scope * [Redis](https://redis.io/docs/latest/develop/):共享计数存储 ## 下一步 - [审计日志](https://kernlift.dev/zh/docs/core/admin/audit-log.md) 哪些规则被触发,以及每次 webhook 校验的结果。 - [API 密钥](https://kernlift.dev/zh/docs/core/auth/api-keys.md) scope、调用记录,以及每个密钥适用的限额。 - [缓存](https://kernlift.dev/zh/docs/core/admin/cache.md) 另一项在单进程和多实例下行为不同的设置。 - [积分](https://kernlift.dev/zh/docs/extensions/credits/usage.md) 冻结被拒绝时,用户余额如何变化。 --- # 使用编码 Agent 技能 > 使用 skills/ 中的 SKILL.md 工作流了解项目、创建项目,开发、安装和卸载模块,添加页面,配置服务商并部署。 Source: https://kernlift.dev/zh/docs/core/agent-skills `skills/` 是给维护本仓库或其衍生项目的编码助手使用的工作流。它们**不是**可选 `/app/agent` 运行时使用的 `agent-skills/` 发布包。后者见 [Agent 模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)和 [Agent 运行机制](https://kernlift.dev/zh/docs/extensions/agent.md)。 ## 准备工作 * 能读取 `SKILL.md` 文件的编码 Agent,例如 Claude Code。 * 已检出的仓库,或你想安装技能的项目。 | 技能 | 适用场景 | | --------------------- | ------------------------------------------------------------------------ | | `project-context` | 刚接手项目或要改一块没读过的代码时,弄清有什么、在哪里 | | `quick-start` | 用 CLI 创建项目并做到管理员可以正常登录 | | `new-module` | 端到端添加一个模块,包括区域标记和清单 | | `new-page` | 添加一个带文案、守卫和导航的后台或工作台页面 | | `new-agent-plugin` | 把一项 agent 能力做成统一工作台的插件:Skill、卡片、面板和操作 | | `configure-providers` | 通过 `/admin/config/*` 接入真实服务商 | | `deploy` | 部署到 Cloudflare、Fly.io、Railway 或 Docker 主机:选择或切换平台、保存生成的密钥、迁移并检查 `/setup` | | `add-module` | 通过 CLI 的包管理流程安装或升级模块,先预览再执行 | | `remove-module` | 通过 CLI 的包管理流程卸载模块:预览计划、保留改动、决定数据去留并下架它的 Skill | `quick-start`、`add-module` 和 `remove-module` 走的是 CLI 的包管理流程,从 GitHub 克隆的项目用不到。克隆的项目请按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)操作,不用 `quick-start` 技能;另外两个也不需要,因为所有模块已经在代码里。 每个技能都有同样的四个部分:**Inputs**、**Invariants**、**Workflow** 和 **Verification**。它只提到仓库中真实存在的命令、路径和路由。 ## 安装技能 **在你的克隆中** 无需安装。仓库为 `skills/` 中的每个技能提交了 `.claude/skills/` 链接,在克隆目录中打开 Claude Code 即可加载。 在 Windows 上,除非开启了符号链接(克隆前执行 `git config core.symlinks true`,并打开开发者模式),git 会把这些链接检出为普通文本文件。这种情况下用另一种方式安装。 **在其他项目中** ```bash npx skills add kernlift/kernlift ``` 在项目根目录运行。`kernlift/kernlift` 是你受邀访问的私有仓库,你的 GitHub 账号需要有读取权限。命令会把技能装到 `.claude/skills` 供 Claude Code 使用,装到 `.agents/skills` 供其他编码 Agent 使用。 ## 运行技能 ### 说明任务 用自然语言向 Agent 描述任务,或直接点名技能,例如“用 new-page 技能添加一个导出用的后台页面”。 ### 提供输入 每个技能都以 **Inputs** 部分开头,例如模块键或部署平台。缺什么 Agent 会向你询问。 ### 让它按工作流执行 Agent 按 **Workflow** 步骤执行,同时遵守 **Invariants**,例如绝不编造 id、不在功能代码中读取 `process.env`。 ### 检查结果 Agent 最后执行技能的 **Verification** 部分:证明任务完成的命令和页面。 ## 让 Agent 读懂项目 文档讲的是 Kernlift 的通用做法;在你的项目里工作的 Agent 需要的是这个项目本身的情况。下面两个来源提供这些信息。 **`pnpm kernlift context`** 每次运行时从源码读出当前项目的描述,新增路由、插件或设置后无需维护。它不需要令牌、网络或数据库,也不写任何文件。 ```bash pnpm kernlift context # 概况和下面的主题 pnpm kernlift context routes # 每个 URL 及其文件 pnpm kernlift context validators --json ``` | 主题 | 列出的内容 | | ------------ | --------------------------------------------------------- | | `rules` | `AGENTS.md` 各节摘要 | | `routes` | 按区域(public、auth、app、admin、api)列出 URL 及文件 | | `plugins` | `src/plugins` 里的插件、本次构建是否安装、它们的路由和导航项 | | `config` | 每个 `/admin/config/*` 页面及其背后的 server function 和 repository | | `env` | `.env.example` 里的变量、级别和说明 | | `scripts` | 校验器以外的 `pnpm` 脚本 | | `validators` | `pnpm validate:*` 检查、哪些由 `validate:all` 运行,以及已知失败项 | | `skills` | `skills/` 里的技能 | `all` 一次输出全部主题。`project-context` 技能会让 Agent 从这里开始。 **Markdown 版文档。** [`/zh/llms.txt`](https://kernlift.dev/zh/llms.txt) 列出本站每一页并链接到它的 Markdown,[`/zh/llms-full.txt`](https://kernlift.dev/zh/llms-full.txt) 是全站合在一个文件里,任意页面地址后加 `.md` 即可得到 Markdown,例如 `/zh/docs/quick-start.md`。英文版去掉 `/zh` 前缀。Agent 需要代码里没有的概念或操作步骤时,把 `https://kernlift.dev/zh/llms.txt` 给它。 ## 验证 * 在 Claude Code 中,可用技能列表里出现 `skills/` 中的技能。 * `pnpm kernlift context` 输出的概况里,插件列表与 `src/plugins/installed.ts` 一致。 * 在仓库中,`pnpm validate:skills` 确认技能提到的每个命令、路径和路由都存在。 ## 常见问题 ### Agent 看不到技能 在仓库根目录打开 Agent,使其找到 `.claude/skills`。如果 `.claude/skills/` 是一个很小的文本文件而不是链接,说明克隆时没有启用符号链接,用 `npx skills add kernlift/kernlift` 安装。 ### 修改后 `pnpm validate:skills` 失败 某个技能提到的命令、路径或路由已经不存在。按代码更新该技能。 ## 参考 * [技能](https://kernlift.dev/zh/docs/reference/skills.md):每个技能做什么、需要什么、如何检查 * [Agent 模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md):单独的运行时产品及其发布技能包 * [Agent Skills 规范](https://agentskills.io/specification):`SKILL.md` 的文件格式 ## 下一步 - [新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md) - [开发一个模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md) - [部署项目](https://kernlift.dev/zh/docs/deploy.md) - [架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md) --- # 签发 API 密钥并设置限流 > 完成后,用户可以在脚本中用带 scope 的密钥调用 AI 和上传接口,你可以控制每个密钥的调用频率。 Source: https://kernlift.dev/zh/docs/core/auth/api-keys API 密钥让用户无需浏览器会话即可调用部分 `/api/*` 接口。任何已登录用户都可以为自己的账号创建密钥,限流由运营人员设置。密钥不需要服务商,也不需要环境变量。 ## 准备工作 * 一个用于创建密钥的已登录用户账号。 * 查看限流需要 `config.read`,修改需要 `config.write`,查看所有用户的密钥需要 `api_keys.read`。内置的 **Platform Operator** 角色可以查看,**Settings Manager** 角色提供 `config.write`。 * 调用 AI 时需要一个已设置路由的场景,见 [设置场景路由和定价](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)。 ## 创建密钥 ### 打开表单 登录后在应用侧边栏打开 **API Keys**(`/app/api-keys`),点击 **创建 API Key**。 ### 填写字段 | 字段 | 填写内容 | | ------------------- | ----------------------------------------------------------- | | **Key 名称** | 便于日后辨认的名称,至少两个字符。 | | **环境** | **Production**、**Staging** 或 **Development**。只是标签,不影响密钥的权限。 | | **速率限制 (req/sec)** | 没有 API 规则的接口上每个窗口允许的请求数,默认 100。 | | **过期日期** | 可选。到该日期(UTC)起密钥失效。 | | **允许的 Origins/IPs** | 可选,每行一个。见下方警告。 | | **Scopes** | **运行 AI 任务**、**查询 AI 任务状态**、**上传文件**。默认勾选前两项。 | ### 复制密钥 点击 **创建 key**,然后点击 **复制** 保存 **Secret key**。它只显示这一次,之后无法找回,丢失了只能重新创建。 创建后不能修改 Scopes。 **允许来源会拦截服务端之间的调用** 填写 **允许的 Origins/IPs** 后,只有请求的 `Origin` 头与某一行完全一致(包括协议和端口)才会被接受。不会按 IP 匹配。没有 `Origin` 头的请求(例如 curl 或服务端代码)会被拒绝。服务端之间调用的密钥请留空。 ## 用密钥调用接口 通过 `Authorization: Bearer ` 或 `x-api-key: ` 发送密钥。 ```bash curl -X POST "https://your-domain.example/api/$SCENE/generate" \ -H "Authorization: Bearer $KERNLIFT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Summarise this changelog"}' curl "https://your-domain.example/api/status?taskId='taskId'" \ -H "x-api-key: $KERNLIFT_API_KEY" ``` `$SCENE` 是 **场景路由** 中的场景编码。第一个请求需要 **运行 AI 任务**,第二个需要 **查询 AI 任务状态**,`POST /api/assets/upload` 需要 **上传文件**。调用以密钥所有者的身份执行,消耗的是所有者的积分。`GET /api/openapi.json` 提供这些接口的 OpenAPI 3.1 文档。 ## 为所有密钥设置限流 ### 打开限流配置 在后台进入 **平台 → 限流配置**(`/admin/rate-limits`)。 ### 选择后端 **限流后端**:**内存** 在每个服务进程内单独计数。多个实例同时提供 API 时选择 **Redis**,并填写 **Redis URL**(例如 `redis://default:password@host:6379`)。Redis 连不上时,该请求改用内存计数。切回 **内存** 会清空已保存的 URL。 ### 设置默认值 **默认次数 (req/sec)** 和 **默认窗口 (秒)** 作用于没有单独规则的接口。次数范围 1–10,000,窗口范围 1–3,600 秒。 ### 设置 API 规则 **API 规则** 中 **AI generate**(`/api/{scene}/generate`)、**AI status**(`/api/status`)和 **Asset upload**(`/api/assets/upload`)各占一行,分别设置 **次数 (req)** 和 **窗口 (秒)**,然后点击 **保存配置**。 这三个接口上的 API 规则对所有密钥生效,并且优先于用户创建密钥时填写的速率限制。用户填写的限制只作用于其他支持密钥认证的接口。 ## 为单个密钥设置不同的限流 ### 找到密钥 进入 **平台 → API Keys**(`/admin/api-keys`)。**Key 库存** 列出所有用户的密钥(已脱敏),以及所属用户、状态、过期时间、**最后使用** 和使用事件数。用 **搜索** 和 **状态** 筛选后点击 **应用**。 ### 编辑规则 点击该行的 **API 规则**。**API key 默认规则** 设置这个密钥自己的次数和窗口。每个接口行会显示当前继承的值,可以为这个密钥单独填写 **限流** 和 **窗口**。 ### 保存 点击 **保存**。对话框里每一行都会存为该密钥的设置,之后在 **限流配置** 页的修改不再影响这个密钥。 ## 撤销密钥 在 `/app/api-keys` 该密钥所在行点击 **撤销**,输入 key 名称后点击 **确认撤销**。使用该密钥的请求会立即失败。运营人员不能创建或撤销用户的密钥,但用户被封禁期间,其所有密钥都无法使用。 ## 验证 不带 `taskId` 调用状态接口: ```bash curl -i "https://your-domain.example/api/status" \ -H "Authorization: Bearer $KERNLIFT_API_KEY" ``` * `400` 且返回 `taskId is required.`:密钥可用。 * `401` `invalid_api_key`:密钥错误、已撤销或已过期,或被允许来源拒绝。 * `403` `insufficient_scope`:密钥没有 **查询 AI 任务状态**。 * `429` `rate_limited`:触发了限流,等当前窗口过去再试。 每次调用都会以通过或拒绝的形式出现在 **使用统计**(`/app/api-keys/usage`)中。`pnpm validate:api-keys` 会检查密钥库存、scope 和校验限流。 ## 常见问题 ### 请求返回 `insufficient_scope` 密钥缺少该接口要求的 scope。例如只有默认 scope 的密钥无法调用 `POST /api/assets/upload`。密钥创建后不能修改,请用所需的 scope 新建一个。 ### 限额被重置或不同服务器表现不一致 **内存** 后端在每个服务进程内单独计数。在 **限流配置** 页把 **限流后端** 设为 **Redis** 并填写 **Redis URL**,让所有实例共享计数。 ### 接口忽略密钥、要求会话 部分接口只接受会话:`/api/chat`、`/api/chat/conversations` 和 `/api/billing/checkout`。 ### 同一 IP 频繁收到 `rate_limited` 除上面的限流外,每个密钥前缀加客户端 IP 在 60 秒内最多校验 120 次,用来拖慢猜测密钥的尝试。请分散调用,或停止发送无效密钥。 ## 参考 * [限流](https://kernlift.dev/zh/docs/core/admin/rate-limits.md) * [Bearer authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) ## 下一步 - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) - [配置文件存储和上传](https://kernlift.dev/zh/docs/extensions/storage.md) --- # 认证与授权模型 > 身份在哪里读取、每个边界如何判定访问权限,以及为什么没有兜底用户。 Source: https://kernlift.dev/zh/docs/core/auth 认证确定调用者是谁,授权确定调用者能否执行某个操作。Kernlift 把两者放在同一个目录里,在多个层次上检查,并且没有身份兜底。配置登录方式与角色,见[配置邮箱密码登录](https://kernlift.dev/zh/docs/extensions/auth/email-password.md)和[管理用户、角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 ## 只有一个地方读取会话 `src/server/auth/` 是唯一允许读取 Better Auth 会话的代码。它分为三部分: | 文件 | 决定什么 | 主要导出 | | ----------------- | ----------- | ------------------------------------------------------------------------------- | | `context.ts` | 调用者是谁 | `requireAuthContext()`(默认用法,没有身份时抛错)、`getAuthContext()`(返回 `null`,只用于身份确实可选的路径) | | `guards.ts` | 调用者能否执行操作 | `requirePermission`、`requireOwnership`、`requireNotBanned`、`hasPermission` | | `api-boundary.ts` | API 处理器如何认证 | `withApiAuth`,接受会话;路由声明后也接受带指定 scope 的 API Key | `AuthContext` 包含 `userId`、`roles`、`permissions`、`status`、`sessionId`、`apiKeyId` 和 `source`。来源为 `session`、`api-key` 或 `dev-impersonation`。 Better Auth 实例在 `auth.ts` 中根据管理后台保存的设置构建,并挂载在 `/api/auth/*`,用于 OAuth 回调和重置密码链接。Google 与 GitHub 凭据按请求读取,所以保存后无需重启。 ## 没有身份兜底 未认证的调用者会被拒绝。任何代码路径都不会把它映射为默认用户。唯一的例外是开发环境的登录绕过,它要求同时满足 `APP_ENV=development` 和显式设置的 `AUTH_DEV_IMPERSONATE_USER_ID`。只满足其一不会生效。绕过第一次生效时,服务端会打印一条警告。 ## 分层检查访问权限 访问受保护页面的请求要经过多层检查,其中任何一层都足以单独拒绝它。 | 层 | 位置 | 检查内容 | | ------ | ------------------------ | --------------------------------------------------------------------------------------- | | 请求中间件 | `src/start.ts` | 没有会话 cookie 的 `/app/*` 与 `/admin/*` 页面请求跳转到 `/auth/sign-in` | | 工作台布局 | `app.tsx` | 被封禁的用户跳转到 `/system/permission-denied`;没有身份或账号未激活跳转到 `/system/session-expired` | | 后台布局 | `admin.tsx` | 要求 `admin.access`;没有身份跳转到 `/system/session-expired`,缺少权限跳转到 `/system/permission-denied` | | 服务端函数 | `requireAdminPermission` | 每个后台函数检查自己的权限键,页面从来不是数据的唯一关卡 | | API 路由 | `withApiAuth` | 会话或带 scope 的 API Key;否则该路由必须出现在显式的公开列表中 | 在布局层守卫意味着 `/app` 或 `/admin` 下新增的页面默认就受到保护。 ## 角色、权限与状态 角色、权限和状态从用户的访问档案、角色分配以及各角色的权限中一并解析。只有运营人员修改用户访问权限时才会写入档案,所以没有档案的用户解析为 `active`。 | 状态 | 效果 | | --------- | ----------------------------------------- | | `active` | 正常访问,受权限约束 | | `banned` | 被所有守卫拒绝,创建会话时即被拒绝。封禁结束时间已过的用户解析为 `active` | | `pending` | 未激活,工作台与后台守卫都会拒绝 | `requirePermission` 和 `requireOwnership` 都会先调用 `requireNotBanned`,所以未激活的账号在任何权限检查之前就会失败。角色是权限键的组合,见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 ## 归属检查隐藏存在性 按归属读取的查询把调用者 id 写进查询条件。这样,属于别人的记录与不存在的记录无法区分,接口不能用来探测他人的数据。当记录是否存在本身属于敏感信息时,路由返回 404 而不是 403,`/api/status` 对他人的任务就是这样处理的。 ## 公开接口需要列出并说明理由 每个 API 路由要么使用 `withApiAuth`,要么出现在显式的公开接口列表中并写明理由。服务商 Webhook 和签名授权兑换都在这个列表里:它们通过签名或不可猜测的凭据认证。 ## API Key 与 scope API Key 以哈希形式存储、只显示一次,并带有 scope:`ai:run`、`ai:read`、`files:write` 和 `files:read`。用户可以在自己的 Key 上选择 `ai:run`、`ai:read` 和 `files:write`。`files:read` 为保留项。安装了 agent 时,运营人员还可以签发带 `agent:read` 和 `agent:run` 的 Key。 ## 登录限流 `auth.sign-in` 规则按 IP 与邮箱每 300 秒允许 10 次尝试。它属于 `pnpm db:bootstrap-super-admin` 写入的基线内容,每次判定都会记入审计日志。被拦截的调用者会跳转到 `/system/rate-limited`。 ## 如何强制执行 `pnpm validate:auth-boundary` 检查:会话只在 `src/server/auth/` 中读取、布局守卫各自的路由树、没有身份兜底、开发身份模拟需要双重条件、生产环境拒绝模板默认会话密钥,以及每个 API 路由都使用 `withApiAuth` 或被列为公开。 ## 相关文件 - 唯一允许读会话的地方/ - src/server/auth/context.ts - src/server/auth/guards.ts - src/server/auth/api-boundary.ts - src/server/auth/auth.ts - 守卫在哪里生效/ - src/routes/{-$locale}/app.tsx - src/routes/{-$locale}/admin.tsx ## 下一步 - [架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md) - [签发 API Key 并设置限流](https://kernlift.dev/zh/docs/core/auth/api-keys.md) --- # 管理用户、角色和权限 > 完成后,每位成员只持有其工作所需权限的角色,你也可以暂停或封禁任意账号。 Source: https://kernlift.dev/zh/docs/core/auth/roles 访问控制基于角色。用户持有角色,每个角色授予若干权限键。进入 `/admin` 需要 `admin.access`,每个后台页面再各自检查权限,所以成员能看到哪些页面由其角色确定。 ## 准备工作 * 已用 `pnpm db:bootstrap-super-admin` 创建第一个管理员,见 [安装后的第一步](https://kernlift.dev/zh/docs/customize/first-steps.md)。 * 创建角色需要 `roles.write`;分配角色或修改用户状态需要 `users.write`。 * 带说明的完整权限目录在 `/admin/permissions`。 ## 创建角色 一般来说,`.read` 权限用于打开页面,对应的 `.write` 权限用于在页面上修改数据。 ### 打开角色表单 进入 **运营 → 角色**(`/admin/roles`),切换到 **新增角色** 标签页。 ### 从预设开始(可选) 在 **侧边栏角色预设** 中点击一个预设填入表单。预设包括 **Admin Overview**、**Admin Operations**、**Commerce Manager**、**Platform Operator**、**Content Manager**、**Security Manager** 和 **Settings Manager**。角色列表中已有同样 Key 的角色,可以直接分配。 ### 描述角色 填写 **Key**(稳定的标识,例如 `support.lead`)、**名称** 和 **描述**,三项都必填。 ### 勾选权限 在 **权限** 中勾选要授予的权限。权限按侧边栏区域分组:**Overview**、**Operations**、**Commerce**、**Platform**、**Content**、**Security**、**Settings** 和 **Other**。务必包含 **admin.access**。 ### 保存 点击 **保存角色**。 之后要修改角色,切换到 **角色与用户** 标签页,在 **角色列表** 中该角色所在行点击 **编辑**。**删除** 仅在没有用户持有该角色时可用。带说明的完整权限列表在 `/admin/permissions`(**权限目录**,侧边栏中没有入口)。 ## 为用户分配角色 ### 找到用户 进入 **概览 → 用户**(`/admin/users/dashboard`),找到该用户,点击用户名或 **详情**。 ### 检查状态 在 **访问状态** 中,**状态** 必须是 **正常**。待审核或已封禁的用户无论持有什么角色都没有任何权限。 ### 选择角色 在 **角色** 卡片上点击 **角色** 按钮,在 **更新用户角色** 对话框中勾选要授予的角色、取消要移除的角色,然后点击 **保存角色**。 已经持有角色的用户也会出现在 `/admin/roles` 的 **角色下的用户** 中,点击 **更新角色** 打开同一个对话框。 ## 暂停或封禁用户 ### 打开用户 在 **概览 → 用户** 中点击该用户的 **详情**。 ### 设置状态 把 **状态** 设为 **正常**、**待审核** 或 **已封禁**。封禁时可以填写 **封禁原因** 和 **封禁到期**。 ### 保存 点击 **保存**。页面提示已保存,并记录审计日志。 被封禁的用户无法登录,访问页面会被带到 `/system/permission-denied`,其 API 密钥也会失效。**封禁到期** 时间过后,账号重新视为正常。待审核的用户会被带到 `/system/session-expired`。 **无需重新登录即可生效** 角色和状态的变更在用户下次加载页面时生效,不需要让用户重新登录。 ## 验证 在无痕窗口中以该用户登录。侧边栏只显示其角色允许的页面。通过 URL 打开缺少权限的页面时显示 `Permission denied: <权限>`。**安全 → 审计**(`/admin/audit`)中能看到状态变更。在命令行运行 `pnpm validate:users`,会检查角色保存、分配和状态变更。 ## 常见问题 ### `/admin` 跳转到 `/system/permission-denied` 用户缺少 `admin.access`。分配包含该权限的角色;如果是第一个管理员,运行 `pnpm db:bootstrap-super-admin`。 ### 页面显示 `Permission denied: <权限>` 用户能进入后台,但缺少该页面检查的权限。`/admin` 仪表盘需要四项:`admin.dashboard.read`、`users.read`、`credits.read` 和 `ai.read`,所以范围较窄的角色打开它会报错。 ### 用户持有正确的角色却仍然没有权限 该用户的 **状态** 是待审核或已封禁。在用户详情页把状态改为 **正常**。 ### 新权限没有授予 Super Admin 角色权限在运行 `pnpm db:bootstrap-super-admin` 时写入。升级新增权限后需要再运行一次。 ## 参考 * [用户与账号](https://kernlift.dev/zh/docs/core/auth/users.md) * [Better Auth](https://better-auth.com/docs) ## 下一步 - [认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md) - [运营管理后台](https://kernlift.dev/zh/docs/core/admin.md) --- # 用户与账号 > 查找账号,查看它持有的内容,分配角色,封禁与恢复,以及修复积分余额。 Source: https://kernlift.dev/zh/docs/core/auth/users 运营在 `/admin/users/dashboard` 查看单个账号:买了什么、持有什么、为什么无法登录。这个页面不是 CRM,没有关于客户的自由文本备注,只显示产品写入的数据行。 ## 准备工作 * 打开目录和详情页需要 `users.read`,修改状态需要 `users.write`,修改角色需要 `roles.write`。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 这三个权限相互独立,可以分别授予。客服通常需要第一个,偶尔需要第二个,不需要第三个。 ## 设置 ### 打开目录 `/admin/users/dashboard` 列出账号及其状态和角色,可按姓名或邮箱搜索。 ### 打开一个账号 `/admin/users/$userId` 显示这个账号的角色、访问状态、许可证、积分余额和近期活动。这些数据行与客户在 `/app` 看到的相同,通过同一批仓储读取。 ### 封禁与恢复 被封禁的账号保留所有数据,失去会话。守卫在布局层拒绝该账号,所以 `/app` 和 `/admin` 的每个页面都无法访问,不需要逐页检查。恢复账号即解除封禁,期间不删除任何数据。 ### 修复积分余额 如果账本和缓存余额不一致,`adminRepairUserCreditBalance({ userId })` 根据账本条目重新计算余额。它对应详情页上的按钮,需要 `credits.write`。用户无法调用它,也没有任何由用户写入余额的途径。 ## 账号状态 `users-rbac.ts` 中每个服务端操作都通过 `requireAdminPermission` 校验权限。能看到页面不代表有权限执行操作。 ## 验证 1. 用只有 `users.read` 的角色打开 `/admin/users/dashboard`。列表正常显示,封禁操作被拒绝。 2. 封禁一个账号,然后用这个账号打开 `/app`。布局层拒绝该账号,`/app` 下的页面都打不开。 3. 恢复账号。同一个账号能重新登录,许可证和积分保持不变。 4. 给账号加一个角色并刷新详情页,权限列表是它各角色的并集。 ## 参考 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [认证](https://kernlift.dev/zh/docs/core/auth.md):身份在哪里解析 * [Better Auth:用户与账号](https://better-auth.com/docs/concepts/users-accounts) ## 下一步 - [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) 定义这个目录要分配的角色。 - [积分](https://kernlift.dev/zh/docs/extensions/credits/usage.md) 发放、扣减,以及从账本修复余额。 - [审计日志](https://kernlift.dev/zh/docs/core/admin/audit-log.md) 每一次状态和角色变更都有记录。 --- # 后台任务 > Web 应用如何在每个平台上每分钟执行一轮自己的周期性工作,为什么一行锁就够,以及 /setup 怎样发现它停了。 Source: https://kernlift.dev/zh/docs/core/background-jobs Web 应用有一些不由请求触发的工作:重试失败的履约、收尾没人轮询的 AI 任务。这些工作集中在一个函数 `runScheduledJobs()` 里,它把每个任务各执行一轮。平台之间的差别只在于由谁来调用它。检查自己的部署见[运行后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md)。 ## 一轮,固定的任务列表 一轮按顺序执行各个任务。某个任务抛出异常会被记为失败,后面的任务照常执行。 | 任务 | 作用 | | --------------------- | ------------------------------------------------------------------------------------- | | `credit-sweep` | 扩展点。模板的账本没有需要过期或补发的积分,所以它报告为零;加入会过期的积分时在这里实现 | | `billing-fulfilments` | 按退避间隔重试订单付款或退款时失败的履约 | | `ai-channel-tasks` | 推进没人轮询的异步服务商任务,让它们完成并结算积分 | | `agent-maintenance` | 仅在安装 `agent-starter` 后存在:让有未完成运行的 Cloudflare Agent 容器执行一轮维护。对通过 URL 访问的 Agent 服务不做任何事 | 这些任务属于 Web 应用,不属于 Agent 服务。不部署 Agent 时,除 `agent-maintenance` 外的任务全部照常执行。Agent 服务自己的循环不执行其中任何一个。 ## 一轮的三种触发方式 | 部署方式 | 触发方 | 开关 | | --------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------- | | Node 服务(Fly.io、Railway、Docker、VPS、`pnpm dev`) | Web 进程内的循环:启动五秒后第一轮,之后每分钟一轮 | `JOBS_IN_PROCESS`,默认开启 | | Cloudflare Worker | `wrangler.jsonc` 里的 Cron Trigger `"crons": ["* * * * *"]`,由 Worker 入口的 `scheduled` 处理 | `triggers` 配置块 | | 任意 | 系统 cron、Kubernetes CronJob 或平台调度器调用 `pnpm jobs:run` | 你的调度器 | Node 构建在服务进程加载时就启动循环,所以一个还没有流量的新部署也会重试履约。`pnpm dev` 不会执行服务端入口,循环在第一个请求到来时启动。Worker 不是长驻进程,也不允许持有定时器,所以循环不会在那里启动。设置 `JOBS_IN_PROCESS=false` 会关闭循环,把调度交给 `pnpm jobs:run`。 ## 一行锁保证每分钟只执行一轮 触发可以重叠:每个副本都在运行循环,同时还可能有 cron 触发。锁是 `config_settings` 里的一行 `jobs.next_run_at`,值是 ISO 时间戳。 1. 执行方用一条带条件的更新认领这一轮:只有当 `jobs.next_run_at` 不在未来时才把它往后移。只有一个调用方的更新会改到这一行,其余调用方更新了零行,返回 `"skipped"`。 2. 认领时把时间戳往后推五分钟。执行方中途崩溃的话,锁会在这之后过期。 3. 一轮结束时,`jobs.next_run_at` 设为本轮开始后一分钟,`jobs.last_run_at` 设为结束时间,`jobs.last_report` 写入本轮的 JSON 报告。 比较的是 ISO 时间戳字符串,在 SQLite、D1 和 Postgres 上排序结果一致。认领只有一条语句,因此不需要事务。 ## /setup 上的心跳 `/setup` 不保存任务状态标记。它每次读取 `jobs.last_run_at` 和 `jobs.last_report` 并判断: | 状态 | `/setup` 显示 | | ------------ | ------------------------------------- | | 没有任何一轮的记录 | 未就绪。新部署会在一分钟内记下第一轮;提示一直不消失说明没有任何东西在触发 | | 上一轮在五分钟以前 | 未就绪,并说明是多久以前 | | 上一轮有任务失败 | 未就绪,并列出每个失败任务的名称和错误 | | 上一轮时间很近且全部成功 | 就绪 | 每条提示的末尾都会说明 `deploy.config.json` 所记录的平台是怎样触发的:Cloudflare 的 Cron Trigger、Fly.io 的 `min_machines_running = 1`、Railway 的 Web 服务、Docker 的 Web 容器。这一项没有可以跳转的后台页面,因为它需要在部署平台上修复。 ## 相关文件 - 一轮任务/ - src/server/jobs/scheduled.ts - src/server/jobs/credit-sweep.ts - src/server/db/repositories/scheduled-jobs.repository.ts - 触发方/ - src/server/jobs/in-process.ts - src/server-entry.ts - src/server-entry.node.ts - scripts/jobs/run.ts - 心跳/ - src/server/jobs/heartbeat.ts - src/server/functions/setup-readiness.ts `pnpm validate:optional-agent` 会在当前配置的数据库上真实执行几轮并断言这把锁:一分钟内的第二次调用被跳过,两个并发调用只执行一轮,崩溃的执行方留下的锁会被接管。 ## 下一步 - [运行后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md) 检查你的平台、手动执行一轮、读懂警告。 - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) 这些轮次执行的履约重试。 - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) 为什么每个平台的触发方式不同。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) `JOBS_IN_PROCESS`。 --- # 运行后台任务 > 确认定时任务在你的平台上运行,手动执行一轮,并在 /setup 提示它停止时知道该做什么。 Source: https://kernlift.dev/zh/docs/core/background-jobs/run 履约重试和未完成的 AI 任务由一轮定时任务处理,它应该每分钟执行一次。多数部署下它已经在运行。本文说明如何确认这一点、如何手动执行一轮,以及 `/setup` 提示轮次停止时如何处理。锁和心跳的原理见[后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md)。 ## 准备工作 * 一个已部署的项目,或数据库已迁移的本机项目。 * 拥有 `config.read` 的管理员账号,用来打开 `/setup`。 * 知道项目部署在哪个平台:`deploy.config.json` 的 `platform` 字段,见[部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 确认你的平台在执行任务 ### 找到触发方 | 平台 | 由什么触发 | 检查什么 | | ---------- | ----------------------------- | ---------------------------------------------------------------------------------- | | Cloudflare | Worker 的 Cron Trigger | `wrangler.jsonc` 保留 `"triggers": { "crons": ["* * * * *"] }`,且已部署的 Worker 列出了这个触发器 | | Fly.io | Web 进程内的循环 | `fly.toml` 保留 `min_machines_running = 1`;停掉的机器什么也不会执行 | | Railway | Web 服务内的循环 | Web 服务在运行 | | Docker | Web 容器内的循环 | 容器在运行:`docker compose ps` | | 本机 | 同一个循环,由 `pnpm dev` 收到的第一个请求启动 | 打开任意页面一次 | 在 Node 平台上,除非设置了 `JOBS_IN_PROCESS=false`,循环默认开启。 ### 决定是否改用外部 cron 没有特别理由就保留进程内循环。需要把调度移出 Web 进程时(例如 Web 机器会缩容到零),在 Web 应用的环境里设置 `JOBS_IN_PROCESS=false`,再让调度器每分钟执行一次下面的命令,数据库变量与 Web 应用保持一致: ```bash pnpm jobs:run ``` 循环和 cron 同时存在也是安全的。锁行保证每一轮只有一个执行方执行,其余的跳过。 ### 手动执行一轮 在 `.env` 指向目标数据库的检出目录里运行: ```bash pnpm jobs:run ``` 它会打印这一轮的报告,有任务失败时退出码非零: ```json { "startedAt": "2026-11-17T08:00:00.000Z", "finishedAt": "2026-11-17T08:00:00.412Z", "jobs": [ { "name": "credit-sweep", "ok": true, "counts": { "expiredUsers": 0, "granted": 0 } }, { "name": "billing-fulfilments", "ok": true, "counts": { "attempted": 0, "succeeded": 0 } }, { "name": "ai-channel-tasks", "ok": true, "counts": { "polled": 0 } } ] } ``` 如果打印的是 `"skipped"`,说明最近一分钟内已有别的执行方拿走了这一轮。这是正常现象,等一分钟再执行。安装了 `agent-starter` 的项目还有第四个任务 `agent-maintenance`。 ## 读懂 /setup 上的警告 打开 `/setup`,找到定时任务这一项。每次加载页面时,页面都根据最近一次记录的轮次重新计算这一项的状态。 | 这一项的提示 | 含义 | 处理 | | ------------------------------------------------------ | ----------------- | --------------------------------------------- | | No scheduled round has been recorded | 数据库建好之后还没有执行过任何一轮 | 新部署等一分钟。一直不消失说明上表中的触发方缺失 | | The last scheduled round ran N minutes ago | 超过五分钟没有新的一轮 | 检查你所在平台的触发方,提示里会指出。恢复之前,履约重试和 AI 任务轮询都在等待 | | The last round had failures | 某个任务抛出了异常 | 读提示里的任务名和错误,修复原因,再运行 `pnpm jobs:run` 查看该任务的结果 | | Last round less than a minute ago, every job succeeded | 轮次在正常执行 | 无需处理 | 某个任务失败不会影响同一轮里的其它任务,下一轮还会再试。 ## 验证任务在运行 * `/setup` 的定时任务一项为就绪,上一轮距今不超过几分钟。 * 两分钟后刷新 `/setup`,上一轮的时间已更新。 * `config_settings` 中 `jobs.last_run_at` 是一个很近的 ISO 时间戳,`jobs.last_report` 是那一轮的报告。 * `pnpm validate:optional-agent` 通过。发布前,`pnpm smoke:node`(先 `pnpm build:node`)或 `pnpm smoke:worker`(先 `pnpm build`)会在一次性数据库上启动构建产物,并检查确实记录了一轮。 ## 下一步 - [后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md) 锁、心跳和任务列表。 - [编写履约插件](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md) 这些轮次执行的重试。 - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) 每一轮持续推进的 AI 任务。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) `JOBS_IN_PROCESS` 以及 `pnpm jobs:run` 读取的数据库变量。 --- # 配置模型 > 为什么少数设置放在环境变量里,而其他一切都保存在数据库中、在管理后台编辑。 Source: https://kernlift.dev/zh/docs/core/configuration Kernlift 把设置放在两个地方。少量环境变量用于启动应用并连接数据库。其余设置,包括所有服务商凭据,都保存在数据库中,在管理后台编辑。修改设置见[管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md)。 ## 规则 | 设置 | 放在哪里 | 原因 | | ---------------------- | ------------------------------------------ | ---------------- | | 应用环境、会话密钥、数据库连接、站点 URL | `.env` 或主机的环境变量 | 应用读取数据库之前就需要 | | 登录方式、邮件、支付、存储、AI、分析、缓存 | 管理后台 `/admin/config/*` | 保存在数据库中,修改无需重新部署 | | 产品、方案与授权 | 管理后台 `/admin/products` 与 `/admin/licences` | 业务数据,不是配置 | 划分依据是启动顺序。进程在打开数据库之前需要的设置来自环境变量。其余设置保存在数据库中,由运营者管理。 ## 为什么服务商设置不是环境变量 * **更换服务商无需重新部署。** 轮换密钥、切换当前邮件服务商或开启 Google 登录,只需在管理后台保存一次。 * **单一事实来源。** `/setup` 清单、后台页面和运行时读取的是同一批数据行,所以页面显示的就是服务端实际使用的配置。 * **便于 fork 的模板。** 基于模板构建的项目把服务商设置加到后台界面,不新增环境变量。功能代码不读取 `process.env`。 ## 环境变量 本地项目只需要 `BETTER_AUTH_SECRET`,在[快速开始](https://kernlift.dev/zh/docs/quick-start.md)里已经设置。生产环境需要设置: | 变量 | 作用 | | ----------------------- | ---------------------------------------------- | | `APP_ENV` | `development` 或 `production`。生产环境会启用更严格的检查 | | `BETTER_AUTH_SECRET` | 签名会话。生产环境使用模板默认值时拒绝启动 | | `CONFIG_ENCRYPTION_KEY` | 可选,生产环境强烈建议设置。加密存在数据库里的凭据,见[加密存储的凭据](#加密存储的凭据) | | `DATABASE_DIALECT` | `sqlite`、`postgres` 或 `d1` | | `DATABASE_ADAPTER` | 可选的适配器 id,例如 `turso` 或自定义适配器。默认等于方言 | | `DATABASE_URL` | 文件路径或连接串 | | `SITE_URL` | 元数据、站点地图、订阅源和邮件链接使用的规范源地址 | `.env.example` 列出源代码读取的每个变量,`pnpm validate:env-example` 确保两者保持一致。每个变量的说明见[环境变量](https://kernlift.dev/zh/docs/reference/env.md)。 ## 后台设置页面 | 页面 | 内容 | | ------------------------- | -------------------------------------------------------------- | | `/admin/config/auth` | 邮箱密码规则、Google 与 GitHub OAuth、Google One Tap、注册奖励 | | `/admin/config/email` | Resend、Cloudflare Email 或阿里云邮件推送,以及通知 Webhook | | `/admin/config/payment` | Stripe、Creem、PayPal、DodoPayments、微信支付、支付宝或 Waffo,成功与取消 URL,优惠码 | | `/admin/config/storage` | S3 兼容存储与允许的上传类型 | | `/admin/config/ai` | AI 服务商、服务商场景、场景与积分定价 | | `/admin/config/analytics` | 分析服务商 | | `/admin/config/cache` | 每个缓存域的启用状态、TTL 与后端 | | `/admin/config/sandbox` | Agent 沙箱服务商、镜像与资源上限;安装 `agent-starter` 后出现 | | `/admin/config/search` | Agent 搜索与抓取服务;安装 `agent-starter` 后出现 | 订阅、通知渠道和限流规则各有独立的后台页面。完整路由与权限见[管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md)。 ## 「未配置」是一种状态,不是错误 没有凭据的服务商会报告「未配置」,并且不运行。模板从不伪造服务商响应、模拟支付或编造用量数据。`/setup` 把这些状态汇总成清单:每一项显示**已就绪**或**未就绪**,**去配置**链接到修复它的页面。只有会话密钥、登录方式和邮件投递是必需的。 ## 加密存储的凭据 凭据存在数据库里,数据库备份、只读副本或数据库控制台一旦泄露就会暴露它们。在每个读取配置表的进程(Web 应用,以及部署了的 Agent 服务)的环境中设置 `CONFIG_ENCRYPTION_KEY`(至少 32 个字符),所有分类为 `secret` 的设置就会静态加密: * **加密什么**:分类为 `secret` 的值,即支付、邮件、存储、AI 和 OAuth 凭据。写入格式为 `enc:v1::<密文>`,算法 AES-256-GCM,密钥经 HKDF-SHA-256 派生,配置键作为附加数据参与加密,密文无法挪到其它行使用。`public` 和 `internal` 保持明文。 * **已有凭据**:设置密钥之前保存的凭据在再次保存前仍是明文。执行一次 `pnpm db:encrypt-config-secrets` 全部加密;D1 加 `--remote` 处理线上数据库。重复执行不会改动任何行。 * **密钥错误或缺失**:解不开的值读作未配置,绝不返回密文;写入默认值时也不会覆盖它,换回正确的密钥即可恢复。 * **缓存**:持有解密后凭据的缓存域固定使用进程内存,在 `/admin/config/cache` 不能为它们选择 KV 或 Redis。 * **就绪检查**:`/setup` 有一项 **凭证加密**,会报告密钥缺失或过短、遗留的明文凭据以及解不开的凭据;只有最后一种会让它成为必需项。 不设置密钥时凭据以明文存储,其余行为不变,适合本地开发。`kernlift deploy-target` 会把密钥生成到 `.env.production`。密钥要保持不变:目前不支持轮换,更换或丢失密钥就需要重新录入所有凭据。 ## 设置如何读取 多数配置读取经过缓存。通过后台保存时会清除对应缓存域。若直接修改数据库,变更可能要等到 TTL 到期才被读取。引导域 `admin_config` 不能从自己缓存的表中读取策略,因此其 TTL 来自 `ADMIN_CONFIG_CACHE_TTL_MS`。`/admin/config/cache` 将该域标记为不可编辑。 ## 应用之外的变量 `.env.example` 末尾的 `KERNLIFT_*` 变量只由 registry 发布脚本和 CLI 的包管理命令读取。应用本身从不读取它们,从 GitHub 克隆的项目不用设置。 ## 相关文件 - 存储与缓存/ - src/server/db/repositories/admin-config.repository.ts - src/server/config/config-encryption.ts - scripts/db/encrypt-config-secrets.ts - src/server/platform/cache-policy.ts - 配置页/ - src/routes/{-$locale}/admin/config - src/components/admin/config-layout.tsx 这些页面共用后台界面模式,但存储方式并不相同:一般服务商设置使用带分类的 `config_settings` 行,AI 通道与定价使用专用数据表,Agent 搜索使用分类为 `secret` 的 JSON 行。 ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) 这一页的操作版。 - [缓存](https://kernlift.dev/zh/docs/core/admin/cache.md) 一项设置被缓存多久,你的改动多久才被读到。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) 保存在数据库之外的少量变量。 - [安装后的第一步](https://kernlift.dev/zh/docs/customize/first-steps.md) /setup 要求先配置的内容。 --- # 配置一个可运行的项目 > 从启动变量开始,完成登录与邮件投递,再按实际使用的功能接入服务商并验证。 Source: https://kernlift.dev/zh/docs/core/configuration/project 首次部署时,先让应用能启动、管理员能登录、系统能发送验证邮件。支付、文件、AI 等集成按产品需要逐项开启;页面存在并不代表服务商已就绪。 ## 准备工作 * 数据库已迁移;你可以修改运行环境,并有一个能登录的管理员账号。还没有管理员时,先按[管理后台入门](https://kernlift.dev/zh/docs/core/admin.md)创建。 * 准备所用服务商的测试或沙箱账号。生产凭据由后台保存,不要写进 `.env`。变量清单见[环境变量](https://kernlift.dev/zh/docs/reference/env.md)。 ## 1. 设置启动环境 以 `.env.example` 为清单,在本地 `.env` 或托管平台设置 `APP_ENV`、`BETTER_AUTH_SECRET`、`SITE_URL` 和数据库连接。生产环境的 `BETTER_AUTH_SECRET` 必须是新生成的随机值,不能留空或沿用模板值。可用以下命令生成: ```bash node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``` 生产环境还要把 `CONFIG_ENCRYPTION_KEY` 设为至少 32 个字符的值(可用同一命令生成),这样接下来录入的服务商凭据会加密存库。设置后保持不变。若设置前已保存过凭据,执行一次 `pnpm db:encrypt-config-secrets`。见[加密存储的凭据](https://kernlift.dev/zh/docs/core/configuration.md)。 环境变量在进程启动时读取。保存后重启应用,运行 `pnpm db:migrate`,确认数据库迁移成功。数据库方言和 Workers 绑定的选择见[数据库与部署](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 2. 保留一种可用的登录方式 登录后台,打开 **认证配置**。邮箱密码登录默认开启;如果关闭它,先配置并测试 Google 或 GitHub 登录,否则用户会失去登录入口。按需要设置邮箱验证、注册和账号注销策略。社交登录前要在服务商侧登记页面显示的回调地址,再填入客户端 ID 与密钥。 保存后退出当前会话,分别测试登录和新账号注册。具体字段与 OAuth 回调流程见[邮箱密码登录](https://kernlift.dev/zh/docs/extensions/auth/email-password.md)和[社交登录](https://kernlift.dev/zh/docs/extensions/auth/social.md)。会话签名密钥 `BETTER_AUTH_SECRET` 仍在环境变量中,不在此页设置。 ## 3. 让邮件实际送达 在 **邮件配置** 中选择 Resend、Cloudflare 或阿里云,填写服务商凭据和已验证的发件地址,启用并保存。域名验证要先在服务商控制台完成。接着到 **邮件 → 测试发送** 发一封邮件,并在投递记录中确认成功;再走一次注册验证或密码重置流程。 保存成功只说明设置已写入,不等于邮件已经送达。失败时先核对发件域名、凭据及投递记录中的服务商错误。字段和模板操作见[邮件指南](https://kernlift.dev/zh/docs/extensions/email.md)。 ## 4. 按功能继续配置 只配置项目实际会用到的集成,每完成一项就做对应的端到端验证: | 要启用的功能 | 配置重点 | 验证结果 | | --------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 收款与订阅 | 在支付配置中填写沙箱凭据、回跳地址和 Webhook 密钥,再在 **套餐**(`/admin/plans`)中创建至少一个上架的套餐 | 完成一次沙箱结账;订单状态由已签名 Webhook 或服务端确认更新。见[支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) | | 文件上传或 Agent 产物 | 选择 S3 兼容存储或 R2 绑定,填写桶、访问密钥、大小和类型限制 | 上传一个允许的文件,并以该用户身份下载。见[存储](https://kernlift.dev/zh/docs/extensions/storage.md) | | AI 任务或 Agent 模型 | 创建通道及服务商场景,配置密钥、模型、场景路由和定价 | 发起一项测试任务,确认返回真实服务商结果并记录用量。见[AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)和[场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) | | 分析与客服聊天 | 填写脚本 ID;需要报表时另配服务端访问令牌 | 在浏览器确认脚本加载并产生测试事件;报表拉取单独验证。见[分析](https://kernlift.dev/zh/docs/extensions/analytics.md) | | Agent 沙箱与网页检索 | 先安装 `agent-starter`,配置对象存储和 AI;再填写沙箱、SearXNG、crawl4ai 的连接与限额 | 分别测试搜索与抓取连接,并在工作台运行需要这些工具的任务。见[Agent 模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) | 缓存默认可用。需要调整时,在 **缓存配置** 中逐域选择启用状态、TTL 和可用后端;关闭 **启用** 才会绕过缓存,TTL 不能设为 0。见[缓存](https://kernlift.dev/zh/docs/core/admin/cache.md)。订阅、通知、定价套餐和 API Key 限流在各自的业务页面配置,各自的位置见[运行管理后台](https://kernlift.dev/zh/docs/core/admin.md)。 ## 确认配置状态 打开 `/setup`。会话密钥、登录方式、邮件投递和定时任务是必需项;它还显示支付、存储、AI、订阅和分析的可选状态,以及 **凭证加密**;存储的凭据无法解密时该项变为必需。该清单不检查缓存、Agent 沙箱或搜索,因此还要执行上表中的功能测试。不要用页面是否能打开来判断服务商可用。 ## 排查 * **无法启动或会话密钥报错**:检查 `APP_ENV` 和 `BETTER_AUTH_SECRET`,修改后重启。生产环境拒绝空值和模板默认值。 * **设置已保存但功能未就绪**:先看对应页面的配置状态和测试结果,再查服务商返回的错误。后台保存成功不代表服务商连接成功。 * **AI 配置菜单可见但页面打不开**:侧边栏按 `config.read` 显示,页面读取实际需要 `ai.read`,保存需要 `ai.write`。 * **某个模块的页面或菜单不见了**:检查 **插件**(`/admin/plugins`);插件停用后入口会隐藏,页面返回 not found。 * **`/setup` 提示定时任务没有运行**:这需要在部署平台上修复。见[排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md)。 * **修改似乎未生效**:后台保存通常清除对应缓存;若绕过后台直接改数据库,可能需等缓存 TTL 到期或手动清除。见[缓存](https://kernlift.dev/zh/docs/core/admin/cache.md)。 --- # 数据访问 > 业务代码如何访问数据库:只经过仓储,同一套契约覆盖 SQLite、D1 和 Postgres,事务在每种数据库上意味着什么,以及为什么迁移按方言分别维护。 Source: https://kernlift.dev/zh/docs/core/data-access 同一套业务代码可以运行在 SQLite、Cloudflare D1 和 Postgres 上。所有数据库访问都经过 `src/server/db/repositories/*`,数据库之间的差异都放在下层的 schema、迁移和适配器层。切换数据库见[使用 Postgres](https://kernlift.dev/zh/docs/extensions/database/postgres.md)。 ## 仓储是唯一的入口 服务端函数、服务和 API 路由调用仓储函数。它们不导入 Drizzle 表、不写 SQL,也不按方言分支。仓储通过 `withRepositoryDialect` 获得三个值: | 值 | 含义 | | --------- | ---------------------------------------------------- | | `db` | 当前适配器的 Drizzle 数据库 | | `schema` | 该数据库对应的表定义:`schema/postgres.ts` 或 `schema/sqlite.ts` | | `dialect` | `"postgres"`、`"sqlite"` 或 `"d1"` | 两个 schema 文件定义了同名、同列的表,所以仓储针对 `schema.billingOrders` 写一条查询,在两边都能运行。某一列的存储方式不同时(最常见的是时间戳),仓储就在那一处根据 `dialect` 做转换。Agent 的表在 `agent-sqlite.ts` 和 `agent-postgres.ts` 中遵循同样的做法。 ## 两个 schema 家族,五个适配器 适配器决定应用如何连接,schema 家族决定执行哪种 SQL。 | 适配器 | Schema 家族 | 运行环境 | 连接方式 | | ------------ | --------- | ------------------ | ------------------------------------------------ | | `sqlite` | SQLite | Node | 通过 `better-sqlite3` 访问本地文件 | | `turso` | SQLite | Node | libSQL,使用 `DATABASE_URL` 和 `DATABASE_AUTH_TOKEN` | | `d1` | SQLite | Cloudflare Workers | `EDGE_DB` 绑定 | | `postgres` | Postgres | Node | `DATABASE_URL`,每个进程一个客户端 | | `hyperdrive` | Postgres | Cloudflare Workers | `HYPERDRIVE` 绑定,每个请求一个客户端 | `DATABASE_ADAPTER` 选择其中之一,默认与 `DATABASE_DIALECT` 相同。两个家族都可以注册自己的适配器,见[编写自定义数据库适配器](https://kernlift.dev/zh/docs/extensions/database/custom-adapter.md)。 Worker 不能复用在处理另一个请求时打开的 socket。因此 `hyperdrive` 适配器把 Postgres 客户端创建在按请求划分的作用域里:Worker 入口用 `runInRequestScope` 包住每个请求和每次定时事件,客户端的生命周期与该作用域相同。真正的连接由 Hyperdrive 池化。Node 上没有这个作用域,`postgres` 适配器始终保留一个客户端。 ## 事务在每种数据库上意味着什么 仓储只写一遍,使用异步事务回调:`db.transaction(async (tx) => { ... })`。实际执行方式取决于数据库。 | 数据库 | 行为 | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Postgres、Hyperdrive、Turso | 驱动把回调作为交互式事务执行 | | SQLite(`better-sqlite3`) | 驱动是同步的,拒绝异步回调,所以仓储门面在同一个连接上把它作为真正的事务执行:`BEGIN IMMEDIATE`,然后 `COMMIT`,失败则 `ROLLBACK` 并抛出原始错误。同一进程内的事务按顺序一个一个执行,嵌套调用会加入已打开的事务 | | D1 | 没有交互式事务。仓储上下文报告 `d1`,本来要开事务的代码改为把同样的语句逐条执行 | 在 SQLite 上,事务回调里只应做数据库操作并保持简短,因为进程里其它已排队的工作可能在它的语句之间执行。在 D1 上,多步写入不是原子的,所以必须能安全地重复执行或中途停下。需要事务来保存运行状态的 Agent 也因此不使用 D1。 一条语句就够的地方,代码就只用一条。定时任务的锁是一条带条件的更新,履约的认领是唯一键下的一次插入,所以它们在三种数据库上行为一致。 ## 迁移按方言分别维护 迁移链有两条,每个 schema 家族一条,文件名相同: | 迁移链 | 用于 | 执行方式 | | ----------------------------- | ------------------- | ------------------------------------------------------------------------------- | | `drizzle/migrations/sqlite` | SQLite、Turso、D1 | `pnpm db:migrate`;D1 用 `pnpm db:migrate:d1:local` 和 `pnpm db:migrate:d1:remote` | | `drizzle/migrations/postgres` | Postgres、Hyperdrive | `pnpm db:migrate`,生产镜像里用 `pnpm db:migrate:runtime` | 两条链都由人手工维护。改 schema 意味着同时修改两个 schema 文件,并在两条链里各加一个同名迁移。`pnpm db:generate:sqlite` 和 `pnpm db:generate:postgres` 可以分别生成初稿。之后由 `pnpm validate:migrations` 检查两条链是否一致:日志与文件一致,每条链都能在空库上重放,每个 `--> statement-breakpoint` 分段只含一条语句,两种方言最终得到相同的表。 `pnpm db:migrate` 对迁移工具做了一层包装,用来解释一种它原本会静默失败的状态:表已经存在,但迁移记录为空,说明数据库不是通过迁移链建立的。 ## 相关文件 - 仓储/ - src/server/db/repositories - src/server/db/repositories/repository-dialect.ts - Schema/ - src/server/db/schema/sqlite.ts - src/server/db/schema/postgres.ts - src/server/db/schema/agent-sqlite.ts - src/server/db/schema/agent-postgres.ts - 适配器与事务/ - src/server/db/client.ts - src/server/db/adapter-registry.ts - src/server/db/sqlite-transactions.ts - src/server/platform/request-scope.ts - 迁移/ - drizzle/migrations/sqlite - drizzle/migrations/postgres - scripts/db/migrate.ts - scripts/db/migrate-runtime.mjs 有三个校验器覆盖这一层:`validate:db-adapters`(注册表、绑定与服务端入口)、`validate:migrations`(两条迁移链)和 `validate:sqlite-transactions`(默认 SQLite 适配器上的提交、回滚、顺序与嵌套)。 ## 下一步 - [使用 Postgres](https://kernlift.dev/zh/docs/extensions/database/postgres.md) 切换方言并执行第二条迁移链。 - [编写自定义数据库适配器](https://kernlift.dev/zh/docs/extensions/database/custom-adapter.md) 为同一套 schema 换一种连接方式。 - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) 每个平台允许使用哪些数据库。 --- # 开发一个模块 > 把一项功能做成仓库里的一个模块:代码、两种方言的 schema 与迁移、区域标记、清单和校验器。 Source: https://kernlift.dev/zh/docs/core/plugins/build-a-module 模块是一项边界被仓库准确记录下来的功能:它的文件、它在共享文件里的区域、它的数据表和设置。把你自己的功能做成模块,就能与上游代码分开,合并时冲突更少,`pnpm validate:registry` 还能证明底座在没有它时仍然可以编译。本指南从头到尾添加一个模块。仓库自带的 `affiliate` 模块(`modules/affiliate/module.json`)是一个完整的例子,可以对照着看。 如果你使用编码 agent,`new-module` skill 包含同样的步骤,见[使用编码 Agent 技能](https://kernlift.dev/zh/docs/core/agent-skills.md)。 ## 准备工作 * 一份 `pnpm validate:registry` 能通过的仓库克隆。开始之前记下哪些校验器是通过的,之后才能确认没有让任何一个由通过变为失败。 * 一个 kebab-case 的 key,下文写作 ``,例如 `reviews`。清单目录和标记都用它命名。 * 模块拥有的数据表、新增的页面,以及需要的权限键。 * 它依赖的模块的 key。例如 `image-agent` 依赖 `agent-starter`。 ## 添加模块 ### 提出变更 ```bash openspec-cn new change "" openspec-cn validate "" ``` 校验之前,先填好 `openspec/changes//` 下的 `proposal.md`、`design.md`、`specs//spec.md` 和 `tasks.md`。 ### 添加数据表,并为两种方言各生成迁移 在 `src/server/db/schema/sqlite.ts` 和 `src/server/db/schema/postgres.ts` 中都定义这些表,表名保持一致。然后为每种方言生成一个迁移: ```bash pnpm db:generate:sqlite --name my-change pnpm db:generate:postgres --name my-change pnpm validate:migrations ``` Postgres 那一条需要设置 `DATABASE_URL`,但不会连接数据库。两种方言最终要有相同的迁移标签(例如 `0018_`),分别位于 `drizzle/migrations/sqlite` 和 `drizzle/migrations/postgres`。 ### 编写代码 | 内容 | 位置 | | ------------------------------------- | ------------------------------------------------------------- | | 数据访问 | `src/server/db/repositories/.repository.ts` | | 业务逻辑 | `src/server/services/.service.ts` | | 服务端函数,用 `requireAdminPermission` 检查权限 | `src/server/functions/.ts` | | 组件 | `src/components//` | | 页面 | `src/routes/{-$locale}/admin/` 或 `src/routes/{-$locale}/app/` | | 插件:清单以及 `admin.nav` 导航项等贡献 | `src/plugins//manifest.ts`、`src/plugins//plugin.ts` | 所有数据库访问都经过 repository。业务代码不出现具体的 SQL 方言。`/admin` 和 `/app` 的布局已经保护了各自的路由树,新页面不需要自己加守卫。插件能贡献什么,见[插件](https://kernlift.dev/zh/docs/core/plugins.md)。 ### 接入共享文件 模块还需要在底座拥有的文件里加几行: * `src/plugins/installed.ts` 中的插件 import 和列表项; * `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` 中的文案,两边的键必须一致; * `src/server/services/super-admin-bootstrap.service.ts` 中的权限行,以及 `src/server/db/repositories/users-rbac.repository.ts` 中的预设角色。 把这些片段,连同第 2 步的数据表,用标记行包起来: ```ts // @module: import { reviewsPlugin } from "./reviews/plugin"; // @end-module: ``` 注释语法跟随文件类型:`//`、`/* */`、``、`--` 或 `#`,在 JSX 元素之间则写 `{/* @module: */}`。区域不能嵌套,而且去掉所有区域后底座必须仍能编译。在 `src/plugins/installed.ts` 中保持 import 的排序,这样整理 import 时不会把某一行移出它的区域。 ### 编写校验器 创建 `scripts/validate/.ts`。断言行为和接线,不要只断言文件存在。用名称以 `validate-` 开头的测试数据调用 repository,检查结果,再把测试数据清理掉。然后在 `package.json` 中加上: * 脚本 `"validate:": "tsx scripts/validate/.ts"`; * `validate:all` 链中的 `pnpm validate:` 片段。 ### 编写清单 创建 `modules//module.json`。目录名必须与 `key` 相同。 ```json { "key": "reviews", "kind": "module", "version": "0.1.0", "requires": [], "files": [ "src/plugins/reviews/**", "src/components/reviews/**", "src/routes/{-$locale}/admin/reviews.tsx", "src/server/services/reviews.service.ts", "src/server/db/repositories/reviews.repository.ts", "src/server/functions/reviews.ts", "scripts/validate/reviews.ts" ], "fragments": [ "src/plugins/installed.ts", "src/server/db/schema/sqlite.ts", "src/server/db/schema/postgres.ts", "src/i18n/locales/en/messages.ts", "src/i18n/locales/zh/messages.ts", "src/server/services/super-admin-bootstrap.service.ts", "src/server/db/repositories/users-rbac.repository.ts" ], "migrations": ["0018_reviews"], "packages": [], "validators": ["validate:reviews"], "i18nNamespaces": ["reviewsCopy"], "admin": { "routes": ["/admin/reviews"], "configPages": [] }, "screenshots": [], "docs": [], "tables": ["reviews"], "configKeys": [], "skillPackages": [] } ``` | 字段 | 构建时强制的规则 | | ---------------------- | ----------------------------------------------------- | | `files` | 每个 glob 至少匹配一个文件;同一个文件不能被两个模块认领。以 `!` 开头表示排除某个路径 | | `fragments` | 列出的每个文件都有 `@module:` 区域;模块完全拥有的文件不带标记 | | `migrations` | 该标签在两种方言中都有 `.sql` 文件和 journal 条目 | | `packages` | `name@range` 形式,并且存在于 `package.json` 的 dependencies 中 | | `validators`、`scripts` | `package.json` 中存在的脚本名 | | `tables` | 与模块的文件和区域在两种方言中定义的表完全一致。模块有迁移时必须声明 | | `configKeys` | 模块自己的代码写入的后台配置键。以 `.` 结尾表示该前缀下的所有键 | | `skillPackages` | 模块自己的代码发布的 Skill 包 id,它自带的每个 Skill 目录对应一个 | 其余字段是描述性的。`key` 与目录名相同,`version` 是模块自己的版本。`kind` 对一项功能是 `module`,对自带运行时的条目是 `template`,例如 `agent-starter`。`requires` 列出它依赖的模块。`i18nNamespaces` 是它拥有的字典命名空间,`admin`、`screenshots` 和 `docs` 记录它的后台页面与素材。 `tables`、`configKeys` 和 `skillPackages` 说明模块拥有哪些数据,所以构建会把它们与代码核对。 ### 用构建核对清单 ```bash pnpm registry:build ``` 构建按清单切分仓库,并写入 `registry/dist/`:`index.json`、每个条目一个 `@.json`,较大的条目还有 `.files..json` 分页。它为每个条目打印一行,包含文件数、片段数和迁移数。清单违反上面任何一条规则时,构建会停止,并在错误信息中指出模块和问题。 ### 归档变更 ```bash openspec-cn archive "" -y --skip-specs ``` `registry/dist/` 是构建产物,已被 git 忽略,不需要保留。 ## 验证模块 * `pnpm validate:registry` 通过:底座加上所有模块能逐字节重现仓库,并且底座在没有任何模块时能通过类型检查。 * `pnpm validate:`、`pnpm validate:plugins`、`pnpm validate:app-i18n`、`pnpm validate:route-i18n`、`pnpm validate:auth-boundary` 和 `pnpm validate:migrations` 通过。 * `pnpm typecheck`、`pnpm build` 和 `pnpm check` 没有新增问题,`pnpm validate:all` 没有让原本通过的检查失败。 * `pnpm validate:kernlift-lifecycle` 通过:它在一个临时项目里应用并移除构建出的条目,包括数据清除。 ## 常见问题 ### 「has migrations but declares no tables in module.json」 把模块创建的每一张表都列进 `tables`。 ### 「module.json tables \[…] differ from the sqlite tables its files define \[…]」 `tables` 必须与模块自己的文件和标记区域中 `sqliteTable(...)`、`pgTable(...)` 的表名一致。要么有表定义落在了 `@module` 区域之外,要么列表过期了。 ### 「no file matches …」 `files` 中有一个 glob 什么都没匹配到。修正路径或删掉这一项。 ### `… has no @module: region` `fragments` 中列出的某个文件没有该模块的区域。加上标记,或者把这个文件从 `fragments` 中去掉。 ### `pnpm validate:registry` 在底座类型检查时失败 底座中的某个文件引用了模块拥有的东西。把这个 import 移进 `@module` 区域,或者让底座通过插件插槽使用该功能。 ## 下一步 - [底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md) - [插件](https://kernlift.dev/zh/docs/core/plugins.md) - [模板与派生产品](https://kernlift.dev/zh/docs/core/plugins/templates.md) - [校验器与发布门禁](https://kernlift.dev/zh/docs/core/validators.md) --- # 编写后台插件 > 把自己的功能做成一个本地插件:用户工作区的侧边栏入口、一个页面和一张仪表盘卡片,管理员可以随时启用和停用。 Source: https://kernlift.dev/zh/docs/core/plugins/console-plugins 本地插件把你写的功能接入后台,不需要改外壳代码。本文做一个叫 `notes` 的插件:用户工作区侧边栏里的一个入口、`/app/notes` 页面,以及 `/app` 仪表盘上的一张卡片。管理后台的做法相同,只是换成 `admin.nav` 插槽。内核的工作方式见[插件](https://kernlift.dev/zh/docs/core/plugins.md)。 ## 准备工作 * 项目能用 `pnpm dev` 在本地运行。 * 一个持有 `config.read` 和 `config.write` 的管理员账号,用来打开 **设置 → 插件**。 * 想好插件 id:小写短横线形式,例如 `notes`,在 `src/plugins/installed.ts` 的插件里唯一。 * 开始之前记录 `pnpm validate:all` 的通过和失败情况,方便之后确认没有检查由通过变为失败。 ## 编写插件 ### 写清单 清单是纯数据。`kind: "local"` 表示插件属于这个项目。`routes` 列出插件拥有的路径前缀,不含语言前缀。 ```ts title="src/plugins/notes/manifest.ts" import { defineManifest } from "../kernel/types"; export const notesManifest = defineManifest({ id: "notes", version: "0.1.0", kind: "local", routes: ["/app/notes"], }); ``` ### 加文案 导航文案是词典 key。在 `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` 的 `appConsole` 命名空间里都加上 `notes`。只在一种语言里存在的 key 会让 `pnpm validate:app-i18n` 失败。 ### 加页面 在带语言前缀的路由树下创建路由。`active` 必须是下一步贡献的 `app.nav` 条目的 `id`。 ```tsx title="src/routes/{-$locale}/app/notes/index.tsx" import { createFileRoute } from "@tanstack/react-router"; import { useAuth } from "@/components/auth/auth-state"; import { AppConsoleLayout } from "@/components/layout/app-console-sidebar"; import { useI18n } from "@/i18n/use-i18n"; export const Route = createFileRoute("/{-$locale}/app/notes/")({ component: NotesPage, }); function NotesPage() { const { locale, t } = useI18n(); const { user } = useAuth(); return (

{t("appConsole.notes")}

); } ``` 页面自己不需要守卫。`/app` 布局负责鉴权,插件停用时同一个布局会让这条路由返回未找到。数据通过调用 `requireCurrentUserId()` 的 server function 加载,做法见[新增页面](https://kernlift.dev/zh/docs/customize/new-page.md)。 ### 写仪表盘卡片 仪表盘卡片是一个接收当前语言的组件。 ```tsx title="src/plugins/notes/notes-card.tsx" import { Surface, SurfaceContent } from "@/components/motion/surface"; import { getDictionary, type Locale, localizedPath } from "@/i18n/messages"; export function NotesCard({ locale }: { locale: Locale }) { const { t } = getDictionary(locale); return ( {t("appConsole.notes")} ); } ``` 组件用 `@workspace/beui`、`src/components/motion` 和 Tailwind 工具类来写。`src/plugins` 下的文件如果 import 了 `src/components/ui` 或读取 `process.env`,`pnpm validate:plugins` 会失败。 ### 向插槽贡献 ```ts title="src/plugins/notes/plugin.ts" import { NotebookPen } from "lucide-react"; import { definePlugin } from "../kernel/types"; import { notesManifest } from "./manifest"; import { NotesCard } from "./notes-card"; export const notesPlugin = definePlugin({ manifest: notesManifest, contributes: { "app.nav": [ { id: "notes", icon: NotebookPen, labelKey: "appConsole.notes", path: "/app/notes", section: "product", order: 50, }, ], "app.dashboard.cards": [{ id: "notes.summary", order: 10, component: NotesCard }], }, }); ``` 基础版自己的 `product` 条目用的是 0 到 40,所以 50 会排在它们后面。每个字段的类型在 `src/plugins/slots.ts` 里,见[客户端插槽与服务端插槽](https://kernlift.dev/zh/docs/core/plugins.md)。 ### 登记 把插件加进安装列表。写在所有 `// @module:` 区段之外。这些区段属于随仓库提供的模块,本地插件放进去会导致校验器失败。 ```ts title="src/plugins/installed.ts" import { notesPlugin } from "./notes/plugin"; export const installedPlugins: readonly Plugin[] = [ foundationPlugin, // … 随仓库提供的模块的区段 … notesPlugin, ]; ``` 运行一次 `pnpm dev`,让 `src/routeTree.gen.ts` 收录新的路由文件。 ## 增加服务端行为 需要提供 HTTP 接口或响应已支付订单的插件,再加一个用 `defineServerPlugin` 定义的 `plugin.server.ts`,向 `api.routes` 或 `billing.fulfilment` 贡献,并同时登记到 `src/plugins/installed.server.ts`。这个文件也会被 agent 服务 import,所以从它能到达的代码都不能 import React、图标或 `@/` 别名。 插件的 server function 在鉴权之后调用 `src/server/plugins/state.ts` 里的 `requirePluginEnabled("notes")`,插件停用时拒绝调用。贡献给 `api.routes` 的接口不需要这样做,因为插件停用时宿主返回 `404`。支付插槽见[交付已支付订单](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md)。 ## 验证 1. `pnpm typecheck` 通过。插槽名写错或贡献缺字段都是类型错误。 2. `pnpm validate:plugins` 通过。它检查注册表能构建、导航项指向存在的路由文件、条目落在插件 `routes` 的前缀之下,以及页面的 `active` 值是某个已贡献的 `app.nav` id。 3. 打开 `/app`:侧边栏里有 **Notes** 入口,卡片在账户概览上方。再打开 `/app/notes`。 4. 打开 **设置 → 插件**(`/admin/plugins`)。`notes` 这一行列出了它的工作区入口和路由。把它停用。 5. 刷新 `/app`:入口和卡片都消失,`/app/notes` 显示未找到页面。重新启用后两者恢复。 6. `pnpm validate:all` 与之前记录的结果相比没有新增失败。 ## 故障排查 ### 应用启动失败,报 `duplicate_slot_key` 另一个插件已经向该插槽贡献了相同的 key:`id` 相同的 `app.nav` 条目,或 `to` 相同的 `admin.nav` 条目。错误信息里有插槽、key 和两个插件的名字。 ### 应用启动失败,报 `duplicate_plugin_route` 两份清单在 `routes` 里声明了同一个前缀。一个前缀只能有一个所有者,把新路由放到自己的前缀下。 ### `pnpm validate:plugins` 报 `module-entries-sit-in-their-own-routes` 插件的导航项指向了清单前缀之外的路径。把前缀加进 `routes`;否则停用插件只会隐藏入口,页面仍然能访问。 ## 下一步 - [客户端插槽与服务端插槽](https://kernlift.dev/zh/docs/core/plugins.md) 插槽是什么,每个插槽在哪里声明。 - [新增页面](https://kernlift.dev/zh/docs/customize/new-page.md) 页面本身的文案、守卫和 server function。 - [构建模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md) 通过 registry 分发这个功能。 - [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md) 为工作台贡献一项 agent 能力。 --- # 插件 > 插件内核的工作方式:什么是插件,它向哪些客户端插槽和服务端插槽贡献内容,插件如何在构建期安装、在运行时启用和停用。 Source: https://kernlift.dev/zh/docs/core/plugins 管理后台和用户工作区的代码不写死任何功能。它们读取**插槽**(侧边栏、仪表盘、账单页头部、agent 工作台),每个已安装的**插件**向这些插槽贡献条目。基础版本身是一个插件,每个模块是一个插件,你为自己产品写的功能也可以是一个插件。编写方法见[编写后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md)。 ## 什么是插件 一个插件由一份清单和若干插槽贡献组成,放在 `src/plugins//` 目录里。 | 文件 | 内容 | 由谁加载 | | ------------------ | --------------------------------------------- | -------------------- | | `manifest.ts` | 纯数据:`id`、`version`、`kind`、`requires`、`routes` | 任何地方 | | `plugin.ts` | 浏览器安全的贡献:带图标的导航、页面区块、工作台扩展 | Web 应用 | | `plugin.server.ts` | 只在服务端的贡献:API 路由、支付履约、agent 宿主扩展。可选 | Web 应用的服务端和 agent 服务 | 清单的 `routes` 列出插件拥有的路径前缀(不含语言前缀),例如 `/admin/cms`、`/app/image`。`requires` 列出必须已安装并启用的其他插件 id。 | 类型 | 含义 | 能否停用 | | --------- | --------------------------------- | ---- | | `builtin` | 基础版:每个安装都有的后台 | 不能 | | `module` | 随仓库提供的模块,带标记区段和 `module.json` | 能 | | `agent` | 一项 agent 能力,依赖 `agent-starter` | 能 | | `local` | 属于你自己的项目。没有标记区段,也没有 `module.json` | 能 | ## 构建期安装,运行时启用 插件不会在应用运行时下载或加载。模板要部署到 Cloudflare Workers,那里不能加载远程代码。文件路由在构建期就确定。插件还必须和宿主一起通过类型检查和校验器。因此一个插件有两个彼此独立的状态。 **已安装**是构建期的事实。`src/plugins/installed.ts` 是一份显式的列表,一个部署运行哪些插件以它为准。模块的条目写在这份列表里它自己的 `// @module:` 区段内。`local` 插件由你手工加入,写在任何区段之外。`src/plugins/installed.server.ts` 是对应的服务端列表。agent 服务会 import 它,所以从它能到达的代码都不能 import React、图标或 `@/` 别名。 **已启用**是运行时的事实,保存在后台配置表的 `plugins.state.v1` 里。这里只记录被运营人员停用的 id,所以之后新装的插件默认启用。启用集合这样计算: 1. `builtin` 插件始终启用。 2. 停用列表里的插件停用。 3. 依赖了已停用插件的插件也停用,按依赖关系传递。 持有 `config.write` 的管理员在 **设置 → 插件**(`/admin/plugins`)里修改。停用一个仍被已启用插件依赖的插件会被拒绝,并列出依赖它的插件。启用一个依赖尚未启用的插件也会被拒绝,并指出缺少的依赖。 ## 客户端插槽与服务端插槽 插槽是一个带类型、有名字的列表,由宿主读取,由插件贡献内容。客户端插槽增加界面:`admin.nav` 和 `app.nav` 接收侧边栏条目,`app.dashboard.cards` 接收 `/app` 仪表盘上的卡片。插件通过 `plugin.ts` 里的 `contributes` 向它们贡献内容,后台外壳通过 `usePluginValues(slot)` 读取。服务端插槽增加行为:`api.routes` 在 `/api/plugins//…` 下提供接口,`billing.fulfilment` 交付已支付订单购买的内容。插件通过 `plugin.server.ts` 里的 `contributes` 向它们贡献内容。 每个插槽都声明了单条贡献的结构,以及用哪个字段作为 key。完整列表和每条贡献的类型见 `src/plugins/slots.ts`(客户端)和 `src/plugins/server-slots.ts`(服务端)。agent 插槽只在安装了 `agent-starter` 模板后才存在,见 [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md)。 注册表把已安装的插件合并一次,并在构建注册表时拒绝所有冲突,报以下错误之一: | 错误 | 原因 | | --------------------------- | ------------------ | | `duplicate_plugin` | 两个插件的 id 相同 | | `duplicate_slot_key` | 同一个插槽里两条贡献的 key 相同 | | `duplicate_plugin_route` | 两个插件声明了同一个路由前缀 | | `missing_plugin_dependency` | 插件依赖的插件没有安装 | | `plugin_dependency_cycle` | 插件之间循环依赖 | | `unknown_plugin_slot` | 贡献指向一个没有声明的插槽 | ## 停用插件之后 | 位置 | 效果 | | ---------------------- | -------------------------------------------------------------- | | 导航和页面区块 | 外壳只读取已启用插件的贡献,它的入口和卡片随之消失。 | | `/admin` 和 `/app` 下的页面 | 两个后台布局在 `beforeLoad` 里调用路由守卫;属于已停用插件的路径返回未找到。路径归属按最长匹配的路由前缀判断。 | | `/api/plugins//…` | 通配路由返回 `404`。 | | Server function | 模块自己的函数在鉴权之后调用 `requirePluginEnabled()`,拒绝调用。 | | 支付 | 只调用已启用插件的履约器。 | | Agent | 已停用插件的场景、路由和技能被跳过,在它的场景上创建运行会被拒绝,错误码 `plugin_disabled`。 | 路由守卫只在两个后台布局里执行。清单里的公开路由前缀(例如 `/blog`)只登记归属,不在那里拦截。 停用插件不会卸载它。文件、数据表、数据和迁移都保留。 ## 部署能力 有些入口取决于部署具备的能力。`app.nav` 的条目可以带 `requires: "agent"`。agent 服务不可用时,即使插件已启用,这个入口也会隐藏。后台布局在服务端同时解析已启用的 id 和部署能力,一起传给外壳。见 [Agent 运行机制](https://kernlift.dev/zh/docs/extensions/agent.md)。 ## 模块与插件的关系 模块是一项边界记录在 `modules//module.json` 里的功能:文件、共享文件区段、迁移和依赖包。插件则是这个模块接入后台的方式。两者必须在三个地方保持一致,由 `pnpm validate:plugins` 检查: * 插件 id 等于模块 key,版本号一致。 * 模块的 `files` 包含 `src/plugins//**`。 * 模块的 `fragments` 包含 `src/plugins/installed.ts`,它的标记区段就在那里。 Schema、权限种子和文案词典不是插件贡献。它们仍在共享文件的 `// @module:` 区段里。见[开发一个模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md)。 ## 相关文件 - 内核/ - src/plugins/kernel/types.ts - src/plugins/kernel/registry.ts - src/plugins/kernel/state.ts - 插槽与安装列表/ - src/plugins/slots.ts - src/plugins/server-slots.ts - src/plugins/installed.ts - src/plugins/installed.server.ts - src/plugins/registry.ts - src/plugins/registry.server.ts - 运行时状态与守卫/ - src/plugins/route-guard.ts - src/plugins/context.tsx - src/server/plugins/state.ts - src/server/plugins/server-state.ts - src/server/plugins/api-dispatch.ts - src/routes/{-$locale}/admin/plugins.tsx - 示例/ - src/plugins/foundation/plugin.ts - src/plugins/cms/plugin.ts - src/plugins/image-agent/plugin.server.ts - 校验/ - scripts/validate/plugins.ts ## 下一步 - [编写后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md) 加一个自己的导航项、页面和仪表盘卡片。 - [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md) 为唯一的工作台增加一项 agent 能力。 - [开发一个模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md) 把你自己的功能做成带清单的模块。 --- # 模板与派生产品 > 仓库里的模块和模板产品有什么不同,业务模板是什么,以及如何在底座上只加一个插件,做出自己的产品。 Source: https://kernlift.dev/zh/docs/core/plugins/templates 这个项目里的一切都建立在同一个底座上。**模块**给它加一个功能,**模板产品**给它加一整种产品形态和自己的运行时,**派生产品**是你在底座上加一个自己的插件做出的产品。它们的区别决定了要部署什么,以及你自己的代码放在哪里。 ## 模块还是模板产品 两者都已经在仓库里,各自由 `modules//module.json` 里的清单描述。`kind` 字段说明它是哪一种。 | | 模块 | 模板产品 | | ----------------------- | -------------------------------------------- | -------------------------------------- | | `module.json` 里的 `kind` | `module` | `template` | | 增加什么 | 一个功能:页面、服务端代码、自己的表、文案和一个校验器 | 一种产品形态:工作区包、第二个进程、一个运行时,以及这个运行时需要的表和设置 | | 仓库里的例子 | `cms`、`newsletter`、`affiliate`、`image-agent` | `agent-starter` | | 是否改变部署方式 | 否 | 是:要在 Web 应用旁边多运行一个服务 | | 是否有别的东西建立在它之上 | 很少 | 是:agent 能力插件都依赖它 | `agent-starter` 是唯一的模板产品。它的清单里有功能模块不包含的内容:`packages/agent-*` 工作区包和 `apps/agent-service`,脚本 `dev:agent`、`build:agent-service` 和 `agent:publish-skills`,包含运行、线程、技能和工作区数据表的迁移 `0016_agent_starter`,以及六个校验器。相比之下,`image-agent` 是一个 `requires: ["agent-starter"]` 的模块:一个插件目录、两条路由、一个设置 key,没有数据表。 模板产品是其他条目的基础,模块之上通常不再建立别的东西。两者的清单见[底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md)。 ## 业务模板就是做好的派生产品 与底座一起出售的业务模板(`image-studio`、`video-studio`、`image-agent`、`video-agent`)是已经做好的派生产品。每个都是独立的私有仓库:底座加上某一个产品的插件、页面和套餐。你克隆的是它而不是底座,之后用同样的方式同步更新。见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。底座仓库里的 `image-agent` 插件是随仓库提供的 Agent 能力示例;同名的业务模板是另一个独立的仓库。 本页余下的部分说明这样一个产品是怎么搭起来的,你做自己的产品也是同样的做法。 ## 派生产品 = 底座 + 一个插件 在模板上做产品(比如一个生成图片或视频的站点)不需要另起一套后台。登录、套餐与结账、积分账本、服务商配置、文件存储、管理后台和校验器,底座都已经有了。你的产品只需要增加一个向后台插槽贡献页面和入口的插件,加上自己的落地页和套餐。 有两种做法,区别在于产品是否需要 agent。 | | 不带 agent | 带 agent | | ----- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | 由什么生成 | 渠道任务:`POST /api//generate`,通过 `GET /api/status` 读取结果 | 一次 agent 运行:在同样的场景上调用 `model.generate`,并发布产物 | | 你的插件 | 一个 `local` 后台插件:一个 `app.nav` 入口,一个在 `image-creation` 或 `video-creation` 上发起任务的页面,可选一张仪表盘卡片 | 建立在 `agent-starter` 之上的 `agent` 插件:一个场景、一个 Skill、输入框控件,可选自己的卡片和面板 | | 用到的插槽 | `app.nav`、`app.dashboard.cards`,可选 `api.routes` 和 `billing.fulfilment` | `agent.host`、`agent.workbench`,可选 `api.routes` | | 交互方式 | 一个表单和一个结果 | 一段对话:读者描述、修改,结果直接出现在消息里 | | 数据库 | 任何受支持的数据库,包括 Cloudflare D1 | Postgres,或 Node 上的 SQLite | | 部署 | 只有 Web 应用 | Web 应用和 agent 服务 | 两种做法共用同一套服务商接线。图片或视频服务商只在 `/admin/config/ai` 配置一次。无论哪条路径发起,任务都以积分计价,结果都进入用户的文件。见[跑通图片和视频生成](https://kernlift.dev/zh/docs/extensions/ai/media-generation.md)。 ### 不带 agent 没有 agent 服务时,底座本身就是完整的 Web 应用。`/app/ai` 已经能发起和跟踪渠道任务,所以一个生成类产品就是在同样的 server function 和 API 之上写一个自己的页面,并登记为 `local` 插件。外壳的其他部分都不用改,这个插件还可以在 **设置 → 插件** 里停用。见[编写后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md)。 ### 带 agent 先把 `agent-starter` 的 agent 服务跑起来,再加一个能力插件。图片 Agent 是仓库自带的例子:它声明 `agent.image` 场景,自带 Image Studio Skill,在输入框旁加上画幅选择,并渲染 `image` 产物。视频能力的做法相同,而且不需要自己的产物类型,因为 `video` 是核心类型,对话里已经可以直接播放。宿主代码不按名称引用任何插件,所以再加一项能力只是在已安装列表里增加一条,不需要改工作台。见 [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md)。 Agent 在运行时也是可选的,所以一套代码可以同时服务两种部署。没有部署 agent 服务的地方,带 `requires: "agent"` 的入口被隐藏,普通的渠道页面照常可用。 ## 仍然由底座负责的事 无论走哪条路,下面这些都不需要为每个产品重做: * **计费。** 套餐、结账和积分账本。需要为已支付订单交付东西的插件,向 `billing.fulfilment` 贡献一个履约器,不修改订单。 * **配置。** 服务商凭据放在 `/admin/config/*`,不放在环境变量里。 * **访问控制。** 受保护的路由树在布局层守卫,插件的新页面默认就是受保护的。 * **校验。** 插件自带校验器,其余由 `pnpm validate:all` 覆盖。 ## 相关文件 - 清单/ - modules/kernlift/module.json - modules/agent-starter/module.json - modules/image-agent/module.json - 插件加在哪里/ - src/plugins/installed.ts - src/plugins/installed.server.ts - src/plugins/slots.ts - src/plugins/server-slots.ts - 自带的能力插件/ - src/plugins/image-agent/plugin.ts - src/plugins/image-agent/plugin.server.ts - agent 在不在/ - src/server/agent-host/availability.ts ## 下一步 - [插件](https://kernlift.dev/zh/docs/core/plugins.md) 派生产品接入的内核。 - [编写后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md) 不带 agent 的做法。 - [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md) 带 agent 的做法。 - [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) 带来整套 agent 的模板产品。 - [底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md) 底座、它的模块,以及各自增加什么。 --- # 项目结构 > 熟悉 Kernlift 代码仓库,知道每一类改动应该放在哪里。 Source: https://kernlift.dev/zh/docs/core/project-structure 一个 Kernlift 项目就是一个仓库:应用本身、迁移、校验器、agent 技能、可选的 agent 服务,以及把它打包成模块的工具。本页说明各部分的位置。这样布局的原因见[架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md)。 ## 准备工作 * 一个按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)克隆并安装好的项目。 ## 顶层目录 ```text title="my-saas/" src/ Web 应用(路由、组件、插件、服务端代码、文案) packages/ workspace 包:beui(设计系统)、kernlift-skills,以及 agent-* 系列包 apps/agent-service/ 可选的 agent 服务,独立进程(agent-starter 模块) drizzle/migrations/ 手工维护的迁移,每种方言一个目录:sqlite/ 和 postgres/ scripts/ db/、jobs/、validate/、registry/、assets/、skills/,以及 Node 与 Worker 冒烟测试 modules/ 每个模块一个 module.json,另有底座清单 skills/ 开发项目时使用的 agent 技能(quick-start、new-page、deploy 等) agent-skills/ agent 自身运行的技能(agent-starter 模块) tools/kernlift/ kernlift CLI 包 openspec/ 规格与变更提案(openspec/changes/) docs/ 维护者笔记与设计参考 public/ 图标、分享图和占位素材 deploy.config.json 这份构建面向的平台、数据库以及是否带 agent wrangler.jsonc Cloudflare Worker 入口与绑定(仅 Cloudflare 项目) Dockerfile 其他平台运行的 Node 镜像 .env.example 源代码读取的全部环境变量 ``` 项目只带自己所选平台的部署文件:Cloudflare 是 `wrangler.jsonc`,Fly.io 是 `fly.toml`,Railway 是 `.railway/railway.ts`,Docker 是 `compose.yaml`。`kernlift deploy-target ` 负责在它们之间切换,并重写 `deploy.config.json`。你正在阅读的产品文档由商店项目发布,不在你的仓库里。 ## `src/` 内部 ```text title="src/" routes/{-$locale}/ 页面;可选的语言段用于提供 /zh 路由 app.tsx, app/ 登录后的工作台(/app/*),在布局处统一守卫 admin.tsx, admin/ 管理后台(/admin/*),在布局处统一守卫 routes/api/ API 处理器,例如 /api/billing/*、/api/chat 和 /api/agent/* components/ 按能力分组的 UI motion/ 页面导入的 beUI 组件 admin/ 后台页面模式(记录列表、指标、面板、配置表单) marketing/ 公开站:外壳、page-shell 原语、落地页、定价页 layout/ AppShell 与工作台侧边栏 plugins/ 后台插件:底座插件和每个模块各一个,以及它们填充的插槽 (admin.nav、app.nav、工作台首页卡片、账单页操作) i18n/ locales/{en,zh}/messages.ts,以及按功能拆分的文案文件 config/site.ts 站点名称、规范 URL、描述和社交分享图 styles/app.css 挂在 :root 上、全站共用的产品令牌 server/ auth/ 唯一读取会话的代码:身份上下文、守卫、API 边界 functions/ 供路由和组件调用的服务端函数 services/ 跨能力的编排 db/repositories/ 所有数据库访问 db/schema/ sqlite.ts 与 postgres.ts,两种方言下相同的表 jobs/ 定时任务:runScheduledJobs() 和进程内循环 agent-host/ agent 在 Web 一侧的部分:可用性判断、传输、积分、存储 plugins/ 插件状态,以及插件贡献的 API 路由 platform/ 运行时能力:缓存后端、存储驱动、绑定、部署信息 server-entry.ts wrangler.jsonc 中指定的 Worker 入口 server-entry.node.ts Node 构建(pnpm build:node)的服务端入口 ``` 服务端每一层只调用下一层,因此业务代码从不接触 SQL 方言。Web 应用不依赖 `apps/agent-service` 运行。没有部署它时,agent 入口会提示服务未部署。 ## 改动放在哪里 | 你想要 | 修改 | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 重命名产品 | `src/config/site.ts` 和 `public/` 下的素材;见[换成自己的品牌](https://kernlift.dev/zh/docs/customize/branding.md) | | 替换首页 | `src/components/marketing/example-landing.tsx`;见[替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md) | | 修改配色或搭建页面 | `src/styles/app.css` 和 `src/components/motion`;见[使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md) | | 修改或新增文案 | 同时修改 `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts`;见[新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md) | | 新增后台或工作台页面 | 在 `src/routes/{-$locale}/admin/` 或 `app/` 下新增路由,并在 `src/plugins/foundation/plugin.ts` 中加导航入口;见[新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md) | | 接入服务商 | 不需要改代码:使用 `/admin/config/*`,见[管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) | | 新增数据库表 | 同时修改两个 schema 文件,再为每种方言各写一条迁移 | | 新增周期性后台任务 | 在 `src/server/jobs/scheduled.ts` 中加一个任务;见[后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md) | | 新增功能检查 | 在 `scripts/validate/` 下新增校验器,并接入 `pnpm validate:all` | | 新增模块 | 按 `new-module` 技能操作;见[构建模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md) | **服务商设置不要放进环境变量** 环境变量只用于启动与基础设施。功能代码不读取 `process.env`,服务商凭据在管理后台配置。 ## 验证 按下面的顺序运行每次改动完成前都要跑的检查: 1. `pnpm typecheck`。它需要由 `pnpm cf-typegen` 生成的 `worker-configuration.d.ts`,以及最新的 `src/routeTree.gen.ts`;路由有变化时,`pnpm dev` 或 `pnpm build` 会重写后者。 2. `pnpm check`。它会报告样式表中一些既有问题。不要为了消除它们在整个仓库上运行 `biome check --write --unsafe`。 3. `pnpm validate:all`。 ## 下一步 - [架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md) 代码为什么这样分层。 - [安装后的第一步](https://kernlift.dev/zh/docs/customize/first-steps.md) 完成初始化清单,并决定先定制哪一部分。 - [排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md) 项目跑不起来时的现象与修复。 - [校验器与发布门禁](https://kernlift.dev/zh/docs/core/validators.md) `pnpm validate:all` 证明了什么。 --- # 校验器与发布门禁 > 为什么每项能力都带有断言行为与接线的可执行检查,以及发布门禁如何决定哪些检查必须通过。 Source: https://kernlift.dev/zh/docs/core/validators Kernlift 的每项能力都带有一个校验器,即检查功能可用且可访问的可执行脚本。发布门禁决定其中哪些检查必须通过。完整脚本列表见[校验器](https://kernlift.dev/zh/docs/reference/validators.md)。 ## 每项能力一个校验器 `scripts/validate/*.ts` 中每项能力一个检查,每个都以 `validate:*` 脚本形式出现在 `package.json` 中,并串入 `pnpm validate:all`。校验器存在并通过之前,改动不算完成。模块也自带校验器,在其清单中列出。 校验器会报告它运行的每项检查,大多以 JSON 报告形式列出各项检查及其证据,任何检查失败时以非零状态退出。 ## 断言行为与接线,而不是文件存在 只断言文件存在的检查,在文件没有被任何路由引用时照样通过。这个仓库不止一次交付过这种 bug,所以校验器断言行为与接线。常见形态有: | 形态 | 证明什么 | | -------------------------------------- | ---------------------- | | 用 `validate-` 前缀的夹具在真实数据库上运行仓储或服务,然后清理 | 逻辑在真实表上可用,包括失败路径 | | 用真实营销快照在两种语言下渲染页面 | 页面在中英文下展示真实数据,没有写死的价格 | | 读取路由、壳与字典 | 功能可访问:已路由、已守卫、在导航中且已翻译 | 校验器从不伪造服务商。需要真实凭据的检查放在外部验证中。 ## 发布门禁 目前并非每个校验器都能通过。`pnpm validate:all` 运行整条链并在第一个失败处停止,在已知有检查失败时不能作为门禁。CI 运行 `pnpm validate:gate`: | 分组 | 门禁如何处理 | | --------------------------------------------------------- | ----------------------------------- | | 未列为已知失败的校验器 | 必须通过;任何失败都算回归 | | `scripts/validate/known-failures.json` 中的校验器 | 同样运行;开始通过的必须从列表中移除 | | `validate:all`、`validate:gate`、`validate:storage-drivers` | 门禁不运行。存储驱动检查会向存储桶写入真实对象,所以只在有意为之时运行 | 每个已知失败都写明了原因和修复所需的工作。这个列表只能缩短。开始失败的校验器必须修复,不能加进列表。做改动时,记录改动前后的通过与失败集合,确认没有把通过的检查变红。 ## 外部验证 本地校验器检查状态机和未配置路径。针对真实服务商的检查需要沙箱或生产凭据,通过 `pnpm validate:external` 单独运行。没有凭据时这些检查报告为跳过,`EXTERNAL_VALIDATE_STRICT=true` 会让跳过的检查失败。见[运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 重要的校验器 | 脚本 | 证明 | | ----------------------------- | --------------------------------------- | | `validate:auth-boundary` | 每个 API 路由要么有守卫,要么显式公开并说明理由 | | `validate:migrations` | 两条迁移链都能重放并与 schema 一致 | | `validate:billing-fulfilment` | 计费对每个已启用的履约插件只通知一次,失败会被记录并由定时任务重试 | | `validate:optional-agent` | 不部署 Agent 服务时 Web 应用完整可用,定时任务凭一把锁运行 | | `validate:plugins` | 插件注册表拒绝冲突,停用会级联,每个贡献的入口都指向真实的路由文件 | | `validate:store-boundary` | 销售 Kernlift 的那部分没有回到模板里 | | `validate:products` | 服务端定价、授权签发与撤销、全量授权展开 | | `validate:registry` | 底座加模块能重现仓库;底座可以单独通过类型检查 | | `validate:init-cli` | 令牌从不出现在 argv 中、拒绝未授权项、升级保留本地修改 | | `validate:skills` | 技能只引用真实存在的脚本、路径、路由和命令 | | `validate:module-catalog` | 模块页面基于真实快照渲染,没有价格字面量 | | `validate:docs` | 双语导航与链接可解析;模块、Agent API、数据表和环境变量参考与源码一致 | | `validate:landing-blocks` | 首页上的数字是从仓库实际统计出来的 | `validate:products`、`validate:module-catalog`、`validate:docs` 和 `validate:landing-blocks` 属于商店项目,由模板创建的项目里没有它们。 ## 相关文件 - 校验本体/ - scripts/validate - scripts/validate/gate.ts - scripts/validate/known-failures.json - scripts/validate/lint-budget.json - 它们读什么/ - scripts/validate/change-path.ts - scripts/validate/render.ts - scripts/validate/fixtures.ts `change-path.ts` 能同时解析进行中和已归档的 OpenSpec 变更,所以没有任何校验器写死变更目录。`render.ts` 在服务端渲染页面,让检查可以对渲染出的标记做断言。`fixtures.ts` 创建并清理检查需要的 `validate` 前缀数据行,所以检查不依赖种子数据。 ## 下一步 - [校验器参考](https://kernlift.dev/zh/docs/reference/validators.md) 每条检查断言什么,如何单独运行。 - [架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md) 这些检查保证的边界。 - [项目结构](https://kernlift.dev/zh/docs/core/project-structure.md) 新检查放在哪里。 - [升级分叉](https://kernlift.dev/zh/docs/guide/upgrading.md) 改动前后各运行一次门禁,确认原本通过的检查仍然通过。 --- # 换成自己的品牌 > 把 Kernlift 的名称、域名、描述、图标和分享图换成你自己的,并决定用户登录后落在哪个页面。 Source: https://kernlift.dev/zh/docs/customize/branding 新建的项目在页头、浏览器标签、邮件和分享卡片里仍然写着 Kernlift。站点身份在 `src/config/site.ts` 一个文件里设置。本指南还说明这个文件不涉及的几处:消息字典里的页面标题、生成的图标素材,以及发件人名称。 ## 准备工作 * 一个能用 `pnpm dev` 在本地运行的项目。见[快速开始](https://kernlift.dev/zh/docs/quick-start.md)。 * 产品名称、一句话描述和生产域名。 * 可选:自己的 SVG 标志,以及一张 1200×630 的分享图。 ## 设置站点身份 ### 编辑 `src/config/site.ts` ```ts title="src/config/site.ts" export const siteConfig = { name: "Acme", shortName: "Acme", url: normalizeOrigin(process.env.SITE_URL ?? "https://acme.com"), description: "One sentence that says what Acme does.", ogImage: "/og-default.png", locale: "en", themeColor: "#3859D6", backgroundColor: "#F6F5F1", twitter: { site: "", card: "summary_large_image" }, } as const; ``` | 字段 | 用在哪里 | | ------------------------------ | ----------------------------------------------------------------- | | `name` | 公开站页头与页脚、登录注册页、工作台侧边栏、系统页、邮件外壳、`og:site_name`、订阅源标题和 web manifest | | `shortName` | `/manifest.webmanifest` 中的 `short_name` | | `url` | 规范链接、`og:url`、站点地图、`robots.txt`、订阅源,以及邮件里的绝对链接 | | `description` | 兜底的 meta description、订阅源和 manifest | | `ogImage` | 兜底的 `og:image` 与 `twitter:image`,相对于 `url` | | `themeColor`、`backgroundColor` | `theme-color` meta 标签和 manifest | | `twitter.site` | `twitter:site`;留空则不输出该标签 | 刚克隆的仓库里,`name`、`shortName` 和 `url` 还是模板自己的,三项都要改。 ### 设置生产域名 `SITE_URL` 会在运行时覆盖 `siteConfig.url`,因此同一份构建既能服务预览域名,也能服务生产域名。在应用运行的环境里设置它: ```bash title=".env" SITE_URL=https://acme.com ``` 结尾不需要斜杠,配置会自动去掉。OAuth 回调和认证邮件里的链接使用 `/admin/config/auth` 里的 **基础 URL**。首次启动时它用站点地址初始化,域名变化时在那里修改。见[环境变量](https://kernlift.dev/zh/docs/reference/env.md)。 ### 替换两份字典里的默认标题 全站默认标题和首页标题属于文案,所以放在消息字典里,而不在 `site.ts`。在 `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` 中修改相同的键: | 键 | 出现位置 | | --------------------------------------------- | -------------------- | | `seo.default.title`、`seo.default.description` | 根文档输出的兜底标题和描述 | | `seo.home.title`、`seo.home.description` | 首页 | | `content.blogCopy` | 博客列表页的导语(安装 CMS 模块时) | 文案的组织方式见[新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md)。 ## 替换图标和分享图 ### 选择生成素材还是手工素材 项目自带的占位素材由脚本绘制。你可以保留生成器,把名称和配色换成自己的,也可以直接放入自己的文件。 要重新生成,先修改 `scripts/assets/generate-site-assets.ts` 顶部的常量(`siteName`、`tagline` 和 `palette`),然后运行: ```bash pnpm assets:generate ``` 它会重写 `public/` 下的 `favicon.svg`、`favicon.ico`、`apple-touch-icon.png`、`icon-192.png`、`icon-512.png` 和 `og-default.png`,以及 `public/placeholder/` 下的图片。 ### 或者手工替换文件 保持以下文件名和尺寸不变,因为根文档、manifest 和各个外壳都按路径引用它们: | 文件 | 尺寸 | 用途 | | ------------------------------------------- | --------------- | ------------------------- | | `public/favicon.svg` | 矢量 | 浏览器标签,以及公开站页头、登录页和系统页里的标志 | | `public/favicon.ico` | 32×32 | 不支持 SVG 图标的浏览器 | | `public/apple-touch-icon.png` | 180×180 | iOS 主屏幕 | | `public/icon-192.png`、`public/icon-512.png` | 192×192、512×512 | web manifest | | `public/og-default.png` | 1200×630 | 默认分享图 | 之后再运行 `pnpm assets:generate` 会覆盖这些文件。 ### 让浏览器外框颜色与配色一致 把 `site.ts` 里的 `themeColor` 和 `backgroundColor` 设为你的主色和页面底色。它们是普通的十六进制字符串,不会自动跟随 CSS 令牌。如果你改了 `--primary` 或 `--background`,这里也要一起改。见[使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md)。 ## 检查元数据和站点地图 页面通过 `src/lib/seo.ts` 中的 `buildMeta()` 生成 ``,页面没有提供的字段会回退到站点配置。需要你维护的只有两份清单: 1. 打开 `src/server/services/static-seo.service.ts`,编辑 `publicSeoRoutes`:删掉已经移除的页面,加上新建的公开页面。`/sitemap.xml` 会把这份清单按每种语言各渲染一遍,并带上 `hreflang` 互链。 2. `robots.txt` 一般不用动,除非你新增了别的私有区域。它由 `src/routes/robots[.]txt.ts` 输出,已经禁止抓取 `/admin`、`/app` 和 `/api`,并指向当前配置域名下的站点地图。 不要新增 `public/sitemap.xml`。它会遮住路由,`pnpm validate:site-metadata` 也会失败。 ## 设置发件人名称 邮件外壳里的产品名取自 `site.ts`,但发件人是一项存储在数据库里的设置。打开**设置 → 邮件配置**(`/admin/config/email`),把发件人地址改成你自己的名称和已验证的域名。见[发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md)。 ## 决定登录后落在哪里 从受保护页面跳去登录的访客,会通过 `redirectTo` 参数回到原页面。没有这个参数时,落在 `src/config/site.ts` 的 `signedInHome`,默认是 `/app/profile`。邮箱登录、注册、社交登录以及邮箱验证成功后的按钮都读取它。 ```ts signedInHome: "/app", ``` 填写 `/app` 下不带语言前缀的站内相对路径。语言前缀会按访客的语言自动加上,登录页只接受 `/auth` 之外的相对路径。 ## 验证 ```bash pnpm validate:site-metadata pnpm validate:example-landing pnpm typecheck ``` 然后启动 `pnpm dev` 检查: * 页头、浏览器标签和 `/auth/sign-in` 显示你的名称和标志。 * `/manifest.webmanifest` 返回你的 `name`、`short_name` 和颜色。 * 设置 `SITE_URL` 后,`/sitemap.xml` 和 `/robots.txt` 使用你的域名。 * 查看 `/` 的页面源码:`og:title`、`og:image` 和规范链接都是你的名称和域名。 * 退出后重新登录:落在你选定的页面。 图标缺失、源码引用了 `public/` 中不存在的图片,或某个页面绕过 `buildMeta()` 自己写规范链接时,`pnpm validate:site-metadata` 会失败。 ## 下一步 - [替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md) 用 page-shell 原语重写示例首页。 - [使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md) 修改所有页面共用的颜色令牌。 - [新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md) 在两种语言的消息字典里编辑文案。 --- # 使用设计系统 > 用 beUI、motion 组件和产品令牌搭建或改造页面,修改主题,并避开校验器会拒绝的导入。 Source: https://kernlift.dev/zh/docs/customize/design-system 项目里的每个页面都使用同一套设计系统:管理后台、工作台、登录与系统页,以及公开站。它分三层:挂在 `:root` 上的令牌、经 `src/components/motion` 转出的 `@workspace/beui` 组件,以及少量页面级模式。所有页面默认使用设计系统,不需要包裹层,也不需要设置属性。 ## 准备工作 * 一个能用 `pnpm dev` 运行的项目。 * 确定要搭建或改造的页面,以及它属于后台/工作台(`/admin`、`/app`)还是公开页面。 * 如果是新页面,先读[新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md)或[替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md)。本指南说明两者共用的视觉层。 ## 认识各层 | 层 | 位置 | 用途 | | --------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 令牌 | `src/styles/app.css` 中的 `:root` 和 `:root[data-theme="dark"]` | 颜色、圆角和字体。`bg-background`、`text-muted-foreground`、`border-border` 这类 Tailwind 工具类读取它们 | | beUI 源码 | `packages/beui`(workspace 包 `@workspace/beui`) | 组件本体:按钮、输入框、选择器、标签页、表格、surface、弹窗、浮层、表单布局 | | motion 组件 | `src/components/motion` | 页面实际导入的入口。每个文件为本应用转出或适配一个 beUI 组件(`button`、`input`、`select`、`switch`、`checkbox`、`tabs`、`surface`、`table`、`morphing-modal`、`drawer`、`tooltip`、`toast`、`empty-state`、`status-tag`、`skeleton`、`loader`、`theme-toggle`) | | 后台模式 | `src/components/admin` | 后台页面的整块区域:记录列表、指标行、面板、配置表单、保存状态 | | 公开页原语 | `src/components/marketing/ui/page-shell.tsx` | 公开页面的区块、标题和面板 | | 外壳 | `src/components/layout` | `AppShell`(后台、初始化页)和 `AppConsoleLayout`(工作台):侧边栏、页头,以及页面唯一的 `
` | ## 搭建一个页面 ### 选定外框 后台页面渲染在 `AppShell` 里,工作台页面渲染在 `AppConsoleLayout` 里,公开页面渲染在 `PublicMarketingShell` 里。`
` 元素由外壳提供。页面内部使用 `
` 和 `
`,不要再写第二个 `
`。 ### 先组合模式,再写标记 后台页面从 `src/components/admin` 的模式开始: | 模式 | 导入路径 | 提供什么 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------- | | `AdminRecords` | `@/components/admin/admin-records` | 由 `columns`、`rows` 和 `rowKey` 生成的可搜索、可分页记录列表;桌面端是表格,手机上是带标签的记录 | | `AdminMetrics` | `@/components/admin/admin-metrics` | 由 `items`(`label`、`value`、可选 `detail`)生成的一行指标 | | `AdminPanel`、`AdminFacts` | `@/components/admin/admin-detail` | 带标题和可选 `actions` 的面板,以及详情页用的标签/值网格 | | `ConfigShell`、`ConfigPanel`、`ConfigPanelGrid`、`ConfigField`、`ConfigFormFields`、`ConfigSelect`、`ConfigSwitch`、`ConfigTextarea`、`ConfigMessage`、`ConfigDetailsTable` | `@/components/admin/config-layout` | 所有 `/admin/config/*` 表单使用的布局 | | `useAdminSave`、`AdminSaveFeedback` | `@/components/admin/admin-save` | 感知权限的保存状态:`allowed`、`pending`、`result`、`save()`,以及保存成功或失败的提示 | | `AdminSectionWorkspace` | `@/components/admin/admin-section-workspace` | 一个带标题、页头 `actions` 和子页面链接(`tabs`)的 `AppShell` 页面 | | `adminRouteFeedback` | `@/components/admin/admin-route-feedback` | 展开到后台路由上的加载中与出错组件 | `useAdminSave("config.write")` 从布局快照中读取当前用户的权限。`allowed` 为 false 时禁用表单并显示只读提示。服务端函数仍然会检查权限。 ### 用 motion 组件填充 控件从 `src/components/motion` 导入,表单布局从 beUI 包导入: ```tsx import { FieldLegend, FieldSet } from "@workspace/beui/form-layout"; import { Button } from "@/components/motion/button"; import { Input } from "@/components/motion/input"; import { Surface, SurfaceContent } from "@/components/motion/surface"; ``` `Button` 和 `ButtonLink` 的 `variant` 可取 `"primary" | "secondary" | "ghost" | "outline" | "danger"`。`@workspace/beui` 没有入口导出,按需导入子路径(`@workspace/beui/form-layout`、`@workspace/beui/components/motion/*`);`src/components/motion` 里已有封装时优先用封装。 ### 用基于令牌的工具类写样式 使用能解析到令牌的 Tailwind 工具类:`bg-background`、`bg-card`、`bg-muted`、`text-foreground`、`text-muted-foreground`、`text-primary`、`border-border`、`ring-ring`、`rounded-lg`。不要在页面里写十六进制颜色、`rgb()` 值或内联 `style` 颜色,因为硬编码的颜色不会跟随深色主题。 只有令牌表达不了差异时才用 `dark:` 变体。该变体跟随根元素上的 `data-theme="dark"`。 ## 修改主题 ### 在两个主题里同时修改令牌 打开 `src/styles/app.css`。产品令牌是 `:root` 末尾的那一段(注释以 "beUI: one set of tokens for the whole product" 开头),`:root[data-theme="dark"]` 里有同名的一组: ```css title="src/styles/app.css" :root { --background: #f6f5f1; --foreground: #20231f; --card: #ffffff; --primary: #3859d6; --primary-foreground: #ffffff; --muted: #eeede8; --muted-foreground: #62666e; --accent: #e8edf9; --border: #ddded8; --ring: #3859d6; --radius: 0.625rem; } ``` 每个值都要在两段里一起改。更换品牌色时,同时设置 `--primary`、`--ring` 和 `--brand-accent`,并选一个在它上面仍然清晰的 `--primary-foreground`。`--radius` 控制所有圆角的比例。侧边栏有自己的一组 `--sidebar-*`。 ### 不要动 Tailwind 映射 `@theme inline` 这一段把每个令牌映射成工具类颜色(`--color-primary: var(--primary)`)。只有新增令牌并希望有对应工具类时才需要改它。 ### 字体留在样式表里 字体在 `app.css` 顶部导入(Geist、Geist Mono 和 Noto Sans SC),并写在 `:root` 的 `font-family` 以及 `@theme inline` 的 `--font-sans` 里。换字体时,替换导入语句和这两处名称。 ### 同步校验器和站点配置 `pnpm validate:beui-console` 断言六个核心令牌在两个主题下都是十六进制值,并把页面底色固定为 `#f6f5f1`(浅色)和 `#101114`(深色)。修改 `--background` 时,在同一次改动里更新 `scripts/validate/beui-console.ts` 中的这两个值。然后把 `src/config/site.ts` 里的 `themeColor` 和 `backgroundColor` 改成一致的颜色,见[换成自己的品牌](https://kernlift.dev/zh/docs/customize/branding.md)。 ## 避开校验器会拒绝的写法 | 规则 | 由谁检查 | | ------------------------------------------------------------------------------ | ------------------------------- | | `admin`、`app`、`auth`、`system` 下的任何路由都不能直接或间接导入 `src/components/ui`(shadcn)中的模块 | `pnpm validate:beui-console` | | 每个后台和工作台页面都渲染在 `AppShell` 或 `AppConsoleLayout` 里 | `pnpm validate:beui-console` | | 后台和工作台页面及其组件不再自带 `
` | `pnpm validate:beui-console` | | `app.css` 不在级联层之外声明裸元素规则(`a`、`button`、`h1`、`table` 等) | `pnpm validate:beui-console` | | 令牌不限定在某个界面属性之下 | `pnpm validate:beui-console` | | 落地页和定价页不硬编码颜色、不用内联样式、不用 `ds-`/`mk-` 类名前缀 | `pnpm validate:example-landing` | | 新文件不带 `!important` | `pnpm check` | `src/styles/app.css` 带有历史遗留的 `!important` 和选择器优先级债务,`biome.json` 只豁免了这一个文件。不要扩大豁免范围,也不要在整个仓库上运行 `biome check --write --unsafe`。这条命令会删掉样式表里的 `!important`,并改写 React hook 的依赖数组。 页面也不使用自己的类名前缀。如果页面来自设计工具,用上面的组件和工具类重新实现,不要粘贴它生成的类名。 ## 新增 beUI 里还没有的组件 1. 先看 `src/components/motion`,大多数控件已经有了。 2. 确实没有时,从 beUI registry 把它安装到 `packages/beui/src/components/`,再在 `src/components/motion` 下加一个转出它的薄文件,写法参考 `src/components/motion/surface.tsx`。编码 agent 可以通过 beUI MCP 服务(`https://mcp.beui.dev/mcp`)获取组件。 3. 文字标签由应用的字典提供。需要渲染文字的 beUI 组件从 `BeuiLocaleProvider` 取文案,各布局已经挂载了它。 ## 验证 ```bash pnpm validate:beui-console pnpm validate:example-landing pnpm validate:mobile pnpm check ``` 在两种主题(切换按钮在公开站页头和后台的账户菜单里)、两种语言、手机宽度和桌面宽度下分别打开页面。深色主题下仍是浅色背景的区域用了硬编码颜色。 ## 下一步 - [新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md) 路由、服务端函数、文案、守卫和导航入口。 - [替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md) 公开页原语的实际用法。 - [架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md) 设计系统在仓库里的位置。 - [校验器](https://kernlift.dev/zh/docs/reference/validators.md) 每项检查及其断言。 --- # 安装后的第一步 > 查看初始化清单、接入邮件,然后决定接下来打开哪一篇定制指南。 Source: https://kernlift.dev/zh/docs/customize/first-steps 项目已经运行,你也以管理员身份登录了。本页完成用户注册前需要的配置:查看初始化清单、接入邮件,然后开始把模板改成你自己的产品。 ## 准备工作 * 一个按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)运行起来的项目。 * 已用管理员账号在 `/auth/sign-in` 登录。 * 一个邮件服务商的凭据:Resend、Cloudflare Email 或阿里云邮件推送。 ## 查看初始化清单 ### 打开 `/setup` 页面读取实时配置,所以显示的是这套部署当前能做什么。每一项显示**已就绪**或**未就绪**,点击**去配置**会打开修复该项的页面。 ### 检查必需项 有四项是必需的。其余标记为**可选**,只在产品需要时再配置。 | 项目 | 必需 | 在哪里配置 | | --------- | -- | ---------------------------------------------------------------------------------------------- | | **会话密钥** | 是 | `.env` 中的 `BETTER_AUTH_SECRET`;在快速开始里已经设置 | | **登录方式** | 是 | **设置 → 认证配置**;邮箱密码登录默认开启 | | **邮件投递** | 是 | **设置 → 邮件配置** | | **定时任务** | 是 | 本地不需要操作:`pnpm dev` 每分钟执行一轮。生产环境取决于部署平台,见[排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md) | | **支付供应商** | 可选 | **设置 → 支付配置** | | **对象存储** | 可选 | **设置 → 存储配置** | | **AI 渠道** | 可选 | **设置 → AI 配置** | | **订阅供应商** | 可选 | 等待名单的**服务商设置**标签页,需要 newsletter 模块 | | **分析供应商** | 可选 | **设置 → 分析配置** | 全新项目通常只缺**邮件投递**。**定时任务**会在服务启动后一分钟内变为**已就绪**。 ## 接入邮件 在启用服务商之前,验证邮件和重置密码邮件都无法发送,所以先做这一步。 ### 打开邮件配置 在 `/setup` 中点击**邮件投递**旁的**去配置**,或进入**设置 → 邮件配置**。 ### 填写一个服务商 填写服务商凭据:Resend 填 **API key**;Cloudflare 填 **Account ID** 和 **API token**;阿里云填 **AccessKey ID**、**AccessKey Secret** 和**发信地址**。再设置邮件使用的**发件人地址**。 ### 设为启用并保存 勾选**设为当前邮件 provider**,点击**保存 provider**。页面提示**邮件 provider 配置已保存。** 各服务商的细节、邮件模板和投递日志见[发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md)。 ## 让项目成为你自己的 项目已经能用,但外观和文字仍然是模板的样子。下面每一项都有单独的指南。按这个顺序做,暂时用不到的可以跳过。 | 你想要 | 打开 | | ------------------------------ | --------------------------------------------- | | 换上自己的名称、域名、图标和分享图 | [换成自己的品牌](https://kernlift.dev/zh/docs/customize/branding.md) | | 替换示例首页,并了解 `/pricing` | [替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md) | | 修改配色和字体,或改造某个页面 | [使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md) | | 重写中英文文案 | [新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md) | | 在 `/app` 或 `/admin` 下新增第一个产品页面 | [新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md) | 见效最快的是第一项:编辑 `src/config/site.ts`,它保存站点名称、规范 URL、描述和社交分享图。 ## 验证 回到 `/setup`。**邮件投递**现在显示**已就绪**,页面显示**必需项已齐备**。在隐私窗口中用另一个邮箱注册:验证邮件会从你设置的**发件人地址**发出。 ## 常见问题 ### `/setup` 跳转到登录页 你还没有登录。用管理员账号在 `/auth/sign-in` 登录,然后重新打开 `/setup`。 ### `/setup` 显示无权限页面 你登录的账号不是管理员。请使用 `pnpm db:bootstrap-super-admin` 创建的账号登录。 ### 保存后邮件投递仍显示未就绪 服务商保存了但没有设为启用,或者缺少必需的凭据。勾选**设为当前邮件 provider**,填写该服务商的全部凭据后再保存一次。 ### 遇到了其他问题 [排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md)列出了会话密钥、生成的类型、迁移、定时任务和 agent 相关的现象与修复方法。 ## 下一步 - [换成自己的品牌](https://kernlift.dev/zh/docs/customize/branding.md) 名称、域名、图标、分享图和元数据。 - [替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md) 重写示例首页。 - [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) 用 Stripe、Creem、PayPal、DodoPayments、微信支付、支付宝或 Waffo 收款。 - [部署项目](https://kernlift.dev/zh/docs/deploy.md) 上线到 Cloudflare、Fly.io、Railway 或 Docker。 --- # 新增与修改文案 > 在英文和中文两种语言下编辑文案、新增支持多语言的路由,并了解可选语言段和 i18n 校验器的工作方式。 Source: https://kernlift.dev/zh/docs/customize/i18n 每个页面都由同一个路由文件提供英文和简体中文两个版本。英文不带前缀(`/pricing`),中文在 `/zh` 下(`/zh/pricing`)。组件里不写文案。文案来自字典,两种语言的键完全一致。 ## 准备工作 * 一个能用 `pnpm dev` 运行的项目。 * 两种语言的文字。只存在于一份字典里的键就是 bug,即使你正在测试的那种语言看起来一切正常。 * 如果要新增整个页面,请按[新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md)或[替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md)操作。本指南说明它们依赖的文案与路由机制。 ## 了解文案放在哪里 | 存放位置 | 文件 | 读取方式 | | ------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | 主字典 | `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` | 通过 `useI18n()` 或 `getDictionary(locale)` 得到的 `t("shell.nav.dashboard")`,或用 `getMessageNamespace(locale, "publicSite")` 取整个命名空间 | | 功能文案文件 | `src/i18n/*.ts`,例如 `admin-plans.ts`、`auth-pages.ts`、`system-pages.ts` | 导出的按语言索引的表:`adminEditingMessages[locale]` | 两者保存的是同一类数据。主字典存放共享文案、公开站文案和所有导航标签。功能文件把某一块后台区域的文案和它的类型放在一起。你正在改的代码用哪一种,就沿用哪一种。 辅助函数都在 `src/i18n/messages.ts` 中: | 函数 | 用途 | | ---------------------------------- | ---------------------------------------------------- | | `locales`、`defaultLocale` | `["en", "zh"]` 和 `"en"` | | `normalizeLocale(value)` | 把路由参数转成 `Locale`;无法识别的值一律当作 `en` | | `localizedPath(path, locale)` | `en` 返回 `/pricing`,`zh` 返回 `/zh/pricing`。所有站内链接都用它生成 | | `switchLocalePath(path, locale)` | 同一页面在另一种语言下的路径,语言切换器使用它 | | `getDictionary(locale)` | 在路由组件之外获得 `{ locale, t }` | | `getMessageNamespace(locale, key)` | 把某个顶层命名空间作为带类型的对象取出,包含数组和格式化函数 | | `localeToIntlTag(locale)` | 供 `Intl` 数字和日期格式化使用的 `en-US` 或 `zh-CN` | ## 修改已有文案 ### 找到对应的键 在两份 `messages.ts` 和 `src/i18n/` 中搜索页面上看到的英文文字。公开站和共享文案在主字典里,后台文案可能在功能文件里。 ### 在两种语言里修改同一个键 在英文和中文条目的相同路径下修改值。值可以是字符串、数组,或用于带数字文案的函数: ```ts title="src/i18n/locales/en/messages.ts" pricing: { title: "Plans", credits: (count: number) => `${count.toLocaleString("en-US")} credits included`, }, ``` 不要为了改文字而重命名键,其他文件可能也在读取它。 ## 新增文案 ### 把键加到两份字典里 只有几条文字时,加到已有的命名空间里。新页面或新功能则单独建一个命名空间,在两个文件中放在相同的位置: ```ts title="src/i18n/locales/en/messages.ts" reportsPage: { title: "Reports", empty: "No reports yet.", }, ``` ```ts title="src/i18n/locales/zh/messages.ts" reportsPage: { title: "报表", empty: "还没有报表。", }, ``` 位于某个模块 `// @module:` 区域里的键属于该模块。你自己的键要放在这些区域之外。 ### 在组件里读取 在 `{-$locale}` 下的路由组件中: ```tsx import { useI18n } from "@/i18n/use-i18n"; const { locale, t } = useI18n(); return

{t("reportsPage.title")}

; ``` 在通过属性接收 `locale` 的组件中,读取整个命名空间: ```tsx import { getMessageNamespace, type Locale } from "@/i18n/messages"; const copy = getMessageNamespace(locale, "reportsPage"); ``` `t()` 的类型以英文字典为准,所以拼错的键会让 `pnpm typecheck` 失败。运行时,如果中文字典里缺少某个键,页面上会直接显示这个键名。 ### 检查两份字典的键是否一致 ```bash pnpm validate:app-i18n ``` 其中的 `dictionaries-carry-the-same-keys` 检查会运行 `validateLocaleParity()`,逐一比较键路径。任一语言多出或缺少键时,检查失败并列出这些键。 ## 新增支持多语言的路由 ### 在 `{-$locale}` 下创建文件 所有页面路由都在 `src/routes/{-$locale}/` 里。`{-$locale}` 是 TanStack Router 的可选路径段。同一个文件在没有 `locale` 参数时响应 `/reports`,在 `locale: "zh"` 时响应 `/zh/reports`。 ```tsx title="src/routes/{-$locale}/reports.tsx" import { createFileRoute } from "@tanstack/react-router"; import { normalizeLocale } from "@/i18n/messages"; export const Route = createFileRoute("/{-$locale}/reports")({ component: ReportsPage, }); function ReportsPage() { const { locale } = Route.useParams(); return ; } ``` 不要创建 `src/routes/zh/` 目录,也不要为每种语言各写一个文件。这两种做法都会让 `pnpm validate:route-i18n` 失败。 ### 未知语言交给父路由处理 `src/routes/{-$locale}.tsx` 是所有页面的父路由。第一个路径段不是已知语言时它返回 not found,并把解析出的 `locale` 放进路由上下文,`useI18n()` 读取的就是它。页面里不需要重复这项检查。 ### 按语言生成链接和页面描述 链接用 `localizedPath()` 生成。公开页面把本地化后的路径传给 `buildMeta()`,并加上 `hreflang` 互链,写法参考 `src/components/marketing/example-landing.tsx` 中的 `buildHomeHead()`。根文档会根据 URL 自动设置 ``(`en` 或 `zh-Hans`)。 ### 重新生成路由树 运行一次 `pnpm dev`。它会重写 `src/routeTree.gen.ts` 收录新路由。在此之前 `pnpm typecheck` 会失败。 ## 了解校验器检查什么 | 校验器 | 关于 i18n 的断言 | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `pnpm validate:route-i18n` | 所有页面路由都在 `src/routes/{-$locale}/` 下;不存在 `src/routes/zh/` 文件;父路由校验语言;首页是围绕同一个共享组件的单个路由 | | `pnpm validate:app-i18n` | 外壳、导航标签、登录、系统、初始化和公开页面都从字典读取文案;导航项带有 `labelKey`;清单中的字符串没有被硬编码 | | `pnpm validate:beui-console` | `src/i18n/` 下每个后台文案文件(文件名以 `admin`、`asset`、`email`、`support`、`auth`、`system`、`billing` 或 `config` 开头)都有键完全一致的 `en` 和 `zh` 条目,且没有其他语言 | | `pnpm validate:system` | 系统状态页及其文案 | `pnpm validate:app-i18n` 还会比较主字典的键集合,并指出只存在于一种语言的键。 **增加第三种语言** 语言列表是 `src/i18n/messages.ts` 中的 `locales` 常量,每一项对应一份字典,并在 `localeHrefLang` 和 `localeToIntlTag` 中有对应的标签。后台文案文件和 `pnpm validate:beui-console` 只接受 `en` 和 `zh`,因此增加第三种语言需要修改这些文件和这个校验器。 ## 验证 ```bash pnpm typecheck pnpm validate:route-i18n pnpm validate:app-i18n pnpm validate:beui-console ``` 分别用英文路径和 `/zh` 路径打开页面。使用页面上的语言切换器,页面切换到另一种语言的同一页面,所有标签随之变化。 ## 下一步 - [新增后台或工作台页面](https://kernlift.dev/zh/docs/customize/new-page.md) 在新的后台页面上使用新命名空间。 - [替换落地页和定价页](https://kernlift.dev/zh/docs/customize/landing-pages.md) 公开站文案命名空间的实际用法。 - [换成自己的品牌](https://kernlift.dev/zh/docs/customize/branding.md) 放在字典里的标题和描述。 --- # 替换落地页和定价页 > 重写示例首页、用 page-shell 原语新增公开页面,并了解 /pricing 读取什么数据、校验器强制哪些规则。 Source: https://kernlift.dev/zh/docs/customize/landing-pages 底座在 `/` 提供了一个示例落地页,页面文案已注明它需要改写。`/pricing` 是实际可用的页面,列出结账时收费的套餐。本指南说明如何重写落地页,以及 `/pricing` 读取哪些数据。 ## 准备工作 * 一个能用 `pnpm dev` 跑起来的项目,并且 `src/config/site.ts` 里已经是你的名称。见[换成自己的品牌](https://kernlift.dev/zh/docs/customize/branding.md)。 * 首页在每种上线语言下的文案。默认英文和中文都必须提供,见[新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md)。 * 对于 `/pricing`:至少一个处于上架状态的套餐。见[定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)。 ## 认识各个部件 | 部件 | 文件 | 说明 | | ----- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | 首页路由 | `src/routes/{-$locale}/index.tsx` | 加载会话快照,为 `/` 和 `/zh` 渲染 `ExampleLandingPage` | | 落地页组件 | `src/components/marketing/example-landing.tsx` | `ExampleLandingPage`、`buildHomeHead` 和 `loadHomeRouteData` | | 落地页文案 | 两份 `messages.ts` 中的 `publicSite.landing` | 标题、导语、两个行动按钮、`features`、`steps` 和结尾区块 | | 公开站外壳 | `src/components/marketing/public-shell.tsx` | `PublicMarketingShell`(页头、页脚、跳转链接)和 `PublicPageHero` | | 布局原语 | `src/components/marketing/ui/page-shell.tsx` | `Section`、`SectionHeader`、`Panel`、`PanelGrid`、`Eyebrow`、`PageTitle`、`ArrowLink`、`Screenshot`、`CommandLine`、`FactList`、`PageContainer` | | 定价页 | `src/components/marketing/pricing-plans-page.tsx` | `PricingPlansPage`,由 `src/routes/{-$locale}/pricing.tsx` 渲染 | | 关于与联系 | `src/components/marketing/localized-pages.tsx` | 两个用同样方式搭建的短页面,新增页面时可以照抄 | ## 重写首页 ### 先改文案 修改 `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` 中的 `publicSite.landing`。如果现有结构(首屏、功能网格、三个步骤、结尾行动按钮)适合你的产品,改完这些字符串就完成了。页面的 `` 和分享卡片在同一文件的 `seo.home.title`、`seo.home.description` 中设置。 ### 在 `example-landing.tsx` 中调整布局 用原语拼出一个个区块。`Section` 是一条通栏区块。`tone="stage"` 使用柔和的背景色,区块在 `page` 与 `stage` 之间交替。`tone="inverted"` 只用于唯一的结尾区块。 ```tsx title="src/components/marketing/example-landing.tsx" <PublicMarketingShell locale={locale}> <PublicPageHero actions={ <ButtonLink href={localizedPath("/auth/sign-up", locale)} variant="primary"> {copy.primaryCta} </ButtonLink> } copy={copy.copy} eyebrow={siteConfig.name} title={copy.title} /> <Section tone="stage"> <div className="grid min-w-0 gap-8"> <SectionHeader eyebrow={copy.featuresEyebrow} title={copy.featuresTitle} /> <PanelGrid columns={3}> {copy.features.map((feature) => ( <Panel key={feature.title}> <h3 className="m-0 text-base leading-6 font-semibold">{feature.title}</h3> <p className="m-0 text-sm leading-6 text-muted-foreground">{feature.body}</p> </Panel> ))} </PanelGrid> </div> </Section> </PublicMarketingShell> ``` 按钮来自 `@/components/motion/button`(`Button`、`ButtonLink`)。站内链接一律用 `localizedPath(path, locale)` 生成,这样 `/zh` 页面只会链接到 `/zh` 页面。样式用基于产品令牌的 Tailwind 工具类(`text-muted-foreground`、`border-border`、`bg-card`),见[使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md)。 ### 保留文件、导出名和两个链接 有几个校验器会读取这个页面。满足以下条件它们就保持通过: * 组件仍在 `src/components/marketing/example-landing.tsx` 中,以 `ExampleLandingPage` 导出,`loadHomeRouteData` 与它同文件,首页路由仍然渲染它; * 文案通过 `getMessageNamespace(locale, "publicSite").landing` 读取; * 页面上保留一个指向 `/auth/sign-up` 的链接和一个指向 `/pricing` 的链接; * 渲染站点名称、`title`、`primaryCta`、`secondaryCta`、每个 `features[].title` 和 `steps` 的每一项。 如果你的设计不再需要功能网格或步骤,就在同一次改动里从两份字典中删掉这些键,并更新 `scripts/validate/example-landing.ts` 里的期望列表。不要让校验器断言页面已经不再渲染的文案。 ### 为已登录的访客显示账户入口 首页是唯一会加载会话的公开页面。`loadHomeRouteData()` 返回当前用户、是否可以进入 `/admin` 以及积分余额。`ExampleLandingPage` 把 `PublicAccountMenu` 传给外壳的 `account` 属性,替换掉登录和注册按钮。其他公开页面不要设置 `account`,这样这些页面保持匿名,可以缓存。 ## 新增一个公开页面 1. 在两份 `messages.ts` 中新增一个命名空间存放文案,写法参考 `aboutPage`。 2. 在 `src/components/marketing/localized-pages.tsx` 中 `AboutMarketingPage` 旁边新增组件(也可以在 `src/components/marketing/` 下单独建文件):`PublicMarketingShell` 包住一个 `PublicPageHero` 和一个或多个 `Section`。 3. 复制 `src/routes/{-$locale}/about.tsx` 作为新路由,修改 `createFileRoute("/{-$locale}/about")` 里的路径。 4. 把路径加入 `src/server/services/static-seo.service.ts` 的 `publicSeoRoutes`,它才会出现在 `/sitemap.xml` 中。 5. 需要放进页头时,在 `src/components/marketing/public-shell.tsx` 的 `publicNavigation` 中加一项,并在两份字典的 `publicSite.navigation` 下加上对应的标签。页脚链接也在这个文件里。 6. 运行一次 `pnpm dev`,让 `src/routeTree.gen.ts` 收录新路由。 ## 了解 `/pricing` 读取什么 `/pricing` 的代码里没有任何套餐数据。它的 loader 按当前语言调用 `getMarketingSite()`,只保留状态为 `active` 的套餐。这些记录来自 `pricing_plans` 表,每个套餐每种语言一行,在 `/admin/plans` 中编辑。 | 页面上的内容 | 来源 | | ----------------- | -------------------------------------------------------------------- | | 套餐名称、描述、功能列表、按钮文字 | 该套餐在当前语言下的那一行 | | 价格 | 该行的 `priceCents` 和 `currency`,按语言格式化 | | 计费周期 | `publicSite.pricing.intervals`(`month`、`year`、`lifetime`、`one_time`) | | 「包含积分」一行 | `includedCredits`,大于零时显示 | | 标题、导语、空状态 | 字典中的 `publicSite.pricing` | 套餐按钮向 `/api/billing/checkout` 发起请求。服务端重新计算价格,再把浏览器跳转到支付服务商的结账页。未登录的访客先跳到登录页,登录后回到 `/pricing`。其他失败跳到 `/system/payment-failed`,并附带原因。已登录用户在 `/app/billing/upgrade` 看到的是同一批套餐。 要调整售卖内容,在后台修改套餐。要调整页面样式,可以修改 `PricingPlansPage`,但必须保留 `requestCheckout()` 作为按钮发起购买的唯一途径。没有上架套餐时,页面只显示 `publicSite.pricing.empty` 这句文案。 ## 遵守校验器强制的规则 `pnpm validate:example-landing` 会读取 `example-landing.tsx` 和 `pricing-plans-page.tsx`,出现以下任一情况即失败: * 从 `src/components/ui`(shadcn)导入; * 硬编码颜色(`#hex`、`rgb(` 或 `hsl(`); * 使用 `ds-`、`mk-` 或 `ds-mk-` 前缀的类名。`ds-mk-*` 营销命名空间已经停用,不要再引入,也不要沿用设计生成工具产出的类名; * 使用内联的 `style={{ … }}`; * 没有渲染在 `PublicMarketingShell` 里。 公开页面不声明自己的令牌。缺少某个颜色时,在 `src/styles/app.css` 的 `:root` 上新增或修改令牌,这样所有界面都能使用。这个校验器还会检查落地页、定价页和外壳渲染出的每个链接,以及 `publicSeoRoutes` 中的每个路径,只要有一个找不到对应的路由文件就失败。 ## 验证 ```bash pnpm validate:example-landing pnpm validate:marketing pnpm validate:route-i18n pnpm validate:app-i18n pnpm validate:mobile ``` 然后在浅色和深色主题、手机宽度和桌面宽度下分别打开 `/` 和 `/zh`。未登录时打开 `/pricing` 并点击某个套餐。页面先跳到登录页,登录后回到 `/pricing`。 ## 下一步 - [定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md) 创建 `/pricing` 列出的套餐。 - [使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md) 令牌、motion 组件,以及不能导入什么。 - [新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md) 让两份字典保持一致。 - [用 CMS 发布内容](https://kernlift.dev/zh/docs/extensions/cms.md) 博客、更新日志和法律页面。 --- # 新增后台或工作台页面 > 在 /admin 或 /app 下新增一个页面:带守卫的服务端函数、两种语言的文案和一个导航入口。 Source: https://kernlift.dev/zh/docs/customize/new-page 本指南新增单个页面:`/admin` 下面向运营人员的页面,或 `/app` 下面向用户的页面。布局已经保护了这个页面,所以你只需要添加一个路由文件、一个检查调用者身份的服务端函数、两种语言的文案和一个导航入口。带有自己数据表的完整功能应该做成模块,见[构建模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md)。 ## 准备工作 * 一个能用 `pnpm dev` 跑起来的项目,以及一个管理员账号。见[运行管理后台](https://kernlift.dev/zh/docs/core/admin.md)。 * 页面路径(`/admin/<name>` 或 `/app/<name>`),以及它读取什么、写入什么。 * 后台页面还需要确定用哪个权限键做门禁。`/admin/permissions` 的权限目录里有合适的就复用。 * 如果你使用编码 agent,`new-page` 技能包含同样的步骤。见[使用 agent 技能](https://kernlift.dev/zh/docs/core/agent-skills.md)。 ## 了解布局已经做了什么 | 区域 | 布局路由 | 在页面加载前做的事 | | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------ | | `/admin/*` | `src/routes/{-$locale}/admin.tsx` | 要求有会话并具备 `admin.access` 权限。没有会话跳转到 `/system/session-expired`,没有权限跳转到 `/system/permission-denied` | | `/app/*` | `src/routes/{-$locale}/app.tsx` | 要求有会话。没有会话跳转到 `/system/session-expired`,账号被封禁跳转到 `/system/permission-denied` | 两个布局还会对属于已停用插件的页面返回 not found,并通过 `AuthProvider` 把当前用户的权限传给页面。在这两个目录下新建的文件不需要额外代码就受保护。 布局只保护页面,不保护数据。服务端函数是任何人都能调用的 HTTP 端点,所以每个服务端函数都必须检查调用者。 ## 新增页面 ### 编写服务端函数 加到 `src/server/functions/` 下对应的文件里,或在那里新建文件。用 zod 校验输入,先解析调用者,再委托给服务层。 ```ts title="src/server/functions/reports.ts" import { createServerFn } from "@tanstack/react-start"; import { requireAdminPermission } from "./admin-permissions"; import { requireCurrentUserId } from "./session"; // Admin: gate on a permission. export const getAdminReports = createServerFn({ method: "GET" }).handler(async () => { await requireAdminPermission("reports.read"); return listReports(); }); // Workspace: bind to the signed-in user. export const getMyReports = createServerFn({ method: "GET" }).handler(async () => { const userId = await requireCurrentUserId(); return listReportsForUser(userId); }); ``` 调用者没有权限时,`requireAdminPermission()` 抛出 `Permission denied: <key>`。`requireCurrentUserId()` 拒绝没有会话或已被封禁的调用者,不存在兜底身份。数据库访问写在 `src/server/db/repositories/` 下的仓储里,由服务层调用。 ### 在两种语言里添加文案 在 `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` 中新增键完全一致的命名空间,并在 `shell.nav`(后台)或 `appConsole`(工作台)下为导航入口加一个标签。见[新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md)。 ### 创建路由文件 后台页面参考 `src/routes/{-$locale}/admin/rate-limits.tsx` 的结构: ```tsx title="src/routes/{-$locale}/admin/reports.tsx" import { createFileRoute } from "@tanstack/react-router"; import { AdminRecords } from "@/components/admin/admin-records"; import { adminRouteFeedback } from "@/components/admin/admin-route-feedback"; import { AppShell } from "@/components/layout/app-shell"; import { getMessageNamespace, normalizeLocale } from "@/i18n/messages"; import { getAdminReports } from "@/server/functions/reports"; export const Route = createFileRoute("/{-$locale}/admin/reports")({ ...adminRouteFeedback, loader: () => getAdminReports(), component: AdminReportsPage, }); function AdminReportsPage() { const rows = Route.useLoaderData(); const locale = normalizeLocale(Route.useParams().locale); const copy = getMessageNamespace(locale, "adminReportsCopy"); return ( <AppShell activeNav="Reports" currentPage={copy.currentPage} locale={locale} mode="admin"> <AdminRecords columns={[{ key: "name", label: copy.name, render: (row) => row.name }]} emptyLabel={copy.empty} rowKey={(row) => row.id} rows={rows} /> </AppShell> ); } ``` `adminRouteFeedback` 提供加载中和出错时的组件,每个后台路由都要展开它。 工作台页面参考 `src/routes/{-$locale}/app/tickets/index.tsx`。这个页面渲染在 `@/components/layout/app-console-sidebar` 的 `AppConsoleLayout` 里,用 `useI18n()` 读取文案,并把自己导航入口的 id 作为 `active` 传入。 带详情子页面的列表页,在路径更深时返回 `<Outlet />`,写法参考 `src/routes/{-$locale}/admin/orders.tsx`。 ### 用设计系统搭建页面主体 组合后台模式(`AdminRecords`、`AdminMetrics`、`AdminPanel`、`Config*` 布局、`useAdminSave`)和 `src/components/motion` 里的组件。不要导入 `src/components/ui`,也不要添加 `<main>`,`<main>` 由外壳渲染。见[使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md)。 需要保存的页面调用 `useAdminSave("<key>.write")`。`allowed` 为 false 时禁用表单,并在执行写入的服务端函数里再检查一次同样的权限。 ### 添加导航入口 侧边栏入口由插件贡献。属于你产品本身的页面,加到 `src/plugins/foundation/plugin.ts` 的底座插件里。 后台入口加在 `adminNav` 数组中: ```ts title="src/plugins/foundation/plugin.ts" { ...operations, label: "Reports", labelKey: "shell.nav.reports", to: "/admin/reports", icon: ListChecks, permission: "reports.read", order: 650, }, ``` 文件顶部的分组常量(`overview`、`operations`、`commerce`、`platform`、`security`、`settings`)决定入口出现在侧边栏的哪个分组。`order` 决定位置。底座入口以 100 为步长,你的入口可以插在两个入口之间。`permission` 必填,没有该权限的用户看不到这个入口。 工作台入口加在同一插件的 `app.nav` 列表中: ```ts title="src/plugins/foundation/plugin.ts" { id: "reports", icon: ListTodo, labelKey: "appConsole.reports", path: "/app/reports", section: "product", order: 35, }, ``` `section` 取 `product` 或 `account`。页面把同一个 `id` 作为 `active` 传给 `AppConsoleLayout`。 如果希望这个页面可以在 `/admin/plugins` 里整体开关,就为它单独写一个插件,见[后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md)。 ### 授予新权限 复用已有权限键时跳过这一步。新增权限键时,在 `src/server/services/super-admin-bootstrap.service.ts` 的 `superAdminPermissionTemplates` 中加一行,然后运行: ```bash pnpm db:bootstrap-super-admin ``` 脚本会写入全部权限,并全部授予 Super Admin 角色。其他角色在 `/admin/roles` 中授权。见[管理用户、角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 ### 重新生成路由树 ```bash pnpm dev ``` 启动开发服务器会重写 `src/routeTree.gen.ts`,收录新路由。然后运行 `pnpm typecheck`。 ## 验证 ```bash pnpm typecheck pnpm validate:auth-boundary pnpm validate:plugins pnpm validate:beui-console pnpm validate:route-i18n pnpm validate:app-i18n ``` 这些校验器在新页面上检查以下问题: | 校验器 | 何时失败 | | ----------------------------- | ------------------------------------------------------------------------------------------------------ | | `pnpm validate:auth-boundary` | 某个导出的服务端函数既不解析身份也不检查权限。确实需要公开的函数必须连同理由写进 `scripts/validate/auth-boundary.ts` 的 `publicServerFunctions` | | `pnpm validate:plugins` | 导航入口指向不存在的路由文件、后台入口没有 `permission`,或工作台页面传入的 `active` id 没有任何 `app.nav` 入口声明 | | `pnpm validate:beui-console` | 页面导入了 `src/components/ui`、没有渲染在外壳里,或自带 `<main>` | | `pnpm validate:route-i18n` | 路由文件不在 `src/routes/{-$locale}/` 下 | 然后在浏览器里检查: * 在浅色和深色主题下,分别用英文路径和 `/zh` 路径打开页面。 * 用没有该权限的用户登录。侧边栏入口消失,直接打开 URL 会显示路由的出错状态,因为 loader 调用的服务端函数拒绝了请求。 * 退出登录后打开 URL,页面跳转到 `/system/session-expired`。 ## 下一步 - [使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md) 后台模式与 motion 组件。 - [后台插件](https://kernlift.dev/zh/docs/core/plugins/console-plugins.md) 用自己的插件贡献页面和导航。 - [认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md) 服务端函数为什么要自己检查调用者。 --- # 部署到 Cloudflare Workers > 把 Worker 部署在 D1 或经 Hyperdrive 连接的 Postgres 上,写入会话密钥,创建线上管理员,并按需加上 agent 容器。 Source: https://kernlift.dev/zh/docs/deploy/cloudflare 在 Cloudflare 上,项目是一个 Worker,带一个 R2 桶和一个 KV 命名空间。数据库是 D1,或经 Hyperdrive 访问的 Postgres。agent 服务可选,以 Cloudflare 容器运行,且只支持 Postgres。首次生产部署或修改绑定后使用本指南。 ## 准备工作 * Cloudflare 账号,且 `wrangler` 已登录(`npx wrangler login`)。 * `deploy.config.json` 中是 `"platform": "cloudflare"`。如果是别的平台,先执行 `pnpm kernlift deploy-target cloudflare`,见 [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 * 使用 Postgres 时:一个空的 Postgres 数据库及其连接 URL,见[使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md)。 * 项目根目录的 `.env.production`。`pnpm kernlift deploy-target cloudflare` 会生成它,里面有会话密钥。 ## 在 Cloudflare 创建资源 先在要部署的 Cloudflare 账号中登录 Wrangler,将示例中的 `my-saas` 换成你的项目名。 ### 选择数据库连接 D1 项目创建数据库并保存输出的 `database_id`。 ```bash npx wrangler d1 create my-saas-edge ``` Postgres 项目在此处改为创建 Hyperdrive。将命令中的连接串替换为你的数据库连接串,保存输出的配置 ID。 ```bash npx wrangler hyperdrive create my-saas-db --connection-string='postgresql://USER:PASSWORD@HOST:5432/DB' ``` ### 创建对象存储桶 保存桶名,稍后将它填入 R2 绑定。 ```bash npx wrangler r2 bucket create my-saas-assets ``` ### 创建缓存命名空间 保存 KV 命名空间的 ID。 ```bash npx wrangler kv namespace create my-saas-cache ``` 把 D1 的 `database_id`、KV 的 `id`、R2 桶名和 Hyperdrive id 填进 `wrangler.jsonc` 里已有的条目。Wrangler 若询问是否自动添加绑定,请拒绝。模板已经声明了 `EDGE_DB`、`BUCKET`、`CACHE` 和 `HYPERDRIVE`,应用按这些名字查找绑定。见 [D1 创建数据库](https://developers.cloudflare.com/d1/get-started/)、[R2 创建桶](https://developers.cloudflare.com/r2/buckets/create-buckets/)、[KV 创建命名空间](https://developers.cloudflare.com/kv/get-started/)和 [Hyperdrive](https://developers.cloudflare.com/hyperdrive/get-started/)。 ## 绑定资源 ### 填写 `wrangler.jsonc` 把每个 `replace-with-...` 占位符换成真实 id,保留 worker `name`。D1 项目包含: ```jsonc title="wrangler.jsonc" "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-saas-assets" }], "kv_namespaces": [{ "binding": "CACHE", "id": "<your KV namespace id>" }], "d1_databases": [ { "binding": "EDGE_DB", "database_name": "my-saas-edge", "database_id": "<your D1 database id>", "migrations_dir": "./drizzle/migrations/sqlite" } ] ``` Postgres 项目没有 `d1_databases` 块。它在 `vars` 下把 `DATABASE_DIALECT` 设为 `postgres`、`DATABASE_ADAPTER` 设为 `hyperdrive`,并包含: ```jsonc title="wrangler.jsonc" "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<your Hyperdrive id>" }] ``` ### 设置生产变量 D1 项目的 `vars` 里 `APP_ENV` 默认是 `development`,改成 `production`。再加上 `SITE_URL`,值为你的公网源地址。不要把密钥写进这个文件。 ### 重新生成绑定类型 ```bash pnpm cf-typegen ``` **重新渲染会把现有的 wrangler.jsonc 移到一边** `pnpm kernlift deploy-target cloudflare --dialect postgres` 把 D1 项目改成 Hyperdrive 项目,做法是按模板重新渲染 `wrangler.jsonc`。现有文件连同其中的资源 id 会移到 `.kernlift/previous-deploy/wrangler.jsonc`,把桶名和 KV id 从那里抄到新文件。 ## 迁移并部署 ### 应用迁移 D1: ```bash pnpm db:migrate:d1:remote ``` Postgres 则在检出目录里直接迁移数据库。Hyperdrive 是 Worker 绑定,所以迁移用的是 Postgres URL 本身: ```bash DATABASE_DIALECT=postgres DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB' pnpm db:migrate ``` ### 构建并部署 ```bash pnpm build pnpm run deploy ``` 该脚本执行 `wrangler deploy` 并打印 Worker 的 URL。 ### 写入会话密钥 密钥要挂在已存在的 Worker 上,所以在首次部署之后写入。值从 `.env.production` 经标准输入读取: ```bash grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put BETTER_AUTH_SECRET grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2- | npx wrangler secret put CONFIG_ENCRYPTION_KEY ``` ### 创建线上管理员 D1 在检出目录里执行引导脚本,`--remote` 通过 wrangler 连到已部署的数据库: ```bash DATABASE_DIALECT=d1 SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin --remote ``` Postgres 则指向生产数据库: ```bash DATABASE_DIALECT=postgres DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB' SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin ``` 脚本从环境变量读取邮箱和密码,不接受通过参数传入。 **使用 pnpm run deploy** 不带 `run` 的 `pnpm deploy` 是 pnpm 自己的工作区命令,不是项目脚本。 ## 加上 agent 容器 项目不含 agent 时跳过本节。agent 需要 Postgres,所以项目必须使用 Hyperdrive。`pnpm kernlift deploy-target cloudflare --agent` 渲染出带 `containers` 和 `durable_objects` 块的 `wrangler.jsonc`,并把 agent 密钥补进 `.env.production`。 ### 写入 agent 密钥 ```bash grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put AGENT_INTERNAL_SIGNING_SECRET grep '^AGENT_RESOURCE_GRANT_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put AGENT_RESOURCE_GRANT_SECRET ``` `AGENT_DATABASE_URL` 用同样的方式写入。它是直连的 Postgres URL。容器不能使用 Hyperdrive 绑定,所以直接连接同一个数据库。 ### 让 agent 能回访 Worker 把 `wrangler.jsonc` 里 `vars` 下的 `AGENT_WEB_INTERNAL_URL` 设为 Worker 的公网 URL。agent 服务通过它回调 Web 应用。 ### 再部署一次 ```bash pnpm build pnpm run deploy ``` Wrangler 用 `apps/agent-service/Dockerfile` 构建容器镜像。只运行一个实例,因为服务在内存里持有运行状态。 ## 验证 * `pnpm run deploy` 打印 Worker 的 URL,站点可以在该地址打开。 * 以管理员身份打开 `/setup`,第一行写明 Cloudflare 和所用数据库,**会话密钥**为就绪。 * `/admin/config/auth` 里的 **基础 URL** 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。 * **定时任务**在一两分钟内变为就绪。`wrangler.jsonc` 里的 Cron Trigger 每分钟执行一轮。 * 包含 agent 时,`/app/agent` 打开工作台。 * 在仓库里,`pnpm build` 之后的 `pnpm smoke:worker` 会用一次性的 D1 数据库运行构建出的 Worker,`pnpm validate:deploy-targets` 检查渲染出的配置。 ## 故障排查 ### `EDGE_DB D1 binding is required when DATABASE_ADAPTER=d1` Worker 没有名为 `EDGE_DB` 的 D1 绑定。检查 `wrangler.jsonc` 里的 `d1_databases` 后重新部署。 ### `DATABASE_ADAPTER=hyperdrive needs the HYPERDRIVE Worker binding.` `wrangler.jsonc` 里缺少 `hyperdrive` 条目,或其中仍是占位 id。填入真实的 Hyperdrive id 后重新部署。 ### Worker 因会话密钥错误拒绝启动 `APP_ENV` 不是 `development`,且缺少 `BETTER_AUTH_SECRET`。用上面的命令写入。 ### 页面因缺少表而报错 迁移只在本地数据库上执行过。运行 `pnpm db:migrate:d1:remote`,或对 Postgres URL 运行 `pnpm db:migrate`。 ### 定时任务一直未就绪 检查 `wrangler.jsonc` 是否保留 `"triggers": { "crons": ["* * * * *"] }`,以及已部署的 Worker 是否列出了该触发器。 ## 参考 * [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md)与[环境变量](https://kernlift.dev/zh/docs/reference/env.md) * [缓存](https://kernlift.dev/zh/docs/core/admin/cache.md)与[存储](https://kernlift.dev/zh/docs/extensions/storage.md) * [Wrangler 配置](https://developers.cloudflare.com/workers/wrangler/configuration/) * [D1](https://developers.cloudflare.com/d1/)、[R2](https://developers.cloudflare.com/r2/)、[KV](https://developers.cloudflare.com/kv/)、[Hyperdrive](https://developers.cloudflare.com/hyperdrive/)、[Containers](https://developers.cloudflare.com/containers/) ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md) - [运行 agent starter](https://kernlift.dev/zh/docs/extensions/agent/starter.md) --- # 用 Docker Compose 部署 > 用 compose.yaml 在自己的服务器上运行项目:设置公网地址,启动并迁移,在前面加上 TLS,并创建线上管理员。 Source: https://kernlift.dev/zh/docs/deploy/docker 在 Docker 主机上,项目是一组 compose 服务:`migrate` 服务应用迁移后退出,`web` 服务由根目录的 `Dockerfile` 构建,数据库是挂在卷上的 SQLite 文件或自带的 Postgres。agent 服务可选,作为 compose 服务运行,且只支持 Postgres。整个过程不创建任何远程资源。在自己管理的服务器上首次部署时使用本指南。 ## 准备工作 * 一台装有 Docker 和 Docker Compose 的服务器(`docker compose version` 有输出),项目已检出到上面。 * `deploy.config.json` 中是 `"platform": "docker"`。执行 `pnpm kernlift deploy-target docker` 来设置,按需加上 `--dialect sqlite`、`--dialect postgres` 或 `--agent`。见 [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 * 项目根目录有 `compose.yaml` 和 `.env.production`,这条命令会写出它们。`.env.production` 不进仓库,需要你自己拷到服务器上。 * 一个指向该服务器的域名,以及负责 TLS 的反向代理。 ## 准备各项值 ### 设置公网地址 在 `.env.production` 里把 `SITE_URL` 设为公网地址,例如 `https://your-domain.com`。不设置时 web 服务回退到 `http://localhost:3000`。应用首次启动时还会用它初始化认证的 **基础 URL**,OAuth 回调和邮件链接就会指向那里。 ### 检查生成的密钥 同一个文件里必须有 `BETTER_AUTH_SECRET` 和 `CONFIG_ENCRYPTION_KEY`,数据库是 Postgres 时还要有 `POSTGRES_PASSWORD`。包含 agent 时还有 `AGENT_INTERNAL_SIGNING_SECRET` 和 `AGENT_RESOURCE_GRANT_SECRET`。缺少其中任何一个,Compose 都会启动失败。要补上缺失的键而不改动已有的值,再执行一次 `pnpm kernlift deploy-target docker`。 ## 启动 ### 构建、迁移并启动 ```bash pnpm run deploy ``` 该脚本执行: ```bash docker compose --env-file .env.production up -d --build ``` `migrate` 服务先执行 `node scripts/db/migrate-runtime.mjs`,成功后 `web` 才启动。使用 Postgres 时,`migrate` 会等 `postgres` 服务健康后再执行。 ### 在前面加上 TLS `web` 服务对外发布 3000 端口。把反向代理指向它,用你填在 `SITE_URL` 里的地址以 HTTPS 提供站点。 ### 创建线上管理员 ```bash docker compose --env-file .env.production exec web node .output/scripts/bootstrap-super-admin.mjs ``` 脚本在 web 容器内运行,针对它自己的数据库,并提示输入邮箱和密码。 ## 数据放在哪里 | 数据库 | 服务 | 卷 | | ---------- | ----------------------------------------------------- | -------- | | `sqlite` | 无;`web` 直接打开 `/data/app.db` | `data` | | `postgres` | `postgres`,镜像 `postgres:16-alpine`,用户与库名均为 `kernlift` | `pgdata` | 请备份这些卷,删除卷会删除数据库。用户上传的文件不存放在服务器上,需要在 `/admin/config/storage` 配置 S3 兼容存储,见[配置文件存储与上传](https://kernlift.dev/zh/docs/extensions/storage.md)。 `"agent": true` 时,还会有一个由 `apps/agent-service/Dockerfile` 构建的 `agent` 服务。web 服务在 compose 网络里通过 `http://agent:3001` 访问它,它不对外发布端口。只运行一个实例,因为它在内存里保存运行状态。 ## 发布新版本 拉取新代码后再执行一次 `pnpm run deploy`。镜像会重新构建,`migrate` 应用新增的迁移,成功后 `web` 被替换。 ## 验证 * `docker compose ps` 显示 `web` 在运行,`migrate` 已成功退出。 * 站点可以通过 HTTPS 在你的域名上打开。 * 以管理员身份打开 `/setup`,第一行写明 Docker 和所用数据库,**会话密钥**为就绪。 * `/admin/config/auth` 里的 **基础 URL** 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。 * **定时任务**在一两分钟内变为就绪。定时任务在 web 容器里运行。 * 包含 agent 时,`/app/agent` 打开工作台。 * 在仓库里,`pnpm build:node` 之后的 `pnpm smoke:node` 检查你要发布的构建,`pnpm validate:deploy-targets` 检查渲染出的 `compose.yaml`。 ## 故障排查 ### Compose 报 `set BETTER_AUTH_SECRET`、`set CONFIG_ENCRYPTION_KEY` 或 `set POSTGRES_PASSWORD` 后停止 `.env.production` 里缺少该值,或者执行命令时没有带 `--env-file .env.production`。使用 `pnpm run deploy`。 ### OAuth 登录或邮件链接指向 `localhost:3000` `/admin/config/auth` 里的 **基础 URL** 还是回退地址。在那里改正。同时在 `.env.production` 里设置 `SITE_URL`,再执行 `pnpm run deploy`,让元数据和绝对链接也使用公网地址。 ### `web` 一直不启动 `migrate` 失败了。用 `docker compose logs migrate` 查看它的输出。 ### `/setup` 上定时任务一直未就绪 用 `docker compose ps` 检查 web 容器是否在运行。如果设置了 `JOBS_IN_PROCESS=false`,就必须由外部 cron 执行 `pnpm jobs:run`。 ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) - [运行 Node 构建](https://kernlift.dev/zh/docs/deploy/node.md) - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md) --- # 部署到 Fly.io > 创建 Fly 应用,导入生成的密钥,部署 Node 镜像并执行迁移,创建线上管理员,并按需加上 agent 应用。 Source: https://kernlift.dev/zh/docs/deploy/fly 在 Fly.io 上,项目是一个由根目录 `Dockerfile` 构建的应用。数据库是挂在卷上的 SQLite 文件(单机),或你自备的 Postgres。agent 服务可选,作为 Fly 内网中的第二个应用运行,且只支持 Postgres。首次生产部署时使用本指南。 ## 准备工作 * `fly` CLI 已登录(`fly auth login`)。 * `deploy.config.json` 中是 `"platform": "fly"`。执行 `pnpm kernlift deploy-target fly` 来设置,按需加上 `--dialect`、`--agent` 或 `--region`。见 [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 * 项目根目录有 `fly.toml` 和 `.env.production`,这条命令会写出它们。 * 使用 Postgres 时:一个数据库及其连接 URL,见[使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md)。 示例中应用名为 `my-saas`,区域为 `iad`。请使用你 `fly.toml` 里的 `app` 和 `primary_region`。 ## 创建应用并写入密钥 `kernlift deploy-target fly` 会按你的项目打印这些步骤。 ### 设置公网地址 在 `.env.production` 里,把 `SITE_URL` 设为站点实际对外的地址。使用 Postgres 时,在同一个文件里加一行 `DATABASE_URL=`,值为连接 URL。 ### 创建应用 ```bash fly apps create my-saas ``` 使用 SQLite 时,还要创建存放数据库文件的卷: ```bash fly volumes create data --app my-saas --region iad --size 1 --yes ``` ### 导入密钥 值从 `.env.production` 经标准输入读取。SQLite: ```bash grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL)=' .env.production | fly secrets import --app my-saas ``` Postgres 则把数据库 URL 一并导入: ```bash grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL|DATABASE_URL)=' .env.production | fly secrets import --app my-saas ``` ## 部署 ### 部署 Web 应用 ```bash fly deploy ``` `pnpm run deploy` 执行的是同一条命令。Fly 构建根目录的 `Dockerfile`,并在新版本接收流量之前应用迁移。使用 Postgres 时,`release_command` 在临时机器上执行 `node scripts/db/migrate-runtime.mjs`。使用 SQLite 时,应用进程先迁移卷上的文件,再启动服务。 ### 创建线上管理员 ```bash fly ssh console --app my-saas --pty -C "node .output/scripts/bootstrap-super-admin.mjs" ``` 脚本在应用内部运行,针对它自己的数据库,并提示输入邮箱和密码。 **保持一台机器在线** 定时任务运行在 Web 进程里,所以 `fly.toml` 设置了 `min_machines_running = 1`。机器停止后,履约重试和 AI 任务轮询不再执行。使用 SQLite 时不要把应用扩到一台以上,因为数据库文件只属于一台机器。 ## 加上 agent 应用 项目不含 agent 时跳过本节。`"agent": true` 时,项目里还有 `fly.agent.toml`,对应 `my-saas-agent` 应用;`fly.toml` 把 Web 应用指向 `http://my-saas-agent.internal:3001`。agent 应用没有对外服务,也不会在运行中途被自动停机。 ### 创建 agent 应用并导入它的密钥 ```bash fly apps create my-saas-agent grep -E '^(AGENT_INTERNAL_SIGNING_SECRET|AGENT_RESOURCE_GRANT_SECRET|DATABASE_URL)=' .env.production | fly secrets import --app my-saas-agent ``` ### 把签名密钥给 Web 应用 ```bash grep -E '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | fly secrets import --app my-saas ``` ### 部署 agent 服务 ```bash fly deploy -c fly.agent.toml ``` 只运行一台机器,因为服务在内存里保存运行状态。 ## 验证 * `fly deploy` 打印应用地址,站点可以在该地址打开。 * 以管理员身份打开 `/setup`,第一行写明 Fly.io 和所用数据库,**会话密钥**为就绪。 * `/admin/config/auth` 里的 **基础 URL** 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。 * **定时任务**在一两分钟内变为就绪。 * 包含 agent 时,`/app/agent` 打开工作台。 * 在仓库里,`pnpm build:node` 之后的 `pnpm smoke:node` 检查你要发布的构建,`pnpm validate:deploy-targets` 检查渲染出的 `fly.toml`。 ## 故障排查 ### 部署在 release command 阶段失败 迁移连不上 Postgres。检查 `DATABASE_URL` 是否已导入应用,以及数据库是否接受来自 Fly 的连接。 ### 应用因会话密钥错误拒绝启动 `BETTER_AUTH_SECRET` 没有导入。重新执行导入命令。 ### `/setup` 上定时任务一直未就绪 检查 `fly.toml` 是否保留 `min_machines_running = 1`。如果设置了 `JOBS_IN_PROCESS=false`,就必须由外部 cron 执行 `pnpm jobs:run`。 ### 工作台提示未部署 agent 服务 Web 应用访问不到 `my-saas-agent.internal:3001`,或者两个应用里的 `AGENT_INTERNAL_SIGNING_SECRET` 不一致。用同一份 `.env.production` 给两个应用导入该密钥。 ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) - [运行 Node 构建](https://kernlift.dev/zh/docs/deploy/node.md) - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md) --- # 部署项目 > 从四个平台里选一个,写入生成的密钥,迁移、部署,并创建线上管理员。 Source: https://kernlift.dev/zh/docs/deploy 本教程把你在本地跑起来的项目放到公网地址上。一个项目只部署到一个平台:Cloudflare、Fly.io、Railway 或 Docker 主机。选择记录在 `deploy.config.json` 里,仓库中只保留该平台的配置文件。本页是最短路径, 每个平台另有完整指南。 ## 准备工作 * 项目能在本地构建:`pnpm build` 无错误结束。 * 目标平台的 CLI 已安装并登录:`wrangler`、`fly`、`railway`,或 Docker Compose。 * 在 Cloudflare 或 Fly.io 上使用 Postgres 时:一个 Postgres 数据库及其连接 URL。Railway 和 Docker 会自己创建。 ## 选择平台 | 平台 | 数据库 | agent 服务 | 适用场景 | | ---------- | ----------------------------- | ------------------------- | ------------------------ | | Cloudflare | D1,或经 Hyperdrive 连接的 Postgres | Cloudflare 容器,仅限 Postgres | 想用 Worker 以及 D1、R2、KV 绑定 | | Fly.io | 挂卷的 SQLite,或 Postgres | 内网中的第二个应用,仅限 Postgres | 想让容器靠近用户,并自备 Postgres | | Railway | Postgres | 第二个服务 | 想让平台把 Postgres 和应用一起建好 | | Docker | 挂卷的 SQLite,或自带的 Postgres | compose 服务,仅限 Postgres | 自己管理服务器 | Cloudflare 使用 Worker 构建;其余三个使用 Node 构建,由根目录的 `Dockerfile` 打包。agent 服务在任何 平台都是可选的,并且始终需要 Postgres。这张表背后的模型见[部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 部署 ### 确认或切换平台 仓库在 `deploy.config.json` 里记录了部署平台。查看当前选择: ```bash cat deploy.config.json ``` 对你要用的平台运行一次 `deploy-target`,即使它就是已记录的那个:刚克隆的仓库没有 `.env.production`, 这条命令会生成它。该命令写入该平台的文件,把其他平台的文件移到 `.kernlift/previous-deploy/`, 补全 `.env.production`,并打印剩下的步骤。它不创建任何远程资源,也不搬数据。 ```bash pnpm kernlift deploy-target fly --no-agent pnpm cf-typegen ``` 可用选项见 [部署配置参考](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 ### 检查生产环境的值 `.env.production` 里是生成好的会话密钥和公网地址。它被 git 忽略,绝不提交。把其中的 `SITE_URL` 改成站点实际对外的地址。下面的命令都从这个文件经标准输入读取密钥, 值不会出现在命令行上。 ### 在所选平台上迁移并部署 **Cloudflare** ```bash pnpm db:migrate:d1:remote pnpm build pnpm run deploy grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put BETTER_AUTH_SECRET grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2- | npx wrangler secret put CONFIG_ENCRYPTION_KEY ``` 在此之前,`wrangler.jsonc` 里的 D1、R2、KV 必须是真实 id。完整指南: [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md)。 **Fly.io** ```bash fly apps create my-saas fly volumes create data --app my-saas --region iad --size 1 --yes grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL)=' .env.production | fly secrets import --app my-saas fly deploy ``` 卷只在使用 SQLite 时需要。迁移在新版本接收流量之前执行。完整指南: [部署到 Fly.io](https://kernlift.dev/zh/docs/deploy/fly.md)。 **Railway** ```bash railway init --name my-saas railway config apply --yes railway variables --service web --set "BETTER_AUTH_SECRET=$(grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2-)" railway variables --service web --set "CONFIG_ENCRYPTION_KEY=$(grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2-)" railway variables --service web --set "SITE_URL=$(grep '^SITE_URL=' .env.production | cut -d= -f2-)" railway up ``` `railway config apply` 创建各个服务和 Postgres;迁移由 pre-deploy 步骤执行。完整指南: [部署到 Railway](https://kernlift.dev/zh/docs/deploy/railway.md)。 **Docker** ```bash pnpm run deploy ``` 该脚本执行 `docker compose --env-file .env.production up -d --build`;`migrate` 服务结束后 `web` 才启动。在 3000 端口前面放一个带 TLS 的反向代理。完整指南: [用 Docker Compose 部署](https://kernlift.dev/zh/docs/deploy/docker.md)。 **使用 pnpm run deploy** 不带 `run` 的 `pnpm deploy` 是 pnpm 自己的工作区命令,不是项目脚本。 ### 创建线上管理员 线上数据库不是你本地那个,需要单独创建管理员。在 Fly.io、Railway 和 Docker 上,镜像里带有一个脚本, 会提示输入邮箱和密码: ```bash fly ssh console --app my-saas --pty -C "node .output/scripts/bootstrap-super-admin.mjs" docker compose --env-file .env.production exec web node .output/scripts/bootstrap-super-admin.mjs ``` 在 Railway 上,用 `railway ssh --service web` 打开 shell,再执行 `node .output/scripts/bootstrap-super-admin.mjs`。在 Cloudflare D1 上,在已登录 `wrangler` 的检出目录 里执行: ```bash DATABASE_DIALECT=d1 SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin --remote ``` ## 验证 打开线上地址的 `/setup`,以管理员身份登录。然后打开 `/admin/config/auth`,检查 **基础 URL**;站点用的是 另一个域名时,在那里改掉。 * 第一行写明平台、数据库以及是否包含 agent 服务。 * **会话密钥**为就绪。 * **定时任务**在首次部署后一两分钟内变为就绪。 清单读取的是线上数据库,所以从这里开始配置需要的服务商,先配**邮件投递**。存储在 `/admin/config/storage` 配置;在 Cloudflare 上也可以使用运行时检测到的存储桶绑定。 ## 故障排查 ### 应用因会话密钥错误拒绝启动 `APP_ENV` 不是 `development`,而 `BETTER_AUTH_SECRET` 没有写到平台上。用所在平台的命令重新写入。 ### OAuth 登录或邮件链接指向了错误的地址 OAuth 回调和邮件链接使用 `/admin/config/auth` 里的 **基础 URL**。在那里改正即可,约 30 秒内生效, 不需要重新部署。 ### `/setup` 上定时任务一直未就绪 没有任何东西在触发任务轮次。该项会指出所在平台的开关:Cloudflare 上是 `wrangler.jsonc` 里的 Cron Trigger,其它平台上是一个在运行的 Web 进程。 ## 下一步 - [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md) D1、用于 Postgres 的 Hyperdrive,以及 agent 容器。 - [部署到 Fly.io](https://kernlift.dev/zh/docs/deploy/fly.md) 挂卷的 SQLite 或 Postgres,agent 作为第二个应用。 - [部署到 Railway](https://kernlift.dev/zh/docs/deploy/railway.md) 由 `.railway/railway.ts` 创建服务和 Postgres。 - [用 Docker Compose 部署](https://kernlift.dev/zh/docs/deploy/docker.md) 一台服务器、`compose.yaml` 和反向代理。 - [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md) 允许的组合,以及每个平台拥有的文件。 --- # 运行 Node 构建 > 用 pnpm build:node 或根目录的 Dockerfile 构建 Node 服务,提供它需要的环境变量,迁移,然后在任意主机上运行。 Source: https://kernlift.dev/zh/docs/deploy/node 除 Cloudflare 以外,所有平台运行的都是同一个 Node 服务。`pnpm build:node` 构建它,根目录的 `Dockerfile` 打包它,Fly.io、Railway 和 Docker Compose 各自用生成的配置部署这个镜像。本指南说明这个构建里有什么,以及如何在没有专门指南的主机上运行它。三个受支持的平台请直接看[部署到 Fly.io](https://kernlift.dev/zh/docs/deploy/fly.md)、[部署到 Railway](https://kernlift.dev/zh/docs/deploy/railway.md)或[用 Docker Compose 部署](https://kernlift.dev/zh/docs/deploy/docker.md)。 ## 准备工作 * 一台装有 Node 22 或 Docker 的主机。 * 一个数据库:Postgres(见[使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md)),或单实例时放在重启后不丢失的磁盘上的 SQLite 文件。 * 一个会话密钥。`kernlift deploy-target` 生成的 `.env.production` 里已经有。 ## 构建产物 | 路径 | 内容 | | ------------------------------------------- | ---------------------------------------- | | `.output/server/index.mjs` | 服务端。`pnpm start` 运行它;监听 `PORT`,镜像里是 3000 | | `.output/scripts/bootstrap-super-admin.mjs` | 对部署自己的数据库创建管理员,不需要 TypeScript 运行器 | | `scripts/db/migrate-runtime.mjs` | 用纯 Node 应用迁移链 | | `drizzle/migrations/` | 迁移器读取的 SQLite 与 Postgres 迁移链 | 根目录的 `Dockerfile` 执行 `pnpm build:node`,把这四项复制进 `node:22` 镜像,并装上数据库驱动(`better-sqlite3`、`postgres`、`drizzle-orm`)。驱动在运行时按名字加载,不在打包产物里。镜像以 `node` 用户运行,暴露 3000 端口,并提供 `/data` 目录,用来放挂载卷上的 SQLite 文件。agent 服务是另一个镜像:`apps/agent-service/Dockerfile`。 `deploy.config.json` 里是 `fly`、`railway` 或 `docker` 时,`pnpm build` 产出的就是这个构建;`pnpm build:node` 则始终产出它。 ## 环境变量 服务从进程环境读取设置。 | 变量 | 值 | | --------------------------------------------------- | --------------------------------------------------------- | | `APP_ENV` | `production` | | `PORT` | 监听端口 | | `BETTER_AUTH_SECRET` | `.env.production` 里的会话密钥 | | `CONFIG_ENCRYPTION_KEY` | `.env.production` 里的凭据加密密钥,生成后不要更换 | | `SITE_URL` | 规范源地址,用于页面元数据和绝对链接 | | `DATABASE_DIALECT` | `postgres` 或 `sqlite` | | `DATABASE_URL` | `postgresql://` URL,或 `/data/app.db` 这样的文件路径 | | `JOBS_IN_PROCESS` | 不要设置。设为 `false` 会关闭定时任务循环,此时必须由外部 cron 调用 `pnpm jobs:run` | | `AGENT_SERVICE_URL`、`AGENT_INTERNAL_SIGNING_SECRET` | 仅在部署 agent 服务时需要:它的内网地址和双方共用的签名密钥 | 服务商凭据不放在这里,见[管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md)。全部变量见[环境变量](https://kernlift.dev/zh/docs/reference/env.md)。 ## 构建并运行 ### 构建 在检出目录里: ```bash pnpm install pnpm build:node ``` 或者在仓库根目录构建镜像: ```bash docker build -t kernlift-web . ``` ### 应用迁移 设置好 `DATABASE_DIALECT` 和 `DATABASE_URL`,在新版本接收流量之前运行迁移器: ```bash node scripts/db/migrate-runtime.mjs ``` 它的记账表与 `pnpm db:migrate` 相同,两者可以用在同一个数据库上。 ### 启动服务 ```bash node .output/server/index.mjs ``` 这也是镜像的默认命令。定时任务随进程启动,每分钟执行一轮。有多个副本时,配置表里的一行锁保证每轮只有一个副本执行。 ### 创建管理员 在与服务相同的环境里: ```bash node .output/scripts/bootstrap-super-admin.mjs ``` 它会提示输入邮箱和密码,密码不回显。没有终端时,改为在环境里设置 `SUPER_ADMIN_EMAIL` 和 `SUPER_ADMIN_PASSWORD`。 ### 配置运行时服务 登录后打开 `/setup`。在 `/admin/config/storage` 填写 S3 兼容凭据。存储桶绑定驱动只存在于 Cloudflare。`/admin/config/cache` 的后端是进程内存,每个进程各有一份缓存。见[配置文件存储与上传](https://kernlift.dev/zh/docs/extensions/storage.md)和[缓存](https://kernlift.dev/zh/docs/core/admin/cache.md)。 ## 验证 * `/setup` 上**会话密钥**和**定时任务**为就绪;后者在首次启动后需要一两分钟。 * 在仓库里,`pnpm build:node` 之后的 `pnpm smoke:node` 会用一次性的 SQLite 数据库启动这个构建,检查页面能渲染、没有 agent 服务时 agent 接口返回 503、并且记录了一轮定时任务。 * `pnpm validate:deploy-targets` 检查镜像运行的是 Node 构建,并带有迁移文件和迁移器。 ## 故障排查 ### `.output/server/index.mjs is missing` 上一次构建是 Cloudflare 构建,产物在 `dist/`。运行 `pnpm build:node`。 ### `DATABASE_URL is required when DATABASE_ADAPTER=postgres` `DATABASE_DIALECT` 是 `postgres`,但 `DATABASE_URL` 为空。设置连接串。 ### 服务因会话密钥错误拒绝启动 `APP_ENV` 不是 `development`,且 `BETTER_AUTH_SECRET` 缺失或仍是模板默认值。设置生成的值。 ### `/setup` 上定时任务一直未就绪 Web 进程没在运行,或者设置了 `JOBS_IN_PROCESS=false` 但没有任何程序调用 `pnpm jobs:run`。 ## 下一步 - [部署到 Fly.io](https://kernlift.dev/zh/docs/deploy/fly.md) - [部署到 Railway](https://kernlift.dev/zh/docs/deploy/railway.md) - [用 Docker Compose 部署](https://kernlift.dev/zh/docs/deploy/docker.md) - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) --- # 部署到 Railway > 由 .railway/railway.ts 创建 Railway 项目、服务和 Postgres,写入生成的密钥,部署,并创建线上管理员。 Source: https://kernlift.dev/zh/docs/deploy/railway 在 Railway 上,项目是一个由根目录 `Dockerfile` 构建的 `web` 服务和一个 Postgres 数据库,两者都声明在 `.railway/railway.ts` 里。agent 服务可选,作为名为 `agent` 的第二个服务运行。首次生产部署时使用本指南。 ## 准备工作 * `railway` CLI 已登录(`railway login`)。 * `deploy.config.json` 中是 `"platform": "railway"`。执行 `pnpm kernlift deploy-target railway` 来设置,需要 agent 服务时加上 `--agent`。见 [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 * 项目根目录有 `.railway/railway.ts` 和 `.env.production`,这条命令会写出它们。 Railway 项目使用 Postgres。不需要事先准备数据库。配置里声明了一个,并把它的 `DATABASE_URL` 传给各个服务。 ## 创建项目 `kernlift deploy-target railway` 会按你的项目打印这两步。 ### 创建 Railway 项目 ```bash railway init --name my-saas ``` ### 应用配置 ```bash railway config apply --yes ``` 它创建 `web` 服务、Postgres 数据库,以及包含 agent 时的 `agent` 服务。`railway config plan` 只展示变更,不执行。 ## 写入密钥并部署 ### 设置公网地址 在 `.env.production` 里,把 `SITE_URL` 设为 `web` 服务的公网地址:你自己的域名,或 Railway 分配的域名。 ### 给 web 服务设置变量 每个值都从 `.env.production` 读取,不需要在命令行里输入。 ```bash railway variables --service web --set "BETTER_AUTH_SECRET=$(grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2-)" railway variables --service web --set "CONFIG_ENCRYPTION_KEY=$(grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2-)" railway variables --service web --set "SITE_URL=$(grep '^SITE_URL=' .env.production | cut -d= -f2-)" ``` 密钥只用这种方式设置,不要写进 `.railway/railway.ts`。 ### 部署 ```bash railway up ``` `pnpm run deploy` 执行的是同一条命令。`web` 服务的 pre-deploy 步骤执行 `node scripts/db/migrate-runtime.mjs`,所以迁移在新版本接收流量之前完成。 ### 创建线上管理员 在 web 服务里打开 shell: ```bash railway ssh --service web ``` 然后运行镜像自带的脚本,它会提示输入邮箱和密码: ```bash node .output/scripts/bootstrap-super-admin.mjs ``` **定时任务需要 web 服务在运行** 定时任务运行在 `web` 服务里。服务不在运行时,履约重试和 AI 任务轮询都不会执行,直到服务恢复运行。 ## 加上 agent 服务 项目不含 agent 时跳过本节。`"agent": true` 时,`.railway/railway.ts` 声明一个单副本的 `agent` 服务,由 `apps/agent-service/Dockerfile` 构建,并把 web 服务指向 `http://agent.railway.internal:3001`。 ### 设置 agent 密钥 ```bash railway variables --service web --set "AGENT_INTERNAL_SIGNING_SECRET=$(grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2-)" railway variables --service agent --set "AGENT_INTERNAL_SIGNING_SECRET=$(grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2-)" railway variables --service agent --set "AGENT_RESOURCE_GRANT_SECRET=$(grep '^AGENT_RESOURCE_GRANT_SECRET=' .env.production | cut -d= -f2-)" ``` ### 部署 ```bash railway up ``` ## 验证 * 站点可以在 `web` 服务的公网地址打开。 * 以管理员身份打开 `/setup`,第一行写明 Railway 和 Postgres,**会话密钥**为就绪。 * `/admin/config/auth` 里的 **基础 URL** 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。 * **定时任务**在一两分钟内变为就绪。 * 包含 agent 时,`/app/agent` 打开工作台。 * 在仓库里,`pnpm build:node` 之后的 `pnpm smoke:node` 检查你要发布的构建,`pnpm validate:deploy-targets` 检查渲染出的 `.railway/railway.ts`。 ## 故障排查 ### web 服务因会话密钥错误拒绝启动 `web` 服务上没有设置 `BETTER_AUTH_SECRET`。重新执行 `railway variables` 命令并再次部署。 ### OAuth 登录或邮件链接指向了错误的地址 `/admin/config/auth` 里的 **基础 URL** 与公网地址不一致。在那里改正即可,不需要重新部署。 ### `/setup` 上定时任务一直未就绪 检查 `web` 服务是否在运行。如果设置了 `JOBS_IN_PROCESS=false`,就必须由外部 cron 执行 `pnpm jobs:run`。 ### TypeScript 在 `.railway/railway.ts` 里报错 该文件以 `@ts-nocheck` 开头,因为它由 `railway` CLI 检查,本项目不检查它。保留这一行。 ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) - [运行 Node 构建](https://kernlift.dev/zh/docs/deploy/node.md) - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md) --- # 部署模型 > 一个项目一个平台、两种构建目标、每个平台允许的数据库与 agent 组合、密钥放在哪里、迁移何时执行,以及定时任务如何启动。 Source: https://kernlift.dev/zh/docs/deploy/runtimes 一个项目只部署到一个平台:Cloudflare、Fly.io、Railway 或 Docker 主机。这个选择保存在提交到仓库的 文件 `deploy.config.json` 中。它决定执行哪种构建、仓库里有哪个平台的文件、可以用哪些数据库、 迁移和定时任务如何启动。路由、守卫、仓储和校验器在所有平台上都一样。具体步骤见 [部署项目](https://kernlift.dev/zh/docs/deploy.md)。 ## 一个项目一个平台 ```json title="deploy.config.json" { "platform": "cloudflare", "agent": false, "database": "d1" } ``` 这个文件已经提交在你克隆的仓库里,由 `kernlift deploy-target <platform>` 改写。文件里 没有任何密钥。构建读取它来选择目标,应用也会把它打包进去,所以线上的 `/setup` 显示的就是这次构建 对应的平台、数据库和 agent 选择。 项目根目录只有所选平台的文件:`wrangler.jsonc`,或 `fly.toml` 与 `fly.agent.toml`,或 `.railway/railway.ts`,或 `compose.yaml`。`package.json` 里的 `deploy` 脚本执行该平台的部署命令。 全部字段和文件见 [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 ## 两种构建目标 | 目标 | 平台 | 服务端入口 | 产物 | 启动方式 | | ------------ | --------------------- | -------------------------- | ---------- | ------------------------------- | | `cloudflare` | Cloudflare | `src/server-entry.ts` | `dist/` | `wrangler deploy` | | `node` | Fly.io、Railway、Docker | `src/server-entry.node.ts` | `.output/` | `node .output/server/index.mjs` | `pnpm build` 根据 `deploy.config.json` 选择目标,所以无论在哪里构建(包括平台的远程构建器),产物 都相同。`pnpm build:cloudflare` 和 `pnpm build:node` 用来显式指定目标。没有这个文件的项目按 Cloudflare 构建。 Worker 入口还带有 Cron Trigger 的处理函数和 agent 容器类。Node 入口两者都没有,它在进程加载时启动 定时任务循环。根目录的 `Dockerfile` 为三个 Node 平台打包 Node 构建,见 [运行 Node 构建](https://kernlift.dev/zh/docs/deploy/node.md)。 ## 平台、数据库与 agent 矩阵 | | Cloudflare | Fly.io | Railway | Docker | | -------------- | --------------------------- | -------------------- | ---------- | -------------------- | | 不含 agent 时的数据库 | D1,或经 Hyperdrive 的 Postgres | Postgres,或挂卷的 SQLite | Postgres | Postgres,或挂卷的 SQLite | | 含 agent 时的数据库 | 经 Hyperdrive 的 Postgres | Postgres | Postgres | Postgres | | agent 服务 | Cloudflare 容器 | `<name>-agent` 应用 | `agent` 服务 | compose 的 `agent` 服务 | | 对象存储 | R2 绑定或 S3 兼容存储 | S3 兼容存储 | S3 兼容存储 | S3 兼容存储 | | 缓存 | KV 或进程内存 | 进程内存 | 进程内存 | 进程内存 | agent 需要一个支持事务、并由 Web 应用和 agent 服务共用的数据库,所以它始终跑在 Postgres 上。SQLite 是单机方案:数据库文件归一台机器所有。D1 只存在于 Cloudflare。表外的组合会被 `kernlift deploy-target` 在写入任何文件之前拒绝。 agent 服务只有一个实例,因为它在内存里持有运行状态。它只能经平台的内网访问。不部署它,Web 应用 依然完整,见 [Agent 运行时](https://kernlift.dev/zh/docs/extensions/agent.md)。 ## 密钥 生产密钥只生成一次,写入 `.env.production`:会话密钥、包含 agent 时的 agent 签名密钥,以及 Docker 上 自带 Postgres 的密码。文件权限为 0600,被 git 和 Docker 构建上下文忽略。再次运行 CLI 只补全缺失的键, 不会轮换已有的值。 这些值再从该文件进入平台的密钥存储:`wrangler secret put`、`fly secrets import`、 `railway variables`,或 `docker compose --env-file .env.production`。命令经标准输入读取它们,所以 密钥不会被打印、不会出现在命令行上,也不会写进提交的文件。服务商凭据不在此列。它们保存在数据库里, 在 `/admin/config/*` 管理。 ## 迁移先于流量 schema 只由迁移链构建,每个平台都在新版本接收请求之前应用迁移。 | 平台 | 由谁应用迁移 | | --------------------- | ---------------------------------------------------- | | Cloudflare + D1 | `pnpm db:migrate:d1:remote`,在 `pnpm run deploy` 之前执行 | | Cloudflare + Postgres | 在检出目录里对 Postgres URL 执行 `pnpm db:migrate` | | Fly.io + Postgres | `fly.toml` 里的 `release_command`,在临时机器上执行 | | Fly.io + SQLite | 应用进程在启动服务之前执行;发布用的临时机器不挂卷 | | Railway | `web` 服务的 `preDeploy` 步骤 | | Docker | compose 的 `migrate` 服务;它成功后 `web` 才启动 | Node 平台执行 `node scripts/db/migrate-runtime.mjs`,它不需要 TypeScript 运行器,记账表与 `pnpm db:migrate` 相同,所以两者可以用在同一个数据库上。 创建线上管理员是单独的一步,因为线上数据库不是本地那个。Node 镜像带有 `node .output/scripts/bootstrap-super-admin.mjs`。Cloudflare 在检出目录里执行 `pnpm db:bootstrap-super-admin`,D1 加上 `--remote`。 ## 定时任务 后台工作通过 `runScheduledJobs()` 每分钟执行一轮:履约重试、积分过期和未完成的 AI 任务。由谁发起 一轮取决于构建目标。 * **Cloudflare**:`wrangler.jsonc` 里每分钟一次的 Cron Trigger 调用 Worker 的 `scheduled` 处理函数。 * **Fly.io、Railway、Docker**:Web 进程内的循环。每个副本都跑这个循环,配置表里的一行锁保证每轮 只有一个副本执行。不需要单独的任务进程,也不配置平台 cron。 Web 进程停止后不会执行任何任务,所以 `fly.toml` 保留 `min_machines_running = 1`。设置 `JOBS_IN_PROCESS=false` 会关闭循环,此时必须由外部 cron 调用 `pnpm jobs:run`。 每一轮都会记录执行时间。超过五分钟没有新的一轮,或上一轮有失败的任务时,`/setup` 把**定时任务** 显示为未就绪,并指出所在平台的开关。 ## 切换平台做了什么 `kernlift deploy-target <platform>` 用 CLI 自带的模板重新渲染部署配置。它改写 `deploy.config.json`, 写入新平台的文件,把 `deploy` 脚本指向新平台,并把缺失的键补进 `.env.production`。原平台的文件移到 `.kernlift/previous-deploy/`。不删除任何文件,那里已有的副本也不会被覆盖。 切换只是文件操作。它不创建远程资源,不影响正在运行的部署,也不搬数据。下一次 `pnpm build` 跟随新的 目标。参数见 [部署配置参考](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 ## 本地开发 本地开发在所有平台下都一样:`pnpm dev`,使用一个 SQLite 文件。生产用 Postgres 的项目,本地仍然用 SQLite 开发。 ```bash DATABASE_DIALECT=sqlite DATABASE_URL=./local.db ``` ```bash pnpm db:migrate SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin pnpm dev ``` 引导步骤创建第一位管理员、权限集合与超级管理员角色,并写入运营基线内容。没有演示数据,外部服务商的 成功绝不伪造。 ## 数据库适配器 schema 分为 SQLite 和 Postgres 两个家族,每个仓储都针对两者编写。`DATABASE_DIALECT` 决定家族。 `DATABASE_ADAPTER` 决定如何连接,默认等于方言。 | 适配器 | 方言 | 用在哪里 | 配置 | | ------------ | ---------- | -------------------------------- | ------------------------------------------------------------- | | `sqlite` | `sqlite` | 本地开发,Fly.io 与 Docker 的挂卷方案 | `DATABASE_URL` 是文件路径 | | `d1` | `d1` | Cloudflare | `EDGE_DB` 绑定 | | `postgres` | `postgres` | Fly.io、Railway、Docker、任意 Node 主机 | `DATABASE_URL=postgresql://...` | | `hyperdrive` | `postgres` | 使用 Postgres 的 Cloudflare | `DATABASE_ADAPTER=hyperdrive` 与 `HYPERDRIVE` 绑定 | | `turso` | `sqlite` | 使用 libSQL 的 Node 主机 | `DATABASE_ADAPTER=turso`、`DATABASE_URL`、`DATABASE_AUTH_TOKEN` | Worker 不能复用为另一个请求打开的 socket,所以 `hyperdrive` 适配器为每个请求创建 Postgres 客户端, 连接池交给 Hyperdrive。项目可以注册自己的适配器,见 [编写自定义数据库适配器](https://kernlift.dev/zh/docs/extensions/database/custom-adapter.md)。 ### Supabase 托管 Postgres Supabase 和 Neon 都是托管的 Postgres 端点,走通用 Drizzle Postgres 适配器。应用不把 Supabase 专有的 API、客户端 SDK、认证助手、存储 API 或 RLS 作为业务依赖。授权始终留在服务端的认证、RBAC 和仓储层。 ```bash DATABASE_DIALECT=postgres DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgres ``` 见[使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md)和 [使用 Turso](https://kernlift.dev/zh/docs/extensions/database/turso.md)。 ### Cloudflare Workers 与 D1 `wrangler.jsonc` 定义了 Worker 入口 `src/server-entry.ts`、D1 绑定 `EDGE_DB`、`DATABASE_DIALECT=d1`, 以及 D1 迁移目录 `./drizzle/migrations/sqlite`。D1 属于 SQLite schema 家族,所以应用与本地 SQLite 相同的迁移。D1 没有交互式事务,开启事务的代码在那里改为依次执行各条语句。 ### 变更 schema schema 变更需要在两种方言下各有一条匹配的迁移: ```bash pnpm db:generate:sqlite --name=my-change pnpm db:generate:postgres --name=my-change pnpm validate:migrations ``` `pnpm db:generate:sqlite` 写入 `drizzle/migrations/sqlite`,`pnpm db:generate:postgres` 写入 `drizzle/migrations/postgres`。两个目录从不共享。`pnpm db:generate` 为 schema 的差异写出一条新迁移,不用于准备数据库。 ## 基于 S3 兼容协议的存储 上传、删除和签名 URL 通过 S3 兼容协议完成,使用 `/admin/config/storage` 中后台管理的 S3 兼容配置: 端点、区域、存储桶、访问密钥、私密密钥、可选的 CDN 或公开访问域名,以及图片/视频/音频/文件上传的 MIME 类别。Cloudflare R2、阿里云 OSS、MinIO、AWS S3 等服务商共用这条路径。 存储凭据是后台设置,不放在环境变量里,所以每个平台都以相同方式配置存储。在 Cloudflare 上,存储桶绑定 是同一存储接口后面的第二种驱动。其它平台没有绑定,使用 S3 兼容凭据。 ## 外部服务商验证 本地验证覆盖状态机和缺少服务商时的失败路径。真实服务商检查需要沙箱或生产凭据: ```bash pnpm validate:external-readiness EXTERNAL_VALIDATE_STRICT=true pnpm validate:external ``` 就绪报告写入 `openspec/EXTERNAL_VALIDATION_STATUS.json`。有意保留未完成的 OpenSpec `3.3` 任务是 `auth-account 3.3`、`billing-payment 3.3`、`analytics-support 3.3`、`ai-workspace 3.3` 和 `newsletter-waitlist 3.3`,在配置真实的 Google OAuth、支付、分析、AI 和邮件订阅凭据之前保持未勾选。 ## 发布护栏 * 发布前运行 `pnpm validate:all`。 * 修改部署模板或 Dockerfile 后运行 `pnpm validate:deploy-targets`。 * 修改 Drizzle schema 或迁移文件后运行 `pnpm validate:migrations`。 * 部署前运行 `pnpm build`,再对要发布的构建做冒烟检查:Cloudflare 在 `pnpm build` 之后运行 `pnpm smoke:worker`,其它平台在 `pnpm build:node` 之后运行 `pnpm smoke:node`。 * SQLite/D1 迁移放在 `drizzle/migrations/sqlite`,Postgres 迁移放在 `drizzle/migrations/postgres`。 * 把 `A32-A34` 与 `A82-A98` 排除在路由和设计生成输入之外。 * 保持 `/zh` 路由对等。 * 不添加 mock 服务商,也不伪造服务商 id、结账 URL、提现成功、邮件 id、AI 输出或分析报表。 ## 相关文件 - 部署选择/ - deploy.config.json - vite.config.ts - src/server/platform/deployment.ts - 构建目标/ - src/server-entry.ts - src/server-entry.node.ts - Dockerfile - apps/agent-service/Dockerfile - 平台模板与步骤/ - tools/kernlift/src/deploy/render.js - tools/kernlift/src/deploy/templates.js - tools/kernlift/src/deploy/platforms.js - tools/kernlift/src/deploy/secrets.js - 迁移与管理员/ - scripts/db/migrate-runtime.mjs - scripts/db/bootstrap-super-admin.ts - scripts/db/bootstrap-super-admin.runtime.ts - 定时任务/ - src/server/jobs/scheduled.ts - src/server/jobs/in-process.ts - src/server/jobs/heartbeat.ts - 适配器与绑定/ - src/server/db/client.ts - src/server/db/adapter-registry.ts - src/server/platform/cache-backends.ts - src/server/platform/storage-drivers.ts ## 下一步 - [部署项目](https://kernlift.dev/zh/docs/deploy.md) - [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md) - [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md) - [运行 Node 构建](https://kernlift.dev/zh/docs/deploy/node.md) - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) --- # 运营联盟推广计划 > 在管理后台设置计划条款、为推广者发放推荐码、把推广订单转成佣金并审核提现。 Source: https://kernlift.dev/zh/docs/extensions/affiliate 联盟推广模块为推广者发放推荐码,把他们带来的订单转成佣金,并记录你对每笔提现申请的决定。提现由人工审核,模块不会实际转账。 ## 准备工作 * 一个能在本地运行的项目,见[快速开始](https://kernlift.dev/zh/docs/quick-start.md)。`affiliate` 模块已经在底座仓库里;`pnpm db:bootstrap-super-admin` 会写入 `affiliates.read`、`affiliates.write` 权限和默认推广计划。 * 管理员账号:`affiliates.read` 用于打开页面,提交任何表单还需要 `affiliates.write`。 * 推广者的用户 ID,即其 `/admin/users/<id>` 地址的最后一段。 侧边栏没有推广入口,请直接访问 `/zh/admin/affiliates`(英文后台为 `/admin/affiliates`)。 ## 授予推广权限 ### 分配 Commerce Manager 角色 进入 **概览 → 用户**(`/admin/users/dashboard`),打开用户详情,点击 **角色**,勾选 **Commerce Manager** 后点击 **保存角色**。该角色还包含订单、订阅、产品、授权和积分权限。 ### 或者把权限加到自己的角色 进入 **运营 → 角色**(`/admin/roles`),在角色上点击 **编辑**,在 **权限** 的 **Other** 分组中勾选 `affiliates.read` 和 `affiliates.write`,点击 **保存角色**。 ## 设置计划条款 默认计划:佣金 20%,Cookie 窗口 30 天,最低提现 $50.00,币种 USD。 ### 打开计划设置 打开 **计划设置** 标签页(`/zh/admin/affiliates/settings`),卡片中显示当前条款。 ### 填写计划条款 * **佣金比例 (%)**:按订单金额计算佣金的比例,例如 `20`,不能超过 100%。 * **Cookie 窗口 (天)**:1 到 365。只有在推荐创建后的这些天数内才能记录转化。 * **最低提现金额**:可接受的最小提现申请金额,例如 `50.00`。 * **币种**:三位字母的 ISO 4217 代码,例如 `USD`。 * **状态**:**进行中**,或 **已暂停**(不再记录转化,也不接受提现申请)。 ### 保存 点击 **保存计划设置**,页面显示 **计划设置已保存并记录审计日志。** 新条款作用于之后的转化和提现申请,已记录的佣金金额不变。 ## 创建推荐码 ### 找到创建推荐表单 在 **总览** 或 **推荐** 标签页找到 **创建推荐** 表单。 ### 填写表单 * **推广用户**:推广者的用户 ID。 * **推荐码**:推广者对外分享的码。保存时会转成大写并把空格换成连字符,`partner acme` 会保存为 `PARTNER-ACME`。 * **被推荐邮箱**:可选。 点击 **创建推荐**。推荐码已存在时会保留原记录,且不报错。 ## 记录转化 结账流程不会自动把订单归因到推荐码,所以需要逐笔记录推广订单。 ### 确认订单已支付 在 **商业化 → 订单**(`/admin/orders`)中查看该订单。 ### 填写记录转化 在 **佣金** 或 **总览** 标签页填写 **推荐码**、**订单 ID** 和 **订单金额 cents**($290.00 填 `29000`),点击 **记录转化**。 佣金按订单金额乘以计划比例向下取整,初始状态为待审核。 如果想自动归因,在服务商 Webhook 确认订单后,从你的结算代码调用服务: ```ts title="src/server/services/example.service.ts" import { recordConversion } from "@/server/services/affiliate-operations.service"; await recordConversion({ referralCode: "PARTNER-ACME", orderId: order.id, orderAmountCents: order.amountCents, }); ``` ## 审核提现 提现申请显示在 **提现** 标签页。后台没有创建提现申请的页面,提现申请由你自己的服务端代码创建。 ### 找到提现 ID 从 **提现** 标签页表格的 **提现** 列复制。 ### 做出决定 进入 **审核** 标签页,填写 **提现 ID** 和 **审核备注**,点击 **批准提现** 或 **拒绝提现**。保存时审核人记为你。 ### 给推广者打款 通过你自己的支付渠道打款。模块只记录审核决定。 ## 验证 1. 用你自己的用户 ID 和推荐码 `TEST-PARTNER` 创建一个推荐。 2. 为 `TEST-PARTNER` 记录一笔转化,**订单金额 cents** 填 `30000`。 3. 按默认 20% 比例,**佣金** 出现一笔 $60.00 的待审核佣金,**推荐** 中该推荐显示为已转化,**安全 → 审计**(`/admin/audit`)记录了这两次操作。 在仓库中运行 `pnpm validate:affiliate`。 ## 常见问题 ### 出现 "Affiliate program is not configured",或页面显示「暂无 Affiliate 记录」 推广计划还不存在。运行 `pnpm db:seed-baseline` 创建默认计划;再次运行不会覆盖你的设置。 ### 出现 "Referral code is not active" 没有使用该推荐码的推荐。比对前推荐码会去空白、转大写、空格改连字符,请在 **推荐** 标签页核对。 ### 出现 "Affiliate program is paused; …" **计划设置** 中的 **状态** 为 **已暂停**。改为 **进行中** 并保存。 ### 出现 "Conversion is outside the N-day attribution window for this referral." 推荐创建时间已超过 **Cookie 窗口 (天)**。请使用较新的推荐,或调大 Cookie 窗口。 ### 出现 "Payout amount is below the program minimum of N cents." 申请金额至少要达到 **最低提现金额**,或在 **计划设置** 中调低最低金额。 ## 参考 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) * [Drizzle ORM](https://orm.drizzle.team) ## 下一步 - [插件](https://kernlift.dev/zh/docs/core/plugins.md) - [管理订单、退款与订阅](https://kernlift.dev/zh/docs/extensions/payments/subscriptions.md) - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) --- # 阿里云沙箱 > 为 Agent 接入 阿里云沙箱。 Source: https://kernlift.dev/zh/docs/extensions/agent/aliyun ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,工作台可在实际任务中调用该服务。 ## 在 阿里云沙箱 完成准备 ### 开通云沙箱 打开 [阿里云沙箱](https://help.aliyun.com/zh/agent-sandbox/build-and-manage-custom-templates-with-code/)。在账号中开通兼容 E2B 的沙箱服务。 ### 准备运行器镜像 获取对应地域的 API URL、密钥和兼容项目运行器镜像的模板 ID。 ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/sandbox`。 | 来源 | 后台字段 | | --------------- | ---------------- | | API key | Provider API Key | | Control plane | 控制面 API URL | | Runner template | 不可变模板 ID | 启用对应服务,填写连接信息并保存。 <img src="/docs/guides/agent/template.zh.png" alt="后台的运行器模板配置" width="512" height="1283" loading="lazy" /> ## 验证 1. 保存后查看沙箱就绪状态。 2. 在工作台运行使用脚本工具的任务,确认实际执行并产生产物。 ## 常见问题 ### 脚本类工具提示沙箱未配置 `/admin/config/sandbox` 未启用或缺少密钥。这里没有环境变量兜底,只能在该页面保存密钥。 ## 下一步 [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) --- # Crawl4AI > 为 Agent 接入 Crawl4AI。 Source: https://kernlift.dev/zh/docs/extensions/agent/crawl4ai ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,工作台可在实际任务中调用该服务。 ## 在 Crawl4AI 完成准备 ### 启动 API 服务 打开 [Crawl4AI](https://docs.crawl4ai.com/core/self-hosting/)。部署 Crawl4AI Docker API 服务。 ### 验证抓取结果 使用 API 抓取公开测试页,确认响应中含有网页正文。 官方说明 · [官方自托管说明](https://docs.crawl4ai.com/core/self-hosting/) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/search`。 | 来源 | 后台字段 | | ----------- | -------- | | Service URL | Base URL | 启用对应服务,填写连接信息并保存。 <img src="/docs/guides/agent/crawl4ai.zh.png" alt="Kernlift 后台的 Crawl4AI 配置字段" width="512" height="942" loading="lazy" /> ## 验证 1. 在该服务面板点击 **测试连接**。 2. 在工作台执行检索或网页提取,核对返回的内容。 ## 常见问题 ### 连接失败 从 Agent 服务所在网络测试配置的地址。若通过代理鉴权,核对后台配置的请求头和值。 ## 下一步 [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) --- # E2B > 为 Agent 接入 E2B。 Source: https://kernlift.dev/zh/docs/extensions/agent/e2b ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,工作台可在实际任务中调用该服务。 ## 在 E2B 完成准备 ### 创建沙箱密钥 打开 [E2B](https://e2b.dev/dashboard)。创建沙箱 API Key。 ### 构建运行器模板 使用 `pnpm --filter @workspace/sandbox-adapter build:runner-template` 从项目的 Dockerfile 构建运行器,记下模板名。 官方说明 · [E2B 模板文档](https://e2b.dev/docs) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/sandbox`。 | 来源 | 后台字段 | | --------------- | ---------------- | | API key | Provider API Key | | Runner template | 不可变模板 ID | 启用对应服务,填写连接信息并保存。 <img src="/docs/guides/agent/template.zh.png" alt="后台的运行器模板配置" width="512" height="1283" loading="lazy" /> ## 验证 1. 保存后查看沙箱就绪状态。 2. 在工作台运行使用脚本工具的任务,确认实际执行并产生产物。 ## 常见问题 ### 脚本类工具提示沙箱未配置 `/admin/config/sandbox` 未启用或缺少密钥。这里没有环境变量兜底,只能在该页面保存密钥。 ## 下一步 [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) --- # 图片 Agent > 为用户后台加入图片页面:请求在 agent 运行时上执行图片 Skill,使用用户选择的画幅,并受你设置的每次运行出图上限约束。 Source: https://kernlift.dev/zh/docs/extensions/agent/image-agent 图片 Agent 是 [Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)之上的插件。它在 `/app/agent` 工作台的输入框里加入 **图片** agent(交给它的消息运行 **Image Studio** Skill)、composer 旁边的画幅选择、图片 artifact 查看器,以及管理后台 `/admin/config/image-agent` 的 **图片 Agent** 设置页。侧边栏的 **图片** 入口(`/app/image`)是一个快捷方式,打开工作台并预先选好这个 agent。它不新增 Tool 和数据表。图片由 `model.generate` 在平台的图片场景上生成。 ## 准备工作 * 已安装 Agent 启动模板并部署了 agent 服务:按其指南为 `agent.general` 配好模型并配置沙箱。没有 agent 服务时,**图片** 入口会被隐藏。 * 已接好图片服务商,`image-creation` 任务能够完成。参见[跑通图片和视频生成](https://kernlift.dev/zh/docs/extensions/ai/media-generation.md)。 * `image-agent` 插件,它已经在仓库里,依赖 `agent-starter`。可以在 **设置 → 插件**(`/admin/plugins`)里看到它。 * 管理员账号:`config.read` 用于打开设置页,保存还需要 `config.write`。 ## 配置两个场景 图片 Agent 使用两个场景,都在 **设置 → AI 配置**(`/admin/config/ai`)中按普通场景配置,参见 [AI 场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)。 | 场景 | 媒体类型 | 用途 | | ---------------- | ---- | -------------------------------------- | | `agent.image` | 文本 | 图片运行的 agent 循环,需要一个带模型的 OpenAI 兼容对话路由。 | | `image-creation` | 图片 | 生成图片本身,价格在这条路由上设置。 | `agent.image` 不影响 agent 服务的就绪状态。缺少它时,工作台的其他功能照常可用,只有图片页面会提示缺少什么。 Skill 还会调用 `image-editing` 修改已有图片,调用 `image-understanding` 查看图片。需要改图和视觉检查时,也要为这两个场景配置路由。在 `image-creation` 或 `image-editing` 上生成的图片计入每次运行的张数上限,查看图片不计入。 ## 发布 Skill 运行从 Skill 注册表加载 Skill,不从磁盘读取。Skill 位于 `src/plugins/image-agent/skills/image-studio`,与平台 Skill 一起发布: ```bash pnpm agent:publish-skills ``` 部署时会执行同一步骤,只有内容变化时才发布新的 `platform.image` 版本。 ## 检查就绪状态并设置上限 ### 打开设置页 进入 **设置 → 图片 Agent**(`/admin/config/image-agent`)。**就绪状态** 列出 `agent.image` 路由、`image-creation` 路由和 Skill 发布情况,每项显示 **就绪** 或 **缺少**。 ### 设置每次运行的出图张数 在 **每次运行的出图张数** 中填写 1 到 32(默认 8),点击 **保存**。超过这个数量的生成会在到达供应商之前被拒绝,模型会收到停止生成并发布已有结果的指示。 ## 使用图片 agent 在用户后台侧边栏打开 **图片**。工作台会在 `/app/agent` 打开,agent 选择器里已选中 **图片**;也可以在那里自己选。选择画幅(1:1、3:4、4:3、9:16 或 16:9),然后描述想要的图片。画幅随消息一起保存,重试旧消息时画幅不变,同一线程的下一次运行也会沿用。某次生成自己指定了画幅时,以它为准。 选择器停在 **自动** 时,明确要求出图的请求(如「画一张……」「generate an image of…」)会路由到同一个 Skill,工作台在这个线程的后续消息里切换到图片 agent。每张发布的图片既显示在消息里,也可以在面板中打开。 ## 验证 1. 在 `/admin/config/image-agent`,三项 **就绪状态** 都显示 **就绪**。 2. 打开 `/app/image`,页面会进入 `/app/agent` 并选中 **图片**。选择 **16:9**,发送「一张黎明时分山间湖泊的宽幅横幅」。 3. 运行会生成并发布图片,面板用图片查看器打开最后一张,并显示像素尺寸。 4. 把 **每次运行的出图张数** 设为 1 再发一次请求。第二次生成会被拒绝,回复中会说明额度已用完。 在仓库中,`pnpm validate:image-agent` 会在不调用供应商的情况下检查路由、画幅固定、出图上限和接线。 ## 常见问题 ### 图片页面提示图片生成还未就绪 每一行都写明缺少什么。`agent.image` 的路由必须是带模型的 OpenAI 兼容对话路由,只有图片路由不能用于 agent 循环。 ### 看不到图片入口 这个入口需要 agent 服务。服务没有部署、数据库是 D1,或 `agent-starter` 被停用时,它会被隐藏。参见[运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)。 ### 自动模式下请求没有路由到图片 只有明确要求出图的请求才会被路由。在选择器里选中 **图片**,选中后始终运行图片 Skill。 ## 停用 在 **设置 → 插件** 中关闭 **image-agent**。**图片** 和 **图片 Agent** 入口会消失,两个页面返回 not found,它的 server function 会拒绝请求,`agent.image` 上的运行会在启动时被拒绝。关闭 **agent-starter** 时,图片 Agent 会一起停用。 --- # Agent 运行机制 > 可选的 agent 服务如何部署,Web 应用如何判断它是否可用,以及运行、工作区、技能和决策之间的关系。 Source: https://kernlift.dev/zh/docs/extensions/agent Agent 是 Web 应用旁边的一个独立服务,而且是可选的。不部署它时,Web 应用本身是完整的:AI 任务和对话通过 `/app/ai`、`/app/chat` 和 `/api/chat` 直接调用已配置的渠道。部署了服务之后,Web 应用负责用户鉴权和所有权检查,再把签名请求转发给它。服务执行 agent 循环、沙箱和自己的后台工作器。浏览器始终只请求 Web 应用的 `/api/agent/*` 路由。 ## 两个进程,单向信任 `apps/agent-service` 是 `agent-starter` 模板安装的一个 Node 进程。Web 应用通过两种方式之一访问它: | 传输方式 | 适用场景 | 如何配置 | | ----------- | ----------------------------------------- | ----------------------------------------------------- | | `url` | Node 服务器、其他平台上的容器,或本地开发 | Web 应用环境里的 `AGENT_SERVICE_URL` | | `container` | Cloudflare Worker,agent 以 Cloudflare 容器运行 | `wrangler.jsonc` 里的 `AGENT_SERVICE` Durable Object 绑定 | 两种方式发送的是同一份签名请求。`AGENT_INTERNAL_SIGNING_SECRET` 用来认证两个进程之间的请求,`AGENT_RESOURCE_GRANT_SECRET` 用来签发访问存储文件的短期令牌。服务不接收会话、OAuth 和支付相关的变量,环境里出现这类变量时会拒绝启动,因为它要在沙箱里执行不受信任的代码。 在 Cloudflare 上,所有请求都发往同一个命名的容器实例。服务在内存里持有流订阅、进行中的运行和沙箱池,同一次运行的请求必须落到同一个进程。有未完成的运行时,Worker 的 Cron Trigger 会让这个容器执行一轮维护,同时保持它不休眠。 ## 可用性只有一个答案 `getAgentAvailability()` 返回这个部署能否运行 agent。它只读插件状态、环境变量和数据库方言,不加载 agent 运行时,所以后台布局在每次导航时都可以调用。 | 原因 | 含义 | | ---------------------------- | ----------------------------------------------- | | `plugin_disabled` | `agent-starter` 插件在 **设置 → 插件** 中被停用。 | | `database_not_transactional` | 数据库是 Cloudflare D1,没有交互式事务。 | | `service_not_configured` | 既没有 `AGENT_SERVICE_URL`,也没有 `AGENT_SERVICE` 绑定。 | | `signing_secret_missing` | 没有设置 `AGENT_INTERNAL_SIGNING_SECRET`。 | 所有 agent 入口都使用这个结果: * 带 `requires: "agent"` 的导航项被隐藏。 * `/app/agent` 和 `/app/image` 说明 agent 服务没有部署,以及下一步该做什么。 * `/api/agent/*` 返回 `503` 和错误码 `agent_unavailable`。 可用不等于就绪。服务是否有模型路由和沙箱,由下文的就绪检查报告。 ## 数据库必须支持事务 接受一次运行、回答问题、处理审批、领取后台任务,每一项都是必须同时成功的多条语句。因此 agent 仓储在读写任何数据之前,就会拒绝不支持交互式事务的数据库,错误码是 `agent_requires_transactions`。 | 数据库 | Agent | | -------------- | ---------------------------------------------- | | Postgres | 支持。在 Worker 上 Web 应用经 Hyperdrive 连接,容器直连。 | | Node 上的 SQLite | 支持。仓储门面包装了 `better-sqlite3` 连接,让异步事务回调一个接一个执行。 | | Cloudflare D1 | 不支持。Web 应用照常运行,agent 入口不出现。 | ## 运行背后的引擎 `packages/agent-runtime` 用 DeepSeek Harness 的包(`@deepseek-ai/cordis` 和 `@deepseek-ai/dsh-*`)组合出运行循环:agent 循环、以事件日志持久化的会话、上下文压缩、token 计量、旧工具结果裁剪和服务商重试。依赖版本是固定的,其中一个包带有 `patches/` 下的补丁,通过 pnpm 的 `patchedDependencies` 应用。 宿主代码不直接 import 这些包,只依赖 `runtime-contracts.ts` 里面向产品的合约,所以引擎可以在包内部替换,不影响 `src/server` 和 `apps/agent-service`。`pnpm validate:dsh-runtime` 检查版本固定、业务代码没有直接 import 引擎,并运行引擎的合约测试。 Web 的请求路径不会加载运行时。路由通过窄的子路径导出引用运行时的辅助函数,不引用包入口。`pnpm validate:optional-agent` 会检查构建产物。 ## 线程、运行与工作区 线程保存对话历史。运行是回答一条消息的一次尝试。`POST /api/agent/runs` 提交消息、幂等键,以及可选的已有线程、分支或指定技能。每次运行拥有独立工作区。附件和小型工作区文件在模型第一轮之前放入这次运行。后续运行不能读取上一次的工作区。引用旧产物需要显式随新消息传入。 运行会固定主技能、附加能力技能、场景和工具集合。即使 registry 的最新技能版本发生变化,恢复的运行仍使用原来的有效配置。服务解析生效的 AI 场景路由,并通过服务端积分账本结算预留积分。模型、沙箱或存储未配置时会明确报错,不会输出示例结果。一个用户可以同时进行多少次运行,由套餐的 `concurrentAgentTasks` 权益决定。 创建运行的响应和线程快照都带有 `routing`:这次运行落到的场景、主技能和插件。工作台用它跟随被自动路由的请求。 ## 状态与决策 | 状态 | 含义 | 后续动作 | | --------------------------------------------- | --------- | ------------------------------- | | `queued` | 已接受,尚未执行 | 工作器启动;也可能在执行前失败或取消。 | | `running` | 模型与工具正在执行 | 可能完成、失败、中断,或等待用户。 | | `waiting_user` | 运行提出问题 | 所有者回答该次用户请求。 | | `waiting_approval` | 工具动作需要同意 | 所有者批准或拒绝该动作。 | | `completed`、`failed`、`canceled`、`interrupted` | 终态 | 同一次运行不会回到 `running`;继续工作需要新的运行。 | 审批请求带有指纹和策略版本,回应时必须连同决定一起带回,所以不能用旧按钮批准已经变化或过期的动作。用户请求是一个问题,走另一个端点。重连流只是恢复对运行的观察,不会创建第二次运行。取消是发给服务的请求,并不保证已经完成的动作可以撤销。 ## 技能、工具与沙箱 平台技能在源码的 `agent-skills/` 目录里,能力插件的技能放在插件自己的目录里。`pnpm agent:publish-skills` 把它们打包到对象存储和技能 registry。运行时读取已授权的已发布版本,不读取本地文件。运行可以自动选择技能,也可以固定某个已授权的版本。`agent-skills/` 与 `skills/` 相互独立,后者是给编码助手用的工作流。 需要执行代码的工具使用 `/admin/config/sandbox` 配置的沙箱。搜索和抓取工具使用 `/admin/config/search` 配置的服务。连接器动作需要各自的账号授权。资源预览和下载使用按所有者签发的短期授权,存储的产物不会变成公开地址。 核心之外的能力(例如图片 agent)是同一个工作台的插件。它们声明场景、技能、卡片和操作,由宿主校验,并随插件一起停用。见[插件](https://kernlift.dev/zh/docs/core/plugins.md)和 [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md)。 ## 就绪与失败边界 Agent 服务的 `GET /healthz` 报告进程是否存活。`GET /readyz` 检查数据库可达、schema 版本、对象存储和可用的服务商配置,任何一项必需检查未就绪时返回 `503`。`/app/agent` 的输入框有自己更窄的检查:一条生效的 `agent.general` 文本路由及其引用的密钥,加上已配置的沙箱。搜索和抓取只在用到它们的工具里才需要。就绪检查不会模拟调用服务商。 Web 应用自己的后台工作(履约重试、未完成的 AI 任务)在 Web 应用的定时任务里执行,不在 agent 服务的循环里,所以没有 agent 也照常进行。见[后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md)。 ## 相关文件 - Web 应用一侧/ - src/server/agent-host/availability.ts - src/server/agent-host/repository.ts - src/server/services/agent-api-bridge.service.ts - src/server/services/agent-route-readiness.service.ts - src/server/platform/agent-service-container.ts - Agent 服务/ - apps/agent-service/src/main.ts - apps/agent-service/src/server.ts - apps/agent-service/Dockerfile - 运行时与合约/ - packages/agent-runtime/src/runtime.ts - packages/agent-runtime/src/runtime-contracts.ts - packages/agent-contracts/src/run.ts - packages/agent-contracts/src/api.ts - 校验/ - scripts/validate/optional-agent.ts - scripts/validate/dsh-runtime.ts - scripts/validate/sqlite-transactions.ts ## 下一步 * [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md):配置、启动与检查。 * [插件](https://kernlift.dev/zh/docs/core/plugins.md):agent 能力如何安装、启用和停用。 * [积分](https://kernlift.dev/zh/docs/extensions/credits.md):预留与结算。 --- # Novita Sandbox > 为 Agent 接入 Novita Sandbox。 Source: https://kernlift.dev/zh/docs/extensions/agent/novita ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,工作台可在实际任务中调用该服务。 ## 在 Novita Sandbox 完成准备 ### 开通沙箱 打开 [Novita Sandbox](https://novita.ai/docs/guides/sandbox-template)。在 Novita 账号中开通沙箱。 ### 选择运行器模板 获取同一账号下的控制面地址、API Key 和兼容项目运行器的模板 ID。 ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/sandbox`。 | 来源 | 后台字段 | | --------------- | ---------------- | | API key | Provider API Key | | Control plane | 控制面 API URL | | Runner template | 不可变模板 ID | 启用对应服务,填写连接信息并保存。 <img src="/docs/guides/agent/template.zh.png" alt="后台的运行器模板配置" width="512" height="1283" loading="lazy" /> ## 验证 1. 保存后查看沙箱就绪状态。 2. 在工作台运行使用脚本工具的任务,确认实际执行并产生产物。 ## 常见问题 ### 脚本类工具提示沙箱未配置 `/admin/config/sandbox` 未启用或缺少密钥。这里没有环境变量兜底,只能在该页面保存密钥。 ## 下一步 [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) --- # Agent 插件 > 把一项 agent 能力做成插件:接入唯一的工作台输入框,带上自己的卡片、面板和操作,运行时随时启停,宿主不用改代码。 Source: https://kernlift.dev/zh/docs/extensions/agent/plugins 一个 agent 插件就是 `src/plugins/<id>/` 下的一个目录,有两个入口:给 agent 宿主的 `plugin.server.ts` 和给浏览器的 `plugin.ts`。宿主代码里不出现任何插件名。它读取每个已启用插件声明的内容(场景、Skill、卡片、面板、操作),并在内容展示给读者之前逐项校验。它是[插件](https://kernlift.dev/zh/docs/core/plugins.md)一文所说的后台内核里的一个插件,`kind` 为 `"agent"`。[图片 Agent](https://kernlift.dev/zh/docs/extensions/agent/image-agent.md) 是一个小插件。`scripts/validate/fixtures/agent-plugin-fixture` 是用到全部接入点的参考插件,校验器会实际运行它。 ## 准备工作 * 已安装并能运行 [Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)。 * 为插件建一个 OpenSpec 变更:`openspec-cn new change "<id>-plugin"`。 * 想好插件 id:小写短横线形式,同时也是它的模块 key。插件声明的所有 key 都以它开头。 ## 读者看到什么 只有一个工作台 `/app/agent`、一个输入框。输入框旁的选择器列出 **自动**、**通用** 和所有已启用的 agent 插件。 * 选中某个 agent,输入框换上它的附加控件,已输入的文字保留。选择随消息保存,重试旧消息时仍交给当时的 agent。 * 选 **自动** 时由服务端路由。创建 Run 的响应和线程快照会给出这个 Run 所属的插件,工作台切换到该插件,并在本线程后续沿用。 * 插件的卡片在消息流里渲染,它的工作区作为面板 tab 打开。一个线程里可以有多个插件的 Run。 * 在 **设置 → 插件** 中停用插件后,页面重新获得焦点时它从选择器消失,新的 Run 和操作被拒绝,旧卡片显示摘要。重新启用后恢复。 像 `/app/image` 这样的插件页面,是预先选好该 agent 的工作台快捷入口。 ## 选择接入点 只声明插件需要的部分。 | 插件需要 | 声明 | 位置 | | ---------------- | ---------------------------------------------------- | --- | | 被选中和被路由到 | `scenes`、`capabilityRoutes`(按文字、文件类型或两者)、`skills` | 服务端 | | 自己的输入框控件和空线程引导 | `agent`,capability 按需加载 | 浏览器 | | 在消息流里放结构化、可交互的内容 | `cards`(payload schema)/ `cardRenderers` | 两侧 | | 在线程旁打开面板 | `surfaces` / `surfaces` | 两侧 | | 让读者不经模型直接操作 | `operations`(输入、Run 状态、超时) | 服务端 | | 把确认绑定到读者看到的内容 | `validateUserAnswer`(守卫、审批凭据) | 服务端 | | 由服务端决定 Run 级策略 | `hostPinnedContext` | 服务端 | | 保存自己类型的成品 | `artifactKinds` / `artifactRenderers`(`<id>.<kind>`) | 两侧 | | 通过 HTTP 提供下载或预览 | `/api/plugins/<id>/` 下的 `api.routes` | 服务端 | ## 每个插件都要遵守的规则 1. **key 带命名空间。** 卡片、面板、操作和 artifact 类型的 key 都是 `<id>.<name>`。注册表会拒绝别的插件的前缀、重复的 key,以及 `<id>.workspace`,这个 key 留给宿主打开插件的工作区。 2. **两侧都校验。** payload 和输入的 schema 写在插件的 `contracts.ts` 里(浏览器安全)。服务端在写入或执行前校验,浏览器在渲染卡片前再校验一次。 3. **没有插件也能读。** 每张卡片都带纯文本摘要。插件停用或卸载后,卡片显示摘要,该插件类型的成品改为提供下载。 4. **隔离。** 卡片和面板渲染在错误边界里。操作有超时,同一 Run 同时只执行一个操作或回答。 `plugin.server.ts` 里不要引入 React 和图标,因为 agent 服务会打包它。capability、卡片和面板用 `import()` 按需加载,这样工作台的体积不会随插件数量增长。 ## 构建插件 下面的例子用一个 id 为 `storyboard` 的插件。照着 `scripts/validate/fixtures/agent-plugin-fixture` 的目录结构来写,只保留上面选中的接入点。 ### 合约与清单 `contracts.ts` 放两侧共同约定的内容:key 和 zod schema,不引入 React,也不引入服务端模块。 ```ts title="src/plugins/storyboard/contracts.ts" import { z } from "zod"; export const STORYBOARD_PLUGIN_ID = "storyboard"; export const STORYBOARD_SCENE_KEY = "agent.storyboard"; export const STORYBOARD_SKILL_PACKAGE_ID = "platform.storyboard"; export const STORYBOARD_SKILL_DIRECTORY = "src/plugins/storyboard/skills/storyboard-studio"; export const STORYBOARD_CARD_KEY = `${STORYBOARD_PLUGIN_ID}.summary`; export const STORYBOARD_CARD_SCHEMA_VERSION = 1; export const StoryboardSummaryPayload = z .object({ shots: z.number().int().min(0).max(100) }) .strict(); ``` ```ts title="src/plugins/storyboard/manifest.ts" import { defineManifest } from "../kernel/types"; export const storyboardManifest = defineManifest({ id: "storyboard", version: "0.1.0", kind: "agent", requires: ["agent-starter"], }); ``` 插件在 `/app` 或 `/admin` 下有自己的页面时,再加上 `routes`。 ### 服务端 声明 `AgentHostExtension` 并贡献到 `agent.host`。使用相对路径 import,因为 agent 服务会打包这个文件,而它解析不了 `@/` 别名。 ```ts title="src/plugins/storyboard/server/extension.ts" import type { AgentHostExtension } from "../../../server/agent-extensions/types"; import { STORYBOARD_CARD_KEY, STORYBOARD_CARD_SCHEMA_VERSION, STORYBOARD_SCENE_KEY, STORYBOARD_SKILL_DIRECTORY, STORYBOARD_SKILL_PACKAGE_ID, StoryboardSummaryPayload, } from "../contracts"; export const storyboardExtension: AgentHostExtension = { id: "storyboard", scenes: [{ sceneKey: STORYBOARD_SCENE_KEY, readinessRequired: false }], capabilityRoutes: [{ scene: STORYBOARD_SCENE_KEY, pattern: /\bstoryboard\b/iu }], skills: [{ packageId: STORYBOARD_SKILL_PACKAGE_ID, directory: STORYBOARD_SKILL_DIRECTORY }], cards: { [STORYBOARD_CARD_KEY]: { payload: StoryboardSummaryPayload, schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION, }, }, }; ``` ```ts title="src/plugins/storyboard/plugin.server.ts" import { defineServerPlugin } from "../kernel/types"; import { storyboardManifest } from "./manifest"; import { storyboardExtension } from "./server/extension"; export const storyboardServerPlugin = defineServerPlugin({ manifest: storyboardManifest, contributes: { "agent.host": [storyboardExtension] }, }); ``` `readinessRequired: false` 让一个还没配模型的插件不会拖住整个 agent 服务。插件要在 `/api/plugins/storyboard/` 下提供 HTTP 接口时,在同一个 `contributes` 里加上 `api.routes`。不要在任何地方检查插件自己的启停状态。插件停用期间,宿主会拒绝它的场景、Skill、操作和 API 路由。 ### 浏览器 `plugin.ts` 只放元数据和加载函数。capability、卡片渲染器和面板在工作台第一次用到时才 import。 ```ts title="src/plugins/storyboard/plugin.ts" import { Clapperboard } from "lucide-react"; import { definePlugin } from "../kernel/types"; import { STORYBOARD_CARD_KEY, STORYBOARD_CARD_SCHEMA_VERSION, STORYBOARD_SCENE_KEY, STORYBOARD_SKILL_PACKAGE_ID, } from "./contracts"; import { storyboardManifest } from "./manifest"; export const storyboardPlugin = definePlugin({ manifest: storyboardManifest, contributes: { "agent.workbench": [ { id: "storyboard", agent: { id: "storyboard", labelKey: "appConsole.storyboard", icon: Clapperboard, order: 30, scenes: [STORYBOARD_SCENE_KEY], skillPackageId: STORYBOARD_SKILL_PACKAGE_ID, load: () => import("./workbench/capability").then(({ storyboardCapability }) => storyboardCapability), }, cardRenderers: { [STORYBOARD_CARD_KEY]: { schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION, load: () => import("./workbench/summary-card").then(({ summaryCard }) => summaryCard), }, }, }, ], }, }); ``` 卡片和面板只能通过收到的 `actions` 操作(回答待答问题、打开 artifact 或面板、引用到输入框、`runOperation`),或使用 `src/components/agent/extension-card.tsx` 里的 `useWorkbenchOperation`。文案 key 要加进两份词典。 ### Skill 把 Skill 放在插件目录里,这里是 `src/plugins/storyboard/skills/storyboard-studio`,包含 `skill.json` 和 `SKILL.md`。在 `skill.json` 的 `scenes` 里写上插件的场景,`allowedTools` 里只写真实存在的工具。`src/plugins/image-agent/skills/image-studio` 是一个可用的例子。然后发布: ```bash pnpm agent:publish-skills ``` 扩展在 `skills` 里声明了这个目录,所以命令会把它和平台 Skill 一起发布,卸载插件时 Skill 也随之移除。 ### 登记 把两半分别加进安装列表,各自写在 `// @module:storyboard` … `// @end-module:storyboard` 区段里,import 语句也放在自己的区段里: | 文件 | 条目 | | --------------------------------- | ------------------------ | | `src/plugins/installed.ts` | `storyboardPlugin` | | `src/plugins/installed.server.ts` | `storyboardServerPlugin` | 词典条目写进两份 `messages.ts`,放在同样标记的区段里。 ### 分发与校验 编写 `modules/storyboard/module.json`:`files` 包含 `src/plugins/storyboard/**`,`fragments` 包含两份安装列表和两份词典,`requires: ["agent-starter"]`,`version` 与清单一致,`docs` 写插件指南的完整地址。再加上 `scripts/validate/storyboard.ts`(通过真实的注册表断言插件的行为)、`validate:storyboard` 脚本和 `validate:all` 里的一段,然后运行 `pnpm registry:build`。参见[构建模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md)。 ## 验证 1. `pnpm validate:agent-plugin-contract` 通过。它还会构建参考插件,并通过宿主运行每个接入点。 2. 插件自己的校验器断言它的行为,`pnpm validate:all` 没有校验由通过变为失败。 3. 在 `/app/agent`,选择器里有这个插件;匹配其路由的请求显示 **自动 ·** 加插件名,并打开它的工作区 tab。 4. 在 **设置 → 插件** 中停用它:页面重新获得焦点后它从选择器消失,它的卡片显示摘要。 ## 常见问题 ### 注册表启动时报 `invalid_extension_key` 某个 key 没有以插件 id 开头,或者用了 `<id>.workspace`。在 `contracts.ts` 里改名。两侧读的是同一个常量。 ### 卡片只显示摘要 插件已停用,渲染器的 `schemaVersion` 比卡片旧,或者 payload 没通过渲染器的 schema。payload 结构变化时两侧版本号一起升。 ### 消息被以 `plugin_disabled` 拒绝 选中的 agent 刚被停用。输入框保留文字并切回 **自动**,下一条消息不会再路由到它。 ## 下一步 - [插件](https://kernlift.dev/zh/docs/core/plugins.md) 已安装和已启用的插件如何解析。 - [图片 Agent](https://kernlift.dev/zh/docs/extensions/agent/image-agent.md) 可以对照本文阅读的一个小插件。 --- # SearXNG > 为 Agent 接入 SearXNG。 Source: https://kernlift.dev/zh/docs/extensions/agent/searxng ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,工作台可在实际任务中调用该服务。 ## 在 SearXNG 完成准备 ### 部署搜索服务 打开 [SearXNG](https://docs.searxng.org/admin/installation-docker)。部署 Agent 服务能够访问的 SearXNG。 ### 启用 JSON 响应 在 settings.yml 的 search.formats 开启 json 并重启。 ### 验证搜索请求 从 Agent 所在网络请求带 format=json 的搜索地址,确认返回 JSON。 官方说明 · [官方容器安装说明](https://docs.searxng.org/admin/installation-docker) · [SearXNG Search API](https://docs.searxng.org/dev/search_api) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/search`。 | 来源 | 后台字段 | | ------------ | -------- | | Instance URL | Base URL | 启用对应服务,填写连接信息并保存。 <img src="/docs/guides/agent/searxng.zh.png" alt="Kernlift 后台的 SearXNG 配置字段" width="512" height="942" loading="lazy" /> ## 验证 1. 在该服务面板点击 **测试连接**。 2. 在工作台执行检索或网页提取,核对返回的内容。 ## 常见问题 ### 连接失败 从 Agent 服务所在网络测试配置的地址。若通过代理鉴权,核对后台配置的请求头和值。 ## 下一步 [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) --- # 运行 Agent 启动模板 > 安装 agent 模板,配置模型通道、沙箱与搜索服务商,启动 agent 服务并打开工作台。 Source: https://kernlift.dev/zh/docs/extensions/agent/starter `agent-starter` 模板增加 Agent 工作台和独立的 Node 服务。服务协调运行、审批、用户请求、技能、工具和每次运行独立的工作区。模型调用使用已配置的 AI 通道,积分由服务端预留和结算。Agent 是可选的。不部署这个服务时,Web 应用依然完整,agent 入口会显示服务未部署。本指南说明安装与就绪检查。执行模型见 [Agent 运行机制](https://kernlift.dev/zh/docs/extensions/agent.md)。 ## 模板包含什么 | 组成 | 位置 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | agent 契约、运行循环、工具与浏览器客户端 | `packages/agent-{contracts,runtime,tools,client}` | | 沙箱适配与镜像 | `packages/sandbox-adapter`、`packages/sandbox-adapter/template/Dockerfile` | | agent 服务(第二个进程) | `apps/agent-service` | | 运行、会话、消息、技能、审批、工作区与后台任务数据表 | 迁移 `0016_agent_starter`,SQLite 与 Postgres 各一份 | | 面向浏览器的鉴权接口 | `/api/agent/**` | | 工作台 | `/app/agent` | | `agent-starter` 插件:导航入口与路由归属 | `src/plugins/agent-starter` | | 服务商配置页 | `/admin/config/sandbox`、`/admin/config/search` | | 平台技能与发布脚本 | `agent-skills/`、`pnpm agent:publish-skills` | | 自带校验器 | `pnpm validate:agent-starter`、`validate:optional-agent`、`validate:dsh-runtime`、`validate:agent-plugin-contract`、`validate:sqlite-transactions`、`validate:agent-generation` | 工作台需要可用的 `agent.general` 模型路由和已配置沙箱。搜索与抓取服务商只对使用它们的工具必需。配置缺失时工作台会显示缺少的配置,不会模拟服务商响应。 ## 准备工作 * 底座仓库,或 `image-agent`、`video-agent` 业务模板。它们都包含 agent 部分。参见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。 * Node 20 或更高版本,以及一个能在本地运行的项目。参见[快速开始](https://kernlift.dev/zh/docs/quick-start.md)。 * **Postgres,或运行在 Node 上的 SQLite。** agent 运行需要交互式事务,而 Cloudflare D1 没有。 在 D1 上 web 应用照常运行,agent 入口被隐藏,`/api/agent/*` 返回 `503 agent_unavailable`。 参见[使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md)。 * 拥有 `config.read` 与 `config.write` 权限的管理员账号。模板新增的两个配置页沿用后台已有的权限, 不需要再授予新权限。 * **在 `/admin/config/storage` 配置好对象存储。** 技能包、运行产物与工作区文件都存在那里。 在配置好之前 `pnpm agent:publish-skills` 不会发布任何内容,并输出原因。`pnpm dev:agent` 会输出同样的提示, 并照常启动两个进程,以便访问配置页。参见[配置文件存储和上传](https://kernlift.dev/zh/docs/extensions/storage.md)。 * 如果要让 agent 执行脚本,还需要一个 E2B 兼容的沙箱服务;如果要让它检索网页与提取正文, 还需要 SearXNG 与 crawl4ai。 ## 配置 agent 服务 ### 安装依赖并迁移 ```bash pnpm install && pnpm db:migrate ``` agent 部分已经在仓库里:`packages/agent-*` 下的工作区包,以及 `apps/agent-service` 里的独立应用。`pnpm install` 安装它们的依赖,迁移为所选数据库方言创建 Agent 数据表。如果在快速开始里已经运行过,这两条命令不会再做任何事。 ### 让两个进程找到彼此 ```bash title=".env" # 只放基础设施项。服务商、限额与价格都在 /admin/config/* 中配置。 AGENT_SERVICE_URL=http://127.0.0.1:3001 AGENT_WEB_INTERNAL_URL=http://127.0.0.1:5173 AGENT_INTERNAL_SIGNING_SECRET= AGENT_RESOURCE_GRANT_SECRET= ``` 运行两次 `openssl rand -hex 32`。将两个独立的随机值分别填入上面的密钥字段,并在 Web 和 Agent 进程的对应字段中使用同一组值。 `AGENT_SERVICE_HOST`、`AGENT_SERVICE_PORT`、`AGENT_SERVICE_REQUEST_TIMEOUT_MS` 与 `AGENT_FLOW_LOG_LEVEL` 是可选项,`AGENT_SANDBOX_ERROR_LOG_ENABLED` 也是,`.env.example` 中列出了它们与默认值。服务商密钥应在管理后台配置。 这些变量只在运行 agent 时需要。没有 `AGENT_SERVICE_URL` 和签名密钥时,web 应用把 agent 视为未部署。 ## 两个进程 web 应用负责页面、对每个 `/api/agent/**` 请求鉴权并转发。`apps/agent-service` 是一个 Node 进程, 运行 agent 循环、沙箱与后台工作器。两者通过签名 HTTP 通信,使用上面两个密钥。 签名密钥用于两个进程之间的请求鉴别,资源授权密钥用于签发沙箱访问文件或模型时使用的短期令牌。 本地开发时,`pnpm dev` 只运行 web 应用,下面这条命令同时运行两个进程: ```bash pnpm dev:agent ``` 它会先执行迁移、发布平台技能、构建附件解析器,然后同时运行 Vite 与 agent 服务。 两个密钥未设置或不足 32 字节时,它会为本次会话临时生成,因此第一次运行不需要先准备密钥。 还没有配置对象存储的项目发布不了任何技能。该命令会输出提示并照常启动两个进程, 这样仍可访问 `/admin/config/storage` 完成配置。 ## 准备沙箱与检索服务 | 厂商 | 适用场景 | | -------------------------------------------------- | -------------- | | [E2B](https://kernlift.dev/zh/docs/extensions/agent/e2b.md) | 在 E2B 运行器中执行脚本 | | [阿里云沙箱](https://kernlift.dev/zh/docs/extensions/agent/aliyun.md) | 使用阿里云运行器镜像 | | [Novita Sandbox](https://kernlift.dev/zh/docs/extensions/agent/novita.md) | 使用 Novita 沙箱 | | [SearXNG](https://kernlift.dev/zh/docs/extensions/agent/searxng.md) | 通过自托管实例搜索 | | [Crawl4AI](https://kernlift.dev/zh/docs/extensions/agent/crawl4ai.md) | 抓取网页正文 | ## 配置服务商 ### 模型通道 打开 `/admin/config/ai`,为每个 agent 场景配置生效的路由:`agent.general` 用于普通对话,`agent.research` 用于以搜索为主的运行,`agent.mail` 用于邮件助理,`agent.audio` 用于语音。没有生效通道的场景会被判为未配置, 需要它的运行会失败并提示模型未配置。参见[配置 AI 场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)。 ### 沙箱 打开 `/admin/config/sandbox`,启用沙箱,选择服务商与其控制面地址,设置运行器模板与运行时上限,并填入服务商密钥。 密钥只写,保存在后台配置表中,之后不再回显。这里没有 `E2B_*` 环境变量兜底。没有配置的沙箱报告为不可用, 脚本类工具返回错误。运行器模板所用的镜像来自 `packages/sandbox-adapter/template/Dockerfile`。 ### 搜索 打开 `/admin/config/search` 配置 SearXNG(检索)与 crawl4ai(网页正文提取)。两者各有地址、鉴权头、 超时与启用开关,并各带一个 **测试连接** 按钮,点击后对你填写的服务发起一次真实请求。 ### 平台技能 `agent-skills/` 存放 agent 可加载的技能:`general-chat` 与 `mail-assistant`。已安装的能力插件(例如图片 Agent) 把技能放在自己的插件目录里,由同一条命令发布。 ```bash pnpm agent:publish-skills ``` 该命令会把每个技能打包发布到技能注册表,内容与当前生效版本一致的会跳过。运行从注册表加载技能,不读取磁盘文件, 所以改完技能要重新发布,每次部署也要执行一次。`agent-skills/` 和 `skills/` 是两个目录,后者是本仓库给编码助手用的文档。 ### 打开工作台 两个进程都启动之后,登录并打开 `/app/agent`。会话列表、流式对话、审批与产物面板都在这个页面上。 服务商未配置时,页面会显示缺少的配置并禁用不可用的操作。 ## 部署 两个进程分别部署,并且 web 应用必须能访问到 agent 服务。 ### agent 服务 构建产物,并在 Node 22 或更高版本上直接运行,或放进容器: ```bash pnpm build:agent-service node apps/agent-service/dist/main.js ``` 只给它数据库连接、`AGENT_INTERNAL_SIGNING_SECRET`、`AGENT_RESOURCE_GRANT_SECRET`、 `AGENT_WEB_INTERNAL_URL` 与监听地址,别的都不要。当环境中出现认证或支付类密钥时 (`BETTER_AUTH_*`、`AUTH_*`、`STRIPE_*`、`PAYMENT_*` 等),该进程会拒绝启动, 因为它在沙箱中运行不受信任的代码,不能持有这些密钥。同一次构建还会产出 `dist/publish-skills.mjs`, 部署时的技能发布步骤运行这个文件。 ### web 应用 Web 应用可按现有方式部署,但必须连接存放 Agent 数据表的数据库,所以不能用 D1。 把 `AGENT_SERVICE_URL` 指向 agent 服务的内网地址,并且不要把该服务暴露到公网。浏览器不直接访问它。 在 Cloudflare 上,agent 服务以容器的形式运行在 Worker 旁边。Worker 经 Hyperdrive 连接 Postgres (`DATABASE_DIALECT=postgres`、`DATABASE_ADAPTER=hyperdrive`),容器用 `AGENT_DATABASE_URL` 直连, `AGENT_SERVICE` 绑定取代 `AGENT_SERVICE_URL`。`wrangler.jsonc` 里注释掉的配置块列出了步骤。参见 [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md)、[部署到 Node 主机](https://kernlift.dev/zh/docs/deploy/node.md), 以及 Fly.io、Railway 和 Docker 的部署指南,它们都把 agent 作为单独的服务运行。 ### 每次部署之后 ```bash pnpm db:migrate pnpm agent:publish-skills ``` 两条命令都是幂等的。没有新迁移、技能也没有变化时,它们不会写入任何内容。 ## 验证 1. `pnpm db:migrate` 在你部署使用的方言下报告 `0016_agent_starter` 已应用。 2. `/admin/config/sandbox` 显示沙箱已配置,密钥保存在后台配置表中,页面不回显。 3. `/admin/config/search` 对你启用的每个服务商都返回测试连接成功。 4. 未登录时 `curl -i http://127.0.0.1:5173/api/agent/threads` 返回 `401`。登录后只返回你自己的会话。 5. agent 服务的 `GET /healthz` 返回 `status: "ok"`。场景与沙箱配置完成后,`GET /readyz` 返回 `200`, 且 `database`、`schema`、`objectStorage` 与 `providers` 均为 `ready`。 6. `/app/agent` 能完整执行一轮对话,并且这次运行的积分预留在积分账本中结算为实际消耗。 在仓库中运行 `pnpm validate:agent-starter` 和 `pnpm validate:optional-agent`。 ## 故障排查 ### Agent 入口不见了,或 `/api/agent/*` 返回 `503` Web 应用报告 agent 不可用。响应带有错误码 `agent_unavailable` 和 `x-agent-unavailable-reason` 响应头: | 原因 | 处理 | | ---------------------------- | -------------------------------------------------------------- | | `plugin_disabled` | 在 **设置 → 插件** 中启用 **agent-starter**。 | | `database_not_transactional` | 数据库是 D1。改用 Postgres,或 Node 上的 SQLite。 | | `service_not_configured` | 设置 `AGENT_SERVICE_URL`;在 Cloudflare 上则加上 `AGENT_SERVICE` 容器绑定。 | | `signing_secret_missing` | 在两个进程里把 `AGENT_INTERNAL_SIGNING_SECRET` 设为同一个值。 | 管理员在 `/app/agent` 上能看到同样的原因。 ### agent 脚本以 `agent_requires_transactions` 失败 进程连接的数据库不支持交互式事务(D1)。把它指向 Postgres(`DATABASE_DIALECT=postgres`) 或 Node 上的 SQLite。脚本在写入任何数据之前就失败,不会留下需要清理的数据。 ### 运行提示模型未配置 该运行需要的场景没有生效的通道路由。在 `/admin/config/ai` 中配置。在每个生效路由都能解析到带密钥的通道之前, `/readyz` 会一直报告 `providers: not_ready`。 ### 脚本类工具提示沙箱未配置 `/admin/config/sandbox` 未启用或缺少密钥。这里没有环境变量兜底,只能在该页面保存密钥。 ### 服务以 `forbidden_agent_service_configuration` 退出 它的环境里带了认证或支付类密钥。删掉它们。该服务只需要数据库、两个 agent 密钥与 web 内部地址。 ### `pnpm agent:publish-skills` 提示对象存储未配置 技能包保存在对象存储里,所以 `/admin/config/storage` 没有配置服务商之前发布不了任何内容。 该命令以非零码退出,部署中执行到它会停下。`pnpm dev:agent` 打印同样的提示并启动两个进程, 以便访问配置页。配置之后重新执行发布。 ### 新技能对运行没有产生效果 技能只改了磁盘上的文件,没有发布。运行 `pnpm agent:publish-skills`。运行从注册表读取技能,不读取 `agent-skills/`。 ## 参考 * [Agent 运行机制](https://kernlift.dev/zh/docs/extensions/agent.md) * [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md) * [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md) * [E2B sandboxes](https://e2b.dev/docs) ## 下一步 - [Agent 插件](https://kernlift.dev/zh/docs/extensions/agent/plugins.md) - [配置 AI 场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) - [积分](https://kernlift.dev/zh/docs/extensions/credits/usage.md) - [使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md) --- # 接收异步结果(轮询与 webhook) > 完成后,稍后才出结果的图片、视频、音频任务能到达最终状态,积分随之扣除或退回。 Source: https://kernlift.dev/zh/docs/extensions/ai/async 很多图片、视频、音频供应商先返回任务 ID,稍后才给出结果。你可以为每个 Provider(或 Provider 场景)选择由应用查询状态,还是由供应商回调。文本始终是直接返回,对话模型可以跳过本指南。 ## 准备工作 * 一个用于图片、视频或音频模型、已设置响应解析的 Provider 和 Provider 场景,见 [接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)。 * 一个可查询的状态 URL,或一个供应商能回调到的公网部署地址。本地 `127.0.0.1` 收不到回调。 * 拥有 `ai.read` 和 `ai.write` 的管理员账号。 ## 选择结果的获取方式 **状态轮询** ### 选择轮询 在 **设置 → AI 配置** 中打开 Provider(或 Provider 场景),在结果获取中选择 **状态轮询**。 ### 设置状态 URL 填写 **状态查询 URL 模板**、**间隔秒** 和 **超时秒**。模板中的 `{{externalTaskId}}` 是供应商返回的任务 ID。点击 **保存**。 **Webhook 推送** ### 选择 Webhook 推送 在 **设置 → AI 配置** 中打开 Provider(或 Provider 场景),在结果获取中选择 **Webhook 推送**。 ### 设置签名密钥 在 **Webhook 签名密钥** 中填写一个与供应商或中转服务共享的随机字符串。保存后不再显示。字段旁的标记显示 **已配置** 或 **未配置**,留空则保留已保存的密钥。在 Provider 场景上,如果 Provider 已有密钥,字段显示 **继承 Provider 密钥**。 ### 登记回调 URL 在供应商处登记字段下方显示的 **需要登记的回调 URL**。它由 **认证配置** 中的 **Base URL** 和 Provider 编码拼成: ```text <Base URL>/api/ai/channels/webhook/<provider 编码>?taskId={{externalTaskId}} ``` 回调需要通过 `taskId` 查询参数、`x-ai-task-id` 请求头或请求体中的 `taskId` 字段指明任务。请求参数中的 `{{externalTaskId}}` 会替换为任务 ID,因此可以在每次请求时把这个 URL 传给供应商。 ### 为每个回调签名 请求必须带 `x-ai-signature` 请求头:以 webhook 密钥为 key,对原始请求体计算的十六进制 HMAC-SHA256,可带 `sha256=` 前缀。大多数供应商不按这种方式签名,因此在前面放一个中转服务,先校验供应商自己的签名,再重新签名: ```ts title="relay.ts" import { createHmac } from "node:crypto"; const body = JSON.stringify({ taskId, status: "succeeded", output: "https://..." }); const signature = createHmac("sha256", webhookSecret).update(body).digest("hex"); // 以请求头 { "content-type": "application/json", "x-ai-signature": signature } 发送 POST ``` 没有已保存密钥时,Webhook 模式的 Provider 或 Provider 场景无法保存,表单提示 **Webhook 推送必须配置 Webhook 签名密钥。** **有两处会请求状态 URL** 客户端通过 `GET /api/status?taskId=...` 读取任务、且已到轮询间隔时,会请求一次状态 URL。没有人读取的任务由定时任务 `ai-channel-tasks` 每分钟推进一次,因此仍会结束并结算积分。这个任务只在[后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md)正常运行的部署上执行。 ## 读取任务状态 发起任务后,按返回的 `statusUrl` 读取状态。读取状态需要会话或带 **查询 AI 任务状态** 的 API Key,且只返回调用者自己的任务。 ```bash curl -X POST https://your-domain.example/api/video-creation/generate \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"海岸线上空的航拍镜头","mediaType":"video"}' # => { "taskId": "ai_task_...", "status": "running", "statusUrl": "/api/status?taskId=...", # "estimatedPriceCredits": 12, "resultMode": "polling" } curl "https://your-domain.example/api/status?taskId=ai_task_..." \ -H "Authorization: Bearer $API_KEY" ``` 任务成功后,输出中的 URL 会被复制到用户存储的 `/generated` 目录。没有配置 [文件存储](https://kernlift.dev/zh/docs/extensions/storage.md) 时任务仍会成功,任务事件中会记录跳过了存储导入。 ## 验证 * 在用户的 `/app/ai/<taskId>` 页面,任务从 `running` 变为 `succeeded` 或 `failed`,并显示扣除或退回的积分。 * **平台 → AI Tasks**(`/admin/ai/tasks`)显示最终状态。失败任务在 `/admin/ai/failed` 中列出。 * `pnpm validate:ai-channel` 会检查 webhook 签名、轮询和退款。 ## 常见问题 ### 异步任务一直处于运行中 确认轮询填写了 **状态查询 URL 模板**,并且要么有客户端在读取 `GET /api/status?taskId=...`,要么[后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md)在正常运行、定时任务 `ai-channel-tasks` 能推进该任务。Webhook 模式下,确认供应商会携带任务 ID 调用 webhook URL。 ### Webhook 返回 401 `Webhook secret is not configured.` 表示 Provider 和 Provider 场景都没有保存 **Webhook 签名密钥**,请填写并保存。`Webhook signature verification failed.` 表示 `x-ai-signature` 缺失,或不是对原始请求体计算的 HMAC。任务状态不会改变。 ### Webhook 返回 400 回调没有指明任务(`taskId is required.`)、回调 URL 指向了其他 Provider(`Webhook channel does not match task.`),或请求体不是 JSON。任务状态不会改变。 ### 任务状态或输出不对 解析配置读取了供应商响应中错误的字段。在 Provider 表单中粘贴一段真实响应,点击 **测试解析**,修正 **结果路径** 或 **状态映射**。 ## 参考 * [积分账本](https://kernlift.dev/zh/docs/extensions/credits.md) * [HMAC signatures](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/sign) ## 下一步 - [AI 渠道、场景与任务生命周期](https://kernlift.dev/zh/docs/extensions/ai.md) - [配置文件存储和上传](https://kernlift.dev/zh/docs/extensions/storage.md) --- # AI 对话记录 > 查看用户和 agent 的对话:谁、哪个 agent、什么语言,以及每一条消息的内容。 Source: https://kernlift.dev/zh/docs/extensions/ai/chats 用户的每一次对话都存为一条会话和它的消息。`/admin/chats` 是它们的只读视图,分页展示;`/admin/chats/$conversationId` 是一条完整线程,带每条消息的角色和内容。运营在这里查看 agent 对某位客户说过什么。 ## 准备工作 * `ai.read`,和 AI 运营页用同一个权限键。对话是 AI 的输出,查看 AI 任务的运营人员也负责查看对话。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 至少要有一条对话。聊天需要模型通道:如果 `/app/ai` 显示未配置,见 [AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)。 ## 设置 ### 给审阅人 `ai.read` 这是只读权限。`/admin/chats` 没有写入路径:不能编辑会话,不能删除会话,也不能以助手身份回复。 ### 看列表 `/admin/chats` 按更新时间倒序分页,显示账号、agent key、语言和最后更新时间。每页条数是 URL 上的搜索参数,所以别人打开你分享的链接时看到的是同一页。 ### 打开一条线程 `/admin/chats/$conversationId` 按顺序渲染消息及其角色:`system`、`user`、`assistant`、`tool`。工具消息也会显示,你可以看到答案来自哪一次工具调用。 ## 一条会话里有什么 <TypeTable type="{ agentKey: { type: "string", description: "由哪个 agent 应答。部署了多个 agent 时在这里区分。", }, locale: { type: '"en" | "zh"', description: "对话进行时的语言,和会话一起保存。", }, status: { type: '"active" | "archived"', default: '"active"', description: "归档的会话仍然可读;归档不删除任何东西。", }, "message.role": { type: '"system" | "user" | "assistant" | "tool"', description: "包含系统提示词和每一次工具返回,按顺序排列。", }, "message.status": { type: '"ready" | "submitted" | "streaming" | "error"', description: "流式输出中途失败的消息留在线程里,并保留错误状态。", }, }" /> 消息随流式输出持续写入。即使回答中断,会话仍保留已收到的内容及消息状态。 ## 验证 1. 在 `/app/ai` 聊几句,然后打开 `/admin/chats`,这条会话在最上面,带着你的账号和 agent key。 2. 点开它,系统提示词、你的消息和助手的回复按顺序排列。 3. 改 URL 里的 `pageSize`,列表按这个条数分页,链接在另一个浏览器里同样生效。 4. 用没有 `ai.read` 的角色登录,页面显示无权限。 ## 参考 * [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md):一次对话怎样到达模型 * [AI 场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md):场景路由到哪个通道 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [UIMessage 结构](https://ai-sdk.dev/docs/reference/ai-sdk-ui/ui-message):消息的 parts 是什么 ## 下一步 - [AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md) 配置对话运行所在的通道。 - [AI 场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) 把每个场景路由到该由它回答的模型。 - [积分](https://kernlift.dev/zh/docs/extensions/credits/usage.md) 一次对话花多少,记在哪里。 - [Agent 模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) 把对话扩展成带工具的 agent 的模板。 --- # Google Gemini > 将文本生成请求路由到 Google Gemini。 Source: https://kernlift.dev/zh/docs/extensions/ai/gemini ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能将可用的文本模型分配给聊天场景。 ## 在 Google Gemini 完成准备 ### 创建 AI Studio 密钥 打开 [Google Gemini](https://aistudio.google.com/apikey)。选择或导入 Cloud 项目,创建 API Key。 ### 确认模型权限 确认项目有可用额度,复制可调用的 Gemini 模型 ID。 官方说明 · [Google AI Studio 的 API Keys](https://ai.google.dev/gemini-api/docs/api-key) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/ai`。 | 来源 | 后台字段 | | ---------------- | ---------- | | API key | API key 密钥 | | Service endpoint | Base URL | | Model ID | 模型 ID | 添加输出类型为文本的 Provider 场景,选择 **Gemini 协议**。填写模型 ID 和定价后保存,再将就绪的模型分配给聊天场景。 <img src="/docs/guides/ai/provider.zh.png" alt="Kernlift 后台的 Google Gemini 配置字段" width="1040" height="1045" loading="lazy" /> ## 验证 1. 查看模型的路由就绪状态,补齐提示的字段。 2. 从已分配该模型的聊天场景发送消息,确认收到真实回复。 ## 常见问题 ### 对话报错 "Provider scene chat protocol is not configured" 对话场景路由到的 Provider 场景没有设置调用协议或模型 ID。在该 Provider 场景上补齐。 ## 下一步 [接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md) --- # AI 渠道、场景与任务生命周期 > 服务商、服务商场景与场景如何组合,积分价格如何解析,以及任务与对话从请求到结算的运行过程。 Source: https://kernlift.dev/zh/docs/extensions/ai Kernlift 中的 AI 通过配置接入。你在管理后台描述上游 API,把命名场景暴露给产品,每次调用都以积分定价并在账本中结算。配置方法见[接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)和[路由场景并设置定价](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)。 ## 三层配置 | 概念 | 是什么 | 示例 | | ----------- | ---------------------------------------------- | ------------------------- | | **服务商**(渠道) | 一个上游 API 账号:基础 URL、API Key、请求模板、结果返回方式以及响应解析方式 | `openai` | | **服务商场景** | 服务商下的一个具体模型或端点,带有自己的请求覆盖项和价格 | OpenAI 协议下的 `gpt-4o-mini` | | **场景** | 产品按代码请求的对象,带有输出类型,路由到一个服务商场景 | `chat`、`image-creation` | 调用方只指明场景。由于场景路由到一个服务商场景,你可以更换 `image-creation` 背后的模型而不改动任何调用方。对话默认使用 `chat` 场景,除非请求指定其他场景。任务通过 `POST /api/<scene>/generate` 发起。 场景只能路由到输出类型相同、处于启用且就绪状态的服务商场景,输出类型为 `text`、`image`、`video` 或 `audio`。服务商场景在缺少其设置所需的端点、定价、协议与模型 ID、轮询 URL 或 Webhook 密钥时,不算就绪。 ## 价格如何解析 每个服务商场景有一种定价模式: | 模式 | 计费依据 | 典型用途 | | -------- | ------------------------ | --------- | | `fixed` | 每次调用的成本 | 固定尺寸的单张图片 | | `rules` | 请求参数,按组合或数值步长 | 图片尺寸、视频时长 | | `tokens` | Token 用量,统一费率或输入、输出分开的费率 | 文本模型与对话 | 成本以你的币种填写,并按积分单价换算为积分。用户支付的价格是积分成本乘以加价后向上取整,且不低于成本。加价依次取自服务商场景、服务商、默认规则。 换算发生在保存服务商场景时,结果会被保存下来。之后修改积分单价不会重新定价已有的服务商场景,除非逐个重新保存。 ## 任务如何运行 1. 任务由服务端函数或 `POST /api/<scene>/generate` 发起,受 `ai.tasks.create` 限流约束。未指定场景时由任务类型选择。 2. 解析场景、其路由的渠道以及该媒体类型下启用的服务商场景,并计算积分价格。 3. 根据模板渲染请求 URL、请求头和请求体。 4. 在积分账本中冻结价格,任务以 `queued` 状态保存,并附带渠道、价格和脱敏请求的快照。 5. 调用服务商,并用渠道的解析器和状态映射读取响应。 6. 结果决定冻结如何结算: | 服务商状态 | 任务 | 积分 | 另外 | | ------ | ----------- | ---- | ------------------------------------------------- | | 成功 | `succeeded` | 扣除 | 输出 URL 被复制到用户的 `/generated` 存储目录;写入一条 `pass` 安全报告 | | 失败 | `failed` | 退还 | 写入一条 `warn` 安全报告 | | 排队或运行中 | `running` | 保持冻结 | 等待 Webhook 或轮询 | 每次状态变化都会在任务时间线上追加一条事件。用户只能读取自己的任务。管理后台可以看到全部任务。 ## 结果模式 图片、视频和音频服务商往往稍后才完成,所以每个渠道要选择结果如何到达。 | 模式 | 结果如何到达 | | --------- | ---------------------------------------------------------- | | `sync` | 在调用的响应中。文本始终是 `sync` | | `polling` | 客户端通过 `GET /api/status` 读取任务且已过轮询间隔时,查询状态 URL。没有后台定时器 | | `webhook` | 服务商或其前置中转服务向 `/api/ai/channels/webhook/<provider code>` 推送 | schema 还接受 `webhook_or_polling`,但后台表单只提供直接响应、状态轮询和 Webhook 推送三种方式。 Webhook 必须指明任务,并带有 `x-ai-signature` 请求头:用渠道的 Webhook 密钥对原始请求体计算的十六进制 HMAC-SHA256。大多数服务商并不这样签名,所以通常的做法是放一个小型中转服务,校验服务商自己的签名后重新签名。渠道或场景与任务不匹配的回调会被拒绝。配置方法见[接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md)。 ## 对话如何运行 1. `POST /api/chat` 接收 AI SDK UI 消息,并以流式返回包含文本和推理部分的回复。 2. 保存会话和用户消息。 3. 解析价格、冻结预估金额,并通过服务商场景的协议运行模型。 4. 流结束后,按上报的 Token 用量重新定价并扣除。出错时退还冻结,并以 `error` 状态保存助手消息。 | 协议 | 说明 | | ------------------ | ----------------------------------------------------------------------- | | `openai` | 兼容 OpenAI 的 chat completions。API Key 是服务商请求头中的 bearer token | | `gemini` | Google Generative AI。Key 取自 `x-goog-api-key`、`x-api-key` 或 bearer token | | `edge_inference` | 通过 `AI` 绑定调用 Cloudflare Workers AI;没有该绑定时不可用 | | `image_generation` | 仅用于任务;对话路径会拒绝 | 任务直接调用渲染后的请求 URL,所以协议和模型 ID 只影响对话。 ## 为什么这样设计 * **每个服务商无需写代码。** 任何返回 JSON 的 HTTP API 都可以用模板、JSON 路径和状态映射来描述。只有新增对话协议才需要代码。 * **不使用环境变量中的密钥。** 环境中的 `OPENAI_API_KEY` 等变量会被忽略。只使用保存在服务商上的密钥。 * **未配置就不运行。** 模板不自带任何服务商或场景。在场景路由到就绪的服务商场景之前,任务会以不可用错误失败、不扣任何积分,`/setup` 中 **AI 渠道**显示未就绪。 ## 相关文件 - 运行时/ - src/server/services/ai-workspace.service.ts - src/server/db/repositories/ai-workspace.repository.ts - 后台/ - src/routes/{-$locale}/admin/config/ai.tsx - src/components/ai/admin-ai-operations-workspace.tsx ## 下一步 - [积分账本](https://kernlift.dev/zh/docs/extensions/credits.md) - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) --- # 跑通图片和视频生成 > 接入图片或视频服务商,让一次生成完整跑通:请求变量、带数组下标的解析路径、状态轮询、结果入库,以及在 agent 对话里显示图片和视频。 Source: https://kernlift.dev/zh/docs/extensions/ai/media-generation 一次图片或视频生成要经过四个环节,用户才能看到结果:发给服务商的请求、服务商的响应(通常是一个任务 ID)、让任务结束的状态查询,以及文件存储。本文为 `image-creation` 和 `video-creation` 两个场景逐一配置这四个环节,再说明 agent 如何发布同一份结果。相关概念见 [AI 渠道、场景与任务生命周期](https://kernlift.dev/zh/docs/extensions/ai.md)。 ## 准备工作 * 一个图片或视频服务商的账号和 API Key,以及它的提交响应和状态查询响应的真实样例。 * 已在 **设置 → 存储配置** 中配置文件存储。没有存储时任务仍会成功,但结果不会进入用户的文件,agent 也没有文件可发布。见[配置文件存储与上传](https://kernlift.dev/zh/docs/extensions/storage.md)。 * 一个持有 `ai.read` 和 `ai.write` 的管理员账号。 * 仅 agent 部分需要:[Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)已经运行,`agent.general` 已配置模型。 ## 接入服务商 ### 创建 Provider 和它的请求 在 **设置 → AI 配置**(`/admin/config/ai`)中创建 Provider,填写 base URL 和 API Key,做法见[接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)。在 **请求参数** 里,用下面的变量拼出服务商要求的请求体: | 变量 | 值 | | ----------------------------------------------- | -------------------------------------------- | | `{{prompt}}` | 请求的提示词 | | `{{input}}` | 请求的 input;没有提供时是提示词 | | `{{metadata.<name>}}` | 请求里的其他字段,例如 `size`、`aspect_ratio`、`duration` | | `{{externalTaskId}}` | 服务商的任务 ID,拿到之后才有值,用在状态查询地址里 | | `{{sceneKey}}`、`{{channelKey}}`、`{{mediaType}}` | 本次调用的场景、Provider 和输出类型 | | `{{secret.<key>}}` | 后台配置里分类为 secret 的一项设置 | 文本值原样插入,其他类型的值按 JSON 插入,所以时长这样的数字发给服务商时仍是数字。使用上表以外的变量会报 `Unsupported template variable`。模板里直接粘贴密钥也会报错,请改用 secret 引用。 发给 `POST /api/<scene>/generate` 的字段里,除了 `prompt`、`mediaType` 这类保留名之外的都是请求的 metadata。agent 的 `model.generate` 调用里 `input` 的字段也是。例如,图片 agent 里选的画幅以 `{{metadata.aspect_ratio}}` 发给服务商。 ### 每个模型加一个 Provider 场景 为图片模型加一个输出类型为 **图片** 的 Provider 场景,为视频模型加一个 **视频** 的。在 **Provider 场景 endpoint** 里填以 `/` 开头的路径(会拼到 Provider 的 base URL 后面),或者完整的 `https://` 地址。计价按[路由场景与设置价格](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)配置。 ### 让解析路径对上服务商的字段 对照真实响应填写 **上游任务 ID 路径**、**状态路径**、**结果路径** 和 **错误路径**。路径从 `$` 开始,可以带数组下标: ```json title="提交响应" { "code": 200, "data": [{ "status": "submitted", "task_id": "task_1" }] } ``` | 字段 | 路径 | | ---------- | ------------------- | | 上游任务 ID 路径 | `$.data[0].task_id` | | 状态路径 | `$.data[0].status` | ```json title="完成后的状态响应" { "data": { "status": "completed", "result": { "images": [{ "url": ["https://cdn.example.com/a.png"] }] } } } ``` | 字段 | 路径 | | ---- | -------------------------------- | | 状态路径 | `$.data.status` | | 结果路径 | `$.data.result.images[0].url[0]` | 下标越界,或者对对象使用下标,都按未提供处理。提交响应和状态响应的结构通常不同,状态查询的路径在 **状态查询响应字段** 里单独填写。 ### 把服务商返回的每种状态都映射上 在 **状态映射** 里,用逗号分隔列出服务商的哪些字符串代表 **排队中**、**运行中**、**成功**、**失败** 和 **已取消**。匹配不区分大小写。提交响应里的状态也要列进去(上例的 `submitted` 应归到 **排队中**)。状态不在任何列表里时任务失败,报 `Unmapped AI channel status`,即使服务商已经受理。 保存前粘贴一份真实响应,点击 **测试解析**。 ### 设置结果如何返回 大多数图片和视频 API 返回的是任务 ID。在 **结果获取** 中选择 **状态轮询**,在 **状态查询 URL 模板** 里填入带 `{{externalTaskId}}` 的地址,并填写 **间隔秒**。 在 Provider 场景上,状态查询地址可以是以 `/` 开头的路径。这个路径相对 Provider 的 base URL 解析,规则与 endpoint 相同: ```text Provider base URL https://api.example.com 状态查询 URL 模板 /v1/tasks/{{externalTaskId}} 实际查询 https://api.example.com/v1/tasks/task_1 ``` 完整的 `https://` 地址原样使用。服务商主动回调的情况见[接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md)。 ### 路由场景 把 `image-creation` 路由到图片 Provider 场景,把 `video-creation` 路由到视频 Provider 场景。场景只能路由到输出类型相同、已启用且就绪的 Provider 场景。 ## 运行中的任务如何收尾 服务商受理的任务一直是 `running`,直到状态被查询。有三处会查询状态,服务商报告任务结束时都会结算积分: | 触发方 | 时机 | | -------------------------------- | -------------------------------------------------------- | | 客户端读取 `GET /api/status?taskId=…` | 每当轮询间隔已过。`/app/ai/<taskId>` 页面打开期间会这样做。 | | 定时任务 `ai-channel-tasks` | 每分钟一次,处理没有人在看的任务。见[后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md)。 | | agent 的 `model.collect` | 运行取回它用 `async: true` 发起的生成时。 | 任务成功后,系统下载输出里的每个 URL,作为私有文件存入用户的 `/generated` 文件夹,并标记为来自这个任务。之后任务的输出列出这些已存储的文件。 ## 检查存储 endpoint 生成的文件通过你配置的存储服务写入。对 S3 兼容的服务,对象地址取决于 **S3 endpoint**: | Endpoint | 对象地址 | | ------------------------ | ---------------------------------------------------------- | | `https://s3.example.com` | `https://s3.example.com/<bucket>/<key>`(路径风格) | | 主机名已经以桶名开头 | `https://<bucket>.storage.example.com/<key>` | | 主机名以 `.aliyuncs.com` 结尾 | `https://<bucket>.oss-<region>.aliyuncs.com/<key>`(虚拟主机风格) | 请求签名和预签名 URL 使用同一个地址,所以 endpoint 要严格按服务商文档填写。阿里云 OSS 填地域 endpoint,不要带桶名。 ## 由 agent 发布 Agent 通过同样的场景生成,不需要额外配置。在一次运行里: 1. Skill 调用 `model.generate`,带上 `sceneKey: "image-creation"` 或 `"video-creation"` 和一个 `saveTo` 路径。使用 `async: true` 时 Skill 先得到任务句柄,之后用同一个 `saveTo` 调用 `model.collect`。 2. 写在 `saveTo` 的是一份清单,里面指明存储文件。图片或视频本身已经在存储里。 3. Skill 用 `kind: "image"` 或 `"video"` 和这个路径调用 `artifact.publish`。产物的版本指向这个存储文件,不会重新下载或上传。前提是清单里只有一个文件,文件属于该用户、来自 AI 任务,并且内容类型与发布的类型一致。 4. 对话在消息里显示产物:图片显示为预览,视频显示为带控制条的播放器。产物仍然可以在右侧面板打开。 预览授权的有效期是一分钟。视频在播放期间按区间读取,所以加载因授权过期而失败时,播放器重新获取一次授权,并从原位置继续播放。授权仍有效时加载失败,卡片改为显示打开和下载操作。 如果需要画幅选择和每次运行的张数上限,安装[图片 Agent](https://kernlift.dev/zh/docs/extensions/agent/image-agent.md)。 ## 验证 1. 在 `/app/ai` 发起一个图片任务,或者用 API: ```bash curl -X POST https://<your-domain>/api/image-creation/generate \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"A lighthouse at dusk","mediaType":"image"}' ``` 2. 在 `/app/ai/<taskId>` 上,任务从 `running` 变为 `succeeded`,事件里有 `Generated output imported to storage.` 3. 图片出现在 `/app/assets` 中该用户的生成文件里。 4. 用 `video-creation` 和 `"mediaType":"video"` 再做一遍。 5. 如果安装了 agent,在 `/app/agent` 里请求一张图或一段视频。结果显示在消息里,页面停留超过一分钟后视频仍能播放。 6. 在仓库里,`pnpm validate:generation-pipeline` 检查解析路径、相对的状态查询地址和对象寻址。随 agent 启动模板分发的 `pnpm validate:agent-generation` 检查发布和播放器。两者都不调用服务商。 ## 故障排查 ### 服务商已受理,任务却失败 提交响应里的状态不在任何 **状态映射** 列表里,或者 **状态路径** 指向了错误的字段。任务的错误信息里有未映射的状态名,把它加到 **排队中** 或 **运行中**。 ### 任务一直在运行 检查 **上游任务 ID 路径** 能否从提交响应里读到 ID(服务商返回数组时要带下标),轮询是否启用并填了 **状态查询 URL 模板**,以及后台任务是否在运行。超过五分钟没有执行一轮时,`/setup` 会给出警告。 ### 任务成功了,但没有文件入库 任务事件里有 `Generated output storage import skipped.`,并附带每个 URL 的失败原因。S3 兼容服务返回 `403`,通常是 endpoint 的寻址风格与上表不符。 ### agent 的产物显示无法加载 发布的路径不是本次运行里某次生成的 `saveTo` 清单,或者类型与文件不符。视频要以 `video` 发布,图片要以 `image` 发布。 ## 下一步 - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) 用 Webhook 回调代替轮询。 - [路由场景与设置价格](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) 按尺寸或时长为一次生成计价。 - [图片 Agent](https://kernlift.dev/zh/docs/extensions/agent/image-agent.md) agent 工作台上的图片入口。 - [配置文件存储与上传](https://kernlift.dev/zh/docs/extensions/storage.md) 生成的文件存在哪里。 --- # OpenAI > 将文本生成请求路由到 OpenAI。 Source: https://kernlift.dev/zh/docs/extensions/ai/openai ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能将可用的文本模型分配给聊天场景。 ## 在 OpenAI 完成准备 ### 创建项目密钥 打开 [OpenAI](https://platform.openai.com/api-keys)。创建项目密钥并妥善保存。 ### 选择可用模型 从项目可调用的模型列表复制完整模型 ID。 官方说明 · [API 平台](https://platform.openai.com/api-keys) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/ai`。 | 来源 | 后台字段 | | --------------- | ---------- | | Project API key | API key 密钥 | | API endpoint | Base URL | | Model ID | 模型 ID | 添加输出类型为文本的 Provider 场景,选择 **OpenAI 协议**。填写模型 ID 和定价后保存,再将就绪的模型分配给聊天场景。 <img src="/docs/guides/ai/provider.zh.png" alt="Kernlift 后台的 OpenAI 配置字段" width="1040" height="1045" loading="lazy" /> ## 验证 1. 查看模型的路由就绪状态,补齐提示的字段。 2. 从已分配该模型的聊天场景发送消息,确认收到真实回复。 ## 常见问题 ### 对话报错 "Provider scene chat protocol is not configured" 对话场景路由到的 Provider 场景没有设置调用协议或模型 ID。在该 Provider 场景上补齐。 ## 下一步 [接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md) --- # 接入 AI 服务商 > 完成后,上游 AI 账号及其模型保存在后台,可以路由到你的场景。 Source: https://kernlift.dev/zh/docs/extensions/ai/providers Provider 对应一个上游 API 账号,例如 OpenAI、Gemini、Cloudflare Workers AI,或任何返回 JSON 的 HTTP API。Provider 场景是 Provider 下的一个具体模型或接口。两者都在 **设置 → AI 配置** 中配置,不需要改代码,也不需要环境变量。 ## 准备工作 * 供应商账号、API Key,以及从供应商文档中查到的 API Base URL 和模型 ID。 * 拥有 `ai.read` 和 `ai.write` 的管理员账号。 按供应商提供的能力选择接入方式: | 供应商 | 输出类型 | 需要配置 | | ---------------------------- | ----------------------- | ------------------------------------------ | | OpenAI 或兼容 OpenAI 的对话 API | `text` | **OpenAI 协议**、Base URL、API Key、模型 ID | | Google Gemini | `text` | **Gemini 协议**、Base URL、API Key、模型 ID | | Cloudflare Workers AI | `text` | **边缘推理** 和模型 ID;只在配置了 `ai` 绑定的 Workers 上可用 | | 返回 JSON 的 HTTP API(图片、视频、音频) | `image`、`video`、`audio` | 接口地址、请求参数、结果获取方式和响应解析 | ## 在模型服务商准备凭据 | 厂商 | 适用场景 | | ---------------------------------------------------------- | ------------------- | | [OpenAI](https://kernlift.dev/zh/docs/extensions/ai/openai.md) | OpenAI 协议文本生成 | | [Google Gemini](https://kernlift.dev/zh/docs/extensions/ai/gemini.md) | Gemini 协议文本生成 | | [Cloudflare Workers AI](https://kernlift.dev/zh/docs/extensions/ai/workers-ai.md) | 通过 Workers 绑定运行文本模型 | 自定义 HTTP 图片、音频或视频接口按下文配置端点和结果解析。先从服务商取得真实响应,再填写解析路径。 ## 添加 Provider ### 打开表单 进入 **设置 → AI 配置**(`/admin/config/ai`),打开 **Provider**,点击 **添加 Provider**。 ### 标识 Provider 填写 **显示名称** 和 **编码**(例如 `openai`)。编码保存为小写加连字符,并会出现在 webhook 回调 URL 中。**状态** 选 **启用**。 ### 设置基础请求 * **方法** 和 **Base URL**:一般为 `POST`,以及 API 基础地址。OpenAI 协议下,对话接口路径会拼接在它后面。 * **API key 密钥**:供应商控制台里的 Key。以密钥形式存储,并在 **请求 Headers** 中自动添加一行引用它的 **Authorization**。之后编辑时留空即保留原密钥。 * **请求 Headers** 和 **请求参数**:可选,每次调用都带上的请求头和请求体字段。值中可以使用 `{{prompt}}`、`{{input}}` 和 `{{metadata.<name>}}`。不要把 Key 直接写进请求头的值里。 ### 选择结果获取和解析方式 文本始终是 **直接返回**。图片、视频、音频等稍后才出结果的供应商,选择 **状态轮询** 或 **Webhook 推送**,见 [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md)。 这类供应商还需要填写 **上游任务 ID 路径**、**状态路径**、**结果路径**、**错误路径** 和 **事件 ID 路径**(默认 `$.id`、`$.status`、`$.output`、`$.error`),并在 **状态映射** 中用英文逗号分隔列出哪些供应商状态值分别对应 **排队中**、**运行中**、**成功**、**失败** 和 **已取消**。粘贴一段真实响应,点击 **测试解析** 检查。 ### 保存 保持勾选 **使用系统默认价格**,或取消勾选后为该 Provider 设置 **基础成本积分** 和 **加价率**。点击 **保存**,Provider 出现在列表中。 ## 添加模型 ### 描述模型 在 Provider 所在行点击 **Provider 场景**,再点击 **添加 Provider 场景**。在 **Provider 场景** 区块填写 **Provider 场景编码**、**Provider 场景名称**、**输出类型** 和 **状态**。 ### 设置请求 在 **Provider 场景请求** 区块: * **文本**:选择 **调用协议**(**OpenAI 协议**、**Gemini 协议** 或 **边缘推理**),按供应商的命名填写 **模型 ID**,例如 `gpt-4o-mini` 或 `gemini-2.5-flash`。请求发往 Provider 的 **Base URL**。 * **图片、视频、音频**:填写完整的 **Provider 场景 endpoint**,留空则使用 Provider 的 **Base URL**。只在这里补充该模型独有的请求头或参数,留空的区块继承 Provider。可在 **请求预览** 中点击 **预览** 查看渲染后的请求。 **Provider 场景结果获取** 保持 **继承**,除非这个模型的结果获取方式与该 Provider 的其他模型不同。 ### 定价并保存 按 [为 Provider 场景定价](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) 在 **Provider 场景计费** 中选择 **计费模式**,然后点击 **保存**。 **环境变量中的 Key 不会被读取** 只使用 Provider 上保存的 Key,`OPENAI_API_KEY` 等环境变量不会被读取。 ## 验证 在 Provider 场景列表中,**路由状态** 显示 **可路由**,或列出缺少的项:**缺少 endpoint**、**缺少计费**、**缺少协议或模型 ID**、**缺少轮询 URL**、**缺少 Webhook secret**。可路由的 Provider 场景就能在 **场景路由** 中选择了。`pnpm validate:ai-channel` 会检查渠道结构、响应解析和定价。 ## 常见问题 ### 对话报错 "AI channel ... is not configured" Provider 的请求头中没有 API Key。在 Provider 上保存 **API key 密钥**。Gemini Provider 也可以添加 `x-goog-api-key` 请求头。对话对 OpenAI 读取 Bearer 令牌,对 Gemini 读取 `x-goog-api-key`、`x-api-key` 或 Bearer 令牌。 ### 对话报错 "Provider scene chat protocol is not configured" 对话场景路由到的 Provider 场景没有设置调用协议或模型 ID。在该 Provider 场景上补齐。 ### 边缘推理不可用 Workers AI 绑定只在 Cloudflare Workers 上、且 `wrangler.jsonc` 配置了 `ai` 绑定时存在。其他运行环境请使用 OpenAI 或 Gemini 协议,见 [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md)。 ### 场景路由中找不到该 Provider 场景 下拉框只列出输出类型与场景相同、已启用且可路由的 Provider 场景。检查 **路由状态**、**状态** 和 **输出类型**。 ## 参考 * [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md) * [缓存](https://kernlift.dev/zh/docs/core/admin/cache.md) * [OpenAI API reference](https://platform.openai.com/docs/api-reference) ## 下一步 - [设置场景路由和定价](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) - [AI 渠道、场景与任务生命周期](https://kernlift.dev/zh/docs/extensions/ai.md) --- # 设置场景路由和定价 > 完成后,产品对外提供 chat、image-creation 等命名 AI 场景,每个场景路由到一个模型并按积分计价。 Source: https://kernlift.dev/zh/docs/extensions/ai/scenes 调用方按编码请求场景。每个场景路由到一个 Provider 场景,因此切换背后的模型不需要修改调用方。每次调用都按积分计价。积分在调用供应商前预留,成功时扣除,失败时退回。 ## 准备工作 * 至少一个带有 Provider 场景的 Provider,见 [接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)。 * 拥有 `ai.read` 和 `ai.write` 的管理员账号。 * 一个有积分的测试用户,见 [用积分对用量计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md)。 ## 从服务商确认计费单位 先在当前模型的服务商控制台或官方价目表确认模型 ID、计费货币与单位。文本模型通常区分输入/输出 Token,图片或视频可能按请求、尺寸或时长计费。可参考 [OpenAI 价格](https://platform.openai.com/docs/pricing)、[Gemini 价格](https://ai.google.dev/gemini-api/docs/pricing)或 [Workers AI 价格](https://developers.cloudflare.com/workers-ai/platform/pricing/)。兼容 HTTP 服务以其自己的合同或价目表为准。项目不会同步服务商价格。先把服务商价格换算成下文的 **Provider 场景成本** 或 Token 比率,再设加价率,并用一笔真实测试请求核对供应商账单与项目扣费。文中的示例数字不是服务商现价。 ## 设置积分价格 ### 打开默认规则 进入 **设置 → AI 配置**(`/admin/config/ai`),打开 **默认规则**。 ### 填写全局默认值 在 **全局默认** 中填写 **1 积分价格**(一个积分值多少钱,例如 `0.01`)、**加价率**(百分比,例如 `50`)和 **货币**(例如 `USD`),然后点击 **保存**。 ## 为 Provider 场景定价 ### 打开 Provider 场景 打开 **Provider**,在 Provider 所在行点击 **Provider 场景**,再通过 **配置 Provider 场景** 打开模型。 ### 选择计费模式 在 **Provider 场景计费** 中选择 **计费模式**: * **固定积分**:在 **Provider 场景成本**(按你的货币)中填写每次调用的成本,可选填 **Provider 场景加价率(可选)**。预览显示 **成本积分** 和 **最终扣费**。 * **按参数规则**:按 `size`、`duration` 等请求参数计费。选择 **参数排列组合** 时,为每个参数填写 **参数名称**、**默认值** 和 **有效值列表**,系统为每种组合生成一行价格,初始值取自 **默认成本** 和 **默认加价率**。选择 **数值步长** 时,填写 **计费参数名**、**步长**、**每步成本** 和 **最少步数**。 * **Token 折算**:用于文本模型。选择 **按总 Token 统一折算** 并填写 **总 Token / 货币单位**,或选择 **输入 / 输出分别折算** 并填写两个比率。对话在流式返回期间先预留估算积分,结束后按模型返回的 Token 用量扣费。 ### 保存 点击 **保存**。`/admin/ai/pricing` 汇总了每个 Provider 场景最终的价格。 扣费积分 = 成本积分叠加加价率后向上取整,且不低于成本积分。加价率依次取 Provider 场景、Provider、**默认规则** 中的值。**1 积分价格** 为 `0.01` 时: * 固定成本 `0.04` 折合 4 成本积分,加价率 50% 时用户支付 6 积分。 * **总 Token / 货币单位** 填 `1000000` 时,每 10,000 Token 计 1 成本积分。一次 25,000 Token 的回复为 3 成本积分,加价率 50% 时扣 5 积分。 **修改积分价格** 成本在保存 Provider 场景时按当时的积分价格换算成积分并保存下来。之后如果修改了 **1 积分价格**,需要逐个打开 Provider 场景重新保存,否则用户仍按旧价格扣费。 ## 创建场景并设置路由 ### 添加场景 打开 **场景路由**,点击 **添加场景**,填写 **显示名称**、**编码**(例如 `chat` 或 `image-creation`)、**输出类型**、**排序** 和 **状态**,然后点击 **保存**。 ### 选择模型 在场景所在行的 **Provider 场景** 下拉框中选择模型。下拉框只列出输出类型相同、已启用且可路由的 Provider 场景。如果还没有,点击 **请先创建 Provider 场景**,保存该表单时会自动完成路由。 徽标变为 **当前路由**。对话默认使用编码为 `chat` 的场景,除非请求指定了其他场景。任务通过 `POST /api/<编码>/generate` 调用,例如 `/api/image-creation/generate`。 ## 验证 ### 发送对话消息 以测试用户登录站点,在浏览器控制台运行: ```js await fetch("/api/chat", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ messages: [{ id: "m1", role: "user", parts: [{ type: "text", text: "你好" }] }], }), }).then((response) => response.text()); ``` 回复会流式返回,对话出现在 **平台 → 对话**(`/admin/chats`)中。 ### 运行任务 用带 **运行 AI 任务** 权限范围的 API Key 调用任务场景: ```bash curl -X POST https://your-domain.example/api/image-creation/generate \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"木桌上的陶瓷马克杯","mediaType":"image","size":"1024x1024"}' ``` 响应中包含 `taskId`、`status` 和 `estimatedPriceCredits`。除 `prompt`、`input`、`mediaType` 等保留字段外,其余字段会作为 metadata 传给定价规则,因此上例的 `size` 可以用于 **按参数规则** 计费。 ### 检查结果 * 用户的 `/app/ai` 列出该任务,任务详情页显示积分的预留、扣除或退回情况。 * **平台 → AI Tasks**(`/admin/ai`)能看到该任务。失败任务及供应商错误在 `/admin/ai/failed` 中列出。 * `/setup` 中 **AI 渠道** 显示为就绪。 `pnpm validate:ai` 会运行文本和视频任务,检查积分和事件。`pnpm validate:ai-channel` 会检查定价和路由。 ## 常见问题 ### 任务报错 "AI scene is not available" 或 "AI provider is not available for this scene" 场景没有启用的路由,或路由到的 Provider 在请求的输出类型下没有启用的 Provider 场景。在 **场景路由** 中设置路由,并确认 Provider 和 Provider 场景都已启用。此时不会扣积分。 ### 任务报错 "S06 insufficient credits" 用户可用余额低于价格。在 **概览 → 用户** 发放积分或调低价格。此时不会调用供应商。 ### 用户仍按旧价格扣费 Provider 场景保存之后修改过积分价格。打开该 Provider 场景,再点击一次 **保存**。 ## 参考 * [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md) * [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) * [OpenAI API reference](https://platform.openai.com/docs/api-reference) ## 下一步 - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) - [签发 API 密钥并设置限流](https://kernlift.dev/zh/docs/core/auth/api-keys.md) - [AI 渠道、场景与任务生命周期](https://kernlift.dev/zh/docs/extensions/ai.md) - [积分账本](https://kernlift.dev/zh/docs/extensions/credits.md) --- # Cloudflare Workers AI > 将文本生成请求路由到 Cloudflare Workers AI。 Source: https://kernlift.dev/zh/docs/extensions/ai/workers-ai ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能将可用的文本模型分配给聊天场景。 ## 在 Cloudflare Workers AI 完成准备 ### 选择文本模型 打开 [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/models/)。从 Workers AI 模型目录选择文本模型,复制完整 ID。 ### 部署 AI 绑定 在 Worker 配置中声明名为 `ai` 的绑定并部署。 官方说明 · [模型目录](https://developers.cloudflare.com/workers-ai/models/) · [Workers AI 绑定](https://developers.cloudflare.com/workers-ai/configuration/bindings/) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/ai`。 | 来源 | 后台字段 | | -------- | ----- | | Model ID | 模型 ID | 添加输出类型为文本的 Provider 场景,选择 **边缘推理**。填写模型 ID 和定价后保存,再将就绪的模型分配给聊天场景。 <img src="/docs/guides/ai/provider.zh.png" alt="Kernlift 后台的 Cloudflare Workers AI 配置字段" width="1040" height="1045" loading="lazy" /> ## 验证 1. 查看模型的路由就绪状态,补齐提示的字段。 2. 从已分配该模型的聊天场景发送消息,确认收到真实回复。 ## 常见问题 ### 边缘推理不可用 Workers AI 绑定只在 Cloudflare Workers 上、且 `wrangler.jsonc` 配置了 `ai` 绑定时存在。其他运行环境请使用 OpenAI 或 Gemini 协议,见 [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md)。 ## 下一步 [接入 AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md) --- # Microsoft Clarity > 为网站接入 Microsoft Clarity。 Source: https://kernlift.dev/zh/docs/extensions/analytics/clarity ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在公开页面确认该厂商的脚本已加载。 ## 在 Microsoft Clarity 完成准备 ### 创建项目 打开 [Microsoft Clarity](https://clarity.microsoft.com/projects)。创建项目并复制 Project ID。 ### 开启报表导出 如需报表,在 Settings → Data Export 生成令牌。 官方说明 · [Clarity Data Export API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/analytics`。 | 来源 | 后台字段 | | ------------------------------------------------------- | ---------------------- | | Clarity → 你的项目 → Settings → Overview。 | **Clarity Project ID** | | Clarity → 你的项目 → Settings → Data Export → 生成 API token。 | **Clarity API Token** | 保存配置。 <img src="/docs/guides/analytics/clarity-crisp.zh.png" alt="Kernlift 后台的 Microsoft Clarity 配置字段" width="512" height="466" loading="lazy" /> ## 验证 1. 使用无痕窗口打开公开页面,关闭广告拦截。 2. 在页面中确认已加载带有 `clarity.ms/tag` 的脚本。 ## 常见问题 ### 页面上没有出现脚本 标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 **运行检查** 面板,再关闭扩展后刷新。 ## 下一步 [添加统计分析与客服聊天](https://kernlift.dev/zh/docs/extensions/analytics.md) --- # Crisp > 为网站接入 Crisp。 Source: https://kernlift.dev/zh/docs/extensions/analytics/crisp ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在公开页面确认该厂商的脚本已加载。 ## 在 Crisp 完成准备 ### 创建网站 打开 [Crisp](https://app.crisp.chat/)。在工作区中创建网站。 ### 获取 Website ID 打开该网站的安装说明,复制 Website ID。 官方说明 · [Crisp Web SDK](https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/npm/) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/analytics`。 | 来源 | 后台字段 | | --------------------------------------------------------- | -------------------- | | Crisp → Settings → Website settings → Setup instructions。 | **Crisp Website ID** | 保存配置。 <img src="/docs/guides/analytics/clarity-crisp.zh.png" alt="Kernlift 后台的 Crisp 配置字段" width="512" height="466" loading="lazy" /> ## 验证 1. 使用无痕窗口打开公开页面,关闭广告拦截。 2. 在页面中确认已加载带有 `client.crisp.chat/l.js` 的脚本。 ## 常见问题 ### Crisp 组件显示 "Invalid website" 保存的 **Crisp Website ID** 与 Crisp 账号中的网站不一致。从 Crisp 复制正确的 ID 后重新保存。 ## 下一步 [添加统计分析与客服聊天](https://kernlift.dev/zh/docs/extensions/analytics.md) --- # Google Ads > 为网站接入 Google Ads。 Source: https://kernlift.dev/zh/docs/extensions/analytics/google-ads ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在公开页面确认该厂商的脚本已加载。 ## 在 Google Ads 完成准备 ### 创建转化操作 打开 [Google Ads](https://ads.google.com/)。创建网站转化操作。 ### 复制代码标识符 打开代码设置,复制转化 ID 和转化标签。 官方说明 · [Google Ads](https://support.google.com/google-ads/answer/7548399) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/analytics`。 | 来源 | 后台字段 | | ------------------------------------ | ------------------------------- | | Google Ads → 目标 → 转化 → 代码设置(`AW-…`)。 | **Google Ads ID** | | 转化操作旁显示的标签。它会被保存并提供给页面,但系统不会自动上报转化。 | **Google Ads Conversion Label** | 保存配置。 <img src="/docs/guides/analytics/google.zh.png" alt="Kernlift 后台的 Google Ads 配置字段" width="512" height="562" loading="lazy" /> ## 验证 1. 使用无痕窗口打开公开页面,关闭广告拦截。 2. 在页面中确认已加载带有 `googletagmanager.com/gtag/js` 的脚本。 此步骤加载 Ads 标签。要上报转化,还需为对应转化操作接入事件。 ## 常见问题 ### 页面上没有出现脚本 标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 **运行检查** 面板,再关闭扩展后刷新。 ## 下一步 [添加统计分析与客服聊天](https://kernlift.dev/zh/docs/extensions/analytics.md) --- # Google Analytics > 为网站接入 Google Analytics。 Source: https://kernlift.dev/zh/docs/extensions/analytics/google-analytics ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在公开页面确认该厂商的脚本已加载。 ## 在 Google Analytics 完成准备 ### 创建网站数据流 打开 [Google Analytics](https://analytics.google.com/)。创建 GA4 媒体资源和网站数据流,复制衡量 ID。 ### 启用报表 API 如需报表,记下数字格式的媒体资源 ID 并启用 Analytics Data API。 ### 授权读取报表 为有权读取该媒体资源的账号获取只读 OAuth Access Token。 官方说明 · [GA4 衡量 ID](https://support.google.com/analytics/answer/9311124?hl=en) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/analytics`。 | 来源 | 后台字段 | | ----------------------------------------------------------------------------------- | ---------------------------- | | Google Analytics → 管理 → 数据流 → 你的网站数据流 → 衡量 ID(`G-…`)。 | **Google Analytics ID** | | Google Analytics → 管理 → 媒体资源详情,只包含数字。 | **GA Property ID** | | 对该媒体资源有读取权限的 OAuth access token,例如带 `analytics.readonly` scope。有效期很短,拉取报表前需要粘贴一个新的。 | **GA Data API Access Token** | 保存配置。 <img src="/docs/guides/analytics/google.zh.png" alt="Kernlift 后台的 Google Analytics 配置字段" width="512" height="562" loading="lazy" /> ## 验证 1. 使用无痕窗口打开公开页面,关闭广告拦截。 2. 在页面中确认已加载带有 `googletagmanager.com/gtag/js` 的脚本。 ## 常见问题 ### 页面上没有出现脚本 标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 **运行检查** 面板,再关闭扩展后刷新。 ## 下一步 [添加统计分析与客服聊天](https://kernlift.dev/zh/docs/extensions/analytics.md) --- # 添加统计分析与客服聊天 > 在所有页面加载 Google Analytics、Umami、Plausible、Clarity 或 Crisp 聊天组件,检查连接,并按国家查看统计。 Source: https://kernlift.dev/zh/docs/extensions/analytics 在管理后台保存服务商的标识后,它的脚本会在所有页面加载。再保存 API 凭据,就能拉取报表确认连接。所有服务商都是可选的,彼此独立,都不读取环境变量。 ## 准备工作 * 在要使用的服务商为自己的域名创建好站点或项目。 * 具备 `config.write` 的管理员账号。只有 `config.read` 可以打开页面,但不能保存、拉取报表或上报测试事件。 * 按国家查看统计需要 `countries.read`。 每个服务商分两部分:公开标识用于加载脚本,API 凭据只在管理员拉取报表时使用。 | 服务商 | 用途 | 加载脚本所需 | 拉取报表所需 | | ----------------- | -------------------- | ----------------------- | ------------------------------------------------- | | Google Analytics | 在 GA4 中查看访问和事件 | **Google Analytics ID** | **GA Property ID** 和 **GA Data API Access Token** | | Google Ads | 为 Ads 账号加载 Google 代码 | **Google Ads ID** | 不拉取 | | Umami | 注重隐私的访问统计,云服务或自托管 | **Umami Website ID** | **Umami API Key** | | Plausible | 注重隐私的访问统计,云服务或自托管 | **Plausible Domain** | **Plausible API Key** | | Microsoft Clarity | 热力图和会话录屏 | **Clarity Project ID** | **Clarity API Token** | | Crisp | 在线客服聊天组件 | **Crisp Website ID** | 不拉取 | ## 在分析服务商创建站点 | 厂商 | 适用场景 | | ------------------------------------------------------------------ | ------------- | | [Google Analytics](https://kernlift.dev/zh/docs/extensions/analytics/google-analytics.md) | GA4 网页访问与报表 | | [Google Ads](https://kernlift.dev/zh/docs/extensions/analytics/google-ads.md) | 加载广告标签并配置转化标签 | | [Umami](https://kernlift.dev/zh/docs/extensions/analytics/umami.md) | 云端或自托管访问统计 | | [Plausible](https://kernlift.dev/zh/docs/extensions/analytics/plausible.md) | 基于站点域名的流量统计 | | [Microsoft Clarity](https://kernlift.dev/zh/docs/extensions/analytics/clarity.md) | 热力图和访问录屏 | | [Crisp](https://kernlift.dev/zh/docs/extensions/analytics/crisp.md) | 嵌入在线客服组件 | ## 接入服务商 ### 打开分析配置 进入 **设置 → 分析配置**(`/admin/config/analytics`)。表单按服务商分为 **Google**、**Umami**、**Plausible** 和 **Clarity / Crisp** 几块,**运行检查** 面板显示每个服务商的标识是否已保存。 ### 填写服务商字段 按上方对应厂商指南中的字段对照表填写。 Token 和 API Key 字段保存后不会再显示,占位文字为 **留空则保留当前 token**。清空某个标识会移除该服务商的脚本,清空 Base URL 或 Script URL 会恢复默认值。 ### 保存 点击 **保存分析配置**。页面提示 **Analytics provider 配置已保存。**,**运行检查** 面板随之刷新。 **没有同意弹窗** 保存后,每个已配置的脚本从下一次页面加载起在站点所有页面加载,包括管理后台。系统没有 Cookie 同意弹窗,也没有按页面开关。如果业务要求先征得访客同意再统计,请在启用服务商之前自行加上同意流程。 ## 拉取服务商报表 ### 拉取 在 **分析配置** 的 **供应商报表** 卡片中点击 **拉取报表**。 ### 查看结果 Google Analytics、Umami、Plausible 和 Clarity 各自显示 **通过** 并附返回行数、**失败** 并附服务商返回的 HTTP 状态,或 **未配置** 并说明缺少哪些字段。只有标识和 API 凭据都已保存,才会请求该服务商。当前 Clarity 请求固定为 7 天,但其 Data Export API 只接受 1–3 天。服务商可能因此拒绝这项报表检查,这不能说明脚本未安装。 ## 记录自己的事件 不写代码也可以测试:在 **分析配置** 的 **上报测试事件** 卡片中保留默认值,或选择 **分类** 并填写 **事件名**,点击 **上报事件**。看到 **事件已记录。** 即表示已保存。 在受信任的服务端代码中也可以这样记录产品事件。该函数本身不做权限检查,不要直接暴露给浏览器: ```ts title="src/server/services/example.service.ts" import { trackAnalyticsEvent } from "@/server/services/analytics-support.service"; await trackAnalyticsEvent({ type: "product", name: "project_created", userId: user.id, path: "/app/projects", locale: "zh", value: 1, }); ``` `type` 取值为 `product`、`revenue`、`ai`、`api`、`acquisition`、`support` 或 `retention`。事件只保存在你的数据库中,不会发送给外部服务商。 如需按国家查看账号与已结算订单,见独立的[国家与地区](https://kernlift.dev/zh/docs/core/admin/countries.md)指南。该页面读取本地账号与订单记录,不使用服务商报表。 ## 验证 1. 关闭广告拦截扩展,用无痕窗口打开一个公开页面,例如 `/` 或 `/pricing`。 2. 查看网页源代码,找到对应脚本:Google Analytics 或 Google Ads 是 `googletagmanager.com/gtag/js`,Umami 是带有你的 `data-website-id` 的 script,Plausible 是带有你的 `data-domain` 的 script,Clarity 是 `clarity.ms/tag`,Crisp 是 `client.crisp.chat/l.js`。 3. 在服务商的实时视图中确认这次访问已被记录。Crisp 会在页面角落显示聊天气泡。 4. 保存了 Google Analytics、Umami、Plausible 或 Clarity 任一标识后,`/setup` 中 **分析供应商** 显示为就绪。 在仓库中,`pnpm validate:analytics` 会检查配置、事件、报表拉取与权限。 ## 常见问题 ### 保存时报格式错误 Google Analytics ID 必须形如 `G-XXXXXXXX`,Property ID 必须是纯数字,Google Ads ID 必须形如 `AW-XXXXXXXX`。三者都合法之前不会保存任何内容。 ### 服务商报表显示失败 服务商拒绝了请求,报告中带有 HTTP 状态和响应内容的开头部分。对于 Google Analytics,确认 access token 未过期且有权读取该媒体资源。 ### 页面上没有出现脚本 标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 **运行检查** 面板,再关闭扩展后刷新。 ### Crisp 组件显示 "Invalid website" 保存的 **Crisp Website ID** 与 Crisp 账号中的网站不一致。从 Crisp 复制正确的 ID 后重新保存。 ## 参考 * [国家与地区](https://kernlift.dev/zh/docs/core/admin/countries.md) * [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) * [Plausible docs](https://plausible.io/docs) ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) - [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) --- # Plausible > 为网站接入 Plausible。 Source: https://kernlift.dev/zh/docs/extensions/analytics/plausible ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在公开页面确认该厂商的脚本已加载。 ## 在 Plausible 完成准备 ### 添加网站 打开 [Plausible](https://plausible.io/sites)。添加网站并复制登记的域名。 ### 创建 Stats API 密钥 如需报表,在拥有该站点的团队下创建 Stats API 密钥。 官方说明 · [Stats API Key](https://plausible.io/docs/stats-api) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/analytics`。 | 来源 | 后台字段 | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | 与 Plausible 中登记的站点域名完全一致,例如 `example.com`。 | **Plausible Domain** | | Plausible → Account settings → API keys(Stats API)。 | **Plausible API Key** | | 默认填好 `https://plausible.io` 和 `https://plausible.io/js/script.js`,只有自托管 Plausible 或使用自定义脚本时才需要修改。 | **Plausible API Base URL**、**Plausible Script URL** | 保存配置。 <img src="/docs/guides/analytics/plausible.zh.png" alt="Kernlift 后台的 Plausible 配置字段" width="512" height="466" loading="lazy" /> ## 验证 1. 使用无痕窗口打开公开页面,关闭广告拦截。 2. 在页面中确认已加载带有 `data-domain` 的脚本。 ## 常见问题 ### 页面上没有出现脚本 标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 **运行检查** 面板,再关闭扩展后刷新。 ## 下一步 [添加统计分析与客服聊天](https://kernlift.dev/zh/docs/extensions/analytics.md) --- # Umami > 为网站接入 Umami。 Source: https://kernlift.dev/zh/docs/extensions/analytics/umami ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在公开页面确认该厂商的脚本已加载。 ## 在 Umami 完成准备 ### 登记域名 打开 [Umami](https://cloud.umami.is/)。在 Settings → Websites 登记网站域名,复制 Website ID。 ### 创建报表密钥 如需 Umami Cloud 报表,在 Settings → API keys 创建密钥。 官方说明 · [添加网站](https://v2.umami.is/docs/add-a-website) · [Cloud API Key](https://docs.umami.is/docs/cloud/api-key) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/analytics`。 | 来源 | 后台字段 | | -------------------------------------------------------------------------------------- | ------------------------------------------- | | Umami → Settings → Websites → 你的站点 → Website ID。 | **Umami Website ID** | | Umami Cloud → Settings → API keys。 | **Umami API Key** | | 默认填好 `https://api.umami.is` 和 `https://cloud.umami.is/script.js`,只有自托管 Umami 时才需要一起修改。 | **Umami API Base URL**、**Umami Script URL** | 保存配置。 <img src="/docs/guides/analytics/umami.zh.png" alt="Kernlift 后台的 Umami 配置字段" width="512" height="562" loading="lazy" /> ## 验证 1. 使用无痕窗口打开公开页面,关闭广告拦截。 2. 在页面中确认已加载带有 `data-website-id` 的脚本。 ## 常见问题 ### 页面上没有出现脚本 标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 **运行检查** 面板,再关闭扩展后刷新。 ## 下一步 [添加统计分析与客服聊天](https://kernlift.dev/zh/docs/extensions/analytics.md) --- # 配置邮箱密码登录 > 完成后,用户可以注册账号、验证邮箱、登录,并重置忘记的密码。 Source: https://kernlift.dev/zh/docs/extensions/auth/email-password 邮箱密码是默认的登录方式。会话密钥在环境变量中设置,注册和邮箱验证的开关在后台中控制。 ## 准备工作 * 已完成迁移的数据库和第一个管理员,见 [安装后的第一步](https://kernlift.dev/zh/docs/customize/first-steps.md)。 * 拥有 `config.read` 和 `config.write` 的管理员账号。 * 一个邮件服务商,用于投递验证邮件和重置邮件,见 [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md)。 ## 设置会话密钥和基础 URL ### 设置会话密钥 在部署环境中把 `BETTER_AUTH_SECRET` 设为一个足够长的随机值,例如 `node -e "console.log(crypto.randomUUID()+crypto.randomUUID())"` 的输出。它是认证中唯一放在环境变量里的设置,因为读取数据库之前就要用到。非开发环境下缺少它,应用无法启动。 ### 设置基础 URL 以管理员登录,进入 **设置 → 认证配置**(`/admin/config/auth`)。在 **Better Auth** 面板中把 **基础 URL** 设为部署的公网地址,例如 `https://<your-domain>`,点击 **保存**。页面显示 **配置已保存。** ## 选择账号规则 **认证配置** 页的 **Better Auth** 面板里是作用于所有账号的开关。 ### 调整开关 * **已启用**:开启或关闭邮箱密码注册与登录。在这里保存会同步更新 **邮箱登录** 面板中的 **已启用** 开关,所以请在这里修改。 * **Delete account**:允许已登录用户在 `/app/profile` 删除自己的账号。 * **邮箱验证**:开启时(默认),没有点过验证链接的用户无法登录,每次尝试登录都会重新发送验证邮件。 ### 不要改动密钥 **Secret** 已经保存了 `BETTER_AUTH_SECRET` 的值,留空即保留原值。 ### 保存 点击 **保存**。页面上每个面板只保存本面板的字段。 **修改密钥会让所有人退出登录** 在 **Secret** 中填入新值会替换原值,已有的登录会话全部失效。**邮箱验证** 开启但没有配置邮件服务商时,注册仍会成功,但新用户无法登录。 **邮箱登录** 面板中的 **允许新用户注册** 开关目前不会限制邮箱注册。 ## 验证 ### 注册账号 在浏览器无痕窗口中打开 `/auth/sign-up` 注册账号。表单提示账号已创建,并要求先验证邮箱。 ### 验证并登录 打开验证邮件中的链接,它会进入 `/auth/verify-email`。然后在 `/auth/sign-in` 登录,登录后进入 `/app/profile`。 ### 重置密码 退出登录,打开 `/auth/forgot-password`,为同一邮箱申请重置。重置邮件固定使用英文,其中的链接打开 `/auth/reset-password`,在那里设置新密码。 `/setup` 会显示会话密钥是否已设置,以及是否至少有一种可用的登录方式。要在命令行检查接入情况,运行 `pnpm validate:auth`。 ## 常见问题 ### 登录提示邮箱未验证 **邮箱验证** 处于开启状态,未验证的邮箱会被拒绝,每次尝试都会重新发送验证邮件。如果产品不需要验证邮箱,可在 **认证配置** 中关闭。收不到邮件时,检查 **邮件配置** 中的服务商,以及 `/admin/email/deliveries` 中的发送记录。 ### 应用因会话密钥报错而无法启动 `APP_ENV` 不是 `development`,且 `BETTER_AUTH_SECRET` 未设置或仍为模板值。把它设为随机值。 ### 登录后被带到 `/system/rate-limited` 每个 IP 加邮箱在 5 分钟内最多尝试登录 10 次。等窗口过去后再试。 ### 已登录用户被跳转到 `/system/session-expired` 该账号的状态是 **待审核**。在后台的用户详情页把它改为 **正常**,见 [管理用户、角色和权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 ## 参考 * [认证](https://kernlift.dev/zh/docs/core/auth.md) * [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) * [Better Auth](https://better-auth.com/docs) ## 下一步 - [接入 Google 和 GitHub 登录](https://kernlift.dev/zh/docs/extensions/auth/social.md) - [管理用户、角色和权限](https://kernlift.dev/zh/docs/core/auth/roles.md) - [认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md) - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) --- # GitHub > 让用户通过 GitHub 登录。 Source: https://kernlift.dev/zh/docs/extensions/auth/github ## 准备工作 先在 `/admin/config/auth` 的回调地址面板复制以 `/api/auth/callback/github` 结尾的完整地址。域名和协议须与登录站点一致。 **完成后**,登录页显示该厂商的登录按钮,可使用测试账号登录。 ## 在 GitHub 完成准备 ### 登记 OAuth 应用 打开 [GitHub](https://github.com/settings/developers)。创建 OAuth App,填写站点首页。 ### 填写回调地址 将后台显示的 GitHub 回调地址粘贴到 Authorization callback URL。 ### 生成客户端密钥 生成 Client Secret,再从同一应用复制 Client ID。 官方说明 · [GitHub 创建 OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/auth`。 | 来源 | 后台字段 | | ------------- | ------------- | | Client ID | Client ID | | Client secret | Client Secret | 启用此登录方式。要接受首次登录的用户,勾选 **允许新用户注册** 并保存。 <img src="/docs/guides/auth/github.zh.png" alt="Kernlift 后台的 GitHub 配置字段" width="512" height="464" loading="lazy" /> ## 验证 1. 在无痕窗口打开 `/auth/sign-in`,选择 GitHub。 2. 完成授权,确认回到站点并处于已登录状态。 ## 常见问题 ### 提供方拒绝跳转 在 Google 或 GitHub 登记的回调地址与 **回调 URL** 面板中的不一致。重新复制一次,协议和域名都要一致。 ## 下一步 [接入 Google 和 GitHub 登录](https://kernlift.dev/zh/docs/extensions/auth/social.md) --- # Google > 让用户通过 Google 登录。 Source: https://kernlift.dev/zh/docs/extensions/auth/google ## 准备工作 先在 `/admin/config/auth` 的回调地址面板复制以 `/api/auth/callback/google` 结尾的完整地址。域名和协议须与登录站点一致。 **完成后**,登录页显示该厂商的登录按钮,可使用测试账号登录。 ## 在 Google 完成准备 ### 配置同意屏幕 打开 [Google](https://console.cloud.google.com/auth/clients)。配置 OAuth 同意屏幕;应用处于测试状态时将测试账号加入允许列表。 ### 创建 Web 客户端 创建类型为 Web 应用的客户端。 ### 登记回调 URI 在已获授权的重定向 URI 粘贴后台显示的 Google 回调地址,复制 Client ID 和 Client Secret。 官方说明 · [Google Web OAuth 官方说明](https://developers.google.com/identity/protocols/oauth2/web-server) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/auth`。 | 来源 | 后台字段 | | ------------- | ------------- | | Client ID | Client ID | | Client secret | Client Secret | 启用此登录方式。要接受首次登录的用户,勾选 **允许新用户注册** 并保存。 <img src="/docs/guides/auth/google.zh.png" alt="Kernlift 后台的 Google 配置字段" width="512" height="464" loading="lazy" /> ## 开启 Google One Tap(可选) One Tap 会在登录和注册页弹出 Google 的“以 … 身份继续”提示,已登录 Google 的访客一次点击即可登录或注册。它复用上面的 Google 客户端。 1. 在 Google 客户端的**已获授权的 JavaScript 来源**中加入站点源,例如 `https://<你的域名>`。来源不在列表中时 One Tap 会被拒绝。 2. 在 `/admin/config/auth` 的 Google 面板打开 **Google One Tap** 并保存。只有 Google 登录已启用、Client ID 和 Client Secret 都已保存时才生效。 开启期间,Better Auth 提供 `POST /api/auth/one-tap/callback`,用你的 Client ID 校验 Google 签发的 ID token;关闭时这个端点不存在。只有勾选了 **允许新用户注册**,首次使用的用户才能通过 One Tap 注册;被封禁的用户仍会被拒绝。 ## 验证 1. 在无痕窗口打开 `/auth/sign-in`,选择 Google。 2. 完成授权,确认回到站点并处于已登录状态。 3. 开启 One Tap 后,在已登录 Google 的浏览器中打开 `/auth/sign-in`。提示出现后选择账号,即可登录并回到原本要去的页面。 ## 常见问题 ### One Tap 提示没有出现 确认 Google 登录已启用且 Client ID 和 Client Secret 已保存、**Google One Tap** 已打开、站点源已加入**已获授权的 JavaScript 来源**。访客关闭过提示后,Google 也会在一段时间内不再显示。 ### 提供方拒绝跳转 在 Google 或 GitHub 登记的回调地址与 **回调 URL** 面板中的不一致。重新复制一次,协议和域名都要一致。 ## 下一步 [接入 Google 和 GitHub 登录](https://kernlift.dev/zh/docs/extensions/auth/social.md) --- # 接入 Google 和 GitHub 登录 > 完成后,登录页和注册页会显示 Google 或 GitHub 按钮,用户可以用已有账号直接登录。 Source: https://kernlift.dev/zh/docs/extensions/auth/social Google 和 GitHub 登录在后台中分别开启。每个提供方都需要在对方平台登记一个 OAuth 应用,修改在下一次登录时生效,无需重启。 ## 准备工作 * 一个有公网地址的部署,并已在 **认证配置** 中设置 **基础 URL**,见 [配置邮箱密码登录](https://kernlift.dev/zh/docs/extensions/auth/email-password.md)。 * 拥有 `config.read` 和 `config.write` 的管理员账号。 * 可以创建 OAuth 应用的 Google Cloud 项目或 GitHub 账号。 ## 登记 OAuth 应用 | 厂商 | 适用场景 | | ----------------------------------------- | ------------------------- | | [Google](https://kernlift.dev/zh/docs/extensions/auth/google.md) | 使用 Google Web OAuth 客户端登录 | | [GitHub](https://kernlift.dev/zh/docs/extensions/auth/github.md) | 通过 GitHub OAuth 应用登录 | ## 开启提供方 ### 填入凭证 在 **Google 登录** 或 **GitHub 登录** 面板中,填入 OAuth 应用页面上的 **Client ID** 和 **Client Secret**。凭证保存后不会再显示。留空即保留已保存的值。 ### 调整开关 * **已启用**:在登录页和注册页显示该提供方的按钮。 * **允许新用户注册**:关闭后,该提供方只允许已有账号的用户登录。 ### 保存 点击该面板中的 **保存**。**登录渠道** 面板会显示哪些登录方式已启用。 **缺少凭证的按钮** 按钮已启用但缺少 Client ID 或 Client Secret 时,点击后只显示需要先配置凭证的提示,不会跳转。 ## 服务商 <TypeTable type="{ google: { type: "clientId + clientSecret", default: "未配置", description: "回调地址:每个登录来源上的 /api/auth/callback/google,包括 localhost。", }, github: { type: "clientId + clientSecret", default: "未配置", description: "回调地址:/api/auth/callback/github。", }, }" /> 没有凭据的服务商会解析成禁用的服务商,登录页不提供它。 ## 验证 在浏览器无痕窗口中打开 `/auth/sign-in`,点击 **使用 Google 登录** 或 **使用 GitHub 登录**。在提供方页面授权后会进入 `/app/profile`。`pnpm validate:auth` 也会检查未配置状态和 **认证配置** 页的接入情况。 ## 常见问题 ### 提供方拒绝跳转 在 Google 或 GitHub 登记的回调地址与 **回调 URL** 面板中的不一致。重新复制一次,协议和域名都要一致。 ### 用户被带到 `/auth/error` 跳转之后 OAuth 交换失败。确认 **Client Secret** 与 **Client ID** 属于同一个应用。在提供方重新生成过 secret 的,需要重新填入。 ### 新用户无法用提供方登录 该提供方的 **允许新用户注册** 已关闭,只有已有账号能使用。打开开关并点击 **保存**。 ## 参考 * [认证](https://kernlift.dev/zh/docs/core/auth.md) * [Better Auth social providers](https://better-auth.com/docs/authentication/google) * [Google OAuth](https://developers.google.com/identity/protocols/oauth2) ## 下一步 - [管理用户、角色和权限](https://kernlift.dev/zh/docs/core/auth/roles.md) - [配置邮箱密码登录](https://kernlift.dev/zh/docs/extensions/auth/email-password.md) - [认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md) --- # 用 CMS 发布内容 > 在管理后台用中英文撰写、发布和整理博客文章、法务页面、更新日志与路线图。 Source: https://kernlift.dev/zh/docs/extensions/cms CMS 模块在 `/blog` 发布博客(RSS 为 `/blog/rss.xml`),在 `/legal/<slug>` 发布法务页面,并提供 `/changelog` 和 `/roadmap`。每次保存都会保留一条修订并运行 SEO 检查。 ## 准备工作 * 一个能在本地运行的项目,见[快速开始](https://kernlift.dev/zh/docs/quick-start.md)。`cms` 模块已经在底座仓库里,入口是后台侧边栏 **内容** 分组下的 **CMS**。 * 管理员账号:`cms.read` 用于打开页面;新建或保存条目、新增分类术语还需要 `cms.write`。**Content Manager** 角色同时包含两者。 **页脚链接需要已发布的条目** 公开页脚链接到 `/blog`、`/legal/privacy` 和 `/legal/terms`。安装后请发布 `privacy` 和 `terms` 两个法务条目,否则这些链接会进入未找到页面。 ## 新建条目 ### 开始新建 进入 **内容 → CMS**(`/zh/admin/cms`)。在 **文章** 标签页点击 **新建内容**,选择 **类型**:**博客文章**、**页面**、**法务**、**更新日志**、**路线图** 或 **案例**。类型创建后不能再修改。 ### 填写字段 * **标题**、**摘要** 和 **Markdown**:条目内容。Markdown 只渲染 `#`、`##` 标题和段落。 * **Slug**:保存时转为小写,其他字符替换为连字符,`Launch Notes` 会保存为 `launch-notes`。 * **语言**:**English** 或 **中文**。中文条目显示在 `/zh` 路径下。 * **分类** 和 **标签**(用逗号分隔):自由填写。 * **SEO 标题** 和 **SEO 描述**。 * **OG 图片**:社交分享预览图的路径或 URL。留空则保留当前图片。 ### 创建 点击 **创建内容**。条目会连同第一条修订一起保存,并在编辑器中打开。类型、Slug 和语言三者组合必须唯一;新建永远不会替换已有条目。 ## 发布条目 ### 打开条目 在对应标签页点击条目标题进入编辑器。路线图条目没有标签页,可直接打开 `/zh/admin/cms/editor/cms_roadmap_<locale>_<slug>`。 ### 发布 把 **状态** 设为 **已发布** 并点击 **保存内容**,条目就会出现在对应语言的公开页面上。 改回 **草稿** 或 **已归档** 后,条目会从列表中移除,详情页显示未找到状态。首次发布时间会保留,重新发布时继续使用。每次保存都会记录一条修订,**修订** 卡片显示修订数量。 | 标签页 | 内容 | | -------- | ----------------------- | | **文章** | 博客文章,发布在 `/blog` | | **页面** | page 和 showcase 类型的条目 | | **更新日志** | 发布在 `/changelog` 的条目 | | **法务** | 发布在 `/legal/<slug>` 的条目 | | **分类** | 分类、标签和模块及其使用次数 | | **SEO** | 每次保存产生的检查结果 | ## 处理 SEO 警告 ### 打开 SEO 标签页 每次保存都会为条目新增三项检查:SEO 标题 10 到 70 个字符、SEO 描述 50 到 160 个字符、Slug 为小写连字符格式。 ### 修改后重新保存 未通过的检查显示 `warn`。在编辑器中调整对应字段后点击 **保存内容**。 ## 新增分类术语 ### 打开分类 打开 **分类** 标签页。 ### 填写新增术语 选择 **类型**(**分类**、**标签** 或 **模块**)和 **语言**,填写 **标签**、**Slug** 以及可选的 **描述**。 ### 保存 点击 **新增术语**。术语出现在表格中,使用次数统计分类或标签与该 slug 相同的条目。 ## 验证 1. 新建一篇 **博客文章**,把 **状态** 设为 **已发布** 并点击 **保存内容**。 2. 中文条目打开 `/zh/blog`:文章出现在列表中,可以通过 `/zh/blog/<slug>` 访问,`/zh/blog/rss.xml` 也包含它。 3. 在仓库中运行 `pnpm validate:cms`。 ## 常见问题 ### 出现 "An entry with this type, locale and slug already exists." **新建内容** 发现已有类型、语言和 slug 相同的条目。请从列表中打开已有条目,或换一个 slug。 ### 出现 "CMS slug, locale, and type must be unique." 已有条目使用了相同的类型、slug 和语言。请修改 slug。 ### 文章或法务页面显示未找到 条目是草稿或已归档,或者语言与 URL 不一致。把 **状态** 设为 **已发布**,并在 `/zh` 路径下访问中文条目。 ### 条目没有出现在 `/blog` 列表只显示已发布且语言与 URL 一致的条目。中文条目出现在 `/zh/blog`,而不是 `/blog`。 ### 显示「没有此 id 的内容。」 编辑器地址指向不存在的条目。请从列表中打开条目。 ## 参考 * [底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md) * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [MDX](https://mdxjs.com/docs/) ## 下一步 - [插件](https://kernlift.dev/zh/docs/core/plugins.md) - [管理用户、角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) --- # 积分账本 > 积分如何以只追加账本加余额快照的方式存储,以及冻结、扣除与退还如何让计量计费保持准确。 Source: https://kernlift.dev/zh/docs/extensions/credits 积分是产品为 AI 任务等计量型工作计费的单位。每一次变动都是只追加账本中的一条记录,余额是一份可以从账本重建的快照。配置积分见[按积分计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md)。 ## 两个余额 每个用户有两个余额。 | 余额 | 含义 | | ------ | ------------------ | | **可用** | 用户当前可以花费的积分 | | **冻结** | 为已开始但尚未结束的工作而冻结的积分 | 每个用户有一行快照,同时保存这两个余额,以及累计购买和累计使用两个总数。新用户从零开始,除非在 `/admin/config/auth` 开启了注册奖励。 ## 每次变动都是一条账本记录 所有写入都经过同一个函数,对每条记录它会: 1. 拒绝非正数的金额。 2. 把这条记录的变动应用到可用和冻结余额上。 3. 如果任一余额会变为负数,拒绝写入。 4. 追加这条记录,包含变动量和变动后的余额。 5. 更新快照:发放和购买增加累计购买,扣除增加累计使用。 6. 写入一条审计日志。 记录不会修改或删除,所以账本保留了用户积分的完整历史。 | 操作 | 记录类型 | 可用 | 冻结 | | ----------------------- | ------------ | --------- | --------- | | 管理员发放 | `grant` | `+amount` | 0 | | 注册奖励(来源 `signup.bonus`) | `grant` | `+amount` | 0 | | 管理员扣减 | `adjustment` | `-amount` | 0 | | 购买(方案积分) | `purchase` | `+amount` | 0 | | 冻结 | `reserve` | `-amount` | `+amount` | | 扣除 | `capture` | 0 | `-amount` | | 退还 | `refund` | `+amount` | `-amount` | ## 先冻结,再扣除或退还 计量型工作先冻结价格,再扣除或退还: | 冻结状态 | 何时进入 | 账本效果 | | ---------- | ---------------- | -------- | | `reserved` | 工作开始,且可用余额足以覆盖价格 | 可用转为冻结 | | `captured` | 工作成功 | 冻结部分被消耗 | | `refunded` | 工作失败 | 冻结部分退回可用 | 一笔冻结只会结算一次。对已结算、不存在或属于其他用户的冻结执行扣除或退还都会抛错,所以重试不会重复扣费。可用余额不足时工作不会开始,用户会跳转到 `/system/insufficient-credits`。 ## AI 工作如何使用它 * **任务**在调用服务商之前冻结解析出的渠道价格,成功时扣除,失败时退还。异步任务在最终状态经 Webhook 或轮询到达时结算。 * **对话**在调用模型前冻结一个预估金额。流结束后退还这笔预冻结,按实际 Token 用量计算的金额重新冻结并立即扣除。扣除失败则退还。 价格如何解析,见 [AI 渠道、场景与任务生命周期](https://kernlift.dev/zh/docs/extensions/ai.md)。 ## 注册奖励每个用户只发放一次 注册奖励开启时,Better Auth 的用户创建钩子为每个新用户发放,无论通过哪种方式注册。账本记录 id 按用户固定(`credit_entry_signup_<userId>`),重复调用会发现已有记录,并发的重复写入会在余额变动前失败。发放失败只记日志,不会阻断注册。开关和数量是后台设置,不是环境变量,见[按积分计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md)。 ## 方案积分每个订单只发放一次 已支付订单结算时,方案附带的积分以 `purchase` 记录的形式加入,来源为 `billing.order.<orderId>`。如果同一用户已有该来源的记录,就跳过发放,因此 Webhook 和回调结算同一订单时积分只会加一次。见[支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md)。 ## 重算与修复 账本是事实来源,所以快照随时可以核对。重算会累加每条记录的变动量,并报告是否与快照一致。用户可以对自己的余额执行这项只读检查。修复需要 `credits.write` 权限,它把重算结果写回快照、重建累计总数,并在审计日志中记录修复前后的值。 ## 尚未实现过期 schema 接受 `expire` 记录类型,后台账本也可以按它筛选,但没有任何代码写入 `expire` 记录,发放也不带过期日期。积分不会过期。要加入过期机制,需要为每次发放保存过期时间(两种方言下的 schema 变更),并通过同一个账本函数写入 `expire` 记录。 ## 相关文件 - 账本/ - src/server/services/credits-ledger.service.ts - src/server/db/repositories/credits-ledger.repository.ts - src/server/db/repositories/credits-config.repository.ts - 工作台/ - src/components/credits/credits-workspace.tsx ## 下一步 - [按积分计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md) - [AI 渠道、场景与任务生命周期](https://kernlift.dev/zh/docs/extensions/ai.md) - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) --- # 用积分对用量计费 > 完成后,用户通过方案或手动发放获得积分余额,AI 任务等按量计费的工作从余额中扣除。 Source: https://kernlift.dev/zh/docs/extensions/credits/usage 积分是产品对按量计费的工作收费的单位。用户通过付费方案、运营人员发放或注册奖励获得积分。每个任务在运行前先冻结价格,工作成功后才扣除。积分不需要服务商和环境变量,除非开启注册奖励,新用户余额为零;积分不会过期。 ## 准备工作 * 拥有 `credits.read` 和 `credits.write` 的管理员账号。要在方案上设置积分还需要 `products.write`;内置的 **Commerce Manager** 角色已包含产品和积分相关权限。 * 如果希望买家付款后拿到方案积分,需要先接入支付服务商,见 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 ## 给用户积分 **通过方案** ### 打开方案 进入 **商业化 → 产品**(`/admin/products`),点击产品键,在 **定价方案** 卡片中选择一个方案。 ### 填写数量 在 **包含积分** 中填入数量,点击 **保存方案**。不附带积分的方案保持 `0` 即可。 该方案的订单付款后,买家会获得这些积分;即使服务商重复推送付款事件,也只发放一次。发放时优先读取 `en` 那一行方案,所以请在 `en` 方案上设置 **包含积分**,其他语言填同样的数字。 **手动发放** ### 找到用户 进入 **概览 → 用户**(`/admin/users/dashboard`)。 ### 填写变动 在该用户的 **积分操作** 一栏输入数量,并填写至少两个字符的变更说明。 ### 执行 点击 **赠送** 或 **扣除**。扣除不能让可用余额变成负数。 这次变动会带着你的说明出现在该用户的账本中,并记录到审计日志。 **注册奖励** ### 打开注册奖励 进入 **设置 → 认证配置**(`/admin/config/auth`),找到 **注册奖励** 面板。保存需要 `config.write`。 ### 设置数量 打开 **注册时赠送积分**,填写 **每个新用户赠送的积分**(0 到 1,000,000 的整数),点击 **保存**。 保存之后新建的每个用户都会获得一次奖励,无论通过邮箱密码、Google、GitHub 还是 Google One Tap 注册;已有用户不会补发。奖励记为类型 `grant`、来源 `signup.bonus` 的账本记录,同一用户永远不会得到第二次。发放出错时注册照常成功,错误写入日志,可以改为手动发放。 ## 设置工作的价格 AI 任务的积分价格在 **设置 → AI 配置** 中设置:每个任务固定价格、按请求参数定价,或按 Token 用量计费。操作见 [设置场景路由和定价](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)。任务价格高于可用余额时,在调用服务商之前就会被拒绝。 ## 为自己的功能收取积分 工作开始前先冻结价格,然后对这笔预留只结算一次:成功时扣除,失败时退还。先解析出用户,再在服务端代码中调用。 ```ts title="src/server/services/export.service.ts" import { captureAiTaskCredits, refundAiTaskCredits, reserveAiTaskCredits, } from "@/server/services/credits-ledger.service"; const { reservationId } = await reserveAiTaskCredits({ userId, taskId: `export_${jobId}`, amount: 5, }); try { await runExport(jobId); await captureAiTaskCredits({ reservationId, userId }); } catch (error) { await refundAiTaskCredits({ reservationId, userId }); throw error; } ``` 可用余额不足时预留会失败,错误信息包含 `/system/insufficient-credits`,界面可以据此跳转。把 `reservationId` 与任务一起保存,让重试或轮询程序结算同一笔预留。 **不要让用户直接改动余额** 不要新增可由用户调用的发放、预留、扣除、退还或修复积分的 server function。面向用户的函数只读并绑定当前会话用户,否则 `pnpm validate:session-owner` 会失败。 ## 查看或修复余额 ### 打开用户 在 **概览 → 用户** 的用户行点击 **详情**。**积分** 卡片显示当前余额和最近的账本记录。 ### 必要时修复 如果余额和账本对不上(例如有人直接改过数据库),点击 **修复余额快照**。系统会根据账本重建余额,并把修复前后的数值写入审计日志。 ## 验证 ### 给测试用户发放 10 积分 手动发放 10 积分,以该用户登录并打开 `/app/credits`。可用余额显示 10,账本里能看到这次发放。 ### 购买方案 在服务商测试模式下购买一个设置了 **包含积分** 的方案,刷新 `/app/credits`。方案积分以一条购买记录出现。 ### 注册新用户 开启注册奖励后注册一个新账号并打开 `/app/credits`。账本中有一条数量等于设置值的 `signup.bonus` 发放记录。 ### 用完积分 发起一个价格高于剩余余额的 AI 任务。任务不会被创建,用户会被带到 `/system/insufficient-credits`。 用户在 `/app/credits/ledger` 查看完整账本和余额是否一致的标识,在 `/app/credits/reservations` 查看预留和退还记录。`pnpm validate:credits` 会检查积分不足的处理、余额偏差修复和页面接线。 ## 常见问题 ### 任务因积分不足失败 可用余额低于任务价格。仍在运行的任务所冻结的积分不计入可用余额。发放积分或购买设置了 **包含积分** 的方案,然后重试。 ### `Reservation is already settled.` 该预留已被扣除或退还。每笔预留只结算一次,重试扣除或退还前先检查它的状态。 ### 账本页面显示余额不一致 存储的余额不再等于账本之和,通常是直接修改了数据库。在后台打开该用户,点击 **修复余额快照**。 ### 付费方案没有增加积分 确认方案 `en` 那一行的 **包含积分** 大于零,并在 **商业化 → 订单** 中确认订单已付款。如果订单仍为待付款,参考 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 ## 参考 * [积分账本](https://kernlift.dev/zh/docs/extensions/credits.md) * [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md) * [Double-entry bookkeeping](https://en.wikipedia.org/wiki/Double-entry_bookkeeping) ## 下一步 - [积分账本](https://kernlift.dev/zh/docs/extensions/credits.md) - [设置场景路由和定价](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) - [销售产品和方案](https://kernlift.dev/zh/docs/extensions/payments/products.md) --- # 编写自定义数据库适配器 > 为 Postgres 或 SQLite schema 家族注册自己的连接方式,并用 DATABASE_ADAPTER 选择它。 Source: https://kernlift.dev/zh/docs/extensions/database/custom-adapter 数据库连接通过适配器注册表解析。内置适配器有 `sqlite`、`postgres`、`turso` 和 `d1`;你可以注册自己的适配器,例如使用公司内部的 Postgres 驱动或连接池。 ## 准备工作 * 面向已有 schema 家族(`postgres` 或 `sqlite`)的 Drizzle 兼容数据库客户端。 * 服务端代码中一个在首次访问数据库之前执行的位置。 **同一 schema,不同连接** 适配器只改变应用的连接方式。全新的 SQL 方言(例如 MySQL)还需要自己的 schema 文件、迁移链和仓储分支。 ## 注册适配器 ### 调用 `registerDatabaseAdapter` 在第一次调用 `getDatabase()` 之前注册: ```ts title="src/server/db/my-company-postgres.ts" import { registerDatabaseAdapter } from "./client"; registerDatabaseAdapter({ id: "my-company-postgres", dialect: "postgres", runtime: "my-company-postgres", canHandle: ({ config }) => Boolean(config.database.url), create: ({ config }) => ({ adapter: "my-company-postgres", dialect: "postgres", runtime: "my-company-postgres", db: createMyDrizzlePostgresClient(config.database.url), }), missingPackageHint: "Set DATABASE_URL to use my-company-postgres.", }); ``` `canHandle` 返回适配器能否在当前环境运行。`create` 返回 Drizzle 数据库对象。`missingPackageHint` 可选,`canHandle` 返回 false 时会附加在错误信息后面。 ### 选择它 ```bash title=".env" DATABASE_DIALECT=postgres DATABASE_ADAPTER=my-company-postgres DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgres ``` `DATABASE_DIALECT` 必须与适配器的 `dialect` 一致,迁移才会使用正确的迁移链。 ### 迁移 ```bash pnpm db:migrate ``` 适配器注册与解析入口在 `adapter-registry.ts`:`registerDatabaseAdapter`、`listDatabaseAdapters` 和 `resolveDatabaseAdapter`。 ## 验证 * 选择该适配器后应用可以启动,`/admin` 能正常加载。 * `pnpm validate:db-adapters` 通过。 ## 常见问题 ### 出现 `DATABASE_ADAPTER="…" is not registered.` 适配器在首次访问数据库之后才注册,或没有注册。错误信息会列出已注册的 id。把注册提前。 ### 出现 `Database adapter "…" cannot run in this environment.` `canHandle` 返回了 false,例如 `DATABASE_URL` 为空。消息末尾附有你的 `missingPackageHint`。 ### 出现 `Database adapter "…" is already registered` 已有同 id 的适配器。换一个 id。 ## 参考 * [运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md) * [环境变量](https://kernlift.dev/zh/docs/reference/env.md) * [Drizzle ORM](https://orm.drizzle.team/docs/overview):`create` 返回的客户端 * [Drizzle 迁移](https://orm.drizzle.team/docs/migrations):为什么方言决定迁移链 ## 下一步 - [使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md) - [运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [架构与分层](https://kernlift.dev/zh/docs/guide/architecture.md) --- # Neon > 在 Neon 托管应用数据库。 Source: https://kernlift.dev/zh/docs/extensions/database/neon ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,完成数据库迁移,应用可以通过运行时连接读取数据。 ## 在 Neon 完成准备 ### 选择分支和数据库 打开 [Neon](https://console.neon.tech/)。创建项目并选择目标分支和数据库。 ### 复制迁移连接地址 在 Connect 复制非池化连接地址用于迁移,运行时选用支持预处理语句的连接。 官方说明 · [Neon 连接文档](https://neon.com/docs/connect/connect-from-any-app) ## 填写项目配置 在执行迁移的服务端环境填写下列值。数据库类型填 `postgres`。 | 连接信息 | 服务端环境变量 | | ---------------- | ----------------- | | Postgres URL | DATABASE\_URL | | Database dialect | DATABASE\_DIALECT | 使用目标数据库运行 `pnpm db:migrate`,再为应用部署配置运行时连接。 ## 验证 1. 查看迁移输出,确认迁移成功。 2. 启动应用,用管理员账号打开 `/admin`。 ## 常见问题 ### 出现 `DATABASE_URL is required when DATABASE_ADAPTER=postgres` 连接串为空。设置 `DATABASE_URL`。 ## 下一步 [使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md) --- # 使用 Postgres 与 Supabase > 把应用指向任意 Postgres 数据库(包括 Supabase 与 Neon),并用迁移链构建 schema。 Source: https://kernlift.dev/zh/docs/extensions/database/postgres 任何 Postgres 数据库都通过通用的 Drizzle Postgres 适配器接入。Supabase 和 Neon 是同一代码路径上的托管 Postgres 端点。应用不使用 Supabase SDK、认证助手、存储 API 或行级安全策略。 ## 准备工作 * 一个 Postgres 数据库及其连接串,例如 Supabase 的 **Project Settings → Database**。 * 一台能连上该数据库、用于执行迁移的机器。 * 一个空数据库。不是由迁移链创建的 schema 无法原地迁移。 ## 在托管平台创建数据库 | 厂商 | 适用场景 | | ------------------------------------------------- | ----------- | | [Supabase](https://kernlift.dev/zh/docs/extensions/database/supabase.md) | 直连或会话连接池 | | [Neon](https://kernlift.dev/zh/docs/extensions/database/neon.md) | 按分支获取数据库连接串 | ## 连接数据库 ### 设置连接 ```bash title=".env" DATABASE_DIALECT=postgres DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgres ``` `DATABASE_ADAPTER` 可以不设置,默认为 `postgres`。 ### 构建 schema ```bash pnpm db:migrate ``` 这会应用 `drizzle/migrations/postgres` 下的 Postgres 迁移链。 ### 创建管理员 ```bash SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin ``` **凭据只留在服务端** 不要把连接串或 Supabase service-role 密钥暴露给客户端代码。Supabase 的 Data API 若已暴露这些表,需限制角色授权,并对暴露表启用及审查行级安全策略。本项目的服务端权限不会自动保护该 API。 ## 使用托管 Postgres Supabase 和 Neon 使用同一套 Postgres 适配器与迁移链。迁移优先用直连,运行期使用上文选定的连接方式;应用不需要服务商 SDK。修改 schema 时,Postgres 与 SQLite 两条迁移链都要添加对应迁移。 ## 生产环境里连接从哪里来 部署如何连上 Postgres,取决于 `deploy.config.json` 里记录的平台。上面的步骤适用于本地使用和在检出目录里迁移;生产环境里连接这样提供: | 平台 | 应用如何连接 | schema 如何迁移 | | ---------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Cloudflare | 经 Hyperdrive:`DATABASE_ADAPTER=hyperdrive`,加上 `wrangler.jsonc` 里的 `HYPERDRIVE` 绑定。Worker 不持有 `DATABASE_URL` | 在检出目录里把 `DATABASE_URL` 设为 Postgres URL,执行 `pnpm db:migrate` | | Fly.io | `DATABASE_URL` 作为应用密钥 | 每次部署时的 `release_command` | | Railway | `.railway/railway.ts` 里声明的 Postgres,它的 `DATABASE_URL` 会传给各个服务 | `web` 服务的 pre-deploy 步骤 | | Docker | compose 自带的 `postgres` 服务,`POSTGRES_PASSWORD` 来自 `.env.production` | compose 的 `migrate` 服务 | 在 Workers 上,Postgres 客户端只存活一个请求,连接池由它背后的 Hyperdrive 负责。见[部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md)、[部署到 Fly.io](https://kernlift.dev/zh/docs/deploy/fly.md)、[部署到 Railway](https://kernlift.dev/zh/docs/deploy/railway.md)和[用 Docker Compose 部署](https://kernlift.dev/zh/docs/deploy/docker.md)。 ## 验证 ```bash pnpm validate:db-adapters ``` 然后启动应用,以管理员身份登录并打开 `/admin`。 ## 常见问题 ### 出现 `DATABASE_URL is required when DATABASE_ADAPTER=postgres` 连接串为空。设置 `DATABASE_URL`。 ### `pnpm db:migrate` 报告已有 schema 数据库中存在不是由迁移链创建的表。删库重建后再运行 `pnpm db:migrate`。 ### 需要运行 `pnpm db:generate` 吗? 不需要。generate 用于为 schema 变更写出新迁移,并不用于准备数据库。 ## 参考 * [环境变量](https://kernlift.dev/zh/docs/reference/env.md) * [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) * [Postgres.js](https://github.com/porsager/postgres):这个适配器加载的驱动 * [Supabase 连接串](https://supabase.com/docs/guides/database/connecting-to-postgres) ## 下一步 - [运行 Node 构建](https://kernlift.dev/zh/docs/deploy/node.md) - [编写自定义数据库适配器](https://kernlift.dev/zh/docs/extensions/database/custom-adapter.md) - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) --- # Supabase > 在 Supabase 托管应用数据库。 Source: https://kernlift.dev/zh/docs/extensions/database/supabase ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,完成数据库迁移,应用可以通过运行时连接读取数据。 ## 在 Supabase 完成准备 ### 创建项目 打开 [Supabase](https://supabase.com/dashboard/projects)。创建 Postgres 项目并保存数据库密码。 ### 复制数据库连接 在 Connect 复制用于迁移的直连地址;仅支持 IPv4 的主机可查看 Session pooler 地址。 官方说明 · [Supabase 连接方式](https://supabase.com/docs/guides/database/connecting-to-postgres) · [保护 Data API](https://supabase.com/docs/guides/api/securing-your-api) ## 填写项目配置 在执行迁移的服务端环境填写下列值。数据库类型填 `postgres`。 | 连接信息 | 服务端环境变量 | | ---------------- | ----------------- | | Postgres URL | DATABASE\_URL | | Database dialect | DATABASE\_DIALECT | 使用目标数据库运行 `pnpm db:migrate`,再为应用部署配置运行时连接。 ## 验证 1. 查看迁移输出,确认迁移成功。 2. 启动应用,用管理员账号打开 `/admin`。 ## 常见问题 ### 出现 `DATABASE_URL is required when DATABASE_ADAPTER=postgres` 连接串为空。设置 `DATABASE_URL`。 ## 下一步 [使用 Postgres 与 Supabase](https://kernlift.dev/zh/docs/extensions/database/postgres.md) --- # 使用 Turso > 通过 SQLite schema 分支和 turso 适配器,在 Turso libSQL 数据库上运行应用。 Source: https://kernlift.dev/zh/docs/extensions/database/turso Turso 提供的 libSQL 兼容 SQLite。应用仍然使用 SQLite 的 schema 和 SQLite 的迁移链,只更换客户端。`DATABASE_DIALECT` 保持 `sqlite`,另外设置 `DATABASE_ADAPTER=turso`。 ## 准备工作 * 一个 Turso 数据库,拿到它的地址和令牌:`turso db show --url <name>` 和 `turso db tokens create <name>`。 * `@libsql/client`,项目已经把它列为依赖。数据库层用 `require.resolve` 探测它,只有选了 `turso` 适配器才加载,所以 SQLite 或 Postgres 部署不会加载它。 * 后台不用配任何东西。数据库连接是少数几个仍然留在环境变量里的设置之一。见[配置模型](https://kernlift.dev/zh/docs/core/configuration.md)。 ## 在 Turso 创建数据库 按 [Turso CLI 文档](https://docs.turso.tech/cli/db/create)安装并登录 CLI,然后执行 `turso db create <数据库名>`。从 `turso db show --url <数据库名>` 复制 `libsql://` 地址,再用 `turso db tokens create <数据库名>` 创建应用令牌。将这两个值分别填入下面的 `DATABASE_URL` 和 `DATABASE_AUTH_TOKEN`。CLI 的登录凭据不是应用数据库令牌。令牌只在服务端保存,部署环境也要设置同样两个值。见 [Turso 令牌说明](https://docs.turso.tech/cli/db/tokens/create)。 ## 连接数据库 ### 设置连接 ```bash title=".env" DATABASE_DIALECT=sqlite DATABASE_ADAPTER=turso DATABASE_URL=libsql://YOUR-DATABASE.turso.io DATABASE_AUTH_TOKEN=YOUR-TURSO-TOKEN ``` 两个值缺任何一个,适配器都会在启动时报错。它不会退回本地文件,所以配错的部署不会写入错误的数据库。 ### 构建 schema ```bash pnpm db:migrate ``` 它应用的是 `drizzle/migrations/sqlite`,和本地 SQLite 文件、Cloudflare D1 用的是同一条链。Turso 不需要单独的迁移。 ### 创建管理员 ```bash SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin ``` 它同时写入角色、权限和默认限流规则。可以重复执行。它只补充缺失的数据,不覆盖运营修改过的内容。 ## 适配器如何选择 `DATABASE_DIALECT=sqlite` 选择 SQLite schema 与迁移链,`DATABASE_ADAPTER=turso` 选择 libSQL 客户端。缺少 `libsql://` 地址、令牌或 `@libsql/client` 依赖时,适配器会在启动时报错。启动字段见[环境变量](https://kernlift.dev/zh/docs/reference/env.md)。 内置的 `sqlite`、`postgres`、`d1` 和 `turso` 适配器与自定义适配器一样,通过 `registerDatabaseAdapter` 注册。 ## 验证 ```bash pnpm validate:db-adapters ``` 然后启动应用,用管理员登录并打开 `/admin`。另外再做两项检查: 1. 去掉 `DATABASE_AUTH_TOKEN` 再启动。它会抛 `DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso`,不会打开本地文件。 2. 在后台写入一条数据(比如发放一张许可证),然后用 Turso CLI 读这一行。CLI 读到的就是应用写入的那一行。 ## 故障排查 ### `DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso` 用 `turso db tokens create <name>` 创建令牌并设置它。 ### `DATABASE_URL is required when DATABASE_ADAPTER=turso` 把 `DATABASE_URL` 设为 `turso db show --url <name>` 给出的 `libsql://` 地址。 ### 适配器根本没被选中 `canHandle` 还要求 `@libsql/client` 能被解析到。刚克隆完的仓库先运行 `pnpm install`。 ## 参考 * [环境变量](https://kernlift.dev/zh/docs/reference/env.md) * [运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md) * [Turso 文档](https://docs.turso.tech/) * [Drizzle 配合 libSQL](https://orm.drizzle.team/docs/get-started-sqlite#turso) ## 下一步 - [编写自定义数据库适配器](https://kernlift.dev/zh/docs/extensions/database/custom-adapter.md) 四个内置适配器实现的是同一个接口。 - [运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md) 各运行时适用的适配器及原因。 - [使用 Postgres](https://kernlift.dev/zh/docs/extensions/database/postgres.md) 另一种方言,有自己的迁移链。 - [部署到 Node 主机](https://kernlift.dev/zh/docs/deploy/node.md) Turso 部署通常运行的环境。 --- # 阿里云邮件推送 > 通过 阿里云邮件推送 发送事务邮件。 Source: https://kernlift.dev/zh/docs/extensions/email/aliyun ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在收件箱和投递记录中核对同一封测试邮件。 ## 在 阿里云邮件推送 完成准备 ### 验证发信域名 打开 [阿里云邮件推送](https://dm.console.aliyun.com/)。选择邮件推送地域并验证发信域名。 ### 创建发信地址 在相同地域创建触发邮件的发信地址。 ### 创建 RAM 访问密钥 为具有邮件推送权限的专用 RAM 身份创建 AccessKey。 官方说明 · [API 发送准备](https://www.alibabacloud.com/help/en/direct-mail/getting-started/simplified-procedure-of-sending-by-api-and-smtp) · [创建发信地址](https://www.alibabacloud.com/help/en/direct-mail/user-guide/setup-sender-addresses) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/email`。 | 来源 | 后台字段 | | ------------------------------------------------------------------------------ | ------------------------------------------- | | 阿里云 RAM 控制台中具备邮件推送权限的用户。 | **AccessKey ID**、**AccessKey Secret** | | 邮件推送控制台中、已验证域名下创建的发信地址。 | **发信地址** | | 可选:显示名称;接入点(默认 `https://dm.aliyuncs.com`,使用其他地域时修改);地址类型(默认 `1`);勾选后回复会发到发信地址。 | **发件人昵称**、**Endpoint**、**地址类型**、**回复到发信地址** | 勾选 **设为当前邮件 provider**,点击 **保存 provider**。 <img src="/docs/guides/email/aliyun.zh.png" alt="Kernlift 后台的 阿里云邮件推送 配置字段" width="512" height="1165" loading="lazy" /> ## 验证 1. 在 `/admin/email/test` 选择模板,填写自己的邮箱并点击 **发送测试邮件**。 2. 确认收件箱收到邮件,且 `/admin/email/deliveries` 对应记录为 `sent`。 ## 常见问题 ### 投递状态为 `not_configured` 当前服务商缺少凭据,或邮件发送已关闭。Resend 需要 API Key;Cloudflare 需要 Account ID 和 API Token;阿里云需要 AccessKey ID、Secret 和发信地址。 ## 下一步 [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) --- # Cloudflare Email > 通过 Cloudflare Email 发送事务邮件。 Source: https://kernlift.dev/zh/docs/extensions/email/cloudflare ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在收件箱和投递记录中核对同一封测试邮件。 ## 在 Cloudflare Email 完成准备 ### 启用邮件发送 打开 [Cloudflare Email](https://dash.cloudflare.com/)。为发件域名启用 Email Sending。 ### 验证发件域名 发布并验证发件域名的 DNS 记录。 ### 复制账户 ID 从账户概览复制 Account ID。 ### 创建发信令牌 创建允许发送邮件的 API Token。 官方说明 · [Email Sending REST API](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/) · [创建 API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/email`。 | 来源 | 后台字段 | | ------------------------------------------------------ | ---------------------------- | | 已验证域名下的邮箱 | 发件人地址 | | Cloudflare 账户概览页;My Profile → API Tokens,创建可发信的 token。 | **Account ID**、**API token** | 勾选 **设为当前邮件 provider**,点击 **保存 provider**。 <img src="/docs/guides/email/cloudflare.zh.png" alt="Kernlift 后台的 Cloudflare Email 配置字段" width="512" height="742" loading="lazy" /> ## 验证 1. 在 `/admin/email/test` 选择模板,填写自己的邮箱并点击 **发送测试邮件**。 2. 确认收件箱收到邮件,且 `/admin/email/deliveries` 对应记录为 `sent`。 ## 常见问题 ### 投递状态为 `not_configured` 当前服务商缺少凭据,或邮件发送已关闭。Resend 需要 API Key;Cloudflare 需要 Account ID 和 API Token;阿里云需要 AccessKey ID、Secret 和发信地址。 ## 下一步 [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) --- # 发送事务邮件 > 完成后,验证邮件、密码重置邮件和你自己的产品邮件会用可编辑的模板,通过 Resend、Cloudflare Email Service 或阿里云邮件推送发出。 Source: https://kernlift.dev/zh/docs/extensions/email 邮件使用模板,通过当前启用的一个服务商发送。每次尝试,无论是否发出,都会写入投递日志。请在上线前配置好。没有服务商时,用户收不到验证邮件和密码重置邮件。 ## 准备工作 * 一个已在服务商完成验证的发信域名(需添加 SPF、DKIM 等 DNS 记录)。未验证域名发出的邮件会被拒绝。 * 服务商的凭据。 * 拥有 `config.read` 和 `config.write` 的管理员账号。 按你的域名和账号所在平台选择服务商: | 服务商 | 凭据 | 发件人 | | ----------------- | ---------------------- | ---------------------------------------------- | | Resend | 一个 API key | **发件人地址**,需属于在 Resend 验证过的域名 | | Cloudflare Email | Account ID 和 API token | **发件人地址**,需属于在 Cloudflare 开通 Email Service 的域名 | | Aliyun DirectMail | AccessKey ID 和 Secret | 在邮件推送控制台创建的 **发信地址**;不使用 **发件人地址** | ## 在邮件服务商完成准备 | 厂商 | 适用场景 | | -------------------------------------------------------- | --------------------- | | [Resend](https://kernlift.dev/zh/docs/extensions/email/resend.md) | 通过已验证域名和发信密钥发信 | | [Cloudflare Email](https://kernlift.dev/zh/docs/extensions/email/cloudflare.md) | 使用 Cloudflare 账户和发信令牌 | | [阿里云邮件推送](https://kernlift.dev/zh/docs/extensions/email/aliyun.md) | 通过指定地域的发信地址发信 | ## 接入服务商 ### 打开邮件配置 进入 **设置 → 邮件配置**(`/admin/config/email`)。顶部卡片分别是 **Resend**、**Cloudflare Email** 和 **Aliyun DirectMail**。凭据已保存的卡片显示 **已配置**,否则显示 **缺少配置**。当前负责发信的服务商带有 **启用中** 标记。点击要配置的卡片。 ### 设置发件人 在 **投递设置** 中填写 **发件人地址**(Resend 和 Cloudflare 使用),例如 `Acme <noreply@mail.example.com>`;以及 **联系表单通知收件人**,即接收 `/contact` 表单内容的邮箱。留空的字段会保留当前值。 ### 填入凭据 在 **密钥配置** 中填写所选服务商的字段: 按上方对应厂商指南中的字段对照表填写。 密钥字段保存后显示为空,留空即保留已保存的值。 ### 启用并保存 勾选 **设为当前邮件 provider**,点击 **保存 provider**。卡片显示 **启用中**,**运行状态** 面板显示当前服务商和发件人。 保存的效果取决于这个复选框。勾选时,该卡片的服务商成为当前启用的服务商。在当前启用服务商的卡片上取消勾选,会关闭邮件发送。在其他卡片上不勾选,只保存该服务商的配置。复选框下方一行显示 `当前启用:…` 或 `邮件发送已关闭:没有启用的 provider。` **尚未配置服务商时** 不会发出任何邮件,每次尝试都记录为 `not_configured`。注册仍然可以完成,但如果开启了 **邮箱验证**,未验证邮箱的用户将无法登录。在服务商启用之前,`/setup` 会把 **邮件投递** 列为必需项。 ## 了解自动发送的邮件 以下模板无需你写代码就会发送: | 模板 | 触发时机 | | -------------------- | ------------------------------- | | `email-verification` | 注册时;要求邮箱验证期间未验证用户尝试登录时;用户请求重发时。 | | `password-reset` | 用户申请重置密码时。固定使用英文。 | | `contact-routed` | 有人提交联系表单时,发到 **联系表单通知收件人**。 | 模板集合中还有 `registration-success`、`newsletter-welcome`、`billing-receipt`、`payment-success`、`subscription-renewal`、`subscription-canceled`、`payment-failed`、`invoice-ready` 和 `security-alert`。它们不会自动发送,需要在你自己的代码中发送。 ## 编辑模板 ### 打开模板 打开 `/admin/email/templates`(属于 **设置** 分组中的 **邮件** 区域)。每个模板按语言各出现一次,位于 **模板配置** 下,key 下方列出其变量。 ### 修改内容 修改主题、**文本正文** 或 **HTML 正文**。变量使用 `{{name}}` 占位符,发送时变量值会经过 HTML 转义。 ### 保存并预览 点击 **保存模板**,看到 **模板已保存。** 即完成,变量列表会根据占位符重新生成。然后打开 `/admin/email/preview`,选择模板并点击 **渲染预览**。预览与正式投递使用同一套布局。 ## 在代码中发送邮件 用模板 key、收件人、语言和模板变量调用邮件 service。 ```ts title="src/server/services/example.service.ts" import { sendEmailTest } from "@/server/services/email-notifications.service"; const delivery = await sendEmailTest({ templateKey: "payment-success", to: user.email, locale: "zh", variables: { name: user.name, planName: "Pro", amount: "¥199.00", orderId: order.id, receiptUrl: receiptUrl, }, }); if (delivery.status !== "sent") { console.warn("Email not sent", delivery.status, delivery.errorMessage); } ``` 调用返回投递日志记录,状态为 `sent`、`failed` 或 `not_configured`。只有模板不存在时才抛出错误。缺少模板用到的任一变量时不会发送,记录为 `failed`,错误为 `Missing template variables: ...`。 ## 验证 ### 发送测试邮件 打开 `/admin/email/test`,页头显示 **Provider 已就绪**。选择 **模板** 和 **语言**,在 **收件人** 中填写自己的邮箱,在 **变量 JSON** 中为每个变量填值,点击 **发送测试邮件**。表单显示 `邮件投递已记录:` 及结果。 ### 检查投递 邮件到达收件箱,`/admin/email/deliveries` 中这条记录状态为 `sent`;在 `/auth/forgot-password` 为已有账号申请重置密码,能收到重置链接。 `pnpm validate:email` 会检查模板、预览、投递日志和服务商接线。`EXTERNAL_VALIDATE_EMAIL_TO=you@example.com pnpm validate:external` 会真实发送一封密码重置邮件。 ## 常见问题 ### 投递状态为 `not_configured` 当前服务商缺少凭据,或邮件发送已关闭。Resend 需要 API Key;Cloudflare 需要 Account ID 和 API Token;阿里云需要 AccessKey ID、Secret 和发信地址。 ### 保存服务商卡片后邮件停止发送 当前启用服务商的卡片在 **设为当前邮件 provider** 未勾选时被保存。打开该卡片,勾选后点击 **保存 provider**。 ### 投递 `failed`,错误与发件人或域名有关 服务商拒绝了发件人。在服务商处完成域名验证,并确认 **发件人地址**(或阿里云的 **发信地址**)属于该域名。 ### 报错 "Email template not found" 该 key 和语言下没有模板。新数据库请运行 `pnpm db:seed-baseline`。 ## 参考 * [通知](https://kernlift.dev/zh/docs/extensions/notifications.md) * [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) * [Resend API](https://resend.com/docs/api-reference/introduction) ## 下一步 - [向 Slack、Discord 或飞书发送通知](https://kernlift.dev/zh/docs/extensions/notifications.md) - [配置邮箱密码登录](https://kernlift.dev/zh/docs/extensions/auth/email-password.md) - [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) --- # Resend > 通过 Resend 发送事务邮件。 Source: https://kernlift.dev/zh/docs/extensions/email/resend ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能在收件箱和投递记录中核对同一封测试邮件。 ## 在 Resend 完成准备 ### 添加发件域名 打开 [Resend](https://resend.com/domains)。添加发件人邮箱使用的域名。 ### 验证 DNS 记录 在域名服务商录入 Resend 给出的 DNS 记录,等待状态变为 Verified。 ### 创建发信密钥 在 API Keys 为该域名创建 Sending access 密钥。 官方说明 · [域名验证](https://resend.com/changelog/domain-verification-events) · [API Key 权限](https://resend.com/changelog/new-api-key-permissions) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/email`。 | 来源 | 后台字段 | | -------------------------------------- | ----------- | | 已验证域名下的邮箱 | 发件人地址 | | Resend 控制台 → API Keys(`re_…`),有发信权限即可。 | **API key** | 勾选 **设为当前邮件 provider**,点击 **保存 provider**。 <img src="/docs/guides/email/resend.zh.png" alt="Kernlift 后台的 Resend 配置字段" width="512" height="653" loading="lazy" /> ## 验证 1. 在 `/admin/email/test` 选择模板,填写自己的邮箱并点击 **发送测试邮件**。 2. 确认收件箱收到邮件,且 `/admin/email/deliveries` 对应记录为 `sent`。 ## 常见问题 ### 投递状态为 `not_configured` 当前服务商缺少凭据,或邮件发送已关闭。Resend 需要 API Key;Cloudflare 需要 Account ID 和 API Token;阿里云需要 AccessKey ID、Secret 和发信地址。 ## 下一步 [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) --- # Beehiiv > 将邮件订阅者同步到 Beehiiv。 Source: https://kernlift.dev/zh/docs/extensions/newsletter/beehiiv ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,订阅的测试邮箱会出现在服务商的联系人列表。 ## 在 Beehiiv 完成准备 ### 创建 Publication 打开 [Beehiiv](https://developers.beehiiv.com/welcome/create-an-api-key)。创建 Publication 并复制其 ID。 ### 授权订阅同步 创建有权读写该 Publication 订阅者的 API Key。 官方说明 · [创建 API Key](https://developers.beehiiv.com/welcome/create-an-api-key) · [Publication API](https://developers.beehiiv.com/api-reference/publications/show) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/waitlist/settings`。 | 来源 | 后台字段 | | -------------- | ---------------------- | | API key | Beehiiv API Key | | Publication ID | Beehiiv Publication ID | 选择 Beehiiv,点击 **保存服务商设置**。 <img src="/docs/guides/newsletter/beehiiv.zh.png" alt="Kernlift 后台的 Beehiiv 配置字段" width="512" height="369" loading="lazy" /> ## 验证 1. 在 `/zh/newsletter` 使用自己的邮箱订阅。 2. 在后台重试同步,确认记录状态为 `success`。 3. 在 Beehiiv 控制台查到该联系人。 ## 常见问题 ### 同步日志显示 `failed` 服务商拒绝了请求,日志消息中包含其错误信息。在 **服务商设置** 中修正凭据后运行 **重试 provider 同步**。 ## 下一步 [邮件订阅与候补名单](https://kernlift.dev/zh/docs/extensions/newsletter.md) --- # 邮件订阅与候补名单 > 收集邮件订阅者和发布候补名单,同步到 Resend 或 Beehiiv,分批邀请用户并重试失败的同步。 Source: https://kernlift.dev/zh/docs/extensions/newsletter 邮件订阅模块提供公开的 `/newsletter`、`/waitlist` 和 `/waitlist/status` 页面,为每个新注册账号自动订阅,并把每次订阅、退订和邀请同步到 Resend 或 Beehiiv。不接入服务商时订阅同样可用。同步留在队列中,直到你接入服务商。 ## 准备工作 * 一个能在本地运行的项目,见[快速开始](https://kernlift.dev/zh/docs/quick-start.md)。`newsletter` 模块已经在底座仓库里,入口是后台侧边栏 **内容** 分组下的 **Waitlist**。 * 管理员账号:`newsletter.read` 用于打开页面;保存设置、批量邀请和重试同步还需要 `newsletter.write`。 * 一个具备完整权限(Full access)的 Resend API Key 用于创建联系人,或者一个 Beehiiv API Key 及对应的 publication ID。 要给同事授权,在 **概览 → 用户** 中为其分配 **Content Manager** 角色。该角色包含两个订阅权限和 CMS 权限。 ## 在订阅服务商准备账号 | 厂商 | 适用场景 | | ------------------------------------------------- | --------------------- | | [Resend](https://kernlift.dev/zh/docs/extensions/newsletter/resend.md) | 使用联系人写入权限同步订阅者 | | [Beehiiv](https://kernlift.dev/zh/docs/extensions/newsletter/beehiiv.md) | 将订阅者同步到指定 Publication | ## 接入服务商 同一时间只启用一个服务商。 ### 打开服务商设置 进入 **内容 → Waitlist**(`/zh/admin/waitlist`),打开 **服务商设置** 标签页(`/zh/admin/waitlist/settings`)。`/setup` 中的 **订阅供应商** 也链接到这里。 ### 选择服务商并填写凭据 在 **服务商** 中选择 **Resend** 或 **Beehiiv**,然后填写对应字段: 按上方对应厂商指南中的字段对照表填写。 API Key 和 Publication ID 只写不读。已保存值的字段显示 **已保存,留空则保留**。 ### 保存 点击 **保存服务商设置**。页面显示 **订阅服务商设置已保存。**,之后的订阅、退订和邀请会使用该服务商。 要停止同步,选择 **未配置** 并保存,之后的同步会留在队列中。 **与邮件配置相互独立** 模块本身不发送邮件,也不读取 **邮件配置**。保存在那里的 Resend Key 只用于事务邮件,订阅通讯需要在这里单独填写。 ## 从候补名单发出邀请 ### 打开批量邀请 打开 **批量邀请** 标签页(`/zh/admin/waitlist/invites`)。 ### 邀请一批用户 填写 1 到 100 之间的 **批次大小**,点击 **批量邀请**。排队最久的等待记录会变为已邀请,并逐个同步到服务商。 ### 通知用户 系统不会发送邀请邮件,请通过你自己的邮件流程发送。 ## 重试排队中和失败的同步 服务商配置之前产生的同步仍在队列中,被服务商拒绝的同步记为失败。 ### 打开批量邀请 打开 **批量邀请** 标签页(`/zh/admin/waitlist/invites`)。 ### 重试 在 **重试 provider 同步** 区域填写 **批次大小**,点击 **重试 provider 同步**。最近一次尝试为 `pending` 或 `failed` 的同步会从最早的开始重试。 ## 验证 1. 打开 `/zh/newsletter`,用你能收信的邮箱订阅。 2. 在 **批量邀请** 点击 **重试 provider 同步**。 3. 日志表新增一行,服务商为你配置的服务商,状态为 `success`,Resend 或 Beehiiv 控制台中也会出现该联系人。 在仓库中,`pnpm validate:newsletter` 会运行这些流程。要验证真实服务商,设置 `EXTERNAL_VALIDATE_NEWSLETTER_EMAIL` 后运行 `EXTERNAL_VALIDATE_STRICT=true pnpm validate:external`。 ## 常见问题 ### 同步日志一直是 `pending` 没有配置服务商,因此没有发出请求。先[接入服务商](#接入服务商),再运行 **重试 provider 同步**。 ### 同步日志显示 `failed` 服务商拒绝了请求,日志消息中包含其错误信息。在 **服务商设置** 中修正凭据后运行 **重试 provider 同步**。 ### 保存服务商设置时报错 错误消息会指出原因:`Resend needs an API key before it can be selected.`、`Beehiiv needs an API key and a publication id before it can be selected.` 或 `The Beehiiv API base URL must be an https URL.`。表单填写完整之前不会保存任何内容。 ### 候补用户没有收到邀请邮件 邀请只修改状态并同步联系人。请自行发送邮件。 ## 参考 * [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) * [底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md) * [Resend audiences](https://resend.com/docs/dashboard/audiences/introduction) ## 下一步 - [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) - [插件](https://kernlift.dev/zh/docs/core/plugins.md) --- # Resend > 将邮件订阅者同步到 Resend。 Source: https://kernlift.dev/zh/docs/extensions/newsletter/resend ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,订阅的测试邮箱会出现在服务商的联系人列表。 ## 在 Resend 完成准备 ### 创建联系人同步密钥 打开 [Resend](https://resend.com/api-keys)。为联系人同步创建单独的 Full access 密钥。 ### 保存同步凭据 将该密钥与事务邮件使用的 Sending access 密钥分别保管。 官方说明 · [Resend Key 权限](https://resend.com/changelog/new-api-key-permissions) · [Contacts 模型](https://resend.com/blog/new-contacts-experience) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/waitlist/settings`。 | 来源 | 后台字段 | | ------- | -------------- | | API key | Resend API Key | 选择 Resend,点击 **保存服务商设置**。 <img src="/docs/guides/newsletter/providers.zh.png" alt="Kernlift 后台的 Resend 配置字段" width="512" height="369" loading="lazy" /> ## 验证 1. 在 `/zh/newsletter` 使用自己的邮箱订阅。 2. 在后台重试同步,确认记录状态为 `success`。 3. 在 Resend 控制台查到该联系人。 ## 常见问题 ### 同步日志显示 `failed` 服务商拒绝了请求,日志消息中包含其错误信息。在 **服务商设置** 中修正凭据后运行 **重试 provider 同步**。 ## 下一步 [邮件订阅与候补名单](https://kernlift.dev/zh/docs/extensions/newsletter.md) --- # Discord > 向 Discord 发送团队通知。 Source: https://kernlift.dev/zh/docs/extensions/notifications/discord ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,目标群聊收到测试消息,后台可以查询对应投递记录。 ## 在 Discord 完成准备 ### 打开服务器集成 打开 [Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)。打开目标服务器的设置 → 集成 → Webhooks。 ### 创建频道 Webhook 为目标文字频道创建 Webhook 并复制 URL。 官方说明 · [Discord Webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/email`。 | 来源 | 后台字段 | | ----------- | ------------------- | | Webhook URL | Discord Webhook URL | 保持原有邮件服务商启用状态,点击 **保存 provider**。 <img src="/docs/guides/notifications/channels.zh.png" alt="Kernlift 后台的 Discord 配置字段" width="512" height="653" loading="lazy" /> ## 验证 1. 在 `/admin/notifications` 选择 `discord-alerts` 并点击 **发送通知**。 2. 在群中确认收到消息,并在投递日志中核对 `sent` 状态。 ## 常见问题 ### 投递日志显示 `not_configured` 该渠道的 Webhook URL 为空。在 **邮件配置** 中保存 URL,然后再发送一次测试。 ## 下一步 [向 Slack、Discord 或飞书发送通知](https://kernlift.dev/zh/docs/extensions/notifications.md) --- # 飞书 > 向 飞书 发送团队通知。 Source: https://kernlift.dev/zh/docs/extensions/notifications/feishu ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,目标群聊收到测试消息,后台可以查询对应投递记录。 ## 在 飞书 完成准备 ### 添加自定义机器人 打开 [飞书](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot)。在目标群中添加自定义机器人。 ### 复制群机器人地址 复制 Webhook URL,并确认该群允许接收此集成发送的未签名消息。 官方说明 · [飞书自定义机器人说明](https://www.feishu.cn/content/7271149634339422210) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/email`。 | 来源 | 后台字段 | | ----------- | -------------- | | Webhook URL | 飞书 Webhook URL | 保持原有邮件服务商启用状态,点击 **保存 provider**。 <img src="/docs/guides/notifications/channels.zh.png" alt="Kernlift 后台的 飞书 配置字段" width="512" height="653" loading="lazy" /> ## 验证 1. 在 `/admin/notifications` 选择 `feishu-alerts` 并点击 **发送通知**。 2. 在群中确认收到消息,并在投递日志中核对 `sent` 状态。 ## 常见问题 ### 投递日志显示 `not_configured` 该渠道的 Webhook URL 为空。在 **邮件配置** 中保存 URL,然后再发送一次测试。 ## 下一步 [向 Slack、Discord 或飞书发送通知](https://kernlift.dev/zh/docs/extensions/notifications.md) --- # 向 Slack、Discord 或飞书发送通知 > 完成后,产品的运营提醒会发到团队群聊频道,每次尝试都记录在投递日志中。 Source: https://kernlift.dev/zh/docs/extensions/notifications 运营通知发到团队群聊,不发给用户。后台内置 Slack、Discord 和飞书三个渠道,每个渠道向你在后台保存的 Incoming Webhook URL 发送消息。 ## 准备工作 * 可以添加 Incoming Webhook 或机器人的 Slack 工作区、Discord 服务器或飞书群。 * 拥有 `config.read` 和 `config.write` 的管理员账号。 ## 在群聊服务创建 Webhook | 厂商 | 适用场景 | | ---------------------------------------------------- | ---------- | | [Slack](https://kernlift.dev/zh/docs/extensions/notifications/slack.md) | 发送到工作区频道 | | [Discord](https://kernlift.dev/zh/docs/extensions/notifications/discord.md) | 发送到服务器文字频道 | | [飞书](https://kernlift.dev/zh/docs/extensions/notifications/feishu.md) | 发送到群机器人 | ## 保存 Webhook URL ### 创建 Incoming Webhook 在 Slack 应用中启用 Incoming Webhooks,在 Discord 频道的 **整合** 设置中新建 Webhook,或在飞书群中添加自定义机器人。复制 URL。 ### 粘贴到邮件配置 进入 **设置 → 邮件配置**(`/admin/config/email`),在 **通知 Webhook** 中把 URL 粘贴到 **Slack Webhook URL**、**Discord Webhook URL** 或 **飞书 Webhook URL**。字段显示已保存的地址,清空某一项即删除对应的 Webhook。 ### 保存 点击 **保存 provider**。这个按钮同时保存所选的邮件卡片,所以如果当前在启用中邮件服务商的卡片上,请保持 **设为当前邮件 provider** 勾选,否则会关闭邮件发送。 **URL 就是凭证** 每条通知都是不带签名头的 JSON `POST`。请妥善保管 Webhook URL,也不要在接收端机器人上开启签名校验,否则请求会被拒绝。 ## 发送测试通知 ### 打开通知 进入 **设置 → 通知**(`/admin/notifications`)。 ### 填写测试内容 在 **测试通知** 中选择 **渠道**,按需修改 **事件 key** 和 **消息**,点击 **发送通知**。表单显示 `通知投递已记录:` 及结果。 ## 在代码中发送通知 模板本身不会自动发送运营通知。在产品需要提醒的地方调用 service。用渠道 key 指定渠道:`slack-alerts`、`discord-alerts` 或 `feishu-alerts`。 ```ts title="src/server/services/example.service.ts" import { sendNotificationTest } from "@/server/services/email-notifications.service"; await sendNotificationTest({ channelKey: "feishu-alerts", eventKey: "billing.refund.requested", message: "订单 ord_123 申请退款", metadata: { orderId: "ord_123" }, }); ``` 调用返回投递日志记录,状态为 `sent`、`failed`、`not_configured` 或 `disabled`。只有渠道 key 不存在时才抛出错误。 ## 分类 <TypeTable type="{ transactional: { type: "分类", description: "收据、验证邮件、重置密码。客户无法关闭,因为它们是交易的一部分。", }, system: { type: "分类", description: "关于账号本身的运营通知。", }, marketing: { type: "分类", description: "只在用户主动同意后发送。用户在偏好页退订。", }, }" /> 每次投递无论成功失败都会写入记录和审计条目,所以发送失败的通知也能在投递日志中查到。 ## 验证 * 消息出现在群聊频道中。 * **投递日志**(`/admin/notifications/deliveries`)中这次尝试为 `sent`,失败时 **错误** 列显示群聊服务返回的信息。 * `/admin/notifications/channels` 显示每个渠道的状态,状态来自 **邮件配置** 中保存的 URL。 `pnpm validate:email` 会检查通知日志和后台路由。 ## 常见问题 ### 投递日志显示 `not_configured` 该渠道的 Webhook URL 为空。在 **邮件配置** 中保存 URL,然后再发送一次测试。 ### 投递日志显示 `failed` 群聊服务拒绝了请求,**错误** 列显示它的响应。确认 URL 完整且仍然有效,并确认飞书机器人没有开启签名校验。 ### 投递日志显示 `disabled` 该渠道在数据库中被关闭,即使保存了 URL 也不会发送。 ### 保存 Webhook 后邮件停止发送 Webhook 是在启用中邮件服务商的卡片上保存的,且 **设为当前邮件 provider** 未勾选。打开该卡片,勾选后点击 **保存 provider**。 ## 参考 * [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) * [审计日志](https://kernlift.dev/zh/docs/core/admin/audit-log.md) * [Web push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) ## 下一步 - [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) - [运营管理后台](https://kernlift.dev/zh/docs/core/admin.md) - [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) --- # Slack > 向 Slack 发送团队通知。 Source: https://kernlift.dev/zh/docs/extensions/notifications/slack ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,目标群聊收到测试消息,后台可以查询对应投递记录。 ## 在 Slack 完成准备 ### 启用 Incoming Webhooks 打开 [Slack](https://api.slack.com/apps)。创建应用并启用 Incoming Webhooks。 ### 选择接收频道 点击 Add New Webhook to Workspace,授权目标频道并复制 URL。 官方说明 · [Slack Incoming Webhooks](https://api.slack.com/messaging/webhooks) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/email`。 | 来源 | 后台字段 | | ---------------- | ----------------- | | Incoming webhook | Slack Webhook URL | 保持原有邮件服务商启用状态,点击 **保存 provider**。 <img src="/docs/guides/notifications/channels.zh.png" alt="Kernlift 后台的 Slack 配置字段" width="512" height="653" loading="lazy" /> ## 验证 1. 在 `/admin/notifications` 选择 `slack-alerts` 并点击 **发送通知**。 2. 在群中确认收到消息,并在投递日志中核对 `sent` 状态。 ## 常见问题 ### 投递日志显示 `not_configured` 该渠道的 Webhook URL 为空。在 **邮件配置** 中保存 URL,然后再发送一次测试。 ## 下一步 [向 Slack、Discord 或飞书发送通知](https://kernlift.dev/zh/docs/extensions/notifications.md) --- # 支付宝 > 通过支付宝电脑网站收银台收取人民币付款。 Source: https://kernlift.dev/zh/docs/extensions/payments/alipay * **结账** 支付宝电脑网站收银台(`alipay.trade.page.pay`),只收人民币一次性付款 * **订阅** 不支持 * **客户门户** 不支持 * **退款** 支持 * **优惠码** 不支持 人民币计价的套餐在微信支付启用且配置齐全时走微信支付,否则走支付宝。其它币种或订阅套餐会在调用支付宝之前被拒绝。 ## 准备工作 准备公网 HTTPS 站点、`/admin/plans` 中以 `CNY` 计价的一次性套餐(见[管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)),以及支付宝开放平台账号。先用沙箱应用测试,后台网关字段默认就指向沙箱。 **完成后**,一笔订单经验签通过的异步通知结算,并能在后台退款。 ## 在支付宝完成准备 ### 打开沙箱应用 打开[支付宝开放平台](https://open.alipay.com/develop/sandbox/app),使用沙箱应用。上线时创建网页 / 移动应用,并为它签约电脑网站支付。 ### 生成应用密钥 用支付宝密钥工具生成 RSA2(2048 位)密钥对,保存应用私钥;PKCS#1 和 PKCS#8 格式都可以。 ### 选择公钥模式 在接口加签方式中选择公钥模式(不是证书模式),上传应用公钥,复制页面显示的**支付宝公钥**。 ### 记下标识 记下 APPID。可选:记下账号的 PID,即 `2088` 开头的用户号,用于拒绝其它卖家的通知。 异步通知地址不需要在支付宝登记。每个收银台地址都带有 `notify_url`:**成功 URL** 的源加上 `/api/billing/webhook/alipay`。 官方说明 · [电脑网站支付](https://opendocs.alipay.com/open/028r8t) · [异步通知](https://opendocs.alipay.com/open/00dn7l) · [签名与验签](https://opendocs.alipay.com/common/057k53) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/payment`。选择 **Alipay**(支付宝),填写公网成功 URL 和取消 URL。测试期间 **API base URL** 保持沙箱网关 `https://openapi-sandbox.dl.alipaydev.com/gateway.do`。 | 来源 | 后台字段 | | ------------------ | ------------------------ | | 应用的 APPID | **应用 APPID** | | 账号 PID(`2088…`),可选 | **卖家支付宝用户号(2088 开头,可选)** | | 你生成的密钥对中的私钥 | **应用私钥** | | 上传应用公钥后显示的支付宝公钥 | **支付宝公钥** | 勾选启用并点击 **保存 provider**。保存应用 APPID 和两个密钥后卡片显示已配置;保存支付宝公钥后显示 Webhook 已配置。 **两个公钥别混淆** 这里粘贴的是支付宝公钥,不是应用公钥。用错公钥时通知验签失败,订单停在待付款。密钥可以是 PEM 或纯 base64;密钥字段留空保存会保留原值。 <img src="/docs/guides/payments/alipay.zh.png" alt="Kernlift 后台的 支付宝 配置字段" width="512" height="719" loading="lazy" /> ## 验证 1. 用普通用户登录,打开 `/pricing`,购买人民币一次性套餐。**预期**:跳转到支付宝收银台。 2. 用沙箱买家账号付款。**预期**:经 `/api/billing/callback/alipay` 回到站点,服务端先用 `alipay.trade.query` 查单,再把订单标记为已付款。 3. 打开 `/admin/billing-webhooks`。**预期**:出现一条来自支付宝、签名有效的 `TRADE_SUCCESS` 事件。 4. 在 `/admin/orders` 为这笔订单退款。**预期**:退款立即成功。 ## 切换到正式环境 1. 把 **API base URL** 改为 `https://openapi.alipay.com/gateway.do`。 2. 保存正式应用的 APPID、应用私钥和正式环境的支付宝公钥。沙箱密钥无法验证正式环境的通知。 3. 实付一笔并退款。 ## 常见问题 ### 支付宝下单被拒绝,原因是 `provider_unsupported` 支付宝只收人民币一次性付款。在 `/admin/plans` 把套餐的币种设为 `CNY`、计费周期设为一次性或终身,或改用其它服务商收款。 ### 人民币套餐走了微信支付而不是支付宝 微信支付启用且配置齐全时优先收人民币套餐。如果要由支付宝收款,在 `/admin/config/payment` 取消启用微信支付。 ### 通知记录的类型带 `.mismatch` 签名通过,但 `app_id`、`seller_id` 或 `total_amount` 与订单不一致。核对保存的应用 APPID 和卖家用户号,并确认下单后没有修改套餐价格。 ## 下一步 - [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) 比较各服务商及共用的设置。 --- # Creem > 通过 Creem 收款。 Source: https://kernlift.dev/zh/docs/extensions/payments/creem * **结账** 托管结账页 * **订阅** 取消和恢复 * **客户门户** 支持 * **退款** 只能在 Creem 后台操作 **结账接口兼容性** Creem 的结账接口要求传入 `product_id`。当前适配器发送 `product_data`,后台也没有 Creem 商品 ID 配置项。需要先对接商品 ID,再用沙箱订单验证收款。 [Creem API](https://docs.creem.io/skills/creem-api/REFERENCE) ## 准备工作 准备公网 HTTPS 站点、`/admin/plans` 中已上架的套餐,以及能管理商户设置的账号。 **完成后**,可以核对测试店铺的 API 地址、签名密钥和通知端点。 ## 在 Creem 完成准备 ### 选择测试店铺 打开 [Creem](https://www.creem.io/dashboard)。切换到测试店铺。 ### 创建 API Key 在 Developers 创建 API Key,保存密钥。 ### 登记付款通知 在 Webhooks 登记以 `/api/billing/webhook/creem` 结尾的公网 HTTPS 地址,订阅 `checkout.completed`,复制签名密钥。 官方说明 · [Creem Webhook 指南](https://docs.creem.io/code/webhooks) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/payment`。选择 **Creem**,填写公网成功 URL、取消 URL,将 **API base URL** 设为 `https://test-api.creem.io`。 | 来源 | 后台字段 | | -------------- | -------------- | | API key | API key | | Webhook secret | Webhook secret | | Test API | API base URL | 勾选启用并点击 **保存 provider**。 <img src="/docs/guides/payments/creem.zh.png" alt="Kernlift 后台的 Creem 配置字段" width="512" height="465" loading="lazy" /> ## 验证 先确认适配器已能传入测试商品 ID,再验收以下三步。 1. 用沙箱买家账号在 `/pricing` 购买套餐。 2. 在 `/admin/billing-webhooks` 确认签名校验通过。 3. 在 `/admin/orders` 找到同一订单,确认状态为已付款。 ## 切换到正式环境 在正式账号创建凭据并登记正式域名的 Webhook。将新端点的验签值、同一环境的凭据和 `https://api.creem.io` 一起保存。 ## 常见问题 ### webhook 签名校验失败 确认签名密钥来自当前店铺,且端点与 API Key 均在同一环境创建。 ## 下一步 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) --- # DodoPayments > 通过 DodoPayments 收款。 Source: https://kernlift.dev/zh/docs/extensions/payments/dodopayments * **结账** 托管结账页,需要先在 DodoPayments 建好产品 * **订阅** 没有生命周期操作 * **客户门户** 不支持 * **退款** 不支持 ## 准备工作 准备公网 HTTPS 站点、`/admin/plans` 中已上架的套餐,以及能管理商户设置的账号。 **完成后**,能通过签名通知核对一笔订单。 ## 在 DodoPayments 完成准备 ### 创建测试商品 打开 [DodoPayments](https://app.dodopayments.com)。切换至 Test Mode,在 Products 创建商品并复制产品 ID。 ### 创建 API Key 在 Developer → API Keys 生成 API Key。 ### 订阅付款通知 在 Webhooks 登记以 `/api/billing/webhook/dodopayments` 结尾的 HTTPS 地址,选择 `payment.succeeded` 和 `payment.failed`,复制完整签名密钥。 官方说明 · [Dodo 产品](https://docs.dodopayments.com/features/products) · [官方接入示例](https://docs.dodopayments.com/developer-resources/nextjs-boilerplate) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/payment`。选择 **DodoPayments**,填写公网成功 URL、取消 URL,将 **API base URL** 设为 `https://test.dodopayments.com`。 | 来源 | 后台字段 | | ---------------- | --------------- | | API key | API key | | Product ID | Dodo product ID | | Signing secret | Webhook secret | | 按套餐映射商品的 JSON,可选 | 套餐 Product ID | 勾选启用并点击 **保存 provider**。 <img src="/docs/guides/payments/dodopayments.zh.png" alt="Kernlift 后台的 DodoPayments 配置字段" width="512" height="562" loading="lazy" /> ## 验证 1. 用沙箱买家账号在 `/pricing` 购买套餐。 2. 在 `/admin/billing-webhooks` 确认签名校验通过。 3. 在 `/admin/orders` 找到同一订单,确认状态为已付款。 ## 切换到正式环境 在正式账号创建凭据并登记正式域名的 Webhook。将新端点的验签值、同一环境的凭据和 `https://live.dodopayments.com` 一起保存。 ## 常见问题 ### webhook 签名校验失败 粘贴含前缀的完整签名密钥,核对服务器时间并确认请求正文未经改写。 ## 下一步 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) --- # 编写履约插件 > 用自己的插件交付已付订单所买的内容、拒绝无法履约的结账,并观察失败的交付被自动重试。 Source: https://kernlift.dev/zh/docs/extensions/payments/fulfilment 计费在结算订单之后,会通知每个已启用的 `billing.fulfilment` 插件。本文在一个本地插件里添加你自己的履约方(fulfiller)。它对每个已付订单运行一次,对每笔退款运行一次,还可以在扣款之前拒绝结账。内置的 `plan-credits` 履约方(`src/server/billing/plan-credits-fulfiller.ts`)是参考实现。 ## 准备工作 * 能在本机运行、数据库已迁移的项目,以及一个可以购买的上架套餐,见[管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)。 * 想看到真实订单结算的话,需要一个处于测试模式的支付服务商,见[接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 * [定时任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md)在运行,因为重试由它执行。 * 明确订单要交付什么,以及用什么键保证重复交付无害,例如以订单 id 为键的一行记录。 ## 添加履约方 ### 编写履约方 新建 `src/server/billing/seat-fulfiller.ts`。履约方是一个带 `id` 的对象,可以实现三个钩子中的任意几个。类型定义在 `src/server/billing/fulfilment-types.ts`。 ```ts import type { BillingFulfiller } from "./fulfilment-types"; export const seatFulfiller: BillingFulfiller = Object.freeze({ id: "seats", async canCheckout({ userId, planKey }) { if (planKey !== "team") return { ok: true }; const allowed = await userMayBuySeats(userId); return allowed ? { ok: true } : { ok: false, code: "seats_unavailable", reason: "This account cannot buy seats." }; }, async onOrderPaid(order) { if (order.planKey !== "team") return; await grantSeatsOnce({ orderId: order.id, userId: order.userId }); }, async onOrderRefunded(order, refund) { if (refund.fullRefund) await revokeSeats(order.id); }, }); ``` `userMayBuySeats`、`grantSeatsOnce` 和 `revokeSeats` 由你实现,放在 `src/server/db/repositories/` 下的仓储里。三个钩子要遵守的规则: | 钩子 | 收到 | 规则 | | ----------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | `canCheckout` | `userId`、`planKey`、`productKey`、`checkoutMode` | 在订单创建之前运行。返回 `ok: false` 会以 HTTP 409 和你的 `code` 终止结账 | | `onOrderPaid` | 订单:`id`、`userId`、`provider`、`planKey`、`productKey`、`checkoutMode`、`amountCents`、`currency` | 必须幂等。重试可能发生在一次只成功了一半的调用之后 | | `onOrderRefunded` | 订单以及 `refundId`、`amountCents`、`fullRefund` | 重试规则相同;每笔在服务商侧成功的退款调用一次 | 交付失败时直接抛出异常。计费会记录失败并重试,付款不会被撤销。 ### 给插件写清单 属于你自己项目的插件类型是 `local`。它可以在 `/admin/plugins` 停用。新建 `src/plugins/seats/manifest.ts`: ```ts import { defineManifest } from "../kernel/types"; export const seatsManifest = defineManifest({ id: "seats", version: "0.1.0", kind: "local", }); ``` ### 创建两半 每个插件都有一个可在浏览器加载的部分,履约方放在服务端那一半。新建 `src/plugins/seats/plugin.ts`: ```ts import { definePlugin } from "../kernel/types"; import { seatsManifest } from "./manifest"; export const seatsPlugin = definePlugin({ manifest: seatsManifest }); ``` 以及 `src/plugins/seats/plugin.server.ts`: ```ts import { seatFulfiller } from "../../server/billing/seat-fulfiller"; import { defineServerPlugin } from "../kernel/types"; import { seatsManifest } from "./manifest"; export const seatsServerPlugin = defineServerPlugin({ manifest: seatsManifest, contributes: { "billing.fulfilment": [seatFulfiller] }, }); ``` 服务端这一半请使用相对路径导入。Agent 服务也会加载同一份列表,所以从这里能到达的代码都不能导入 React、图标或 `@/` 别名。 ### 注册两半 把 `seatsPlugin` 加到 `src/plugins/installed.ts` 的 `installedPlugins`,把 `seatsServerPlugin` 加到 `src/plugins/installed.server.ts` 的 `installedServerPlugins`。两处都要写在 `// @module:` 标记区域之外,那些区域属于随仓库提供的模块。 ### 为拒绝代码补上文案 如果 `canCheckout` 可能拒绝,买家会带着你的 `code` 落到支付失败页。在 `src/i18n/locales/en/messages.ts` 和 `src/i18n/locales/zh/messages.ts` 的 `checkoutFailure.reasons` 与 `checkoutFailure.nextActions` 下各加一句说明。 ## 观察失败后的重试 1. 让 `onOrderPaid` 抛出异常,例如 `throw new Error("seat service down")`,然后用服务商的测试卡购买这个套餐。 2. `/admin/orders` 中订单仍然是 `paid`。打开 `/admin/audit`,会看到一条 `billing.fulfilment.failed` 记录,目标是订单 id,元数据里有你的履约方、事件 `paid`、第几次尝试和错误信息。 3. 去掉 `throw`,等一分钟,然后手动执行一轮: ```bash pnpm jobs:run ``` 报告中 `billing-fulfilments` 任务显示 `"attempted": 1, "succeeded": 1`。如果报告是 `"skipped"`,说明进程内循环已经执行了这一轮,直接查看那一行记录。 每次失败之后按固定间隔重试: | 第几次尝试 | 运行时间 | | ----- | ---------------------------------------------------- | | 1 | 订单结算时 | | 2 | 第 1 次失败后 1 分钟 | | 3 | 再过 5 分钟 | | 4 | 再过 30 分钟 | | 5 | 再过 2 小时 | | 6 | 再过 12 小时;这次仍失败会写入 `billing.fulfilment.abandoned` 并停止 | 如果订单在此期间已退款或取消,`paid` 交付会被放弃。如果你停用了插件,它失败的记录会保留,每小时重新检查一次,不消耗尝试次数。 ## 验证结果 * `pnpm validate:plugins` 通过:注册表接受新插件,两半都已安装。 * `pnpm validate:billing-fulfilment` 通过:计费仍然只通知履约方一次,记录失败并重试。 * 测试购买之后,`billing_fulfilments` 中该订单的每个履约方各有一行,事件为 `paid`,状态为 `succeeded`。可以用 `pnpm db:studio` 打开这张表。 * 在 `/admin/orders` 给订单退款,会多出一行事件为 `refunded:<refundId>` 的记录。 ## 下一步 - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) 履约处在结算与退款之间的什么位置。 - [运行后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md) 确认重试在你的平台上运行。 - [审计日志](https://kernlift.dev/zh/docs/core/admin/audit-log.md) 查找失败和被放弃的履约。 --- # 支付生命周期 > 一次结账如何变成已支付订单:服务端定价、通过 Webhook 或回调由服务商确认、幂等结算以及退款。 Source: https://kernlift.dev/zh/docs/extensions/payments Kernlift 中的一笔支付经历四个阶段:服务端按方案价格创建订单,买家在服务商的托管结账页付款,服务商确认付款,结算把订单变成发票,并通知履约插件交付方案所售的内容。接入服务商见[接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 ## 生命周期概览 | 阶段 | 触发方 | 结果 | | -- | ------------------------------------ | ------------------------------------------------ | | 结账 | 已登录买家调用 `POST /api/billing/checkout` | 一个 `pending` 订单和托管结账 URL | | 付款 | 买家在服务商页面操作 | 本地暂无变化 | | 确认 | 签名 Webhook,或向服务商查询的返回回调 | 订单变为 `paid`、`failed` 或 `canceled` | | 结算 | `paid` 确认 | 发票与订阅,先行提交 | | 履约 | 结算,在订单提交之后 | 每个已启用的 `billing.fulfilment` 插件收到一次通知;内置的那个发放方案积分 | | 退款 | 管理员 | 退款记录;退款成功后通知履约插件 | 同一时间只有一个默认服务商,所有方案都由它收款。唯一的例外是人民币钱包:以人民币(CNY)计价的方案在微信支付或支付宝启用且凭据齐全时由它们收款,优先微信支付,微信支付未就绪时走支付宝;其它币种仍走默认服务商。请求也可以显式指定服务商。各服务商共用这条生命周期,区别在于结账之后支持哪些操作。 | 服务商 | 订阅 | 客户门户 | 在管理后台退款 | | ------------ | ---------------------------- | ---- | ------------------- | | Stripe | 支持,按方案周期每月或每年续费 | 支持 | 支持 | | Creem | 取消与恢复 | 支持 | 不支持,只能在 Creem 控制台操作 | | PayPal | 不支持,仅一次性付款 | 不支持 | 不支持 | | DodoPayments | 无生命周期操作 | 不支持 | 不支持 | | 微信支付 | 不支持,仅人民币一次性付款 | 不支持 | 支持 | | 支付宝 | 不支持,仅人民币一次性付款 | 不支持 | 支持 | | Waffo | 支持,使用在 Waffo 创建的月付、年付订阅商品各一个 | 不支持 | 不支持,只能在 Waffo 后台操作 | 打开 **结账时允许使用优惠码** 后,Stripe 和 Waffo 的结账页还会显示优惠码输入框,账单记录买家的实付金额。见[提供优惠码](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 ## 结账价格由服务端决定 请求只指明方案 key。服务端加载该方案,把客户端发来的金额、币种和结账模式与之比较。发现任何不一致时,服务端会在调用服务商之前拒绝请求。 | 拒绝原因(HTTP 409) | 触发条件 | | ------------------------ | ---------------------------------- | | `unknown_plan` | 不存在该 key 的方案 | | `plan_inactive` | 方案未启用 | | `amount_mismatch` | 金额、币种或结账模式与方案不一致 | | `product_mismatch` | 请求中的产品与方案所售产品不同 | | `plan_interval_mismatch` | 方案按订阅计费,但周期不是每月或每年;或者相反 | | `provider_unsupported` | 方案将由微信支付或支付宝收款,但它是订阅或不以人民币计价 | | 履约方自定义的代码 | 某个已启用的履约插件在 `canCheckout` 中拒绝了这次购买 | 检查通过后,按方案价格保存一个 `pending` 订单。如果当前服务商未配置,订单标记为 `failed`,记录一条未配置事件,请求返回 409。否则服务商创建托管结账,其成功与取消 URL 都指回 `/api/billing/callback/:provider`。 微信支付没有托管收银页。Native 下单返回一个 `weixin://` 开头的 code URL,它保存在订单上,买家跳转到站内的 `/app/billing/pay/<orderId>`。这个页面只为待支付订单的登录所有者显示二维码,每三秒向服务端查询一次订单状态,支付成功后跳到成功 URL。二维码两小时后失效。 支付宝直接把买家带到电脑网站收银台,地址经 RSA2 签名,两小时后失效。Waffo 在与套餐匹配的 Waffo 商品上创建托管结账会话:一次性商品,或月付、年付订阅商品,价格取自套餐(含税)。 ## 只有服务商能把订单标记为已支付 买家返回时访问的 URL 不能证明已付款,因为任何人都能打开它。支付状态只会通过以下两种服务端确认之一发生变化。 **签名 Webhook。** `/api/billing/webhook/:provider` 在读取任何内容之前,先在原始请求体上校验服务商签名。它从事件中找到本地订单 id,再把事件类型映射为已支付、失败或取消。每个事件 id 都会保存,所以重复投递只会返回已保存的结果,不再产生效果。签名无效的事件保存为失败,不改变任何状态。各服务商的 Webhook 注册见[接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 **返回回调。** `/api/billing/callback/:provider` 除了记录日志外忽略 `status` 查询参数。它向服务商查询已保存的结账,只有服务商报告已支付时才结算。否则把订单留给 Webhook 处理。随后买家被重定向到成功或取消 URL。 两者谁先到达谁就完成结算,后到的不再产生变更。失败的 Webhook 可以在管理后台重试,重试会以新的事件 id 重新应用签名有效的载荷。 微信支付遵循同样的规则,有两点不同。通知先用微信支付公钥验签,再用 APIv3 密钥解密。通知和服务端查单都只有在金额(分)等于订单金额且币种为 CNY 时才结算。 支付宝的异步通知把签名放在表单请求体里,用支付宝公钥验签;只有应用 APPID、卖家用户号(已填写时)和金额都与订单一致才结算。服务端 `alipay.trade.query` 查单只有在原始应答的签名通过、金额一致时才结算。Waffo 的 webhook 用保存的 webhook 公钥验签,服务端确认查询该订单的支付记录。两者都记录实际扣款金额,用了优惠码时账单上能看到折后金额。 ## 结算是幂等的 Webhook 和回调都会运行结算,所以每一步都可以安全地重复: 1. 订单状态变为 `paid`。 2. 写入发票 `invoice_<orderId>`。 3. 订阅订单写入 `subscription_<orderId>`,并带上服务商订阅 id。如果回调先完成结算,之后到达的 Webhook 会补上该 id。 4. 以上写入提交之后,再把已付订单通知给每个已启用的履约插件。 ## 履约发生在提交之后 计费只负责订单、付款和退款。一笔已付订单让买家得到什么,由销售它的插件定义:该插件向 `billing.fulfilment` 服务端插槽贡献一个履约方(fulfiller)。计费代码不按名称引用任何履约方。 | 钩子 | 调用时机 | 用途 | | ----------------- | ------------------ | ------------ | | `canCheckout` | 创建订单和支付会话之前 | 用一个代码和原因拒绝购买 | | `onOrderPaid` | 订单提交为已付之后,每个订单一次 | 交付方案所售的内容 | | `onOrderRefunded` | 退款在服务商侧成功之后,每笔退款一次 | 收回退款对应的内容 | 每次调用都记录在 `billing_fulfilments` 中,每个订单、履约方和事件一行。插入这一行就是认领,所以即使 Webhook 和回调同时结算同一个订单,每个履约方也只运行一次。履约方抛出异常不会撤销付款。这一行标记为 `failed`,写入一条审计记录,[定时任务](https://kernlift.dev/zh/docs/core/background-jobs.md)会在 1 分钟、5 分钟、30 分钟、2 小时和 12 小时后依次重试。第六次尝试仍失败则放弃,留给运营者处理。如果订单在此期间已退款或取消,`paid` 事件会被放弃,不再交付。被停用插件的履约方不会被调用。 模板自带一个履约方 `plan-credits`,由底座插件贡献。它把方案附带的积分发放一次,作为来源为 `billing.order.<orderId>` 的购买记录。见[积分账本](https://kernlift.dev/zh/docs/extensions/credits.md)和[编写履约插件](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md)。 ## 退款与订阅变更 退款在管理后台创建,状态记录为 `pending`、`succeeded`、`failed` 或 `not_configured`。Stripe 针对 PaymentIntent 或 Charge 退款,遇到 Checkout Session 会先解析出对应的 PaymentIntent。微信支付通过退款接口退款:同步返回 `SUCCESS` 立即记为成功,`PROCESSING` 保持 `pending`,直到收到验签通过的 `REFUND.SUCCESS` 通知。支付宝通过 `alipay.trade.refund` 退款,以本地退款 id 作为 `out_request_no`,同一请求重复发送也只退一次。其他适配器报告不支持退款;Waffo 的退款和订阅变更在 Waffo 后台操作。是否全额退款按买家实付金额判断。退款成功后,履约插件会收到 `onOrderRefunded`,其中带有金额以及是否为全额退款。退款要收回什么由各插件决定。 取消订阅会把它设为在当前周期结束时终止,恢复则清除该标记。两者都需要结算时保存的服务商订阅 id。 ## 记录了什么 每一次结账、Webhook、回调和未配置的尝试都会连同签名结果、状态和原始载荷一起保存,管理员可以逐条查看。订单、发票、订阅、退款和履约是各自独立的记录。 ## 相关文件 - 结算/ - src/server/db/repositories/billing-payment.repository.ts - src/server/functions/billing-payment.ts - src/server/payments/wechatpay.ts - src/server/payments/alipay.ts - src/server/payments/waffo.ts - 履约/ - src/server/billing/fulfilment.ts - src/server/billing/fulfilment-types.ts - src/server/billing/plan-credits-fulfiller.ts - src/server/db/repositories/billing-fulfilment.repository.ts - 后台与工作台/ - src/components/billing/app-billing-pages.tsx - src/components/billing/billing-workspace.tsx - src/components/billing/wechat-pay-checkout.tsx ## 下一步 - [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) - [编写履约插件](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md) - [管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md) - [管理订单、退款与订阅](https://kernlift.dev/zh/docs/extensions/payments/subscriptions.md) - [积分账本](https://kernlift.dev/zh/docs/extensions/credits.md) --- # PayPal > 通过 PayPal 收款。 Source: https://kernlift.dev/zh/docs/extensions/payments/paypal * **结账** Orders,仅一次性付款 * **订阅** 不支持 * **客户门户** 不支持 * **退款** 不支持 ## 准备工作 准备公网 HTTPS 站点、`/admin/plans` 中已上架的套餐,以及能管理商户设置的账号。 **完成后**,能通过签名通知核对一笔订单。 ## 在 PayPal 完成准备 ### 创建沙箱 REST 应用 打开 [PayPal](https://developer.paypal.com/dashboard/applications/sandbox)。在 Apps & Credentials → Sandbox 中创建 REST 应用。 ### 复制应用凭据 打开应用,复制 Client ID 和 Secret。 ### 订阅订单事件 在 Webhooks 登记以 `/api/billing/webhook/paypal` 结尾的 HTTPS 地址,订阅 `CHECKOUT.ORDER.APPROVED`、`CHECKOUT.ORDER.COMPLETED` 和 `CHECKOUT.ORDER.VOIDED`。 ### 复制 Webhook ID 打开已保存的端点,复制 Webhook ID。 官方说明 · [创建 REST 应用](https://developer.paypal.com/api/get-started/) · [订阅 Webhook](https://developer.paypal.com/api/rest/webhooks/rest/) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/payment`。选择 **PayPal**,填写公网成功 URL、取消 URL,将 **API base URL** 设为 `https://api-m.sandbox.paypal.com`。 | 来源 | 后台字段 | | ---------- | ------------- | | Client ID | Client ID | | Secret | Client secret | | Webhook ID | Webhook ID | 勾选启用并点击 **保存 provider**。 **Webhook ID** 填写同一 REST 应用、同一环境下的端点 ID。此栏需要标识符。 <img src="/docs/guides/payments/paypal.zh.png" alt="Kernlift 后台的 PayPal 配置字段" width="512" height="465" loading="lazy" /> ## 验证 1. 用沙箱买家账号在 `/pricing` 购买套餐。 2. 在 `/admin/billing-webhooks` 确认签名校验通过。 3. 在 `/admin/orders` 找到同一订单,确认状态为已付款。 ## 切换到正式环境 在正式账号创建凭据并登记正式域名的 Webhook。将新端点的验签值、同一环境的凭据和 `https://api-m.paypal.com` 一起保存。 ## 常见问题 ### webhook 签名校验失败 确认 Webhook ID 属于当前 REST 应用及环境。PayPal 使用该 ID 和应用凭据校验通知。 ## 下一步 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) --- # 管理定价套餐 > 在管理后台新建和编辑定价页展示、结账售卖的套餐,并为每种语言填写文案。 Source: https://kernlift.dev/zh/docs/extensions/payments/pricing-plans `/pricing` 展示上架的套餐,结账按套餐上保存的价格收费。套餐在 `/admin/plans` 管理。价格、币种、计费周期、积分、状态和排序属于套餐本身,对所有语言生效。名称、描述、按钮文字和功能列表按语言分别填写。 ## 准备工作 * 拥有 `plans.read`(查看页面)和 `plans.write`(保存)的管理员账号。**Commerce Manager** 角色两者都有,见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 如果要让买家能付款,需要一个支付服务商,见[接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 * 确定套餐键。订单和订阅通过套餐键引用套餐,创建后不能修改。 ## 新建套餐 ### 打开套餐页 进入 **商业化 → 套餐**(`/admin/plans`)。页面统计套餐总数、在定价页展示的数量、已隐藏的数量和订阅制的数量,并列出每个套餐的价格、积分、语言和状态。点击**新建套餐**,打开 `/admin/plans/new`。 ### 填写套餐 | 字段 | 规则 | | ---------- | -------------------------------------------------- | | **套餐键** | 小写字母和数字,中间可用单个连字符或下划线分隔,最长 64 个字符;`new` 是保留字。创建后固定 | | **价格** | 以币种的主单位填写,例如 `29` 或 `29.50`,可以为零。按最小货币单位存储 | | **币种** | 三位代码,例如 `USD` 或 `CNY` | | **计费周期** | 每月、每年、一次性或终身 | | **赠送积分** | 不小于零的整数,订单付款后加到买家的积分余额 | | **在定价页展示** | 打开时套餐为 `active`;关闭后套餐隐藏,结账会以 `plan_inactive` 拒绝 | | **排序** | 整数,套餐按升序排列 | 计费周期决定套餐的收费方式。每月和每年的套餐是订阅,一次性和终身的套餐是单次付款。表单会显示当前适用哪一种。 ### 为每种语言填写文案 在每种语言下填写**名称**、**描述**、**按钮文字**和**功能**列表。套餐包含的功能勾选**包含**,未勾选的功能显示为不包含。没有填写文字的功能行不会保存。 英文必填。名称留空的语言没有这个套餐的数据行。该语言的 `/pricing` 和结账都使用英文行,功能列表也是英文的。定价页用到的每种语言都应填写。 ### 保存 点击**创建套餐**。保存被拒绝时,表单旁会指出问题,例如套餐键重复或币种不合法,此时不会写入任何数据。 ## 编辑套餐 从列表打开套餐,改完后点击**保存套餐**。保存时,共享字段写入每个语言行,每种语言的文案和功能列表替换为表单里的内容。清空某种语言的名称会删除该语言的那一行及其功能列表。 改价只影响之后的新结账。已有订阅仍按支付服务商当前的扣款金额。 如果列表提示部分套餐的各语言行价格、周期或积分不一致,把这些套餐逐个打开并保存一次。保存会把相同的值写入所有语言行。 **Note** 微信支付和支付宝只对以 `CNY` 计价、单次付款的套餐收款。启用其中任一个后,人民币套餐由它收款(优先微信支付),其它币种由默认服务商收款。Waffo 只能通过与套餐匹配的 Waffo 商品销售:一次性套餐需要一次性商品,月付或年付套餐需要对应周期的订阅商品。 ## 验证套餐 * 用每种语言打开 `/pricing`。套餐出现在应有的位置,显示该语言的名称、价格和功能。隐藏的套餐不出现。 * 用普通用户登录,用服务商的测试卡购买这个套餐。`/admin/orders` 中订单金额等于套餐价格,套餐积分出现在买家的 `/app/credits`。 * `/admin/audit` 中有 `billing.plan.created` 或 `billing.plan.updated`,操作者是你的账号,目标是套餐键。 * `pnpm validate:pricing-plans` 通过。 ## 排查问题 ### 结账返回 `amount_mismatch` 页面是在改价之前加载的。结账会把浏览器发来的金额、币种和模式与已保存的套餐比较,不一致时拒绝请求。刷新页面即可。 ### 结账返回 `plan_interval_mismatch` 套餐行按订阅计费,但周期不是每月或每年,或者相反。只有不经后台写入的数据行才会出现这种情况。在 `/admin/plans` 打开该套餐并保存,之后计费模式由周期决定。 ### 某种语言的定价页上,套餐显示英文文案 该语言没有这个套餐的数据行,定价页显示的是英文行。打开套餐,填写该语言的名称。 ## 下一步 - [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) 为这些套餐收款。 - [积分](https://kernlift.dev/zh/docs/extensions/credits/usage.md) 赠送的积分用来支付什么。 - [编写履约插件](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md) 套餐被购买时,交付积分以外的内容。 - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) 结账如何按套餐给订单定价。 --- # 销售产品和方案 > 你的产品带着价格出现在前台;买家购买后获得授权,并用 GitHub 用户名激活。 Source: https://kernlift.dev/zh/docs/extensions/payments/products 商店的售卖内容在后台定义。产品是买家获得授权的对象。方案是该产品在某一种语言下的一个价格。结账始终按方案上保存的价格收费。 ## 准备工作 * 拥有 `products.read` 和 `products.write` 的管理员账号,内置的 **Commerce Manager** 角色已包含这两项。 * 要收取真实款项,需要先接入支付服务商,见 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 ## 从预置目录开始 刚完成迁移的数据库没有任何商品,店面是空的。先写入售卖站自带的目录(Kernlift Premium 会员和各个业务模板),然后在此基础上修改: ```bash pnpm db:seed-storefront ``` 该命令只插入缺失的行,重复执行不会产生变化,也不会覆盖你改过的文案与价格。预置价格只是示例,请按下面的步骤改成自己的定价。目录定义在 `scripts/db/storefront-catalog.ts`,售卖自己的产品时替换这个文件。 ## 创建产品 ### 打开表单 进入 **商业化 → 产品**(`/admin/products`),点击 **新建产品**。 ### 描述产品 * **键**:稳定的标识,只能使用小写字母、数字、连字符或下划线,例如 `cms`。保存后不能修改。 * **类型**:**底座** 即会员商品(附带底座仓库,并解锁会员价);**模板** 是单独出售的业务模板。**模块** 和 **全家桶** 保留给按那种方式售卖的目录。 * **状态**:**在售** 的产品会在前台列出;**隐藏** 和 **下架** 不会。 * **交付仓库(owner/name)**:买家激活后被邀请进入的 GitHub 私有仓库,例如 `kernlift/image-studio`。没有填写的商品会显示为尚未开放,无法购买。 * **依赖(逗号分隔的产品键)** 与 **全家桶(持有者可使用全部在售产品)**:会员和模板留空、不勾选。 * 每种语言的 **名称**、**一句话卖点** 和 **描述**。 ### 保存 点击 **保存产品**,页面会打开该产品,以便继续添加方案。 ## 添加方案 每个方案是一种语言下的一个价格,所以同时以英文和中文销售的产品,每种语言各有一行方案。 业务模板在每种语言下有两个方案:`<key>-lifetime` 是任何人都能支付的原价,`<key>-member` 是会员价。键以 `-member` 结尾的方案只有持有会员授权的账号可以结账,否则服务端会拒绝。 ### 新建方案 在产品页面的 **定价方案** 卡片中点击 **+ 方案键**。要编辑已有方案,点击它的按钮(显示为 `方案键 · 语言`)。 ### 设置价格 * **方案键**(例如 `pro_monthly`)和 **语言**,保存后都不能修改。 * **价格(分)** 和 **币种**,例如 `4900` 和 `usd`。 * **周期**:**按月**、**按年**、**终身** 或 **一次性**,显示在价格旁边。 * **结账模式**:`payment` 为一次性收费,`subscription` 为周期性收费。Stripe 创建的订阅按月计费。 * **包含积分**:该方案的订单付款后发放一次的积分,见 [用积分对用量计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md)。 * **方案状态**:`active` 可以购买,`deferred` 不能购买。 ### 填写卡片文案 填写 **名称**、**描述**、**按钮文案** 和 **按钮链接**,可选填 **AI 额度说明**。在 **功能列表(每行一项,以 - 开头表示不包含)** 中每行写一项功能。 ### 保存 点击 **保存方案**,页面显示 **方案已保存。**,结账立即使用新价格。每种语言重复一次。 **产品在哪里展示** 只有 **状态** 为 **在售** 的产品才会列出。`/pricing` 用一张卡片展示会员,并列出各模板的原价和会员价。访问者是会员时结账用会员价方案,否则用原价方案。访问者语言下没有价格大于零的启用方案时显示 **暂未定价**。 ## 了解购买会获得什么 服务商确认付款后,买家会获得: * `/app/billing` 中的发票;`subscription` 方案还会生成一条订阅。 * 方案的 **包含积分**,每笔订单只发放一次。 * `/app/licences`(**已购模板**)中该方案产品的授权。 拿到授权还不等于拿到代码。买家在该页面填写自己的 GitHub 用户名并点击 **激活**,售卖站随即把该账号以只读权限邀请进商品的交付仓库。用户名在首次激活后不可更改;GitHub 的邀请 7 天后过期,可以在同一页面重新发送。 激活即视为交付:授权已激活的订单不能再退款;从未激活的订单可以退款,全额退款会撤销它的授权。在 **商业化 → 授权** 中撤销一条已激活的授权,会把该账号移出仓库。 邀请由你保存在 **商业化 → 产品** 页「GitHub 交付」区域的 GitHub 令牌发出,令牌需要对每个交付仓库有管理权限。没有令牌时,买家激活会被告知交付尚未配置,且不会记录任何状态。 要不经购买直接授予授权,在 **商业化 → 授权**(`/admin/licences`,需要 `licences.write`)中使用 **授予授权**。账号不能重复购买已持有的商品。 ## 在自己的页面添加购买按钮 定价卡片会向结账 API 发起请求,你也可以在任意已登录页面这样做。请原样传入方案的价格、币种和模式,值不一致的请求会被拒绝。 ```ts title="src/components/billing/buy-button.tsx" const response = await fetch("/api/billing/checkout", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ planKey: "growth", checkoutMode: "subscription", amountCents: 9900, currency: "usd", locale: "zh", }), }); const result = await response.json(); if (response.status === 409 && result.message) { // result.status 为 unknown_plan、plan_inactive、amount_mismatch、 // product_mismatch、membership_required 或 already_owned throw new Error(result.message); } if (result.checkoutUrl) window.location.assign(result.checkoutUrl); ``` 成功时 API 返回 `201` 和服务商站点上的 `checkoutUrl`。付款后买家回到 **成功 URL**,查询参数中带有 `billing_order_id`、`billing_status` 和 `provider`。不要把这些参数当作付款凭证,应以订单状态为准。 ## 验证 在每种语言下打开 `/pricing`,确认显示了方案的价格。用测试卡购买,然后在 **商业化 → 订单** 中确认订单已付款,并在买家的 `/app/licences` 中看到可激活的授权。`pnpm validate:github-delivery` 检查会员价、激活、退款规则与撤销;`pnpm validate:billing` 检查结算只发放一次方案积分。 ## 常见问题 ### 产品没有出现在前台 产品的 **状态** 不是 **在售**。改为 **在售** 并点击 **保存产品**。 ### 卡片显示暂未定价 该语言下没有价格大于零、状态为 `active` 的方案。为该语言添加或修改方案。 ### 结账返回 409 和 `amount_mismatch` 请求中的金额、币种或模式与方案不一致。请原样传入方案的值。在后台修改方案后,期望金额立即变化。 ### 结账返回 409 和 `membership_required` 请求使用了会员价方案(`<key>-member`),而账号没有会员授权。买家可以先成为会员,或用原价方案购买该模板。 ### 结账返回 409 和 `already_owned` 账号已持有该商品的有效授权。请引导买家到 `/app/licences` 激活。 ### 激活时提示交付尚未配置 商品没有填写 **交付仓库**,或没有保存 GitHub 令牌。在 **商业化 → 产品** 中补齐两者,再用「验证已保存的令牌」确认 GitHub 接受该令牌。 ## 参考 * [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) * [Stripe products and prices](https://stripe.com/docs/products-prices/overview) ## 下一步 - [管理订单、退款和订阅](https://kernlift.dev/zh/docs/extensions/payments/subscriptions.md) - [用积分对用量计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md) - [管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md) --- # 接入支付服务商 > 完成后,买家在 Stripe、Creem、PayPal、DodoPayments、微信支付、支付宝或 Waffo 付款,付款确认后订单标记为已付款。 Source: https://kernlift.dev/zh/docs/extensions/payments/setup 同一时间只有一个支付服务商处于启用状态。微信支付和支付宝例外。启用且配置齐全后,所有人民币计价的套餐都由它们收款:优先微信支付,微信支付未就绪时走支付宝;其它币种仍由当前服务商收款。你在后台接入服务商、注册 webhook,再完成一笔测试付款。支付功能不需要任何环境变量。 ## 准备工作 * 服务商账号及其 API 凭据。微信支付使用正式商户号,其他厂商(包括支付宝沙箱)先使用测试环境。 * 部署后的公网地址。本地 `127.0.0.1` 收不到 webhook。 * 拥有 `config.read` 和 `config.write` 的管理员账号。 * `/admin/plans` 中至少有一个上架的套餐,见[管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)。 ## 在支付服务商创建测试资源 | 厂商 | 适用场景 | | --------------------------------------------------------- | ------------------------------------------- | | [Stripe](https://kernlift.dev/zh/docs/extensions/payments/stripe.md) | 订阅结账、门户与退款 | | [Creem](https://kernlift.dev/zh/docs/extensions/payments/creem.md) | 托管结账,请先核对适配器兼容性 | | [PayPal](https://kernlift.dev/zh/docs/extensions/payments/paypal.md) | 使用沙箱买家验证一次性付款 | | [DodoPayments](https://kernlift.dev/zh/docs/extensions/payments/dodopayments.md) | 绑定厂商商品 ID 的托管结账 | | [微信支付](https://kernlift.dev/zh/docs/extensions/payments/wechat-pay.md) | 人民币一次性扫码收款 | | [支付宝](https://kernlift.dev/zh/docs/extensions/payments/alipay.md) | 人民币一次性付款,跳转支付宝电脑网站收银台,支持退款 | | [Waffo](https://kernlift.dev/zh/docs/extensions/payments/waffo.md) | 代收代缴销售税的托管结账(merchant of record),支持一次性和订阅套餐 | ## 填写服务商配置 ### 打开支付配置 进入 **设置 → 支付配置**(`/admin/config/payment`)。每个服务商卡片会显示 **缺少密钥** 或 **已配置**,以及 **Webhook 未配置** 或 **Webhook 已配置**。点选要配置的服务商。 ### 填写 Checkout 跳转 在 **Checkout 跳转** 中填写: * **成功 URL**:付款确认后买家的落地页,例如 `https://<你的域名>/app/billing`。 * **取消 URL**:其他情况下的落地页,例如 `https://<你的域名>/pricing`。 * **API base URL**:调用的服务商 API 地址。Creem、PayPal 和 DodoPayments 默认分别是 `https://api.creem.io`、`https://api-m.sandbox.paypal.com` 和 `https://test.dodopayments.com`,在测试和正式环境之间切换时修改这里。Stripe 不使用这个字段,测试环境还是正式环境由密钥决定。微信支付默认 `https://api.mch.weixin.qq.com`,只有这一个环境。支付宝默认指向沙箱网关;Waffo 只有 `https://api.waffo.ai` 一个地址,测试还是正式由密钥决定。 * **结账时允许使用优惠码**:见[提供优惠码](#提供优惠码)。 买家在到达成功 URL 之前会先回到你自己的域名,所以这里要填公网域名。 ### 填入 API 凭据 在 **密钥配置** 中填写所选服务商的字段: 按上方对应厂商指南中的字段对照表填写。 密钥字段保存后不会再显示,留空保存会保留已保存的值。 ## 注册 webhook 按上表中对应厂商的指南登记 HTTPS 端点、勾选事件并保存验签凭据。微信支付和支付宝在每次下单时传入通知地址。 ## 启用服务商 勾选 **设为当前支付 provider**,点击 **保存 provider**。卡片上会出现 **启用中** 和 **Webhook 已配置**,**运行状态** 面板显示当前服务商。取消勾选并保存当前服务商后,没有任何服务商处于启用状态。不勾选保存其它服务商,当前服务商保持不变。勾选微信支付或支付宝会为人民币套餐启用该渠道,只有在没有其它当前服务商时才把它设为当前服务商。**能力** 面板会显示该服务商是否支持客户门户、订阅、退款和优惠码。 ## 提供优惠码 在 **Checkout 跳转** 中打开 **结账时允许使用优惠码**,点击 **保存 provider**。这个开关只存一份(`payment.checkout.allow_promotion_codes`),默认关闭。打开后 Stripe 和 Waffo 的托管结账页会显示优惠码输入框;其它服务商忽略此开关,**能力** 面板中优惠码显示为不支持。优惠码本身在服务商后台创建。 账单的实付金额取自签名 webhook 或服务端确认给出的实收金额,应付金额仍是套餐原价。退回买家实付的全部金额即为全额退款。 ## 验证 用普通用户登录,打开 `/pricing`,用服务商的测试卡或沙盒买家购买一个方案,然后检查: * **安全 → Webhooks**(`/admin/billing-webhooks`)中出现该服务商的事件,签名校验通过。 * **商业化 → 订单**(`/admin/orders`)中订单状态为已付款。 * 买家的 `/app/billing` 中出现发票,方案附带的积分出现在 `/app/credits`。积分由内置的履约插件在订单提交后发放。如果积分没有到账,到 `/admin/audit` 查找 `billing.fulfilment.failed` 记录。 * 使用微信支付时,买家跳转到 `/app/billing/pay/<order>`,用微信扫码付款,付款后几秒内页面跳到成功 URL。 * 使用支付宝时,买家跳转到支付宝收银台,付款后经 `/api/billing/callback/alipay` 回到站点,服务端先查单再把订单标记为已付款。 `pnpm validate:billing` 会检查订单状态机、未配置路径和签名处理。`pnpm validate:wechat-pay` 在不调用微信支付的前提下检查签名、解密、金额核对和按币种选渠道。`pnpm validate:alipay`、`pnpm validate:waffo` 和 `pnpm validate:promotion-codes` 分别对支付宝、Waffo 和折后金额做同样的检查。要真实调用沙盒,在保存好服务商凭据后运行 `pnpm validate:external`。 ## 常见问题 ### 买家从定价页被带到 `/system/payment-failed` 结账被拒绝。到 **Webhooks** 查看 `checkout.not_configured` 或 `checkout.failed` 事件及错误信息,然后在 **支付配置** 中补全凭据。DodoPayments 还需要产品 id。 ### webhook 签名校验失败 确认保存的 **Webhook secret** 是该端点的签名密钥,DodoPayments 要保存完整的 `whsec_…`。Stripe 和 DodoPayments 会拒绝与服务器时间相差超过 300 秒的事件,请检查服务器时间。改写请求体的代理也会导致签名失效。 ### 买家付款后落到不存在的页面 在默认值变更之前初始化的数据库中,**成功 URL** 可能仍是没有对应路由的 `http://127.0.0.1:5173/app/billing/orders`。把它改为存在的页面,例如 `https://<你的域名>/app/billing`。 ### 微信支付或支付宝下单被拒绝,原因是 `provider_unsupported` 微信支付和支付宝只收人民币一次性付款。在 `/admin/plans` 把套餐的币种设为 `CNY`、计费周期设为一次性或终身,或改用其它服务商收款。 ### 订单一直是待付款 webhook 没有到达,买家也没有回到网站。确认端点已注册且订阅了正确的事件,然后在服务商后台重新发送事件。 ## 参考 * [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) * [Stripe webhooks](https://stripe.com/docs/webhooks) ## 下一步 - [管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md) - [编写履约插件](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md) - [管理订单、退款和订阅](https://kernlift.dev/zh/docs/extensions/payments/subscriptions.md) - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) --- # Stripe > 通过 Stripe Checkout 收取一次性付款和按月、按年续费的订阅,支持退款和客户门户。 Source: https://kernlift.dev/zh/docs/extensions/payments/stripe Stripe 是适配最完整的支付服务商。买家在 Stripe 托管的 Checkout 页面付款,价格取自你的套餐,所以不需要在 Stripe 里创建产品或价格。 ## 支持的能力 | 能力 | 是否支持 | 说明 | | ----- | ----- | ---------------------------- | | 一次性付款 | 支持 | 计费周期为一次性或终身的套餐 | | 订阅 | 支持 | 按月或按年续费的套餐 | | 在后台退款 | 支持 | 全额或部分退款,在 `/admin/orders` 操作 | | 客户门户 | 支持 | 买家从 `/app/billing/portal` 打开 | | 币种 | 套餐的币种 | 按套餐上保存的币种原样发给 Stripe | 续费由 Stripe 扣款。这个适配器只结算订阅的第一笔付款,不处理 Stripe 的 `invoice.*` 事件,所以续费不会生成新订单,也不会再次发放套餐附带的积分。 ## 准备工作 **你需要准备** * 一个 Stripe 账号。整个流程跑通之前使用测试模式。 * 站点已部署到公网 HTTPS 地址。Stripe 无法把 webhook 发到 `127.0.0.1`。 * 拥有 `config.read` 和 `config.write` 的管理员账号。 * `/admin/plans` 中至少有一个上架的套餐,见[管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)。 **完成后你会得到** * 保存在后台的密钥(`sk_test_…`)和 webhook 签名密钥(`whsec_…`)。 * Stripe 成为当前支付服务商,并有一笔测试购买结算为已付款订单。 ## 在 Stripe 完成准备 下面这些步骤在 Stripe Dashboard 里完成。 ### 打开测试环境的 API 密钥页 打开 [dashboard.stripe.com/test/apikeys](https://dashboard.stripe.com/test/apikeys)。地址里的 `/test/` 表示你在测试模式。 **测试密钥和正式密钥不能混用** 测试密钥只能搭配测试环境的 webhook 签名密钥,正式密钥只能搭配正式环境的。先在测试模式把整个流程跑通,再去正式模式创建任何东西。 ### 复制密钥 在 **Standard keys** 下,点击 **Secret key** 一行的 **Reveal test key**,复制密钥。它以 `sk_test_` 开头。 ### 打开 webhook 页面 打开 [dashboard.stripe.com/test/workbench/webhooks](https://dashboard.stripe.com/test/workbench/webhooks),点击 **Add destination**。 ### 选择事件 勾选下面三个事件,然后继续: | 事件 | 在这里的作用 | | --------------------------------------- | ------------------ | | `checkout.session.completed` | 把订单标记为已付款,并保存订阅 id | | `checkout.session.async_payment_failed` | 把订单标记为失败 | | `checkout.session.expired` | 把订单标记为已取消 | 这三个结账会话事件覆盖表中的状态变化。 ### 填写端点地址 目标类型选择 **Webhook endpoint**,把 **Endpoint URL** 设为: ```text https://<你的域名>/api/billing/webhook/stripe ``` 点击 **Create destination**。 ### 复制签名密钥 在这个目标的详情页里,显示并复制 **Signing secret**。它以 `whsec_` 开头。 **每个目标一个密钥** 每个目标有自己的签名密钥。从别的目标或 Stripe CLI 复制来的密钥无法校验这里的事件。 ### 启用客户门户(可选) 如果要让买家自己管理银行卡和取消订阅,打开 [dashboard.stripe.com/test/settings/billing/portal](https://dashboard.stripe.com/test/settings/billing/portal),点击 **Activate test link**。如果有多套门户配置,复制要使用的那一套的 id,它以 `bpc_` 开头。 Stripe 官方说明:[Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks) 和 [Activate the customer portal](https://docs.stripe.com/customer-management/activate-no-code-customer-portal)。 ## 填写后台配置 回到 Kernlift 后台。 ### 打开支付配置 进入 **设置 → 支付配置**(`/admin/config/payment`),点选 **Stripe** 卡片。 ### 填写跳转地址 在 **Checkout 跳转** 中,把 **成功 URL** 设为付款后买家的落地页,例如 `https://<你的域名>/app/billing`;把 **取消 URL** 设为其他情况下的落地页,例如 `https://<你的域名>/pricing`。**API base URL** 保持不动,Stripe 不使用它。 ### 粘贴从 Stripe 复制的值 在 **密钥配置** 中,把每个值粘贴到对应的字段: | Stripe 里的名称 | 后台表单里的字段 | | ------------------------- | --------------------------- | | Secret key(`sk_test_…`) | **Secret key** | | Signing secret(`whsec_…`) | **Webhook secret** | | 门户配置 id(`bpc_…`),可选 | **Portal configuration ID** | 密钥字段保存后不会再显示,留空保存会保留已保存的值。 ### 把 Stripe 设为当前服务商 勾选 **设为当前支付 provider**,点击 **保存 provider**。卡片上会显示 **启用中**、**已配置** 和 **Webhook 已配置**。 <img src="/docs/guides/payments/stripe.zh.png" alt="Stripe 支付配置的密钥字段" width="512" height="465" loading="lazy" /> ## 验证 1. 用普通用户登录,打开 `/pricing`,购买一个套餐。**预期结果**:跳转到 Stripe 的 Checkout 页面。 2. 用测试卡 `4242 4242 4242 4242` 付款,有效期填任意未来日期,CVC 任意(见 [Stripe 测试卡](https://docs.stripe.com/testing))。**预期结果**:页面回到 **成功 URL**。回跳途中,`/api/billing/callback/stripe` 会先向 Stripe 确认该会话已付款,再把订单标记为已付款。 3. 打开 **安全 → Webhooks**(`/admin/billing-webhooks`)。**预期结果**:有一条来自 Stripe 的 `checkout.session.completed` 事件,签名校验通过。 4. 打开 **商业化 → 订单**(`/admin/orders`)。**预期结果**:订单为已付款,买家在 `/app/billing` 看到发票,在 `/app/credits` 看到套餐附带的积分。 要测试退款,打开这笔订单并创建退款,见[管理订单、退款和订阅](https://kernlift.dev/zh/docs/extensions/payments/subscriptions.md)。 ## 切换到正式环境 1. 打开 [dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys)(地址里没有 `/test/`),复制正式的 **Secret key**(`sk_live_…`)。 2. 打开 [dashboard.stripe.com/workbench/webhooks](https://dashboard.stripe.com/workbench/webhooks),重新添加目标,地址和事件与之前相同。复制它新的签名密钥;测试模式的密钥无法校验正式事件。 3. 把这两项保存到 `/admin/config/payment`,并确认 **成功 URL** 和 **取消 URL** 指向正式域名。 4. 真实购买一次,再退款。 ## 常见问题 ### webhook 记录显示签名校验失败 保存的 **Webhook secret** 不是这个目标的签名密钥,或者来自另一种模式。事件时间戳与服务器时钟相差超过 300 秒时也会被拒绝,请检查服务器时间。改写请求体的代理同样会让签名失效。 ### 付款成功后订单一直是待付款 经 `/api/billing/callback/stripe` 的回跳和 webhook 都没有到达站点。确认目标地址是公网地址,并且勾选了 `checkout.session.completed`,然后在 Stripe Dashboard 里重新发送事件。 ### 结账被拒绝,原因是 `plan_interval_mismatch` 套餐按订阅计费,但周期不是月或年;或者按一次性计费,周期却是月或年。到 `/admin/plans` 重新保存这个套餐,表单会让两者保持一致。 ### 退款失败,提示 "requires a PaymentIntent or Charge id" 这笔订单背后没有 Stripe 付款,通常是结账没有完成。只有已付款的订单才能退款。 ## 下一步 - [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) 比较各家服务商,以及它们共用的设置。 - [管理订单、退款和订阅](https://kernlift.dev/zh/docs/extensions/payments/subscriptions.md) 退款、取消订阅、打开客户门户。 --- # 管理订单、退款和订阅 > 完成后,你可以为订单退款、取消或恢复订阅、让买家自助管理账单,并重新处理失败的 webhook。 Source: https://kernlift.dev/zh/docs/extensions/payments/subscriptions 成交之后,运营人员在后台的 **商业化** 和 **安全** 区域操作,买家使用自己的账单页面。所有变更都通过支付服务商执行,所以可用的操作取决于当前启用的服务商。 ## 准备工作 * 一个已接入并至少完成过一笔付款的服务商,见 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md)。 * 与操作对应的权限:退款需要 `orders.write`,订阅变更需要 `subscriptions.write`,重试 webhook 需要 `webhooks.write`。打开页面需要对应的 `.read` 权限。 * 在后台退款需要 Stripe、微信支付或支付宝;Creem 和 Waffo 的退款在各自后台操作。订阅变更和客户门户需要 Stripe 或 Creem。 ## 为订单退款 ### 打开订单 进入 **商业化 → 订单**(`/admin/orders`),打开订单。 ### 创建退款 填写要退回的 **金额 cents** 和 **原因**,点击 **创建退款**。退款记录的状态为待处理、成功、失败或未配置。 全额退款成功后,该订单签发的授权被撤销。部分退款不撤销任何授权。退款不会改变订单状态,也不会收回积分,需要时请手动扣减积分,见 [用积分对用量计费](https://kernlift.dev/zh/docs/extensions/credits/usage.md)。Creem 退款需要在 Creem 后台操作。 ## 取消或恢复订阅 ### 打开订阅 进入 **商业化 → 订阅**(`/admin/subscriptions`),打开订阅。 ### 执行变更 点击 **周期结束时取消** 停止续费,或点击 **恢复订阅** 撤销取消。变更会发送给服务商。 两个操作都需要服务商的订阅 id,这个 id 包含在付款成功的 webhook 中。 ## 让买家管理账单 买家在 `/app/billing` 查看当前方案、订单和发票,并可导出 CSV。更换卡片或取消订阅则在服务商的客户门户中进行。 ### 打开门户页面 买家打开 `/app/billing/portal`。 ### 创建会话 **Provider** 保持 **已配置默认值**,填写 **Provider customer ID**(Stripe 为 `cus_…`),点击 **创建 portal session**。服务商创建会话后,页面显示 **Portal 已就绪:** 和门户地址。否则显示状态。 **替换门户表单** 门户页面是一个简单表单。在你的产品中,把它换成一个传入已保存客户 id 的按钮。 ## 重试失败的 webhook 签名正确但处理失败的 webhook(例如遇到临时的数据库错误)可以重新处理。 ### 找到事件 进入 **安全 → Webhooks**(`/admin/billing-webhooks`),打开事件查看 payload、签名结果和错误信息。 ### 重试 在失败的事件上点击 **重试**。系统重新处理已保存的 payload,并把结果记录为一条新事件。 签名无效的事件无法重试,请在服务商后台重新发送。 ## 验证 * 退款后,订单页面列出该退款及其状态。全额退款后,买家的 `/app/licences` 中不再有该授权。 * 点击 **周期结束时取消** 后,订阅页面的 **周期结束时取消** 显示为 `是`。**恢复订阅** 会把它改回 `否`。 * 重试后,**Webhooks** 中出现同一 payload 的新事件。 `pnpm validate:billing` 会检查退款、订阅和 webhook 路径。设置好沙盒 id 后,`pnpm validate:external` 会真实调用客户门户、取消、恢复和退款接口。 ## 常见问题 ### Stripe 退款提示没有可退款的 PaymentIntent 报错 `The Stripe checkout session has no PaymentIntent to refund.` 说明该结账 session 从未产生付款,没有可退回的款项。 ### 取消或恢复返回 `missing_provider_subscription` 携带服务商订阅 id 的付款成功 webhook 还没有到达。到 **Webhooks** 查看该事件。如果没有,先注册 webhook。 ### 退款记录为未配置或失败 未配置表示接单服务商的凭据在 **支付配置** 中缺失。退款失败时,**Webhooks** 中会有一条带错误信息的 `refund.failed` 事件。Stripe 以外的服务商会报 `This payment provider does not support refunds through this adapter.`,请在其后台退款。 ### 门户页面提示门户未配置 当前服务商没有客户门户,只有 Stripe 和 Creem 提供。 ## 参考 * [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) * [Stripe subscriptions](https://stripe.com/docs/billing/subscriptions/overview) ## 下一步 - [支付生命周期](https://kernlift.dev/zh/docs/extensions/payments.md) - [销售产品和方案](https://kernlift.dev/zh/docs/extensions/payments/products.md) - [编写履约插件](https://kernlift.dev/zh/docs/extensions/payments/fulfilment.md) --- # Waffo > 通过 Waffo 收款,由它作为 merchant of record 代收代缴销售税。 Source: https://kernlift.dev/zh/docs/extensions/payments/waffo * **结账** Waffo 托管结账页,价格取自套餐(含税) * **订阅** 月付与年付,首期付款时结算 * **客户门户** 不支持 * **退款** 只能在 Waffo 后台操作 * **优惠码** 支持 Waffo 是 merchant of record(记录商户):由它向买家销售并处理各地销售税。结账要求商品预先存在于 Waffo,但只需建三个商品,所有套餐共用;每次结账的价格取自套餐。 ## 准备工作 准备公网 HTTPS 站点、`/admin/plans` 中已上架的套餐(见[管理定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md)),以及开好店铺的 Waffo 商户账号。整个流程跑通前都在测试环境操作。 **完成后**,一笔测试订单经签名的 `order.completed` 或 `subscription.activated` webhook 结算。 ## 在 Waffo 完成准备 ### 创建 API 密钥 在 Waffo 后台打开 **API & Development → API Keys**,点击 **Create API Key** 并选择测试环境。立即下载私钥,之后不会再显示。测试还是正式由密钥所属环境决定。同时记下商户 ID(`MER_…`)。 ### 创建商品 创建一个一次性商品、一个月付订阅商品和一个年付订阅商品,复制它们的 ID。每次结账都会覆盖价格,商品本身的价格无所谓。 ### 登记 webhook 在 **Settings → Webhooks** 添加一个测试模式的 HTTP webhook,地址为 `https://<你的域名>/api/billing/webhook/waffo`,订阅 `order.completed` 和 `subscription.activated`。 ### 复制 webhook 公钥 在同一页面复制测试环境的 **Webhook Public Key**。测试和正式环境的公钥不同。 官方说明 · [认证](https://docs.waffo.ai/api-reference/authentication) · [创建结账会话](https://docs.waffo.ai/api-reference/endpoints/orders/create-checkout-session) · [Webhooks](https://docs.waffo.ai/api-reference/webhooks) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/payment`。选择 **Waffo**,填写公网成功 URL 和取消 URL,**API base URL** 保持 `https://api.waffo.ai`。 | 来源 | 后台字段 | | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | 商户 ID(`MER_…`) | **商户 ID(MER\_...)** | | 所售商品的税务类别:`saas`、`digital_goods`、`software`、`ebook`、`online_course`、`consulting` 或 `professional_service` | **税务类别(saas、digital\_goods、software 等)**;留空保持 `saas` | | 三个商品 ID | **一次性商品 ID**、**月付订阅商品 ID**、**年付订阅商品 ID** | | 下载的 API 私钥 | **商户私钥** | | 同一环境的 Webhook Public Key | **Webhook 公钥** | 勾选启用并点击 **保存 provider**。保存商户 ID、私钥和至少一个商品 ID 后卡片显示已配置;保存 webhook 公钥后显示 Webhook 已配置。要让买家输入优惠码,打开 **结账时允许使用优惠码**,优惠码在 Waffo 创建。 **套餐要有对应商品** 一次性套餐需要一次性商品,月付或年付套餐需要对应周期的订阅商品,缺少时下单被拒绝。按其它周期续费的订阅套餐无法通过 Waffo 销售。 <img src="/docs/guides/payments/waffo.zh.png" alt="Kernlift 后台的 Waffo 配置字段" width="512" height="985" loading="lazy" /> ## 验证 1. 用普通用户登录,打开 `/pricing` 购买套餐。**预期**:跳转到 Waffo 结账页,显示套餐价格。 2. 用 Waffo 的测试付款信息付款。**预期**:经 `/api/billing/callback/waffo` 回到站点,服务端先在 Waffo 查询该订单的支付记录,再标记为已付款。 3. 打开 `/admin/billing-webhooks`。**预期**:出现签名有效的 `order.completed`(一次性)或 `subscription.activated`(订阅)事件。 4. 打开 `/admin/orders`。**预期**:订单已付款,账单显示实际扣款金额;用了优惠码时低于套餐价格。 ## 切换到正式环境 1. 创建正式环境的 API 密钥和商品,并关闭测试模式重新添加 webhook。 2. 保存正式环境的商户私钥、商品 ID 和 webhook 公钥。测试密钥无法验证正式环境的事件。 3. 实付一笔,并在 Waffo 后台退款。 ## 常见问题 ### webhook 签名校验失败 保存的 webhook 公钥属于另一个环境,或者没有填写。Waffo 签名中的 `t` 以毫秒计,重试沿用原值,所以 45 分钟以内的事件都会接受,更早的会被拒绝。改写请求体的代理也会导致签名失效。 ### 下单失败,提示 "No Waffo subscription product is configured" 套餐是订阅,但它的周期没有对应的商品 ID。保存月付或年付商品 ID,或修改套餐周期。 ### 退款或续费没有反映到订单上 退款和订阅变更在 Waffo 后台操作。它们的事件(如 `refund.succeeded`、`subscription.renewed`)记为已忽略:不改变本地订单,不创建新订单,也不会再次发放套餐积分。 ## 下一步 - [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) 比较各服务商及共用的设置。 --- # 微信支付 > 通过 微信支付 收款。 Source: https://kernlift.dev/zh/docs/extensions/payments/wechat-pay * **结账** Native 扫码,二维码显示在站内 `/app/billing/pay/<订单>` 页面,只收人民币一次性付款 * **订阅** 不支持 * **客户门户** 不支持 * **退款** 支持 ## 准备工作 准备公网 HTTPS 站点、`/admin/plans` 中已上架的套餐,以及能管理商户设置的账号。 **完成后**,能通过签名通知核对一笔订单。 ## 在 微信支付 完成准备 ### 开通 Native 支付 打开 [微信支付](https://pay.weixin.qq.com/index.php/core/cert/api_cert)。在商户平台的产品中心开通 Native支付。 ### 关联 AppID 在 AppID账号管理关联应用,记下 AppID 和商户号。 ### 申请商户 API 证书 在 API安全申请商户 API 证书,保存私钥并记下证书序列号。 ### 设置解密密钥 设置用于解密支付通知的 APIv3 密钥。 ### 下载验签公钥 下载微信支付公钥并复制公钥 ID。下单时系统会自动传递通知地址。 官方说明 · [Native 支付](https://pay.weixin.qq.com/doc/v3/merchant/4012791874) · [使用微信支付公钥验签](https://pay.weixin.qq.com/doc/v3/merchant/4013053249) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/payment`。选择 **微信支付**,填写公网成功 URL、取消 URL,将 **API base URL** 设为 `https://api.mch.weixin.qq.com`。 | 来源 | 后台字段 | | -------------------------------------------------------- | ----------------------------- | | 商户平台 → 产品中心 → AppID账号管理,以及账户首页。 | **AppID**、**商户号(mchid)** | | 账户中心 → API安全 → 商户API证书;私钥粘贴完整的 `apiclient_key.pem`。 | **商户 API 证书序列号**、**商户私钥** | | 账户中心 → API安全 → APIv3密钥,即你设置的 32 位密钥。 | **APIv3 密钥** | | 账户中心 → API安全 → 微信支付公钥:`PUB_KEY_ID_…` 和完整的 `pub_key.pem`。 | **微信支付公钥 ID**、**微信支付公钥** | 勾选启用并点击 **保存 provider**。 **保留 PEM 格式** 两个 PEM 字段均保留首尾标记和换行。商户私钥只保存在服务端。 <img src="/docs/guides/payments/wechat-pay.zh.png" alt="Kernlift 后台的 微信支付 配置字段" width="512" height="969" loading="lazy" /> ## 验证 1. 选择小额人民币一次性套餐,扫码实付。 2. 在后台核对已验签的通知和已支付订单。 3. 在激活交付前退回测试款,并核对渠道退款状态。 ## 常见问题 ### 微信支付下单被拒绝,原因是 `provider_unsupported` 微信支付只收人民币一次性付款。在 `/admin/plans` 把套餐的币种设为 `CNY`、计费周期设为一次性或终身,或改用其它服务商收款。 ## 下一步 [接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) --- # Amazon S3 > 将上传文件保存到 Amazon S3。 Source: https://kernlift.dev/zh/docs/extensions/storage/aws-s3 ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能上传并下载同一个文件。 ## 在 Amazon S3 完成准备 ### 创建私有存储桶 打开 [Amazon S3](https://console.aws.amazon.com/s3/)。在目标区域创建私有存储桶。 ### 授予对象权限 为应用身份授予桶内对象的 GetObject、PutObject 和 DeleteObject 权限。 ### 创建访问密钥 创建访问密钥并保存 Secret。 官方说明 · [S3 建桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) · [IAM 访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/storage`。 | 来源 | 后台字段 | | ----------------- | ----------------- | | Bucket | Bucket 名称 | | Regional endpoint | S3 endpoint | | AWS Region | Region | | Access Key ID | Access Key ID | | Secret Access Key | Secret Access Key | 开启上传,选择 S3 兼容端点。签名区域须与实际桶所在区域一致。保存存储配置。 <img src="/docs/guides/storage/connection.zh.png" alt="Kernlift 后台的 Amazon S3 配置字段" width="512" height="1052" loading="lazy" /> ## 验证 1. 打开 `/app/assets/upload` 上传一个符合限制的小文件。 2. 从 `/app/assets` 下载该文件并核对内容。 ## 常见问题 ### S3 上传报 "Storage upload failed (403)" 错误中带有供应商自己的错误码和信息。检查 Access Key、Secret、存储桶名称,以及 **Region** 是否与端点的签名要求一致。 ## 下一步 [配置文件存储和上传](https://kernlift.dev/zh/docs/extensions/storage.md) --- # Cloudflare R2 > 将上传文件保存到 Cloudflare R2。 Source: https://kernlift.dev/zh/docs/extensions/storage/cloudflare-r2 ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能上传并下载同一个文件。 ## 在 Cloudflare R2 完成准备 ### 创建 R2 存储桶 打开 [Cloudflare R2](https://dash.cloudflare.com/)。创建 R2 存储桶并记下桶名。 ### 使用 Workers 原生绑定 使用 Workers 原生绑定时,在 `wrangler.jsonc` 中将该桶绑定为 `BUCKET` 并部署。 ### 使用兼容 S3 的令牌 使用 S3 接口时,为该桶创建对象读写令牌,保存 S3 密钥对和账户端点。 官方说明 · [R2 建桶与凭据](https://developers.cloudflare.com/r2/get-started/cli/) · [R2 token 权限](https://developers.cloudflare.com/r2/api/tokens/) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/storage`。 | 来源 | 后台字段 | | ----------------- | ----------------- | | Bucket | Bucket 名称 | | S3 endpoint | S3 endpoint | | Signing region | Region | | Access Key ID | Access Key ID | | Secret Access Key | Secret Access Key | 开启上传,选择 S3 兼容端点。R2 的 S3 签名区域填 `auto`。使用 Workers 原生绑定时选择平台绑定,跳过 S3 字段。保存存储配置。 <img src="/docs/guides/storage/connection.zh.png" alt="Kernlift 后台的 Cloudflare R2 配置字段" width="512" height="1052" loading="lazy" /> ## 验证 1. 打开 `/app/assets/upload` 上传一个符合限制的小文件。 2. 从 `/app/assets` 下载该文件并核对内容。 ## 常见问题 ### S3 上传报 "Storage upload failed (403)" 错误中带有供应商自己的错误码和信息。检查 Access Key、Secret、存储桶名称,以及 **Region** 是否与端点的签名要求一致。 ## 下一步 [配置文件存储和上传](https://kernlift.dev/zh/docs/extensions/storage.md) --- # 配置文件存储和上传 > 完成后,用户可以上传文件,并通过限时链接下载。文件保存在你自己的 S3 兼容存储桶或 R2 绑定中。 Source: https://kernlift.dev/zh/docs/extensions/storage 用户上传的文件和 AI 生成的媒体保存在同一个存储桶中。文件由服务端写入,浏览器不直接上传到存储桶,因此存储桶保持私有,也不需要 CORS 规则。存储在后台配置,不需要环境变量。 ## 准备工作 * 拥有 `config.read` 和 `config.write` 的管理员账号。 * 一个存储桶,或者应用运行在 Cloudflare Workers 上,且绑定了名为 `BUCKET` 的 R2 存储桶。 按应用的运行环境选择驱动: | 驱动 | 适用场景 | 需要准备 | | ----------- | -------------------------------------------------- | ----------- | | **S3 兼容端点** | 任意运行环境:Node、Docker、Cloudflare Workers。 | 存储桶和访问密钥。 | | **平台原生绑定** | 应用运行在 Cloudflare Workers,且绑定了名为 `BUCKET` 的 R2 存储桶。 | 只需绑定,不需要密钥。 | ## 在存储服务商创建存储桶 | 厂商 | 适用场景 | | ---------------------------------------------------------- | ---------------------- | | [Cloudflare R2](https://kernlift.dev/zh/docs/extensions/storage/cloudflare-r2.md) | Workers 原生绑定或兼容 S3 的端点 | | [Amazon S3](https://kernlift.dev/zh/docs/extensions/storage/aws-s3.md) | 使用区域签名的 AWS 私有桶 | | [MinIO](https://kernlift.dev/zh/docs/extensions/storage/minio.md) | 自托管对象存储 | ## 接入存储桶 **S3 兼容端点** ### 创建存储桶和访问密钥 在供应商控制台创建存储桶,并创建一个能在该桶内读、写、删除对象的 API 密钥。 | 供应商 | 端点 | Region | 访问密钥 | | ------------- | ----------------------------------------------- | ----------------------- | -------------------------------------------------------------------- | | Cloudflare R2 | `https://<account-id>.r2.cloudflarestorage.com` | `auto` | Cloudflare 控制台 → R2 → 管理 API 令牌,授予该桶的对象读写权限。 | | AWS S3 | `https://s3.<region>.amazonaws.com` | 存储桶所在区域,例如 `eu-west-1` | IAM 用户访问密钥,对该桶具有 `s3:PutObject`、`s3:GetObject`、`s3:DeleteObject` 权限。 | | MinIO | 服务器的 API 地址,例如 `http://minio.internal:9000` | 除非服务器另有设置,填 `us-east-1` | MinIO 控制台 → Access Keys。 | ### 填写连接信息 进入 **设置 → 存储配置**(`/admin/config/storage`),勾选 **启用上传**,选择 **S3 兼容端点**,然后填写: * **连接信息 → Bucket 名称**:刚创建的存储桶。 * **连接信息 → Region**:该厂商指南中的签名区域,默认 `us-east-1`。 * **连接信息 → S3 endpoint**:该厂商的 S3 API 地址,不要带存储桶名称。 * **密钥配置 → Access Key ID** 和 **Secret Access Key**:密钥对。 首次配置时,S3 选项在这些字段保存之前一直置灰,直接保存仍会使用它。 ### 保存 点击 **保存存储配置**,页面提示 **存储配置已保存。**,**运行状态** 面板中 **存储驱动** 下的 **读取方式** 显示 `sigv4`。 每次打开页面时密钥字段都是空的,留空表示保留已保存的值。 **平台原生绑定** ### 绑定存储桶 在 `wrangler.jsonc` 中声明名为 `BUCKET` 的 R2 存储桶绑定并部署,见 [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md)。 ### 选择驱动 在 **设置 → 存储配置** 中勾选 **启用上传**,选择 **平台原生绑定**,点击 **保存存储配置**。这种驱动不使用连接信息和密钥字段。 **读取方式** 显示 `application`。绑定无法预签名,因此签名链接指向你自己的站点,由应用返回文件内容。当前运行环境无法使用的选项会置灰,并在下方说明原因。 ## 设置限制和公开域名 ### 限制文件大小 在 **限制与 MIME 类型** 中设置 **最大文件字节数**,默认 `10485760`(10 MB)。 ### 限制文件类型 修改 **图片 MIME 类型**、**视频 MIME 类型**、**音频 MIME 类型** 和 **文件 MIME 类型**(用逗号分隔的内容类型)。默认值分别为 `image/png, image/jpeg, image/webp, image/gif`;`video/mp4, video/webm`;`audio/mpeg, audio/wav, audio/ogg`;`application/pdf, text/plain`。 ### 添加公开域名(可选) 如果已有 CDN 或自定义域名能访问桶内对象,在 **连接信息 → CDN 或公开访问域名** 中填写基础地址,例如 `https://assets.example.com`。之后每次上传都会用这个域名加对象路径记录一条公开链接。应用不会把存储桶设为公开,之前上传的文件保留原来记录的链接。 ### 保存 点击 **保存存储配置**。 取消勾选 **启用上传** 再保存,会关闭上传,但不会删除已保存的密钥。 ## 通过 API 上传 用户在 `/app/assets/upload` 上传文件。脚本使用会话 Cookie 或带 **上传文件** 的 API Key。接口接受 `multipart/form-data`(`file` 字段)或 JSON(`base64` 字段)。不传 `folderId` 时文件存入用户的 `/uploads` 目录。 ```bash curl -X POST https://your-domain.example/api/assets/upload \ -H "Authorization: Bearer $API_KEY" \ -F "file=@./report.pdf" \ -F "resourceType=file" # 201 => { "ok": true, "file": { "id": "file_...", "objectKey": "...", "publicUrl": null, ... } } ``` 每个用户有三个目录:`/`、`/uploads` 和存放 AI 产出的 `/generated`。上传到其他目录会被拒绝。签名下载链接最长 24 小时后过期。 **尚未配置存储时** 没有备用存储。上传会报 `S3-compatible storage credentials are not configured.`(`/api/assets/upload` 返回 HTTP 503),无法生成签名链接,`/setup` 中 **对象存储** 显示为未就绪。 ## 验证 ### 查看上传页面 以任意已登录用户打开 `/app/assets/upload`。驱动可用时标题旁的徽标显示 **R2 已就绪**(无论使用哪家供应商都显示这个文案),否则显示 **存储未配置**。 ### 上传文件 选择 **资源类型**,选一个符合该类型白名单的 **文件**,点击 **上传**。表单显示 **已上传** 加文件名,失败时显示供应商返回的错误。 ### 下载文件 在 `/app/assets` 中打开这个文件,点击 **生成签名 URL**。在新标签页打开按钮下方的 URL,文件可以正常加载。 ### 查看后台 **平台 → 资源**(`/admin/assets`)中可以看到该文件及其所有者,`/setup` 中 **对象存储** 显示为就绪。 `pnpm validate:files` 会检查两种驱动的接入。`pnpm validate:storage-drivers` 会在你的存储桶中真实写入、读取和删除对象。 ## 常见问题 ### 上传返回 "Content type ... is not allowed" 文件类型不在所传资源类型的列表中。在 **存储配置** 对应的 MIME 列表中添加该类型,或传入正确的资源类型。 ### 上传返回 "Folder does not exist" 目录 ID 不是调用者自己的目录。在 `/api/assets/upload` 中省略 `folderId`,文件会存入 `/uploads`。 ### S3 上传报 "Storage upload failed (403)" 错误中带有供应商自己的错误码和信息。检查 Access Key、Secret、存储桶名称,以及 **Region** 是否与端点的签名要求一致。 ### 绑定驱动的签名链接返回 503 指向你站点的链接只在选中绑定驱动且存在 `BUCKET` 绑定时返回文件。切换驱动前签发的链接无法使用,请重新生成。 ## 参考 * [部署到 Cloudflare](https://kernlift.dev/zh/docs/deploy/cloudflare.md) * [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) * [S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) ## 下一步 - [签发 API 密钥并设置限流](https://kernlift.dev/zh/docs/core/auth/api-keys.md) - [接收异步结果](https://kernlift.dev/zh/docs/extensions/ai/async.md) - [部署到 Cloudflare Workers](https://kernlift.dev/zh/docs/deploy/cloudflare.md) --- # MinIO > 将上传文件保存到 MinIO。 Source: https://kernlift.dev/zh/docs/extensions/storage/minio ## 准备工作 准备可操作该服务的账号,以及有权保存下列表单的 Kernlift 管理员账号。 **完成后**,能上传并下载同一个文件。 ## 在 MinIO 完成准备 ### 创建存储桶 打开 [MinIO](https://min.io/docs/minio/linux/administration/identity-access-management/minio-user-management.html)。在自己的 MinIO Console 创建存储桶。 ### 创建应用密钥 在 Access Keys 创建可读写该桶对象的应用密钥。 ### 记录 S3 端点 记下应用可达的 S3 API 端点和签名区域。 官方说明 · [MinIO 对象存储文档](https://min.io/docs/minio/linux/administration/identity-access-management/minio-user-management.html) ## 填写项目配置 回到 Kernlift 后台,打开 `/admin/config/storage`。 | 来源 | 后台字段 | | -------------- | ----------------- | | Bucket | Bucket 名称 | | API address | S3 endpoint | | Signing region | Region | | Access Key | Access Key ID | | Secret Key | Secret Access Key | 开启上传,选择 S3 兼容端点。端点填写服务端能够访问的 S3 API 地址。保存存储配置。 <img src="/docs/guides/storage/connection.zh.png" alt="Kernlift 后台的 MinIO 配置字段" width="512" height="1052" loading="lazy" /> ## 验证 1. 打开 `/app/assets/upload` 上传一个符合限制的小文件。 2. 从 `/app/assets` 下载该文件并核对内容。 ## 常见问题 ### S3 上传报 "Storage upload failed (403)" 错误中带有供应商自己的错误码和信息。检查 Access Key、Secret、存储桶名称,以及 **Region** 是否与端点的签名要求一致。 ## 下一步 [配置文件存储和上传](https://kernlift.dev/zh/docs/extensions/storage.md) --- # 工单 > 接收已登录客户提交的工单,按 SLA 分派处理,并在后台回复。 Source: https://kernlift.dev/zh/docs/extensions/support 客户在 `/app/tickets` 提交工单。工单出现在 `/admin/support`,带状态、优先级和 SLA 标记,每条回复都写入同一个会话。不需要第三方客服系统,会话、工单和消息都保存在你自己的数据库中。 ## 准备工作 * 一个能进后台的账号:读工单需要 `support.read`,回复或改派需要 `support.write`。见[角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * 邮件是可选的。没有邮件服务商时工单同样可用。要让客户在站外收到通知,见[发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md)。 ## 设置 ### 给运营人员授权 打开 `/admin/roles`,选中客服使用的角色,加上 `support.read` 和 `support.write`。只有 `support.read` 的角色能看队列和会话,但不能回复和改派,适合分析岗位。 ### 以客户身份提交一条 用普通账号登录,打开 `/app/tickets` 提交。服务端从会话读取提交者邮箱,不从表单读取,所以客户无法用别人的邮箱提交工单。 新工单的初始状态是 `triage`,优先级 `normal`,SLA `within_sla`,负责人 `support`。 ### 处理队列 `/admin/support` 列出每条工单的提交者、优先级、SLA 状态和负责人。点开一条可以读会话、回复,并同时设置状态、优先级、负责人和 SLA 状态。 运营回复后工单变为 `waiting`,客户回复后工单变回 `triage`。关闭工单同时把会话标记为 `resolved`,`/app/tickets/closed` 列出这个状态的会话。 ## 客户数据隔离 服务端从会话读取提交者身份,不从表单读取。每次回复前,服务端同时用工单 ID 和提交者邮箱重新读取工单,所以不会返回其他客户的工单。状态变化见上面的处理步骤。 会话、工单和工单消息在同一事务中写入。后台操作也会写入审计记录,见[审计日志](https://kernlift.dev/zh/docs/core/admin/audit-log.md)。 ## 验证 1. 在 `/app/tickets` 提交一条工单,它以 `triage` 状态出现在 `/admin/support`。 2. 以运营身份回复。客户侧能看到回复,工单变为 `waiting`。 3. 换一个客户账号,直接访问前一个客户的工单 id。页面不显示会话。 4. 关闭工单。客户可以在 `/app/tickets/closed` 看到它。 ## 参考 * [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) * [Better Auth 会话](https://better-auth.com/docs/concepts/session-management):提交者身份的来源 ## 下一步 - [角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md) 给客服一个只能读和回工单的角色。 - [审计日志](https://kernlift.dev/zh/docs/core/admin/audit-log.md) 运营的每次改派和回复都有记录。 - [通知](https://kernlift.dev/zh/docs/extensions/notifications.md) 工单状态变化时,通过站内或邮件通知客户。 - [发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) 接入服务商,发送工单邮件。 --- # 系统架构 > 代码如何分层、业务代码为什么从不接触 SQL 方言,以及让模板便于 fork 的约定。 Source: https://kernlift.dev/zh/docs/guide/architecture Kernlift 是供他人 fork 的模板,所以它的结构要在功能不断增加时仍保持可预期。服务端代码分层组织,运行时能力在应用运行时检测,另有几条约定适用于整个仓库。目录地图见[项目结构](https://kernlift.dev/zh/docs/core/project-structure.md)。 ## 分层 ```text 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 变更需要在每种方言下各有一条匹配的迁移。连接与适配器如何选择,见[运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 运行时能力是事实,不是偏好 `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。数据保留。见[插件](https://kernlift.dev/zh/docs/core/plugins.md)。 ## 后台任务在 Web 应用内运行 周期性工作统一放在 `src/server/jobs/scheduled.ts` 的 `runScheduledJobs()` 中:积分过期、支付履约重试、未完成的 AI 任务。每分钟执行一轮,由平台提供的机制触发:Node 服务器上是进程内循环,Cloudflare 上是 Worker 的 Cron Trigger,也可以由外部 cron 调用 `pnpm jobs:run`。配置表里的一行锁保证多副本时也只执行一轮,每一轮都会写入心跳记录,供 `/setup` 读取。见[后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md)。 ## 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 运行时](https://kernlift.dev/zh/docs/extensions/agent.md)。 ## 每个部署目标一份构建 `deploy.config.json` 记录部署平台(`cloudflare`、`fly`、`railway` 或 `docker`)、数据库以及是否部署 agent。它在构建时被打包进产物,同时决定使用哪种构建:以 `src/server-entry.ts` 为入口的 Worker 构建,或以 `src/server-entry.node.ts` 为入口的 Node 构建。`kernlift deploy-target` 负责重写它。见[运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 多语言 路由在 `src/routes/{-$locale}/` 下按语言组织:同一个页面在 `/…` 提供英文,在 `/zh/…` 提供中文。文案保存在 `src/i18n/locales/{en,zh}/messages.ts` 中,两边的键完全一致,组件从这些字典中读取文案。只属于某一块后台区域的文案可以放在 `src/i18n/` 下单独的文件里,同样带有键一致的 `en` 和 `zh`。见[新增与修改文案](https://kernlift.dev/zh/docs/customize/i18n.md)。 ## 贯穿全局的约定 | 约定 | 含义 | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 规格驱动的变更 | 每个非小改动都先在 `openspec/changes/` 中建立 OpenSpec 变更,包含提案、设计、规格和任务,完成后归档 | | 配置在数据库中 | 服务商凭据与业务设置在 `/admin/config/*` 中;环境变量只负责启动与基础设施。见[配置模型](https://kernlift.dev/zh/docs/core/configuration.md) | | 不使用 mock 服务商 | 集成调用真实的测试或沙箱环境。缺少凭据时显示未配置状态,绝不伪造成功 | | 唯一的身份边界 | 只有 `src/server/auth/` 读取会话。见[认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md) | | 每项能力一个校验器 | `scripts/validate/*.ts` 断言行为与接线。见[校验器与发布门禁](https://kernlift.dev/zh/docs/core/validators.md) | | 全站一套设计系统 | 后台、工作台、登录与系统页以及公开站都用 beUI(`packages/beui`、`src/components/motion`)配合 Tailwind 工具类。令牌挂在 `:root` 上,页面不需要声明就在设计系统里,也没有自己的类名前缀。`src/styles/app.css` 中历史遗留的 `!important` 债务不能被新文件效仿。见[使用设计系统](https://kernlift.dev/zh/docs/customize/design-system.md) | | 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` 证明这些切片能逐字节还原为原仓库,并且底座在没有任何模块时仍能编译。见[底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md)。 ## 相关文件 - 分层/ - 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 ## 下一步 - [项目结构](https://kernlift.dev/zh/docs/core/project-structure.md) - [运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [插件](https://kernlift.dev/zh/docs/core/plugins.md) - [后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md) - [底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md) --- # 常见问题 > 激活、邀请过期、退款、fork、同步上游更新、同步后更新数据库、项目数量与技术支持。 Source: https://kernlift.dev/zh/docs/guide/faq 买家问得最多的问题,这里给出简短的回答。没有找到你的问题,见[如何获得技术支持](#如何获得技术支持)。 ## 购买 Kernlift Premium 会员能得到什么? 商业完整版包含底座、Image Studio 和 Video Studio 三个仓库,两款 Agent 可按会员价另购。[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md) ## CMS、邮件订阅、联盟推广要单独购买吗? CMS、邮件订阅和联盟推广已包含在完整版底座中。完整版另附两款 Studio,两款 Agent 成品可按会员价单独购买。 ## 买业务模板必须先买会员吗? 两款 Studio 随商业完整版赠送。两款 Agent 可按会员价购买。未购买完整版的买家可原价单买。 ## 模板如何激活? 打开工作台的**已购模板**(`/zh/app/licences`),在对应的购买项旁填写 **GitHub 用户名**,点击**激活**。售卖站会把这个账号邀请为该商品私有仓库的只读协作者。 > 填的是用户名,不是邮箱。激活前先打开 `https://github.com/<用户名>`,确认是你自己的主页。 然后在 GitHub 通知里或 GitHub 发来的邮件里接受邀请。 ## 邀请过期了怎么办? GitHub 的邀请 7 天后过期。回到**已购模板**,在这项购买上点击**重新发送邀请**。用户名不变,只是把邀请重发一次。 ## 激活后可以更换 GitHub 用户名吗? 不可以。一项购买只为一个 GitHub 账号激活,不能转到另一个账号。点击**激活**之前请核对用户名。 ## 可以退款吗? 只有激活之前可以。订单里的购买项都还没有激活时,订单可以退款。激活即视为已交付,因为从那一刻起仓库就可以被克隆,所以订单里只要有一项已激活,就不能退款。 申请退款时,在**工单**(`/zh/app/tickets`)里提交一条,附上**账单**(`/zh/app/billing`)里的订单号。 ## 代码仓库可以 fork 吗? 不可以。仓库是私有的,不允许 fork。把仓库克隆下来,推送到你自己的私有仓库: ```bash git clone git@github.com:kernlift/kernlift.git my-app cd my-app git remote set-url origin git@github.com:YOUR-ACCOUNT/my-app.git git push origin main ``` 推送之前,先在 GitHub 上创建空的私有仓库 `<you>/my-app`。仓库要保持私有:代码授权给你使用,不是公开发布。 ## 如何同步上游更新? 把模板仓库添加为第二个远程,命名为 `upstream`,然后从它合并。 1. 添加远程,只需做一次: ```bash git remote add upstream git@github.com:kernlift/kernlift.git ``` 业务模板则换成该模板自己的仓库(`kernlift/<template-key>`)。 2. 在干净的工作区里拉取并合并: ```bash git fetch upstream git merge upstream/main ``` 3. 解决冲突,然后安装依赖并执行迁移: ```bash pnpm install pnpm db:migrate ``` 4. 推送到你自己的仓库: ```bash git push origin main ``` > 如果距离上次同步已经改动很多,不要一次全部合并。先看更新日志,用 `git cherry-pick <commit>` 只取你需要的改动。 完整流程见[同步上游更新](https://kernlift.dev/zh/docs/guide/upgrading.md),其中说明了哪些目录是留给你改的,这样合并时冲突最少。 ## 同步后如何更新数据库? 执行迁移即可。迁移文件随仓库一起提供,不需要自己生成: ```bash pnpm db:migrate ``` 使用 Cloudflare D1 时,用 `pnpm db:migrate:d1:remote` 把迁移应用到线上数据库。 如果之后某个新的后台页面提示「Permission denied」,说明这次更新新增了权限。按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)里同样的 `SUPER_ADMIN_EMAIL` 和 `SUPER_ADMIN_PASSWORD` 再运行一次 `pnpm db:bootstrap-super-admin`,超级管理员角色就会获得这些权限。 ## 可以用来做多少个项目? 不限。会员不按项目或域名计数,应用运行时也不校验授权。 ## 团队成员怎么获得代码? 一项购买只为一个 GitHub 账号激活。按[代码仓库可以 fork 吗?](#代码仓库可以-fork-吗)里的做法把代码推送到你自己的私有仓库,在那里给团队成员开权限。 ## 激活之后如何开始? 1. 对照[前置要求](https://kernlift.dev/zh/docs/guide/prerequisites.md)准备环境。 2. 按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)操作。 ## 如何获得技术支持? * 在工作台的**工单**(`/zh/app/tickets`)里提交。与购买有关的问题请附上订单号。 * 无法登录时,使用联系页面 `/zh/contact`。 安装或运行项目时遇到报错,先看[排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md),里面按现象列出了常见原因和修复办法。 ## 下一步 - [获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md) 购买、激活并打开仓库。 - [系统架构](https://kernlift.dev/zh/docs/guide/architecture.md) 应用分哪几层,一个请求如何穿过它们。 --- # 获取 Kernlift > 购买 Kernlift Premium 会员,用 GitHub 用户名激活,打开私有仓库;以及会员和非会员如何购买业务模板。 Source: https://kernlift.dev/zh/docs/guide/get-kernlift Kernlift 以 GitHub 私有仓库的形式交付。你付一次款,把 GitHub 用户名告诉售卖站,售卖站把这个账号邀请进仓库。本页分三种情况说明:新用户、会员购买业务模板、不买会员直接买模板。 ## 新用户 ### 购买 Kernlift Premium 会员 登录后打开定价页 `/zh/pricing`,购买 **Kernlift Premium 会员**。一次付费,含底座和两个 Studio 仓库。 ### 打开「已购模板」 付款确认后,进入工作台的**已购模板**(`/zh/app/licences`)。会员会出现在列表里,状态是**未激活**。 ### 用 GitHub 用户名激活 填写 **GitHub 用户名**,点击**激活**。填的是用户名,不是邮箱;不确定的话,打开 `https://github.com/<用户名>`,确认是你自己的主页。 售卖站会把这个账号邀请为私有仓库的只读协作者。 **两件事不可撤回** 用户名激活后不能更改。激活即视为已交付:订单里只要有一项已激活,这笔订单就不能再退款。 ### 接受邀请 打开 [GitHub 通知](https://github.com/notifications)或查看 GitHub 邀请邮件,点接受即可。邀请 7 天内未接受会过期;过期后回到同一页面,点击**重新发送邀请**。 ### 打开仓库 「已购模板」页面此时会显示仓库地址和克隆命令。点**在 GitHub 打开**可以直接进入仓库。 ```bash git clone git@github.com:kernlift/kernlift.git my-app ``` ### 开始使用 按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)安装并以管理员身份登录。 ## 会员购买业务模板 商业完整版包含底座、Image Studio 和 Video Studio 三个仓库。Image Agent 和 Video Agent 可另购,会员享优惠价。 打开「已购模板」即可分别激活两个 Studio。以下购买步骤适用于 Agent 模板。 1. 用持有 Kernlift Premium 会员的账号登录。会员价只有这个账号才能下单。 2. 按会员价购买模板。 3. 打开**已购模板**(`/zh/app/licences`)。模板会单独列出,状态是**未激活**。 4. 用 GitHub 用户名激活,做法同上。每项购买单独激活,各自邀请你进入各自的仓库: ```bash git clone git@github.com:kernlift/<template-key>.git my-app ``` 每个模板的准确地址以「已购模板」页面显示的为准。 5. 按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)操作。业务模板是包含底座全部能力的完整项目,步骤完全一样。 ## 不买会员,直接买模板 购买业务模板不要求先买 Kernlift Premium 会员。 * 非会员按模板的原价购买。会员价只有持有会员的账号才能下单。 * 激活和交付方式相同:**已购模板**、GitHub 用户名、**激活**。 * 这样买到的是这个模板的仓库,不单独包含底座仓库,买其他模板也不享会员价。 如果打算买不止一个模板,付款前先比较一下「各模板原价之和」与「会员加会员价」。之后再买会员,不会改变已付订单的价格。 ## 订单找不到怎么办 付了款却没出现在**已购模板**里,绝大多数情况是订单在另一个账号下。 1. 确认登录的邮箱就是付款时用的邮箱。用 Google 登录创建的账号,和用另一个邮箱加密码注册的账号,是两个账号。 2. 打开工作台的**账单**(`/zh/app/billing`)查看订单。显示待支付的订单说明支付渠道还没有确认到账,等几分钟再刷新。 3. 订单已支付但「已购模板」里没有,就在**工单**(`/zh/app/tickets`)里提交一条,写明付款邮箱、订单号和你的 GitHub 用户名。 不要重复付款。已持有某个商品的账号不能再次购买它,结账时会在扣款前提示。 ## 下一步 - [快速开始](https://kernlift.dev/zh/docs/quick-start.md) 克隆、安装、迁移数据库,并以管理员身份登录。 - [常见问题](https://kernlift.dev/zh/docs/guide/faq.md) 邀请过期、退款、fork 与同步更新。 - [前置要求](https://kernlift.dev/zh/docs/guide/prerequisites.md) 克隆之前要准备好的工具和账号。 --- # 前置要求 > 克隆 Kernlift 之前要准备好的工具、账号和基础知识。 Source: https://kernlift.dev/zh/docs/guide/prerequisites 开始[快速开始](https://kernlift.dev/zh/docs/quick-start.md)之前,先把下面这些准备好。这里的东西都不花钱;需要付费的服务要到接入服务商时才用得上。 ## 本机工具 | 工具 | 版本 | 用途 | | ------- | --------------------------------------- | ------------------- | | Node.js | 22.x 系列的 22.12 或以上版本 | 运行开发服务器、构建和各种脚本 | | pnpm | `package.json` 中 `packageManager` 指定的版本 | 安装依赖,运行所有 `pnpm` 脚本 | | git | 任意较新版本 | 克隆仓库、同步更新 | 检查一下: ```bash node --version pnpm --version git --version ``` 没有 `pnpm` 的话,用 `npm install -g pnpm@10.25.0` 安装。 ## GitHub 账号 代码通过 GitHub 交付,所以你需要一个 GitHub 账号,而且必须是激活购买时填写的那个。见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。 文档里的克隆命令用的是 SSH(`git@github.com:...`)。请先在 [GitHub 的 SSH keys 页面](https://github.com/settings/keys)添加 SSH 公钥,或者改用仓库页面上显示的 HTTPS 地址克隆。 ## 现在还不需要的 * **数据库服务。** 本地开发用的是一个 SQLite 文件,执行迁移时自动创建。 * **云平台账号。** Cloudflare、Fly.io、Railway 或 Docker 主机到[部署](https://kernlift.dev/zh/docs/deploy.md)时才需要。 * **服务商账号。** 支付、邮件、存储和 AI 都是项目跑起来之后在管理后台里接入的。在那之前它们各自显示「未配置」。 ## 如果要用 Agent 工作台 Agent 是可选的,没有它 Web 应用也是完整的。如果你打算运行它,或者买的是 `image-agent`、`video-agent`,还需要 Postgres 和一个沙箱服务。见[运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)。 ## 需要了解的知识 你会阅读并修改 TypeScript 和 React 代码。最好具备: * TypeScript 和 React,能看懂一个组件和一个服务端函数。 * TanStack Start 与 TanStack Router 的基础:文件路由、loader 和服务端函数。 * SQL 基础。表结构和查询用 Drizzle 编写。 * Tailwind CSS,用于样式。 如果你用编码 Agent 干活,仓库自带一组技能,能带着它完成常见任务。见[使用编码 Agent 技能](https://kernlift.dev/zh/docs/core/agent-skills.md)。 ## 下一步 - [快速开始](https://kernlift.dev/zh/docs/quick-start.md) 克隆、安装,并在本地运行项目。 - [项目结构](https://kernlift.dev/zh/docs/core/project-structure.md) 代码仓库里各部分放在哪里。 --- # 排查项目问题 > 根据现象找到原因和修复方法:初始化清单缺项、会话密钥、生成的类型、迁移、开发环境免登录、agent、定时任务和仓库访问。 Source: https://kernlift.dev/zh/docs/guide/troubleshooting 新项目里的大多数问题来自缺少某项配置,应用会报告该项未配置。先做下面三项检查,可以定位大部分原因。然后在后面的小节里找到你遇到的现象。 ## 准备工作 * 项目目录下的终端,以及应用运行环境的访问权限(本地是 `.env`,生产环境是平台上的变量)。 * 一个管理员账号,用于需要打开 `/setup` 的检查。见[运行管理后台](https://kernlift.dev/zh/docs/core/admin.md)。 * 准确的报错文字,或你最后停在的页面。下面有几项修复要根据它来判断。 ## 定位原因 1. 以管理员身份打开 `/setup`。页面每次加载都读取实时配置,逐项显示**已就绪**或**未就绪**并给出原因。第一行说明当前的部署平台、数据库,以及构建是否包含 agent 服务。 2. 在运行 `pnpm dev` 的终端或平台的日志中查看服务端输出。启动失败的原因和开发环境免登录的警告都打印在这里。 3. 运行门禁。门禁运行所有预期通过的校验器,并把结果与 `scripts/validate/known-failures.json` 对比: ```bash pnpm validate:gate ``` ## 某项功能提示未配置 服务商从不使用 mock。没有凭据时,功能会报告未配置。 | 现象 | 原因 | 修复 | | ------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------- | | `/setup` 中**邮件投递**未就绪;验证邮件和重置邮件一直收不到 | 没有启用的邮件服务商 | **设置 → 邮件配置**(`/admin/config/email`)。见[发送事务邮件](https://kernlift.dev/zh/docs/extensions/email.md) | | 点击 `/pricing` 上的套餐按钮后落在 `/system/payment-failed`,带有 `reason=checkout_not_configured` | 没有配置支付服务商 | `/admin/config/payment`。见[接入支付服务商](https://kernlift.dev/zh/docs/extensions/payments/setup.md) | | `/pricing` 提示套餐尚未发布 | 该语言下没有状态为 `active` 的套餐 | `/admin/plans`。见[定价套餐](https://kernlift.dev/zh/docs/extensions/payments/pricing-plans.md) | | 上传失败;`/setup` 中**对象存储**未就绪 | 没有存储驱动 | `/admin/config/storage`。见[存储文件](https://kernlift.dev/zh/docs/extensions/storage.md) | | AI 任务无法发起;`/setup` 中 **AI 渠道**未就绪 | 没有启用的渠道,或有渠道但没有场景路由到它们 | `/admin/config/ai`。见 [AI 服务商](https://kernlift.dev/zh/docs/extensions/ai/providers.md)和[场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md) | 设置页保存成功只说明值已经保存,不代表服务商接受这些值。先用该页面自带的测试操作验证,再回到 `/setup`。 ## `/setup` 打不开或显示缺项 * **跳转到 `/system/session-expired`**:你还没有登录。在 `/auth/sign-in` 登录。 * **页面能打开但清单加载不出来**:读取清单需要 `config.read`。用 `pnpm db:bootstrap-super-admin` 创建的账号登录,或授予该权限,见[管理用户、角色与权限](https://kernlift.dev/zh/docs/core/auth/roles.md)。 * **必需项未就绪**:必需项有四个:**会话密钥**、**登录方式**、**邮件投递**和**定时任务**。除会话密钥和定时任务外,每一项都有**去配置**按钮,点击后打开对应的配置页面。 * **某一项显示的是报错信息而不是原因**:对应的子系统读取失败,通常是因为表不存在。见[迁移没有执行](#迁移没有执行)。 ## 会话密钥缺失或被拒绝 `BETTER_AUTH_SECRET` 用于签名会话。缺少它时的行为取决于 `APP_ENV`: | `APP_ENV` | 行为 | | ------------------- | -------------------------------------------------------------------------------------------------- | | `development`(或未设置) | 应用使用模板内置的密钥启动。`/setup` 中**会话密钥**未就绪:「BETTER\_AUTH\_SECRET is unset or still the template default.」 | | 其他任何值 | 应用拒绝启动:`Refusing to start with the built-in session secret while APP_ENV is "production".` | 生成一个值,写入 `.env` 或平台的密钥存储,然后重启: ```bash node -e "console.log(crypto.randomUUID()+crypto.randomUUID())" ``` 生产环境要用另一个密钥:`kernlift deploy-target` 会在 `.env.production` 中生成一个。 ## `pnpm typecheck` 因 Worker 类型失败 出现与 `CloudflareEnv` 或其他 Workers 类型有关的错误,说明 `worker-configuration.d.ts` 不存在。这个文件由命令生成,不提交到仓库: ```bash pnpm cf-typegen ``` 克隆仓库后,以及修改 `wrangler.jsonc` 中的绑定后都要运行这条命令。部署到 Fly.io、Railway 或 Docker 的项目没有 `wrangler.jsonc`。这时同一条命令根据一份参考配置生成类型,因为源码仍然引用这些类型。 如果错误提到你刚新增的路由,说明 `src/routeTree.gen.ts` 过期了。启动一次 `pnpm dev` 或运行 `pnpm build` 重新生成。 ## 迁移没有执行 刚克隆、升级或安装模块之后,加载数据的页面报数据库错误,提示缺少某张表或某个列。 | 数据库 | 命令 | | -------------------------------------- | --------------------------- | | 由 `DATABASE_URL` 指定的 SQLite 或 Postgres | `pnpm db:migrate` | | Cloudflare D1(本地) | `pnpm db:migrate:d1:local` | | Cloudflare D1(已部署) | `pnpm db:migrate:d1:remote` | `pnpm db:migrate` 从环境中读取 `DATABASE_DIALECT` 和 `DATABASE_URL`,先确认它们指向应用实际使用的数据库。失败时命令会打印方言、数据库,以及迁移文件数和已应用记录数。如果还附带一句 "The schema exists but no migration has been recorded",说明这个库不是通过迁移创建的。请换一个空库重新迁移,不要在现有库上继续迁移。 合并上游更新之后,运行 `pnpm install && pnpm db:migrate`,再运行 `pnpm db:bootstrap-super-admin`,让 Super Admin 角色获得这次更新新增的权限。 ## 开发环境免登录不生效 只有同时满足以下两个条件,未登录的请求才会被当作指定用户: 1. `APP_ENV=development`。 2. `AUTH_DEV_IMPERSONATE_USER_ID` 设为非空的用户 id。 生效时服务端会打印一次:`[auth] AUTH_DEV_IMPERSONATE_USER_ID is set. Unauthenticated requests are being treated as "<id>".` 如果没有看到这一行,说明两个条件之一不成立,或者修改 `.env` 后没有重启服务。这个值必须是已存在用户的 id,并且该用户需要有 `admin.access` 才能打开 `/admin`。 非开发环境下这个变量会被忽略。除此之外没有任何身份兜底。未登录的调用者会被拒绝,不会映射成默认用户。见[认证与授权模型](https://kernlift.dev/zh/docs/core/auth.md)。 ## agent 提示未部署 agent 是可选的。没有 agent 时,`/app/ai` 和 `/app/chat` 仍然可用,侧边栏隐藏 agent 入口,agent 页面显示 **未部署 agent 服务**,`/api/agent/*` 返回 503 和 `agent_unavailable`。页面会说明是以下四种原因中的哪一种: | 原因 | 修复 | | ------------------------------------ | ----------------------------------------------------- | | agent 插件被停用 | 在 `/admin/plugins` 中启用 | | 数据库不支持事务 | agent 运行不能使用 D1,改用 Postgres 或 SQLite 部署 | | 没有配置 agent 服务 | 设置 `AGENT_SERVICE_URL`(或 Cloudflare 容器绑定)并部署 agent 服务 | | 没有设置 `AGENT_INTERNAL_SIGNING_SECRET` | 为 Web 应用和 agent 服务设置相同的值 | 本地 `pnpm dev` 只启动 Web 应用。`pnpm dev:agent` 同时启动 agent 服务。见 [Agent 模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)。 ## `/setup` 对定时任务告警 后台工作(积分过期、支付履约重试、AI 任务轮询)每分钟执行一轮,并记录每一轮的结果。以下情况**定时任务**会变为未就绪:从未记录过任何一轮、最近一轮距今超过五分钟,或最近一轮有任务失败(提示里会写出失败任务的名称)。 | 平台 | 每一轮如何触发 | 检查什么 | | ---------- | --------------------- | ----------------------------------------------------------------------------------- | | Cloudflare | Worker 的 Cron Trigger | `wrangler.jsonc` 保留了 `"triggers": { "crons": ["* * * * *"] }`,并且已部署的 Worker 列出了该触发器 | | Fly.io | 在 Web 进程内 | `fly.toml` 中 `min_machines_running = 1`;停止的机器不执行任何任务 | | Railway | 在 Web 服务内 | 服务处于运行状态 | | Docker | 在 Web 容器内 | `docker compose ps` 显示容器已启动 | 在 Node 平台上,`JOBS_IN_PROCESS=false` 会关闭进程内循环,这时必须由外部 cron 调用 `pnpm jobs:run`。手动运行这条命令可以看到一轮的 JSON 报告。新部署会在一分钟内记录第一轮,所以先等一分钟,再排查这条告警。见[后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md)。 ## git 无法访问仓库 | 提示 | 原因 | 修复 | | --------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------- | | `git clone` 或 `git fetch upstream` 提示 `Repository not found` | 对于账号没有读取权限的私有仓库,GitHub 就是这样回答的:邀请还没有接受,或者 git 登录的是另一个账号 | 到 GitHub 通知里接受邀请,并确认 SSH 密钥或凭据属于哪个账号 | | `Permission denied (publickey)` | 这台机器上没有任何 SSH 密钥登记在你的 GitHub 账号下 | 把公钥添加到 GitHub,或改用仓库页面上的 HTTPS 地址克隆 | | 邀请链接提示已过期 | GitHub 的邀请 7 天后过期 | 打开**已购模板**(`/zh/app/licences`),点击**重新发送邀请** | | `git merge upstream/main` 提示 `fatal: refusing to merge unrelated histories` | `upstream` 指向的模板不是项目当初克隆的那个 | 把 `upstream` 指回你克隆的仓库:`git remote set-url upstream <地址>` | 购买、激活和退款见[常见问题](https://kernlift.dev/zh/docs/guide/faq.md)。 ## 验证 修复之后,运行检查并重做之前失败的操作来确认结果。只看设置页保存成功是不够的: ```bash pnpm typecheck pnpm validate:gate ``` * `/setup` 显示**必需项已齐备**。 * 之前失败的操作现在能在真实服务商上完成:验证邮件能收到,沙箱结账能到达服务商页面,上传的文件能再次下载。 * 部署之前,`pnpm smoke:node`(先运行 `pnpm build:node`)或 `pnpm smoke:worker`(先运行 `pnpm build`)会在一次性数据库上运行构建产物,检查页面、agent 的 503 响应和一轮定时任务。 ## 下一步 - [配置一个可用的项目](https://kernlift.dev/zh/docs/core/configuration/project.md) 按什么顺序接入服务商。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) 源码读取的全部变量。 - [校验器与发布门禁](https://kernlift.dev/zh/docs/core/validators.md) 门禁检查什么。 - [后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md) 每一轮定时任务做什么。 --- # 同步上游更新 > 从 upstream 远程把模板的新版本合并进你的项目,并用项目自带的检查验收。 Source: https://kernlift.dev/zh/docs/guide/upgrading 你的项目是从模板仓库克隆出来的,而模板仓库会持续更新。更新的方式是从 `upstream` 远程合并。把你的改动放在留给你改的目录里,合并时的冲突就少。 ## 准备工作 * 干净的工作区:改动已提交或已暂存。 * 对 GitHub 上模板仓库的只读权限。见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。 * 项目已推送到你自己的私有仓库,作为 `origin`。见[代码仓库可以 fork 吗?](https://kernlift.dev/zh/docs/guide/faq.md) * 目标版本的 `CHANGELOG.md`。破坏性变更标有 `Breaking`,并附带迁移说明。 ## 把改动放在你的区域 | 区域 | 路径 | | ------ | --------------------------------------------------------------------------------------------------------------------- | | 属于你的区域 | `src/config/site.ts`、`src/components/marketing/example-landing.tsx`、`src/i18n/locales`、`public` | | 模板骨架 | `src/server`、`src/components/ui`、`scripts`、`drizzle/migrations`、`src/router.tsx`、`src/start.ts`、`src/server-entry.ts` | 骨架从不引用你的区域,唯一的例外是 `src/config/site.ts`。`pnpm validate:template-boundary` 检查这条规则。 ## 合并一次更新 ### 添加一次上游远程 ```bash git remote add upstream git@github.com:kernlift/kernlift.git git fetch upstream ``` 业务模板则换成该模板自己的仓库(`kernlift/<template-key>`)。 ### 在分支上合并更新 ```bash git fetch upstream git checkout -b upgrade/upstream-update main git merge upstream/main ``` 用合并,不要变基,这样不会改写你项目的提交历史。如果距离上次同步已经改动很多,用 `git cherry-pick <commit>` 只取需要的改动,不要一次全部合并。 ### 解决冲突 * **你的区域**:保留你的,再看上游是否新增了你也需要的键。这种情况最常出现在字典文件中。 * **骨架**:取上游,再重新应用你的改动。如果同一文件反复出现这种情况,把改动移到骨架调用的模块里。 * **`drizzle/migrations`**:不要修改已有迁移。原样取上游的迁移链,在其上加你自己的迁移。 * **`package.json`**:两边的依赖都保留,然后 `pnpm install`。 * **部署文件**(`deploy.config.json` 以及 `wrangler.jsonc`、`fly.toml`、`.railway/railway.ts` 或 `compose.yaml`):保留你的。这些文件记录了你的平台和资源 id。如果上游改了你所用平台的文件,手动合入上游的改动,然后运行 `pnpm cf-typegen`。 ### 验收更新 ```bash pnpm install pnpm cf-typegen pnpm db:migrate pnpm typecheck pnpm build pnpm validate:all ``` ### 推送到你的仓库 ```bash git checkout main git merge upgrade/upstream-update git push origin main ``` ## 验证 * 打开 `/setup`,确认没有必需项变成 **未就绪**。 * `pnpm validate:all` 没有新增失败。对照你合并的上游提交上的 `scripts/validate/known-failures.json`。 * 运行 `git describe --tags $(git merge-base HEAD upstream/main)` 查看当前所在版本。版本标签与变更日志条目一一对应。 ## 常见问题 ### 新的后台页面提示 "Permission denied" 这次更新新增了权限。按[快速开始](https://kernlift.dev/zh/docs/quick-start.md)里同样的 `SUPER_ADMIN_EMAIL` 和 `SUPER_ADMIN_PASSWORD` 再运行一次 `pnpm db:bootstrap-super-admin`,让 Super Admin 角色获得这些权限。 ### 合并后 `pnpm db:migrate` 失败 某个已有迁移被修改,或两条迁移链出现分叉。把上游的迁移文件原样恢复,在其上添加你的迁移,然后运行 `pnpm validate:migrations`。 ### 同一个骨架文件每次合并都冲突 你把改动留在了上游也会修改的文件里。把改动移到你的区域,或移到骨架调用的插件里,下次合并就不会再碰到它。见[插件](https://kernlift.dev/zh/docs/core/plugins.md)。 ### `git fetch upstream` 提示 "Repository not found" git 客户端使用的 GitHub 账号不是激活购买时填写的那个,或者邀请一直没有接受。到**已购模板**(`/zh/app/licences`)查看;见[邀请过期了怎么办?](https://kernlift.dev/zh/docs/guide/faq.md) ## 参考 * [常见问题](https://kernlift.dev/zh/docs/guide/faq.md) * [校验器](https://kernlift.dev/zh/docs/reference/validators.md) * [Git merge strategies](https://git-scm.com/docs/merge-strategies) ## 下一步 - [常见问题](https://kernlift.dev/zh/docs/guide/faq.md) - [排查项目问题](https://kernlift.dev/zh/docs/guide/troubleshooting.md) - [校验器与发布门禁](https://kernlift.dev/zh/docs/core/validators.md) - [项目结构](https://kernlift.dev/zh/docs/core/project-structure.md) --- # 介绍 > Kernlift 是什么,底座仓库里有什么,业务模板多了什么,以及从哪里开始。 Source: https://kernlift.dev/zh/docs ## Kernlift 是什么? Kernlift 是一套基于 TanStack Start 的 SaaS 启动模板。一次购买后,你会获得一个 GitHub 私有仓库的访问权限,把代码克隆下来,在自己的仓库里做自己的产品。运行时不校验授权,也不需要从某个包源安装任何东西:克隆下来的代码就是完整的应用。 同一套代码可以跑在 Cloudflare Workers 或 Node 上,数据库可以用 SQLite、Cloudflare D1 或 Postgres。服务商凭据和业务设置保存在管理后台里,不写进环境变量。没有填凭据的集成会显示「未配置」,不会用假数据顶替。 ## 底座仓库里有什么 底座仓库随 Kernlift Premium 会员附带。它是一个完整的 Web 应用,组织方式与这份文档相同。 **核心** * [配置](https://kernlift.dev/zh/docs/core/configuration.md)放在管理后台,环境变量只管启动和基础设施。 * [登录、角色与权限](https://kernlift.dev/zh/docs/core/auth.md)、[用户](https://kernlift.dev/zh/docs/core/auth/users.md)和 [API 密钥](https://kernlift.dev/zh/docs/core/auth/api-keys.md)。 * [管理后台](https://kernlift.dev/zh/docs/core/admin.md),带审计日志、限流和就绪检查清单。 * [数据访问层](https://kernlift.dev/zh/docs/core/data-access.md),业务代码不依赖具体的 SQL 方言。 * [插件内核](https://kernlift.dev/zh/docs/core/plugins.md),不改外壳就能加页面和服务端行为。 * [后台任务](https://kernlift.dev/zh/docs/core/background-jobs.md)、[校验器](https://kernlift.dev/zh/docs/core/validators.md)和[给编码 Agent 用的技能](https://kernlift.dev/zh/docs/core/agent-skills.md)。 **扩展** * [数据库](https://kernlift.dev/zh/docs/extensions/database/postgres.md):SQLite、Turso、Cloudflare D1、Postgres(Supabase、Neon)。 * [登录方式](https://kernlift.dev/zh/docs/extensions/auth/email-password.md):邮箱密码、Google、GitHub。 * [支付](https://kernlift.dev/zh/docs/extensions/payments.md):Stripe、Creem、PayPal、Dodo Payments、微信支付、支付宝、Waffo。 * [存储](https://kernlift.dev/zh/docs/extensions/storage.md):Cloudflare R2 或任意兼容 S3 的存储桶。 * [邮件](https://kernlift.dev/zh/docs/extensions/email.md):Resend、Cloudflare Email、阿里云邮件推送。 * [访问统计](https://kernlift.dev/zh/docs/extensions/analytics.md):Google Analytics、Umami、Plausible、Microsoft Clarity,以及 Crisp 客服聊天组件。 * [AI](https://kernlift.dev/zh/docs/extensions/ai.md):兼容 OpenAI 的接口、Google Gemini、Cloudflare Workers AI,以及用于图片、视频、音频的自定义 HTTP 接口,按[积分](https://kernlift.dev/zh/docs/extensions/credits.md)计费。 * [CMS](https://kernlift.dev/zh/docs/extensions/cms.md)、[邮件订阅与候补名单](https://kernlift.dev/zh/docs/extensions/newsletter.md)、[联盟推广](https://kernlift.dev/zh/docs/extensions/affiliate.md)、[工单](https://kernlift.dev/zh/docs/extensions/support.md)和[通知](https://kernlift.dev/zh/docs/extensions/notifications.md)。 * 可选的 [Agent 工作台](https://kernlift.dev/zh/docs/extensions/agent.md),作为第二个服务运行。 完整清单以及每部分带来的路由见[底座仓库里有什么](https://kernlift.dev/zh/docs/reference/capabilities.md)。 ## 业务模板 业务模板是在底座上做好的成品:同一套应用,里面已经放好了一个产品。每个业务模板是一个独立的私有仓库,单独出售。 | 模板 | 是什么 | | -------------- | ------------------------------------ | | `image-studio` | 图片生成站:提示词、画幅和作品库,按积分计费。只有一个 Web 应用。 | | `video-studio` | 视频生成站:提示词、画幅、时长和可播放的作品库。只有一个 Web 应用。 | | `image-agent` | 基于 Agent 工作台的对话式图片产品,需要 Agent 服务。 | | `video-agent` | 基于 Agent 工作台的对话式视频产品,需要 Agent 服务。 | 两款 Studio 随商业完整版赠送。两款 Agent 可按会员价购买。未购买完整版的买家可原价单买。 ## 从哪里开始 - [获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md) 购买会员,用 GitHub 用户名激活,打开代码仓库。 - [快速开始](https://kernlift.dev/zh/docs/quick-start.md) 克隆仓库,在本地跑起来,并以管理员身份登录。 - [常见问题](https://kernlift.dev/zh/docs/guide/faq.md) 激活、退款、fork、同步更新与技术支持。 - [系统架构](https://kernlift.dev/zh/docs/guide/architecture.md) 动手改之前,先看各层是怎么搭起来的。 --- # 快速开始 > 克隆仓库、安装依赖、构建数据库、创建管理员,在本地把项目跑起来。 Source: https://kernlift.dev/zh/docs/quick-start 本页带你从「购买已激活」走到「本地项目已运行,并以管理员身份登录」。全程使用本地的 SQLite 文件,不需要数据库服务,也不需要云平台账号。业务模板的安装方式相同,只是仓库地址不同。 ## 准备工作 * [前置要求](https://kernlift.dev/zh/docs/guide/prerequisites.md)里的工具:Node 22.12 及以上的 22.x 版本、pnpm 和 git。 * 购买已激活,并且已接受 GitHub 邀请。见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。 * 大约十分钟,大部分时间花在 `pnpm install` 上。 ## 在本地运行 ### 克隆仓库 ```bash 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 账号。 ### 安装依赖并生成类型 ```bash pnpm install pnpm cf-typegen ``` `pnpm cf-typegen` 生成运行时类型声明 `worker-configuration.d.ts`。这个文件是生成的,不会提交到仓库,所以在它生成之前,全新克隆的仓库上 `pnpm typecheck` 会失败。有没有 `wrangler.jsonc` 它都能运行;在 Cloudflare 项目中,每次修改绑定后都要重新运行。 ### 创建 `.env` ```bash 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` 为每个变量做了标记:`[必填]` 必须设置,`[可选]` 有可用的默认值,`[开发]` 只用于开发环境。 ### 构建数据库 ```bash pnpm db:migrate ``` 它会应用迁移链并记录每一步。完成后,项目根目录下会出现 `local.db`。这是构建 schema 唯一受支持的方式。 ### 创建第一位管理员 ```bash 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` 状态页、通知渠道和限流规则)。不包含演示数据。 ### 启动应用 ```bash 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 新建仓库](https://github.com/new),创建一个空的私有仓库,把它设为 `origin`: ```bash git remote set-url origin git@github.com:YOUR-ACCOUNT/my-app.git git push origin main ``` 之后要获取更新,再把模板仓库添加为 `upstream`。见[同步上游更新](https://kernlift.dev/zh/docs/guide/upgrading.md)。 ## 设置部署目标 克隆的仓库带有 `deploy.config.json` 和某一个平台的部署文件。本地开发不需要动它们。要部署到别处,或者加上 agent 服务,运行: ```bash pnpm kernlift deploy-target fly --no-agent --dialect sqlite ``` 把 `fly` 换成 `cloudflare`、`railway` 或 `docker`。命令会写入该平台的文件,把原来的文件移到 `.kernlift/previous-deploy/`,在 `.env.production` 中生成生产环境的密钥,并打印剩余步骤。它不创建任何远端资源。各平台及其允许的数据库见 [部署配置](https://kernlift.dev/zh/docs/reference/deploy-config.md)。 ## 验证 打开 `/setup`。**会话密钥**和**登录方式**显示**已就绪**;在接入服务商之前,**邮件投递**显示**未就绪**。这就是一个新项目应有的状态。 ## 常见问题 ### `git clone` 提示 "Repository not found" 对于你没有读取权限的私有仓库,GitHub 就是这样回答的。到 GitHub 通知里接受邀请,并确认 git 使用的 SSH 密钥或凭据属于激活购买时填写的那个账号。邀请过期的话,见[邀请过期了怎么办?](https://kernlift.dev/zh/docs/guide/faq.md) ### `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`。原因见[运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 下一步 - [安装后的第一步](https://kernlift.dev/zh/docs/customize/first-steps.md) 完成初始化清单,接入邮件,让项目成为你自己的。 - [项目结构](https://kernlift.dev/zh/docs/core/project-structure.md) 熟悉代码仓库的布局。 - [部署项目](https://kernlift.dev/zh/docs/deploy.md) 在你选择的平台上把项目部署到生产环境。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) `.env.example` 中的每个变量。 --- # 底座仓库里有什么 > 底座、随底座提供的模块和 Agent 部分:每一部分增加什么,依赖什么。 Source: https://kernlift.dev/zh/docs/reference/capabilities 本页列出你克隆下来的底座仓库里有什么。这里没有任何东西需要另外安装:底座和下面的每个模块都已经在代码里。依赖服务商的能力在凭据配置完成前不可用。 ## 底座 | 领域 | 可用界面 | 配置或指南 | | ------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 账号与权限 | 登录、注册、验证、找回、个人资料、会话、角色、权限及 API 密钥 | [认证](https://kernlift.dev/zh/docs/core/auth.md)、[角色](https://kernlift.dev/zh/docs/core/auth/roles.md)、[API 密钥](https://kernlift.dev/zh/docs/core/auth/api-keys.md) | | 计费 | 产品、定价套餐(`/admin/plans`)、结账、订单、订阅、客户账单页及履约插件 | [支付](https://kernlift.dev/zh/docs/extensions/payments.md)、[产品](https://kernlift.dev/zh/docs/extensions/payments/products.md) | | 积分 | 余额、预留与账本;结算由服务端工作流执行 | [积分](https://kernlift.dev/zh/docs/extensions/credits.md) | | AI 与对话 | 服务商通道、场景、文本和媒体任务、对话、定价及用量 | [AI 通道](https://kernlift.dev/zh/docs/extensions/ai.md)、[场景](https://kernlift.dev/zh/docs/extensions/ai/scenes.md)、[对话](https://kernlift.dev/zh/docs/extensions/ai/chats.md) | | 文件与消息 | 私有资源、上传、邮件模板与投递、通知 | [存储](https://kernlift.dev/zh/docs/extensions/storage.md)、[邮件](https://kernlift.dev/zh/docs/extensions/email.md)、[通知](https://kernlift.dev/zh/docs/extensions/notifications.md) | | 运营 | 后台概览、用户、工单、分析、审计、限流、国家统计和就绪检查 | [管理后台](https://kernlift.dev/zh/docs/core/admin.md)、[初始化检查](https://kernlift.dev/zh/docs/customize/first-steps.md) | | 扩展 | 插件内核、已安装插件列表,以及用于启用和停用插件的 `/admin/plugins` | [插件](https://kernlift.dev/zh/docs/core/plugins.md) | | 工具 | `kernlift deploy-target`、`kernlift context` 命令和编码 Agent 技能 | [CLI](https://kernlift.dev/zh/docs/reference/deploy-config.md)、[技能](https://kernlift.dev/zh/docs/core/agent-skills.md) | | 部署 | Cloudflare、Fly.io、Railway 和 Docker 的部署配置,由 `kernlift deploy-target` 写入 | [运行时与数据库适配器](https://kernlift.dev/zh/docs/deploy/runtimes.md) | 示例落地页、`/pricing`、关于和联系页面属于底座。博客、可编辑法律内容、更新日志与 RSS 来自下方的 CMS 模块。服务商密钥与业务设置保存在 `/admin/config/*` 或相应后台页面。环境变量只用于启动和基础设施。见[配置模型](https://kernlift.dev/zh/docs/core/configuration.md)。 ## 仓库里的模块 每个模块是一项自成一体的功能,带有自己的页面、服务端代码、数据表、中英文案和校验器。它的边界记录在 `modules/<key>/module.json` 里。**依赖**一列列出它还依赖什么。 | Key | 类型 | 依赖 | 增加什么 | 从这里开始 | | --------------- | -- | --------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `cms` | 模块 | — | 内容编辑器、分类、版本、法律页与更新日志、博客及 RSS | [CMS](https://kernlift.dev/zh/docs/extensions/cms.md) | | `newsletter` | 模块 | — | 邮件订阅、候补名单、邀请及设置页面 | [邮件订阅与候补名单](https://kernlift.dev/zh/docs/extensions/newsletter.md) | | `affiliate` | 模块 | — | 推荐、佣金、提现与审核流程 | [推广返佣](https://kernlift.dev/zh/docs/extensions/affiliate.md) | | `image-agent` | 模块 | `agent-starter` | `/app/image`、Image Studio Skill(`platform.image`)、画幅选择、图片查看器与每次运行的出图上限,设置页在 `/admin/config/image-agent` | [图片 Agent](https://kernlift.dev/zh/docs/extensions/agent/image-agent.md) | | `agent-starter` | 模板 | — | `/app/agent`、Agent API 与服务、技能、连接器、运行工作区、沙箱及搜索配置 | [运行 Agent 启动模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md) | Agent 模板在 Web 应用之外再运行一个服务,并且需要 Postgres。`kernlift deploy-target --agent` 不接受其他数据库。D1 可以运行底座,但不能存储 Agent 运行数据。没有 agent 服务时 Web 应用仍然完整,agent 入口显示服务尚未部署。 `image-agent` 是模块,但它是 agent 工作台的一个插件,没有 `agent-starter` 就不起作用。 业务模板(`image-studio`、`video-studio`、`image-agent`、`video-agent`)是各自独立的仓库,每个都是在这个底座上做好的完整项目。见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。 ## 如何核对一个项目 1. 阅读 `modules/*/module.json` 清单。每份清单通过 `kind`、`requires`、`files`、`fragments`、`migrations`、`tables`、`configKeys` 和 `skillPackages` 定义一个模块的边界。 2. 打开 `/setup` 查看实时就绪状态。未配置的服务商显示为未配置。页面可以存在,而它的外部集成尚未配置。 3. 运行 `pnpm validate:gate`。每项能力带有自己的校验器。 ## 下一步 * [模板与派生产品](https://kernlift.dev/zh/docs/core/plugins/templates.md):产品是怎么在底座上做出来的。 * [开发一个模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md):清单字段,以及如何加入你自己的模块。 --- # 部署配置 > deploy.config.json 和改写它的 kernlift deploy-target 命令:允许的组合、每个平台拥有的文件、.env.production 的键,以及各平台如何迁移和创建管理员。 Source: https://kernlift.dev/zh/docs/reference/deploy-config `deploy.config.json` 是提交到仓库的部署记录,写明项目部署到哪里。你克隆的仓库里已经带有它,`kernlift deploy-target` 改写它,`vite.config.ts` 读取它来选择构建目标,应用也把它打包进去,供 `/setup` 显示。文件里没有任何密钥。设计上的原因见[部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md)。 ## 字段 ```json title="deploy.config.json" { "platform": "cloudflare", "agent": false, "database": "d1" } ``` | 字段 | 取值 | 含义 | | ---------- | ------------------------------------- | ------------------------------- | | `platform` | `cloudflare`、`fly`、`railway`、`docker` | 项目部署到的唯一平台。决定构建目标,以及存在哪个平台的文件 | | `agent` | `true`、`false` | 是否在 Web 应用旁边部署 agent 服务 | | `database` | `d1`、`postgres`、`sqlite` | 生产数据库。无论这里写什么,本地开发都使用 SQLite 文件 | 没有这个文件的项目按 Cloudflare 构建。不要手工修改它。平台文件和它一起渲染,要改就用 `kernlift deploy-target`。参数见[下文](#用-kernlift-deploy-target-切换平台)。 ## 用 kernlift deploy-target 切换平台 `kernlift deploy-target <cloudflare|fly|railway|docker> [flags]` 在带有 `deploy.config.json` 的项目目录里运行。它改写这个文件和平台文件,把 `deploy` 脚本指向该平台的部署命令,把其他平台的文件移到 `.kernlift/previous-deploy/`,向 `.env.production` 补上缺少的键,并打印后续步骤。它不创建任何远端资源,也不迁移数据。克隆下来的项目只需要 `kernlift` 的这一条命令,其余都用[脚本](https://kernlift.dev/zh/docs/reference/scripts.md)完成。 CLI 没有依赖,运行在 Node 20 或更新版本上。它的源码在你克隆的仓库的 `tools/kernlift/` 里。用 `pnpm kernlift deploy-target <platform>` 运行。根 `package.json` 里的 `kernlift` 脚本执行的是 `tools/kernlift/src/kernlift.js`,不需要从 npm 下载任何包。 | 参数 | 含义 | | ------------------------ | ----------------------------------- | | `--agent` / `--no-agent` | 包含或去掉 agent 服务(默认:项目当前的选择) | | `--dialect <db>` | 生产数据库(默认:新平台允许时沿用当前的,否则取该平台的第一个可选项) | | `--region <code>` | Fly.io 主区域(默认 `iad`) | | `--cwd <dir>` | 项目目录(默认:当前目录) | | `--help` | 打印用法 | 取值的参数写作 `--flag value` 或 `--flag=value`。`--agent` 和 `--no-agent` 不取值。 退出码: | 退出码 | 何时 | | --- | ------------------------------------------------------------- | | `0` | 命令完成 | | `1` | 任何错误(信息打印到 stderr):未知的平台、平台不允许的组合,或目录里没有 `deploy.config.json` | ## 允许的组合 | `platform` | `agent: false` | `agent: true` | | ------------ | ------------------- | ------------- | | `cloudflare` | `d1`、`postgres` | `postgres` | | `fly` | `postgres`、`sqlite` | `postgres` | | `railway` | `postgres` | `postgres` | | `docker` | `postgres`、`sqlite` | `postgres` | 一共十一种组合。CLI 在写入文件之前拒绝其它组合。agent 需要 Postgres,因为它的运行需要事务,以及一个由两个进程共用的数据库。`sqlite` 是单机方案,`d1` 只存在于 Cloudflare。执行 `kernlift deploy-target` 时不带 `--dialect`,新平台允许当前数据库就沿用,否则取该行的第一个值。 ## 每个平台拥有什么 | `platform` | 项目根目录中的文件 | 构建目标 | `deploy` 脚本 | | ------------ | ---------------------------------------- | ------------ | --------------------------------------------------------- | | `cloudflare` | `wrangler.jsonc` | `cloudflare` | `wrangler deploy` | | `fly` | `fly.toml`,包含 agent 时还有 `fly.agent.toml` | `node` | `fly deploy` | | `railway` | `.railway/railway.ts` | `node` | `railway up` | | `docker` | `compose.yaml` | `node` | `docker compose --env-file .env.production up -d --build` | `node` 构建目标由根目录的 `Dockerfile` 打包。agent 服务在所有平台上都使用 `apps/agent-service/Dockerfile`。无论选哪个平台,这两个 Dockerfile 都留在仓库里。 平台文件由 CLI 自带的模板渲染。`kernlift deploy-target` 对项目当前的平台再次渲染时,内容与新渲染结果不同的文件(填了资源 id 的 `wrangler.jsonc`、手工改动)会先移到 `.kernlift/previous-deploy/` 再写入新文件。内容相同的文件不动。 ## 各平台的行为 | | `cloudflare` | `fly` | `railway` | `docker` | | ---------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------- | --------------------------------- | | 迁移 | `d1` 用 `pnpm db:migrate:d1:remote`;`postgres` 对 Postgres URL 执行 `pnpm db:migrate` | `postgres` 用 `release_command`;`sqlite` 在进程启动时 | `web` 服务的 `preDeploy` | `migrate` 服务 | | 迁移器 | Wrangler 的 D1 迁移,或 `scripts/db/migrate.ts` | `scripts/db/migrate-runtime.mjs` | `scripts/db/migrate-runtime.mjs` | `scripts/db/migrate-runtime.mjs` | | 线上管理员 | `DATABASE_DIALECT=d1` 时 `pnpm db:bootstrap-super-admin --remote`;Postgres 时带上 `DATABASE_URL` | `fly ssh console --pty -C "node .output/scripts/bootstrap-super-admin.mjs"` | `railway ssh --service web`,再运行同一个脚本 | `docker compose exec web` 运行同一个脚本 | | 定时任务 | Cron Trigger,每分钟一次 | Web 进程内循环;`min_machines_running = 1` | Web 进程内循环 | Web 进程内循环 | | 密钥存储 | `wrangler secret put` | `fly secrets import` | `railway variables` | `--env-file .env.production` | | agent 服务 | 绑定为 `AGENT_SERVICE` 的容器 | 应用 `<name>-agent`,`fly.agent.toml` | 服务 `agent`,单副本 | 服务 `agent` | | Web 访问 agent 的地址 | 容器绑定 | `http://<name>-agent.internal:3001` | `http://agent.railway.internal:3001` | `http://agent:3001` | | agent 访问 Web 的地址 | `AGENT_WEB_INTERNAL_URL`,即 Worker 的公网 URL | `http://<name>.internal:3000` | `http://web.railway.internal:3000` | `http://web:3000` | | Postgres 的来源 | 你的数据库,经 `HYPERDRIVE` 绑定 | 你的数据库,作为 `DATABASE_URL` 密钥 | `.railway/railway.ts` 里的 `postgres` 资源 | compose 的 `postgres` 服务 | | SQLite 文件 | 不提供 | `data` 卷上的 `/data/app.db` | 不提供 | `data` 卷上的 `/data/app.db` | ## .env.production 由 `kernlift deploy-target` 在项目根目录生成并补全。文件权限为 0600,被 git 和 Docker 构建上下文忽略。已有的文件会保留。之后的运行只添加缺失的键,不修改也不删除任何值。 | 键 | 何时生成 | 值 | | ------------------------------- | --------------------- | ------------------------------------- | | `BETTER_AUTH_SECRET` | 始终 | 32 个随机字节,十六进制 | | `CONFIG_ENCRYPTION_KEY` | 始终 | 32 个随机字节,十六进制;用来加密后台配置里的服务商密钥,生成后不要更换 | | `SITE_URL` | 始终 | 创建项目时给出的站点 URL;请改成部署后的源地址 | | `POSTGRES_PASSWORD` | `docker` 且 `postgres` | 32 个随机字节,十六进制;自带 Postgres 的密码 | | `AGENT_INTERNAL_SIGNING_SECRET` | `agent` 为 `true` | 32 个随机字节,十六进制;Web 应用与 agent 服务共用 | | `AGENT_RESOURCE_GRANT_SECRET` | `agent` 为 `true` | 32 个随机字节,十六进制 | 在 `fly` 上使用 Postgres 时,`DATABASE_URL` 由你自己加进去,导入 Fly 密钥时会一并带上。在 `cloudflare` 上,agent 容器直连 Postgres 的 URL 以 `AGENT_DATABASE_URL` 密钥保存。这些值经标准输入送到平台,不会被打印。它和 `.env` 是两个文件,后者存放你本机的开发值。 ## .kernlift/previous-deploy/ `kernlift deploy-target` 切换平台时,项目根目录里属于其它平台的文件会按原相对路径移到这里,例如 `.kernlift/previous-deploy/wrangler.jsonc`。不删除任何文件。那里已有的副本不会被覆盖。后来的副本取下一个空闲的名字,`wrangler.jsonc.1`,然后是 `.2`。 这个目录用来找回内容,比如早先 `wrangler.jsonc` 里的资源 id。切回某个平台时,它的文件仍由模板重新渲染,不会从这里恢复。 ## 检查 | 命令 | 检查什么 | | ------------------------------ | -------------------------------------------------- | | `pnpm validate:deploy-targets` | 每个允许的组合都渲染出正确的文件,不允许的组合被拒绝,根目录的文件与渲染器一致,Node 构建能启动 | | `pnpm smoke:node` | `pnpm build:node` 之后,在一次性的 SQLite 数据库上检查 Node 构建 | | `pnpm smoke:worker` | `pnpm build` 之后,在一次性的 D1 数据库上检查 Worker 构建 | ## 下一步 - [部署模型](https://kernlift.dev/zh/docs/deploy/runtimes.md) - [部署项目](https://kernlift.dev/zh/docs/deploy.md) - [脚本](https://kernlift.dev/zh/docs/reference/scripts.md) - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) --- # 环境变量 > 部署必须的六个变量、少数可选变量,以及只有 Agent 服务和脚本才读取的变量。 Source: https://kernlift.dev/zh/docs/reference/env 网站运行只需要六个环境变量。其余的服务商凭据、登录方式、发件人和支付设置都在 `/admin/config/*` 里配置,保存在数据库中。`.env.example` 列出源码读取的每个变量,两者不一致时 `pnpm validate:env-example` 失败。 ## 必须配置 | 变量 | 默认值 | 作用 | | -------------------- | ------------------------------ | ------------------------------------------------------- | | `APP_ENV` | `development` | `development` 或 `production`。只要不是 `development` 就启用生产守卫 | | `BETTER_AUTH_SECRET` | 模板密钥(仅开发环境) | 会话签名密钥。非开发环境下为空或仍是模板默认值时应用拒绝启动 | | `SITE_URL` | `https://kernlift.example.com` | 元数据、站点地图、订阅源和绝对链接使用的规范域名 | | `DATABASE_DIALECT` | `sqlite` | `sqlite`、`postgres` 或 `d1`;同时决定使用哪条迁移链 | | `DATABASE_URL` | `./local.db`(`postgres` 时为空) | 文件路径、`postgresql://` 或 `libsql://` 地址 | ## 可选 不需要对应功能时不用设置。 | 变量 | 默认值 | 作用 | | ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CONFIG_ENCRYPTION_KEY` | —(凭据以明文存储) | 至少 32 个字符。用 AES-256-GCM 对后台配置中分类为 `secret` 的值(支付、邮件、存储、AI 和 OAuth 凭据)做静态加密,存为 `enc:v1:…`。设置后保持不变:用一个密钥写入的值在另一个密钥下读作未配置。设置密钥前已保存的凭据,执行一次 `pnpm db:encrypt-config-secrets` 加密。见[加密存储的凭据](https://kernlift.dev/zh/docs/core/configuration.md) | | `JOBS_IN_PROCESS` | `true` | Node 服务在 Web 进程内每分钟执行一轮[定时任务](https://kernlift.dev/zh/docs/core/background-jobs.md)。设为 `false` 时改由外部 cron 调用 `pnpm jobs:run`。Cloudflare Worker 不读取它,用的是 `wrangler.jsonc` 里的 Cron Trigger | | `ADMIN_CONFIG_CACHE_TTL_MS` | `30000` | 后台配置的缓存时长;它是唯一无法从 `/admin/config/cache` 读取自身策略的缓存 | | `DATABASE_ADAPTER` | 与方言相同 | 已注册的适配器 id:`sqlite`、`postgres`、`turso`、`d1`、`hyperdrive`(在 Worker 上连接 Postgres)或自定义适配器 | | `DATABASE_AUTH_TOKEN` | — | `turso` 适配器使用的 libSQL 认证令牌 | | `AUTH_DEV_IMPERSONATE_USER_ID` | — | 把未登录请求视为该用户。仅在 `APP_ENV=development` 时生效,并输出警告 | ## 可选 Agent 服务 只有在 Web 应用旁边部署 Agent 服务时才需要设置这些变量,不部署 Agent 的站点一个都不用填。模型、沙箱和搜索在 `/admin/config/*` 中配置。本地运行 `pnpm dev:agent` 时,地址和两个密钥由它每次自动设置;部署时需要固定值。 | 变量 | 默认值 | 读取方 | 作用 | | ----------------------------------------- | ----------- | -------- | ------------------------------------------------------------------------------- | | `AGENT_SERVICE_URL` | — | Web 应用 | Agent 服务的内部地址。Node 部署启用 Agent 时必填;Cloudflare 部署通过 `AGENT_SERVICE` 绑定访问容器,不读这个变量 | | `AGENT_WEB_INTERNAL_URL` | — | Agent 服务 | Web 应用的内部地址。必填 | | `AGENT_INTERNAL_SIGNING_SECRET` | — | 两个进程 | 两个进程之间的请求签名密钥,两端取值相同,不少于 32 字节。必填 | | `AGENT_RESOURCE_GRANT_SECRET` | — | Web 应用 | 签发短期资源授权,不少于 32 字节。必填 | | `AGENT_SERVICE_HOST`、`AGENT_SERVICE_PORT` | `::`、`3001` | Agent 服务 | 监听地址和端口 | | `AGENT_SERVICE_REQUEST_TIMEOUT_MS` | `120000` | Web 应用 | 调用 Agent 服务的超时时间(毫秒) | | `AGENT_FLOW_LOG_LEVEL` | `info` | 两个进程 | `debug`、`info`、`warn`、`error` 或 `silent` | | `AGENT_SANDBOX_ERROR_LOG_ENABLED` | `true` | Agent 服务 | 是否记录沙箱错误详情 | 环境中带有 Web 认证或支付密钥时,Agent 服务拒绝启动。`CONFIG_ENCRYPTION_KEY` 要与 Web 应用设为相同的值,因为 Agent 服务读同一张配置表。Agent 的数据库必须支持事务,D1 不能存储 Agent 数据。见[安装 Agent](https://kernlift.dev/zh/docs/extensions/agent/starter.md)。 ## 脚本与工具 只有命令行脚本和校验器读取,Web 应用不会读取。 | 变量 | 读取方 | 作用 | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------- | | `SUPER_ADMIN_EMAIL`、`SUPER_ADMIN_PASSWORD` | `pnpm db:bootstrap-super-admin` | 必填。第一个管理员;密码(至少 8 位)仅在新建账号时使用 | | `SUPER_ADMIN_NAME` | `pnpm db:bootstrap-super-admin` | 可选,默认 `Super Admin` | | `EXTERNAL_VALIDATE_STRICT` | `pnpm validate:external` | 为 `true` 时把跳过的服务商检查判为失败 | | `EXTERNAL_VALIDATE_EMAIL_TO` | `pnpm validate:external` | 真实邮件检查的收件人 | | `EXTERNAL_VALIDATE_NEWSLETTER_EMAIL` | `pnpm validate:external` | 通过订阅服务商订阅并退订的邮箱 | | `EXTERNAL_VALIDATE_GOOGLE_OAUTH_CONFIRMED` | `pnpm validate:external` | 确认已手动完成 Google OAuth 跳转验证 | | `EXTERNAL_VALIDATE_BILLING_CUSTOMER_ID`、`EXTERNAL_VALIDATE_BILLING_PAYMENT_ID`、`EXTERNAL_VALIDATE_BILLING_SUBSCRIPTION_ID` | `pnpm validate:external` | 客户门户、退款和订阅检查使用的沙箱 id | | `KERNLIFT_REGISTRY_URL`、`KERNLIFT_PUBLISH_TOKEN` | `pnpm registry:publish` | 发布目标 registry 及其发布密钥。克隆的项目用不到 | | `KERNLIFT_TOKEN`、`KERNLIFT_CONFIG_DIR` | CLI 的包管理命令 | registry 令牌、配置目录覆盖。克隆的项目用不到 | | `CHROME_PATH` | `pnpm assets:screenshots` | 截图使用的 Chrome 可执行文件 | | `NODE_ENV` | 数据库脚本 | 由工具提供;决定加载哪些 `.env` 文件 | | `AGENT_DEV_WEB_HOST`、`AGENT_DEV_WEB_PORT` | `pnpm dev:agent` | 本地开发的 Web 监听地址,默认 `127.0.0.1:5173` | | `AGENT_DEV_SERVICE_HOST`、`AGENT_DEV_SERVICE_PORT` | `pnpm dev:agent` | 本地开发的 Agent 服务监听地址,默认 `127.0.0.1:3001` | | `SKILL_PUBLISH_DRY_RUN` | `pnpm agent:publish-skills` | 设为任意非空值时只报告将要发布的内容,不写入 | | `AGENT_SANDBOX_TEMPLATE_DIR` | 沙箱镜像构建 | 覆盖沙箱镜像模板目录 | ## Cloudflare 绑定 这些绑定在 `wrangler.jsonc` 中声明,不写入 `.env`。 | 绑定 | 类型 | 作用 | | ------------ | ---------- | ---------------------------------------------------------------- | | `EDGE_DB` | D1 数据库 | `d1` 适配器使用的数据库 | | `HYPERDRIVE` | Hyperdrive | `hyperdrive` 适配器使用的 Postgres 连接;默认注释掉,在 Worker 上使用 Postgres 时再启用 | | `BUCKET` | R2 桶 | 桶绑定驱动使用的存储 | | `CACHE` | KV 命名空间 | `kv` 缓存后端 | | `AI` | Workers AI | 边缘推理 | | `ASSETS` | 静态资源 | 提供 `dist/client` | `wrangler.jsonc` 还声明了 `"triggers": { "crons": ["* * * * *"] }`,每分钟触发一轮定时任务。Agent 服务以 Cloudflare 容器运行时,它直连 Postgres 的地址是 Worker 密钥 `AGENT_DATABASE_URL`,用 `wrangler secret put` 设置。 ## 不是环境变量的设置 `RESEND_API_KEY`、`STRIPE_SECRET_KEY`、`GOOGLE_CLIENT_ID` 这类服务商设置写在环境里不会生效,请在后台配置,见[配置一个可运行的项目](https://kernlift.dev/zh/docs/core/configuration/project.md)。`/admin/config/ai` 中的 AI 通道请求模板可以用 `{{env.NAME}}` 引用环境变量,密钥要用 `{{secret.KEY}}`。 ## 下一步 - [管理配置](https://kernlift.dev/zh/docs/core/configuration/project.md) 不在这一页上的其余设置。 - [配置模型](https://kernlift.dev/zh/docs/core/configuration.md) 为什么只有少量设置放在环境变量里。 - [缓存](https://kernlift.dev/zh/docs/core/admin/cache.md) `ADMIN_CONFIG_CACHE_TTL_MS` 和它引导的缓存域。 - [部署到 Node 主机](https://kernlift.dev/zh/docs/deploy/node.md) 一台生产主机需要的变量。 --- # 脚本 > 模板 package.json 里除单个校验器之外的每个 pnpm 脚本,按用途分组。 Source: https://kernlift.dev/zh/docs/reference/scripts 在项目根目录用 `pnpm <name>` 运行。涉及数据库的脚本从 `.env` 或 shell 读取 `DATABASE_DIALECT` 与 `DATABASE_URL`。单个 `validate:*` 脚本见[校验器](https://kernlift.dev/zh/docs/reference/validators.md)。 ## 开发 | 脚本 | 作用 | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `pnpm dev` | 用 Vite 启动 Web 应用,端口 5173 | | `pnpm dev:agent` | 同时启动 Web 应用和 Agent 服务(`agent-starter`),自带本机地址和临时签名密钥 | | `pnpm kernlift` | 运行 `tools/kernlift` 中的 Kernlift CLI,例如 `pnpm kernlift deploy-target fly`。见 [deploy.config.json](https://kernlift.dev/zh/docs/reference/deploy-config.md) | | `pnpm preview` | 用 `vite preview` 预览最近一次构建 | | `pnpm cf-typegen` | 生成 `worker-configuration.d.ts`,即源码编译所依赖的 Workers 运行时与绑定类型 | | `pnpm assets:generate` | 重新生成占位用的站点图标和社交分享图 | | `pnpm assets:screenshots` | 通过 Chrome 从本机运行的实例截取营销截图;`CHROME_PATH` 指定可执行文件 | ## 构建与运行 | 脚本 | 作用 | | -------------------------- | ----------------------------------------------------------------- | | `pnpm build` | 按 `deploy.config.json` 记录的平台构建:Cloudflare Worker,或其它平台共用的 Node 服务 | | `pnpm build:cloudflare` | 不看 `deploy.config.json`,构建 Cloudflare Worker | | `pnpm build:node` | 构建 Node 服务,并把管理员初始化脚本打包到 `.output/scripts/` 供生产镜像使用 | | `pnpm build:agent-service` | 构建独立的 Agent 服务包 | | `pnpm start` | 运行 Node 构建产物(`.output/server/index.mjs`) | | `pnpm deploy` | 执行所选平台的部署命令;Cloudflare 项目里是 `wrangler deploy` | ## 数据库 | 脚本 | 作用 | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pnpm db:migrate` | 应用当前方言的迁移链;无法执行时打印数据库所处的状态 | | `pnpm db:migrate:runtime` | 用纯 Node 应用同一批迁移,不需要 TypeScript 工具链;生产镜像的发布步骤 | | `pnpm db:migrate:d1:local` | 通过 wrangler 把 SQLite 迁移链应用到本机 D1 | | `pnpm db:migrate:d1:remote` | 把 SQLite 迁移链应用到已部署的 D1 | | `pnpm db:generate` | 按 `DATABASE_DIALECT` 指定的方言运行 `drizzle-kit generate` | | `pnpm db:generate:sqlite` | 为 SQLite schema 生成迁移 | | `pnpm db:generate:postgres` | 为 Postgres schema 生成迁移 | | `pnpm db:studio` | 在当前数据库上打开 Drizzle Studio | | `pnpm db:seed-baseline` | 写入全新数据库需要的基线内容:邮件模板、营销页面与区块、限流规则。已存在的行保持不变 | | `pnpm db:bootstrap-super-admin` | 用 `SUPER_ADMIN_EMAIL` 和 `SUPER_ADMIN_PASSWORD` 创建首个管理员,写入权限目录并执行基线种子 | | `pnpm db:seed` | 不写入任何数据,只提示基线内容来自 `pnpm db:seed-baseline` | | `pnpm db:encrypt-config-secrets` | 用 `.env` 或命令行环境中的 `CONFIG_ENCRYPTION_KEY`,把仍以明文存储的 `secret` 类后台配置加密。已加密的值跳过,重复执行不会改动任何行;没有有效密钥时报错退出。D1 默认处理本地状态,加 `--remote` 处理线上数据库,`--persist-to <目录>` 指定另一份本地状态 | ## 定时任务 | 脚本 | 作用 | | --------------- | ----------------------------------------------------- | | `pnpm jobs:run` | 执行一轮定时任务并打印报告;这一轮已被其它执行方占用时打印 `"skipped"`。有任务失败时退出码非零 | ## Agent | 脚本 | 作用 | | --------------------------- | ----------------------------------------------------------- | | `pnpm agent:publish-skills` | 把内容有变化的平台 Skill 发布到技能注册表;设置 `SKILL_PUBLISH_DRY_RUN` 时只预览不写入 | ## Registry 与技能 `registry:build` 用来把模块清单与代码核对,见[开发一个模块](https://kernlift.dev/zh/docs/core/plugins/build-a-module.md)。`registry:publish` 把结果上传到 registry 服务端,从 GitHub 克隆的项目没有这个服务端。 | 脚本 | 作用 | | ----------------------- | ------------------------------------------------------------------------------------- | | `pnpm registry:build` | 把检出切成一个底座条目和每个 `modules/<key>/module.json` 对应的条目,输出到 `registry/dist` | | `pnpm registry:publish` | 用 `KERNLIFT_PUBLISH_TOKEN` 把 `registry/dist` 推送到 `KERNLIFT_REGISTRY_URL` 指向的 registry | | `pnpm skills:pack` | 从 `skills/` 构建 `packages/kernlift-skills`,并写出 `skills.json` 清单 | ## 检查 | 脚本 | 作用 | | ------------------------ | --------------------------------------------------------------------------------- | | `pnpm typecheck` | `tsc --noEmit`,同时检查 `tests/` 下的单元测试 | | `pnpm test` | 用 Node 内置测试运行器(`tsx --test`)执行 `tests/unit/*.test.ts`。覆盖签名、验签、金额换算和加密,不连数据库、不访问网络 | | `pnpm check` | `biome check .`:lint 与格式检查,会报告存量违规 | | `pnpm lint` | `biome lint .` | | `pnpm lint:budget` | 某条 lint 规则的违规数超过记录的预算时失败;确实减少后用 `--update` 下调预算 | | `pnpm format` | `biome format --write .` | | `pnpm validate:all` | 按顺序运行接入的校验器链,遇到第一个失败即停止 | | `pnpm validate:gate` | 运行除手动项和已知失败项之外的每个校验器;CI 以它为门禁 | | `pnpm openspec:validate` | 对每个带 `tasks.md` 的活动变更运行 `openspec-cn validate` | | `pnpm smoke:node` | 在一次性 SQLite 数据库上运行 Node 构建产物,不带 Agent 服务;先运行 `pnpm build:node` | | `pnpm smoke:worker` | 在本机 `wrangler dev` 和一次性 D1 数据库上运行构建好的 Worker,不带 Agent 服务;先运行 `pnpm build` | **Note** 不要对整个仓库运行 `biome check --write --unsafe`。它的修复会去掉样式表里的 `!important`,并改写 React hook 的依赖数组,两者都会改变行为。 ## 下一步 - [校验器](https://kernlift.dev/zh/docs/reference/validators.md) 单个 `validate:*` 脚本。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) 这些脚本读取什么。 - [运行后台任务](https://kernlift.dev/zh/docs/core/background-jobs/run.md) 什么时候需要自己调度 `pnpm jobs:run`。 - [数据访问](https://kernlift.dev/zh/docs/core/data-access.md) 为什么每种方言各有一条迁移链。 --- # 技能 > skills/ 里的 SKILL.md 工作流:每个做什么、需要你提供什么、如何确认完成。 Source: https://kernlift.dev/zh/docs/reference/skills `skills/<name>/SKILL.md` 是编码 Agent(例如 Claude Code)在本仓库或其衍生项目里干活时遵循的工作流。`.claude/skills/<name>` 链接了每一个,打开代码仓库即可使用。每个技能都有四节:**Inputs**(Agent 向你要什么)、**Invariants**(它遵守的规则)、**Workflow**(步骤)和 **Verification**(证明完成的命令和页面)。在其他项目里安装和运行的方法见[使用编码 Agent 技能](https://kernlift.dev/zh/docs/core/agent-skills.md)。 它们不是可选 `/app/agent` 工作台运行的 `agent-skills/` 发布包,后者见 [Agent 模板](https://kernlift.dev/zh/docs/extensions/agent/starter.md)。 ## 一览 | 技能 | 用途 | 你需要提供 | | --------------------- | -------------------------------------- | ------------------------------ | | `project-context` | 修改之前先了解项目 | 任务或要了解的部分 | | `quick-start` | 创建项目,跑到能用管理员账号登录 | 项目名、域名、部署平台、是否需要 Agent | | `configure-providers` | 接入登录、邮件、支付、存储、AI、分析或缓存 | 要接入的能力和服务商凭据 | | `new-page` | 添加一个后台或工作台页面 | 路径、读写什么、权限键 | | `new-module` | 从头到尾添加一个能力模块 | 模块 key、数据表、页面、权限键、依赖的模块 | | `new-agent-plugin` | 给唯一的 Agent 工作台添加一项能力 | 插件 id、场景、附带的 Skill、用户看到什么 | | `deploy` | 部署到 Cloudflare、Fly.io、Railway 或 Docker | 平台、已登录的平台 CLI、需要时的 Postgres 地址 | | `add-module` | 从 Kernlift registry 安装或升级模块 | 模块 key | | `remove-module` | 卸载 registry 安装的模块,保留本地修改和数据 | 模块 key、数据是否一并删除 | 直接用自然语言说任务,或点名技能,例如“用 new-page 技能加一个导出用的后台页面”。 ## 了解项目 ### `project-context` 让 Agent 先运行 `pnpm kernlift context` 看概况,读 `AGENTS.md`,再按任务查看相关的路由、插件、设置页、环境变量、脚本或校验器,打开输出里指出的文件,最后选择对应的任务技能。概况里的插件列表与 `src/plugins/installed.ts` 一致、`pnpm validate:skills` 通过即为完成。 ## 开发 ### `new-page` 在 `/admin/<x>` 或 `/app/<x>` 下添加页面:双语文案、按权限键把关的服务端函数、导航入口,以及所在布局的守卫。`pnpm validate:route-i18n`、`pnpm validate:app-i18n`、`pnpm validate:auth-boundary` 和 `pnpm validate:beui-console` 通过,页面在两种语言和两种主题下正常显示,没有权限的用户看不到入口,即为完成。 ### `new-module` 把一项能力做成模块:仓储、服务、路由、两种数据库方言的表结构与迁移、双语文案、校验器,以及带 `@module` 标记的清单。`pnpm validate:registry` 显示底座仍能单独通过类型检查、模块自己的校验器通过、`pnpm validate:all` 没有把任何检查变红,即为完成。 ### `new-agent-plugin` 给 Agent 工作台添加插件:服务端扩展、浏览器入口、Skill、卡片、面板和操作,可在 `/admin/plugins` 里随时开关。`pnpm validate:agent-plugin-contract` 和插件自己的校验器通过、`pnpm build:agent-service` 仍能构建、插件出现在 `/app/agent` 的选择器里,即为完成。 ## 配置与上线 ### `quick-start` 创建项目、安装依赖、迁移本地数据库、创建超级管理员并启动 `pnpm dev`。`pnpm typecheck` 和 `pnpm validate:gate` 通过,`/setup` 显示会话密钥和至少一种登录方式就绪,即为完成。 ### `configure-providers` 带你走一遍某项能力对应的 `/admin/config/*` 页面,服务商凭据不放进环境变量。`/setup` 显示该项就绪、`pnpm validate:env-example` 通过即为完成;`EXTERNAL_VALIDATE_STRICT=true pnpm validate:external` 会对真实服务商做检查。 ### `deploy` 选择或切换 `deploy.config.json` 里记录的平台,保存生成的密钥,迁移并部署。部署命令打印出地址,`/setup` 显示平台、会话密钥和定时任务就绪,即为完成。上线前可以先用 `pnpm smoke:node` 或 `pnpm smoke:worker` 检查构建。 ## 模块 这两个技能只用于从 Kernlift registry 安装模块的项目。从商店购买的模板以独立的 GitHub 仓库交付,不需要它们,见[获取 Kernlift](https://kernlift.dev/zh/docs/guide/get-kernlift.md)。 ### `add-module` 安装或升级模块,然后执行它的安装、迁移和校验步骤。模块的校验器通过、CLI 的健康检查全部正常、有权限的用户能看到它的后台页面,即为完成。 ### `remove-module` 卸载模块:先预览计划,保留你的本地修改,除非你要求,否则保留模块数据。CLI 的健康检查全部正常、`pnpm typecheck` 和 `pnpm build` 通过、模块页面已消失,即为完成。 ## 检查 | 命令 | 检查什么 | | ---------------------- | --------------------------------- | | `pnpm validate:skills` | 每个技能都有四节,且只引用存在的命令、路径和路由 | | `pnpm skills:pack` | 从 `skills/` 构建 `@kernlift/skills` | ## 下一步 - [使用编码 Agent 技能](https://kernlift.dev/zh/docs/core/agent-skills.md) 在其他项目里安装技能并运行。 - [脚本](https://kernlift.dev/zh/docs/reference/scripts.md) 技能会运行的命令。 - [校验器](https://kernlift.dev/zh/docs/reference/validators.md) 每个 validate:\* 检查证明什么。 --- # 校验器 > 每个 validate:* 脚本证明什么、validate:all 与发布门禁是否运行它,以及哪些已知会失败。 Source: https://kernlift.dev/zh/docs/reference/validators 用 `pnpm validate:<name>` 运行单个校验器。`pnpm validate:all` 按顺序运行接入的整条链,遇到第一个失败即停止。`pnpm validate:gate` 运行除手动项和 `scripts/validate/known-failures.json` 所列之外的每个 `validate:*` 脚本,出现任何回归即失败。 ## 功能 | 脚本 | 证明 | | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `validate:api-keys` | Key 做了哈希、带 scope 并受限流;记录用量;后台清单与接线 | | `validate:auth` | 账号流程:注册、验证、重置、会话 | | `validate:auth-feedback` | 登录错误在两种语言下都有译文,并以 alert 呈现 | | `validate:auth-boundary` | 每个 API 路由要么受守卫,要么写明理由后公开;布局守卫;Webhook 验签结论 | | `validate:google-one-tap` | 向 Better Auth 处理器发真实请求:One Tap 开启时伪造的 ID token 返回 400 且不建会话;关闭或 Google 未启用时 `/api/auth/one-tap/callback` 返回 404 | | `validate:ai` | AI 任务、定价与积分围绕真实结果结算 | | `validate:ai-channel` | 渠道 schema、定价、解析、Webhook 签名与轮询、退款 | | `validate:generation-pipeline` | 渠道解析路径可以索引数组、场景的相对状态路径、虚拟主机风格的对象寻址 | | `validate:analytics` | 分析服务商、事件、报表拉取与工单 | | `validate:billing` | 结账、Webhook、退款、客户门户;服务商未配置时判为失败,不伪造成功 | | `validate:billing-fulfilment` | 已付订单、退款和结账拒绝对每个 `billing.fulfilment` 插件只通知一次;失败会被记录,并由定时任务重试 | | `validate:wechat-pay` | 微信支付的签名、验签、解密、金额核对、结算、退款、按币种选渠道与二维码收银页 | | `validate:alipay` | 支付宝的 RSA2 签名、收银台地址、异步通知验签及应用号 / 卖家 / 金额核对、结算、重复通知、网关应答验签、按币种选渠道与后台表单 | | `validate:waffo` | Waffo 的请求签名、结账会话(按套餐选商品、含税价格、订单 id、优惠码)、webhook 验签及重放与篡改拒绝、按实收金额结算 | | `validate:promotion-codes` | 优惠码开关只在开启时传给 Stripe Checkout;签名 webhook 中的折后金额记为实付 | | `validate:pricing-plans` | `/admin/plans` 写入每个语言行,`/pricing` 与结账读到同样的数据,非法输入被拒绝,保存有审计且需要 `plans.write` | | `validate:credits` | 预留、扣减与退还账本 | | `validate:signup-credits` | 注册奖励设置读写一致;每个用户只发一次、关闭时不发;Better Auth 的用户创建钩子已接线 | | `validate:cache-policy` | 来自后台配置的分域缓存策略 | | `validate:config-encryption` | `secret` 类配置以 `enc:v1:` 密文存储、读出明文;密钥不对时读作未配置且不被默认值覆盖;加密命令;持有凭证的缓存域只用内存 | | `validate:email` | 模板、投递记录、通知渠道 | | `validate:files` | 上传、签名下载、存储配置 | | `validate:foundation` | 上线就绪检查、后台概览、系统状态 | | `validate:plugins` | 插件注册表的冲突处理、已安装列表的接线、启用状态与依赖级联、`/admin/plugins` 页面 | | `validate:session-owner` | 读取限定在所有者范围内 | | `validate:system` | 系统状态页、事件记录、跳转、维护模式 | | `validate:users` | RBAC、角色、权限、分配、状态变更 | ## 模块与 Agent | 脚本 | 证明 | | -------------------------------- | -------------------------------------------------------------------------------------- | | `validate:affiliate` | 推荐、佣金、提现审核、计划设置 | | `validate:cms` | 内容条目、修订、SEO 检查、支持多语言的后台路由 | | `validate:newsletter` | 订阅与候补名单流程、服务商同步日志 | | `validate:registry` | registry 切片可以还原整个检出;底座单独通过类型检查;清单描述的都是真实文件 | | `validate:kernlift-lifecycle` | 在真实 registry 条目上执行 CLI 的模块安装与卸载:预览不写入、拒绝被依赖的模块、逐字节还原、保留改动、`--purge-data` 生成迁移 | | `validate:optional-agent` | 不部署 Agent 服务时 Web 应用完整可用:定时任务在 Web 应用内由一把锁控制运行,Agent 入口显示不可用,任何 Web 请求路径都不加载 Agent 运行时 | | `validate:agent-starter` | Agent 模板的隔离、对事务型数据库的要求、所有者范围、API 守卫、积分与就绪状态 | | `validate:agent-plugin-contract` | 所有 Agent 插件共用一个工作台输入框;插件的卡片、面板与服务端接入点;被停用的插件不会被选中 | | `validate:agent-generation` | 生成管线的 Agent 一侧:SQLite 上的原始查询、发布生成的媒体、视频产物 | | `validate:dsh-runtime` | Agent 运行时解析到锁定版本的 DeepSeek Harness,运行时包之外没有代码直接引用它 | | `validate:image-agent` | 图片 Agent 只通过插件插槽接入宿主、工作台和两个控制台,并作为模块发布 | ## 站点与文案 | 脚本 | 证明 | | ------------------------------- | --------------------------------------------------------------- | | `validate:app-i18n` | 通用、认证、系统与营销文案都经由词典解析 | | `validate:route-i18n` | 路由支持多语言 | | `validate:marketing` | 营销快照、页面与区块 | | `validate:example-landing` | `/` 与 `/pricing` 只用公开外壳、page-shell 基础组件和 beUI 搭建,其中每个链接都指向存在的路由 | | `validate:beui-console` | 控制台、工作台、认证页与系统页使用统一的 beUI 体系,不引入 `src/components/ui` | | `validate:admin-surface-polish` | 后台记录列表的分页与窗口计算正确 | | `validate:mobile` | 响应式约定 | | `validate:site-metadata` | 站点配置、站点地图、robots、`.env.example` 漂移 | | `validate:project-docs` | README 只提到存在的命令和路径;`/setup` 的就绪状态由实时配置推导 | | `validate:skills` | 技能只引用存在的命令、路径和路由 | | `validate:project-context` | `pnpm kernlift context` 输出与源码一致 | | `validate:store-boundary` | 模板里没有授权、registry 服务端、商品目录、Kernlift 营销站和文档站 | ## 工程与部署 | 脚本 | 证明 | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `validate:env-example` | `.env.example` 与源码读取的变量一致 | | `validate:unit-tests` | `pnpm test` 通过,且 `src/server/payments/` 中每个支付客户端和配置加密都有单元测试 | | `validate:template-boundary` | 骨架不从可编辑区导入;升级指南覆盖该流程 | | `validate:init-cli` | CLI 的项目初始化器会生成会话密钥、能续跑未完成的初始化,且不会删除云资源 | | `validate:migrations` | 两条迁移链都能在空库上重放,并得到相同的表 | | `validate:db-adapters` | 适配器注册表、绑定与服务端入口 | | `validate:sqlite-transactions` | 默认 SQLite 适配器上,异步事务回调的提交、回滚、排队与嵌套都正确 | | `validate:deploy-targets` | `deploy.config.json` 决定 Cloudflare 或 Node 构建;入口、镜像和迁移执行器与之一致 | | `validate:openspec-traceability`、`validate:openspec-consistency`、`validate:openspec-remaining-scope` | OpenSpec 记录、可追溯性与剩余范围 | | `validate:external` | 有凭据时对真实服务商做检查;`EXTERNAL_VALIDATE_STRICT=true` 时跳过即失败 | | `validate:external-readiness` | 先运行 `validate:external`,再写出就绪报告 | `pnpm openspec:validate` 也接在 `validate:all` 里,它对每个带 `tasks.md` 的活动变更运行 `openspec-cn validate`。 ## 单独运行 | 脚本 | 为什么不在 `validate:all` 里 | | ------------------------------------------------------------------ | -------------------------------------- | | `validate:all` | 整条链本身;门禁不运行它 | | `validate:gate` | 发布门禁本身 | | `validate:storage-drivers` | 会在存储桶里写入并删除真实对象,只应对你选定的存储桶有意运行。门禁同样跳过它 | | `validate:ai-channel`、`validate:auth-feedback`、`validate:external` | 没有接进 `validate:all`,但门禁会运行 | | `lint:budget` | 存量 lint 违规的递减预算;`--update` 记下一次减少 | ## 商店项目 以下校验器属于销售 Kernlift 的商店项目。由模板创建的项目里没有它们。 | 脚本 | 证明 | | ------------------------------- | ------------------------------------------ | | `validate:products` | 服务端定价、授权签发与撤销 | | `validate:module-catalog` | 模块页、定价页与首页区块由产品数据渲染 | | `validate:github-delivery` | 会员与会员价、用 GitHub 用户名激活、仓库邀请、激活后的退款规则、撤销授权 | | `validate:template-marketplace` | 模板页基于真实快照渲染 | | `validate:landing-blocks` | 首页组合、设计令牌、来自检出的计数 | | `validate:docs` | 双语导航与链接可解析;模块清单、Agent API 方法、数据表和环境变量与文档一致 | | `validate:deployment-docs` | 部署文档覆盖每个目标平台 | ## 已知失败 `scripts/validate/known-failures.json` 列出在仅由 `pnpm db:migrate` 建出的数据库上尚不能通过的校验器。这份清单只能缩短。新增条目会让 CI 失败。 | 脚本 | 原因简述 | | ------------------------------- | ----------------------- | | `validate:ai` | 需要全新数据库没有的 AI 场景、渠道与定价行 | | `validate:auth` | 断言的文案已移入词典 | | `validate:billing` | 断言一份已归档设计记录里的行 | | `validate:cms` | 需要种子内容,并断言旧的后台标记 | | `validate:credits` | 为不存在的用户写账本行;文案已迁移 | | `validate:files` | 需要种子文件夹、文件与用量行;文案已迁移 | | `validate:newsletter` | 断言的字面量已移入词典 | | `validate:openspec-consistency` | 早期归档的变更缺少后来新增的策略章节 | | `validate:users` | 需要种子用户、角色与权限 | ## 下一步 - [校验器与发布门禁](https://kernlift.dev/zh/docs/core/validators.md) 为什么每个校验器断言的是接线,而不是文件存在。 - [脚本](https://kernlift.dev/zh/docs/reference/scripts.md) 模板里其余的每个 `pnpm` 脚本。 - [升级 fork](https://kernlift.dev/zh/docs/guide/upgrading.md) 先记录通过集合,改完再对比。 - [环境变量](https://kernlift.dev/zh/docs/reference/env.md) 外部检查运行前需要什么。