tdeutsch/debugcontainer

调试容器 (Debugcontainer)

!https://github.com/tuxpeople/docker-debugcontainer/actions/workflows/release.yml/badge.svg !Github Last Commit Badge !Docker Pull Badge !Docker Stars Badge !Docker Size Badge

基于Alpine Linux构建的全面调试容器，集成60多种网络、性能测试和故障排除工具，用于调试容器基础设施，尤其是Kubernetes环境。

快速参考

• 代码仓库： https://github.com/tuxpeople/docker-debugcontainer
• 问题提交地址： https://github.com/tuxpeople/docker-debugcontainer/issues
• 支持的架构： amd64 和 arm64
• 基础镜像： Alpine Linux 3.22.2

镜像标签

• latest - 最新标记版本
• x.y.z、x.y、x - 语义化版本标签（例如：1.0.0、1.0、1）
• nightly - 每日定时任务自动构建
• devel - 主分支的最新版本（每次推送时构建）

多 registry 可用

bash
# Docker Hub
docker pull tdeutsch/debugcontainer:latest

# GitHub Container Registry
docker pull ghcr.io/tuxpeople/debugcontainer:latest

包含工具

网络与诊断

tcpdump, nmap, mtr, iperf3, netcat, socat, arping, ethtool, tcptraceroute, ngrep, bind-tools, dnsperf, sslscan

容器与 Kubernetes

kubectl, crane, flux, ytt, imgpkg, oras

数据库客户端

mariadb-client, azure-cli

存储与文件系统

minio-client, nfs-utils, rsync

性能测试

fio, hdparm, ioping, iozone, speedtest-cli

通用工具

bash, curl, wget, jq, yq, vim, git, screen, tmux, htop, lsof, tree, mc, p7zip

使用示例

快速调试会话

在运行的Kubernetes Pod中启动交互式shell：

bash
kubectl run debugcontainer --rm -it --image=tdeutsch/debugcontainer:latest -- /bin/bash

网络故障排除

测试连接性和DNS解析：

bash
# 运行容器进行网络调试
docker run -it --rm tdeutsch/debugcontainer:latest /bin/bash

# 在容器内 - 测试DNS
nslookup example.com
dig example.com

# 测试连接
ping -c 3 8.8.8.8
mtr google.com

# 端口扫描
nmap -p 80,443 example.com

# 带宽测试
iperf3 -c iperf.example.com

作为Sidecar抓包

部署为sidecar以捕获另一个容器的流量：

yaml
apiVersion: v1
kind: Pod
metadata:
  name: app-with-debug
spec:
  containers:
  - name: app
    image: your-app:latest
  - name: debugger
    image: tdeutsch/debugcontainer:latest
    securityContext:
      capabilities:
        add: ["NET_ADMIN", "NET_RAW"]
    command: ["/bin/sleep", "inf"]

然后进入sidecar并捕获流量：

bash
kubectl exec -it app-with-debug -c debugger -- tcpdump -i any -w /tmp/capture.pcap

存储性能测试

测试磁盘I/O性能：

bash
docker run -it --rm -v /path/to/test:/workdir tdeutsch/debugcontainer:latest /bin/bash

# 在容器内
cd /workdir
/scripts/hdd-perf.sh

OCI Registry操作

使用ORAS操作容器registry：

bash
docker run -it --rm tdeutsch/debugcontainer:latest /bin/bash

# 推送制品到registry
oras push myregistry.io/myartifact:v1 ./file.txt

# 拉取制品
oras pull myregistry.io/myartifact:v1

# 检查ORAS版本
cat /etc/oras-version

数据库连接测试

bash
docker run -it --rm tdeutsch/debugcontainer:latest /bin/bash

# 测试MySQL/MariaDB连接
mysql -h database.example.com -u user -p

# Azure CLI操作
az login
az account list

使用场景

• Kubernetes调试：部署为故障排除Pod以诊断集群问题
• 网络分析：捕获和分析服务间流量
• 性能测试：基准测试存储、网络和计算资源
• Sidecar诊断：与应用容器一起运行，无需修改应用镜像即可调试
• CI/CD测试：在流水线中使用以验证连接性和服务
• 学习工具：在隔离环境中实验各种DevOps和网络工具

本地构建

bash
# 为本地平台构建
docker build -t debugcontainer:local .

# 为多平台构建
docker buildx build --platform linux/amd64,linux/arm64 -t debugcontainer:local .

贡献

欢迎贡献！请在GitHub上提交issue或pull request。

注意：本项目使用规范提交（conventional commits）进行自动版本控制。提交消息必须遵循以下格式：

• feat: 用于新功能（次要版本更新）
• fix: 用于bug修复（补丁版本更新）
• chore:、docs:、refactor: 用于非发布变更

许可证

详见LICENSE文件。