Woodpecker 官方分发包（DEB/RPM）安装与 systemd 部署实战：从软件包安装到 NixOS 声明式配置

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本文聚焦 Woodpecker 的 Linux 分发安装路径先介绍官方 DEB/RPM 软件包的获取与安装方式再结合仓库内真实的 nfpm 打包配置与 systemd 单元文件讲解 server/agent 的目录布局、环境变量配置与开机自启最后给出 Alpine、Arch Linux、NixOS 等社区打包方案的完整实践含一份可复用的 NixOS 声明式配置。读完本文你将能够在 Debian/Ubuntu、CentOS/RHEL 与 NixOS 上分别以包管理器或声明式配置的方式交付一套可随系统启动的 Woodpecker CI/CD 环境。一、官方软件包概览DEB 与 RPMWoodpecker 官方提供两种 Linux 分发包格式DEB适用于 Debian / Ubuntu 及其衍生发行版RPM适用于 CentOS / RHEL / Fedora 及 openSUSE 等基于 RPM 的发行版。DEB 和 RPM 包均为linux/amd64与linux/arm64两个架构构建。若你的平台属于其他架构如linux/arm/v7、linux/riscv64、linux/s390x等官方不会提供对应的软件包此时应改用二进制 tarball 或容器镜像具体支持矩阵见 Supported platforms。需要说明的是DEB/RPM 包覆盖的是 Woodpecker 的三个核心组件它们分工如下表格引自 Supported platforms组件作用woodpecker-serverWeb UI、API、Webhook 接收器、流水线调度器woodpecker-agent通过后端Docker、Kubernetes、Local执行流水线工作流woodpecker-cli与 server 交互的命令行工具其中woodpecker-server与woodpecker-agent都会随包附带一个 systemd 服务单元文件和一个环境变量示例文件这是本文后续部署的核心woodpecker-cli则是纯命令行工具无需常驻服务。二、安装步骤以包管理器完成三个组件官方预编译软件包发布在 GitHub Releases 页面可直接用发行版自身的包管理器安装。安装前先动态获取最新版本号依赖curl与grepRELEASE_VERSION$(curl -s https://api.github.com/repos/woodpecker-ci/woodpecker/releases/latest | grep -Po tag_name:\sv\K[^])Debian / Ubuntux86_64curl -fLOOO https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}_${RELEASE_VERSION}_amd64.deb sudo apt --fix-broken install ./woodpecker-{server,agent,cli}_${RELEASE_VERSION}_amd64.deb说明-fLOOO中的多个-O配合 shell 大括号展开会分别把woodpecker-server、woodpecker-agent、woodpecker-cli三个 DEB 文件以远端文件名下载到当前目录apt --fix-broken install用于在安装本地.deb文件时自动补齐依赖并解决冲突若为linux/arm64将文件名中的amd64替换为arm64即可。CentOS / RHELx86_64sudo dnf install https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}-${RELEASE_VERSION}.x86_64.rpmdnf可以直接安装远程 RPM 地址大括号展开同样会一次安装 server、agent、cli 三个包arm64架构将文件名替换为aarch64版本即可。三、软件包落盘布局从 nfpm 打包配置看安装产物三个组件的 RPM/DEB 均由仓库根目录下的 nfpm 目录中的 nfpm 配置生成。以 nfpm/server.yaml 为例server 包的 contents 定义如下contents: - src: ./dist/server/linux_amd64/woodpecker-server dst: /usr/local/bin/woodpecker-server - src: ./nfpm/woodpecker-server.service dst: /usr/local/lib/systemd/system/woodpecker-server.service - src: ./nfpm/woodpecker-server.env.example dst: /etc/woodpecker/woodpecker-server.env.example - dst: /var/lib/woodpecker/ type: dir file_info: owner: woodpecker group: woodpecker mode: 0750agent.yaml 的结构与之对称把woodpecker-server替换为woodpecker-agent。因此安装完软件包后你会看到以下关键路径路径说明/usr/local/bin/woodpecker-serverserver 可执行文件/usr/local/bin/woodpecker-agentagent 可执行文件/usr/local/lib/systemd/system/woodpecker-server.serviceserver 的 systemd 单元/usr/local/lib/systemd/system/woodpecker-agent.serviceagent 的 systemd 单元/etc/woodpecker/woodpecker-server.env.exampleserver 环境变量示例/etc/woodpecker/woodpecker-agent.env.exampleagent 环境变量示例/var/lib/woodpecker/数据目录属主woodpecker权限0750两个包的preinstall脚本都指向 nfpm/woodpecker-system-user.preinstall.sh该脚本会幂等地创建系统用户与组#!/bin/sh set -e # Create woodpecker group if it doesnt exist if ! getent group woodpecker /dev/null 21; then groupadd --system woodpecker fi # Create woodpecker user if it doesnt exist if ! getent passwd woodpecker /dev/null 21; then useradd \ --system \ --gid woodpecker \ --no-create-home \ --home-dir /var/lib/woodpecker \ --shell /sbin/nologin \ woodpecker fi也就是说安装包会先创建名为woodpecker的系统用户home 指向/var/lib/woodpecker、shell 为/sbin/nologin禁止交互登录随后 systemd 服务便以该用户身份运行。从源码结构看这种专用系统用户 专用数据目录 systemd 托管的组合保证了服务进程以最小权限运行数据统一收敛在/var/lib/woodpecker/下。四、配置 server复制示例环境文件并调整参数包安装完成后server 并不会立即运行需要先把示例环境文件复制为实际生效的配置sudo cp /etc/woodpecker/woodpecker-server.env.example /etc/woodpecker/woodpecker-server.env sudo vim /etc/woodpecker/woodpecker-server.env仓库中的示例文件 nfpm/woodpecker-server.env.example 实际内容是占位模板文档给出了一个可运行的参考配置WOODPECKER_OPENtrue WOODPECKER_HOST${WOODPECKER_HOST} WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENT${WOODPECKER_GITHUB_CLIENT} WOODPECKER_GITHUB_SECRET${WOODPECKER_GITHUB_SECRET} WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET}各变量的含义与源码中的取值约定如下参数解析集中在 cmd/server/flags.goWOODPECKER_OPENtrue允许用户自助注册账号对应open开关见 cmd/server/flags.goWOODPECKER_HOSTserver 的完整对外地址格式为scheme://host[/prefix path]见 cmd/server/flags.go。这是必填项cmd/server/server.go 中会对它做格式校验要求scheme://hostname形式且一般不应是 localhost因为 Forge 回调、Webhook 与 badge 都需要访问它WOODPECKER_GITHUBtrue启用 GitHub 作为 Forge代码托管平台驱动WOODPECKER_GITHUB_CLIENT/WOODPECKER_GITHUB_SECRET在 GitHub OAuth App 中申请的 Client ID 与 Secret见 cmd/server/flags.goWOODPECKER_AGENT_SECRETserver 与 agent 之间的共享认证密钥server 与所有 agent 必须配置为同一个值见 cmd/server/flags.go。除WOODPECKER_HOST外还有一个常用的监听参数WOODPECKER_SERVER_ADDR默认值为:8000见 cmd/server/flags.go。如果你的 8000 端口被占用可在此文件中覆盖。生产环境建议始终为WOODPECKER_HOST使用 HTTPS 地址并让反向代理如 Nginx、Caddy终结 TLS 后再转发到 server 监听端口。server 的 systemd 单元解读仓库 nfpm/woodpecker-server.service 中的单元与文档展示的一致关键点拆解[Unit] DescriptionWoodpeckerCI server Documentationhttps://woodpecker-ci.org/docs/administration/server-config Requiresnetwork.target Afternetwork.target ConditionFileNotEmpty/etc/woodpecker/woodpecker-server.env ConditionPathExists/etc/woodpecker/woodpecker-server.env [Service] Typesimple EnvironmentFile/etc/woodpecker/woodpecker-server.env Userwoodpecker Groupwoodpecker ExecStart/usr/local/bin/woodpecker-server WorkingDirectory/var/lib/woodpecker/ StateDirectorywoodpecker [Install] WantedBymulti-user.targetRequiresnetwork.target/Afternetwork.target确保网络就绪后再启动避免启动即因网络不可用而失败ConditionFileNotEmpty与ConditionPathExists两个条件同时满足才启动服务即/etc/woodpecker/woodpecker-server.env必须存在且非空。这意味着忘记复制并填写环境文件时服务会直接跳过启动而不是以错误配置运行这是包内自带的防呆设计EnvironmentFile/etc/woodpecker/woodpecker-server.env把环境文件中的KEYVALUE注入服务进程环境server 的所有配置均以WOODPECKER_*环境变量读取Userwoodpecker/Groupwoodpecker以最小权限系统用户运行WorkingDirectory/var/lib/woodpecker/StateDirectorywoodpecker工作目录与状态目录统一指向数据目录systemd 会在需要时自动创建StateDirectory并调整属主。五、配置 agent注册到 server 并选择执行后端agent 的配置方式与 server 对称sudo cp /etc/woodpecker/woodpecker-agent.env.example /etc/woodpecker/woodpecker-agent.env sudo vim /etc/woodpecker/woodpecker-agent.env文档给出的示例配置WOODPECKER_SERVERlocalhost:9000 WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET}要点说明WOODPECKER_SERVERagent 要连接的 server 的 gRPC 地址。默认 server 的 gRPC 监听端口为9000HTTP/Web 界面默认端口为8000因此示例为localhost:9000跨机器部署时请替换为 server 的实际地址WOODPECKER_AGENT_SECRET必须与 server 端配置的WOODPECKER_AGENT_SECRET完全一致。配置正确后agent 启动时会自动向 server 注册worker 注册无需手工录入 agent 信息。此外agent 侧还有两个高频变量值得了解解析位于 cmd/agent/core/flags.goWOODPECKER_MAX_WORKFLOWS旧名WOODPECKER_MAX_PROCS仍兼容单个 agent 上可并行执行的工作流数量上限见 cmd/agent/core/flags.goWOODPECKER_BACKENDagent 的执行后端可选docker、kubernetes、local等见 cmd/agent/core/flags.go。后端可用性取决于宿主操作系统例如 Docker 与 Kubernetes 后端依赖 Linux 容器运行时而 macOS/OpenBSD 上只能使用 Local 后端完整矩阵见 Supported platforms。agent 的 systemd 单元解读仓库 nfpm/woodpecker-agent.service 中的单元与文档一致[Unit] DescriptionWoodpeckerCI agent Documentationhttps://woodpecker-ci.org/docs/administration/configuration/agent Requiresnetwork.target Afternetwork.target ConditionFileNotEmpty/etc/woodpecker/woodpecker-agent.env ConditionPathExists/etc/woodpecker/woodpecker-agent.env [Service] Typesimple EnvironmentFile/etc/woodpecker/woodpecker-agent.env Userwoodpecker Groupwoodpecker ExecStart/usr/local/bin/woodpecker-agent WorkingDirectory/var/lib/woodpecker/ StateDirectorywoodpecker [Install] WantedBymulti-user.target结构上与 server 单元完全同构同样要求环境文件存在且非空、同样以woodpecker用户运行、同样将工作目录指向/var/lib/woodpecker/。六、启动并验证服务完成 server 与 agent 的环境文件配置后启用并启动两个服务sudo systemctl enable --now woodpecker-server sudo systemctl enable --now woodpecker-agentenable --now同时完成开机自启与立即启动。随后可以按需检查状态systemctl status woodpecker-server systemctl status woodpecker-agent journalctl -u woodpecker-server -f # 实时跟踪 server 日志 journalctl -u woodpecker-agent -f # 实时跟踪 agent 日志排障要点若服务显示condition check resulted in ...而被跳过说明环境文件不存在或为空回到第四、五节补齐配置若 agent 无法注册优先核对两端的WOODPECKER_AGENT_SECRET是否一致以及WOODPECKER_SERVER指向的端口默认 gRPC9000是否可达若WOODPECKER_HOST未配置或格式非法server 会在启动阶段直接报错退出见 cmd/server/server.go。七、社区软件包主流发行版的现成方案除官方 DEB/RPM 外Woodpecker 社区也为多种发行版维护了软件包。需要注意这些包由各发行版的打包维护者负责并非 Woodpecker 官方创建遇到问题时应向对应发行版的维护者反馈。常见来源包括AlpineEdge通过 Alpine 官方软件包仓库搜索woodpecker安装Arch Linux通过官方软件仓库搜索woodpecker安装openSUSEopenSUSE 软件站提供woodpecker软件包YunoHost提供一键应用woodpeckerCloudron应用商店中的woodpecker应用模板Easypanel提供woodpeckerci模板Homebrew提供woodpecker-cli仅 CLI 组件。如果你是 macOS 用户Homebrew 渠道可以快速获得woodpecker-cli客户端但注意它只打包 CLIserver/agent 仍需通过其他方式如二进制 tarball、容器镜像部署。八、NixOS 声明式安装一份可复用的完整配置NixOS 用户不需要手动复制环境文件或启用 systemd 服务——一切都在 NixOS 配置中声明式完成。文档强调理论上 NixOS 安装与二进制安装非常相似并支持多种后端实践中所有设置都在 NixOS 配置中声明式指定无需任何手工步骤。注意NixOS 上的services.woodpecker-server与services.woodpecker-agents模块由 nixpkgs 维护不属于 Woodpecker 官方若遇到问题请在 nixpkgs 仓库提交 bug 报告。以下配置演示了server agent Podman 后端 Nginx TLS的完整组合{ config , ... }: let domain woodpecker.example.org; in { # This automatically sets up certificates via lets encrypt security.acme.defaults.email acmeexample.com; security.acme.acceptTerms true; # Setting up a nginx proxy that handles tls for us services.nginx { enable true; openFirewall true; recommendedTlsSettings true; recommendedOptimisation true; recommendedProxySettings true; virtualHosts.${domain} { enableACME true; forceSSL true; locations./.proxyPass http://localhost:3007; }; }; services.woodpecker-server { enable true; environment { WOODPECKER_HOST https://${domain}; WOODPECKER_SERVER_ADDR :3007; WOODPECKER_OPEN true; }; # You can pass a file with env vars to the system it could look like: # WOODPECKER_AGENT_SECRETXXXXXXXXXXXXXXXXXXXXXX environmentFile /path/to/my/secrets/file; }; # This sets up a woodpecker agent services.woodpecker-agents.agents.docker { enable true; # We need this to talk to the podman socket extraGroups [ podman ]; environment { WOODPECKER_SERVER localhost:9000; WOODPECKER_MAX_WORKFLOWS 4; DOCKER_HOST unix:///run/podman/podman.sock; WOODPECKER_BACKEND docker; }; # Same as with woodpecker-server environmentFile [ /var/lib/secrets/woodpecker.env ]; }; # Here we setup podman and enable dns virtualisation.podman { enable true; defaultNetwork.settings { dns_enabled true; }; }; # This is needed for podman to be able to talk over dns networking.firewall.interfaces.podman0 { allowedUDPPorts [ 53 ]; allowedTCPPorts [ 53 ]; }; }配置要点逐项解析TLS 与反向代理security.acme自动申请 Lets Encrypt 证书services.nginx把https://${domain}反向代理到本机localhost:3007。注意 server 的WOODPECKER_SERVER_ADDR被显式设为:3007与代理目标一致对应 cmd/server/flags.go 中的 HTTP 监听参数默认值本为:8000server 声明services.woodpecker-server.enable true后通过environment传入WOODPECKER_HOST对外 HTTPS 地址、WOODPECKER_SERVER_ADDR监听端口与WOODPECKER_OPEN开放注册。机密类变量如WOODPECKER_AGENT_SECRET不建议写死在 Nix 配置里而是通过environmentFile指向一个权限收紧的 secrets 文件每行KEYVALUE这与 systemd 的EnvironmentFile语义一致agent 声明services.woodpecker-agents.agents.docker定义了一个名为docker的 agentextraGroups [ podman ]让 agent 进程加入podman组从而有权限访问 Podman socketDOCKER_HOST unix:///run/podman/podman.sock指定使用 Podman 提供的 Docker 兼容 socket即以docker后端驱动 Podman 执行流水线WOODPECKER_BACKEND docker显式选择后端对应 cmd/agent/core/flags.goWOODPECKER_MAX_WORKFLOWS 4限制并行工作流数为 4对应 cmd/agent/core/flags.goWOODPECKER_SERVER localhost:9000指向 server 的 gRPC 端口Podman 网络virtualisation.podman开启 DNSdns_enabled true并放行podman0接口的 53 端口UDP/TCP使流水线容器之间可以通过 DNS 名称互相访问典型场景是服务容器与步骤容器联动。除上述模块外NixOS 上还有大量 Woodpecker 相关配置选项可通过 NixOS Search 的woodpecker关键字检索例如利用 runner 的 nix-store 在流水线中复用 Nix 缓存的用法可以参考 Awesome Woodpecker 页面的相关资源。九、延伸阅读与源码依据本文所有命令、systemd 单元、环境变量与 NixOS 配置均可在当前仓库中直接核验软件包打包定义nfpm/server.yaml、nfpm/agent.yaml、nfpm/cli.yamlsystemd 单元与脚本nfpm/woodpecker-server.service、nfpm/woodpecker-agent.service、nfpm/woodpecker-system-user.preinstall.sh环境变量示例nfpm/woodpecker-server.env.example、nfpm/woodpecker-agent.env.exampleserver 参数解析cmd/server/flags.goagent 参数解析cmd/agent/core/flags.go平台与后端支持矩阵Supported platforms。安装完成后建议继续阅读 10-configuration 目录下的配置文档为你的 ForgeGitHub、Gitea、GitLab 等、数据库与执行后端做精细化调优。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 发行包安装指南DEB/RPM 官方包、Linux 二进制手动安装与 NixOS 声明式部署Woodpecker 发行包安装指南DEB/RPM 官方包、Linux 二进制手动安装与 NixOS 声明式部署 本篇指南以 Woodpecker 官方发行包CI/CDDevOpsxrpld 安装部署指南基于 XRP Ledger 官方 DEB/RPM 包的一站式部署方案xrpld 安装部署指南基于 XRP Ledger 官方 DEB/RPM 包的一站式部署方案 本文以 docs/install.md https://link区块链CANN OAM-Tools rpm/deb 安装包实战指南从源码编译、依赖声明到安装卸载全流程CANN OAM Tools rpm/deb 安装包实战指南从源码编译、依赖声明到安装卸载全流程 OAM Tools华为 CANN 昇腾 AI 处理器的运维运维性能剖析根因分析可观测性健康检查CANN上一篇Davinci数据视图完全指南自定义SQL模板与权限管理终极教程下一篇如何用文言文编程打造独特社交网络应用wenyan-lang社交媒体开发终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考