CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本篇技术指南聚焦 Woodpecker CI/CD 引擎中的Local 后端local backend——它直接在 Agent 宿主机上执行流水线命令不依赖任何容器运行时。你将掌握它的适用场景与安全边界、完整的 Agent 配置方式、Step 级 Shell 与插件用法、临时目录与 HOME 隔离机制、plugin-git克隆原理以及通过woodpecker-cli exec --backend-engine local在本机调试流水线的实战方法。Local 后端是什么Woodpecker 的 Agent 通过后端backend来执行流水线中的 workflow。官方提供三类后端Docker、Kubernetes 和Local本文主题。其中 Local 后端的定位非常特殊The local backend executes pipelines on the local system without any isolation.也就是说Local 后端不启动容器、不创建隔离环境而是把流水线里的命令直接以 Agent 进程相同的用户身份、在相同的文件系统上下文中执行。它是 Docker/Kubernetes 这类容器化后端之外面向可信任的私有环境的轻量执行方案也是 macOS、OpenBSD 等无法运行容器运行时的平台上唯一可选的后端。从源码看Local 后端由 pipeline/backend/local/local.go 中的local类型实现它实现了types.Backend接口New()返回后端实例Name()返回local并随 Agent 一起通过 CLI 标志注册见 pipeline/backend/local/flags.go。安全模型为什么它只能用于可信环境文档开篇用:::danger强调了 Local 后端最核心的安全特性——无隔离。由此带来的风险是结构性的必须在使用前充分理解命令与 Agent 同上下文流水线里的每条命令都运行在与 Agent 相同的用户、相同的文件系统环境中。可窃取 Agent 机密一个恶意的流水线可以直接读取 Agent 进程能够访问到的所有配置尤其是共享密钥WOODPECKER_AGENT_SECRET——它用于 Agent 与 Server 之间的 gRPC 认证配置方式见 Agent 配置。一旦拿到该密钥攻击者就能冒充 Agent 与 Server 通信。可读写宿主机任意文件没有文件系统隔离流水线可以触碰 Agent 用户权限范围内的全部内容。因此官方给出三条明确的使用约束仅推荐用于代码与流水线都可信任的私有环境不应用于公共实例即任何人可以提交代码或添加仓库的环境Agent 不应以特权用户root运行以缩小命令所能触及的权限面。此外文档明确标注Local 后端目前不支持 services 服务容器见 Services 使用文档。如果流水线依赖数据库、缓存等服务容器请选用 Docker/Kubernetes 后端。进程隔离的取舍虽然 Local 后端不提供安全隔离但源码层面仍做了进程组级别的管理在 pipeline/backend/local/cmd_unix.go 中每个命令通过exec.CommandContext启动并设置Setpgid: true创建独立进程组取消Cancel时对整个进程组发送SIGKILL。这样做的目的是取消信号不会反向传播到 Agent 自身不会留下孤儿进程。也就是说进程是可管理的但进程与进程之间、进程与宿主机之间没有安全边界。这一点在评估风险时务必与容器后端的隔离能力区分开。适用平台与组件搭配Local 后端是跨平台能力最强的后端。根据 Supported platforms 中的后端支持矩阵后端LinuxWindowsmacOSFreeBSDOpenBSDDocker支持支持经 WSL2 / Windows 容器–WIP–Kubernetes支持––––Local支持支持支持支持支持文档明确说明在 macOS 与 OpenBSD 上运行 Agent 时Local 是唯一可用的后端。Windows 与 FreeBSD 也受支持。因此如果你的 CI 需要跑在 macOS 构建机上例如 iOS 打包、签名等场景Local 后端就是标准答案。在使用 Local 后端时还需要配套的plugin-git可执行文件而非容器镜像来完成克隆步骤。官方会为各平台发布plugin-git二进制如果你的环境中未安装Agent 也会在运行时自动下载详见下文克隆步骤一节。启用与运行Agent 配置使用 Local 后端需要在宿主机上直接运行 Agent 二进制下载或自行构建当前版本为 Woodpecker v3.17。由于不使用容器Agent 需要配置的最小项与其他后端一致WOODPECKER_SERVERlocalhost:9000 WOODPECKER_AGENT_SECRETyour-shared-secret-goes-here WOODPECKER_BACKEND_ENGINElocalWOODPECKER_SERVERServer 的 gRPC 地址默认localhost:9000WOODPECKER_AGENT_SECRETAgent 与 Server 共享的认证密钥可用openssl rand -hex 32生成WOODPECKER_BACKEND_ENGINE指定后端引擎为local。如果环境变量中设置了WOODPECKER_IN_CONTAINER即 Agent 自己运行在容器里Local 后端会判定自身不可用——源码 pipeline/backend/local/local.go 中的IsAvailable()先检查该环境变量再返回可用性。这从机制上防止了在容器中再跑无隔离命令的嵌套风险。通过 CLI 在本地执行除了运行 Agent你还可以直接用woodpecker-cli exec --backend-engine local在开发机上调试流水线文件无需启动 Server 与 Agent 即可验证工作流逻辑# 自动探测后端默认行为 woodpecker-cli exec .woodpecker/my-first-workflow.yaml # 显式选择 Local 后端 woodpecker-cli exec --backend-engine local .woodpecker/my-first-workflow.yaml更多exec参数如--repo-path、--env、--secrets-file、--metadata-file可参考 CLI 参考 与 本地执行指南。注意Local 后端直接在你的宿主机上执行命令不会复现容器镜像的环境本地调试结果可能与容器环境存在差异。工作原理临时目录、工作区与生命周期文档说明Local 后端会在$TMPDIR下的一个随机目录中存储克隆的代码并执行命令。源码 pipeline/backend/local/local.go 中的SetupWorkflow()给出了精确的实现通过os.MkdirTemp(e.tempDir, woodpecker-local-*)在临时目录下创建形如woodpecker-local-XXXX的随机目录baseDir在baseDir下创建home目录权限0o700作为隔离的 HOME在baseDir下创建workspace目录权限0o700作为工作区流水线命令都在其中执行。tempDir的来源是标志backend-local-temp-dir见下节workspaceDir会通过环境变量CI_WORKSPACE注入给每个步骤。整个 workflow 结束后DestroyWorkflow()会调用os.RemoveAll(state.baseDir)清理临时目录并清理残留的步骤状态。各步骤的生命周期由StartStep/WaitStep/TailStep/DestroyStep管理StartStep启动进程并捕获标准输出Stderr重定向到StdoutWaitStep轮询进程退出码由于输出管道需持续读取源码特意不用cmd.Wait()而是用Process.Wait()TailStep提供日志读取流DestroyStep负责关闭管道并取消未结束的进程。Step 特定配置Shell在 Local 后端中Step 的image字段不再表示容器镜像而是指定用来执行命令的 Shell。例如steps: - name: build image: bash commands: - echo hello from local backend - go build ./...源码 pipeline/backend/local/command.go 的execCommands()会先通过exec.LookPath(step.Image)校验该 Shell 是否存在于$PATH然后按 Shell 类型生成对应的执行参数genCmdByShell()image值生成的调用方式说明sh/bash/zshshell -e -c script使用-e任一命令失败即退出fishfish -c script每条命令后附加|| exit $statusnunu --commands scriptNushell 专用参数powershell/pwsh-noprofile -noninteractive -c ...设置$ErrorActionPreference StopcmdWindowscmd /D /C 生成的 .cmd 脚本通过 Base64 编码回显命令if not %ERRORLEVEL% 0 exit %ERRORLEVEL%对于未知的 Shell后端会先执行一个 POSIX 兼容性探测脚本probeShellIsPosix()——若探测失败则返回ErrNoPosixShell错误见 pipeline/backend/local/errors.go提示该 Shell 不支持并建议提交 issue。此外生成脚本时每条命令前会用shellescape.Quote转义后以echo cmd的方式回显便于在日志中看到正在执行的命令。Step 特定配置PluginsLocal 后端同样支持插件 Step但插件的语义被简化为直接执行一个可执行二进制。官方示例steps: - name: build image: /usr/bin/tree规则如下如果 Step没有提供commands则按插件的常规方式处理插件的image字段可以是$PATH中存在的二进制名如tree也可以是绝对路径如/usr/bin/tree。源码 pipeline/backend/local/plugin.go 的execPlugin()通过exec.LookPath(step.Image)解析二进制路径后直接启动并在workspaceDir下运行。这意味着你可以在宿主机上安装任意 CLI 工具如tree、rsync、curl等作为插件使用无需容器镜像。克隆步骤与 plugin-gitLocal 后端同样内置克隆clone步骤但实现方式与容器后端不同。相关逻辑在 pipeline/backend/local/clone.go启动时通过loadClone()在$PATH中查找全局plugin-git二进制若找到则直接复用若未找到setupClone()会在 workflow 开始时从 GitHub Releases 下载最新plugin-git二进制根据运行时os/arch匹配 asset下载到隔离的homeDir下并赋予0o755权限克隆命令在workspaceDir中执行。若流水线注入了CI_NETRC_MACHINE/CI_NETRC_USERNAME/CI_NETRC_PASSWORD私有仓库认证信息后端会向隔离的homeDir写入.netrcWindows 为_netrc权限0o600并在克隆完成后无条件删除该文件rm/del命令随克隆命令串联执行。注意克隆依赖宿主机已安装gitcheckGitCloneCap()会校验若 clone Step 的image不是默认的 git 克隆镜像后端会发出警告但仍使用自己的plugin-git执行克隆。环境变量与配置项Local 后端的环境变量配置整理如下BACKEND_LOCAL_TEMP_DIR项目值环境变量名WOODPECKER_BACKEND_LOCAL_TEMP_DIRCLI 标志--backend-local-temp-dir默认值系统默认临时目录os.TempDir()作用指定为 workflow 创建工作目录woodpecker-local-*的父目录对应源码见 pipeline/backend/local/flags.goValue: os.TempDir()Load()中通过c.String(backend-local-temp-dir)读取。在 Linux 上即$TMPDIR通常为/tmp如临时目录空间不足或有特殊挂载需求可显式指定WOODPECKER_BACKEND_LOCAL_TEMP_DIR/var/cache/woodpecker-localBACKEND_LOCAL_ISOLATED_HOME项目值环境变量名WOODPECKER_BACKEND_LOCAL_ISOLATED_HOMECLI 标志--backend-local-isolated-home默认值true作用将HOMEUnix与USERPROFILEWindows重定向到隔离的home目录默认开启隔离 HOME每个 workflow 拥有独立的home目录避免流水线读写 Agent 用户真实的$HOME如.ssh、.netrc、缓存等。同时隔离 HOME 是plugin-git的.netrc注入的前提见 pipeline/backend/local/clone.go 中writeNetRC()对isolatedHome的检查。不可覆盖的环境变量出于安全与一致性考虑Step 配置中的environment无法覆盖以下变量见 pipeline/backend/local/const.go 的notAllowedEnvVarOverwritesCI_NETRC_MACHINE CI_NETRC_USERNAME CI_NETRC_PASSWORD CI_SCRIPT HOME SHELL CI_WORKSPACE其中CI_NETRC_*与CI_SCRIPT由后端内部管理HOME/SHELL关系到隔离 HOME 与 Shell 行为CI_WORKSPACE指向工作区路径。StartStep 组装环境变量时local.go会先继承 Agent 自身环境os.Environ()再追加 Step 定义的可允许变量。实测验证仓库自带针对该后端的单元测试例如 pipeline/backend/local/local_test.go 中的TestIsAvailable验证了容器内不可用、容器外可用的判定逻辑command_test.go、const_test.go、cmd_unix_test.go分别覆盖了命令生成、环境变量白名单与进程组创建等行为。你可以在仓库根目录运行go test ./pipeline/backend/local/...以确认当前构建下 Local 后端的行为与本文描述一致。总结与最佳实践Local 后端是 Woodpecker 面向可信、私有、免容器场景的执行方案。综合文档与源码给出如下使用建议限定信任域只把它用于代码与流水线完全可信的私有环境公共实例、多租户环境一律不要使用。降低权限Agent 以非 root 的非特权用户运行如需写入特定目录通过权限与系统用户配合解决。保护密钥牢记WOODPECKER_AGENT_SECRET对本地执行的流水线是可读的密钥泄漏等同于 Agent 身份失守。留意能力边界Local 后端不支持 services 服务容器插件是宿主机二进制而非镜像须保证目标机器已安装相应工具。善用隔离开关保持WOODPECKER_BACKEND_LOCAL_ISOLATED_HOMEtrue默认并可通过WOODPECKER_BACKEND_LOCAL_TEMP_DIR把临时目录定向到空间充足的路径。本地调试优先开发阶段用woodpecker-cli exec --backend-engine local快速验证流水线逻辑同时意识到其环境与容器环境的差异。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker Local 后端实战指南在宿主机上无容器运行流水线的原理、配置与安全边界Woodpecker Local 后端实战指南在宿主机上无容器运行流水线的原理、配置与安全边界 Woodpecker 的 Local本地后端 允许 AgeCI/CDDevOps3天让你的安卓手机脱胎换骨Universal Android Debloater 终极优化指南3天让你的安卓手机脱胎换骨Universal Android Debloater 终极优化指南 想象一下你的手机就像一个装满杂物的房间——厂商预装的那些永远CI/CDDevOpsWoodpecker Local 后端完全指南在 Agent 主机上直接执行流水线Woodpecker Local 后端完全指南在 Agent 主机上直接执行流水线 Local 是 Woodpecker 提供的三种执行后端之一它让 wooCI/CDDevOps上一篇Pixel Art转CSS代码终极指南box-shadow优化与压缩秘籍下一篇Radon高级技巧如何自定义复杂度阈值和报告格式提升代码质量分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考