DBX 部署教程：Docker、数据库连接与 Caddy 域名访问

把数据库工作台放在 VPS 上

数据库还在那台服务器上，管理它的人却可能换了三台电脑。装客户端、找连接、拷密钥，偶尔只是想确认一条记录，也得先把环境凑齐。把 DBX Web 版放到 VPS 上，解决的正是这类小麻烦：浏览器打开一个入口，查询由服务器执行，连接配置也留在服务器。

这篇从一台已经装好 Docker Compose 的 Linux VPS 开始，搭建一个个人使用的 DBX 工作台。先走 SSH 隧道，再接 HTTPS；不为管理器额外开放 PostgreSQL、MySQL 的公网端口。文中的域名和账号都是示例，不能原样当作生产配置。

先把“客户端放在哪里”想明白

DBX 有桌面版，也有 Docker 自托管版本。浏览器只是后者的操作界面，真正发起数据库连接的是 VPS 里的 DBX 进程。因此，连接框里的 `localhost` 指向容器自己，并不是你的电脑，也不自动代表宿主机。

这条区别会影响很多操作。SQLite 文件必须能被容器读取；SSH 私钥路径也必须在容器里存在；数据库如果只允许某个内网来源，就要允许 DBX 所在的网络，而不是浏览器所在的宽带地址。

截至 2026 年 9 月 30 日，官网的介绍已经是“100+ 种连接”，比一些旧介绍中的 60+ 更多。不过，连接数量不是选客户端的主要理由。能连、能查询、能编辑、能导入，是几个不同层次；专用工作台和驱动的支持范围也不同。先用你实际需要的两三种数据库验证，比对着完整列表挑工具更有用。DBX 官网、数据库支持说明

本文使用 Docker Hub 的 `t8y2/dbx:0.6.29`。版本标签和仓库的发行标签不是同一套写法，后者是 `v0.6.29`。不要只凭版本号推测镜像地址，先执行一次 pull 确认。完整的验证范围写在文末。

VPS 的位置，比配置表上多一核更值得先看

网页到 VPS、VPS 到数据库，是两段不同的网络。管理器放在远离数据库的位置，打开对象树、读取字段、测试连接都要跨更远的链路。对于已经有数据库的站点，优先复用同地域或能通过受控内网连接的机器。

如果准备单独买一台做自托管练习，可以从 2 核、2GB 内存留出起步预算。这只是少量连接、轻量查询的规划建议，不是 DBX 官方最低配置，更不是并发承诺。导入大文件、安装外部驱动、把数据库也放在同机，都会改变内存和磁盘需求。先观察实际负载，再决定是否扩容。

雨云有国内和海外云服务器可选，选地域时可以把数据库的位置一起考虑。需要新机器的话，可以查看雨云当前方案；已有空闲 VPS 就直接使用，不必为运行一个客户端重复购机。预算里还应留下备份空间，别把磁盘刚好买到只够装系统。

用 Compose 留下一份能看懂的部署配置

在 VPS 上准备目录：

mkdir -p ~/services/dbx
cd ~/services/dbx
docker version
docker compose version
umask 077
printf 'DBX_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .env

这会为网页入口生成一个随机密码，保存到当前目录的 `.env`。在自己的终端查看并收进密码管理器即可，不要把文件上传到公共仓库。数据库连接密码另行填写，与这个入口密码无关。

创建 `compose.yaml`：

name: dbx
services:
  dbx:
    image: t8y2/dbx:0.6.29
    restart: unless-stopped
    ports:
      - "127.0.0.1:4224:4224"
    environment:
      DBX_PASSWORD: ${DBX_PASSWORD:?请先在 .env 设置密码}
      DBX_DATA_DIR: /app/data
    volumes:
      - dbx-data:/app/data
    stop_grace_period: 90s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
volumes:
  dbx-data:

4224 只绑定回环地址，外部电脑不能直接通过 `VPS_IP:4224` 进入。命名卷保存 DBX 的状态；重建容器会继续使用它，删除卷则是另一回事。日常重启不要附带 `down -v`，也不要在清理“没用的 Docker 文件”时顺手删除数据卷。

启动前用静默模式检查配置，避免把展开后的密码打印到日志：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:4224/

如果 pull 报 `manifest unknown`，先核对镜像仓库和标签，不要去改端口。若是拉取网络问题，官方还提供 CNB 镜像入口；换源时同样需要核对该仓库的实际标签，不能假设两个仓库所有标签都完全一致。官方安装说明

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 `KuZhuJi`。配置按实际任务选择，数据库和附件另做备份。

通过 SSH 隧道完成初始化

在自己的电脑运行：

ssh -N -L 14224:127.0.0.1:4224 your-user@your-vps

打开 `http://127.0.0.1:14224`，输入 `.env` 中的入口密码。SSH 窗口需要保持运行，本地端口被占用时可以换掉前面的 14224。后面的 4224 对应 VPS 上的回环端口，不要两边一起随意改。

密码页能打开，说明隧道和 Web 服务已经接通；登录以后能看到工作台，才说明入口认证通过。这两步都不能证明数据库已经连好。先创建一条测试连接，再执行简单查询，才能把完整路径走完。

遇到数据安全迁移提示时，先读提示，不要删除数据目录重新开始。新建实例和已经保存过旧连接的实例，初次进入的流程可能不同。升级旧环境之前，应备份整个数据目录并保留它使用的加密密钥。

接数据库时，按容器的视角填地址

假设 PostgreSQL 也在 Docker 中，与 DBX 加入同一个用户自定义网络，且网络别名为 `postgres`，连接框应填写 `postgres`、5432、数据库名称和专用账号。这里使用容器端口，不是宿主机映射出去的另一个端口。

如果数据库在另一台 VPS，就填写从 DBX 这台机器能访问的私网地址或域名，并配置对应的网络访问限制与 TLS。先确认路由和账号来源限制，再谈客户端的选项。不要为了让测试变绿，把整个数据库端口对所有公网来源放开。

已有 Docker 网络可以在 Compose 中显式声明：

services:
  dbx:
    networks:
      - database-net
networks:
  database-net:
    external: true
    name: your-existing-database-network

这是对前面配置的补充片段，合并进原文件，不能拿它覆盖完整文件。网络名称要用 `docker network ls` 查到的真实值。连接已有网络也意味着 DBX 可以访问其中的其他服务，所以最好使用专门的管理网络，而不是把所有容器都塞进同一个网络。

只查看数据时，给它一个数据库侧的只读账号。DBX 的只读连接选项可以减少误操作，但数据库最终允许什么，仍由数据库自身授权决定。客户端按钮不是权限系统的替代品。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 `KuZhuJi`；迁移前保留数据与原有部署配置。

域名准备好后，再接宿主机 Caddy

对于运行在宿主机上的 Caddy，可以添加下面的站点块：

db.example.com {
    reverse_proxy 127.0.0.1:4224
}

把示例域名替换成自己的，并确认 DNS、80/443 入站和证书签发条件。若机器已有 Caddy，只追加站点块，不覆盖整份配置。修改后先 validate，再 reload：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

如果 Caddy 也在容器里，`127.0.0.1:4224` 就不再指向 DBX。应让两个容器共享合适的网络，代理到 DBX 的服务名和容器端口。这是部署位置不同，不是 Caddy 随机失灵。Caddy 反向代理文档

访问正式域名时，先检查证书，再验证登录、打开连接、执行查询。对于只供自己使用的管理器，继续走 SSH 或 VPN 也完全可以，不必为了“部署完整”一定公开域名。

检查连接和数据保存

先在 PostgreSQL 连接里执行：

SELECT current_database(), current_user, current_timestamp;

结果要与预期的库和账号一致。随后读取一张测试表，限制返回行数；不要刚连好就点击最大的业务表。保存连接后重启 DBX，再打开同一连接，确认状态和凭据仍在。最后关闭 SSH 隧道，验证正式入口是否仍可正常使用，或者确认仅隧道模式确实随隧道关闭而不可达。

观察资源可以用 `docker stats --no-stream`，检查磁盘用 `df -h`。空闲时占用低并不代表大查询也低；记录一次实际查表和导出时的峰值，更容易判断这台 VPS 是否合适。

常见故障可以按层次拆开：

| 现象 | 先查哪里 | | --- | --- | | SSH 隧道打开不了页面 | 容器状态、4224 回环监听、本地端口冲突 | | 域名返回 502 | Caddy 与 DBX 的相对位置、上游地址、容器是否退出 | | 登录成功但数据库超时 | Docker 网络、数据库地址、来源限制、TLS | | 连上却看不到表 | 当前数据库、Schema、元数据权限 | | 重启后连接消失 | 卷是否仍挂在 `/app/data`、Compose 项目名是否改变 |

备份与迁移

DBX 保存的连接和密钥需要备份，目标数据库里的业务数据也需要备份，两者分开安排。前者丢了会失去工作环境，后者丢了才是业务本身的数据损失。导出一份 CSV 只保存了那次查询结果，不能替代数据库备份。

更新之前保留旧镜像信息、Compose、入口密码和完整数据卷。新版本若迁移了内部配置，仅把 image 改回旧标签并不一定能退回；恢复旧程序时还需要与它匹配的升级前数据。把这一点写进自己的运维记录，远比记住安装命令有用。

后续增加第二种数据库时，沿用同样的顺序：网络可达、账号正确、权限合适、少量数据验证、重启复查。一个能随时打开、也能在换机器后恢复的工作台，才算真正部署好了。

保存完整 DBX 数据卷

备份实际挂载到 /app/data 的完整数据，连同部署配置和访问密码一起保护。SQLite 文件数据库另外保存业务文件；保存连接的工作台数据与所连接数据库的备份分别安排。

恢复后检查原连接

停止 DBX 后归档卷数据，在独立卷和不同端口恢复。用原访问密码登录，确认已保存的连接存在，再查询样例数据；连接目标仍需提供原来的网络路径与数据库凭据。

更新时保留网络配置

记录旧镜像版本、数据卷名称、外部 Docker 网络和代理上游。更新后检查网页登录、数据库查询与数据保存；回退时使用旧镜像和升级前的数据副本。