insforge-backend-advisor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InsForge Backend Advisor

InsForge 后端顾问

Proactive backend health auditing for InsForge projects. This skill drives the

diagnose advisor

scan — security misconfigurations, performance regressions, and system health issues — then pairs each issue category with hands-on commands to verify and reproduce findings before changing anything.

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

为InsForge项目提供主动式后端健康审计。此技能驱动

diagnose advisor

扫描——检测安全配置错误、性能退化和系统健康问题——然后针对每个问题类别提供实操命令，以便在进行任何更改前验证并复现发现的问题。

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

When to Use This Skill vs

insforge-debug

何时使用此技能 vs

insforge-debug

You should be here when...	You should be in `insforge-debug` when...
Doing a periodic health check / pre-launch audit	A specific request just returned an error or unexpected status
Reviewing security posture (RLS, secrets, auth config)	A user can't log in / token expired / OAuth callback failing
Looking for slow queries, bloat, missing indexes proactively	A specific endpoint is slow right now and the user pasted the URL
Backend-wide degradation: high CPU/memory, all responses slow, connection pool exhausted, locks contending	A single request failed or timed out
"What's wrong with my backend?" without a concrete symptom	"Why did THIS request fail?" with a concrete symptom

If you're not sure which side you're on: a concrete error/URL/status code →

insforge-debug

. A general "look for problems" → here.

应使用此技能的场景...	应使用 `insforge-debug` 的场景...
定期健康检查 / 预发布审计	特定请求刚返回错误或异常状态码
检查安全态势（RLS、密钥、认证配置）	用户无法登录 / 令牌过期 / OAuth回调失败
主动查找慢查询、数据膨胀、缺失索引	特定端点当前变慢，且用户已粘贴URL
后端整体性能下降：高CPU/内存占用、所有响应缓慢、连接池耗尽、锁竞争	单个请求失败或超时
“我的后端出了什么问题？”但无具体症状	“为什么这个请求失败了？”且有具体症状

如果不确定该用哪个：有具体错误/URL/状态码 → 使用

insforge-debug

；只是“查找问题” → 使用此技能。

Run a Scan First

先运行扫描

Every workflow in this skill starts from a fresh advisor scan. The scan aggregates checks across security, performance, and health categories and ranks each issue by severity.

bash

npx @insforge/cli diagnose advisor

By default the latest scan summary plus up to 50 issues is shown. Narrow with

--severity

and

--category

bash

undefined

此技能中的每个工作流都从全新的advisor扫描开始。扫描会汇总安全、性能和健康类别的检查结果，并按严重程度对每个问题排序。

bash

npx @insforge/cli diagnose advisor

默认会显示最新扫描摘要及最多50个问题。可通过

--severity

和

--category

缩小范围：

bash

undefined

Only critical issues (start here in any audit)

仅显示严重问题（任何审计都从这里开始）

npx @insforge/cli diagnose advisor --severity critical

Security category only

仅显示安全类别

npx @insforge/cli diagnose advisor --category security

JSON for full issue payload (ruleId, affectedObject, recommendation, isResolved)

返回完整问题负载的JSON格式（包含ruleId、affectedObject、recommendation、isResolved）

npx @insforge/cli diagnose advisor --json


Each issue object includes `ruleId`, `severity`, `category`, `title`, `description`, `affectedObject`, and `recommendation`. Read `affectedObject` to know which table/policy/secret/resource the issue is about before drilling in.

> **Note**: `diagnose advisor` requires InsForge Platform login. It is not available on projects linked via `--api-key`.

npx @insforge/cli diagnose advisor --json


每个问题对象包含`ruleId`、`severity`、`category`、`title`、`description`、`affectedObject`和`recommendation`。在深入排查前，请查看`affectedObject`以了解问题涉及的表/策略/密钥/资源。

> **注意**：`diagnose advisor`需要登录InsForge平台。通过`--api-key`链接的项目无法使用此功能。

Quick Triage

快速分类

Match the issue's

category

(after running a scan) or the user's symptom (if they came in cold) to a deep-dive section.

Source	Maps to	Deep-dive section
Advisor `category=security`	RLS, exposed config, secrets	Security Audit
Advisor `category=performance`	Slow queries, indexes, bloat	Performance Audit
Advisor `category=health`	Connections, locks, system metrics	System Health Audit
Symptom: "everything is slow", high CPU/memory, all responses slow	Backend-wide degradation	System Health Audit
Symptom: "this query is slow" (without a single failing URL)	Query-level performance	Performance Audit

For a mixed report or a "what should I fix first?" question, work through critical issues across all categories before warnings.

将扫描后得到的问题

category

（或用户直接反馈的症状）对应到深度排查章节。

来源	对应	深度排查章节
Advisor的 `category=security`	RLS、暴露的配置、密钥	安全审计
Advisor的 `category=performance`	慢查询、索引、数据膨胀	性能审计
Advisor的 `category=health`	连接、锁、系统指标	系统健康审计
症状：“所有请求都很慢”、高CPU/内存占用、所有响应缓慢	后端整体性能下降	系统健康审计
症状：“这个查询很慢”（无单个失败URL）	查询级性能问题	性能审计

对于混合报告或“我应该先修复什么？”的问题，请先处理所有类别中的严重问题，再处理警告。

Security Audit

安全审计

Triggers: advisor issues with

category=security

, or a request like "review RLS", "audit auth config", "any secrets exposed?".

触发条件：advisor标记

category=security

的问题，或用户请求如“检查RLS”、“审计认证配置”、“是否有密钥暴露？”。

Steps

步骤

List security issues from the latest scan:

bash

npx @insforge/cli diagnose advisor --category security

For each RLS-related issue (
```
affectedObject
```
is a table name or policy), inspect the live policies on that table:

bash

npx @insforge/cli db policies

Verify the project's auth configuration matches expectation (providers enabled, redirect URLs, JWT settings):

bash

npx @insforge/cli metadata --json

For secrets-related issues, list current secrets (names only — values are not printed unless explicitly requested) and check for ones marked
```
--reserved
```
or with expired
```
--expires
```
:

bash

npx @insforge/cli secrets list --all

If an advisor
```
ruleId
```
flags exposure (e.g., public bucket holding sensitive data, RLS disabled on a user-data table), confirm the affected object's actual state before recommending a change — do not blindly apply advisor's recommendation.

Information gathered: active RLS policies, auth providers and redirect URLs, secret inventory, ground-truth state of every

affectedObject

flagged by advisor.

列出最新扫描中的安全问题：

bash

npx @insforge/cli diagnose advisor --category security

对于每个RLS相关问题（
```
affectedObject
```
为表名或策略），检查该表上的实时策略：

bash

npx @insforge/cli db policies

验证项目的认证配置是否符合预期（启用的提供商、重定向URL、JWT设置）：

bash

npx @insforge/cli metadata --json

对于密钥相关问题，列出当前所有密钥（仅显示名称——除非明确请求，否则不会打印值），并检查标记为
```
--reserved
```
或已过期
```
--expires
```
的密钥：

bash

npx @insforge/cli secrets list --all

如果advisor的
```
ruleId
```
标记了暴露风险（例如，存储敏感数据的公共存储桶、用户数据表上RLS未启用），在推荐更改前请确认受影响对象的实际状态——不要盲目应用advisor的建议。

收集到的信息：活跃RLS策略、认证提供商和重定向URL、密钥清单、advisor标记的每个

affectedObject

的实际状态。

Performance Audit

性能审计

Triggers: advisor issues with

category=performance

, or a request like "find slow queries", "do I have missing indexes?", "is my DB bloated?".

触发条件：advisor标记

category=performance

的问题，或用户请求如“查找慢查询”、“我是否有缺失的索引？”、“我的数据库是否有数据膨胀？”。

Steps

步骤

List performance issues:

bash

npx @insforge/cli diagnose advisor --category performance

Pull the full database performance picture — slow queries, index efficiency, bloat, cache hit ratio, size:

bash

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

For a specific table flagged by
```
affectedObject
```
, inspect it directly with SQL:

bash

npx @insforge/cli db query "SELECT pg_size_pretty(pg_total_relation_size('<table>')) AS total_size, pg_size_pretty(pg_indexes_size('<table>')) AS indexes_size"

Cross-check against EC2 instance metrics — a "slow query" report can also be CPU/memory pressure, not the query itself:

bash

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

If the issue is index-related, look at actual index usage via postgres logs to see whether the missing index is being hit at runtime:

bash

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

Information gathered: slow query plans, index usage, table bloat, cache hit ratio, current EC2 resource utilization, postgres query patterns.

列出性能问题：

bash

npx @insforge/cli diagnose advisor --category performance

获取完整的数据库性能情况——慢查询、索引效率、数据膨胀、缓存命中率、大小：

bash

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

对于
```
affectedObject
```
标记的特定表，直接用SQL检查：

bash

npx @insforge/cli db query "SELECT pg_size_pretty(pg_total_relation_size('<table>')) AS total_size, pg_size_pretty(pg_indexes_size('<table>')) AS indexes_size"

与EC2实例指标交叉验证——“慢查询”报告也可能是CPU/内存压力导致，而非查询本身：

bash

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

如果问题与索引相关，通过postgres日志查看实际索引使用情况，确认缺失的索引在运行时是否被调用：

bash

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

收集到的信息：慢查询计划、索引使用情况、表数据膨胀、缓存命中率、当前EC2资源利用率、postgres查询模式。

System Health Audit

系统健康审计

Triggers: advisor issues with

category=health

, or a request like "is my backend healthy?", "any locks?", "connection pool OK?", "EC2 looking right?".

触发条件：advisor标记

category=health

的问题，或用户请求如“我的后端健康吗？”、“是否有锁？”、“连接池正常吗？”、“EC2状态正常吗？”。

Steps

步骤

List health issues:

bash

npx @insforge/cli diagnose advisor --category health

Run the full database health sweep — connections, locks, and other live state:

bash

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

Pull EC2 instance metrics over a meaningful window (default 1h; widen for trend):

bash

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

Aggregate error logs to see whether health issues correlate with recent error spikes:

bash

npx @insforge/cli diagnose logs

If connection-pool exhaustion or lock contention is flagged, drill into postgres logs around the scan time:

bash

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

Information gathered: connection pool state, lock contention, CPU/memory/disk/network metrics with trend, error log summary, postgres-level activity.

列出健康问题：

bash

npx @insforge/cli diagnose advisor --category health

运行完整的数据库健康检查——连接、锁和其他实时状态：

bash

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

获取有意义时间窗口内的EC2实例指标（默认1小时；如需趋势分析可扩大范围）：

bash

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

汇总错误日志，查看健康问题是否与近期错误峰值相关：

bash

npx @insforge/cli diagnose logs

如果标记了连接池耗尽或锁竞争，深入查看扫描时间前后的postgres日志：

bash

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

收集到的信息：连接池状态、锁竞争情况、CPU/内存/磁盘/网络指标及趋势、错误日志摘要、postgres级别的活动情况。

Iteration Workflow

迭代工作流

Advisor issues persist across scans until resolved (issue objects carry

isResolved

). The recommended audit loop:

Scan —
```
diagnose advisor --severity critical
```
to get the working set.
Drill — for each issue, use the relevant deep-dive section above to verify the live state matches advisor's report.
Decide — only proceed to a fix after you've confirmed the issue is real. Advisor surfaces rule violations; whether they're business-relevant is a judgment call.
Fix — apply the change (RLS edit, index, query rewrite, etc.) via the
```
insforge-cli
```
skill (
```
npx @insforge/cli ...
```
commands).
Re-scan — run
```
diagnose advisor
```
again. The fixed issue should appear with
```
isResolved: true
```
on the next scheduled scan, or drop off the active set.

Do not rely on the same scan twice across a fix — always re-scan after applying changes.

Advisor问题会在扫描中持续存在，直到被解决（问题对象包含

isResolved

字段）。推荐的审计循环：

扫描 —— 使用
```
diagnose advisor --severity critical
```
获取待处理问题集。
深入排查 —— 针对每个问题，使用上述相关深度排查章节验证实时状态是否与advisor报告一致。
决策 —— 仅在确认问题真实存在后再进行修复。Advisor会标记规则违规，但这些违规是否与业务相关需要判断。
修复 —— 通过
```
insforge-cli
```
技能（
```
npx @insforge/cli ...
```
命令）应用更改（编辑RLS、添加索引、重写查询等）。
重新扫描 —— 再次运行
```
diagnose advisor
```
。已修复的问题应在下次计划扫描中显示
```
isResolved: true
```
，或从活跃问题集中消失。

修复前后不要依赖同一次扫描——应用更改后务必重新扫描。

Command Quick Reference

命令速查

Advisor scan

Advisor扫描

bash

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

Default

--limit

is 50.

--json

returns scan summary + full issue objects (with

ruleId

recommendation

isResolved

bash

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

默认

--limit

为50。

--json

返回扫描摘要+完整问题对象（包含

ruleId

、

recommendation

、

isResolved

）。

Backend deep-dive

后端深度排查

bash

undefined

bash

undefined

Database health checks

数据库健康检查

npx @insforge/cli diagnose db [--check connections,slow-queries,bloat,size,index-usage,locks,cache-hit]

EC2 instance metrics

EC2实例指标

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

Aggregate error logs from all sources

汇总所有来源的错误日志

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

Postgres-level logs

Postgres级别日志

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

undefined

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

undefined

Supporting

辅助命令

bash

undefined

bash

undefined

Project metadata (auth config, tables, buckets, functions, RLS policies)

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

npx @insforge/cli metadata --json

Live RLS policies

实时RLS策略

npx @insforge/cli db policies

Ad-hoc SQL against the project

针对项目执行临时SQL

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

Secrets inventory

密钥清单

npx @insforge/cli secrets list --all


For reactive debugging (a concrete error, status code, or failing URL), switch to `insforge-debug`.

npx @insforge/cli secrets list --all


对于反应式调试（具体错误、状态码或失败URL），请切换到`insforge-debug`。