insforge-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InsForge Debug

InsForge 调试

Diagnose problems in InsForge projects — from frontend SDK errors to backend infrastructure issues. This skill helps you locate problems by running the right commands and surfacing logs/status. It does NOT suggest fixes; hand the diagnostic output to the developer or their agent for repair decisions.

Always use
npx @insforge/cli
— never install the CLI globally.

用于诊断InsForge项目中的各类问题，覆盖从前端SDK错误到后端基础设施故障的全范围。本技能通过运行对应命令、输出日志/状态来帮助你定位问题，不会提供修复方案；请将诊断结果交给开发人员或对应的Agent来制定修复决策。

请始终使用
npx @insforge/cli
执行命令，不要全局安装该CLI。

Quick Triage

快速分类

Match the symptom to a scenario, then follow that scenario's steps.

Symptom	Scenario
SDK returns `{ data: null, error: {...} }`	#1 SDK Error
HTTP 400 / 401 / 403 / 404 / 429 / 500	#2 HTTP Status Code
Function throws or times out	#3 Edge Function Failure
Query slow or hangs	#4 Database Slow
Login fails / token expired / RLS denied	#5 Auth Failure
Channel won't connect / messages missing	#6 Realtime Issues
High CPU/memory, all responses slow	#7 Backend Performance
`functions deploy` fails	#8 Function Deploy
`deployments deploy` fails / Vercel error	#9 Frontend Deploy

将你遇到的症状匹配到对应场景，再按照该场景的步骤操作。

症状	对应场景
SDK返回 `{ data: null, error: {...} }`	#1 SDK错误
HTTP 400 / 401 / 403 / 404 / 429 / 500	#2 HTTP状态码异常
函数抛出异常或超时	#3 Edge Function运行故障
查询缓慢或无响应	#4 数据库异常
登录失败 / 令牌过期 / RLS拒绝访问	#5 认证授权失败
通道无法连接 / 消息丢失	#6 实时通道异常
CPU/内存占用过高、所有响应缓慢	#7 后端性能下降
`functions deploy` 执行失败	#8 Edge Function部署失败
`deployments deploy` 执行失败 / Vercel报错	#9 前端部署失败

Scenario 1: SDK Returns Error Object

场景1：SDK返回错误对象

Symptoms: SDK call returns

{ data: null, error: { code, message, details } }

. PostgREST error codes like

PGRST301

PGRST204

, etc.

Steps:

Read the error object — extract
```
code
```
,
```
message
```
,
```
details
```
from the SDK response.
Check aggregated error logs to find matching backend errors:

bash

npx @insforge/cli diagnose logs

Based on the error code prefix, drill into the relevant log source:

Error pattern	Log source	Command
`PGRST*` (PostgREST)	postgREST.logs	`npx @insforge/cli logs postgREST.logs --limit 50`
Database/SQL errors	postgres.logs	`npx @insforge/cli logs postgres.logs --limit 50`
Generic 500 / server error	insforge.logs	`npx @insforge/cli logs insforge.logs --limit 50`

If the error is DB-related, check database health for additional context:

bash

npx @insforge/cli diagnose db --check connections,locks,slow-queries

Information gathered: Error code, backend log entries around the error timestamp, database health status.

症状：SDK调用返回

{ data: null, error: { code, message, details } }

，包含

PGRST301

、

PGRST204

等PostgREST错误码。

操作步骤：

读取错误对象，从SDK响应中提取
```
code
```
、
```
message
```
、
```
details
```
信息。
查看聚合错误日志，匹配对应的后端错误：

bash

npx @insforge/cli diagnose logs

根据错误码前缀，查看对应来源的日志：

错误格式	日志来源	命令
`PGRST*` (PostgREST)	postgREST.logs	`npx @insforge/cli logs postgREST.logs --limit 50`
数据库/SQL错误	postgres.logs	`npx @insforge/cli logs postgres.logs --limit 50`
通用500/服务端错误	insforge.logs	`npx @insforge/cli logs insforge.logs --limit 50`

如果错误和数据库相关，查看数据库健康状态获取更多上下文：

bash

npx @insforge/cli diagnose db --check connections,locks,slow-queries

收集到的信息：错误码、错误时间前后的后端日志条目、数据库健康状态。

Scenario 2: HTTP Status Code Anomaly

场景2：HTTP状态码异常

Symptoms: API calls return 400, 401, 403, 404, 429, or 500.

Steps:

Identify the status code from the response.
Follow the path for that status code:

Status	What to check	Command
400	Request payload/params malformed	`npx @insforge/cli logs postgREST.logs --limit 50`
401	Auth token missing or expired	`npx @insforge/cli logs insforge.logs --limit 50`
403	RLS policy or permission denied	`npx @insforge/cli logs insforge.logs --limit 50`
404	Endpoint or resource doesn't exist	`npx @insforge/cli metadata --json`
429	Too many requests	`npx @insforge/cli logs insforge.logs --limit 50`
500	Server-side error	`npx @insforge/cli diagnose logs`

For 500 errors, also check aggregate error logs across all sources:

bash

npx @insforge/cli diagnose logs

Information gathered: Status code context, relevant log entries, request/response details from logs.

症状：API调用返回400、401、403、404、429或500状态码。

操作步骤：

从响应中确认状态码。
根据状态码执行对应检查：

状态码	检查内容	命令
400	请求参数/载荷格式错误	`npx @insforge/cli logs postgREST.logs --limit 50`
401	认证令牌缺失或过期	`npx @insforge/cli logs insforge.logs --limit 50`
403	RLS策略或权限不足	`npx @insforge/cli logs insforge.logs --limit 50`
404	接口或资源不存在	`npx @insforge/cli metadata --json`
429	请求频率超限	`npx @insforge/cli logs insforge.logs --limit 50`
500	服务端错误	`npx @insforge/cli diagnose logs`

针对500错误，还需要查看全来源的聚合错误日志：

bash

npx @insforge/cli diagnose logs

收集到的信息：状态码上下文、相关日志条目、日志中记录的请求/响应详情。

Scenario 3: Edge Function Execution Failure/Timeout

场景3：Edge Function运行失败/超时

Symptoms:

functions invoke

returns error, function times out, or throws runtime exception.

Steps:

Check function execution logs:

bash

npx @insforge/cli logs function.logs --limit 50

Verify the function exists and is active:

bash

npx @insforge/cli functions list

Inspect the function source for obvious issues:

bash

npx @insforge/cli functions code <slug>

Information gathered: Function runtime errors, function status, source code, EC2 resource metrics.

症状：

functions invoke

返回错误、函数超时，或抛出运行时异常。

操作步骤：

查看函数运行日志：

bash

npx @insforge/cli logs function.logs --limit 50

确认函数存在且处于激活状态：

bash

npx @insforge/cli functions list

检查函数源码是否存在明显问题：

bash

npx @insforge/cli functions code <slug>

收集到的信息：函数运行时错误、函数状态、源码、EC2资源指标。

Scenario 4: Database Query Slow or Unresponsive

场景4：数据库查询缓慢或无响应

Symptoms: Queries take too long, hang indefinitely, or connection pool is exhausted.

Steps:

Check database health — slow queries, active connections, locks:

bash

npx @insforge/cli diagnose db --check slow-queries,connections,locks

Check postgres logs for query errors or warnings:

bash

npx @insforge/cli logs postgres.logs --limit 50

Check index usage and table bloat:

bash

npx @insforge/cli diagnose db --check index-usage,bloat,cache-hit,size

If the whole system feels slow, check EC2 instance metrics:

bash

npx @insforge/cli diagnose metrics --range 1h

Information gathered: Slow query details, connection pool state, lock contention, index efficiency, table bloat, cache hit ratio, EC2 resource usage.

症状：查询耗时过长、无限期挂起，或连接池耗尽。

操作步骤：

查看数据库健康状态：慢查询、活跃连接、锁情况：

bash

npx @insforge/cli diagnose db --check slow-queries,connections,locks

查看postgres日志中的查询错误或警告：

bash

npx @insforge/cli logs postgres.logs --limit 50

检查索引使用情况和表膨胀：

bash

npx @insforge/cli diagnose db --check index-usage,bloat,cache-hit,size

如果整个系统都运行缓慢，查看EC2实例指标：

bash

npx @insforge/cli diagnose metrics --range 1h

收集到的信息：慢查询详情、连接池状态、锁竞争情况、索引效率、表膨胀率、缓存命中率、EC2资源使用率。

Scenario 5: Authentication/Authorization Failure

场景5：认证/授权失败

Symptoms: Login fails, signup errors, token expired, OAuth callback error, RLS policy denies access.

Steps:

Check insforge.logs for auth-related errors (login failures, token issues, OAuth errors):

bash

npx @insforge/cli logs insforge.logs --limit 50

Check postgREST.logs for RLS policy violations:

bash

npx @insforge/cli logs postgREST.logs --limit 50

Verify the project's auth configuration:

bash

npx @insforge/cli metadata --json

If RLS suspected, inspect current policies:

bash

npx @insforge/cli db policies

Information gathered: Auth error details, RLS violation logs, auth configuration state, active RLS policies.

症状：登录失败、注册报错、令牌过期、OAuth回调错误、RLS策略拒绝访问。

操作步骤：

查看insforge.logs中的认证相关错误（登录失败、令牌问题、OAuth错误）：

bash

npx @insforge/cli logs insforge.logs --limit 50

查看postgREST.logs中的RLS策略违规记录：

bash

npx @insforge/cli logs postgREST.logs --limit 50`

确认项目的认证配置：

bash

npx @insforge/cli metadata --json

如果怀疑是RLS问题，查看当前生效的策略：

bash

npx @insforge/cli db policies

收集到的信息：认证错误详情、RLS违规日志、认证配置状态、生效的RLS策略。

Scenario 6: Realtime Channel Issues

场景6：实时通道异常

Symptoms: WebSocket won't connect, channel subscription fails, messages not received or lost.

Steps:

Check insforge.logs for realtime/WebSocket errors:

bash

npx @insforge/cli logs insforge.logs --limit 50

Verify the channel pattern exists and is enabled:

bash

npx @insforge/cli db query "SELECT pattern, description, enabled FROM realtime.channels"

If access is restricted, check RLS on realtime tables:

bash

npx @insforge/cli db policies

If the issue is widespread (all channels affected), check overall backend health:

bash

npx @insforge/cli diagnose

Information gathered: WebSocket error logs, channel configuration, realtime RLS policies, overall backend health.

症状：WebSocket无法连接、通道订阅失败、消息未收到或丢失。

操作步骤：

查看insforge.logs中的实时/WebSocket错误：

bash

npx @insforge/cli logs insforge.logs --limit 50

确认通道规则存在且已启用：

bash

npx @insforge/cli db query "SELECT pattern, description, enabled FROM realtime.channels"

如果有权限限制，查看实时表的RLS配置：

bash

npx @insforge/cli db policies

如果问题影响范围广（所有通道都异常），查看后端整体健康状态：

bash

npx @insforge/cli diagnose

收集到的信息：WebSocket错误日志、通道配置、实时表RLS策略、后端整体健康状态。

Scenario 7: Backend Performance Degradation

场景7：后端性能下降

Symptoms: All responses slow, high latency, intermittent failures across the board.

Steps:

Check EC2 instance metrics — CPU, memory, disk, network:

bash

npx @insforge/cli diagnose metrics --range 1h

Check database health (often the bottleneck):

bash

npx @insforge/cli diagnose db

Check aggregate error logs:

bash

npx @insforge/cli diagnose logs

Check advisor for known critical issues:

bash

npx @insforge/cli diagnose advisor --severity critical

Information gathered: CPU/memory/disk/network metrics (current and trend), database health, error log summary, advisor warnings.

症状：所有响应都缓慢、延迟高、全域间歇性故障。

操作步骤：

查看EC2实例指标：CPU、内存、磁盘、网络：

bash

npx @insforge/cli diagnose metrics --range 1h

查看数据库健康状态（通常是性能瓶颈来源）：

bash

npx @insforge/cli diagnose db

查看聚合错误日志：

bash

npx @insforge/cli diagnose logs

查看建议报告中的已知严重问题：

bash

npx @insforge/cli diagnose advisor --severity critical

收集到的信息：CPU/内存/磁盘/网络指标（当前值和趋势）、数据库健康状态、错误日志汇总、建议警告。

Scenario 8: Edge Function Deploy Failure

场景8：Edge Function部署失败

Symptoms:

functions deploy <slug>

command fails, function not appearing in the list after deploy.

Steps:

Re-run the deploy command and capture the error output:

bash

npx @insforge/cli functions deploy <slug>

Check deployment-related errors:

bash

npx @insforge/cli logs function-deploy.logs --limit 50

Verify whether the function exists in the list:

bash

npx @insforge/cli functions list

Information gathered: Deploy command error output, function deployment logs, function list status, backend error logs.

症状：

functions deploy <slug>

命令执行失败，部署后函数未出现在列表中。

操作步骤：

重新执行部署命令，捕获错误输出：

bash

npx @insforge/cli functions deploy <slug>

查看部署相关错误：

bash

npx @insforge/cli logs function-deploy.logs --limit 50

确认函数是否存在于列表中：

bash

npx @insforge/cli functions list

收集到的信息：部署命令错误输出、函数部署日志、函数列表状态、后端错误日志。

Scenario 9: Frontend (Vercel) Deploy Failure

场景9：前端（Vercel）部署失败

Symptoms:

deployments deploy

command fails, deployment status shows error, Vercel build errors.

Steps:

Check recent deployment attempts:

bash

npx @insforge/cli deployments list

Get the status and error details for the failed deployment:

bash

npx @insforge/cli deployments status <id> --json

The

--json

output includes a

metadata

object with Vercel-specific context:

target

fileCount

projectId

startedAt

envVarKeys

webhookEventType

(e.g.,

deployment.succeeded

deployment.error

), etc. This metadata captures the full deployment context and can be used for debugging or AI-assisted investigation.

Verify the local build succeeds before investigating further:

bash

npm run build

Information gathered: Deployment history, deployment metadata (Vercel context, status, webhook events), local build output, backend deployment API logs.

症状：

deployments deploy

命令执行失败、部署状态显示错误、Vercel构建报错。

操作步骤：

查看最近的部署记录：

bash

npx @insforge/cli deployments list

获取失败部署的状态和错误详情：

bash

npx @insforge/cli deployments status <id> --json

--json

输出会包含Vercel专属上下文的

metadata

对象：

target

、

fileCount

、

projectId

、

startedAt

、

envVarKeys

、

webhookEventType

（例如

deployment.succeeded

或

deployment.error

）等。该元数据包含完整的部署上下文，可用于调试或AI辅助排查。

进一步排查前先确认本地构建可以成功：

bash

npm run build

收集到的信息：部署历史、部署元数据（Vercel上下文、状态、webhook事件）、本地构建输出、后端部署API日志。

Command Quick Reference

命令快速参考

Logs

日志查询

bash

npx @insforge/cli logs <source> [--limit <n>]

Source	Description
`insforge.logs`	Main backend logs
`postgREST.logs`	PostgREST API layer logs
`postgres.logs`	PostgreSQL database logs
`function.logs`	Edge function execution logs
`function-deploy.logs`	Edge function deployment logs

Source names are case-insensitive.

bash

npx @insforge/cli logs <source> [--limit <n>]

来源	说明
`insforge.logs`	后端主日志
`postgREST.logs`	PostgREST API层日志
`postgres.logs`	PostgreSQL数据库日志
`function.logs`	Edge Function运行日志
`function-deploy.logs`	Edge Function部署日志

来源名称不区分大小写。

Diagnostics

诊断命令

bash

undefined

bash

undefined

Full health report (all checks)

完整健康报告（所有检查项）

npx @insforge/cli diagnose

EC2 instance metrics (CPU, memory, disk, network)

EC2实例指标（CPU、内存、磁盘、网络）

npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]

Advisor scan results

建议扫描结果

npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit <n>]

Database health checks

数据库健康检查

npx @insforge/cli diagnose db [--check <checks>]

checks: connections, slow-queries, bloat, size, index-usage, locks, cache-hit (default: all)

检查项: connections, slow-queries, bloat, size, index-usage, locks, cache-hit (默认检查所有项)

Aggregate error logs from all sources

全来源聚合错误日志

npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]

undefined

npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]

undefined

Supporting Commands

辅助命令

bash

undefined

bash

undefined

Project metadata (auth config, tables, buckets, functions, etc.)

项目元数据（认证配置、表、存储桶、函数等）

npx @insforge/cli metadata --json

Edge functions

Edge Function相关

npx @insforge/cli functions list npx @insforge/cli functions code <slug>

Secrets

密钥管理

npx @insforge/cli secrets list [--all] npx @insforge/cli secrets get <key> npx @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>]

Database

数据库相关

npx @insforge/cli db policies npx @insforge/cli db query "<sql>"

Deployments

部署相关

npx @insforge/cli deployments list npx @insforge/cli deployments status <id> --json

undefined

npx @insforge/cli deployments list npx @insforge/cli deployments status <id> --json

undefined