🛡️不可违反的守卫 · 在每次改动碰到你的用户之前审查它的 CI

那个时刻 · 需求何时出现

一开始你是一个人在构建。改点东西,刷新屏幕,看到能用,就完事了。没有风险:唯一会因为出错而受苦的人就是你,在自己的机器上,两分钟就能修好。那个阶段是天堂——也是个陷阱,因为你会习惯于「只要在我屏幕上能用,那就没问题」。

那个时刻从别人开始依赖你的应用那天起就变了。第一个注册的用户。已经在付费的客户。也在动代码的同事。从那以后,你上传的每一次改动就不再只影响你自己:它可能把真实的人的应用弄崩,或者更糟,泄露他们的数据。而问题就在这里——你已经没法一个一个看完所有改动了。你向 AI 提个需求,它改了 8 个文件,你读了 2 个,批准,上传。在你没读的那 6 个里,可能就藏着灾难。

那份痛 · 它从哪来,为什么这么疼

这份痛一开始并不戏剧化。它不是黑客电影。它更像是一连串的小事故,累加起来让你付出昂贵的代价。而它们全都来自同一个地方:处于构建模式的 AI 是乐观的。它想的是让新功能跑起来,而不是这个改动可能以一千种方式弄坏别的东西。这是它的天性——当你兴奋地构建时,也是你的天性。

最昂贵的事故是密钥泄露。你让 AI 连接某个服务,为了「快点跑起来」,它把你的 API 密钥直接贴进了一个文件里。你没注意到,批准了,上传到 GitHub。那把密钥现在成了公开的。有机器人 24 小时扫描 GitHub,找的就是这种东西——它们可能几分钟内就发现它,开始花你的钱,或进入你的系统。这不是什么高深的攻击:是一个被别人的机器从地上捡走的疏忽,就像有人捡走了你没注意到掉在地上的钱包。

第二个是数据库里的漏洞。一个无心的改动,让你的某张用户表变得任何人都能访问,或创建了一个本不该有那种权限的函数。它看不见。应用照旧一模一样地运行。但你刚刚留了一扇开着的窗户,没有人会去关它,直到有人发现它——而到那时已经太晚了。

第三个是最常见也最不光鲜的:你弄坏了原本能用的东西。你修好了按钮 A,却没注意到把按钮 B 断开了。你快速测试时只碰了 A,所以没看到。用 B 的那个用户发现应用坏了。在编程里这有个名字——回归(regression)——它是日常真实痛苦的 80%。

那如果你不这么做会怎样?什么都不会……在一段时间内。这就是陷阱。它在没有守卫的情况下运转好几周,你放松了警惕,而恰恰在项目开始真正重要起来的时候——当已经有用户、有钱、有声誉悬在其中时——那个本可以用 30 秒避免的事故就来了。守卫是一份廉价的保险,防的是某个非常昂贵的日子。

7 个检查员 · 每一个查什么

守卫不是一个魔法方块:它是 7 项具体的检查,每一次改动都会自动运行。如果 7 项全部通过,你会看到一个绿色对勾,改动才能继续。如果哪怕只有 1 项失败,它就变红,改动会被卡住,直到你修好为止。就这么简单,就这么严格。我们按它们运行的顺序,一个一个来看。

1 · Gitleaks —— 你是不是不小心塞进了一把密钥? 它扫描整个改动,寻找看起来像凭证的东西:API 密钥、密码、令牌。如果发现什么闻起来像密钥,它就当场停下。它是那个把你从最昂贵事故中救出来的检查员,正因如此它在最最靠前的位置运行——甚至在安装任何东西之前,就在干净的 git 树上运行,好让那把密钥连一步都不许再往公开仓库里迈。

2 · 安全闸(Supabase advisors)—— 这个改动是不是在数据库里开了个漏洞? 它是检查员头儿,正因如此它在所有检查你代码的检查员中第一个运行。它直接问 Supabase:有没有哪张用户表少了它的锁(RLS)?有没有人创建了带危险权限的函数?有没有授予了本不该给的访问权?如果答案是有,它就拦下。这就是那个保护你用户数据、防止悄无声息疏忽的检查员。

3 · 类型检查(Type-check)—— 类型对得上吗? 在现代编程里,每份数据都有一个「类型」(这是数字,这是文本,这是日期)。这个检查员确认你没有,比方说,把文本和日期加在一起。它在应用甚至还没启动之前就抓住了一大类 bug——那些否则会在最糟的时刻当着用户的面冒出来的错误。

4 · Lint —— 代码干净吗? linter 是坏习惯检查员:声明了却从不使用的变量、死代码、已知会引发问题的写法。这不是为讲究而讲究——脏代码正是 bug 藏身的地方。linter 强制你把屋子收拾整齐,好让真正的脏东西显出来。

5 · 格式(Format)—— 格式一致吗? 让所有代码看起来一样:一样的空格、一样的引号、一样的风格。听起来像强迫症,但它是一种共同语言。当多个人(或多个 AI 会话)在没有约定格式的情况下动同一个项目时,每一次改动都会把你做的事和一堆挪动的引号、重排的缩进混在一起——你就再也分不清想法和噪音了。这个检查员一劳永逸地给所有人强加同一种方言,这样谁都不必再为此争论。

6 · 测试(Tests)—— 原本能用的现在还能用吗? 这就是那个抓回归的检查员,也就是上面的第 3 号痛。它们是自动化的测试,验证关键功能仍然给出正确的结果。你修了按钮 A;测试确认 B、C、D 仍然照常运转。这个检查员让你能放心地做大改动,因为你知道,如果你弄坏了什么,它会立刻提醒你。

7 · 构建(Build)—— 真的能编译吗? 最后一个检查员从零把应用组装起来,就像它要发布一样。因为「在你电脑上能用」是一回事,「能从头开始干净地构建出来」是另一回事。如果构建在这里、在门口失败,那也远远好过在生产环境失败、让用户盯着一片空白的屏幕。

成本 · 为什么这几乎是免费的

人们会以为企业级的守卫会花钱。不会。这个花的是 ~$0,每次检查增加大约 ~15 秒。诚实拆解:Supabase 的 advisors 是免费的。GitHub Actions(运行这些检查员的引擎)在私有仓库给你每月 2.000 分钟免费额度——而在公开仓库里是无限且免费的。一次 7 项检查只需几秒钟,所以用 2.000 分钟你每月能做几千次检查,一分钱都不用付。

仓库 · 你要复制的东西

你不用发明任何东西。整个守卫都打包在一个公开、已验证、可直接复制的仓库里。是 4 个搬进你项目的文件,外加一份西班牙语的分步安装指南。它用纯 JavaScript 写成,不依赖任何奇怪的东西。

安装协议 · 只装一次,永久生效

好处来了:你只装一次,它就永久守护你。没有日常维护,不用记得去运行它。它住在你的仓库里,每次改动时自己触发。安装是 6 个步骤,下面的主提示词会把它们贴给你的 AI,让它陪你一起做。先看完整的地图,理解将会发生什么。

// Paso 3: el script que añades a tu package.json (en la sección "scripts")
{
  "scripts": {
    "db:advisors:gate": "node scripts/supabase-advisors-gate.mjs"
  }
}

# Los 2 secrets del paso 5 se crean en GitHub, NO en el código:
# Repositorio → Settings → Secrets and variables → Actions → New secret
#
#   SUPABASE_PROJECT_REF   → el ref de tu proyecto (cambia por proyecto)
#   SUPABASE_ACCESS_TOKEN  → tu token de cuenta (el mismo para todos tus proyectos)
#
# El gate está hecho para saltarse solo (con aviso) si estos secrets faltan,
# así que nunca rompe un proyecto que aún no los tiene configurados.

主提示词 · 贴给你的 AI,让它替你安装

这是你唯一需要的提示词。你在项目里面,把它贴给你的代码代理(Claude Code、Cursor,或你用的任何一个),它会带着你走完 6 个步骤,替你调整那 3 个数据,并给你解释每一步动作。发送之前,先把 [中括号] 填上你自己的内容。

我想在这个项目里搭一个持续集成(CI)守卫,让它在每次改动到达生产环境之前先检查一遍。模板在公开仓库 github.com/MentexDev/NeuralOS-CI-Blindaje 里,它带了 7 个检查员:Gitleaks(密钥)、Supabase advisors 安全闸(它在所有检查代码的检查员中第一个运行)、类型检查、lint、格式、测试和构建。如果有 1 个失败,改动就被拦下。

我项目的背景:
- 数据库:Supabase。
- 包管理器:[npm / pnpm / yarn]。
- 我的包名(package.json 的 "name"):[名称]。

请一步一步地引导我,不需要我懂编程,并按这个顺序:

1. 把模板的 4 个文件(backend-ci.template.yml、gitleaks.toml.template、scripts/supabase-advisors-gate.mjs 和 scripts/supabase-advisors-allowlist.json)拿过来,放到它们该在的地方。工作流要放进 .github/workflows/,并且去掉 .template 后缀。

2. 在文件里找出 3 个 <<<CAMBIAR>>> 标记,把它们替换成我项目的真实数据(文件夹、路径、包名)。让我看清楚你在每一个里改了什么。

3. 往我的 package.json 里添加脚本 "db:advisors:gate": "node scripts/supabase-advisors-gate.mjs",不要删掉我已有的脚本。

4. 精确告诉我在 Supabase 的哪里找到我的 PROJECT_REF,以及我怎么生成我账户的 ACCESS_TOKEN。

5. 一步一步告诉我怎么在 GitHub 里创建那 2 个 secret(SUPABASE_PROJECT_REF 和 SUPABASE_ACCESS_TOKEN)。提醒我它们绝不能放进项目的某个文件里,只能放在 GitHub 的 Secrets 里。

6. 提醒我在 Supabase 里启用 "Leaked Password Protection"(Auth → Settings)。

最后:
- 给我用来 commit 和 push 这些文件的确切命令,并告诉我在 GitHub 的 checks 标签页里应该看到什么(7 个检查员在运行,以及哪一个先运行)。
- 如果按我项目现在的样子,某个检查员会变红(比如,我没有测试,或我的代码有类型错误),请提前告诉我,并告诉我怎么用最简单的方式诚实地把它弄成绿色,而不是关掉那个检查员。

这个习惯 · 它在你的日常里住在哪

守卫的美妙之处在于它不要求你有纪律。它不是一个你得像「喝水」或「锻炼」那样记着的习惯。一旦装好,每次你上传改动它就自己触发。你唯一的工作是看颜色:绿色,继续;红色,在往下走之前修好检查员指出的东西。

你亲身经历它的那一刻,正是你把改动上传到 GitHub 时(或者你按分支工作时打开一个「pull request」时——见并行分支那篇资源)。那时 GitHub 会自动派出 7 个检查员。几秒钟内你就有了裁决。如果你和 AI 一起工作,这里就是它那份构建者的乐观遇上一个不会激动的审计员的地方:机器冷静地检查 AI 火热地构建出来的东西。

最省事的路 · 你做什么,机器做什么

为了让「你哪里动手、哪里不动手」彻底清楚:安装你做一次(用上面的提示词,你的 AI 会陪着你)。之后,一切都是自动的。这是真实的分工。

收尾 · 一个不睡觉的守卫

用 AI 构建又快又上瘾,而这份速度恰恰是它危险的原因:你走得太快,以至于看不清上传的所有东西。守卫不会拖住你——它让你在下面有一张网的情况下快速前进。每一次改动几秒钟内经过 7 个检查员,如果哪里闻起来不对,它会在碰到哪怕一个用户之前就停下。它花零成本,搭一次,给你的是钱通常买不到的东西:安心睡觉,知道不会有坏掉的东西因为疏忽而跑到生产环境。