AgentSQL

生态收录：Glama

已收录于 MCP 官方 Registry，可直接在 MCP Registry 搜索 AgentSQL 接入。

AgentSQL（中文品牌名：智盾，控制台显示为「AgentSQL 智盾控制台」）是面向 AI Agent 的数据库安全网关与生产级 MCP Server：让模型发出的每条 PostgreSQL/MySQL 请求在到达数据库前，经过身份认证、SQL 解析、授权与规则评估、受控执行、结果脱敏和审计。

v0.5.1 聚焦 MCP 客户端互通、租户隔离、发布工具链与达梦/金仓真库复验。自 v0.5.0 起代码采用 Apache-2.0，历史 v0.4.0 发布物仍按其原许可使用，详见下文许可更换声明。

版本变化与验证边界见 v0.5.1 发布说明。

AI Agent → LLM / MCP Client → AgentSQL 网关 → PostgreSQL / MySQL
                                  │
                                  └─ 鉴权 · 授权 · 规则 · 审批 · 脱敏 · 审计

核心特性

• 双 MCP 承载：本机 stdio 与 Streamable HTTP /mcp，提供 7 个基础数据库工具；默认开启的 PostgreSQL B5 会话/计划事务另提供 8 个工具。
• 默认拒绝的安全链路：API Key 认证、Agent 能力档位、对象/列授权、SQL AST 规则与 fail-closed 错误处理。
• 受控读写：只读保护、危险 SQL 拦截、Explain 风险评估、超时、连接/QPS/结果行数限制和人工审批。
• 基础数据保护：列级脱敏提供四种算法——六类 mask 部分遮蔽、九类均可用的带专用密钥 HMAC hash 指纹、无需密钥且把非空值统一替换为 *** 的 block 整值阻断，以及仅用于 number / date、通过数值分桶或日期截断保留粗粒度分布且无需密钥的 range。数据源口令另由 32 字节 AGENTSQL_SECRET 加密保存。
• 可追溯运维：默认零配置 SQLite；可选 PostgreSQL 15+ 控制面（PostgreSQL 18 为基准，metadata 与 audit 可分库）；支持审计导出（面向机器的 JSONL，以及 Excel/WPS 可直接打开、带公式注入防护的中文 CSV）、审批决策闭环、Prometheus 指标与健康/就绪探针。
• 安全事件通知：按决策过滤并以 Webhook 或 Syslog 旁路外发；默认关闭、默认不含 SQL，通知失败不影响审计与 SQL 决策。
• 内嵌 Web 控制台：总览、审计、演示台、Agent、数据源、权限、规则、审批和脱敏规则管理。

生态与兼容

AgentSQL 作为数据库中立的安全网关，当前原生支持 PostgreSQL 与 MySQL。v0.5.1 的主流国产数据库指定实例与协议路径验证范围见下表。

"已实测"仅指对应版本、镜像/拓扑与用例，非数据库厂商官方认证；"适配中 / 待实测 / 待厂商环境"为进行中的工作，不代表当前版本已支持。欢迎各数据库厂商联系开展兼容性认证与合作：请通过交流群、仓库 Discussion 或邮件 [email protected] 联系我们。

**金仓 V9 绿色边界：**仅限上述 PG 模式、单实例合成表的只读受控基础闭环；实际 license 到期日未确认。V9 Oracle 模式、原生驱动、V8、多行/深度分页、JOIN、聚合/函数、复杂表达式、类型 OID、系统目录、EXPLAIN、TLS/加密、HA/故障切换、备份恢复、B2 列级授权、多角色并发及生产负载未测。显式 GRANT CREATE SESSION 被拒；会话能力经 LOGIN + CONNECT 验证。非厂商认证或生产支持承诺；详见真库验证记录。

**HighGo 绿色边界：**仅限上述 9.0.10 企业版、PG 模式、单实例合成表用例；TLS、连接池故障切换、取消/超时、EXPLAIN、扩展类型/OID、系统目录差异、B2 列级授权、parse-error 审计分支（本轮未触发）、跨版本与生产负载未测。绿色不代表厂商认证或生产支持承诺。

**崖山客户端授权与运行：**已获厂家口头授权（C 客户端再分发），仓库无书面授权文件。v0.5.1 的 Linux 发行包与 GHCR 镜像构建使用独立客户端 23.4.7.100，并校验匹配架构的 SHA-256；正式资产须通过双架构内容与运行库检查后发布。自行从源码构建时需取得同版客户端、启用 yashan 构建标签并配置 LD_LIBRARY_PATH；缺少驱动或运行库时明确失败关闭。既有真库验证限于独立客户端的参数绑定、只读 SELECT、写入拒绝及指定流水线场景，详见 YashanDB 驱动说明。

首批金仓 + 瀚高的证据边界、复现 SQL 与待厂商项见联合案例验证记录；公众号与技术群文案见社区运营口径。

5 分钟快速开始

以下三条路径都默认只在宿主机回环地址监听。自动安装器生成的是持久使用的管理员密码，不是一次性口令；远程访问请使用 SSH 本地转发，例如 ssh -L 7780:127.0.0.1:7780 user@server，不要直接向公网暴露 7780。

1. Linux 裸机一行安装（推荐）

v0.4.0 起提供 linux/amd64 与 linux/arm64 两种原生 glibc 包：uname -m 为 x86_64 / amd64 时使用 amd64 包，为 aarch64 / arm64 时使用 arm64 包。两者均要求 glibc 2.28+ 且 systemd 为 PID 1；安装器会自动选择本机架构、校验发布包外层与包内哈希，并安装为 systemd 服务。musl / Alpine 与 CentOS 7 仍不支持：

curl -fsSL https://github.com/cuipengdba/agentsql/releases/latest/download/install.sh | sudo sh -s -- install

管道和 CI 的非 TTY 输出不会显示自动生成的管理员密码；root 可在 /etc/agentsql/agentsql.env 查看。交互终端会在首次创建凭据时显示一次，也可显式加 --show-password。离线环境同时取得 tarball 与同名 .sha256 后，校验、解压并从包根安装：

以下是 v0.5.1 的 amd64 资产名示例；v0.4.0 起 arm64 主机使用同版本的 -linux-arm64 资产名。

sha256sum -c agentsql-v0.5.1-linux-amd64.tar.gz.sha256
tar -xzf agentsql-v0.5.1-linux-amd64.tar.gz
cd agentsql-v0.5.1-linux-amd64
sudo ./install.sh install

2. Docker 一行启动

脚本默认拉取 GitHub 最新稳定 Release 对应的精确 GHCR tag；该 tag 是 linux/amd64 + linux/arm64 多架构镜像，Docker 会自动匹配运行架构。脚本生成权限为 0600 的 .env，使用 agentsql-data 命名卷，并固定绑定回环地址：

curl -fsSL https://raw.githubusercontent.com/cuipengdba/agentsql/main/scripts/quickstart.sh -o quickstart.sh && sh quickstart.sh

GHCR 包必须由发布者设为 public，以上命令才能在未登录环境匿名拉取。以下 v0.5.1 精确 tag 命令可直接使用；Docker 会从 manifest list 自动选择 linux/amd64 或 linux/arm64：

docker pull ghcr.io/cuipengdba/agentsql:v0.5.1

等价的单条 docker run 如下；随机值只通过当前 shell 环境传入，不写进命令行参数：

export AGENTSQL_SECRET="$(openssl rand -base64 24)" AGENTSQL_ADMIN_USER=admin AGENTSQL_ADMIN_PASSWORD="$(openssl rand -base64 18)"
docker run -d --name agentsql --restart unless-stopped --security-opt no-new-privileges:true -p 127.0.0.1:7780:7780 -e AGENTSQL_SECRET -e AGENTSQL_ADMIN_USER -e AGENTSQL_ADMIN_PASSWORD -v agentsql-data:/var/lib/agentsql ghcr.io/cuipengdba/agentsql:v0.5.1

3. 本地 Live Demo（一条命令，无需源码）

这套自包含环境只连接合成的 PostgreSQL/MySQL 演示数据，不连接真实数据库。无需克隆源码、无需编辑配置或构建镜像，只需下载一个 compose 文件并启动：

mkdir agentsql-demo && cd agentsql-demo
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/cuipengdba/agentsql/main/deploy/quickstart/docker-compose.yml
docker compose up -d

等待约 1–2 分钟，四个容器就绪后打开 http://127.0.0.1:17880：登录页已自动填好演示账号，直接点「登录」即可。「演示台」内置 5 个真实剧本：列授权 + 脱敏、列授权缺失、对象越权、DDL 越权、写操作转人工。彻底清理：

docker compose down -v

Demo 凭据均为固定演示值、写在 compose 中，仅用于本地体验，切勿连接真实数据。完整说明见 5 分钟快速上手 与 Live Demo 指南。

其他安装方式（源码构建、离线与审计环境）

需要审计每一步、修改 Compose 配置或从源码构建时，可继续使用原有流程。Docker Compose 默认只启动 AgentSQL，元数据和审计写入命名卷 agentsql-data 中的 /var/lib/agentsql/agentsql.db：

cp examples/docker/.env.example .env
openssl rand -base64 24   # 填入 AGENTSQL_SECRET，输出恰好 32 个 ASCII 字节
openssl rand -base64 24   # 填入 AGENTSQL_ADMIN_PASSWORD
docker compose up -d --build
docker compose ps

PowerShell 可分别执行两次以下命令并填写两个变量：

$bytes = [byte[]]::new(24); $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $rng.GetBytes($bytes); [Convert]::ToBase64String($bytes); $rng.Dispose()

访问 http://127.0.0.1:7780。Compose 也只在宿主机回环地址暴露端口。需要可观测性栈时，先在环境中设置自行生成并保存的随机值，再运行：

docker compose --profile observability up -d --build

完整说明见 可观测性示例。AGENTSQL_SECRET 必须与 agentsql.db 成对备份；直接更换 SECRET 会让既有数据源口令无法解密。生产控制面可将 metadata 与 audit 分别放入独立的 PostgreSQL 15+ 数据库，完整迁移、最小权限和回滚流程见 部署指南。

源码二进制构建按 go.mod 需要 Go 1.26、cgo、C 编译器和 glibc 兼容环境；本地 make build 使用 PATH 中的 Go，须先确认版本。正式发布脚本固定 Go 1.26.8；若人工调用 Makefile 的 Docker 发布目标，须显式传 GO_VERSION=1.26.8，不能依赖其历史默认值 1.25.14。普通构建直接使用仓库已有的内嵌控制台产物，不需要 Node.js。

make build VERSION=v0.5.1
./bin/agentsqlctl init-config -o config.yaml
export AGENTSQL_SECRET="$(openssl rand -base64 24)"
export AGENTSQL_ADMIN_USER='admin'
export AGENTSQL_ADMIN_PASSWORD="$(openssl rand -base64 24)"
./bin/agentsql serve -c config.yaml

Windows PowerShell：

./bin/agentsqlctl.exe init-config -o config.yaml
$bytes = [byte[]]::new(24); $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $rng.GetBytes($bytes); $env:AGENTSQL_SECRET = [Convert]::ToBase64String($bytes); $rng.Dispose()
$env:AGENTSQL_ADMIN_USER = 'admin'
$passwordBytes = [byte[]]::new(24); $passwordRng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $passwordRng.GetBytes($passwordBytes); $env:AGENTSQL_ADMIN_PASSWORD = [Convert]::ToBase64String($passwordBytes); $passwordRng.Dispose()
./bin/agentsql.exe serve -c config.yaml

agentsqlctl check-config -c config.yaml 只校验配置，不要求凭据；agentsqlctl migrate -c config.yaml 会校验 SECRET 后执行元数据库迁移。

v0.5 审计报表支持 CSV、JSONL、纯 Go 生成的 PDF，以及包含四类载荷和逐文件 SHA-256 manifest.json 的 ZIP：

./bin/agentsqlctl audit report -c config.yaml --format archive --out audit-compliance.zip
./bin/agentsqlctl audit verify-archive --in audit-compliance.zip

归档校验只证明包内一致性，不替代数字签名、外部时间戳、WORM 或 SIEM 保留。

MCP 接入

先在控制台创建 Agent、配置数据源和授权策略，并保存只显示一次的 asql_... API Key。

stdio

{
  "mcpServers": {
    "agentsql": {
      "command": "/absolute/path/to/agentsql",
      "args": ["mcp", "--config", "/absolute/path/to/config.yaml"],
      "env": {
        "AGENTSQL_SECRET": "<YOUR_32_BYTE_SECRET>",
        "AGENTSQL_API_KEY": "<YOUR_AGENTSQL_API_KEY>"
      }
    }
  }
}

Streamable HTTP

本地端点为 http://127.0.0.1:7780/mcp；非本机部署必须在前面配置 HTTPS 反向代理。

{
  "mcpServers": {
    "agentsql-http": {
      "url": "http://127.0.0.1:7780/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_AGENTSQL_API_KEY>"
      }
    }
  }
}

网关始终提供 7 个基础 MCP 工具：list_datasources、list_schema、explain_query、query、execute_write、request_approval、get_approval_result。v0.4.0 默认开启的 PostgreSQL B5 会话/计划事务还会注册 open_session、close_session、get_session_status、begin_transaction、execute_transaction_statement、commit_transaction、rollback_transaction、get_transaction_status 8 个工具；显式关闭 mcp.sessions.enabled 后只保留基础工具。

功能矩阵

数据库兼容矩阵

v0.5.1 代码的注册表覆盖 8 大类、27 款数据库（6 款关系型 + 21 款 NoSQL / 向量）。金仓 KingbaseES V9 与瀚高 HighGo 另列为指定环境已验证的 PG 协议基础闭环，不计入 27 款；分类表共 29 行。🟢 表示解析、授权、受控执行、脱敏、审计链路已在所述范围通过；达梦、金仓与瀚高的绿色仅限所述实例和用例，不代表完整方言兼容。🔵 受控只读＝连接、元数据、只读查询子集；🔷 连接级＝ping、版本、Schema、只读预览；🟡 待验证＝等厂商环境。

NoSQL / 向量目前是连接级、低阶支持；只读预览不代表完整查询、检索或服务端安全能力。21 款注册类型、默认端口及 HBase/Couchbase 的实际连接端口边界见 NoSQL 支持范围。DM8 指定实例的只读 SELECT、列血缘、R010、审计和手机号脱敏已通过；R006、多行分页、JOIN、函数和系统目录未验证，写入未放开。Oracle 仍限于既有有界证据。YashanDB 真库流水线测试已通过 SELECT、列血缘、R010、表列定向手机号脱敏及三条测试审计；该测试的认证、策略、审计存储端口为测试夹具，HTTP/MCP、持久化审计和最小权限账号与流水线的组合未测，见 DM/Oracle 方言边界及 YashanDB 方言边界。所有实测仅基于指定容器镜像与合成用例，并非数据库厂商官方认证；协议兼容不等于安全语义相同。所有数据库请求须经 AgentSQL 网关，并使用专用最小权限账号；解析、授权或能力事实不明时一律 fail-closed。详情见 SECURITY.md。

控制面存储另计：SQLite 默认零配置，可 combined 存储；PostgreSQL 15+ 可 combined 或独立 metadata / audit 库（PG18 为基准）。使用 agentsqlctl migrate-sqlite-to-postgres 可从 SQLite 迁至单库或独立双库。

已知限制与安全边界

• 脱敏按全局列、表.列、模式.表.列三档作用域在结果层匹配：能唯一归属到物理表的顶层直接投影列按来源表/来源列精确命中；无法确定归属（JOIN 裸列、SELECT *、CTE 外层）且可能涉及受保护表的列会 fail-closed 固定阻断为 ***。对敏感列做函数/表达式包裹并改名（如 CONCAT(phone,'') AS x）、聚合、CAST、UNION、视图内部重命名仍无法溯源；该能力不是完整 DLP，防绕行还需结合只读数据库账号、列级权限、安全视图与审批。
• hash 是不可逆指纹，不是加密，也不能解密还原。它在业务数据库返回结果后计算，不下推到数据库内的 JOIN/WHERE；确定性会暴露相等关系和频率，共享同一 key 还会带来跨库关联风险。
• block 不输出原值字符、长度或等值关系，但仍保留结果集行列形状、行数、列名、是否有结果，并因空值原样返回而暴露该格为空/NULL；它不是匿名化。block 在数据库执行后处理，不减少数据库读取，也不阻止数据库侧使用原值做 WHERE/JOIN/GROUP BY，只阻止结果单元对外返回。其固定 *** 是不透明字符串，不保证数值、日期或 JSON 的 schema 兼容。
• 多表 JOIN 与自连接的授权只做表级，列级白名单不随投影列归属收紧；脱敏层则可对已用表名或别名限定的 JOIN 投影列精确归属，未限定的裸列按 fail-closed 兜底处理。
• AllowedTables 中的 * 或 schema.* 表示管理员显式授予匹配表的全部列；此时精确列白名单不再收紧。单表使用精确列白名单时，应显式列出投影列。
• PostgreSQL 的 B2 列级授权出厂默认开启；普通 schema-qualified 基表使用免扩展的 CATALOG_CLOSED_V1，原生 binder 仅用于可选增强。MySQL 不进入 B2 PostgreSQL 路径。
• B5 跨请求逻辑会话与 PostgreSQL 计划事务出厂默认开启；MySQL 跨请求事务不支持，配置 mcp.transactions.mysql: true 会拒绝启动。每个 operation 仍只允许一条顶层 SQL，并受预检计划和会话安全边界约束。

本地测试模式

AGENTSQL_INSECURE=1 永久只表示“允许公开测试凭据”：它可在本地开发/测试中放行长度正确的公开示例 SECRET 和非空弱管理员口令，但仍拒绝空 SECRET、非 32 字节 SECRET 与空管理员口令。它不会关闭认证、安全规则或 fail-closed 行为，生产环境不得设置。

文档与社区

• 五分钟快速上手
• 使用手册
• MCP 接入指南
• 敏感列发现与脱敏草稿
• Webhook / Syslog 通知外发与安全配置
• 部署、PostgreSQL 控制面、升级、备份与 systemd
• 本地 Live Demo、定期重置与公开部署安全清单
• 产品与工程规范
• 安全策略与私密漏洞报告
• 变更记录
• Issue 反馈
• 商业授权与企业版合作

请不要在公开 Issue 中提交真实密钥、口令、连接串或未修复漏洞细节；未修复漏洞请按 SECURITY.md 走私密渠道。

加入社区（微信）

交流群 #2	交流群 #3	公众号	个人微信
扫码进群	扫码进群	扫码关注	扫码加好友

交流群 #1 已超过 200 人，无法扫码加入：请先添加作者个人微信（崔鹏），备注「AgentSQL」，由群主拉你进群。
群二维码 7 天内有效；若过期请添加个人微信或关注公众号获取最新入群方式。

构建与贡献

go vet ./...
go test -race -count=1 ./...
make build VERSION=v0.5.1

pg_query_go 要求 cgo；不要使用 CGO_ENABLED=0 或 Alpine/musl 构建。提交改动前请阅读 SPEC，为行为变化补测试，并保持 tests/corpus 决策语料不被无意改写。

许可、商业授权与商标

**许可更换声明：**v0.4.0 及更早版本的既有源码、tag 和发布包保持其发布时适用的原许可，继续按原许可使用，不重打 tag、不重发资产；自 v0.5.0 起，开源版本切换为 Apache License 2.0（含 NOTICE 文件），并提供独立的 商业授权说明。Apache-2.0 允许闭源集成、SaaS 商用与再分发。需要商标使用许可、企业模块、保修或 SLA 时，请参阅商业授权说明。AgentSQL（含中文名 “智盾”）名称与 Logo 的商标权保留；可以依许可证 fork 源码，但不得以 AgentSQL / 智盾名称或 Logo 冒充官方版本对外发行。商业授权与企业版合作：[email protected] ｜ https://agentsql.cn 。

v0.5 人员认证（MFA / OIDC / LDAP）的配置、威胁边界和迁移说明见 身份认证指南。