内容
<div align="center">
# ADB-Link
**连接 AI 代理到您的数据库**
为 AI 代理设计的轻量级、高性能数据库网关 — 通过 REST API 和 MCP（模型上下文协议）提供统一的 SQL 访问、模式发现和工具编排，支持多种数据库引擎。
[](https://go.dev)
[](https://modelcontextprotocol.io)
[](LICENSE)
[]()
📚 **[文档](https://gnodux.github.io/adb-link)** | [English](README.md) | [中文](README_zh.md)
</div>
---
## 快速安装
```bash
# 一键安装
curl -fsSL https://raw.githubusercontent.com/gnodux/adb-link/main/scripts/install-adb-link.sh | bash
# 或从源代码构建（需要 Go 1.22+）
git clone https://github.com/gnodux/adb-link.git
cd adb-link
make build
```
---
## 演示
完整的流程：发现数据源、探索模式、执行查询 — 所有操作均通过 MCP 协议。
```bash
# 1. 列出可用数据源
curl -s -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "list_datasources", "arguments": {}}
}'
# => [{"name":"my-postgres","type":"postgresql","description":"生产数据库", ...}]
# 2. 列出数据源中的数据库
curl -s -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "list_databases", "arguments": {"datasource_name": "my-postgres"}}
}'
# => [{"name":"mydb","comment":"主要应用程序数据库"}, ...]
# 3. 获取模式（表和列）
curl -s -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {"name": "get_schema", "arguments": {"datasource_name": "my-postgres", "database": "mydb"}}
}'
# => {"tables":[{"name":"users","columns":[{"name":"id","type":"INT4"},{"name":"username","type":"VARCHAR"}, ...]}]}
# 4. 执行查询
curl -s -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
"jsonrpc": "2.0", "id": 5, "method": "tools/call",
"params": {
"name": "execute_query",
"arguments": {
"datasource_name": "my-postgres",
"database": "mydb",
"sql": "SELECT id, username, created_at FROM users ORDER BY created_at DESC LIMIT 10"
}
}
}'
# => {"columns":[...],"rows":[[1,"alice","2026-03-15"], ...],"row_count":3}
```
---
## 核心功能
| 功能 | 描述 |
|---------|-------------|
| **多数据库支持** | MySQL、PostgreSQL、ClickHouse、SQLite、SQL Server、Hive、Oracle、GaussDB、TiDB、Redis、MongoDB、Milvus、Elasticsearch |
| **MCP 协议** | 完整的 JSON-RPC 2.0 实现（stdio + HTTP 传输） |
| **动态工具注册** | 通过 API 或 MCP 在运行时注册/注销查询工具 |
| **动态数据源** | 在运行时注册/注销数据源，并进行连接验证 |
| **异步查询引擎** | 提交长运行查询、轮询状态、检索结果 |
| **模式发现** | 数据库、表、视图、列，包含类型和注释信息 |
| **热重载** | YAML 配置更改被检测并在几秒内应用 |
| **RBAC 权限** | 基于通配符的数据源、数据库、表、字段和工具的访问控制 |
| **连接健康检查** | 自动 ping、周期性健康检查、无法访问主机时快速失败 |
| **纯 Go 实现** | 零 CGO 依赖 — 单个静态二进制文件，可在任何地方交叉编译 |
---
## 快速开始
### 安装（一行命令）
```bash
curl -fsSL https://raw.githubusercontent.com/gnodux/adb-link/main/scripts/install-adb-link.sh | bash
```
这将安装最新版本到 `~/.adb-link/` 并在 `~/.local/bin/adb-link` 创建符号链接。
### 从源代码构建
```bash
git clone https://github.com/gnodux/adb-link.git
cd adb-link
make build
# 二进制文件：bin/adb-link
```
### 配置
配置文件默认位于 `~/.adb-link/conf/`（可通过 `ADB_LINK_CONFIG_DIR` 重写）。
```bash
# 复制示例配置文件以开始使用
mkdir -p ~/.adb-link/conf
cp conf/mcp_stdio.yaml.example ~/.adb-link/conf/mcp_stdio.yaml
# 使用数据源详细信息编辑
```
数据源配置示例：
```yaml
kind: datasource
name: my-postgres
type: postgresql
description: "生产 PostgreSQL"
connection:
host: 127.0.0.1
port: 5432
username: app_user
password: ${PG_PASSWORD} # 支持环境变量插值
default_database: mydb
options:
pool_size: 10
```
身份验证配置：
```yaml
kind: users
users:
- name: admin
api_key: "your-secret-api-key"
group: admin
- name: mcp_stdio_user
group: mcp
description: "MCP stdio 传输的默认用户"
```
### 运行
```bash
# API + MCP HTTP 在单个端口（默认 :8000）
adb-link run-all
# 仅 API
adb-link run-api
# MCP 通过 stdio（用于 IDE/代理集成）
adb-link run-mcp
```
### 验证
```bash
curl http://localhost:8000/api/health
# {"status":"ok"}
```
---
## MCP 集成
### Claude Desktop / Cursor
将以下内容添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"adb-link": {
"command": "adb-link",
"args": ["run-mcp"]
}
}
}
```
stdio 传输使用 `mcp_stdio_user` 作为默认身份。在您的 auth/permission YAML 文件中为此用户配置权限。
### HTTP 传输
对于远程或多客户端访问，请使用 HTTP 传输：
```bash
adb-link run-all # 在 /mcp 端点提供 MCP 服务
```
---
## 文档
### 架构
```
┌─────────────────────────────────────────────────────┐
│ AI 代理 / 客户端 │
└──────────┬─────────────────────────┬────────────────┘
│ REST API │ MCP（JSON-RPC）
▼ ▼
┌──────────────────────────────────────────────────────┐
│ ADB-Link 服务器 │
│ ┌──────────┐ ┌───────────┐ ┌────────────────────┐ │
│ │ 路由器 │ │ MCP │ │ 配置服务 │ │
│ │ + 认证 │ │ 服务器 │ │ （热重载/YAML） │ │
│ └─────┬────┘ └─────┬─────┘ └────────────────────┘ │
│ │ │ │
│ ┌─────▼─────────────▼───────────────────────────┐ │
│ │ 服务层 │ │
│ │ 模式 · 查询 · 异步 · 权限 · 元数据 │ │
│ └──────────────────┬────────────────────────────┘ │
│ │ │
│ ┌──────────────────▼────────────────────────────┐ │
│ │ 连接服务（连接池 + 健康检查） │ │
│ └──────────────────┬────────────────────────────┘ │
│ │ │
│ ┌──────────────────▼────────────────────────────┐ │
│ │ 方言层（每种数据库引擎的 DSN 生成器） │ │
│ └───────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
│ │ │ │
┌─────┘ ┌────┘ ┌────┘ ┌────┘
▼ ▼ ▼ ▼
MySQL PostgreSQL ClickHouse SQLite ...
```
### API 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/api/health` | 存活检查 |
| POST | `/api/datasources/list` | 列出数据源 |
| POST | `/api/datasources/detail` | 数据源详情 |
| POST | `/api/datasources/test` | 测试连接性 |
| POST | `/api/datasources/register` | 注册数据源 |
| POST | `/api/datasources/unregister` | 注销数据源 |
| POST | `/api/databases/list` | 列出数据库 |
| POST | `/api/schema/get` | 完整模式 |
| POST | `/api/schema/table` | 表信息 |
| POST | `/api/schema/view` | 视图信息 |
| POST | `/api/query/execute` | 执行 SQL |
| POST | `/api/query/explain` | 解释计划 |
| POST | `/api/async/query/submit` | 提交异步查询 |
| POST | `/api/async/query/status` | 异步查询状态 |
| POST | `/api/async/query/result` | 异步查询结果 |
| POST | `/api/async/query/cancel` | 取消异步查询 |
| GET | `/api/tools` | 列出已注册的工具 |
| POST | `/api/tool/register` | 注册工具 |
| POST | `/api/tool/unregister` | 注销工具 |
| POST | `/api/tool/{name}` | 执行工具 |
| POST | `/mcp` | MCP JSON-RPC 端点 |
### MCP 工具
所有 MCP 工具均可通过 `tools/call` 访问：
- `list_datasources` — 列出所有数据源
- `list_databases` — 列出数据源中的数据库
- `get_schema` — 获取完整模式
- `get_table_info` / `get_view_info` — 列详情
- `execute_query` — 运行 SQL/DSL
- `explain_query` — 执行计划
- `submit_async_query` — 异步查询
- `get_async_query_status` / `get_async_query_result` — 轮询异步结果
- `register_tool` / `unregister_tool` — 动态工具管理
- `register_datasource` / `unregister_datasource` — 动态数据源管理
- *任何动态注册的工具*
### 配置
所有配置均基于 YAML，位于配置目录（默认为 `~/.adb-link/conf/`）：
| 文件 | 类型 | 目的 |
| ---------------------| --------------| -------------------------------------------------------------|
| `datasource.yaml` | `datasource` | 数据库连接定义 |
| `auth.yaml` | `users` | API 密钥和用户 |
| `permission-*.yaml` | `permission` | RBAC 规则 |
| `tool-*.yaml` | `tool` | 自定义查询工具 |
| `metadata-*.yaml` | `metadata` | 列/表注释 |
| `mcp_stdio.yaml` | 混合 | MCP stdio 默认配置（身份验证 + 权限 + 数据源） |
支持通过 `${VAR_NAME}` 语法使用环境变量。配置更改会自动热重载。
### 环境变量
| 变量 | 默认值 | 描述 |
| ----------------------------| --------------------| ----------------------------|
| `ADB_LINK_CONFIG_DIR` | `~/.adb-link/conf` | 配置目录路径 |
| `ADB_LINK_API_HOST` | `0.0.0.0` | API 绑定地址 |
| `ADB_LINK_API_PORT` | `8000` | API 绑定端口 |
| `ADB_LINK_LOG_LEVEL` | `INFO` | 日志级别 |
| `ADB_LINK_LOG_DIR` | `~/.adb-link/logs` | 日志目录 |
| `ADB_LINK_RELOAD` | `true` | 启用热重载 |
| `ADB_LINK_ASYNC_QUERY_TTL` | `3600` | 异步结果 TTL（秒） |
---
## 贡献
欢迎贡献！请随意提交问题和拉取请求。
```bash
# 开发工作流
make fmt # 格式化代码
make vet # 运行测试
make test # 运行测试
make build # 构建二进制文件
```
---
## 许可证
[MIT](LICENSE)
---
<div align="center">
**如果您觉得 ADB-Link 有用，请给它一个星星！**
</div>
