企业官网建设流程全解析

• CI/CD
• DevOps

本文是 Woodpecker CI/CD 引擎的发行版软件包安装实战指南，聚焦如何通过官方 DEB/RPM 软件包在 Debian/Ubuntu 与 CentOS/RHEL 上安装 server、agent、cli 三个组件，并通过 systemd 与示例环境文件完成配置，同时覆盖 Alpine、Arch Linux 等社区软件包以及 NixOS 上的声明式部署方案。读完本文，你将掌握从下载安装、系统服务管理到多后端（Docker/Podman）agent 注册的完整流程，并能对照仓库中的打包清单（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/目录下的打包清单，每个软件包的实际内容如下：

这些映射关系可以在 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":\s"v\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-cli；
• DEB 包使用apt --fix-broken install确保依赖自动补齐；RPM 包则直接由dnf install处理依赖解析；
• arm64 架构只需把文件名中的amd64换成arm64（DEB）或aarch64（RPM）即可，命名规则相同。

如果无法从官方 API 获取版本号（例如网络受限），也可以手动在 Releases 页面查看最新的 tag 后手工替换RELEASE_VERSION变量。

安装后的 systemd 服务与配置

软件包安装完成后会自动落盘 systemd 服务文件与示例环境文件。配置思路是：先把示例环境文件复制为正式环境文件，再填写你的真实配置值——服务在启动时会读取该环境文件，并在文件缺失时拒绝启动（ConditionFileNotEmpty与ConditionPathExists双重校验）。

server 服务与示例环境文件

官方文档给出的 server 单元文件如下（该文件与仓库中 nfpm/woodpecker-server.service 完全一致）：

[Unit] Description=WoodpeckerCI server Documentation=https://woodpecker-ci.org/docs/administration/server-config Requires=network.target After=network.target ConditionFileNotEmpty=/etc/woodpecker/woodpecker-server.env ConditionPathExists=/etc/woodpecker/woodpecker-server.env [Service] Type=simple EnvironmentFile=/etc/woodpecker/woodpecker-server.env User=woodpecker Group=woodpecker ExecStart=/usr/local/bin/woodpecker-server WorkingDirectory=/var/lib/woodpecker/ StateDirectory=woodpecker [Install] WantedBy=multi-user.target

对应地，示例环境文件位于/etc/woodpecker/woodpecker-server.env.example：

WOODPECKER_OPEN=true WOODPECKER_HOST=${WOODPECKER_HOST} WOODPECKER_GITHUB=true 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_OPEN=true：开启注册，允许任何拥有已配置 forge 账号的用户登录（默认关闭，即WOODPECKER_OPEN=false），详见 server 配置文档；
• WOODPECKER_HOST：对外可访问的服务器地址（如https://ci.example.com）；
• WOODPECKER_GITHUB=true与WOODPECKER_GITHUB_CLIENT/SECRET：启用 GitHub 作为 forge（OAuth2 认证），Woodpecker 本身不提供用户注册，用户全部来自所配置的 forge；
• WOODPECKER_AGENT_SECRET：server 与 agent 之间的共享密钥，是 agent 自动注册和鉴权的核心凭证，详见 server 配置文档。

agent 服务与示例环境文件

agent 的单元文件（与仓库中 nfpm/woodpecker-agent.service 一致）：

[Unit] Description=WoodpeckerCI agent Documentation=https://woodpecker-ci.org/docs/administration/configuration/agent Requires=network.target After=network.target ConditionFileNotEmpty=/etc/woodpecker/woodpecker-agent.env ConditionPathExists=/etc/woodpecker/woodpecker-agent.env [Service] Type=simple EnvironmentFile=/etc/woodpecker/woodpecker-agent.env User=woodpecker Group=woodpecker ExecStart=/usr/local/bin/woodpecker-agent WorkingDirectory=/var/lib/woodpecker/ StateDirectory=woodpecker [Install] WantedBy=multi-user.target

示例环境文件/etc/woodpecker/woodpecker-agent.env.example：

WOODPECKER_SERVER=localhost:9000 WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

其中：

• WOODPECKER_SERVER：server 的 gRPC 地址，默认端口 9000；
• WOODPECKER_AGENT_SECRET：必须与 server 配置的密钥一致。agent 启动时会用该令牌连接 server，server 识别并在数据库注册该 agent（如果之前未注册过），因此无需在 server 侧手工添加 agent，agent 会"自动注册"，详见 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 单元中User=woodpecker、WorkingDirectory=/var/lib/woodpecker/能生效的前提。

从构建角度，这些软件包由仓库 Makefile 中的bundle系列目标产出：先通过go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.45.0安装 nfpm，再分别以./nfpm/agent.yaml、./nfpm/server.yaml、./nfpm/cli.yaml为配置，对每个组件同时产出.deb与.rpm。因此你拿到的软件包本质上是"二进制 + systemd 单元 + 示例 env + 系统用户脚本"的标准捆绑包。

社区维护的软件包

除官方 DEB/RPM 外，多个发行版社区也维护了 Woodpecker 的软件包。官方文档特别声明：这些包并非 Woodpecker 项目维护，如有问题应联系对应发行版的打包维护者。主要来源包括：

• Alpine（Edge）：woodpecker包（pkgs.alpinelinux.org 可查）
• Arch Linux：官方仓库中的woodpecker包
• openSUSE：woodpecker软件包
• YunoHost：应用市场中的 Woodpecker 应用
• Cloudron：org.woodpecker_ci.cloudronapp应用
• Easypanel：WoodpeckerCI 模板
• Homebrew：woodpecker-cli（仅 CLI，不包含 server/agent）

对于 Arch、Alpine 等滚动发行版用户，社区包往往能更快跟进新版本；YunoHost、Cloudron、Easypanel 这类 PaaS 平台则提供了图形化的一键部署体验，适合不想手工管理 systemd 的用户。

NixOS：声明式部署 server 与 agent

在 NixOS 上安装 Woodpecker 的思路与二进制安装类似，但所有设置都以声明式配置表达，无需任何手工步骤。官方文档提供了一个开箱即用的完整示例，支持多个后端（示例中使用 Docker 后端配合 Podman socket），并且自动配置 Let's Encrypt 证书与 nginx TLS 反代：

{ config , ... }: let domain = "woodpecker.example.org"; in { # This automatically sets up certificates via let's encrypt security.acme.defaults.email = "acme@example.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_SECRET=XXXXXXXXXXXXXXXXXXXXXX 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段自动申请 Let's Encrypt 证书；nginx 以recommendedTlsSettings/recommendedOptimisation/recommendedProxySettings启用推荐级 TLS 与代理优化，把https://woodpecker.example.org反代到本机localhost:3007（即 server 的监听地址，由WOODPECKER_SERVER_ADDR=":3007"指定）。注意 server 的 gRPC 端口仍是默认的 9000，agent 通过WOODPECKER_SERVER=localhost:9000连接；
• 密钥管理：WOODPECKER_AGENT_SECRET这类敏感变量不写在environment里，而是通过environmentFile指向外部机密文件（格式为变量=值一行一个），server 与 agent 各用各的文件，这比把密钥硬编码进 Nix 配置更安全；
• agent 与 Podman：agent 通过extraGroups = [ "podman" ]获得访问 Podman socket 的权限，DOCKER_HOST=unix:///run/podman/podman.sock让 Docker 后端直接使用 Podman 兼容 socket，WOODPECKER_BACKEND="docker"指定执行后端，WOODPECKER_MAX_WORKFLOWS="4"将该 agent 的并行工作流上限提高到 4（默认值为 1，详见 agent 配置文档）；
• Podman DNS：virtualisation.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 配置参考：forge（GitHub/Gitea/GitLab 等）、开放注册、Agent Secret 轮换等全部变量；
• agent 配置参考：后端选择、并发上限、令牌类型（系统令牌 vs 单 agent 令牌）；
• 支持的平台与组件矩阵：确认你的操作系统/架构对应组件是走 Image、Binary 还是 DEB/RPM 路线，并核对 Docker/Kubernetes/Local 后端在各平台的可用性（例如 macOS 与 OpenBSD 只能使用 Local 后端）。

• CI/CD
• DevOps