排查项目问题
根据现象找到原因和修复方法:初始化清单缺项、会话密钥、生成的类型、迁移、开发环境免登录、agent、定时任务和仓库访问。
新项目里的大多数问题来自缺少某项配置,应用会报告该项未配置。先做下面三项检查,可以定位大部分原因。然后在后面的小节里找到你遇到的现象。
准备工作
- 项目目录下的终端,以及应用运行环境的访问权限(本地是
.env,生产环境是平台上的变量)。 - 一个管理员账号,用于需要打开
/setup的检查。见运行管理后台。 - 准确的报错文字,或你最后停在的页面。下面有几项修复要根据它来判断。
定位原因
-
以管理员身份打开
/setup。页面每次加载都读取实时配置,逐项显示已就绪或未就绪并给出原因。第一行说明当前的部署平台、数据库,以及构建是否包含 agent 服务。 -
在运行
pnpm dev的终端或平台的日志中查看服务端输出。启动失败的原因和开发环境免登录的警告都打印在这里。 -
运行门禁。门禁运行所有预期通过的校验器,并把结果与
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 或 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 角色获得这次更新新增的权限。
开发环境免登录不生效
只有同时满足以下两个条件,未登录的请求才会被当作指定用户:
APP_ENV=development。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 任务轮询)每分钟执行一轮,并记录每一轮的结果。以下情况定时任务会变为未就绪:从未记录过任何一轮、最近一轮距今超过五分钟,或最近一轮有任务失败(提示里会写出失败任务的名称)。
| 平台 | 每一轮如何触发 | 检查什么 |
|---|---|---|
| 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 报告。新部署会在一分钟内记录第一轮,所以先等一分钟,再排查这条告警。见后台任务。
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 <地址> |
购买、激活和退款见常见问题。
验证
修复之后,运行检查并重做之前失败的操作来确认结果。只看设置页保存成功是不够的:
pnpm typecheck
pnpm validate:gate/setup显示必需项已齐备。- 之前失败的操作现在能在真实服务商上完成:验证邮件能收到,沙箱结账能到达服务商页面,上传的文件能再次下载。
- 部署之前,
pnpm smoke:node(先运行pnpm build:node)或pnpm smoke:worker(先运行pnpm build)会在一次性数据库上运行构建产物,检查页面、agent 的 503 响应和一轮定时任务。