1. 为什么要在 1Panel 上跑 DBHub MCP 服务器DBHub MCP 是一个把数据库能力封装成 MCP 协议接口的服务简单说就是让 Claude、Cursor 这类支持 MCP 的客户端通过标准协议去查询你的 MySQL、PostgreSQL、SQLite而不用把数据库账号密码散落在每个客户端里。它适合谁适合手里有一台自己的云服务器、想给 AI 编码工具接上真实数据源、又不想把库直接暴露到公网的人。我这次选 1Panel 来部署原因很直接它把 Docker 编排、反向代理、日志查看、环境变量管理都做成了可视化面板省掉大量手写 systemd 和 Nginx 配置的时间。但面板只是壳真正决定这套服务能不能稳定跑的是容器编排参数、DBHub 的环境变量、以及 MCP 客户端调用的统一通道配置。这里有个关键点容易被忽略MCP 服务器本身不负责模型调用它只负责把数据库操作暴露成工具。而模型侧比如 Claude Code、Cline需要走一个统一的 API 通道去访问模型。我用的方案是 TaoToken 统一通道一个 Key 覆盖多家模型MCP 客户端配置里只填一个 base_url 和 key省得每个工具单独配一遍。下面从零开始把 1Panel 编排、DBHub 配置、TaoToken 接入、连通性验证、日志排障全部走一遍。2. 前置准备TaoToken 通道与 1Panel 环境2.1 TaoToken 统一通道准备TaoToken 的定位是统一模型 API 通道官网在 https://taotoken.net API 入口是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key这个 Key 后面会同时被 MCP 客户端和验证脚本使用。操作路径进入控制台 → API Keys 页面 → 新建 Key → 复制保存。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。如果你后面要长期跑编码 Agent可以看下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 按套餐走比单次调用更划算。注意Key 只在创建时完整显示一次务必先存到密码管理器。后面所有配置里出现的sk-xxxx都替换成你自己的。2.2 1Panel 安装与基础检查服务器建议 2C4G 起步DBHub 本身不重但同时跑数据库和 MCP 服务内存别低于 2G。1Panel 安装脚本官方提供执行后按提示设置面板端口和安全入口。# 安装 1Panel以官方脚本为例具体版本以官网为准 curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o /tmp/quick_start.sh sudo bash /tmp/quick_start.sh # 安装完成后查看版本 1panel version装完后登录面板先在「应用商店」里确认 Docker 已就绪。1Panel 会自动管理 Docker 环境你不需要单独装 docker-compose面板的「容器」→「编排」功能直接支持 compose 文件。2.3 目录规划在服务器上建两个目录一个放 DBHub 配置一个放数据卷避免容器重建时数据丢失。mkdir -p /opt/dbhub/config mkdir -p /opt/dbhub/data chmod 750 /opt/dbhub3. 可复制配置1Panel 编排 DBHub MCP3.1 DBHub 环境变量设计DBHub 通过环境变量读取数据库连接信息。生产环境不要把密码写进 compose 明文用 1Panel 的「环境变量」功能或者.env文件注入。下面是一个覆盖 MySQL 和 PostgreSQL 双数据源的配置骨架。# /opt/dbhub/config/.env DBHUB_HOST0.0.0.0 DBHUB_PORT8501 DBHUB_LOG_LEVELinfo # MySQL 数据源 MYSQL_HOST172.17.0.1 MYSQL_PORT3306 MYSQL_USERdbhub_ro MYSQL_PASSWORDyour_mysql_password MYSQL_DATABASEapp_prod # PostgreSQL 数据源 PG_HOST172.17.0.1 PG_PORT5432 PG_USERdbhub_ro PG_PASSWORDyour_pg_password PG_DATABASEanalytics # 只读保护生产环境强烈建议开启 DBHUB_READ_ONLYtrue DBHUB_MAX_ROWS1000这里172.17.0.1是 Docker 默认网桥的宿主机地址如果你的数据库跑在宿主机上用这个地址容器才能访问到。如果数据库本身也在 Docker 里改成对应容器名或自定义网络别名。3.2 1Panel 编排文件在 1Panel「容器」→「编排」→「创建编排」粘贴下面的 compose 内容。这个配置做了三件事限制资源、配置健康检查、挂载配置和数据卷。version: 3.8 services: dbhub-mcp: image: dbhub/mcp-server:latest container_name: dbhub-mcp restart: unless-stopped env_file: - /opt/dbhub/config/.env ports: - 127.0.0.1:8501:8501 volumes: - /opt/dbhub/config:/app/config:ro - /opt/dbhub/data:/app/data deploy: resources: limits: cpus: 2.0 memory: 2G healthcheck: test: [CMD, curl, -f, http://localhost:8501/health] interval: 30s timeout: 10s retries: 5 start_period: 20s logging: driver: json-file options: max-size: 20m max-file: 5几个参数说明端口绑定到127.0.0.1而不是0.0.0.0意味着只有本机能访问外部要走 1Panel 的反向代理或者 SSH 隧道这是生产环境的基本要求。start_period给 20 秒是因为 DBHub 启动时要连数据库太短会误判健康检查失败。日志限制 20m×5防止磁盘被写满。3.3 config.toml 骨架DBHub 支持用 config.toml 声明数据源和工具暴露范围。放在/opt/dbhub/config/config.toml容器内只读挂载。[server] host 0.0.0.0 port 8501 read_only true [[datasources]] name mysql_prod type mysql dsn dbhub_ro:${MYSQL_PASSWORD}tcp(${MYSQL_HOST}:${MYSQL_PORT})/${MYSQL_DATABASE} max_open_conns 20 max_idle_conns 5 [[datasources]] name pg_analytics type postgres dsn postgres://${PG_USER}:${PG_PASSWORD}${PG_HOST}:${PG_PORT}/${PG_DATABASE}?sslmodedisable max_open_conns 15 max_idle_conns 3 [tools] # 只暴露查询类工具屏蔽写操作 allow [query, list_tables, describe_table] deny [execute, insert, update, delete, drop]read_only true和[tools]的 deny 列表是双保险。即使客户端误调用写操作服务端也会拒绝。生产环境不要图省事把 deny 去掉。4. 接入 TaoToken 统一通道并验证4.1 MCP 客户端配置DBHub 服务跑起来后MCP 客户端以 Claude Code 为例需要配置两件事一是连上 DBHub 的 MCP 端点二是模型调用走 TaoToken 通道。Claude Code 的配置文件通常在~/.claude/settings.json或项目级.mcp.json。{ mcpServers: { dbhub: { url: http://127.0.0.1:8501/mcp, transport: http } }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }如果你用的是 Cline、Continue 这类工具配置逻辑一样MCP 端点指向 DBHub模型 base_url 指向https://taotoken.net/apikey 填 TaoToken 的 Key。这样模型请求和数据库工具调用就分成了两条链路互不干扰。提示Claude Code 的接入细节可以参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 里面有 base_url 和 header 的完整说明。想先在网页里试模型对话用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels 。4.2 连通性验证脚本配置完别急着开客户端先用 curl 验证两条链路。第一条验证 TaoToken 通道是否通第二条验证 DBHub 健康状态。# 1. 验证 TaoToken 通道 curl -sS https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-3-5-sonnet-20241022, max_tokens: 64, messages: [{role: user, content: ping}] } | head -c 500 # 2. 验证 DBHub 健康检查 curl -sS http://127.0.0.1:8501/health # 3. 验证 DBHub MCP 端点可达 curl -sS -X POST http://127.0.0.1:8501/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}} | head -c 800第一条返回里能看到content字段和模型输出说明 TaoToken 通道正常。第二条返回{status:ok}之类说明 DBHub 进程活着。第三条返回工具列表 JSON说明 MCP 协议层通了。三条都过再去客户端里用。4.3 成功结果长什么样在 Claude Code 里输入「列出 mysql_prod 里所有表」正常流程是客户端先通过 TaoToken 通道把请求发给模型模型决定调用 DBHub 的list_tables工具客户端再通过 MCP 端点请求 DBHubDBHub 查库返回结果模型整理后输出。你会在客户端看到工具调用记录和最终表名列表。如果只看到模型回复但没工具调用多半是 MCP 端点没连上如果工具调用报错看 DBHub 日志。5. 本篇常见错误排查5.1 容器启动后健康检查一直 unhealthy先看日志1Panel「容器」→ 找到 dbhub-mcp → 「日志」。常见原因是数据库连不上。检查.env里的MYSQL_HOST是不是172.17.0.1以及宿主机数据库是否允许该网段访问。MySQL 需要授权dbhub_ro172.17.0.%PostgreSQL 要在pg_hba.conf里放行。# 进容器手动测数据库连通性 docker exec -it dbhub-mcp sh nc -zv 172.17.0.1 33065.2 MCP 端点返回 404 或连接拒绝确认端口映射是127.0.0.1:8501:8501且 DBHub 监听在0.0.0.0。如果客户端和服务器不在同一台机器需要走 1Panel 反向代理加 HTTPS或者用 SSH 隧道把 8501 转发到本地。不要直接把 8501 暴露到公网。5.3 TaoToken 调用返回 401九成是 Key 填错或者 header 名不对。Anthropic 协议用x-api-keyOpenAI 兼容协议用Authorization: Bearer。确认 base_url 是https://taotoken.net/api不要多加/v1之外的路径。如果还不行去 API Keys 页面确认 Key 没过期、没被禁用。5.4 工具调用返回权限错误检查 config.toml 的[tools]deny 列表以及数据库账号是否只有只读权限。生产环境建议单独建一个只读账号给 DBHub 用不要复用业务账号。-- MySQL 只读账号示例 CREATE USER dbhub_ro172.17.0.% IDENTIFIED BY strong_password; GRANT SELECT, SHOW VIEW ON app_prod.* TO dbhub_ro172.17.0.%; FLUSH PRIVILEGES;5.5 日志里出现连接池耗尽调大max_open_conns之前先确认数据库的max_connections够用。DBHub 侧连接池 20如果同时有多个客户端可能不够。但盲目调大会拖垮数据库建议先看 DBHub 日志里的等待时间再决定。6. 长期运行与统一通道的配合这套架构跑稳定后你会发现真正的价值在于「统一通道」这四个字。DBHub 负责数据侧TaoToken 负责模型侧两边解耦。以后换模型、加数据源、接新客户端都只动一处配置。如果你要跑长期的编码 Agent 或者自动化任务建议把 TaoToken 的 Coding Plan 用起来配合 DBHub 的只读数据源让 Agent 在受控范围内查数据、写代码。最后留一个我踩过的坑1Panel 升级后偶尔会重置容器网络导致172.17.0.1这个地址变化。稳妥做法是给数据库容器和 DBHub 建一个自定义 Docker 网络用容器名互访而不是依赖默认网桥 IP。这个改动不大但能省掉半夜被健康检查告警叫醒的麻烦。
1. 为什么要在 1Panel 上跑 DBHub MCP 服务器DBHub MCP 是一个把数据库能力封装成 MCP 协议接口的服务简单说就是让 Claude、Cursor 这类支持 MCP 的客户端通过标准协议去查询你的 MySQL、PostgreSQL、SQLite而不用把数据库账号密码散落在每个客户端里。它适合谁适合手里有一台自己的云服务器、想给 AI 编码工具接上真实数据源、又不想把库直接暴露到公网的人。我这次选 1Panel 来部署原因很直接它把 Docker 编排、反向代理、日志查看、环境变量管理都做成了可视化面板省掉大量手写 systemd 和 Nginx 配置的时间。但面板只是壳真正决定这套服务能不能稳定跑的是容器编排参数、DBHub 的环境变量、以及 MCP 客户端调用的统一通道配置。这里有个关键点容易被忽略MCP 服务器本身不负责模型调用它只负责把数据库操作暴露成工具。而模型侧比如 Claude Code、Cline需要走一个统一的 API 通道去访问模型。我用的方案是 TaoToken 统一通道一个 Key 覆盖多家模型MCP 客户端配置里只填一个 base_url 和 key省得每个工具单独配一遍。下面从零开始把 1Panel 编排、DBHub 配置、TaoToken 接入、连通性验证、日志排障全部走一遍。2. 前置准备TaoToken 通道与 1Panel 环境2.1 TaoToken 统一通道准备TaoToken 的定位是统一模型 API 通道官网在 https://taotoken.net API 入口是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key这个 Key 后面会同时被 MCP 客户端和验证脚本使用。操作路径进入控制台 → API Keys 页面 → 新建 Key → 复制保存。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。如果你后面要长期跑编码 Agent可以看下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 按套餐走比单次调用更划算。注意Key 只在创建时完整显示一次务必先存到密码管理器。后面所有配置里出现的sk-xxxx都替换成你自己的。2.2 1Panel 安装与基础检查服务器建议 2C4G 起步DBHub 本身不重但同时跑数据库和 MCP 服务内存别低于 2G。1Panel 安装脚本官方提供执行后按提示设置面板端口和安全入口。# 安装 1Panel以官方脚本为例具体版本以官网为准 curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o /tmp/quick_start.sh sudo bash /tmp/quick_start.sh # 安装完成后查看版本 1panel version装完后登录面板先在「应用商店」里确认 Docker 已就绪。1Panel 会自动管理 Docker 环境你不需要单独装 docker-compose面板的「容器」→「编排」功能直接支持 compose 文件。2.3 目录规划在服务器上建两个目录一个放 DBHub 配置一个放数据卷避免容器重建时数据丢失。mkdir -p /opt/dbhub/config mkdir -p /opt/dbhub/data chmod 750 /opt/dbhub3. 可复制配置1Panel 编排 DBHub MCP3.1 DBHub 环境变量设计DBHub 通过环境变量读取数据库连接信息。生产环境不要把密码写进 compose 明文用 1Panel 的「环境变量」功能或者.env文件注入。下面是一个覆盖 MySQL 和 PostgreSQL 双数据源的配置骨架。# /opt/dbhub/config/.env DBHUB_HOST0.0.0.0 DBHUB_PORT8501 DBHUB_LOG_LEVELinfo # MySQL 数据源 MYSQL_HOST172.17.0.1 MYSQL_PORT3306 MYSQL_USERdbhub_ro MYSQL_PASSWORDyour_mysql_password MYSQL_DATABASEapp_prod # PostgreSQL 数据源 PG_HOST172.17.0.1 PG_PORT5432 PG_USERdbhub_ro PG_PASSWORDyour_pg_password PG_DATABASEanalytics # 只读保护生产环境强烈建议开启 DBHUB_READ_ONLYtrue DBHUB_MAX_ROWS1000这里172.17.0.1是 Docker 默认网桥的宿主机地址如果你的数据库跑在宿主机上用这个地址容器才能访问到。如果数据库本身也在 Docker 里改成对应容器名或自定义网络别名。3.2 1Panel 编排文件在 1Panel「容器」→「编排」→「创建编排」粘贴下面的 compose 内容。这个配置做了三件事限制资源、配置健康检查、挂载配置和数据卷。version: 3.8 services: dbhub-mcp: image: dbhub/mcp-server:latest container_name: dbhub-mcp restart: unless-stopped env_file: - /opt/dbhub/config/.env ports: - 127.0.0.1:8501:8501 volumes: - /opt/dbhub/config:/app/config:ro - /opt/dbhub/data:/app/data deploy: resources: limits: cpus: 2.0 memory: 2G healthcheck: test: [CMD, curl, -f, http://localhost:8501/health] interval: 30s timeout: 10s retries: 5 start_period: 20s logging: driver: json-file options: max-size: 20m max-file: 5几个参数说明端口绑定到127.0.0.1而不是0.0.0.0意味着只有本机能访问外部要走 1Panel 的反向代理或者 SSH 隧道这是生产环境的基本要求。start_period给 20 秒是因为 DBHub 启动时要连数据库太短会误判健康检查失败。日志限制 20m×5防止磁盘被写满。3.3 config.toml 骨架DBHub 支持用 config.toml 声明数据源和工具暴露范围。放在/opt/dbhub/config/config.toml容器内只读挂载。[server] host 0.0.0.0 port 8501 read_only true [[datasources]] name mysql_prod type mysql dsn dbhub_ro:${MYSQL_PASSWORD}tcp(${MYSQL_HOST}:${MYSQL_PORT})/${MYSQL_DATABASE} max_open_conns 20 max_idle_conns 5 [[datasources]] name pg_analytics type postgres dsn postgres://${PG_USER}:${PG_PASSWORD}${PG_HOST}:${PG_PORT}/${PG_DATABASE}?sslmodedisable max_open_conns 15 max_idle_conns 3 [tools] # 只暴露查询类工具屏蔽写操作 allow [query, list_tables, describe_table] deny [execute, insert, update, delete, drop]read_only true和[tools]的 deny 列表是双保险。即使客户端误调用写操作服务端也会拒绝。生产环境不要图省事把 deny 去掉。4. 接入 TaoToken 统一通道并验证4.1 MCP 客户端配置DBHub 服务跑起来后MCP 客户端以 Claude Code 为例需要配置两件事一是连上 DBHub 的 MCP 端点二是模型调用走 TaoToken 通道。Claude Code 的配置文件通常在~/.claude/settings.json或项目级.mcp.json。{ mcpServers: { dbhub: { url: http://127.0.0.1:8501/mcp, transport: http } }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }如果你用的是 Cline、Continue 这类工具配置逻辑一样MCP 端点指向 DBHub模型 base_url 指向https://taotoken.net/apikey 填 TaoToken 的 Key。这样模型请求和数据库工具调用就分成了两条链路互不干扰。提示Claude Code 的接入细节可以参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 里面有 base_url 和 header 的完整说明。想先在网页里试模型对话用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels 。4.2 连通性验证脚本配置完别急着开客户端先用 curl 验证两条链路。第一条验证 TaoToken 通道是否通第二条验证 DBHub 健康状态。# 1. 验证 TaoToken 通道 curl -sS https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-3-5-sonnet-20241022, max_tokens: 64, messages: [{role: user, content: ping}] } | head -c 500 # 2. 验证 DBHub 健康检查 curl -sS http://127.0.0.1:8501/health # 3. 验证 DBHub MCP 端点可达 curl -sS -X POST http://127.0.0.1:8501/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}} | head -c 800第一条返回里能看到content字段和模型输出说明 TaoToken 通道正常。第二条返回{status:ok}之类说明 DBHub 进程活着。第三条返回工具列表 JSON说明 MCP 协议层通了。三条都过再去客户端里用。4.3 成功结果长什么样在 Claude Code 里输入「列出 mysql_prod 里所有表」正常流程是客户端先通过 TaoToken 通道把请求发给模型模型决定调用 DBHub 的list_tables工具客户端再通过 MCP 端点请求 DBHubDBHub 查库返回结果模型整理后输出。你会在客户端看到工具调用记录和最终表名列表。如果只看到模型回复但没工具调用多半是 MCP 端点没连上如果工具调用报错看 DBHub 日志。5. 本篇常见错误排查5.1 容器启动后健康检查一直 unhealthy先看日志1Panel「容器」→ 找到 dbhub-mcp → 「日志」。常见原因是数据库连不上。检查.env里的MYSQL_HOST是不是172.17.0.1以及宿主机数据库是否允许该网段访问。MySQL 需要授权dbhub_ro172.17.0.%PostgreSQL 要在pg_hba.conf里放行。# 进容器手动测数据库连通性 docker exec -it dbhub-mcp sh nc -zv 172.17.0.1 33065.2 MCP 端点返回 404 或连接拒绝确认端口映射是127.0.0.1:8501:8501且 DBHub 监听在0.0.0.0。如果客户端和服务器不在同一台机器需要走 1Panel 反向代理加 HTTPS或者用 SSH 隧道把 8501 转发到本地。不要直接把 8501 暴露到公网。5.3 TaoToken 调用返回 401九成是 Key 填错或者 header 名不对。Anthropic 协议用x-api-keyOpenAI 兼容协议用Authorization: Bearer。确认 base_url 是https://taotoken.net/api不要多加/v1之外的路径。如果还不行去 API Keys 页面确认 Key 没过期、没被禁用。5.4 工具调用返回权限错误检查 config.toml 的[tools]deny 列表以及数据库账号是否只有只读权限。生产环境建议单独建一个只读账号给 DBHub 用不要复用业务账号。-- MySQL 只读账号示例 CREATE USER dbhub_ro172.17.0.% IDENTIFIED BY strong_password; GRANT SELECT, SHOW VIEW ON app_prod.* TO dbhub_ro172.17.0.%; FLUSH PRIVILEGES;5.5 日志里出现连接池耗尽调大max_open_conns之前先确认数据库的max_connections够用。DBHub 侧连接池 20如果同时有多个客户端可能不够。但盲目调大会拖垮数据库建议先看 DBHub 日志里的等待时间再决定。6. 长期运行与统一通道的配合这套架构跑稳定后你会发现真正的价值在于「统一通道」这四个字。DBHub 负责数据侧TaoToken 负责模型侧两边解耦。以后换模型、加数据源、接新客户端都只动一处配置。如果你要跑长期的编码 Agent 或者自动化任务建议把 TaoToken 的 Coding Plan 用起来配合 DBHub 的只读数据源让 Agent 在受控范围内查数据、写代码。最后留一个我踩过的坑1Panel 升级后偶尔会重置容器网络导致172.17.0.1这个地址变化。稳妥做法是给数据库容器和 DBHub 建一个自定义 Docker 网络用容器名互访而不是依赖默认网桥 IP。这个改动不大但能省掉半夜被健康检查告警叫醒的麻烦。
