CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本指南以 Woodpecker v3.17 官方文档 10-docker.md 为核心系统讲解 Docker 这一 Woodpecker 最原始、最成熟的 CI 执行后端的配置与运维方法。你将掌握如何通过 Docker 凭据助手接入私有镜像仓库、如何为单个步骤指定运行用户、如何用环境变量为流水线容器设置网络、卷与 CPU/内存资源上限以及镜像清理、Podman 兼容等实战技巧同时结合仓库源码理解每一项配置在底层是如何落到 Docker 容器上的。Docker 后端每个步骤一个独立容器Docker 是 Woodpecker 最早使用的执行后端original backend也是默认与最常用的后端。它的核心模型是Agent 收到的每一个流水线步骤step都会启动一个独立的 Docker 容器来执行步骤之间彼此隔离执行环境由镜像决定。从源码看该后端位于 pipeline/backend/docker/入口实现New()返回名为docker的引擎见 docker.go。其完整的生命周期由以下方法构成SetupWorkflow为整个流水线创建工作卷volume驱动为local和隔离网络Linux 上为bridge驱动Windows 上为nat并可启用 IPv6见 docker.goStartStep拉取镜像 → 创建容器 → 将容器接入流水线网络及额外指定网络 → 启动容器见 docker.goWaitStep/TailStep等待容器退出并读取退出码、是否 OOM 被杀同时实时跟随容器 stdout/stderr 日志DestroyStep/DestroyWorkflow按「先优雅停止 → 超时强制kill -9→ 删除容器」的顺序清理步骤容器再移除卷和网络见 docker.go。容器命名统一为wp_step.UUID见 convert.go默认日志驱动为json-file。掌握这一生命周期有助于理解后文各项配置分别作用于哪个阶段。私有镜像仓库Docker 凭据助手与 WOODPECKER_DOCKER_CONFIG当流水线步骤使用私有镜像时Woodpecker 支持通过 Docker 官方凭据助手docker-credential-helpers如docker-credential-ecr-login、docker-credential-gcr等安全地保存仓库凭据而不是把密码明文写进配置。使用步骤在运行 Woodpecker Server 的容器中安装对应的凭据助手。文档给出的官方做法是构建一个自定义镜像FROM woodpeckerci/woodpecker-server:latest-alpine RUN apk add -U --no-cache docker-credential-ecr-login在 Server 的 Docker 配置文件config.json中为相应镜像仓库配置该凭据助手通过环境变量WOODPECKER_DOCKER_CONFIG把这个配置文件传给 Server例如WOODPECKER_DOCKER_CONFIG/home/user/.docker/config.jsonWOODPECKER_DOCKER_CONFIG的完整说明见 10-server.md其作用是「为所有流水线配置一个特定的私有仓库配置」Configures a specific private registry config for all pipelines默认值为空。底层解析逻辑Server 端在启动时会读取该配置文件将其中的凭据转换为只读的全局 Registry 供流水线拉取镜像使用。实现位于 server/services/registry/filesystem.go解析 Docker 的config.json遍历CredentialHelpers中的凭据助手并调用其获取认证信息对AuthConfigs中 base64 编码的Auth字段进行解码还原出用户名密码最终把每个 registry 地址转换为model.Registry{Address, Username, Password, ReadOnly: true}。Agent 侧在StartStep拉取镜像时也会把步骤携带的认证信息 base64 编码为RegistryAuth附加到ImagePull请求见 convert.go 与 docker.go。Step 级配置指定运行用户Run user默认情况下Docker 后端启动步骤容器时不传--user标志因此容器使用镜像自身的默认用户通常是root。如果需要以特定用户/组运行步骤可以在步骤的backend_options.docker中设置user其语法与docker run --user完全一致steps: - name: example image: alpine commands: - whoami backend_options: docker: user: 65534:65534上面的例子以 UID/GID 均为65534即nobody用户的身份执行whoami实际输出会是nobody。源码实现该选项由 backend_options.go 定义type BackendOptions struct { User string mapstructure:user }parseBackendOptions通过mapstructure.WeakDecode把 YAML 中的backend_options.docker映射到该结构体随后在 convert.go 的toConfig中options.User被写入容器配置的User字段最终对应docker create/run --user参数。若不设置该字段为空字符串容器即使用镜像默认用户。运维技巧镜像与卷的清理Agent不会自动清理宿主机上的镜像。镜像的累积会持续占用磁盘因此官方建议由宿主机系统自行管理清理任务例如通过 cron 定期执行。⚠️ 以下命令具有破坏性且不可逆。官方文档强烈建议先在测试系统上验证这些命令再通过 cron 或其他自动化手段投入到生产环境。删除所有悬空未被任何容器引用的镜像docker image rm $(docker images --filter danglingtrue -q --no-trunc)删除 Woodpecker 遗留的卷以wp_前缀命名、且处于悬空状态docker volume rm $(docker volume ls --filter name^wp_* --filter danglingtrue -q)wp_前缀与源码中的命名约定一致步骤容器名为wp_step.UUIDconvert.go流水线工作卷同样以wp_开头创建。Podman 兼容尝试Woodpecker官方不提供对 Podman 的正式支持但可以通过将DOCKER_HOST环境变量指向 Podman 的 socket 来尝试使用 Podman 作为 Docker API 的实现。官方措辞是might work也许可以工作即不保证完全兼容。之所以可行是因为 Docker 后端本身就是通过 Docker Engine API 与守护进程通信的——源码中WOODPECKER_BACKEND_DOCKER_HOST的取值会回退到标准的DOCKER_HOST环境变量见 flags.go因此任何实现了 Docker API 的守护进程如 Podman 的兼容 socket都有可能被驱动。生产使用前务必充分测试。环境变量总览Docker 后端的全部配置项Docker 后端的所有配置均以WOODPECKER_BACKEND_DOCKER_为前缀作用于 Agent。下表逐项列出官方文档中的配置环境变量默认值作用WOODPECKER_BACKEND_DOCKER_NETWORK无把流水线所有步骤容器额外接入一个已存在的Docker 网络WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6false为流水线步骤使用的网络启用 IPv6需先保证 Docker daemon 支持 IPv6WOODPECKER_BACKEND_DOCKER_VOLUMES无逗号分隔的默认卷列表挂载到所有步骤容器WOODPECKER_BACKEND_DOCKER_APPARMOR_PROFILE无为步骤容器设置 AppArmor 安全配置文件不设置则由 Docker 采用默认 AppArmor 行为WOODPECKER_BACKEND_DOCKER_LIMIT_MEM_SWAP0单个步骤容器允许换到磁盘的最大内存字节0表示不限WOODPECKER_BACKEND_DOCKER_LIMIT_MEM0单个步骤容器可使用的最大内存字节0表示不限WOODPECKER_BACKEND_DOCKER_LIMIT_SHM_SIZE0/dev/shm允许的最大内存字节0表示不限WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_QUOTA0每个 CPU 周期内容器被限流前可使用的微秒数0表示不限WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SHARES0与其他容器相比的相对 CPU 权重WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SET无逗号分隔的 CPU 列表限制步骤容器可使用的 CPU/核心各配置的详细说明如下。WOODPECKER_BACKEND_DOCKER_NETWORK设置后每个流水线步骤容器在启动时除了加入流水线自建的隔离网络外还会被额外接入这个已有网络。请务必小心这会让不同流水线的容器之间互相可达破坏隔离性仅在确实需要跨流水线通信时才使用。从源码看该网络的接入发生在StartStep阶段docker.go且仅当步骤未指定network_mode时生效。WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6启用后SetupWorkflow创建流水线网络时会传入EnableIPv6标志见 docker.go。前提是宿主机 Docker daemon 已配置 IPv6 支持否则网络创建可能失败。WOODPECKER_BACKEND_DOCKER_VOLUMES逗号分隔的卷列表每个条目格式为宿主路径:容器路径[:读写模式]会挂载到所有步骤容器。官方文档给出的典型用例是让流水线容器使用宿主机自签 CA 证书与主机时区WOODPECKER_BACKEND_DOCKER_VOLUMES/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone源码会在 Agent 启动时校验每个卷定义是否合法非法条目直接报错退出错误信息形如invalid volume ... provided in WOODPECKER_BACKEND_DOCKER_VOLUMES见 config.go。生效时这些默认卷会与步骤自身声明的卷去重合并后写入HostConfig.Binds见 docker.go。WOODPECKER_BACKEND_DOCKER_APPARMOR_PROFILE为步骤容器指定 AppArmor 配置文件。源码在构造HostConfig时若该值非空会追加SecurityOpt: [apparmorprofile]见 convert.go。留空则由 Docker 按自身默认 AppArmor 策略处理。资源限制LIMIT_* 系列六个LIMIT_配置共同构成对单个步骤容器的资源上限在toHostConfig中被一一映射到 Docker 的container.Resources字段见 convert.goLIMIT_MEM→MemoryLIMIT_MEM_SWAP→MemorySwapLIMIT_SHM_SIZE→ShmSizeLIMIT_CPU_QUOTA→CPUQuotaLIMIT_CPU_SHARES→CPUSharesLIMIT_CPU_SET→CpusetCpus它们分别对应docker run的--memory、--memory-swap、--shm-size、--cpu-quota、--cpu-shares、--cpuset-cpus参数。示例WOODPECKER_BACKEND_DOCKER_LIMIT_MEM1073741824 # 1 GiB 内存上限 WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SET1,2 # 仅允许使用 CPU 1 和 2注意所有内存类配置单位为字节0表示不设限CPU 相关限制作用于容器调度可组合使用以达到精确的资源配额。未在文档中单列但源码支持的相关配置此外flags.go 还声明了以下同属 Docker 后端的 Agent 环境变量可与上文配置组合使用WOODPECKER_BACKEND_DOCKER_HOST回退到DOCKER_HOSTDocker socket 路径或 Docker 服务器 URLWOODPECKER_BACKEND_DOCKER_API_VERSION回退到DOCKER_API_VERSIONDocker API 版本留空表示最新WOODPECKER_BACKEND_DOCKER_CERT_PATH回退到DOCKER_CERT_PATH连接 Docker 服务器的 TLS 证书目录WOODPECKER_BACKEND_DOCKER_TLS_VERIFY回退到DOCKER_TLS_VERIFY是否校验 TLS默认trueWOODPECKER_BACKEND_DOCKER_STOP_TIMEOUT等待容器优雅停止的秒数默认20秒超时后强制kill -9对应 docker.go 中先 Stop 再 Kill的清理流程。TLS 证书加载逻辑见 docker.go当指定了backend-docker-cert时会读取ca.pem、cert.pem、key.pem构建带校验的 HTTPS 客户端并把InsecureSkipVerify设为!verifyTLS。小结Docker 后端以「一步骤一容器」的模型为 Woodpecker 提供了成熟稳定的隔离执行环境。实践中的要点可以归纳为私有镜像用 Docker 凭据助手 WOODPECKER_DOCKER_CONFIG安全接入Server 端会自动解析为只读全局 Registry步骤定制通过backend_options.docker.user以非 root 身份运行敏感步骤资源治理用WOODPECKER_BACKEND_DOCKER_LIMIT_*系列限制单个容器的内存、swap、/dev/shm与 CPU防止个别步骤拖垮 Agent运维兜底Agent 不自动清理镜像需宿主侧定时执行清理命令WOODPECKER_BACKEND_DOCKER_NETWORK与 PodmanDOCKER_HOST属于高风险/非官方支持的尝试务必在可控环境验证。延伸阅读官方配置文档10-docker.mdServer 端WOODPECKER_DOCKER_CONFIG说明10-server.md后端实现pipeline/backend/docker/docker.go、pipeline/backend/docker/convert.go配置解析pipeline/backend/docker/flags.go、pipeline/backend/docker/config.go步骤级选项pipeline/backend/docker/backend_options.go私有仓库配置解析server/services/registry/filesystem.go赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker Docker 后端Backend完全指南从私有镜像仓库到资源限制的配置实战Woodpecker Docker 后端Backend完全指南从私有镜像仓库到资源限制的配置实战 Woodpecker 是一个简单而强大的 CI/CD 引CI/CDDevOpsWoodpecker Docker 后端Backend完全指南镜像执行、凭据配置、Podman 兼容与镜像清理Woodpecker Docker 后端Backend完全指南镜像执行、凭据配置、Podman 兼容与镜像清理 导读 Docker 是 WoodpeckeCI/CDDevOpsWoodpecker 容器镜像仓库Registry配置完全指南私有镜像拉取、全局仓库与本地镜像构建Woodpecker 容器镜像仓库Registry配置完全指南私有镜像拉取、全局仓库与本地镜像构建 本篇指南以 Woodpecker CI/CD 引擎 vCI/CDDevOps上一篇【亲测免费】 掌控直播的利器OBS Blade下一篇【亲测免费】 数据集管理神器Dataset创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考