agent-querygate

QueryGate AI 代理与 MySQL 数据库之间的安全代理。提供基于策略的防护、审计日志记录和 REST API，以及 MCP 包装器，使 AI 代理可以安全地查询和修改 MySQL。    [](https://codecov.io/gh/anthropics/agent-querygate) --- ## 功能 - **基于策略的访问控制** -- 默认拒绝，带有每张表、每列和每个操作的规则 - **审计日志记录** -- 每个查询都记录有前后数据差异，可选的代理提供推理 - **审计审查系统** -- AI 或人工审查者可以标记审计条目，具有严重性和备注 - **代理角色** -- 执行代理运行查询，审计代理审查审计轨迹 - **MCP 集成** -- 用于 Claude 和其他 AI 代理的模型上下文协议服务器 - **REST API** -- 任何代理或客户端都可以使用标准 HTTP 端点 - **管理仪表盘** -- 具有暗黑主题的 React SPA，用于管理用户、数据库、代理和策略 - **多租户用户管理** -- 超级管理员 / 管理员 /层次结构 - **数据库凭证加密** -- 存储凭证的 AES-256-GCM 加密 - **SQL 注入预防** -- 基于 AST 的 SQL 解析，具有阻止的关键字检测 - **行限制强制执行** -- 策限制写入操作影响的行数 - **WHERE 子句 -- 强制代理在 UPDATE/DELETE 上包含 WHERE - **值验证** -- 写入值的每列规则（枚举、正则表达式模式、最小/最大值、非空），在执行前后检查 --- ## 快速入门 ### 先决条件 - Node.js 20+ - MySQL 8.0+ ### 设置 ```bash # 1. 克隆并安装依赖 git clone https://github.com/anthropics/agent-querygate.git cd agent-querygate npm install && cd frontend && npm install && cd .. # 2. 配置环境 cp .env.example .env # 编辑 .env -- 将 JWT_SECRET 和 ENCRYPTION_KEY 设置为安全的随机值 # 3. 创建管理数据库 mysql -u root -e DATABASE querygate_admin" # 4. 运行迁移 run db:migrate # 5. 启动（端口 3000）-- 提供 REST API；在，UI 来自 Vite npm run dev # 6. 在单独的，启动 Vite 前端开发服务器（端口 5173） # HMR代理 /api 和 /admin/api 调用到后端 3000 npm run dev:frontend ``` 在 **http://localhost:5173/setup** 上打开以创建初始帐户。 > 在开发中使用 **5173**，而不是 3000。端口 3000 提供最后一个 `vite build` 输出，在您开发前端时是陈旧的空的）。有关完整的开发与生产模型，请参见 [运行应用程序](#运行应用程序)。 --- ## 运行应用程序 前端是 **独立的进程**。您运行哪些您是在开发还是部署。 ### 开发 在两个运行： ```bash # 终端 后端 API（:migrate） npm run db:migrate # 仅当有待处理迁移时 npm run dev # Hono API 在 :3000，热重载 # 终端 2 -- 前端开发服务器 npm run dev:frontend # Vite 在 :5173，HMR，代理 API3000 **http://5173** 上打开。 Vite 开发服务器（5173）提供模块重载的 UI，并将每个 `/api `/admin/api` 请求转发到 3000 端口 300还* 提供一个仅限于上一次 build` 输出 --前端时始终使用 5173。 ### 生产 构建一次，然后运行单个服务器： ```npm run build # 编译后端到 dist将 SPA 构建到 frontend/dist/ npm run start # 一个服务器在 :3000，提供 REST API 和构建的 SPA ``` 在 **http://localhost:3000** 上打开。Vite 开发服务器（5173）中使用。 ### 端 | 端口 | 进程 | 何时 | |------|---------|------|| 3000 | 后端 (`npm run dev` / `npm run start`) | 开发 + 生产 API；来自 `frontend/dist` 的构建 SPA | |3 | Vite run dev:frontend 仅开发 | HMR 的 SPA `/api`，`/` -> 300--- ## 架构 ```mermaid graph TD subgraph 执行代理 EA[执行代理<br><i>Claude, 自定义</i>] EM 客户端<br><i>Claude 桌面i>] end subgraph 审计代理 AA[审计代理i>Claude,i>] AM[MCP 客户端<br><Claude 桌面版</i>] end subgraph Hono 服务器 SP[SQL 解析 PE[策略引擎<br><i>表/操作访问规则 +i>] AL日志记录器] TDB MySQL<br>数据库)] ADB[(管理>MySQL)] 管理员用户<br>React EA -- "REST API<br>POST />POST /execute" --> SP EMCP/stdio<br>mysql_query<br>mysql_execute" --> SP AA -- "REST API<br>GET /audit/*<br>POST /reviews" --> AL AM -- "MCP/stdio<br>audit_*" --> AL SP --> PE PE --> AL AL -- "" --> T AL --> ADB ADM -- 认证" --> SP %% ASCII 版本（仅 Markdown 中可见）： %% +------------------+ %% | 目标 MySQL | %% 数据库 | %% +--------+---------+ %%%% | %% | ---------------+ REST +--------+---------+ + %% | +---------------->| Hono +---->| | %% |代理 | query | | (MySQL | %% | ， | POST /execute | +------------+ | +-----------+ %% | 自定义） | | SQL 解析器 | | %% +---------------+ MCP/stdio | +------------+ | %% | MCP 客户端 +---------------->| | 策略 | | %% | （Claude | mysql_query | | 引擎 | | %% | 桌面版） | mysql_execute | +------------+ | %% +---------------+ | | 审计 | | %% | | 日志记录器 | | %% +---------------+ REST API | +------------+ | %% | 审计 +---------------->| | %% | 代理 | GET /audit/* | | %% | （Claude， | POST /reviews | | %% | 自定义） | | | %% +---------------+ MCP/stdio | | %% | MCP 客户端 +---------------->| | %% | （Claude | audit_* +--------+---------+ %% | 桌面版） | ^ %% +---------------+ | JWT 认证 %% | %% +--------+---------+ %% | 管理用户 | %% | （React SPA） | %% +------------------+ ``` --- ## 技术栈 | 层 | 技术 | |----------|------------------------------------------------------| | 后端 | Hono、zzle ORM、mysql2、node-sql-parser、Zod、JWT | | 前端 | React 19、Vite 8、shadcn/ui、Tailwind CSS v4 | | 认证 | bcryptjs（密码）、JWT）、API | | MCP | @model/sdk（stdio 传输） | | 加密 | Node 加密（AES-256-GCM） | | 测试 | Vitest | --- ## 项目结构 ``` agent-querygate/ +-- src/ | +-- # Hono 服务器入口点 | +-- config.ts # 环境配置与 Zod 验证 | +-- auth/ | | +-- api-key.ts # API 密钥生成和验证 | | +-- jwt.ts # JWT 令牌管理 | | +-- middleware.ts # 认证中间件（管理员 + 代理） | | +-- password.ts # bcrypt 密码哈希 | +-- db/ | | +-- # Dri 模式（用户、代理、策略、审计） | | +-- connection.ts # 数据库连接工厂 | | +-- migrate.ts # 迁移运行器 | +-- policy/ | | +-- engine.ts # 策略评估（默认拒绝） | | sql-parser.ts # 基于 AST 的 SQL 解析 | | +-- blocked-keywords.ts # 危险关键字检测 | +-- query/ | | +-- executor.ts #写入查询执行 | | +-- pool-manager.ts # 每个目标数据库的连接池 | | +-- snapshot.ts # 前后数据快照 | +-- audit/ | | +-- logger.ts # 审计日志写入器 | +-- mcp/ | | +-- server.ts # 包装 REST MCP 服务器 | +-- routes/ | +-- agent/ # 面向代理的端点（执行 + 审计） | | +-- admin/ # 管理仪表板端点 | +-- lib/ | +-- crypto.ts # AES-256-GCM 加密/解密 | +-- errors.ts # 类型错误类 | +-- types.ts # 共享类型定义 +-- frontend # React SPA（shadcn/ui，暗黑主题） +-- drizzle/ # 生成 SQL 文件 / # Vitest 单元测试 +-- drizzle.config.ts # Drizzle Kit 配置 +-- vitest.config.ts # Vitest 配置 ``` --- ## API 概述 ### 代理 API 所有代理端 `X-API-Key` 头部。 **执行代理** （查询/修改数据）： | 方法 | 端点 | 描述 | |--------|--------------------------------|--------------------------------------| | POST | `/api/v1/query` | 执行只读 SELECT 查询 | | POST | `/api/v1/execute` | 执行写入（INSERT/UPDATE/DELETE） | | GET | `/api/v1/tables` | 列出代理可以访问的表 | | GET | `/api/v1/tables/:name/schema` | 描述表的列 | | GET | `/api/v1/health` | 代理连接健康检查 | **审计代理** （审查审计轨迹）： | 方法 | 端点 | 描述 | |--------|--------------------------------|--------------------------------------| | GET | `/api/v1/audit/logs` |和列出审计日志 | | GET | `/api/v1/audit/logs/:id` | 获取审计日志详情与评论 | | | `/api/v1/audit/reviews` | 标记审计日志条目 | | GET | `/api/v1/audit/reviews` | 列出由审计员创建的评论 | ### 管理 API 所有管理端点都需要 JWT `Authorization: Bearer <token>` 头部（除了身份验证）。 | 方法 | 端点 | 描述 | |--------|---------------------------------|-------------------------------------| | POST | `/admin/api` | 创建初始超级管理员 | | `/admin/api/auth/setup-status` | 检查设置是否完成 | | POST | `/admin/api/auth/login` | 认证并接收 JWT | | POST | `/admin/api/auth/logout` | 使当前会话失效 | | GET | `/admin/api/auth/me` | 获取当前认证用户 | | GET | `/admin/api/users` | 列出用户 | | POST | `/admin/api/users` |（仅限管理员） | | PUT /api/users/:id` | 更新用户 | | DELETE | `/admin/api/users/:id` | 删除用户 | | GET | `/admin/api/databases` | 列出已注册的数据库 | | POST | `/admin/api/databases` | 注册目标数据库 | | GET | `/admin/api/databases/:id` | 获取单个已注册数据库 | | PUT `/admin/api/databases/:id` | 更新已注册数据库 | | DELETE | `/admin/api/databases/:id` | 删除已注册数据库 | | POST | `/admin/api/databases/:id/test-connection` | 测试与目标数据库的连接 | | GET | `/admin/api/datid/introspect` | 反射目标数据库的表/列 | | GET | `/admin/api/agents` | 列出代理（带有分配的数据库） | | POST | `/admin/api/agents` | 创建具有角色的代理（返回 API 密钥） | | GET | `/admin/api/agents/:id` | 获取单个代理 | | PUT |/api/agents/:id` | 更新代理 | | DELETE | `/admin/api/agents/:id` | 删除代理 | | POST | `/admin/api/agents/:id/regenerate-key` | 重新生成代理的 API 密钥 | | GET | `/admin/api/agents/:id/databases` | 列出代理可以访问的数据库 | | PUT | `/admin/api/agents/:id/databases` | 替换代理的完整数据库访问集（批量） | | POST | `/admin/api/agents/:id/databases/:dbId` | 授予代理访问数据库 | | DELETE | `/admin/api/agents/:id/databases/:dbId` | 撤销代理的数据库访问 | | GET | `/admin/api/agents/:agentId/databases/:dbId/policies` | 列出代理在数据库上的策略 | | POST | `/admin/api/agents/:agentId/databases/:dbId/policies` | 创建访问策略 | | PUT | `/admin/api/policies/:id` | 更新访问策略 | | DELETE | `/admin/api/policies/:id` | 删除访问策略 | | GET | `/admin/api/audit` | 查询审计日志 | | GET | `/admin/api/audit/export` | 导出审计日志 | | GET | `/admin/api/audit/:id` | 获取审计日志条目的详情 | | GET | `/admin/api/audit/:id/reviews` | 列出审计日志的评论 | | POST | `/admin/api/audit/:id/reviews` | 在审计日志上创建评论 | | GET | `/admin/api/dashboard/stats` | 仪表板统计数据 | --- ## MCP 工具 MCP 服务器包装 REST API 以与 Claude 桌面版和其他 MCP 兼容配合使用。注册的工具取决于。 **执行工具** （默认| 工具 | 描述 | |--------|----------------------------------| | `mysql_query`只读 SQL SELECT 查询 | | `mysql_execute` | 执行 SQL 语句（INSERT/UPDATE/DELETE） | | `mysql_list_tables` | 列出代理有权访问的所有表 | | `mysql_describe_table` | 获取特定表的列模式 | | `mysql_health` | 检查代理连接健康状态 | **审计工具** （当 `AQG_AGENT_ROLE=auditor` 时）： | 工具 | 描述 | |--------|----------------------------------| | `audit_list_logs` | 搜索和列出审计日志，带有筛选器 | | `audit_get_log` | 获取单个审计日志及其评论 | | `audit_create_review` | 标记审计日志条目，具有严重性和备注 | | `audit_list_reviews` | 列出由审计员创建的评论 | | `mysql_health` |连接健康状态 | ### Claude 桌面版配置 在您的 `claude_desktop_config.json` 中添加： ```json { "mcpServers": { "agent-querygate": { "command": "node", "args": ["path/to/agent-querygate/dist/mcp/server.js"], "env": { "AQG_BASE_URL": "http://localhost:3000", "AQG_API_KEY": "your-agent-api-key", "AQG_AGENT_ROLE": "executor" } } } } ``` 将 `AQG_AGENT_ROLE` 设置为 `auditor` 以适用于审计代理的 MCP 服务器。 --- ## 文档 | 指南 | 描述 | |------------------------------------------------|---------------------------------------------| | [入门](docs/getting-started.md) | 首次设置演练 | | [API 参考](docs/api-reference.md) | 完整的端点文档 | | [MCP 集成](docs/mcp-integration.md) | 通过 MCP 连接 AI 代理 | | [管理员指南](docs/admin-guide.md) | 管理用户、数据库和策略 | | [安全性](docs/security.md) | 加密、身份验证和威胁模型 | | [架构](docs/architecture.md) | 系统设计和数据流 | | [开发](docs/development.md) | 贡献和本地开发 | --- ## 环境变量 | 变量 | 描述 | 默认值 | |--------------------|----------------------------------------|------------------------| | `ADMIN_DB_HOST` | 管理数据库主机 | `localhost` | | `ADMIN_DB_PORT` | 管理数据库端口 | `3306` | | `ADMIN_DB_NAME` | 管理数据库名称 | `querygate_admin` | | `ADMIN_DB_USER` | 管理数据库用户 | `root` | | `ADMIN_DB_PASSWORD`| 管理数据库密码 | （空） | | `JWT_SECRET` | JWT 签名密钥（最小 16 个字符） | **必填** | | `ENCRYPTION_KEY` | 数据库密码加密的密钥字符串（最小 32 个字符）；SHA-256 派生到 32 字节 AES-256 密钥 | **必填** | | `PORT` | 服务器监听端口 | `3000` | | `NODE_ENV` | 环境模式 | `development` | | `ALLOWED_ORIGINS` | 用逗号分隔的 CORS 源（在生产中固定） | `http://localhost:5173` | --- ## 脚本 | 脚本 | 命令 | 描述 | |---------------------|-----------------------|------------------------------------------| | `npm run dev` | `tsx watch --env-file=.env src/index.ts` | 在开发模式下启动后端，热重载 | | `npm run dev:frontend` | `cd frontend && npm run dev` | 启动前端开发服务器（Vite） | | `npm run build` | `tsc + vite build` | 为生产环境构建后端和前端 | | `npm run start` | `node --env-file=.env dist/index.js` | 运行生产环境构建 | | `npm run test` | `vitest run` | 运行测试套件 | | `npm run test:watch` | `vitest` | 在监视模式下运行测试 | | `npm run db:generate` | `drizzle-kit generate` | 从模式生成迁移文件 | | `npm run db:migrate` | `tsx --env-file=.env src/db/migrate.ts` | 应用待处理迁移 | | `npm run db:studio` | `drizzle-kit studio` | 打开 Drizzle Studio GUI | 后端脚本通过 Node 的原生 `--env-file` 标志加载 `.env`（无 dotenv 依赖项）。前端（`dev:frontend`）不需要 `.env`：Vite 加载其自己的 `frontend/.env*` 文件，并且只会看到以 `VITE_` 开头的数值，从不泄露后端机密。 --- ## 许可证 在 [MIT 许可证](./LICENSE) 下发布。 ## 安全性 要报告漏洞，请参见 [SECURITY.md](./SECURITY.md)。请勿为安全报告开启公共问题。