debug-toolbox Docker镜像文档

1. 镜像概述和主要用途

debug-toolbox 是一个集成多种系统调试工具的Docker镜像，旨在为容器化环境提供便捷的问题诊断和排查能力。该镜像通过预安装常用调试工具，简化了在隔离容器环境中进行网络分析、系统监控、文件操作及进程管理等调试任务的流程。
主要用途：作为轻量级调试环境，辅助开发和运维人员快速定位容器或宿主机的网络故障、资源瓶颈、文件系统异常等问题。

2. 核心功能和特性

2.1 工具集成

• 网络调试工具：包含 curl、wget、ping、traceroute、tcpdump、netstat、nslookup 等，支持网络连通性检测、流量抓包及DNS解析。
• 系统监控工具：集成 top、htop、ps、df、free、iostat 等，可实时查看CPU、内存、磁盘及进程资源占用情况。
• 文件操作工具：提供 vi、nano、cat、grep、tar、zip 等，支持文件编辑、搜索及压缩解压操作。
• 进程管理工具：包含 pstree、kill、pgrep 等，用于进程状态查询和管理。

2.2 特性

• 轻量级：基于精简基础镜像构建，减少资源占用。
• 跨平台兼容：支持主流Linux架构（如amd64、arm64），可在各类容器运行时（Docker、containerd）中使用。
• 即开即用：无需手动安装依赖，启动容器即可直接使用所有工具。

3. 使用场景和适用范围

3.1 典型使用场景

• 容器网络问题排查：检测容器间网络连通性、端口映射有效性及DNS解析异常。
• 系统资源瓶颈分析：定位容器CPU/内存占用过高、磁盘IO阻塞等资源问题。
• 文件系统检查：查看容器内文件结构、权限配置或日志文件内容。
• 跨环境一致性调试：在不同主机或CI/CD pipeline中提供统一的调试工具集，避免环境差异导致的排查障碍。

3.2 适用范围

• 开发人员：本地容器化应用调试。
• 运维人员：生产/测试环境容器故障排查。
• CI/CD流程：集成到自动化 pipeline 中作为故障诊断节点。

4. 使用方法和配置说明

4.1 基本使用（docker run 命令）

4.1.1 交互式运行

启动容器并进入交互式终端，直接使用工具：

docker run -it --rm pnnl-miscscripts/debug-toolbox /bin/bash

• -it：启用交互式终端。
• --rm：容器退出后自动删除，避免残留。

4.1.2 挂载宿主机目录

如需访问宿主机文件系统（如日志、配置文件），可挂载宿主机目录：

docker run -it --rm -v /var/log:/host/log pnnl-miscscripts/debug-toolbox /bin/bash

此时可通过 /host/log 路径访问宿主机 /var/log 目录。

4.1.3 共享宿主机网络

排查宿主机网络问题时，可使用宿主机网络命名空间：

docker run -it --rm --net=host pnnl-miscscripts/debug-toolbox /bin/bash

4.2 高级配置

4.2.1 环境变量

当前镜像暂未定义专用环境变量，如需自定义配置（如工具路径、默认编辑器），可通过启动命令覆盖：

docker run -it --rm -e EDITOR=vi pnnl-miscscripts/debug-toolbox /bin/bash

4.2.2 自定义命令执行

非交互式运行时，可直接指定调试命令（如执行网络检测后退出）：

docker run --rm pnnl-miscscripts/debug-toolbox ping -c 4 example.com

4.3 docker-compose 配置示例

将 debug-toolbox 集成到现有服务栈中，用于调试特定服务网络：

version: '3'
services:
  debug:
    image: pnnl-miscscripts/debug-toolbox
    tty: true  # 保持终端连接
    network_mode: "service:target-service"  # 共享目标服务网络命名空间
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 可选：挂载Docker socket调试容器
    depends_on:
      - target-service  # 目标调试服务

  target-service:  # 示例：待调试的目标服务
    image: nginx:alpine

5. 注意事项

• 工具列表：镜像内置工具集合可能随版本更新，完整工具清单请参考源码仓库：pnnl-miscscripts/miscscripts。
• 权限限制：容器默认以非root用户运行，部分系统级操作（如修改内核参数）需添加 --user root 提升权限。
• 资源占用：尽管镜像轻量，长期运行仍可能占用系统资源，建议调试完成后清理容器。

注：本镜像基于 pnnl-miscscripts/miscscripts 项目构建，详细构建流程及工具版本请参考该仓库文档。