upbound/docker-delve

dlv 极简镜像文档

镜像概述和主要用途

本镜像是基于 chainguard/static 的极简容器镜像，内置 dlv（Delve）CLI 工具。dlv 是 Go 语言官方推荐的调试器，支持断点调试、变量监视、调用栈分析等功能。本镜像旨在提供轻量、安全、开箱即用的 Go 程序调试环境，适用于开发、测试及容器化场景下的 Go 应用调试。

核心功能和特性

核心功能

• 内置 dlv CLI 工具，支持 Go 程序的本地调试、远程调试及核心调试能力（断点、变量查看、调用栈追踪等）。
• 基于 chainguard/static 静态基础镜像，可直接运行于各类容器环境（无需额外依赖动态链接库）。

主要特性

• 轻量极简：基于 chainguard/static 构建，镜像体积极小（通常 < 20MB），减少资源占用。
• 安全强化：继承 chainguard 系列镜像的安全特性，包含最小化***面、非 root 用户运行（默认）、镜像签名验证等安全加固。
• 即开即用：无需手动安装 dlv，拉取镜像后可直接执行调试命令。
• 多平台支持：支持 amd64、arm64 等主流架构（具体依赖 chainguard/static 基础镜像的平台支持）。

使用场景和适用范围

典型场景

• 本地 Go 开发调试：在开发环境中快速启动 dlv，调试本地 Go 项目（无需在宿主机安装 dlv）。
• 容器化 Go 应用调试：直接在容器内调试运行中的 Go 应用（如微服务容器、K8s Pod 内应用）。
• CI/CD 流程集成：在自动化测试或构建流程中，通过 dlv 执行调试相关的自动化步骤（如条件断点验证、异常场景复现）。
• 资源受限环境：适用于边缘设备、嵌入式系统等资源有限场景，轻量镜像降低部署成本。

使用方法和配置说明

镜像拉取

从容器仓库拉取镜像（以 Docker Hub 为例，实际仓库需替换为镜像源地址）：

bash
docker pull <镜像仓库地址>/dlv-static:latest

基本使用

1. 验证 dlv 版本

运行容器并执行 dlv version 命令，验证工具可用性：

bash
docker run --rm <镜像仓库地址>/dlv-static:latest dlv version

输出示例：

Delve Debugger
Version: 1.21.0
Build: $Id: xxxxxxxxxx $

2. 调试本地 Go 程序

将本地 Go 项目代码挂载到容器内，使用 dlv debug 启动调试会话：

bash
# 假设本地 Go 项目路径为 ./my-go-app，入口文件为 main.go
docker run --rm -v $(pwd)/my-go-app:/app -w /app <镜像仓库地址>/dlv-static:latest dlv debug main.go

此时容器内会启动 dlv 交互式调试会话，支持设置断点（b main.main）、运行（c）、下一步（n）等标准调试命令。

3. 远程调试容器内 Go 程序

如需通过宿主机 IDE（如 VS Code、Goland）远程连接容器内的 dlv 调试会话，需配置 dlv 以无头模式（headless）运行并暴露调试端口：

bash
# 启动容器，暴露调试端口 2345，挂载项目代码并启动 headless 调试
docker run --rm -p 2345:2345 -v $(pwd)/my-go-app:/app -w /app <镜像仓库地址>/dlv-static:latest \
  dlv debug main.go --headless --listen=0.0.0.0:2345 --api-version=2 --accept-multiclient

宿主机 IDE 可通过 localhost:2345 连接调试会话，实现远程断点调试。

Docker Compose 配置示例

通过 docker-compose.yml 定义调试环境，简化多容器或复杂挂载场景的配置：

yaml
version: '3.8'
services:
  dlv-debug:
    image: <镜像仓库地址>/dlv-static:latest
    volumes:
      - ./my-go-app:/app  # 挂载本地 Go 项目代码
    working_dir: /app
    ports:
      - "2345:2345"  # 暴露调试端口
    command: ["dlv", "debug", "main.go", "--headless", "--listen=0.0.0.0:2345", "--api-version=2"]

启动调试环境：

bash
docker-compose up

配置参数说明

dlv 工具支持丰富的命令参数，常用参数如下（使用时需追加到容器启动命令中）：

注意事项

1. 文件权限：挂载本地代码时，需确保容器内用户（默认非 root）对挂载目录有读权限，可通过 chmod 调整宿主机目录权限或添加 --user root 参数（仅调试场景使用，生产环境避免）。
2. 端口安全：远程调试时，--listen=0.0.0.0:2345 会暴露端口到公网，建议通过防火墙限制访问，或仅在可信环境中使用。
3. Go 版本兼容：dlv 版本需与目标 Go 程序的编译版本匹配（如 Go 1.21 需 dlv 1.21+），建议使用镜像标签指定版本（如 dlv-static:1.21）而非 latest。
4. 容器网络：调试容器内运行的 Go 应用时，需确保 dlv 与目标进程在同一网络命名空间（可通过 --net=container:<target-container> 共享网络）。