insforge-backend-advisor

InsForge 后端顾问

主动审计 InsForge 项目的后端健康状况。此技能会运行 diagnose advisor 扫描，检查安全配置错误、性能回归和系统健康问题，然后为每类问题提供可直接执行的命令，以便在进行任何更改前验证并复现发现的问题。

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

何时使用此技能，而非 insforge-debug

适合使用此技能的情况……	适合使用 insforge-debug 的情况……
定期健康检查 / 上线前审计	某个具体请求刚刚返回错误或意外状态
检查安全态势（RLS、密钥、身份验证配置）	用户无法登录 / 令牌已过期 / OAuth 回调失败
主动查找慢查询、膨胀和缺失的索引	某个具体端点当前运行缓慢，且用户已贴出 URL
后端整体性能下降：CPU / 内存占用高、所有响应都很慢、连接池耗尽、锁冲突	单个请求失败或超时
没有具体症状，只问“我的后端出了什么问题？”	有具体症状，询问“这个请求为什么失败了？”

如果不确定该选哪一项：有具体错误 / URL / 状态码 → 使用 insforge-debug。笼统地要求“查找问题” → 使用此技能。

先运行扫描

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

npx @insforge/cli diagnose advisor

默认情况下，会显示最新扫描摘要和最多 50 个问题。可使用 --severity 和 --category 筛选：

# 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)
npx @insforge/cli diagnose advisor --json

每个问题对象都包含 ruleId、severity、category、title、description、affectedObject 和 recommendation。进一步检查前，先查看 affectedObject，了解问题涉及哪个表 / 策略 / 密钥 / 资源。

注意：diagnose advisor 需要登录 InsForge Platform。通过 --api-key 关联的项目无法使用此功能。

快速分类

运行扫描后，根据问题的 category；如果用户未提供具体情况，则根据用户的症状，查找对应的深入分析部分。

来源	对应问题	深入分析部分
顾问 category=security	RLS、暴露的配置、密钥	安全审计
顾问 category=performance	慢查询、索引、膨胀	性能审计
顾问 category=health	连接、锁、系统指标	系统健康审计
症状：“所有操作都很慢”、CPU / 内存占用高、所有响应都很慢	后端整体性能下降	系统健康审计
症状：“这个查询很慢”（没有某个失败 URL）	查询级性能问题	性能审计

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

---

安全审计

触发条件：顾问发现 category=security 问题，或用户提出“检查 RLS”“审计身份验证配置”“有没有密钥泄露？”等请求。

步骤

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

npx @insforge/cli diagnose advisor --category security

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

npx @insforge/cli db policies

3. 验证项目的身份验证配置是否符合预期（已启用的提供方、重定向 URL、JWT 设置）：

npx @insforge/cli metadata --json

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

npx @insforge/cli secrets list --all

5. 如果 advisor 的 ruleId 标记了暴露问题（例如，包含敏感数据的公开存储桶、用户数据表已禁用 RLS），请先确认受影响对象的实际状态，再建议更改——不要盲目应用 advisor 的建议。

收集的信息：活动的 RLS 策略、身份验证提供方和重定向 URL、密钥清单、advisor 标记的每个 affectedObject 的实际状态。

---

性能审计

触发条件：带有 category=performance 的 advisor 问题，或类似“查找慢查询”“是否缺少索引？”“我的数据库是否臃肿？”的请求。

步骤

1. 列出性能问题：

npx @insforge/cli diagnose advisor --category performance

2. 全面检查数据库性能——慢查询、索引效率、膨胀、缓存命中率、大小：

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

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

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"

4. 对照 EC2 实例指标进行交叉检查——“慢查询”报告也可能是 CPU／内存压力导致的，而非查询本身：

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

5. 如果问题与索引有关，请通过 postgres 日志检查实际索引使用情况，确认运行时是否命中了缺失的索引：

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

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

---

系统健康审计

触发条件：带有 category=health 的 advisor 问题，或类似“我的后端运行正常吗？”“有锁吗？”“连接池正常吗？”“EC2 状态正常吗？”的请求。

步骤

1. 列出健康问题：

npx @insforge/cli diagnose advisor --category health

2. 全面检查数据库健康状况——连接、锁及其他实时状态：

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

3. 获取有意义时间范围内的 EC2 实例指标（默认 1h；如需查看趋势，请扩大范围）：

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

4. 汇总错误日志，查看健康问题是否与近期错误激增相关：

npx @insforge/cli diagnose logs

5. 如果标记了连接池耗尽或锁争用，请深入检查扫描时段前后的 postgres 日志：

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

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

---

迭代工作流

问题会持续出现在 advisor 的扫描结果中，直到解决为止（问题对象包含 isResolved）。推荐的审计循环：

1. 扫描 — 运行 diagnose advisor --severity critical 获取待处理的问题集。
2. 深入排查 — 对每个问题，使用上文相应的深入检查部分，确认实时状态与 advisor 的报告一致。
3. 判断 — 只有确认问题确实存在后，才进行修复。Advisor 会指出规则违规；这些问题是否与业务相关，需要自行判断。
4. 修复 — 通过 insforge-cli 技能（npx @insforge/cli ... 命令）应用更改（RLS 编辑、索引、查询重写等）。
5. 重新扫描 — 再次运行 diagnose advisor。在下一次计划扫描中，已修复的问题应显示为 isResolved: true，或从活动问题集中移除。

应用更改后，不要重复依赖同一次扫描的结果——务必重新扫描。

---

命令速查

Advisor 扫描

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

默认 --limit 为 50。--json 会返回扫描摘要和完整的问题对象（包含 ruleId、recommendation、isResolved）。

后端深入检查

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

# EC2 instance metrics
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
npx @insforge/cli logs postgres.logs --limit 50

辅助功能

# Project metadata (auth config, tables, buckets, functions, RLS policies)
npx @insforge/cli metadata --json

# Live RLS policies
npx @insforge/cli db policies

# Ad-hoc SQL against the project
npx @insforge/cli db query "<sql>"

# Secrets inventory
npx @insforge/cli secrets list --all

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