CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本文是 Woodpecker CI/CD 引擎的发行版软件包安装实战指南聚焦如何通过官方 DEB/RPM 软件包在 Debian/Ubuntu 与 CentOS/RHEL 上安装 server、agent、cli 三个组件并通过 systemd 与示例环境文件完成配置同时覆盖 Alpine、Arch Linux 等社区软件包以及 NixOS 上的声明式部署方案。读完本文你将掌握从下载安装、系统服务管理到多后端Docker/Podmanagent 注册的完整流程并能对照仓库中的打包清单nfpm 配置与 systemd 单元文件理解安装背后的实现细节。软件包概览官方渠道与支持的平台Woodpecker 官方发布两种系统软件包格式DEB面向 Debian/Ubuntu 系列发行版RPM面向 CentOS/RHEL/Fedora 系列发行版DEB 和 RPM 软件包针对linux/amd64与linux/arm64两种架构构建。如果你运行在其他架构上如arm/v7、riscv64、ppc64le等官方建议改用二进制 tarball 或容器镜像完整的能力对照表见 支持的平台与组件矩阵。需要特别注意的是并非每个组件在所有平台上都可用woodpecker-server的 Web UI、API、webhook 接收与调度逻辑以 Linux 为中心而 agent 与 CLI 借助 Local 后端可运行在更广的操作系统上。该文档中的组件/平台矩阵明确列出了每个操作系统架构上各组件是发布Image容器镜像、Binary二进制还是两者都有DEB/RPM 软件包仅覆盖其中linux/amd64与linux/arm64两行。软件包内容速览根据仓库nfpm/目录下的打包清单每个软件包的实际内容如下软件包二进制安装路径附带文件woodpecker-server/usr/local/bin/woodpecker-serversystemd 单元woodpecker-server.service、示例环境文件woodpecker-server.env.examplewoodpecker-agent/usr/local/bin/woodpecker-agentsystemd 单元woodpecker-agent.service、示例环境文件woodpecker-agent.env.examplewoodpecker-cli/usr/local/bin/woodpecker-cli无这些映射关系可以在 nfpm/server.yaml、nfpm/agent.yaml 与 nfpm/cli.yaml 中直接核实例如 server 包会把二进制安装到/usr/local/bin/woodpecker-server把单元文件放到/usr/local/lib/systemd/system/把示例环境文件放到/etc/woodpecker/并创建属主为woodpecker用户、权限 0750 的/var/lib/woodpecker/数据目录。通过 apt / dnf 安装官方软件包预编译的软件包发布在项目的 GitHub Releases 页面。由于软件包体积较小且依赖简单官方推荐直接用发行版自带的包管理器安装。以下是官方文档给出的完整安装流程RELEASE_VERSION$(curl -s https://api.github.com/repos/woodpecker-ci/woodpecker/releases/latest | grep -Po tag_name:\sv\K[^]) # Debian/Ubuntu (x86_64) curl -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 # CentOS/RHEL (x86_64) sudo dnf install https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}-${RELEASE_VERSION}.x86_64.rpm命令要点说明第一条命令先从 GitHub API 拉取最新 tag 号并去掉前缀v得到形如3.18.0的版本号供后续下载 URL 拼接使用花括号展开{server,agent,cli}会一次下载三个组件包woodpecker-server、woodpecker-agent、woodpecker-cliDEB 包使用apt --fix-broken install确保依赖自动补齐RPM 包则直接由dnf install处理依赖解析arm64 架构只需把文件名中的amd64换成arm64DEB或aarch64RPM即可命名规则相同。如果无法从官方 API 获取版本号例如网络受限也可以手动在 Releases 页面查看最新的 tag 后手工替换RELEASE_VERSION变量。安装后的 systemd 服务与配置软件包安装完成后会自动落盘 systemd 服务文件与示例环境文件。配置思路是先把示例环境文件复制为正式环境文件再填写你的真实配置值——服务在启动时会读取该环境文件并在文件缺失时拒绝启动ConditionFileNotEmpty与ConditionPathExists双重校验。server 服务与示例环境文件官方文档给出的 server 单元文件如下该文件与仓库中 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.target对应地示例环境文件位于/etc/woodpecker/woodpecker-server.env.exampleWOODPECKER_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}实际操作是执行sudo cp /etc/woodpecker/woodpecker-server.env.example /etc/woodpecker/woodpecker-server.env然后把${...}占位符替换成真实值。几个关键变量的含义WOODPECKER_OPENtrue开启注册允许任何拥有已配置 forge 账号的用户登录默认关闭即WOODPECKER_OPENfalse详见 server 配置文档WOODPECKER_HOST对外可访问的服务器地址如https://ci.example.comWOODPECKER_GITHUBtrue与WOODPECKER_GITHUB_CLIENT/SECRET启用 GitHub 作为 forgeOAuth2 认证Woodpecker 本身不提供用户注册用户全部来自所配置的 forgeWOODPECKER_AGENT_SECRETserver 与 agent 之间的共享密钥是 agent 自动注册和鉴权的核心凭证详见 server 配置文档。agent 服务与示例环境文件agent 的单元文件与仓库中 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示例环境文件/etc/woodpecker/woodpecker-agent.env.exampleWOODPECKER_SERVERlocalhost:9000 WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET}其中WOODPECKER_SERVERserver 的 gRPC 地址默认端口 9000WOODPECKER_AGENT_SECRET必须与 server 配置的密钥一致。agent 启动时会用该令牌连接 serverserver 识别并在数据库注册该 agent如果之前未注册过因此无需在 server 侧手工添加 agentagent 会自动注册详见 agent 配置文档。配置完成后执行sudo systemctl enable --now woodpecker-server或woodpecker-agent即可开机自启并立即启动服务。安装脚本做了什么以仓库源码为证包安装过程中创建的woodpecker系统用户并非手工完成而是由 nfpm 打包时配置的 preinstall 脚本 nfpm/woodpecker-system-user.preinstall.sh 负责脚本会先检查woodpecker组与用户是否存在若不存在则用groupadd --system woodpecker创建系统组再以useradd --system --gid woodpecker --no-create-home --home-dir /var/lib/woodpecker --shell /sbin/nologin woodpecker创建不可登录的系统用户。这正是 systemd 单元中Userwoodpecker、WorkingDirectory/var/lib/woodpecker/能生效的前提。从构建角度这些软件包由仓库 Makefile 中的bundle系列目标产出先通过go install github.com/goreleaser/nfpm/v2/cmd/nfpmv2.45.0安装 nfpm再分别以./nfpm/agent.yaml、./nfpm/server.yaml、./nfpm/cli.yaml为配置对每个组件同时产出.deb与.rpm。因此你拿到的软件包本质上是二进制 systemd 单元 示例 env 系统用户脚本的标准捆绑包。社区维护的软件包除官方 DEB/RPM 外多个发行版社区也维护了 Woodpecker 的软件包。官方文档特别声明这些包并非 Woodpecker 项目维护如有问题应联系对应发行版的打包维护者。主要来源包括AlpineEdgewoodpecker包pkgs.alpinelinux.org 可查Arch Linux官方仓库中的woodpecker包openSUSEwoodpecker软件包YunoHost应用市场中的 Woodpecker 应用Cloudronorg.woodpecker_ci.cloudronapp应用EasypanelWoodpeckerCI 模板Homebrewwoodpecker-cli仅 CLI不包含 server/agent对于 Arch、Alpine 等滚动发行版用户社区包往往能更快跟进新版本YunoHost、Cloudron、Easypanel 这类 PaaS 平台则提供了图形化的一键部署体验适合不想手工管理 systemd 的用户。NixOS声明式部署 server 与 agent在 NixOS 上安装 Woodpecker 的思路与二进制安装类似但所有设置都以声明式配置表达无需任何手工步骤。官方文档提供了一个开箱即用的完整示例支持多个后端示例中使用 Docker 后端配合 Podman socket并且自动配置 Lets Encrypt 证书与 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 ]; }; }逐段解读这份配置证书与反代security.acme段自动申请 Lets Encrypt 证书nginx 以recommendedTlsSettings/recommendedOptimisation/recommendedProxySettings启用推荐级 TLS 与代理优化把https://woodpecker.example.org反代到本机localhost:3007即 server 的监听地址由WOODPECKER_SERVER_ADDR:3007指定。注意 server 的 gRPC 端口仍是默认的 9000agent 通过WOODPECKER_SERVERlocalhost:9000连接密钥管理WOODPECKER_AGENT_SECRET这类敏感变量不写在environment里而是通过environmentFile指向外部机密文件格式为变量值一行一个server 与 agent 各用各的文件这比把密钥硬编码进 Nix 配置更安全agent 与 Podmanagent 通过extraGroups [ podman ]获得访问 Podman socket 的权限DOCKER_HOSTunix:///run/podman/podman.sock让 Docker 后端直接使用 Podman 兼容 socketWOODPECKER_BACKENDdocker指定执行后端WOODPECKER_MAX_WORKFLOWS4将该 agent 的并行工作流上限提高到 4默认值为 1详见 agent 配置文档Podman DNSvirtualisation.podman.defaultNetwork.settings.dns_enabled true为容器网络启用内置 DNS便于流水线中服务之间通过主机名互相访问同时需要在防火墙的podman0接口上放行 53 端口TCP/UDP以保证 DNS 查询可达。注意services.woodpecker-server与services.woodpecker-agents这两个 NixOS 模块并非 Woodpecker 开发者维护而是由 nixpkgs 仓库维护遇到问题应在 nixpkgs 的 issue 追踪器中报告。更多配置选项可通过 NixOS Search 检索woodpecker关键词获得。官方文档还提示Awesome Woodpecker 页面见仓库中的 docs/src/pages/awesome.md收集了更多 NixOS 进阶用法例如在流水线中复用 runner 的 nix-store 缓存。下一步继续配置安装只是第一步安装完成后建议接着阅读server 配置参考forgeGitHub/Gitea/GitLab 等、开放注册、Agent Secret 轮换等全部变量agent 配置参考后端选择、并发上限、令牌类型系统令牌 vs 单 agent 令牌支持的平台与组件矩阵确认你的操作系统/架构对应组件是走 Image、Binary 还是 DEB/RPM 路线并核对 Docker/Kubernetes/Local 后端在各平台的可用性例如 macOS 与 OpenBSD 只能使用 Local 后端。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 发行包安装指南DEB/RPM 包、systemd 服务与 NixOS 声明式部署Woodpecker 发行包安装指南DEB/RPM 包、systemd 服务与 NixOS 声明式部署 Woodpecker CI/CD 引擎除了容器镜像和二CI/CDDevOpsWoodpecker 官方分发包DEB/RPM安装与 systemd 部署实战从软件包安装到 NixOS 声明式配置Woodpecker 官方分发包DEB/RPM安装与 systemd 部署实战从软件包安装到 NixOS 声明式配置 本文聚焦 Woodpecker 的CI/CDDevOpsWoodpecker 发行包安装指南DEB/RPM 官方包、Linux 二进制手动安装与 NixOS 声明式部署Woodpecker 发行包安装指南DEB/RPM 官方包、Linux 二进制手动安装与 NixOS 声明式部署 本篇指南以 Woodpecker 官方发行包CI/CDDevOps上一篇AsNumpy 快速上手指南仅改 import 即可将 NumPy 代码迁移到昇腾 NPU下一篇openpilot模型训练数据增强模拟极端天气与路况的方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考