排查项目问题

根据现象找到原因和修复方法:初始化清单缺项、会话密钥、生成的类型、迁移、开发环境免登录、agent、定时任务和仓库访问。

新项目里的大多数问题来自缺少某项配置,应用会报告该项未配置。先做下面三项检查,可以定位大部分原因。然后在后面的小节里找到你遇到的现象。

准备工作

  • 项目目录下的终端,以及应用运行环境的访问权限(本地是 .env,生产环境是平台上的变量)。
  • 一个管理员账号,用于需要打开 /setup 的检查。见运行管理后台。
  • 准确的报错文字,或你最后停在的页面。下面有几项修复要根据它来判断。

定位原因

  1. 以管理员身份打开 /setup。页面每次加载都读取实时配置,逐项显示已就绪或未就绪并给出原因。第一行说明当前的部署平台、数据库,以及构建是否包含 agent 服务。

  2. 在运行 pnpm dev 的终端或平台的日志中查看服务端输出。启动失败的原因和开发环境免登录的警告都打印在这里。

  3. 运行门禁。门禁运行所有预期通过的校验器,并把结果与 scripts/validate/known-failures.json 对比:

    pnpm validate:gate

某项功能提示未配置

服务商从不使用 mock。没有凭据时,功能会报告未配置。

现象原因修复
/setup 中邮件投递未就绪;验证邮件和重置邮件一直收不到没有启用的邮件服务商设置 → 邮件配置(/admin/config/email)。见发送事务邮件
点击 /pricing 上的套餐按钮后落在 /system/payment-failed,带有 reason=checkout_not_configured没有配置支付服务商/admin/config/payment。见接入支付服务商
/pricing 提示套餐尚未发布该语言下没有状态为 active 的套餐/admin/plans。见定价套餐
上传失败;/setup 中对象存储未就绪没有存储驱动/admin/config/storage。见存储文件
AI 任务无法发起;/setup 中 AI 渠道未就绪没有启用的渠道,或有渠道但没有场景路由到它们/admin/config/ai。见 AI 服务商和场景

设置页保存成功只说明值已经保存,不代表服务商接受这些值。先用该页面自带的测试操作验证,再回到 /setup。

/setup 打不开或显示缺项

  • 跳转到 /system/session-expired:你还没有登录。在 /auth/sign-in 登录。
  • 页面能打开但清单加载不出来:读取清单需要 config.read。用 pnpm db:bootstrap-super-admin 创建的账号登录,或授予该权限,见管理用户、角色与权限。
  • 必需项未就绪:必需项有四个:会话密钥、登录方式、邮件投递和定时任务。除会话密钥和定时任务外,每一项都有去配置按钮,点击后打开对应的配置页面。
  • 某一项显示的是报错信息而不是原因:对应的子系统读取失败,通常是因为表不存在。见迁移没有执行。

会话密钥缺失或被拒绝

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 或平台的密钥存储,然后重启:

node -e "console.log(crypto.randomUUID()+crypto.randomUUID())"

生产环境要用另一个密钥:kernlift deploy-target 会在 .env.production 中生成一个。

pnpm typecheck 因 Worker 类型失败

出现与 CloudflareEnv 或其他 Workers 类型有关的错误,说明 worker-configuration.d.ts 不存在。这个文件由命令生成,不提交到仓库:

pnpm cf-typegen

克隆仓库后,以及修改 wrangler.jsonc 中的绑定后都要运行这条命令。部署到 Fly.io、Railway 或 Docker 的项目没有 wrangler.jsonc。这时同一条命令根据一份参考配置生成类型,因为源码仍然引用这些类型。

如果错误提到你刚新增的路由,说明 src/routeTree.gen.ts 过期了。启动一次 pnpm dev 或运行 pnpm build 重新生成。

迁移没有执行

刚克隆、升级或安装模块之后,加载数据的页面报数据库错误,提示缺少某张表或某个列。

数据库命令
由 DATABASE_URL 指定的 SQLite 或 Postgrespnpm 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。

非开发环境下这个变量会被忽略。除此之外没有任何身份兜底。未登录的调用者会被拒绝,不会映射成默认用户。见认证与授权模型。

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 模板。

/setup 对定时任务告警

后台工作(积分过期、支付履约重试、AI 任务轮询)每分钟执行一轮,并记录每一轮的结果。以下情况定时任务会变为未就绪:从未记录过任何一轮、最近一轮距今超过五分钟,或最近一轮有任务失败(提示里会写出失败任务的名称)。

平台每一轮如何触发检查什么
CloudflareWorker 的 Cron Triggerwrangler.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 报告。新部署会在一分钟内记录第一轮,所以先等一分钟,再排查这条告警。见后台任务。

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 historiesupstream 指向的模板不是项目当初克隆的那个把 upstream 指回你克隆的仓库:git remote set-url upstream <地址>

购买、激活和退款见常见问题。

验证

修复之后,运行检查并重做之前失败的操作来确认结果。只看设置页保存成功是不够的:

pnpm typecheck
pnpm validate:gate
  • /setup 显示必需项已齐备。
  • 之前失败的操作现在能在真实服务商上完成:验证邮件能收到,沙箱结账能到达服务商页面,上传的文件能再次下载。
  • 部署之前,pnpm smoke:node(先运行 pnpm build:node)或 pnpm smoke:worker(先运行 pnpm build)会在一次性数据库上运行构建产物,检查页面、agent 的 503 响应和一轮定时任务。

下一步