Headscale 容器镜像没有 shell 时如何用 -debug 变体进入容器排查问题？

Headscale 容器镜像没有 shell 时如何用 -debug 变体进入容器排查问题？

用 Docker 或 Podman 运行 Headscale 时，如果容器行为不符合预期，一个常见的阻碍是：标准容器镜像基于 distroless 构建，不含 shell 或任何调试工具，无法直接用docker exec ... sh进入容器查看内部状态。容器部署文档 给出的解决办法是使用-debug变体镜像（例如docker.io/headscale/headscale:x.x.x-debug）。该变体内置了一个极简 Busybox shell，并且与标准镜像互相兼容，可以在两者之间切换。

注意：docs/setup/install/container.md标注为社区维护文档，未经 headscale 开发者验证，内容可能过时或缺少必要步骤，执行前请结合自身版本核对。

准备条件

进入排查流程之前，需要满足文档中容器部署一节要求的前置条件：

• 宿主机装有容器运行时，如 Docker 或 Podman；
• 已创建 headscale 运行目录并准备配置：

mkdir -p ./headscale/{config,lib} cd ./headscale

• 已下载对应版本的示例配置并保存为$(pwd)/config/config.yaml，并按本地环境调整（配置项说明见配置文档）。

镜像地址按文档列出的两个来源，<VERSION>替换为你实际使用的版本（x.x.x即指代版本号）：

• Docker Hub：docker.io/headscale/headscale:<VERSION>
• GitHub Container Registry：ghcr.io/juanfont/headscale:<VERSION>

用 -debug 变体运行容器

按文档说明，运行 debug 容器与运行标准容器的命令完全相同，只需把镜像 tag 从docker.io/headscale/headscale:x.x.x换成docker.io/headscale/headscale:x.x.x-debug：

docker run \ --name headscale \ --detach \ --read-only \ --tmpfs /var/run/headscale \ --volume "$(pwd)/config:/etc/headscale:ro" \ --volume "$(pwd)/lib:/var/lib/headscale" \ --publish 127.0.0.1:8080:8080 \ --publish 127.0.0.1:9090:9090 \ --health-cmd "CMD headscale health" \ docker.io/headscale/headscale:<VERSION>-debug \ serve

要点说明：

• <VERSION>为必须替换的变量，填你部署的 headscale 版本号，其余命令与标准镜像部署完全一致；
• 8080 是 headscale 服务端口，9090 是 metrics 和 debug 端点端口。文档提示该端点应保持在内部网络，不要暴露到公网；
• 文档说明标准与 debug 两种容器互相兼容，可以交替使用：排查时用-debug，确认无误后换回标准镜像即可，数据卷./headscale/lib与配置./headscale/config不受影响。

文档同时提供了docker-compose.yaml写法，只需把其中的image字段换成带-debug的 tag，并确认<HEADSCALE_PATH>指向创建 headscale 目录的绝对路径。

进入 debug 容器执行命令

debug 容器的默认命令仍然是运行headscale（二进制位于容器内/ko-app/headscale），额外可用的工具是极简 Busybox shell。文档给出了三类用法：

启动一个交互式 shell：

docker run -it docker.io/headscale/headscale:x.x.x-debug sh

直接执行单条命令，例如文档中的示例：

docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app

在已运行的容器内执行命令——排查正在出问题的实例时使用docker exec -it，而不是重新启动一个容器：

docker exec -it headscale sh

（以上命令中的x.x.x统一替换为你的实际版本号。）

验证容器与服务状态

文档给出的验证路径如下：

docker logs --follow headscale # 跟踪容器日志 docker ps # 确认容器处于运行状态 curl http://127.0.0.1:8080/health # 确认 headscale 服务可用

如果需要更深入地查看内部状态，调试文档 说明 metrics 和 debug 端点（默认监听localhost:9090）提供 Go 运行时信息、已连接节点与待注册请求、当前 policy 与 DERPMap、Prometheus metrics 等，可直接查询：

curl http://localhost:9090/debug/

另外，把配置中的日志级别调到debug（log.level: debug）可以获得更详细的 headscale 日志，数据库查询调试则需同时设置database.debug: true且日志级别为debug或trace，详见调试文档。

限制与说明

• 文档明确 debug 容器只包含"minimalist Busybox shell"，没有完整的发行版工具集，排查手段以 shell 基本命令、ls /ko-app这类文件查看以及 headscale 自身的日志和 debug 端点为主；
• docker run -it ... sh启动的是一个全新的临时容器，适合验证镜像内环境；要排查线上正在运行的实例，应使用docker exec -it连接已有容器；
• 排查完成后，按文档的兼容性说明换回不带-debug的标准镜像运行即可，两种容器可以交替使用。