Community编程与开发github.com

规模检查

对代码库进行只读的七点规模审计:循环中的索引和查询、共享读取缓存、以两个副本运行、Web 请求中的慢速工作、备份与恢复、公共与私有缓存,以及公共或付费端点的速率限制。在计划模式下使用 /scale-check 运行,可选择后跟文件夹或路由以聚焦。

规模检查 是什么?

这是一个用于 AI 代理(如 Claude Code)的计划模式技能,旨在对代码库进行只读的7点生产就绪审计。它不会更改任何文件,而是作为扫描器诊断七个关键的可扩展性问题,包括:循环中的数据库查询和索引(N+1问题)、高频共享读取的缓存、水平扩展时的状态管理、Web 请求中的慢速同步工作、数据库备份和恢复计划、公共资产与私有数据的缓存配置,以及公共或付费 API 端点的速率限制和成本控制。它扫描所有主要的代码库(Node.js、Python、Go、Ruby),通过比较模式与查询、检查循环中的 I/O 调用、评估缓存设置以及识别部署配置来完成审计。输出内容会严格限定在读取现有文件,并将发现的问题表述为“待检查的线索”,而不是确定的错误,同时会明确说明哪些配置(如云数据库的备份)可能存在于仓库之外。最终会生成一个包含记分卡和按优先级排序的修复计划的报告,优先处理“恢复”和“速率限制”等生存问题。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/eboywonder/missing-readme-skills/tree/main/scale-check

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

规模检查 — 7点生产就绪审计

您正在只读计划模式下运行 /scale-check。您的工作是根据以下7个规模问题检查代码库,并在用户屏幕上呈现一个清晰、按优先级排列的验证和修复计划。

目标范围: $ARGUMENTS(如果为空,则审计整个仓库)。


铁律(扫描前阅读)

  1. 观察,不修改: 您严格处于诊断和计划模式。不要创建、编辑或删除任何文件。不要运行数据库迁移、状态更改命令或网络请求。
  2. 发现是待检查的线索,而非事实: 静态仓库分析无法看到外部的云控制面板、CDN 规则、WAF 策略或托管数据库设置。将您发现的每个问题都表述为一个需要验证的线索,永远不要认为是确定的错误。
  3. 始终引用确切位置: 每个代码线索必须包含路径 path/to/file:line 和涉及的特定符号或查询。如果代码库中缺少某些内容,请明确报告:"在仓库中未找到——请在您的托管/云提供商处验证。"
  4. 一次修复一个,从生存问题开始: 始终按以下顺序排列最终的补救计划,从备份(问题5) 和速率限制(问题7) 开始,然后是任何通过共享缓存泄漏的私有数据(问题6),最后按通常影响增长型应用的顺序处理其余问题:索引和循环(Q1)、共享读取(Q2)、作为两个副本运行(Q3)、请求中的慢速工作(Q4)以及公共资产缓存(问题6的其余部分)。

执行工作流

阶段1:识别技术栈(快速通道)

在检查7个问题之前,快速识别项目的技术栈,以便在正确的位置查找:

  • 清单与框架: 检查 package.json、pyproject.toml、requirements.txt、go.mod、Cargo.toml 或 Gemfile。
  • 数据库与 ORM: 定位 schema.prisma、Drizzle 模式文件、TypeORM/Sequelize 模型、SQLAlchemy/Alembic 文件、Django models.py 或原始 .sql 迁移文件。
  • 入口点与路由: 定位 API 路由(app/api/、pages/api/、src/routes/、controllers/、routers/、main.py、cmd/)。
  • 基础设施与配置: 检查 Dockerfile、docker-compose.yml、vercel.json、next.config.*、fly.toml、render.yaml、nginx.conf、.github/workflows/ 以及 README.md。

阶段2:调查所有7个问题

针对下面的7个问题,分别运行有针对性的 Glob、Grep 和 Read 操作。不要跳过任何问题。


7个问题

问题1:循环中的索引与查询

  • 简要卡片形式: "搜索或列出数据的页面:相关列是否已建立索引,并且循环中是否存在任何查询?"
  • 完整诊断问题: 应用在哪里列出、过滤、排序或搜索记录,底层数据库列(WHERE、JOIN、ORDER BY、外键)是否在模式中得到了索引支持,并且是否有任何端点在循环内执行数据库或API查询(N+1问题)或在没有分页的情况下获取无界行?
  • 在哪里以及如何查找:
    • 模式与查询对比: 对比 list/search 查询(findMany、select、filter、WHERE、ILIKE、ORDER BY)与索引定义(@@index、index()、CREATE INDEX、db_index=True)。注意,Prisma/SQLAlchemy 通常不会自动为外键或排序列创建索引,除非明确声明。
    • 带 I/O 的循环: 在路由处理函数和服务函数中搜索 for (、for await、.map(async、forEach(async 或在迭代体内调用了 db.、prisma.、supabase.、session.execute 或 fetch( 的列表推导式。
    • 无界读取: 检查列表端点是否强制实施了 take / limit 上限,或者单个请求是否可以将整个表加载到内存中。
  • 仓库外部可能的情况(误报检查):
    • 可能在生产环境的 SQL 控制台中手动创建了索引,但没有提交到迁移文件中。
    • 小型查找表(例如,<50个静态角色或类别)不会因缺少索引而成为瓶颈,但对用户生成数据的 N+1 循环则会。

问题2:重复的共享读取

  • 简要卡片形式: "频繁运行且为每个用户返回相同结果的读取查询。"
  • 完整诊断问题: 哪些高流量的读取查询会为每次请求的每个访问者计算或获取完全相同的公共数据——例如登录页面信息流、产品目录、全局配置、排行榜或公共计数——而没有将结果缓存在内存、Redis/KV 或框架的数据缓存中?
  • 在哪里以及如何查找:
    • 检查公共路由、主页、布局加载器和全局中间件,这些组件在每次页面加载时都会访问主数据库,且没有使用用户特定参数(userId、sessionId、orgId)。
    • 检查公共端点上是否存在昂贵的聚合操作(COUNT(*)、SUM()、多表连接)。
    • 查找现有的缓存原语(unstable_cache、'use cache'、revalidate、Redis get/set、@lru_cache、Cache-Control: s-maxage),以查看共享读取是否已被包装。
  • 仓库外部可能的情况(误报检查):
    • 上游 CDN(Cloudflare、CloudFront、Fastly)可能已经通过控制面板页面规则在边缘缓存了完整的公共路由。

问题3:作为两个副本运行(无状态性与本地存储)

  • 简要卡片形式: "应用能否作为两个副本运行,以及什么数据存在于单个服务器的内存或其磁盘上?"
  • 完整诊断问题: 如果流量激增,您在负载均衡器后面启动了第二个服务器实例(或部署到自动伸缩的无服务器实例),由于状态存储在单个进程的 RAM 中或写入单个容器的本地文件系统,哪些功能会失效?
  • 在哪里以及如何查找:
    • 进程内内存状态: 搜索模块级别的 new Map()、new Set()、全局可变数组/对象、内存会话存储(MemoryStore)、本地速率限制计数器,或假设所有用户都命中同一个 Node/Python/Go 进程的进程内 pub/sub(EventEmitter、未桥接的 WebSocket Set)。
    • 本地磁盘依赖: 搜索本地文件写入(fs.writeFile、fs.createWriteStream、open(..., 'w')、multer.diskStorage、/tmp 或 ./uploads 存储)以及用于运行时可变数据的本地嵌入式数据库(sqlite、better-sqlite3、.db 文件)。
    • 进程内定时任务: 检查在主 Web 服务器入口点内启动的 node-cron、setInterval 或 APScheduler,如果同时运行两个实例,它们会触发重复的任务。
  • 仓库外部可能的情况(误报检查):
    • 严格用作只读缓存并带有 TTL(或像 Prisma/Stripe 这样的懒加载单例 SDK 客户端)的模块级 Map 在多个实例间是安全的。
    • 使用挂载的持久卷和粘性会话的单 VPS 应用可能有意作为单个节点运行——明确指出这种权衡,而不是说它有问题。

问题4:Web 请求中的慢速同步工作

  • 简要卡片形式: "任何导致 Web 请求执行慢速操作的地方,例如 AI 调用、发送邮件或处理文件。"
  • 完整诊断问题: 在返回响应之前,HTTP 请求在哪些地方保持用户连接以等待慢速、不可预测或繁重的工作——例如 LLM/AI 生成调用、发送事务性电子邮件、生成 PDF、调整图像/视频大小、解析大型 CSV 或链接多个第三方 webhook?
  • 在哪里以及如何查找:
    • 从请求开始到返回响应,追踪 POST/PUT 控制器、Server Actions 和 webhook 处理程序。
    • 在关键请求路径中搜索对 AI SDK(openai、@anthropic-ai、@google/genai、ai)、邮件服务商(resend、nodemailer、sendgrid、postmark)、媒体/文件处理器(sharp、ffmpeg、puppeteer、pdfkit)或外部 API 的阻塞 await 调用。
    • 检查项目是否具有后台队列或异步 worker 设置(bullmq、inngest、trigger.dev、celery、sidekiq、waitUntil),以及慢速调用是否实际使用了它或绕过了它。
  • 仓库外部可能的情况(误报检查):
    • 流式 AI 端点(streamText、SSE、分块响应)旨在保持连接打开以将令牌流式传输到客户端;仅当它们执行繁重的同步预处理/后处理或缺乏超时限制时才标记它们。

问题5:备份、副本与恢复路径

  • 简要卡片形式: "存在哪些备份或副本、位于何处、频率如何以及如何恢复。如果仓库中没有,请明确说明。"
  • 完整诊断问题: 存在哪些自动化的数据库和存储备份或副本、它们存储在哪里、运行频率如何,以及是否有已记录且经过测试的恢复流程?如果备份配置在仓库中不可见,请明确说明。
  • 在哪里以及如何查找:
    • 在基础设施文件(docker-compose.yml、Terraform .tf、Pulumi、CloudFormation、fly.toml、.github/workflows/、scripts/、Makefile、crontab)中搜索 pg_dump、mysqldump、sqlite3 .backup、wal-g、litestream、S3 备份同步或副本配置。
    • 在 README.md、CONTRIBUTING.md、docs/ 或 runbooks/ 中搜索任何提及备份计划、时间点恢复(PITR)或恢复命令的内容。
  • 问题5的强制性规则:
    • 在大多数使用托管数据库(Supabase、Neon、RDS、PlanetScale、Railway、MongoDB Atlas)的现代应用中,备份设置位于云控制面板中,而不是在 git 中。
    • 如果您在仓库中未找到备份配置和恢复说明,请明确说明: "在仓库中未找到备份配置或恢复操作手册。请在您的数据库提供商控制面板中验证是否启用了自动化备份/PITR,检查保留频率,并进行一次测试恢复以验证。"

问题6:公共资产与私有数据缓存

  • 简要卡片形式: "哪些文件对每个用户都是相同的,以及哪些文件绝不能缓存。"
  • 完整诊断问题: 对每个用户都相同的静态文件(代码包、字体、公共图片、营销页面)是否配置为在 CDN/浏览器边缘进行激进缓存,并且经过身份验证或用户特定的响应(账户数据、控制面板、账单、认证令牌)是否严格禁止存储在共享缓存中?
  • 在哪里以及如何查找:
    • 危险的缓存泄漏(P0 风险): 检查是否有返回个性化数据、会话状态或私有 JSON 的路由设置了 Cache-Control: public 或 s-maxage 而没有附带 private 或 no-store,或者框架路由缓存(export const revalidate = ...、force-static)是否意外地启用在了读取特定用户的 cookies/请求头的路由上。
    • 未缓存的静态资产: 检查 next.config.*、vercel.json、nginx.conf、Express static() 或 S3/CDN 上传辅助函数,以查看静态资产和用户上传的公共媒体是否设置了不可变或长生命周期的 Cache-Control 请求头。
  • 仓库外部可能的情况(误报检查):
    • 像 Next.js、Remix 和 Vite 这样的框架即使在仓库中没有自定义请求头,也会在部署时自动为 /_next/static 或 /assets 下的构建资产添加指纹并缓存。

问题7:公共与付费端点(速率限制与成本保护)

  • 简要卡片形式: "哪些端点是公共的或调用付费服务,以及有什么措施限制单个用户调用它们的频率?"
  • 完整诊断问题: 哪些路由可以无需身份验证即可调用(登录、注册、魔法链接、密码重置、公共搜索、联系表单、webhooks),或会触发按量计费/付费服务(LLM API、短信/OTP、邮件发送、文件存储、付费数据 API),以及代码中通过什么机制来强制实施每 IP 或每用户速率限制、请求体大小上限以及消费/令牌限制?
  • 在哪里以及如何查找:
    • 盘点高风险端点: 列出所有公共认证/表单路由以及每个调用计费外部 API 或触发大量数据库写入的端点。
    • 检查速率限制器: 搜索依赖项和中间件中是否存在速率限制库(@upstash/ratelimit、express-rate-limit、rate-limiter-flexible、slowapi、django-ratelimit、rack-attack、golang.org/x/time/rate),并验证它们是否实际挂载到了风险路由上。
    • 检查输入与消费上限: 在 AI 或文件上传端点上,检查在调用供应商之前是否强制实施了 max_tokens / maxOutputTokens、提示长度验证(例如,Zod .max())和文件大小限制。
  • 仓库外部可能的情况(误报检查):
    • 速率限制可能通过 Cloudflare WAF、AWS API Gateway、Vercel Firewall 或 Nginx 反向代理在应用仓库之外的上游强制执行。如果仓库内没有限制器,请将其标记为高优先级线索,以便在上游验证或添加中间件。

输出格式(将此计划呈现在屏幕上)

使用下方精确的章节呈现您的报告。保持语气直接、冷静和实用。

1. 技术栈与范围快照

  • 检测到的技术栈: [框架、语言、数据库/ORM、托管/基础设施提示]
  • 扫描范围: [完整仓库或特定路径]
  • 提醒: 这些发现是待验证的线索,而非确定的错误。在云控制面板中配置的基础设施(托管数据库备份、CDN 规则、WAF 速率限制)将不会出现在 git 中。

2. 7问题记分卡

#问题状态主要线索 / 观察
Q1搜索/列表索引与循环中的查询[待检查的线索] / [看起来已覆盖]一行摘要
Q2返回相同数据的频繁共享读取[待检查的线索] / [看起来已覆盖]一行摘要
Q3以两个副本运行(内存与磁盘状态)[待检查的线索] / [看起来已覆盖]一行摘要
Q4Web 请求中的慢速同步操作[待检查的线索] / [看起来已覆盖]一行摘要
Q5备份与恢复计划[待检查的线索] / [看起来已覆盖]一行摘要
Q6公共资产与私有数据缓存[待检查的线索] / [看起来已覆盖]一行摘要
Q7公共端点上的速率限制[待检查的线索] / [看起来已覆盖]一行摘要

3. 关键发现详情

列出每个标记为 [待检查的线索] 的问题的最重要的1-3个具体线索。

每个线索必须包含:

  • 文件位置: path/to/file:line
  • 符号/模式: 函数名、查询或配置键
  • 风险级别: 🔴 高 / 🟡 中 / 🔵 低
  • 情景: 解释为什么这个模式在规模下会有问题(N+1、重复工作、私有数据泄漏、账单冲击),使用代码库自己的概念。

跨所有7个问题的一个示例格式:

  • 🔴 高 | app/api/users/route.ts:42 — GET /users 使用 prisma.user.findMany() 且没有 take 子句,并且为每个用户模板在循环中调用 await getPosts(userId)(N+1)。添加带有默认 take: 50 的分页,并在 user 和 post 上使用 Prisma 的 include 优化为一个单查询。

4. 建议的修复顺序

按以下顺序列出要解决的计划,从最关键的生存问题开始,然后是中等优先级,最后是低优先级。

优先级问题行动项摘要
P0:生存Q5 — 备份• [行动项] ...
Q7 — 速率限制• [行动项] ...
Q6 — 缓存泄漏• [行动项] ...
P1:规模Q1 — 索引与循环• [行动项] ...
Q2 — 重复共享读取• [行动项] ...
P2:正确性Q3 — 两个副本• [行动项] ...
Q4 — 请求中的慢速工作• [行动项] ...
P3:优化Q6 — 资产缓存• [行动项] ...

5. (可选)关于外部依赖项的说明

如果多个线索指向可能在云控制面板中配置的基础设施(例如,Cloudflare 速率限制、托管数据库备份、CDN缓存规则),请在此总结这些观察,以便用户可以交叉检查云端设置,而不是将所有修复都放在代码更改上。


计划模式审计已完成。上面标记为 [待检查的线索] 的条目需要进行人工验证。

相关技能