危险语句
幻觉可能产生缺少 WHERE 的 UPDATE / DELETE 等危险写法；是否拦截取决于启用的规则、策略与 Agent 能力配置。
v0.4.0
AI Agent 的数据库安全网关
AgentSQL（中文名：智盾）是面向 AI Agent 的数据库安全网关与 MCP Server。模型发出的 PostgreSQL / MySQL 请求在到达数据库前，经过身份认证、SQL 解析、静态与动态风险检查、四态决策与受控执行；结果按配置脱敏，并同步写入应用层审计。
AGPLv3 开源 · Go 单二进制交付（glibc / cgo 构建）· 自托管 · 无第三方遥测依赖
它不是 BI，也不是 ORM 或 Text2SQL，而是模型与数据库之间一道默认拒绝的安全闸门。
请求只在策略允许时进入执行阶段
为什么需要安全闸门
让模型的数据库访问可约束、可解释、可追溯
模型生成的 SQL 具有不确定性。AgentSQL 把身份、权限、语法、风险与执行控制放在一次请求链路里，降低以下常见风险。
越权访问
模型可能查询未授权表或列，需要在执行前按 Agent、数据源、对象与列权限做判断。
敏感数据返回
手机号、邮箱等字段可能以明文进入模型上下文，需要在结果返回前按配置做基础打码。
事后难以定责
缺少请求身份、SQL、规则命中与决策记录时，难以还原一次访问为何被放行或拒绝。
共同防线：安全网关不能替代数据库侧的最小权限、只读账号、安全视图与网络隔离。
六段链路
从身份到留痕，逐段收紧访问
QPS / 连接数限制属于入口与规则控制。
- 01
鉴权
验证 API Key，加载 Agent、数据源与策略，失败即关闭。
- 02
解析
按 PostgreSQL/MySQL 方言构建 AST，畸形 / 多语句等异常按规则拒绝。
- 03
安检
先做不触库的静态检查，静态未拒绝时才建立受控连接做只读 EXPLAIN / 元数据等动态检查。
- 04
决策
按 deny > approve > warn > allow 聚合为放行 / 告警 / 拦截 / 转人工。
- 05
执行与脱敏
仅 allow/warn 执行，限制连接、超时与结果行数，结果返回前按列打码。
- 06
留痕
allow/warn/deny/approve/error 各分支均尝试同步写入应用层审计，审计失败按设计 fail-closed。
场景 1只读查询放行
受控只读查询返回 5 行，并生成审计编号。
场景 2无 WHERE 写请求拒绝
无 WHERE 写请求最终被拒绝；命中项包括 deny 级 R002、R010、DEMO_NON_SELECT 与 approve 级 R202（R202 本身不是 deny 规则）。
场景 3敏感结果打码
手机号与邮箱按最终结果列名匹配，在返回前执行基础打码。
场景 4大结果风险告警
R005 对预估约 600 行的无 LIMIT 查询给出告警，并仅返回前 20 行。
场景 5未授权对象拒绝
查询未获授权的 internal_notes，被 R010 拒绝且未执行。
场景 6审计证据链
审计详情记录基本信息、六段时间线、SQL 原文、归一化 SQL、命中规则，并明确标记被拦语句未执行。
实时大屏
把风险变化放进可观测视图
最近风险事件经带鉴权的 SSE（/api/v1/stream）实时推送，断线降级轮询；KPI、趋势与分布支持手动与约 30 秒自动刷新；Prometheus 指标可接入现有监控。
审计与留痕
从决策列表回看完整证据链
提供应用层审计列表、组合筛选、证据链查看与 JSONL 导出，便于追溯与安全分析；PDF 合规报告在路线图中。它不是法规级 WORM，也不能阻止数据库 owner/superuser 直接改底层数据。
核心特性
面向受控数据库访问的完整路径
双 MCP 承载
支持 stdio 与 Streamable HTTP /mcp；HTTP 为无状态 JSON 响应，已验证 MCP 2025-06-18，并提供 7 个受控工具。
默认拒绝
组合 API Key、Agent 能力档位、对象/列授权与 AST 规则；异常或关键依赖失败时按设计 fail-closed。
受控读写
提供只读保护、危险 SQL 拦截、EXPLAIN 风险、超时、连接/QPS/结果行数上限与人工审批。
结果脱敏
手机号 / 邮箱按列名匹配做基础打码，并非完整 DLP；数据源口令用 32 字节密钥做 AES-256-GCM 加密存储。
控制面
默认零配置 SQLite，可选 PostgreSQL 15+；PG18 为基准。支持单库或独立元数据/审计双库及 SQLite→PG 迁移，独立审计库为可选布局而非默认。
可观测与控制台
提供 Prometheus 指标、健康/就绪探针、Grafana 面板，以及内嵌 Web 控制台。
文档 / 下载
从本地演示到 MCP 接入
按真实部署状态选择入口。文档对应源码仓库 github.com/cuipengdba/agentsql。
快速上手
用本地 Live Demo 看效果，再按默认拒绝的顺序接入自己的数据库。
使用手册
按控制台菜单了解审计、Agent、数据源、权限、规则、审批与脱敏边界。
MCP 接入指南
选择 Streamable HTTP 或 stdio，配置七个工具的调用与返回处理。
更多资料
v0.4.0 提供一键安装与 amd64 / arm64 多架构容器镜像；Live Demo 入口仅使用合成数据。
GHCR 多架构拉取（自动匹配 amd64 / arm64）
docker pull ghcr.io/cuipengdba/agentsql:v0.4.0一键安装（Linux amd64 / arm64）
curl -fsSL https://github.com/cuipengdba/agentsql/releases/latest/download/install.sh | sudo sh -s -- installv0.4.0 起提供 linux/arm64 原生 glibc 包 · x86_64 / amd64 或 aarch64 / arm64 · glibc ≥ 2.28 · systemd · 需要 sudo/root
兼容性
v0.4.0 GA 兼容矩阵
版本与协议支持以 v0.4.0 和仓库文档为准。
| 类别 | 当前支持 | 边界与说明 |
|---|---|---|
| 被防护业务库 | MySQL 8.x；PostgreSQL 14 / 15 / 16 / 17 / 18 | 按对应方言解析并执行受控检查。 |
| 元数据 / 审计控制面 | 纯 Go 嵌入式 SQLite（默认）；PostgreSQL 15+ | PG18 为开发 / Compose / CI 基准；可用 agentsqlctl migrate-sqlite-to-postgres 迁移单库或独立元数据 / 审计双库。 |
| MCP 传输 | stdio；Streamable HTTP /mcp | HTTP 使用 Bearer Agent API Key；无状态 JSON 响应；MCP 2025-06-18。 |
| 控制台实时事件 | Bearer 鉴权 SSE /api/v1/stream | 断线降级轮询。 |
| MCP 宿主 | 支持相应 transport 与协议版本的 MCP 宿主 | 不承诺所有 Claude Desktop / Cursor 版本都支持 HTTP transport。 |
| 七个 MCP 工具 | list_datasources、list_schema、explain_query、query（只读）、execute_write（受控写 / 审批）、request_approval、get_approval_result | |
| 端口 | 控制台 / HTTP 默认 7780；Live Demo 宿主映射 17880 | 均仅绑定回环。 |
| 官方原生发布包 | linux/amd64（x86_64 / amd64）与 linux/arm64（aarch64 / arm64）、glibc 2.28+、systemd | v0.4.0 起提供 linux/arm64 原生 glibc 包；不提供 musl / Alpine 或 CentOS 7 原生包。 |
| 源码 / 容器构建 | Go 1.25 源码构建；Docker / Compose | 源码构建需 cgo 与 C 编译器；GHCR 发布镜像提供 linux/amd64 与 linux/arm64 multi-arch manifest，拉取时自动匹配架构。 |
| 暂不支持（规划方向） | Oracle、SQL Server、达梦 / 金仓 / 瀚高等国产库；高可用 / 跨实例集中管控 / K8s；企业身份集成（SSO/RBAC）与法规级 WORM | 规划方向，不构成版本或交付承诺。 |
开始使用
快速开始
在 Docker 与依赖网络已就绪时通常数分钟可完成（受网络环境影响）。GHCR tag 会自动匹配 linux/amd64 或 linux/arm64；源码路径仍以仓库 README 为准。
GHCRamd64 / arm64
# Docker 自动选择当前平台镜像
docker pull ghcr.io/cuipengdba/agentsql:v0.4.0
# 推荐使用仓库 quickstart 生成凭据并启动
curl -fsSL https://raw.githubusercontent.com/cuipengdba/agentsql/main/scripts/quickstart.sh -o quickstart.sh
sh quickstart.sh --version v0.4.0默认仅绑定
127.0.0.1:7780Live Demo合成数据
# 复制演示环境样例并替换占位凭据
cp examples/docker/demo.env.example demo/demo.env
# 启动或重置演示环境
bash ./demo/reset.sh
# Windows PowerShell
.\demo\reset.ps1使用
docker-compose.demo.yml，访问 http://127.0.0.1:17880部署提示：默认仅绑定回环；不要提交
.env；SECRET 与数据库要成对备份；不要把 7780、17880 或数据库端口暴露公网。安全边界
明确能力范围，再设计纵深防御
以下限制应与数据库权限、网络策略、备份与运维控制一起评估。
- 连接范围只防护经过网关的连接，直连的 owner/superuser/DBA 不在范围内。
- 结果脱敏脱敏为结果层按列打码、非完整 DLP，不承诺任何别名 / 写法都不可绕过。
- 应用审计审计为应用层留痕、非法规级 WORM，不防高权限 DBA。
- JOIN 授权JOIN / 自连接仅做表级授权，不推断投影列归属。
- 通配权限
*/schema.*代表整表全列权限。 - 列名回溯脱敏按最终结果列名匹配，表达式 / 聚合 / CAST / UNION / 复杂 CTE / 视图重命名可能无法回溯源列。
- SQL / 事务边界PostgreSQL 的 B2 列级授权、B5 跨请求逻辑会话与计划事务均出厂默认开启；MySQL 不进入 B2 PostgreSQL 路径，且不支持 B5 跨请求事务。每个 operation 仍只允许一条顶层 SQL，并受预检计划和会话安全边界约束。
- 审批边界审批通过只是一条人工决策记录，不会自动执行原 SQL，也不是后续执行的豁免票据；获准后仍需由库外流程重新发起受控请求。
- 演示环境公网 Demo 仅只读合成数据，不接真实库。
- 规划能力HA / 集中管控 / 企业身份在规划方向。
技术路线
路线图
以下均为规划方向，不构成版本或交付承诺。
- v0.1核心网关
- v0.2实时大屏 / PostgreSQL 控制面 / 一键 Live Demo已完成阶段
- v0.3安全事件通知 / 敏感列发现 / 表.列感知脱敏已完成阶段
- v0.4.0 GA安全与交付增强当前正式版本
- 下一阶段国产与商业数据库适配
- 后续方向企业身份与审计增强SSO/RBAC、WORM 选项
- 后续方向高可用与集中管控
授权模式
开源核心与商业双授权
AgentSQL 开源核心采用 GNU AGPLv3，并保留商标权利。开源版本依据 GNU AGPLv3 提供；具体义务取决于你的修改、分发与网络服务方式。不希望承担相应开源义务，或需要面向团队 / 大规模部署的能力，可邮件咨询商业授权：87326549@qq.com。
需要闭源商用或商业授权，请邮件联系 87326549@qq.com
常见问题
FAQ
它和 MCP 是什么关系？
它本身是一个 MCP Server；MCP 是模型与外部工具 / 数据通信的标准协议。
不用 MCP，模型就不能连数据库吗？
可以，应用也可用自研 API、数据库代理或服务端托管凭据连接；AgentSQL 提供的是面向 MCP 的统一身份、策略、受控执行与审计入口，而非唯一连接方式。
它是 BI / ORM / Text2SQL 吗？
都不是；不负责自然语言生成 SQL 的业务体验，也不替代 ORM，负责安全执行与留痕。
性能如何？
静态判定在毫秒级；在内存 fake executor、20 worker / 20 万样本、剥离真实库网络与执行时间的基准中，网关 CPU 路径 P99 约 1.81 ms，该数字不是端到端查询延迟，真实延迟取决于连接、EXPLAIN、数据库执行与审计存储。
个人 / 公司能免费用吗？
按 AGPLv3 条款；通过网络对外提供服务时需遵守 AGPL 对应源码义务；闭源集成或需要企业能力请邮件咨询商业授权。
支持哪些数据库 / 客户端？
请查看上方兼容矩阵，其中列出业务库、控制面、MCP 传输、宿主与部署范围。