在 NixOS 上声明式部署 Woodpecker CI/CD:services.woodpecker-server 与 Agent 完整配置指南

原创2026-09-26 22:15:011,942 阅读
文章标签:CI/CDDevOps

在 NixOS 上声明式部署 Woodpecker CI/CD:services.woodpecker-server 与 Agent 完整配置指南

本篇技术指南面向使用 NixOS 的开发者与运维人员,讲解如何通过 NixOS 的声明式配置(services.woodpecker-server 与 services.woodpecker-agents 模块)一次性部署完整的 Woodpecker CI/CD 实例:包括 Let's Encrypt 证书、nginx 反向代理、服务端、以 Podman 为后端的执行代理,以及防火墙与 DNS 网络细节。读完本文,你将能够把 Woodpecker 的部署从"手工配置 + 手动启动"升级为"一条 nixos-rebuild switch 即可复现、可版本化、可回滚"的基础设施即代码方案,并理解每个关键环境变量在 server/agent 通信与后端执行链路中的实际作用。

NixOS 模块是什么:声明式安装的定位与维护边界

在开始配置之前,需要明确一个重要的边界:Woodpecker 的 NixOS 模块并不是由 Woodpecker 官方开发者维护的,而是由 NixOS 社区在 nixpkgs 中维护。原文档明确指出,如果遇到问题,应在 nixpkgs 仓库提交 bug report,而不是 Woodpecker 主仓库。这意味着:

  • 模块的可用性与行为以你所使用的 nixpkgs 频道(channel)为准;
  • 模块更新节奏与 Woodpecker 主项目发布节奏可能不完全同步;
  • 需要同时关注 Woodpecker 的环境变量文档(本文所引用的 server 配置 与 agent 配置)与 nixpkgs 模块选项两套信息。

从部署形态上看,NixOS 安装方式"在理论上与二进制安装(binary install)非常相似,并支持多种后端"。区别在于实践层面:配置全部以声明式方式写在 NixOS 配置中,无需任何手工步骤——不需要手动下载二进制、不需要手动写 systemd unit、不需要手动开端口,nixos-rebuild switch 之后一切就绪。

这一特点与仓库中另一条安装路径形成鲜明对比:使用 Docker Compose 部署时,你需要手动维护 compose 文件、volume、镜像 tag 与环境变量;而在 NixOS 上,镜像、服务单元、网络与证书全部由 Nix 表达。

部署前需要理解的架构与端口规划

NixOS 模块的配置语义直接对应 Woodpecker 的组件模型。根据 架构文档 与 管理总览,Woodpecker 由两部分必要组件与一个可选组件构成:

  • server:提供 Web UI、接收 forge(Git 托管平台)的 webhook、对外暴露 REST API,并解析仓库中的 YAML 流水线配置;
  • agent:负责真正执行 workflow(流水线步骤),通过 gRPC 连接到 server 领取任务、回传执行状态与日志;多个 agent 可以共存,各自独立配置并行数、后端类型等;
  • autoscaler(可选):按需在云厂商创建/销毁 VM 以处理积压的构建任务。

server 与 agent 之间走 gRPC,两者使用不同的监听端口:

变量 默认值 作用 依据
WOODPECKER_SERVER_ADDR :8000 服务端 HTTP 监听地址(Web UI / API / webhook) 10-server-config.md
WOODPECKER_GRPC_ADDR :9000 服务端 gRPC 监听地址(供 agent 连接) 10-server-config.md
WOODPECKER_SERVER(agent 侧) localhost:9000 agent 连接 server 的 gRPC 地址 15-agent-config.md

理解这一点非常关键:NixOS 示例中 nginx 代理的是 HTTP 端口(localhost:3007),而 agent 连接的则是 gRPC 端口(localhost:9000)。两条通道分开监听,反向代理(nginx/Traefik/Caddy)通常只负责 HTTP 通道的 TLS 终结,gRPC 通道是否加密由 WOODPECKER_GRPC_SECURE 等变量决定(默认 false,即明文 gRPC)。

一份可直接落地的完整 NixOS 配置

下面是原文档提供的完整配置骨架(configuration.nix 或独立 import 的模块文件)。它一次完成五件事:Let's Encrypt 证书、nginx TLS 反向代理、woodpecker-server、以 docker 后端 + Podman socket 运行的 woodpecker-agent、Podman 容器网络 DNS 与防火墙放行。

{ config
, ...
}:
let
  domain = "woodpecker.example.org";
in
{
  # 自动通过 let's encrypt 申请证书
  security.acme.defaults.email = "acme@example.com";
  security.acme.acceptTerms = true;
  security.acme.certs."${domain}" = { };

  # 配置 nginx 反向代理并负责 TLS 终结
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  services.nginx = {
    enable = 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";
    };
    # 通过文件注入敏感变量,例如:
    # WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX
    environmentFile = "/path/to/my/secrets/file";
  };

  # 配置一个 woodpecker agent
  services.woodpecker-agents.agents."docker" = {
    enable = true;
    # 需要访问 podman socket,加入 podman 用户组
    extraGroups = [ "podman" ];
    environment = {
      WOODPECKER_SERVER = "localhost:9000";
      WOODPECKER_MAX_WORKFLOWS = "4";
      DOCKER_HOST = "unix:///run/podman/podman.sock";
      WOODPECKER_BACKEND = "docker";
    };
    # 与 woodpecker-server 相同,通过文件注入秘密
    environmentFile = [ "/var/lib/secrets/woodpecker.env" ];
  };

  # 配置 podman 并启用容器 DNS
  virtualisation.podman = {
    enable = true;
    defaultNetwork.settings = {
      dns_enabled = true;
    };
  };
  # podman 容器间通过 DNS 通信需要放行 53 端口
  networking.firewall.interfaces."podman0" = {
    allowedUDPPorts = [ 53 ];
    allowedTCPPorts = [ 53 ];
  };
}

注意一个细节:server 的 environmentFile 是单个字符串路径,而 agent 的 environmentFile 是字符串列表——两者语义一致(都是 systemd 的 EnvironmentFile),只是模块接受的类型不同,NixOS 会在求值时自动转换,按原样书写即可。

该配置的所有可选参数都可以通过 NixOS Search(搜索关键词 woodpecker)查询到完整列表,包括 nixpkgs 模块特有的选项(如 environmentFile、extraGroups、package 等),这些是 Woodpecker 官方环境变量文档之外、由模块层额外提供的声明式能力。

服务端配置逐项解析

WOODPECKER_HOST:声明你的公网地址

WOODPECKER_HOST = "https://${domain}";

server 必须知道自己的对外地址,格式为 <scheme>://<hostname>,不要带尾部斜杠。该值被用于生成 webhook 回调地址、UI 中的链接、OAuth 重定向等。仓库文档给出过多种合法形态:WOODPECKER_HOST=http://woodpecker.example.org、http://example.org/woodpecker、http://example.org:1234/woodpecker。

WOODPECKER_SERVER_ADDR:HTTP 监听端口

WOODPECKER_SERVER_ADDR = ":3007";

默认值是 :8000。示例中改用 :3007 是为了避开常见端口并让 nginx 从 80/443 代理进来——这不是必需项,仅展示"端口可自定义"。nginx 的 proxyPass 必须与这里的实际端口保持一致(示例中两者都是 3007)。注意:gRPC 端口 :9000 在这里没有显式配置,说明它使用模块/二进制默认值 :9000,agent 侧 WOODPECKER_SERVER = "localhost:9000" 正是与之对应。

WOODPECKER_OPEN:注册策略

WOODPECKER_OPEN = "true";

默认值为 false(注册关闭)。Woodpecker 没有自己的用户体系,用户全部来自所连接的 forge(OAuth2)。开启后,任何在 forge 上有账号的用户都可以登录。更精细的管控手段包括:保持关闭 + 通过 CLI 手动添加用户、用 WOODPECKER_ADMIN 指定管理员白名单、或开启注册但用 WOODPECKER_ORGS 按组织过滤,详见 server 配置文档的用户注册章节。

environmentFile:敏感信息与配置分离

server 需要与 agent 共享一个 WOODPECKER_AGENT_SECRET 来认证 gRPC 连接(默认值为空,即未配置时 agent 无法注册)。NixOS 模块通过 environmentFile 指向一个包含环境变量的明文文件(systemd EnvironmentFile 格式),典型内容如:

WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX

这样机密不会进入 nix 配置(从而不会进入 nix store 或版本库),并且可以用 openssl rand -hex 32 生成高强度随机值——这正是 agent 配置文档 推荐的生成方式。除此之外,服务端还支持以 *_FILE 后缀变量(如 WOODPECKER_AGENT_SECRET_FILE、WOODPECKER_GRPC_SECRET_FILE)从文件读取敏感值,这为容器化场景提供了另一种秘密注入途径。

Agent 配置逐项解析

WOODPECKER_SERVER 与 WOODPECKER_BACKEND:连接的端点与执行后端

WOODPECKER_SERVER = "localhost:9000";
WOODPECKER_BACKEND = "docker";

agent 通过 gRPC 轮询 server 的队列领取任务。WOODPECKER_BACKEND 决定流水线步骤实际由谁执行,默认值是 auto-detect,可选 docker、local、kubernetes(对应仓库中的 pipeline/backend/docker、pipeline/backend/local、pipeline/backend/kubernetes 实现)。示例选择了 docker 后端,但通过 DOCKER_HOST 指向 Podman 的 unix socket——因为 Podman 实现了 Docker API 兼容协议,docker 后端可以透明地驱动 Podman 容器。这正是"理论上与二进制安装相似、支持多后端"在 NixOS 上的体现:模块本身与后端引擎解耦,后端选择完全由环境变量决定。

WOODPECKER_MAX_WORKFLOWS:单 agent 的并行度

WOODPECKER_MAX_WORKFLOWS = "4";

默认值为 1,即一个 agent 同时只跑一个 workflow。调大该值可以让单个 agent 并行执行更多流水线;如果并行需求更高,也可以部署多个 agent 实例(模块的 services.woodpecker-agents.agents.* 天然支持在同一配置中定义多个命名 agent)。需要注意并行度提升会同步放大对后端资源(本例为 Podman 容器)的占用。

extraGroups:Podman socket 的权限模型

extraGroups = [ "podman" ];

agent 进程需要读写 /run/podman/podman.sock 才能创建/管理容器,因此必须把 agent 运行用户加入 podman 用户组。这是 NixOS 模块层提供的便利选项——在二进制安装场景下,这一步需要你手工编辑 systemd unit 的 SupplementaryGroups= 或调整 socket 权限,而 NixOS 上只是一个声明。

自动注入的默认值

agent 侧还有两个"不配置也会生效"的变量:WOODPECKER_HOSTNAME(未设置时取系统主机名,用于 agent 在 UI 中的标识)与 WOODPECKER_MAX_WORKFLOWS(未设置时取 1)。NixOS 模块的 environment 只覆盖你需要显式定制的部分,其余全部走二进制默认值。

Podman 后端与容器网络:DNS 与防火墙细节

示例最后一段专门处理了容器网络问题:

virtualisation.podman = {
  enable = true;
  defaultNetwork.settings = {
    dns_enabled = true;
  };
};
networking.firewall.interfaces."podman0" = {
  allowedUDPPorts = [ 53 ];
  allowedTCPPorts = [ 53 ];
};
  • 启用 Podman 及其默认网络(podman0),并开启该网络的 DNS 服务(dns_enabled = true);
  • 容器之间按服务名解析需要走宿主机的 DNS 转发,因此要在 podman0 接口上放行 53 端口(TCP/UDP)。

如果省略这两项,流水线中互相依赖的服务(如数据库、测试客户端等 sidecar 容器)可能无法通过主机名互通——这是 NixOS 上运行 docker 后端最容易踩的坑之一,值得在部署清单中单独标注。

声明式部署的实际收益与注意事项

把上面这些配置合在一起,一个 NixOS 主机的部署流程就是:

nixos-rebuild switch
  • 证书由 ACME 服务自动申请与续期;
  • nginx 配置由模块生成并校验语法;
  • server/agent 两个 systemd 服务自动创建并随开机启动;
  • Podman 网络与防火墙规则随系统配置生效;
  • 升级时只需更新 nixpkgs 频道并再次 nixos-rebuild switch,失败可回滚到上一个 generation。

需要注意的限制与边界:

  1. 模块维护在 nixpkgs 而非 Woodpecker 仓库,版本滞后或行为差异以你的频道为准;
  2. server 与 agent 的秘密必须保持一致(同一个 WOODPECKER_AGENT_SECRET),否则 agent 无法通过 gRPC 认证注册;
  3. WOODPECKER_OPEN 默认关闭,新实例记得显式决定注册策略;
  4. 若在反向代理与 server 之间还有额外的端口/协议需求(如 gRPC 走 TLS),需要参考 代理部署 与 SSL 配置 文档做补充配置。

更进一步:Nix 生态中的 Woodpecker 技巧

原文档在结尾推荐了 Awesome Woodpecker 页面,其中收录了若干与 NixOS 场景强相关的资源,可用来把 NixOS 部署的价值再放大一层:

  • 在流水线中直接使用 runner 的 nix store:由于 agent 就运行在 NixOS 主机上,流水线步骤(尤其是 local/docker 后端配合 nix 用户)可以复用宿主机 nix store 的缓存,大幅减少重复构建;Awesome 页面中收录的 "Locally Cached Nix CI with Woodpecker" 教程即展示了这一思路;
  • 用 Nix Flake 定义流水线:社区项目 woodpecker-flake-pipeliner 支持把流水线配置作为 Nix Flake 的 output 定义,配合动态配置服务使用,实现"流水线配置也进 nix 仓库"的端到端声明式体验;
  • 完整的 Woodpecker 流水线语法、环境变量与 backends 文档均可从 v2.8 管理文档目录 继续深入,其中 server 配置 与 agent 配置 是排查部署问题时的第一手资料。

小结

NixOS 上的 Woodpecker 部署本质上只是把"二进制安装 + 手工 systemd + 手工 nginx + 手工防火墙"这套操作翻译成了声明式 Nix 表达式,因此它继承了二进制安装的全部灵活性——包括对 docker/local/kubernetes 多后端的支持——同时获得了 NixOS 的可复现、可回滚、免手工运维特性。只要把握住三条主线:HTTP 端口(对外)与 gRPC 端口(agent 连接)分离、server 与 agent 共享同一个 agent secret、docker 后端 + Podman socket + podman0 DNS 放行,就能稳定跑通整套声明式 CI/CD 基础设施。

登录后查看全文
woodpecker