宝塔拨测探针 Docker 部署完整流程：绑定、更新、备份、卸载

宝塔拨测探针（bt-probe-agent）用 Docker 部署，核心就是写好一个 docker-compose.yml 然后 docker-compose up -d，之后登录宝塔账号完成设备绑定即可。本文把绑定、更新、备份恢复、卸载这四件事一次讲清。

Docker 部署探针需要满足什么条件

部署前确认三点：

项目	要求
Docker	20.10 或更高版本，包含 Docker Compose
系统架构	amd64 或 arm64
网络	可以访问宝塔拨测（t.bt.cn）和镜像仓库

如果国内服务器访问 Docker Hub 受限，先配置可用的镜像加速器（见文末常见问题）。

怎么用一条命令启动探针

先创建部署目录，在目录里建一个 docker-compose.yml：

services:
  bt-probe-agent:
    image: docker.cnb.cool/btpanel/bt-probe-agent:latest
    container_name: bt-probe-agent
    restart: always
    cap_add:
      - NET_RAW
    volumes:
      - /run/bt-probe-agent:/run/bt-probe-agent
      - /etc/bt-probe-agent:/etc/bt-probe-agent
      - /var/lib/bt-probe-agent:/var/lib/bt-probe-agent
    environment:
      - TBT_CONTROL_PLANE_URL=https://t.bt.cn
      - TBT_AGENT_ENDPOINT=wss://t.bt.cn/ws/agent
      - BT_PROBE_LOG_MODE=file
    healthcheck:
      test: ["CMD", "bt-probe-agent", "status"]
      interval: 60s
      timeout: 5s
      retries: 3
      start_period: 10s

在 docker-compose.yml 所在目录执行：

docker-compose up -d

容器首次启动会自动初始化 Agent 身份，生成配置文件和激活会话，不需要额外的初始化命令。

部署后怎么绑定设备

查看绑定信息：

docker exec bt-probe-agent cat /var/lib/bt-probe-agent/activation.json

输出里有两样东西可用：verification_uri_complete 是完整的绑定 URL，user_code 是设备码，二者选其一即可完成绑定。

{
  "agent_uuid": "9aaba087-...",
  "user_code": "6USA-A53X",
  "verification_uri_complete": "https://t.bt.cn/activate/6USA-A53X",
  "expires_at": 1784791588,
  "status": "waiting_login"
}

在浏览器打开 verification_uri_complete 对应的 URL，登录宝塔账号并完成设备绑定。绑定是探针生效的前提，绑定完成后探针才开始上报自检数据。

绑定 URL 过期了怎么办

docker-compose stop
docker-compose run --rm --entrypoint bt-probe-agent bt-probe-agent \
  public-activate
docker-compose up -d

再次查看 activation.json，用新的 URL 完成绑定。

日常维护命令

操作	命令
查看状态	docker exec bt-probe-agent bt-probe-agent status
查看日志	docker-compose logs -f bt-probe-agent
重启	docker-compose restart
停止	docker-compose stop

怎么更新探针

探针支持自动更新：主控下发更新指令后，容器内会自动下载并校验新版本、替换二进制文件，然后退出并由容器引擎重新启动，无需人工操作。

需要手动更新镜像时执行：

docker-compose pull
docker-compose up -d

数据保存在宿主机 bind mount 目录中，更新容器不会删除数据。

探针数据存在哪、怎么备份恢复

探针的数据分三处，都在宿主机上：

内容	宿主机位置
身份配置	/etc/bt-probe-agent/config.json
历史数据	/var/lib/bt-probe-agent/（自检数据、日志、激活会话）
运行时文件	/run/bt-probe-agent/（socket、PID、锁文件）

执行 docker-compose down 不会删除这些目录中的数据。

备份：

tar czf /backup/agent-backup.tar.gz \
  /etc/bt-probe-agent /var/lib/bt-probe-agent

恢复到新服务器：

tar xzf /backup/agent-backup.tar.gz -C /

恢复完成后保留原有探针身份，无需重新绑定。

怎么卸载探针

只停止服务并保留容器和数据：

docker-compose stop

删除容器但保留宿主机数据：

docker-compose down

要彻底卸载，先执行 docker-compose down，确认不再需要后手动删除以下目录：

/etc/bt-probe-agent
/var/lib/bt-probe-agent
/run/bt-probe-agent

删除以上目录后无法恢复探针身份和历史数据，删除前先做好备份。

部署探针后，你加入的是这样一个网络

探针部署并绑定后，就成为宝塔拨测网络里的一个节点，为 HTTP、PING、TCP、DNS 等监控任务提供多地域、多线路的探测能力。

下面是 2026-09-18 08:38 对 docs.bt.cn 发起的一次真实 HTTP 拨测结果：299 个节点全部成功，覆盖 43 个区域（其中大陆 30 个、港澳台及海外 13 个），所有节点 HTTP 状态码均为 200，官方聚合平均响应 508.3ms，中位数 354.2ms，最快 80.9ms（陕西-咸阳-电信），最慢 6149.5ms（新疆-伊犁-移动）。

上图为该次运行的结果页截图，展示按区域和运营商拆分的响应最快、响应最慢、平均响应。这正是你部署的探针节点所参与的网络——节点覆盖越广、越稳定，这类全国多节点检测的结果就越完整。

常见问题

拉取镜像超时怎么办？

国内网络拉取镜像超时时，在 /etc/docker/daemon.json 配置镜像加速器，然后重启 Docker 服务：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1panel.live",
    "https://hub.rat.dev"
  ]
}

systemctl restart docker

怎么确认探针已连接主控？

docker exec bt-probe-agent bt-probe-agent status

状态显示探针正在运行，且日志中没有 WSS 连接错误，即表示连接正常。

信息来源

本文部署流程以宝塔官方文档《使用 Docker 部署宝塔拨测探针》为准；实测数据来自宝塔拨测平台 t.bt.cn 的一次真实 HTTP 拨测运行（目标 docs.bt.cn，采集时间 2026-09-18 08:38）。