insforge-debug

InsForge 调试

通过结合后端的可观测性基础工具——日志、指标、数据库健康状况、顾问、策略、元数据、错误对象、部署状态和 AI 辅助，诊断 InsForge 项目中的问题。此技能提供：

1. 每种调试基础工具的参考资料（每种对应一个可观测性界面，位于 references/ 下）
2. 症状排查方案（如下），列出已知响应式症状和主动审计所需的基础工具调用顺序

始终使用 npx -y @insforge/cli——切勿全局安装 CLI。

最快路径：AI 辅助分诊

当用户提供了具体描述（错误消息、失败的 URL、HTTP 状态码）时，将其交给 InsForge 调试 Agent。与其他基础工具不同，它会返回建议，而不只是观察结果——采取行动前，请根据它引用的基础工具核实诊断结果。

npx -y @insforge/cli diagnose --ai "<issue description>"

参阅 references/ai-assisted.md，了解何时应优先使用此方法、何时应跳过，以及如何核实输出。

调试基础工具

每种基础工具都是一个可独立查询的可观测性界面，由不同的底层数据源提供支持。实际诊断需要组合使用多种基础工具。

所有命令均通过 npx -y @insforge/cli ... 运行。每种基础工具旁显示的 (command) 是实际的 CLI 命令——基础工具名称是概念标签，不是 CLI 子命令名称（例如，“DB health” 对应 diagnose db，而不是 diagnose db-health；“Policies” 对应 db policies，而不是 diagnose policies）。

基础工具（命令）	可查看内容	参考资料
Logs（logs <source>；跨来源汇总使用 diagnose logs）	来自 5 个后端来源（insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs）的事件时间流	references/logs.md
Metrics（diagnose metrics）	EC2 实例在 1h / 6h / 24h / 7d 时间范围内的时间序列数据（CPU / 内存 / 磁盘 / 网络）	references/metrics.md
DB health（diagnose db）	通过 7 项命名检查（connections / slow-queries / bloat / size / index-usage / locks / cache-hit）查看当前 Postgres 状态	references/db-health.md
Advisor（diagnose advisor --json）	对 3 个类别（security / performance / health）进行静态扫描所得的问题，包含 ruleId / affectedObject / recommendation	references/advisor.md
Policies（db policies）	来自 pg_policies 的有效 RLS 规则（每条命令、每种角色对应的 USING / WITH CHECK）——返回所有策略的完整转储	references/policies.md
Metadata（metadata --json）	声明式后端状态转储（身份验证配置 / 表 / 存储桶 / 函数 / AI 模型 / 实时通道）	references/metadata.md
Error objects（无命令——读取 SDK / HTTP 响应）	SDK 错误信封 + HTTP 状态——将客户端可见错误路由到相应日志来源的对照表	references/error-objects.md
Deploy state（deployments list + deployments status <id> --json + logs function-deploy.logs）	前端（Vercel）部署历史记录和每次部署的元数据，以及边缘函数部署日志	references/deploy-state.md
AI assist（diagnose --ai "<description>"）	组合使用其他基础工具的大模型 Agent——返回包含建议的诊断结果	references/ai-assisted.md

症状排查方案

每个方案都包含一系列基础工具调用步骤，并在每个步骤中用一句话说明“要查找什么”。命令语法、标志和深入解读请参阅上面的各基础工具参考资料。

配方：SDK 返回 { data: null, error: { code, message } }

1. error-objects — 读取 code/message/details。如果 code 以 PGRST* 开头，根据参考表按前缀路由。
2. logs（根据 error-objects 路由匹配的来源）— 查找错误时间戳，获取完整的后端上下文。
3. db-health（connections、locks、slow-queries）— 仅当错误表明存在数据库问题时使用（PostgREST 超时、锁冲突）。

配方：特定请求返回 HTTP 4xx/5xx 响应

1. error-objects — 使用 HTTP 状态路由表选择日志来源（每种状态都有各自的路径；429 是特殊情况）。
2. logs（该状态对应的正确来源）— 查找失败请求行和错误。
3. metrics — 仅当多个端点出现 5xx 模式时使用，以确认是否存在系统级负载问题。

配方：RLS 访问问题（写入时返回 403，或读取时结果为空）

同一个 bug，有两种表现。写入（INSERT / UPDATE / DELETE）会明确返回 403。读取（SELECT）则会静默失败，返回空数组——PostgREST 会过滤掉被拒绝的行，而不是返回 403，因此请求看起来成功，但结果行数为零。除第 1 步仅适用于 403 变体外，排查路径相同。

1. logs（postgREST.logs）— 仅适用于 403 变体：查找包含表和角色上下文的策略违规事件。空结果变体：跳过此步——静默过滤的行不会记录错误。
2. policies — 列出该表的策略；根据实际请求和所用的 JWT 声明，逐一检查 USING / WITH CHECK。
3. metadata — 验证身份验证配置（哪个声明会传入 auth.uid() / requesting_user_id()；对于 Clerk/Auth0 等第三方身份验证，提供方是否已注册为 JWT 颁发者？）。
4. db query（db query "<sql>"）— 仅适用于空结果变体：以服务角色（而非用户身份）查询，确认本应可见的行确实存在：npx -y @insforge/cli db query "SELECT id, user_id FROM <table>"。这可以区分“RLS 过滤了所有行”和“不存在匹配数据”。

配方：登录失败 / OAuth 回调错误 / 令牌过期

1. logs（insforge.logs）— 查找包含时间戳和提供方上下文的身份验证错误。
2. metadata — 验证提供方已启用，且重定向 URL 与回调 URL 完全一致（协议 + 主机 + 路径）。

配方：边缘函数运行时错误 / 超时

1. logs（function.logs）— 获取错误堆栈和执行上下文。
2. metadata — 确认该函数存在且 status: "active"。 3.（如有需要）npx -y @insforge/cli functions code <slug> — 检查源代码中是否存在明显问题。

配方：functions deploy 失败

1. deploy-state（function-deploy.logs）— 查找构建/推送错误。
2. metadata — 确认该函数是否已进入活动列表（用于检测部分部署）。

配方：deployments deploy 失败（Vercel）

1. deploy-state（deployments list + status <id> --json）— 查看 status、metadata.webhookEventType 和 envVarKeys。
2. 本地 npm run build — 在本地复现相同错误，以便更快迭代。

配方：单个查询缓慢 / 单个端点缓慢

1. logs（postgres.logs）— 查找查询文本和时间戳。
2. db-health（slow-queries、index-usage）— slow-queries 仅能捕获仍在运行的查询（>5s 快照）；检查 index-usage 是否缺少索引。查询已完成？advisor（--category performance --json）包含 pg_stat_statements 文本和平均耗时；第 1 步可获取时间戳。
3. policies — 如果该表受 RLS 控制，请确认策略没有添加隐藏联接。

方案：“内存使用率约为 80%，但没有变慢”

1. 这是预期情况——先说明这一点。 专用 Postgres 实例会将空闲内存用作共享缓冲区 和页缓存；流量很少时内存持续处于高位是正常状态，并非内存泄漏 （references/metrics.md，“内存：高位属于正常”）。
2. metrics（--range 24h）——只有内存呈上升趋势，或发生 OOM 导致进程被杀死／重启，才会改变判断。 OOM 证据位于 postgres.logs 中，表现为崩溃恢复后的记录（“terminating connection because of crash of another server process”／“automatic recovery in progress”）。
3. 如果有 OOM 证据，解决方法是增加余量：升级到付费方案并选择更大的实例规格 （dashboard → Project Settings → Compute & Disk）。在实际负载下，最小规格实例发生 OOM 很常见 且在预期之中——绝不要通过“重启来释放内存”。

方案：所有响应都很慢／CPU 或内存使用率高（正在发生的故障）

1. metrics（--range 1h）——确认系统整体承压（CPU／内存／磁盘）。
2. db-health——数据库是最常见的瓶颈；检查 connections、locks、slow-queries。
3. logs（diagnose logs 聚合结果）——检查峰值时各来源的错误模式。
4. advisor（--severity critical）——查找可能导致性能下降的已知问题。

方案：Realtime 通道无法连接／消息缺失

1. logs（insforge.logs）——检查 WebSocket 错误和订阅失败。
2. metadata——确认通道模式与客户端订阅的模式相符，并且 enabled: true。
3. policies——检查底层表上的 RLS（Realtime 会传递行变更；RLS 会限制订阅者可见的行）。

方案：429 限流

1. error-objects——确认状态码为 429。不会记录 429 的日志，也不会返回 Retry-After 标头。 不要浪费时间搜索日志。
2. metrics（--range 1h）——了解后端的整体负载情况。
3. 解决方法始终在客户端：防抖、批处理、指数退避、消除重试循环。

配方：特定 URL 上的网关超时（502 / 503 / 504）

先按 URL 所属子系统排查：

URL 模式	深入排查
/api/database/records/...	日志（postgREST.logs → postgres.logs）+ 数据库健康状况（locks、slow-queries）
/functions/<slug>	日志（function.logs）——函数可能陷入崩溃循环
/api/auth/...	日志（insforge.logs）
系统范围内出现峰值时的任何路径	指标（--range 1h）

小型实例上，不相关路径同时出现 504：优先怀疑 OOM。 数据库、身份验证和函数都受到间歇性网关超时影响，这是最小型实例上典型的内存不足特征：内核会终止 Postgres，崩溃恢复期间所有正在处理的请求都会在网关超时，而下次负载峰值到来时问题会再次发生。

快速排查：npx -y @insforge/cli diagnose incident（需要 Platform 登录）。报告完全在云端生成——基于 Prometheus 抓取历史、平台记录和出站数据库探测——因此即使实例已宕机或卡住也能正常工作，恰好适用于 diagnose logs 无法响应的情况。它会返回一个结论（oom_likely、platform_operation_in_progress、paused_or_suspended、metrics_stopped、down_unknown、no_incident_detected）以及证据和建议操作；oom_likely 表示平台端已通过下文的重启／内存相关性检查。

如果命令不可用（CLI／后端较旧，或处于 --api-key 链接模式），请通过 日志（postgres.logs）手动确认崩溃恢复后的痕迹——“terminating connection because of crash of another server process” / “automatic recovery in progress”——并确认其时间与 5xx 峰值相关：单独的恢复证据只能证明 Postgres 曾异常重启，因此必须确认时间戳吻合，才能优先判断为 OOM （references/metrics.md）。有了这些证据，解决办法是增加余量，而不是循环重试：

1. 升级实例——npx -y @insforge/cli projects upgrade-instance <type> （nano → micro → small → medium → large → xl），或前往仪表板 → Project Settings → Compute & Disk。免费套餐需先升级为付费套餐，再选择规格。调整大小会改变账单，CLI 会要求交互式确认——先征得用户同意，再通过 CLI 级别的 --yes 无人值守运行（npx -y 中的 -y 是 npm 的安装标志，并非跳过确认）。调整大小为异步操作——请轮询 projects get，直到 operation_status 清除，再宣布事件已解决。
2. 调整大小时会重启项目，这也会清除任何卡住的状态——无需单独执行面向用户的重启；单纯重启只能暂时缓解问题，下一次峰值仍会再次触发 OOM。最小规格在真实负载下出现 OOM 很常见，也属预期情况，并非 bug。

配方：上线前／主动审计

需要 Platform 登录（npx -y @insforge/cli login）。项目通过 --api-key 链接时不可用——此时请改用 db-health + policies + metadata 进行手动审计。

1. advisor——完整扫描，然后先检查 --severity critical，再检查警告。
2. advisor（--category security）——重点检查安全问题；使用 policies（RLS 覆盖情况）和 metadata（身份验证配置、公开存储桶、密钥是否存在）进行交叉验证。
3. advisor（--category performance）——使用 db-health（slow-queries、index-usage、bloat）进行交叉验证。
4. advisor（--category health）——使用 metrics（7d 内的资源趋势）进行交叉验证。
5. 修复后重新运行 advisor，并确认每个已处理的 ruleId 都为 isResolved: true。

配方：不知道从哪里开始

1. ai-assisted（diagnose --ai "<error or URL>"）——获取初步假设。
2. 验证——重新检查诊断中提到的基础信息。应优先相信基础信息的观察结果，而不是建议。

当根本原因在于 InsForge 本身

有些诊断最终发现问题出在 InsForge 本身，而非项目配置错误：平台 Bug 或回归问题、行为异常的 SDK 调用、与实际行为相矛盾的文档或技能，或缺失的功能。调试会话正是确认这些问题的好时机——趁证据还在手边，及时报告：

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<one-line summary>" \
  --detail "<what happened vs expected, minimal repro>" \
  --command "<the failing call>" \
  --error "<verbatim error from logs>" \
  --workaround "<what you did instead>"

无需登录；系统会在本地对常见的个人身份信息（PII）模式（电子邮件地址、凭据/密钥格式、公网 IP、主目录用户名）进行脱敏——这基于模式匹配，因此仍请避免包含用户数据。SDK 缺陷请使用 --component sdk --language <lang>；文档与实际情况不符时，请使用 --component docs 或 --component skills，并附上 --doc 和 --expected；发现“不支持”时，请使用 --type feature-request。之后请继续通过变通方案完成用户的任务——绝不要因为报告问题而中断，也绝不要针对用户自己的应用代码或配置问题提交反馈。完整的标志参考请见 insforge-cli 技能的“反馈”部分。