使用 Docker 部署宝塔拨测探针

本文介绍如何使用 Docker 部署宝塔拨测探针（bt-probe-agent），并完成设备绑定、日常维护和卸载。

前置要求

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

提示

如果国内服务器访问 Docker Hub 受限，请先配置可用的镜像加速器。

部署探针

项目提供的 docker-compose.yml 使用 bind mount 将数据保存在宿主机中。请先获取探针项目源码，进入项目目录后执行：

docker-compose up -d

容器首次启动时会自动初始化 Agent 身份，生成 config.json 和激活会话，无需执行额外的初始化命令。

手动构建镜像

如需在本地构建镜像，请先安装 Go 环境，然后执行：

# 编译二进制文件
CGO_ENABLED=0 GOOS=linux go build -ldflags "-s -w" -o bt-probe-agent .

# 构建镜像
docker build -f Dockerfile.local -t docker.cnb.cool/btpanel/bt-probe-agent:latest .

# 启动容器
docker-compose up -d

绑定设备

执行以下命令查看绑定信息：

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

输出示例：

{
  "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，或使用 user_code，完成设备绑定。

绑定 URL 过期或需要重新绑定

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

再次查看 activation.json，并使用新的 URL 完成绑定。已有 config.json 时，无需传入端点参数，探针会自动复用配置中的地址。

日常维护

操作	命令
查看状态	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/

历史数据目录中包含 selfcheck.db、日志和 activation.json；运行时目录中包含 socket、PID 和锁文件。

备份与恢复

备份：

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

恢复到新服务器：

mkdir -p /etc/bt-probe-agent /var/lib/bt-probe-agent
tar xzf /backup/agent-backup.tar.gz -C /etc/bt-probe-agent

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

卸载探针

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

docker-compose stop

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

docker-compose down

如需彻底卸载，请先执行 docker-compose down，确认不再需要配置、身份和历史数据后，再手动删除以下目录：

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

注意

删除以上目录后无法恢复探针身份和历史数据。请在删除前完成备份。

常见问题

拉取镜像超时怎么办？

国内网络拉取 Docker Hub 镜像超时时，可根据服务器和 Docker 环境配置可用的镜像加速器。修改 /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 连接错误，即表示连接正常。