SQLGuard：给你的 SQL 变更装上 AI 护盾

2026-5-13 杜世伟 Message

SQLGuard：给你的 SQL 变更装上 AI 护盾

一个开发者写给开发者的工具——让每一条上线的 SQL，都经过一双”会思考”的眼睛。

---

从一次线上事故说起

“DELETE FROM orders;”

没有 WHERE 子句，也没有 LIMIT 限制。凌晨两点，DBA 的手颤抖着盯着屏幕，数据已经清空。这条 SQL 在本地测过、Review 通过、CI 绿灯放行——但没有人注意到那个缺失的 WHERE。

类似的故事每年都在无数团队里上演。工具链里缺了一个关键环节：专门理解 SQL 语义风险的 Review 工具。

这就是 SQLGuard 诞生的原因。

---

它做什么

SQLGuard 是一个结合规则引擎与 AI 大模型的 SQL 风险检测工具，提供桌面客户端和 API 服务两种使用方式。

提交一段 SQL，它会告诉你：

• 哪里有高风险操作（P0/P1 级别）
• 为什么危险，影响范围是什么
• 如何改写更安全

不是简单的关键字扫描，而是基于 AST 语法树分析，理解你写的是什么，而不只是你写了什么字符串。

---

技术栈选型逻辑

后端：Python FastAPI + sqlglot

早期版本用正则做 SQL 检测，结果一堆误报——DROP 出现在注释里也被标记，DELETE 有子查询时 WHERE 判断失效。

换用 sqlglot 之后，SQL 被解析成 AST，规则基于语法节点判断，准确率大幅提升。sqlglot 支持 20+ 种方言（MySQL、PostgreSQL、Spark SQL 等），方言差异不再是检测盲点。

FastAPI 处理 HTTP 层，异步架构保证文件批量上传时不阻塞主线程。ZIP 包里几十个 SQL 文件并发分析，结果按文件维度聚合返回。

AI 集成：双引擎适配

规则引擎能发现已知模式，但 AI 能发现你没想到的问题——比如某个查询的隐式笛卡尔积，或者特定业务场景下 LIMIT 的必要性。

hybrid 模式：规则先跑，AI 补充分析，结果合并去重
rule 模式：纯规则，快速、可离线
ai 模式：纯 AI，适合复杂业务逻辑审查

AI 层支持 OpenAI 兼容接口（OpenAI、DeepSeek、Qwen 等云端模型）和 Ollama 本地模型，数据不出内网时选 Ollama，完整隐私保障。

客户端：Electron 桌面应用

不是又一个 Web 平台——是一个你可以装在本地、离线运行的桌面工具。后端地址可配置，团队用 Docker 部署共享后端也好，个人本地跑 Ollama 也好，客户端切换一个地址搞定。

---

一个被低估的功能：ZIP 批量分析

数据库迁移脚本动辄几十个文件，逐个粘贴到工具里不现实。

SQLGuard 支持上传 .zip 压缩包，自动遍历其中所有 .sql/.txt 文件：

• 单文件异常不中断整体分析（容错处理）
• 自动忽略 __MACOSX/ 等系统垃圾目录
• 同内容分组（content_group）：相同 SQL 的文件复用同一次 AI 分析，避免重复调用
• 目录树展示 + 分文件问题明细折叠展开
• 支持筛选：全部 / 仅失败 / 仅跳过 / 仅重复内容组

发版前把整个迁移脚本目录打包扔进去，一次出完整风险报告。

---

GitLab MR Review 集成

对于已经在用 GitLab 的团队，SQLGuard 提供了 /gitlab/mr-review 接口，直接接收 MR Diff 内容：

curl -X POST http://127.0.0.1:8000/gitlab/mr-review \
  -H "Content-Type: application/json" \
  -d '{
    "title": "feat: 用户查询优化",
    "diff": "+ SELECT * FROM users;\n+ DELETE FROM users;",
    "mode": "hybrid",
    "dialect": "mysql"
  }'

可以挂在 GitLab CI Pipeline 里，在 MR 合并前自动触发 SQL 风险扫描，有问题直接阻断合并。把 SQL Review 变成 CI 门禁，而不是靠人工记得检查。

---

导出报告：Review 过程可追溯

检测结果支持一键导出 JSON / Markdown 报告，区分简版和详细版。导出前有预览弹窗，预览内支持关键字搜索和高亮，上一处/下一处跳转，方便在发现问题后快速定位上下文。

这份报告可以直接贴进 MR 描述、需求文档或者周报——Review 过程有据可查，而不是”口头说没问题”。

---

部署很简单

个人开发者：三条命令跑起来

python3 -m venv myenv && source myenv/bin/activate
pip install -r requirements.txt
python backend/main.py

团队共享：Docker Compose 一键启动

cp .env.example .env  # 填入你的 Ollama 地址或 API Key
docker compose up -d

生产环境：Nginx 反向代理 + HTTPS + CORS 白名单，README 里有完整配置示例，包括速率限制和 IP 白名单。

---

安全性：一个工具审查别人的安全，自身不能是漏洞

SQLGuard 在设计上做了几个关键决定：

• 无硬编码凭证：所有 API Key、模型地址通过环境变量注入
• CORS 白名单：通过 ALLOWED_ORIGINS 环境变量控制，默认只允许本地回环地址
• HTTP 方法限制：API 只接受 GET/POST，拒绝其他方法
• Electron 沙箱：contextIsolation: true、sandbox: true、nodeIntegration: false，渲染进程无法直接访问 Node.js API

---

写在最后

SQLGuard 不试图替代人工 Code Review，它做的是消灭那些”本不该出现”的风险——那些在 Reviewer 注意力不集中时、在深夜赶版本时、在例行操作掩盖下溜进去的高危 SQL。

工具已经开源，本地跑 Ollama 完全免费，数据不出网。

如果你的团队有 SQL 变更上线的压力，值得试一试。

---

项目地址：github.com/dsw0214/sql-guard