CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本篇技术指南面向使用 NixOS 的开发者与运维人员讲解如何通过 NixOS 的声明式配置services.woodpecker-server与services.woodpecker-agents模块一次性部署完整的 Woodpecker CI/CD 实例包括 Lets 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、接收 forgeGit 托管平台的 webhook、对外暴露 REST API并解析仓库中的 YAML 流水线配置agent负责真正执行 workflow流水线步骤通过 gRPC 连接到 server 领取任务、回传执行状态与日志多个 agent 可以共存各自独立配置并行数、后端类型等autoscaler可选按需在云厂商创建/销毁 VM 以处理积压的构建任务。server 与 agent 之间走 gRPC两者使用不同的监听端口变量默认值作用依据WOODPECKER_SERVER_ADDR:8000服务端 HTTP 监听地址Web UI / API / webhook10-server-config.mdWOODPECKER_GRPC_ADDR:9000服务端 gRPC 监听地址供 agent 连接10-server-config.mdWOODPECKER_SERVERagent 侧localhost:9000agent 连接 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 的模块文件。它一次完成五件事Lets Encrypt 证书、nginx TLS 反向代理、woodpecker-server、以 docker 后端 Podman socket 运行的 woodpecker-agent、Podman 容器网络 DNS 与防火墙放行。{ config , ... }: let domain woodpecker.example.org; in { # 自动通过 lets encrypt 申请证书 security.acme.defaults.email acmeexample.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_SECRETXXXXXXXXXXXXXXXXXXXXXX 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_HOSThttp://woodpecker.example.org、http://example.org/woodpecker、http://example.org:1234/woodpecker。WOODPECKER_SERVER_ADDRHTTP 监听端口WOODPECKER_SERVER_ADDR :3007;默认值是:8000。示例中改用:3007是为了避开常见端口并让 nginx 从80/443代理进来——这不是必需项仅展示端口可自定义。nginx 的proxyPass必须与这里的实际端口保持一致示例中两者都是3007。注意gRPC 端口:9000在这里没有显式配置说明它使用模块/二进制默认值:9000agent 侧WOODPECKER_SERVER localhost:9000正是与之对应。WOODPECKER_OPEN注册策略WOODPECKER_OPEN true;默认值为false注册关闭。Woodpecker 没有自己的用户体系用户全部来自所连接的 forgeOAuth2。开启后任何在 forge 上有账号的用户都可以登录。更精细的管控手段包括保持关闭 通过 CLI 手动添加用户、用WOODPECKER_ADMIN指定管理员白名单、或开启注册但用WOODPECKER_ORGS按组织过滤详见 server 配置文档的用户注册章节。environmentFile敏感信息与配置分离server 需要与 agent 共享一个WOODPECKER_AGENT_SECRET来认证 gRPC 连接默认值为空即未配置时 agent 无法注册。NixOS 模块通过environmentFile指向一个包含环境变量的明文文件systemdEnvironmentFile格式典型内容如WOODPECKER_AGENT_SECRETXXXXXXXXXXXXXXXXXXXXXX这样机密不会进入 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 容器的占用。extraGroupsPodman 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。需要注意的限制与边界模块维护在 nixpkgs 而非 Woodpecker 仓库版本滞后或行为差异以你的频道为准server 与 agent 的秘密必须保持一致同一个WOODPECKER_AGENT_SECRET否则 agent 无法通过 gRPC 认证注册WOODPECKER_OPEN默认关闭新实例记得显式决定注册策略若在反向代理与 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 基础设施。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐gs-quant 时间序列代数运算multiply 乘法函数的用法、对齐模式与源码解析gs quant 时间序列代数运算multiply 乘法函数的用法、对齐模式与源码解析 导读 本文深入剖析 gs quantGoldman Sachs 开源CI/CDDevOpsLogicFlow v1.0 发布深度解读基于类继承与 MVVM 的流程图编辑框架设计LogicFlow v1.0 发布深度解读基于类继承与 MVVM 的流程图编辑框架设计 2021 年 12 月 31 日LogicFlow 在其开源一周年之CI/CDDevOps2025最新指南Waybar在NixOS上的声明式部署与模块化配置2025最新指南Waybar在NixOS上的声明式部署与模块化配置 你是否还在为Linux桌面状态栏的碎片化配置烦恼是否希望通过单一配置文件管理所有状态栏模桌面应用上一篇m4s文件转MP4终极指南5分钟无损还原B站缓存视频永久保存不再难下一篇暗黑2存档编辑器d2s-editor完全指南5分钟速通角色改造全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
