Woodpecker Local 后端完全指南：在 Agent 主机上直接执行流水线

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Local 是 Woodpecker 提供的三种执行后端之一它让woodpecker-agent直接把流水线命令运行在宿主机上无需 Docker 或 Kubernetes 运行时。本文以官方文档 docs/docs/30-administration/10-configuration/11-backends/30-local.md 为核心骨架结合 pipeline/backend/local 下的源码实现系统讲解 Local 后端的适用场景、安全边界、工作原理、Step 级配置Shell 与插件、环境变量以及克隆与进程管理细节帮助你判断是否该在生产环境启用它并正确配置与调优。什么是 Local 后端Local 后端是 Woodpecker 中执行流水线工作流workflow的一种方式。与其他后端不同它不做任何隔离流水线中的每条命令都直接运行在 Agent 进程所在的同一上下文中——同一个用户、同一个文件系统。这一特性决定了它的定位Local 后端适合私有、可信的部署场景例如个人开发机、内网构建服务器或者通过woodpecker-cli exec在本机快速验证流水线配置它不应该用于任何人都能提交代码或添加仓库的公开实例。从源码看Local 后端实现于 pipeline/backend/local/local.go核心类型local持有以下状态tempDir为每个工作流创建临时目录的根路径isolatedHome是否将HOME/USERPROFILE隔离到独立目录workflows以taskUUID为键的工作流状态表pluginGitBinary用于克隆步骤的plugin-git二进制路径os/arch宿主机的操作系统与架构用于选择平台并下载对应二进制。安全警告无隔离带来的风险官方文档对该后端使用了醒目danger级别的提示Local 后端在本地系统上执行流水线没有任何隔离。由于命令与 Agent 运行在完全相同的上下文相同用户、相同文件系统中一条恶意的流水线完全可能访问 Agent 自身的配置尤其是WOODPECKER_AGENT_SECRET这一连接凭据。一旦流水线作者拿到该值就能冒充 Agent 与服务器通信。因此使用 Local 后端必须遵守两条硬性约束只用于私有、可信环境代码与流水线内容必须可信不能开放给任意用户提交代码或添加仓库Agent 不要以特权用户root运行即使部署在私有环境也应使用普通用户账户启动 Agent以降低命令逃逸带来的破坏面。从实现层面看这一“无隔离”特性在 StartStep 中体现得很直接命令通过标准库os/exec直接Start()环境变量直接继承os.Environ()当前 Agent 进程的全部环境工作目录直接指向宿主文件系统上的工作区目录没有任何容器、沙箱或权限降级机制。工作原理临时目录与工作流生命周期Local 后端会在$TMPDIR下创建一个随机目录用于存放克隆的代码并执行命令。这一行为对应 SetupWorkflow 的实现调用os.MkdirTemp(e.tempDir, woodpecker-local-*)创建以woodpecker-local-为前缀的随机临时目录baseDir在baseDir下创建home目录baseDir/home权限0700在baseDir下创建workspace目录baseDir/workspace权限0700作为克隆与命令执行的工作区将整个状态以taskUUID为键存入workflows。其中home目录的作用是当启用了隔离 HOME 时每个工作流拥有独立的 HOMEgit的凭据文件netrc会写入这里避免污染 Agent 用户真实的~/.netrc。工作流结束时DestroyWorkflow 会先清理所有未回收的步骤状态关闭输出管道、取消命令再执行os.RemoveAll(state.baseDir)删除整个临时目录最后从workflows表中移除该任务。也就是说每个工作流的生命周期都对应一个随机的临时目录运行完毕后会被完整清除不会在宿主机上留下残留文件。CLI exec 的特殊工作区源码中还有一个值得注意的细节CLIWorkaroundExecAtDir见 local.go。当通过woodpecker-cli exec在本机执行流水线时该变量会被置为当前目录SetupWorkflow会跳过自动创建 workspace 的逻辑直接把当前所在目录作为工作区让用户像在本地终端一样运行流水线命令。这解释了为什么cli exec能在不克隆仓库的情况下直接使用工作目录里的代码。支持的平台Local 后端是 Woodpecker 中跨平台能力最广的执行后端。根据 Supported platforms 中的组件/平台矩阵Local 后端在 Linux、Windows、macOS、FreeBSD、OpenBSD 上均受支持服务器woodpecker-server与 Docker/Kubernetes 后端以 Linux 为中心而 Agent 与 CLI 通过 Local 后端可运行在更广泛的操作系统上在 macOS 与 OpenBSD 上Local 是唯一可用的执行后端Docker 后端在这两个平台上不可用Kubernetes 后端仅限 Linux。因此如果你需要在 macOS 开发机上运行 Agent或在 OpenBSD 上部署构建节点Local 后端是唯一选择。平台矩阵也说明官方为 Agent 发布了包括linux/amd64、linux/arm64、darwin/amd64、darwin/arm64、freebsd/amd64、freebsd/arm64、openbsd/amd64、openbsd/arm64、windows/amd64在内的预编译二进制可直接下载或自行构建Agent 后在宿主机上配置运行。启用方式如何让 Agent 使用 Local 后端要使用 Local 后端需要下载或自行构建Agent配置后端引擎并运行在宿主机器上。Agent 的后端引擎通过命令行参数--backend-engine或其环境变量WOODPECKER_BACKEND指定定义见 cmd/agent/core/flags.go默认值为auto-detect# 通过环境变量指定 export WOODPECKER_BACKENDlocal woodpecker-agent # 或通过命令行参数指定 woodpecker-agent --backend-enginelocal值得注意的是Local 后端还实现了“可用性自检”IsAvailable 会检查环境中是否存在WOODPECKER_IN_CONTAINER变量——如果 Agent 本身运行在容器内该变量被置位则判定 Local 后端不可用因为容器内没有真正的主机上下文这一行为也有对应的测试用例覆盖见 local_test.go。换句话说Local 后端要求 Agent 直接跑在裸机或虚拟机上而不是跑在容器里。Step 级配置Shell 与插件Shell用 image 指定命令解释器在 Local 后端中Step 的image字段不再表示容器镜像而是指定执行命令的 shell例如bash、fish等steps: - name: build image: bash commands: - go build ./... - go test ./...从源码 execCommands 可以看到Local 后端先用exec.LookPath(step.Image)检查该 shell 是否存在于宿主机$PATH中不存在则直接报错随后把commands列表拼装成脚本用该 shell 解释执行。不同 shell 的脚本生成逻辑集中在 genCmdByShell这是理解“支持哪些 shell”的关键image 值调用方式说明sh/bash/zsh-e -c scriptPOSIX 兼容 shell任一命令失败即退出-e其他未知 shell先探测再回退先执行 probeShellIsPosix 做 POSIX 兼容性探测x1 [ $x 1 ] ...通过后按-e -c调用失败则返回ErrNoPosixShellfish-c script每条命令后追加|| exit $status实现失败即停nu--commands scriptNushellpowershell/pwsh-noprofile -noninteractive -c ...并设置$ErrorActionPreference StopcmdWindows/D /C 临时脚本生成临时.cmd批处理脚本由于 cmd.exe 转义繁琐每条命令的 回显以 Base64 编码交由 Agent 内置的decode-base64子命令输出并逐条检查%ERRORLEVEL%脚本生成时还会为每条命令输出 命令回显行这与 Docker 后端的日志行为保持一致。此外脚本中的每条命令都会通过shellescape.Quote处理后再嵌入回显避免特殊字符破坏脚本。插件直接执行宿主机二进制Local 后端下插件Plugin的用法如下steps: - name: build image: /usr/bin/tree当没有提供commands时Step 按插件方式处理在 Local 后端语境下插件就是普通的可执行二进制文件。image字段指向该二进制可以是通过$PATH能查找到的名字也可以是绝对路径。例如上面示例会用/usr/bin/tree这个绝对路径直接运行。对应实现见 execPlugin后端调用exec.LookPath(step.Image)解析出真实二进制路径$PATH查找失败会报错然后在工作区目录下直接执行stdout 通过管道流式返回给 Agent 日志stderr 合并到 stdout。也就是说如果你习惯把构建逻辑封装成“插件”二进制在 Local 后端上只需把它放到 Agent 的$PATH中或使用绝对路径即可像容器插件一样被调用。关于 services官方文档明确提示目前 Local 后端不支持 services服务容器。这意味着依赖数据库、缓存等并行服务步骤的流水线无法在 Local 后端上运行相关支持情况可参见 Services 文档上游仍在跟踪中。设计流水线时若步骤间需要服务依赖应改用 Docker 或 Kubernetes 后端。环境变量Local 后端在 flags.go 中定义了以下配置项WOODPECKER_BACKEND_LOCAL_TEMP_DIR命令行参数--backend-local-temp-dir环境变量WOODPECKER_BACKEND_LOCAL_TEMP_DIR默认值系统默认临时目录os.TempDir()用于指定为工作流创建临时目录的根路径。每个工作流会在此目录下以woodpecker-local-*前缀创建随机子目录。如果你的$TMPDIR空间不足或希望把构建产物集中到特定磁盘如独立的 SSD 或内存盘可以显式配置export WOODPECKER_BACKEND_LOCAL_TEMP_DIR/var/tmp/woodpeckerWOODPECKER_BACKEND_LOCAL_ISOLATED_HOME命令行参数--backend-local-isolated-home环境变量WOODPECKER_BACKEND_LOCAL_ISOLATED_HOME默认值true控制是否为每个工作流设置独立的HOMEWindows 上同时设置USERPROFILE。启用时StartStep会追加HOMEbaseDir/home与USERPROFILEbaseDir/home到命令环境见 local.go克隆所需的git凭据.netrc/_netrc也会写入该隔离目录而非 Agent 用户真实家目录。官方文档原配置表中未列出的这一开关对防止流水线窃取用户 git 凭据至关重要建议保持默认开启。环境变量覆盖保护还有一个源码级的细节值得注意StartStep在注入 Step 环境变量时会跳过 notAllowedEnvVarOverwrites 中列出的变量——包括CI_NETRC_MACHINE、CI_NETRC_USERNAME、CI_NETRC_PASSWORD、CI_SCRIPT、HOME、SHELL、CI_WORKSPACE。也就是说流水线作者无法通过 step 的 environment 覆盖这些关键变量这保证了 HOME 隔离、netrc 注入和工作区路径不会被恶意篡改。克隆步骤与 git 凭据处理Local 后端的克隆步骤与 Docker 后端有显著差异因为它无法拉取plugin-git容器镜像改为使用plugin-git二进制检查 git 可用性execClone首先通过exec.LookPath(git)确认宿主机装有git见 clone.go查找或下载插件Agent 启动时loadClone会在$PATH中查找全局plugin-git二进制若找不到setupClone会根据宿主机的os/arch从上游下载最新版plugin-git二进制到隔离 home 目录Windows 上追加.exe后缀并赋予0755权限注入 netrc如果流水线环境包含CI_NETRC_MACHINE等变量writeNetRC会在隔离 home 下写入.netrcWindows 为_netrc权限0600克隆完成后无论成败都会删除该文件避免凭据残留。若禁用了隔离 HOME则跳过 netrc 写入此时依赖用户既有凭据执行克隆命令在 workspace 目录下直接启动plugin-git二进制完成克隆。注意如果流水线里 clone step 的image不是默认的plugin-git镜像名后端会打印警告并仍然使用自身的plugin-git二进制。这一机制保证了即使 Agent 环境没有容器运行时也能自动完成仓库克隆。进程管理与取消既然没有容器作为隔离边界Local 后端必须自己处理好进程树的管理防止流水线进程“逃逸”并残留在非 Windows 平台上newCmd 通过syscall.SysProcAttr{Setpgid: true}为每个命令创建独立的进程组取消时cmd.Cancel会向整个进程组发送SIGKILLsyscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)确保命令及其所有子进程一并终止且 kill 信号不会传播到 Agent 自身WaitStep通过cmd.Process.Wait()获取退出码DestroyStep会关闭输出管道并取消命令DestroyWorkflow在清理所有步骤后再删除临时目录。这套进程组机制保证了任务取消、超时或 Agent 关闭时本地进程不会被“孤儿化”滞留同时也不误伤 Agent 主进程。使用建议总结综合官方文档与源码实现使用 Local 后端时请牢记以下要点安全第一只在可信的私有环境使用Agent 用非特权用户运行不要把WOODPECKER_AGENT_SECRET暴露给不信任的流水线作者平台选择macOS / OpenBSD 上它是唯一后端Linux / Windows / FreeBSD 上则要与 Docker / Kubernetes 后端按需取舍——追求隔离与多租户安全选容器后端追求极简部署与本地调试选 LocalStep 写法image用于指定 shellbash、fish、powershell等或插件二进制$PATH名字或绝对路径不支持 services常用配置WOODPECKER_BACKENDlocal启用后端WOODPECKER_BACKEND_LOCAL_TEMP_DIR调整临时目录WOODPECKER_BACKEND_LOCAL_ISOLATED_HOME默认开启隔离 HOME 与 git 凭据调试利器配合woodpecker-cli exec可在当前目录直接运行流水线对应源码中的CLIWorkaroundExecAtDir机制是在提交到服务器前快速验证.woodpecker.yaml配置的推荐方式。Local 后端让 Woodpecker 的 Agent 摆脱了容器运行时的依赖成为跨平台覆盖最广、启动最快、最适合本地开发与可信私有构建的执行方案理解其“无隔离”的本质与源码实现细节是安全使用它的前提。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 本地流水线执行指南用 woodpecker-cli exec 调试与回放工作流Woodpecker 本地流水线执行指南用 woodpecker cli exec 调试与回放工作流 woodpecker cli exec 是 WoodpeCI/CDDevOpsSalt 的 salt runner 完全指南在 Master 上直接执行执行模块Salt 的 salt runner 完全指南在 Master 上直接执行执行模块 本文档由 salt.runners.salt runner 的官方 API运维配置管理后端TileLang 后端架构解析以垂直切片模型解耦语言方言、Pass 流水线与执行后端TileLang 后端架构解析以垂直切片模型解耦语言方言、Pass 流水线与执行后端 导读 TileLang 将一个目标后端target backend视编译器编程语言高性能计算人工智能深度学习上一篇virtCCA_sdk安全特性解析硬件派生密钥与TEE隔离技术下一篇LLM网关性能优化指南基于openeuler/gateway的负载均衡与缓存策略最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考