DBX_Docker部署与MCP手册

DBX Web Docker 部署 & MCP 接入手册

适用环境：内网 Ubuntu/Debian 服务器、无外网、Docker 已安装、docker-compose v1.x（连字符命令）
目标：用 Docker 部署 DBX Web，并开启 MCP HTTP 服务供 AI 客户端（Claude / Cursor / Codex 等）接入
版本：v1.0

一、方案总览

1.1 架构

┌──────────────────────────────┐
│ AI 客户端（Claude / Cursor 等）│
│  type: http + Bearer Token    │
└───────────────┬──────────────┘
                │ HTTP :4224/mcp
┌───────────────▼──────────────┐
│ 内网 Ubuntu 服务器             │
│  Docker: 容器 dbx             │
│  ├─ Web UI      :4224        │
│  └─ MCP 端点    :4224/mcp    │
│  卷: dbx-data → /app/data    │
└───────────────┬──────────────┘
                │ 直连数据库
       内网数据库（如 10.58.170.224:15432）

1.2 关键概念

概念	说明
DBX Web	DBX 的 Web/Docker 形态，统一托管数据库连接，浏览器可访问
DBX_PASSWORD	Web 页面登录密码（浏览器用）
DBX_WEB_MCP_TOKEN	MCP HTTP 端点的 Bearer Token（客户端用），与登录密码相互独立
DBX_WEB_MCP_ALLOWED_HOSTS	MCP 端点的 Host 白名单，必填
dbx-data 卷	持久化连接配置、MCP 策略、驱动等

⚠️ 记住：DBX_PASSWORD ≠ DBX_WEB_MCP_TOKEN。浏览器登录用前者，MCP 客户端用后者。

二、前置条件检查

在服务器上执行：

# 1) 检查 Docker 引擎
docker --version
# 期望：Docker version 20.x 及以上

# 2) 检查 compose（重点：区分两种！）
docker compose version        # 新版插件（命令：docker compose，无连字符）
docker-compose version        # 老版独立版（命令：docker-compose，有连字符）
# 内网老环境常见：docker-compose version 1.24.1 → 后续统一用 docker-compose

# 3) 检查 Docker 是否开机自启（关系到断电后容器能否自动恢复）
systemctl is-enabled docker
# 期望：enabled。若不是，执行：sudo systemctl enable docker

# 4) 检查 4224 端口是否被占用
ss -lntp | grep 4224
# 期望：无输出（未被占用）

# 5) 检查磁盘空间（镜像约 400MB + 数据增长）
df -h /var/lib/docker

三、获取镜像（离线 / 在线）

3.1 离线方式（内网无外网，推荐）

步骤 1：在有外网的机器上导出镜像

# 拉取镜像（国内建议用 CNB 源，速度快）
docker pull docker.cnb.cool/dbxio.com/dbx:latest
# 或官方源： docker pull t8y2/dbx:latest

# 导出为 tar 文件（注意 save 时的名字要与 pull 的一致）
docker save -o dbx-web-image.tar docker.cnb.cool/dbxio.com/dbx:latest

# 确认文件大小（一般 350~450 MB）
ls -lh dbx-web-image.tar

步骤 2：把 tar 拷到内网服务器

# 方式一：scp（需网络可达）
scp dbx-web-image.tar user@10.58.170.224:/opt/dbx/

# 方式二：U 盘 / 内网文件服务器，自行拷贝

步骤 3：内网服务器导入镜像

cd /opt/dbx

# 导入镜像
docker load -i dbx-web-image.tar

# 校验导入结果（重点：记住这个名字，要和 compose 里的 image 一致）
docker images | grep -i dbx
# 期望：docker.cnb.cool/dbxio.com/dbx   latest   xxxxx   380MB

如果导入的镜像名与 compose 里的 image: 不一致，二选一：

# 方案 A：给镜像改名，匹配 compose
docker tag <实际镜像名:标签> docker.cnb.cool/dbxio.com/dbx:latest
# 方案 B：改 compose 文件里的 image 字段为实际名字

3.2 在线方式（服务器可联网时）

docker pull docker.cnb.cool/dbxio.com/dbx:latest   # 国内源
# 或
docker pull t8y2/dbx:latest                        # 官方源

四、Docker 部署 DBX Web

4.1 准备目录与配置文件

# 创建部署目录
sudo mkdir -p /opt/dbx
cd /opt/dbx

# 创建 compose 文件（完整内容见下，或使用交付的 docker-compose.dbx.yml）
vim docker-compose.dbx.yml

compose 文件内容（已加详细注释）：

# =============================================================================
# DBX Web Docker 部署编排 —— 适配内网 / 无外网 / docker-compose v1.x
# 使用：cd /opt/dbx && docker-compose -f docker-compose.dbx.yml up -d
# =============================================================================
version: "2.4"          # 必须保留：docker-compose v1 无 version 会按老格式解析而报错

services:
  dbx:
    # 镜像名必须与 docker images 里的名字一致，否则会尝试联网拉取而失败
    image: docker.cnb.cool/dbxio.com/dbx:latest

    container_name: dbx                       # 固定容器名，便于后续 docker logs dbx 等操作

    ports:
      - "4224:4224"                           # 宿主机:容器；Web UI 与 MCP 端点共用此端口

    environment:
      # Web 登录密码（浏览器访问用）；改过密码后建议删除此行
      - DBX_PASSWORD=ChangeMe_StrongPassword

      # MCP HTTP 端点 Token（客户端用）；生成：openssl rand -hex 32
      - DBX_WEB_MCP_TOKEN=替换为你的token

      # MCP Host 白名单（必填）：填客户端实际访问用的 主机:端口
      - DBX_WEB_MCP_ALLOWED_HOSTS=10.58.170.224:4224

    volumes:
      # 持久化：连接配置 / MCP 策略 / 驱动，物理位置 /var/lib/docker/volumes/dbx_dbx-data/_data
      - dbx-data:/app/data

    restart: unless-stopped                   # 断电/重启后自动拉起容器

volumes:
  dbx-data:                                   # 顶层卷声明，缺失会导致持久化不生效

4.2 生成随机 Token

# 生成 32 字节（64位十六进制）随机 token，复制输出填入 DBX_WEB_MCP_TOKEN
openssl rand -hex 32

4.3 启动

cd /opt/dbx

# 老版 compose（连字符）——内网 v1.24 环境用这个
docker-compose -f docker-compose.dbx.yml up -d

# 或新版 compose 插件
# docker compose -f docker-compose.dbx.yml up -d

启动过程说明：

阶段	输出	含义
创建网络	`Creating network "dbx_default"`	正常
创建卷	`Creating volume "dbx_dbx-data"`	正常（持久化卷）
创建容器	`Creating dbx ... done`	正常
⚠️ 拉取镜像	`Pulling dbx ...` 然后 timeout	本地无该镜像，见下方排查
启动完成	`Starting dbx ... done`	成功

如果出现 Pulling dbx ... connection timed out：说明本地没有该 tag 的镜像。
解决：docker images | grep dbx 查看实际名字 → docker tag 改成一致即可。

4.4 验证部署

# 1) 容器是否运行
docker ps | grep dbx
# 期望：Up X seconds

# 2) 容器启动日志（首次启动会有初始化输出）
docker logs dbx | tail -30

# 3) 服务端口是否监听
ss -lntp | grep 4224

# 4) Web API 健康检查（本机）
curl http://127.0.0.1:4224/api/auth/check
# 期望：{"authenticated":false,"required":true,"setup_required":false}

# 5) 从客户端机器测试连通性
curl http://10.58.170.224:4224/api/auth/check   # 应返回同样 JSON

五、开启 MCP HTTP 服务

5.1 原理

DBX Web 默认不开启 MCP HTTP 端点。设置 DBX_WEB_MCP_TOKEN 后，Web 会在同一个 4224 端口上暴露：

http://<服务器IP>:4224/mcp

客户端凭 Authorization: Bearer <token> 访问。

5.2 三个环境变量的作用

变量	作用	是否必填
`DBX_WEB_MCP_TOKEN`	MCP 端点的访问令牌（Bearer Token），开启端点的开关	✅ 必填
`DBX_WEB_MCP_ALLOWED_HOSTS`	Host 白名单，防止 Host 头伪造/DNS rebinding；填客户端实际访问的 `主机:端口`	✅ 必填
`DBX_WEB_MCP_ALLOWED_ORIGINS`	浏览器型客户端的 Origin 白名单	仅浏览器场景

三者已在 docker-compose.dbx.yml 的 environment 中配置好，修改后需重建容器生效。

5.3 修改后重建容器

cd /opt/dbx

# 环境变量变更必须 recreate（restart 不生效）
docker-compose -f docker-compose.dbx.yml up -d

# 确认环境变量已注入
docker inspect dbx --format '{{range .Config.Env}}{{println .}}{{end}}' | grep MCP

5.4 验证端点状态

# 不带 token 访问 → 期望 401（表示端点已启用并在校验 token）
# 若返回 404 → 端点未启用（检查 DBX_WEB_MCP_TOKEN 是否配好、容器是否重建）
curl -i http://10.58.170.224:4224/mcp

# 带正确 token 访问 → 期望非 401（具体状态取决于请求体格式）
curl -i -H "Authorization: Bearer <你的token>" http://10.58.170.224:4224/mcp

状态码对照表：

状态码	含义	处理
404	端点未启用	检查 `DBX_WEB_MCP_TOKEN` 是否配置 + 容器是否重建
401	Token 缺失或格式错误	检查 `Bearer` 前缀 + token 是否一致
403	Host 不在白名单	检查 `DBX_WEB_MCP_ALLOWED_HOSTS` 是否等于访问用的 `主机:端口`
400/200	端点正常工作	Token 校验通过

⚠️ 最常见的坑：Authorization 头必须是 Bearer <token>（Bearer + 一个空格 + token），
只写裸 token 会一直 401。

六、客户端接入 MCP

6.1 方式一：HTTP 直连（推荐，直接连服务器端点）

客户端 MCP 配置（Claude Code 的 .mcp.json / Cursor 的 MCP 设置等）：

{
  "mcpServers": {
    "dbx": {
      "type": "http",                                      // 传输类型：HTTP
      "url": "http://10.58.170.224:4224/mcp",              // 服务器 MCP 端点
      "headers": {
        "Authorization": "Bearer 90c9ea...（与 DBX_WEB_MCP_TOKEN 完全一致）"  // 注意 Bearer + 空格
      }
    }
  }
}

6.2 方式二：stdio 适配（客户端只能用 stdio 时）

用本机 dbx-mcp-server 进程转发到服务器 Web 后端：

{
  "mcpServers": {
    "dbx": {
      "command": "dbx-mcp-server",                          // 需先全局安装 @dbx-app/mcp-server
      "args": [],
      "env": {
        "DBX_WEB_URL": "http://10.58.170.224:4224",         // 指向服务器 Web
        "DBX_WEB_PASSWORD": "你的Web登录密码"                 // 这里是登录密码，不是 token
      }
    }
  }
}

6.3 接入后的验证

重启/重连 MCP 客户端（配置在启动时加载）；
在客户端中调用 dbx_list_connections —— 应看到服务器 Web 上配置的连接；
调用 dbx_list_databases / dbx_list_tables / dbx_execute_query 验证可查库。

6.4 两种方式对比

维度	HTTP 直连	stdio 适配
凭证	`DBX_WEB_MCP_TOKEN`（Bearer）	`DBX_WEB_PASSWORD`（登录密码）
需要本地装包	否	是（`@dbx-app/mcp-server`）
桌面 UI 工具	隐藏	隐藏
适用	支持 http 的客户端	只支持 stdio 的客户端

七、持久化与自动重启

7.1 持久化

# 查看卷是否创建
docker volume ls | grep dbx

# 查看卷的物理路径（最准确）
docker volume inspect dbx_dbx-data --format '{{.Mountpoint}}'
# 典型输出：/var/lib/docker/volumes/dbx_dbx-data/_data

# 查看容器挂载情况
docker inspect dbx --format '{{json .Mounts}}'

# 查看卷内数据
ls -lh /var/lib/docker/volumes/dbx_dbx-data/_data

层级	路径
卷名	`dbx_dbx-data`（compose 项目名 + 卷名）
卷根目录	`/var/lib/docker/volumes/dbx_dbx-data/`
真实数据目录	`/var/lib/docker/volumes/dbx_dbx-data/_data/`
容器内视角	`/app/data/`

⚠️ 禁止直接手工修改 /var/lib/docker/volumes/... 下的文件；备份/迁移请用 docker run --rm -v 或 docker cp。

7.2 自动重启

条件	说明
`restart: unless-stopped`	compose 已配置，断电/重启后自动拉起
`systemctl is-enabled docker` = enabled	Docker 服务开机自启（前提）

# 验证 restart 策略
docker inspect dbx --format '{{.HostConfig.RestartPolicy.Name}}'
# 期望：unless-stopped

# 验证 Docker 开机自启
systemctl is-enabled docker
# 期望：enabled

例外：若断电前手动执行过 docker stop dbx，unless-stopped 不会自动拉起（需 docker start dbx）。

7.3 重启策略对照

策略	断电重启后	手动 stop 后
`no`	不启动	不启动
`always`	启动	启动
`unless-stopped`	启动	不启动

八、安全加固建议

8.1 凭据管理

Token 视为密码：拿到 URL + Token 的人即可访问授权范围内的数据库，不要发到群聊/文档/对话；
定期轮换：更换 DBX_WEB_MCP_TOKEN 后同步更新所有客户端配置；
强随机：始终用 openssl rand -hex 32 生成，不要用可猜测字符串。

8.2 权限最小化（在 DBX Web 界面配置）

配置项	位置	建议
MCP 权限模式	设置 → MCP	先用只读，按需放开数据读写/全访问
Allowed connections	设置 → MCP	只勾选必要的连接
连接只读保护	连接设置	生产库开启
数据库账号	连接配置	使用最小权限账号，而非超级管理员

8.3 网络层

# 防火墙只放行必要来源 IP（示例：仅允许某网段访问 4224）
sudo ufw allow from 10.58.170.0/24 to any port 4224 proto tcp
sudo ufw status

内网 HTTP 为明文传输，建议后续加 Nginx/Caddy 反代做 HTTPS；
若需 HTTPS：DBX 容器仍监听 HTTP，由反代终结 TLS，客户端改用 DBX_WEB_URL=https://...。

8.4 后续升级 HTTPS（参考）

server {
    listen 443 ssl;
    server_name dbx.corp.com;

    ssl_certificate     /etc/nginx/certs/dbx.crt;
    ssl_certificate_key /etc/nginx/certs/dbx.key;

    location / {
        proxy_pass http://127.0.0.1:4224;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_buffering off;              # MCP/SSE 需要，勿开缓冲
        proxy_read_timeout 3600s;
        client_max_body_size 1024m;
    }
}

九、故障排查常用命令手册

9.1 容器状态类

docker ps                          # 只看运行中的容器
docker ps -a                       # 包含已停止的容器（排错必看）
docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'   # 格式化输出
docker inspect dbx                 # 容器完整配置（JSON）
docker stats dbx --no-stream       # 一次性查看 CPU/内存占用
docker top dbx                     # 容器内进程列表

9.2 日志类

docker logs dbx                    # 全量日志
docker logs --tail 100 dbx         # 最近 100 行
docker logs -f dbx                 # 实时跟踪（Ctrl+C 退出）
docker logs --since 30m dbx        # 最近 30 分钟
docker logs -t dbx                 # 带时间戳

9.3 镜像类

docker images | grep -i dbx                        # 本地是否有镜像
docker inspect docker.cnb.cool/dbxio.com/dbx:latest --format '{{.Id}}'   # 镜像 ID/创建时间
docker history docker.cnb.cool/dbxio.com/dbx:latest | head   # 镜像层历史
docker tag <源镜像:标签> docker.cnb.cool/dbxio.com/dbx:latest  # 改名以匹配 compose
docker save -o dbx-web-image.tar docker.cnb.cool/dbxio.com/dbx:latest   # 导出
docker load -i dbx-web-image.tar                    # 导入
docker rmi <镜像ID>                                 # 删除镜像（先删容器）

9.4 编排类（compose）

docker-compose -f docker-compose.dbx.yml up -d      # 启动/更新（v1 老版）
docker-compose -f docker-compose.dbx.yml ps         # 查看编排状态
docker-compose -f docker-compose.dbx.yml logs -f    # 编排日志
docker-compose -f docker-compose.dbx.yml config     # 校验 YAML 语法（排错利器）
docker-compose -f docker-compose.dbx.yml down       # 停止并删除容器（保留卷）
docker-compose -f docker-compose.dbx.yml restart    # 重启（不重建）

注意：down -v 会删除数据卷，导致连接配置丢失，非必要不要用。

9.5 卷与持久化类

docker volume ls                                   # 列出所有卷
docker volume inspect dbx_dbx-data                 # 查看卷详情与物理路径
docker volume inspect dbx_dbx-data --format '{{.Mountpoint}}'
docker exec dbx ls -lh /app/data                   # 查看容器内数据文件
docker inspect dbx --format '{{json .Mounts}}'     # 查看挂载映射
# 备份卷（推荐方式）
docker run --rm -v dbx_dbx-data:/data -v /opt/dbx:/backup alpine \
  tar czf /backup/dbx-data-$(date +%Y%m%d).tar.gz -C /data .

9.6 网络与端口类

ss -lntp | grep 4224                               # 端口是否监听
netstat -tunlp | grep 4224                         # 等价（老系统）
lsof -i:4224                                       # 占用进程
docker port dbx                                    # 容器端口映射
docker inspect dbx --format '{{json .NetworkSettings.Ports}}'
# 从其他机器测试连通性
curl -v http://10.58.170.224:4224/api/auth/check
# 防火墙
sudo ufw status verbose
sudo ufw allow from 10.58.170.0/24 to any port 4224 proto tcp
# 抓包排查（需要 root）
sudo tcpdump -i any -nn port 4224 -c 20

9.7 MCP 端点类

# 1) 端点是否启用（404=未启用，401=已启用）
curl -i http://10.58.170.224:4224/mcp

# 2) 带 token 测试（注意 Bearer + 空格）
curl -i -H "Authorization: Bearer <你的token>" http://10.58.170.224:4224/mcp

# 3) 校验环境变量是否注入容器
docker inspect dbx --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E 'MCP|PASSWORD'

# 4) 只查看 token（注意：勿在公开场合执行）
docker inspect dbx --format '{{range .Config.Env}}{{println .}}{{end}}' | grep DBX_WEB_MCP_TOKEN

# 5) 查看 MCP 相关请求日志（DBX 默认不记录 SQL 内容，仅访问记录）
docker logs dbx 2>&1 | grep -i mcp | tail -50

MCP 排错速查表：

现象	原因	解决
`/mcp` 返回 404	未设 `DBX_WEB_MCP_TOKEN` 或未重建容器	配置后 `up -d` 重建
401 需要授权	token 缺失 / 缺 `Bearer` 前缀 / token 不一致	补 `Bearer` 前缀，核对值
403	Host 不在白名单	修正 `DBX_WEB_MCP_ALLOWED_HOSTS`
客户端连不上	网络不通/端口未放行	`curl` 测试 + 防火墙放行
改了配置不生效	客户端未重启 / 容器未重建	重启客户端 + `up -d`
工具看不到连接	MCP 策略未授权该连接	Web `设置 → MCP` 勾选 Allowed connections

9.8 服务与系统类

systemctl status docker                            # Docker 服务状态
systemctl is-enabled docker                        # 是否开机自启
sudo systemctl enable docker                       # 设置开机自启
sudo systemctl restart docker                      # 重启 Docker（会重启容器）
docker events --filter container=dbx               # 实时事件流
journalctl -u docker --since "1 hour ago" | tail -50   # Docker 系统日志
free -h                                             # 内存
df -h /var/lib/docker                               # 磁盘
dmesg | tail -30                                    # 内核日志（OOM 等问题）

9.9 应急恢复流程

# 场景 1：容器起不来
docker ps -a                     # 看退出码/状态
docker logs dbx --tail 200       # 看报错
docker-compose -f docker-compose.dbx.yml config   # 校验配置语法

# 场景 2：端口冲突
ss -lntp | grep 4224             # 找占用进程，停掉或改端口

# 场景 3：配置改了没生效
docker-compose -f docker-compose.dbx.yml up -d    # 必须重建而非 restart

# 场景 4：彻底重来（数据保留）
docker-compose -f docker-compose.dbx.yml down
docker-compose -f docker-compose.dbx.yml up -d

# 场景 5：彻底重来（数据清空，谨慎！）
docker-compose -f docker-compose.dbx.yml down -v   # -v 会删除数据卷

十、附录：备份与运维

10.1 定期备份脚本

#!/bin/bash
# 文件名：/opt/dbx/backup.sh
# 作用：备份 dbx-data 卷到 /opt/dbx/backup/
# 用法：chmod +x backup.sh && ./backup.sh

set -e
BACKUP_DIR="/opt/dbx/backup"
mkdir -p "$BACKUP_DIR"
STAMP=$(date +%Y%m%d_%H%M%S)

docker run --rm \
  -v dbx_dbx-data:/data \
  -v "$BACKUP_DIR":/backup \
  alpine tar czf "/backup/dbx-data-$STAMP.tar.gz" -C /data .

# 只保留最近 7 份
ls -1t "$BACKUP_DIR"/dbx-data-*.tar.gz | tail -n +8 | xargs -r rm -f

echo "备份完成：$BACKUP_DIR/dbx-data-$STAMP.tar.gz"

10.2 恢复

# 停止容器
docker-compose -f docker-compose.dbx.yml down

# 恢复卷数据
docker run --rm \
  -v dbx_dbx-data:/data \
  -v /opt/dbx/backup:/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/dbx-data-YYYYmmdd_HHMMSS.tar.gz -C /data"

# 重新启动
docker-compose -f docker-compose.dbx.yml up -d

10.3 升级流程（内网离线）

# 1. 外网机器拉新版并导出
docker pull docker.cnb.cool/dbxio.com/dbx:latest
docker save -o dbx-web-image-new.tar docker.cnb.cool/dbxio.com/dbx:latest

# 2. 拷到内网服务器并导入
docker load -i dbx-web-image-new.tar

# 3. 备份数据（见 10.1）

# 4. 重建容器
cd /opt/dbx
docker-compose -f docker-compose.dbx.yml up -d --force-recreate

# 5. 验证
docker ps | grep dbx
curl http://127.0.0.1:4224/api/auth/check

10.4 部署检查清单

检查项	命令	期望
容器运行	`docker ps \| grep dbx`	Up
端口监听	`ss -lntp \| grep 4224`	LISTEN
Web 可用	`curl http://127.0.0.1:4224/api/auth/check`	返回 JSON
MCP 端点	`curl -i http://IP:4224/mcp`	401（非 404）
持久化卷	`docker volume inspect dbx_dbx-data`	存在且有 Mountpoint
自动重启	`docker inspect dbx \| grep -i restart`	unless-stopped
Docker 自启	`systemctl is-enabled docker`	enabled
客户端接入	客户端 `dbx_list_connections`	列出服务器端连接

附：常见问题 FAQ

Q1：docker-compose up 报 unknown shorthand flag: 'f' in -f？
A：说明该机器没装 compose v2 插件，且 docker compose 不被识别。改用连字符的 docker-compose -f ...。

Q2：报 Unsupported config option for services: 'dbx'？
A：compose 文件缺少 version: 字段，docker-compose v1 会按老格式解析。加上 version: "2.4" 即可。

Q3：up 时卡在 Pulling ... connection timed out？
A：本地没有该 tag 的镜像。无外网时先 docker load 导入，确保镜像名与 compose image: 一致。

Q4：MCP 客户端报"需要授权"？
A：Authorization 值必须写成 Bearer <token>，检查是否漏了 Bearer 前缀。

Q5：浏览器打不开 / 提示登录？
A：正常，Web 有登录保护。用 compose 里 DBX_PASSWORD 的值登录。

Q6：断电重启后容器没起来？
A：检查 restart 策略是否 unless-stopped；systemctl is-enabled docker 是否 enabled；是否断电前手动 stop 过。

Q7：连接配置丢了？
A：检查是否误执行了 down -v，或卷未正确声明（顶层缺少 volumes: dbx-data:）。

文档结束

posted @ 2026-09-10 09:55 你的小可爱吖阅读(9) 评论(0) 收藏举报

刷新页面返回顶部

你的小可爱吖