CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Woodpecker CI 是一个简单但功能强大的开源 CI/CD 引擎其部署由服务器Server与代理Agent两部分组成Server 是引擎核心负责 Web 界面、API、Webhook 接收与 Agent 编排Agent 是流水线执行单元通过 gRPC 与 Server 通信并运行工作流。本文以docs/versioned_docs/version-2.8/30-administration/00-getting-started.md为骨架结合本仓库中的 docker-compose 配置、Server/Agent 配置文档与 Go 源码实现系统讲解从选择版本、评估硬件、选择数据库与 Forge到使用 docker-compose 完成 Server Agent 首次部署的完整过程阅读后你将具备独立搭建一套可用 Woodpecker CI 的能力并能理解其架构原理与关键配置项。Woodpecker 部署架构Server 与 Agent一个完整的 Woodpecker 部署由两个核心组件构成Server服务器Woodpecker 的心脏内置 Web 界面负责接收 Forge 的 Webhook、编排与调度 Agent、向 Forge 回写流水线状态同时对外提供 API 和管理界面。Agent代理工作节点负责实际执行流水线。可以部署任意数量通过 gRPC 连接到 Server。每个 Agent 默认同时只能处理一个工作流workflow。理解 Server 与 Agent 的分工后扩容逻辑就非常直观如果你部署了 4 个 Agent 并全部连接到 Server那么系统最多会并行处理 4 个工作流注意是 workflow 而不是整条 pipeline因为一条 pipeline 可拆分为多个 workflow参见术语表。需要更高并行度时有两种方式增加 Agent 数量横向扩展部署更多 Agent 实例提高单 Agent 并行度设置 Agent 的环境变量WOODPECKER_MAX_WORKFLOWS让单个 Agent 同时执行多个工作流。该变量的默认值为1见 Agent 配置。从源码上看WOODPECKER_MAX_WORKFLOWS由 Agent 命令行标志定义 解析并在运行时决定 Agent 从 Server 拉取任务的数量上限因此这是调整系统吞吐量的关键旋钮。版本选择stable 还是 nextWoodpecker 提供两类发布版本stable稳定版经过完整测试的正式发布版本适合生产环境next预览版基于当前main分支构建的滚动版本包含最新特性但可能存在不稳定的变更适合尝鲜与测试。两种版本的具体差异与发布节奏可参考 版本说明页面。对于绝大多数生产部署建议选择 stable 版本。硬件要求以下是 Woodpecker 组件自身的最低资源需求不含操作系统与流水线负载组件内存CPUServer200 MB1Agent32 MB1需要注意两点上述数值不包含操作系统开销与流水线执行workload本身的资源消耗——实际运行 CI 任务的负载例如编译、测试容器会显著增加 Agent 的真实内存与 CPU 占用除 Server/Agent 外还需要一个数据库见下文数据库会按所选数据库系统的不同产生额外资源开销。安装方式概览Woodpecker 支持多种安装方式官方推荐新手从docker-compose方式开始使用 docker-compose 配合官方 容器镜像使用 Kubernetes 通过 Woodpecker Helm chart 部署chart 内含server与agent两个子 chart会自动按需配置使用官方 latest release 提供的二进制、DEB 或 RPM 包或使用第三方安装方式如 NixOS参见 40-nixos.md。数据库默认 SQLite可选 MySQL/PostgresWoodpecker 默认使用SQLite嵌入式数据库零安装、零配置即可运行。若需使用 MySQL 或 PostgreSQL请参考 数据库配置 页面核心配置项为WOODPECKER_DATABASE_DRIVER驱动名可取sqlite3、mysql、postgres默认sqlite3WOODPECKER_DATABASE_DATASOURCE连接串。默认值为 SQLite 文件路径容器内为/var/lib/woodpecker/woodpecker.sqlite非容器环境下为woodpecker.sqlite。MySQL 与 PostgreSQL 的典型连接串示例详见 Server 配置# MySQL使用 go-sql-driver/mysql 的 DSN 语法 WOODPECKER_DATABASE_DATASOURCEroot:passwordtcp(1.2.3.4:3306)/woodpecker?parseTimetrue # PostgreSQL使用 libpq 连接串语法建议版本 11 WOODPECKER_DATABASE_DATASOURCEpostgres://root:password1.2.3.4:5432/woodpecker?sslmodedisable使用 MySQL/Postgres 时需注意Woodpecker 不会自动创建数据库需要手动执行CREATE DATABASE数据库的迁移含建表与索引由 Woodpecker 自动完成备份与归档不在 Woodpecker 范围内需由第三方工具处理。Forge连接代码托管平台CI/CD 系统离不开代码仓库。将 Woodpecker 连接到你的Forge如 GitHub、Gitea、Forgejo、GitLab、Bitbucket 等详见 Forges 概览后就能在 push、pull request 等事件上触发流水线。Woodpecker 同时使用 Forge 完成两件事身份认证用户通过 Forge 的 OAuth2 登录Woodpecker 没有自己的用户注册表用户全部来自 Forge状态回写将流水线的执行状态报告回 Forge 的提交/PR 界面。各 Forge 支持的事件能力略有差异例如 Release 事件与 Deploy 事件并非所有 Forge 都支持详见 Forges 支持特性对比表。GitHub 的接入配置示例GitHub 配置包含WOODPECKER_GITHUBtrue、WOODPECKER_GITHUB_CLIENT、WOODPECKER_GITHUB_SECRET等变量会在下文的 docker-compose 示例中用到。基于 docker-compose 的完整部署最小可运行配置官方推荐的入门方式是 docker-compose以下配置可启动一个 Server 单 Agent 的最小集群完整说明见 docker-compose 部署文档version: 3 services: woodpecker-server: image: woodpeckerci/woodpecker-server:latest ports: - 8000:8000 volumes: - woodpecker-server-data:/var/lib/woodpecker/ environment: - 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} woodpecker-agent: image: woodpeckerci/woodpecker-agent:latest command: agent restart: always depends_on: - woodpecker-server volumes: - woodpecker-agent-config:/etc/woodpecker - /var/run/docker.sock:/var/run/docker.sock environment: - WOODPECKER_SERVERwoodpecker-server:9000 - WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET} volumes: woodpecker-server-data: woodpecker-agent-config:本仓库根目录的 docker-compose.example.yaml 提供了同类参考配置v3 版本镜像并额外演示了WOODPECKER_ADMIN与WOODPECKER_MAX_WORKFLOWS2的用法可对照阅读。启动前需要在.env文件与 compose 文件同目录或 shell 环境中准备以下变量然后执行docker-compose up变量说明WOODPECKER_HOSTServer 对外公开地址格式为scheme://hostname不要带尾部斜杠例如http://woodpecker.example.orgWOODPECKER_GITHUB_CLIENTGitHub OAuth App 的 Client IDWOODPECKER_GITHUB_SECRETGitHub OAuth App 的 Client SecretWOODPECKER_AGENT_SECRETServer 与 Agent 之间共享的认证密钥随机字符串可用openssl rand -hex 32生成并保密保存各配置要点逐项解析1. Server 必须知道自己的地址WOODPECKER_HOSTenvironment: - [...] - WOODPECKER_HOST${WOODPECKER_HOST}该地址用于生成 Forge Webhook 回调、OAuth 回调等链接。若带路径前缀如http://example.org/woodpecker或非默认端口如http://example.org:1234/woodpecker也同样支持。2. HTTP 与 gRPC 端口分开配置*_ADDR系列变量Woodpecker 使用两个独立端口HTTP 端口提供 Web 界面/APIgRPC 端口供 Agent 连接。它们分别由WOODPECKER_SERVER_ADDR默认:8000与WOODPECKER_GRPC_ADDR默认:9000控制environment: - [...] - WOODPECKER_GRPC_ADDR${WOODPECKER_GRPC_ADDR} - WOODPECKER_SERVER_ADDR${WOODPECKER_HTTP_ADDR}3. Agent 跨公网连接时的 gRPC 安全加固如果 Agent 通过公网连接 ServergRPC 流量应启用 TLS 加密反向代理的 gRPC 配置见 代理与 gRPCenvironment: - [...] - WOODPECKER_GRPC_SECUREtrue # 默认 false启用 TLS - WOODPECKER_GRPC_VERIFYtrue # 默认值校验 gRPC 服务器证书对应 Agent 侧也有WOODPECKER_GRPC_SECURE默认false与WOODPECKER_GRPC_VERIFY默认true两个选项需保持一致。4. Agent 需要访问 Docker daemonAgent 以 Docker 容器方式运行每个流水线步骤因此必须挂载宿主机的 Docker socketwoodpecker-agent: [...] volumes: - /var/run/docker.sock:/var/run/docker.sock5. Agent 连接 Server 的 gRPC 地址woodpecker-agent: [...] environment: - WOODPECKER_SERVERwoodpecker-server:9000这里WOODPECKER_SERVER指向 Server 的 gRPC 端口compose 网络内的服务名woodpecker-server 端口9000。从 Agent 源码实现 可见该变量默认值为localhost:9000还支持unix://前缀的 Unix socket 方式。6. 共享密钥WOODPECKER_AGENT_SECRETServer 与 Agent 使用同一共享密钥完成认证通信Server 与 Agent 两端必须配置一致woodpecker-server: environment: - [...] - WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET} woodpecker-agent: environment: - [...] - WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET}推荐用openssl rand -hex 32生成随机密钥。更安全的做法是配合*_FILE系列变量如WOODPECKER_AGENT_SECRET_FILE从 Docker secrets 文件中读取敏感值避免密钥出现在 compose 文件或环境变量中详见 Server 配置 的敏感数据处理小节。从源码看Agent 侧会优先从WOODPECKER_AGENT_SECRET_FILE指定的文件读取密钥再回退到环境变量见 cmd/agent/core/flags.go。Docker 镜像变体官方镜像提供多种标签镜像说明latest最新的稳定版vX.X.X具体的稳定发布版vX.X当前发布分支如release/v1.0可尽早获得 bugfixnext基于main分支的滚动版本。# server docker pull woodpeckerci/woodpecker-server:latest docker pull woodpeckerci/woodpecker-server:latest-alpine # agent docker pull woodpeckerci/woodpecker-agent:latest docker pull woodpeckerci/woodpecker-agent:latest-alpine # cli docker pull woodpeckerci/woodpecker-cli:latest docker pull woodpeckerci/woodpecker-cli:latest-alpine-alpine后缀为更精简的 Alpine 变体镜像。Agent 运行机制与注册流程Agent 是执行 workflow 的工作节点通过WOODPECKER_BACKEND选择执行后端默认auto-detect可选docker、local、kubernetes。docker-compose 部署时 Agent 默认使用 Docker 后端即每个步骤在 Agent 主机上的独立容器中运行因此无需额外配置Docker 后端的网络、IPv6、默认卷等可调项见 Docker 后端配置。Agent 启动时会携带WOODPECKER_AGENT_SECRET中的令牌连接 ServerServer 识别令牌并完成 Agent 注册。存在两种令牌方式系统令牌system tokenServer 与所有 Agent 使用同一个共享令牌。首次通信时 Server 在数据库中注册该 Agent 并生成唯一 ID 回传给 AgentAgent 将 ID 存入由WOODPECKER_AGENT_CONFIG_FILE默认/etc/woodpecker/agent.conf指定的文件之后每次启动都携带系统令牌 Agent ID完成身份识别。Agent 专属令牌agent token每个 Agent 使用独立令牌。管理员需先在 UI 中手动注册 AgentSettings - Agents - Add agent将生成的令牌通过WOODPECKER_AGENT_SECRET提供给对应 AgentAgent 连接后会在 UI 中更新为已连接状态。Agent 侧还有其他常用配置项完整列表见 Agent 配置WOODPECKER_HOSTNAMEAgent 主机名默认取 OS 主机名WOODPECKER_MAX_WORKFLOWS单 Agent 并行 workflow 数默认1WOODPECKER_FILTER_LABELS按标签过滤可接收的流水线默认提供platformos/arch、hostnamemy-agent、repo*三个标签支持keyvalue与*通配符WOODPECKER_HEALTHCHECK/WOODPECKER_HEALTHCHECK_ADDR健康检查端点开关默认开启与地址默认:3000WOODPECKER_KEEPALIVE_TIME/WOODPECKER_KEEPALIVE_TIMEOUTgRPC 长连接保活参数WOODPECKER_CONNECT_RETRY_COUNT默认5与WOODPECKER_CONNECT_RETRY_DELAY默认2s连接 Server 失败时的重试次数与间隔高级设置。收尾配置与首个流水线完成上述部署后还需检查 Server 配置 与 Agent 配置 中是否还有需要调整的部分其中几个对首次使用影响较大的 Server 配置包括用户注册默认关闭注册WOODPECKER_OPENfalse可设置WOODPECKER_OPENtrue允许所有 Forge 用户登录或用WOODPECKER_ADMIN管理员账号列表与WOODPECKER_ORGS允许注册的组织列表来限制注册范围仓库过滤WOODPECKER_REPO_OWNERS可限制只同步指定组织/用户的仓库GitHub 权限粒度较粗时尤其有用流水线超时WOODPECKER_DEFAULT_PIPELINE_TIMEOUT默认 60 分钟与WOODPECKER_MAX_PIPELINE_TIMEOUT默认 120 分钟控制流水线的默认与最大超时。一切就绪后即可参考 首个流水线指南 编写.woodpecker/目录下的 YAML 工作流文件开始你的第一次 CI 构建。Woodpecker 默认会按DefaultConfigOrder./.woodpecker/、.woodpecker.yaml、.woodpecker.yml查找流水线配置文件该顺序定义在 shared/constant/constant.go 中可作为编写配置时的参考。赞分享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/CDDevOps最完整CompreFace入门指南从安装到部署全流程最完整CompreFace入门指南从安装到部署全流程 读完你将学到 3种部署方式的详细对比与操作步骤 环境检测与系统兼容性验证方法 常见故障排查与性能优化技巧人工智能计算机视觉后端AI 应用Giftie 扩展开发如何添加新的抽奖模式九宫格Giftie 扩展开发如何添加新的抽奖模式九宫格 Giftie 是一款纯前端送礼解决方案它通过精美的抽奖界面帮助用户解决送礼难题。本文将详细介绍如何上一篇Ryujinx模拟器终极指南从零开始畅玩Switch游戏下一篇AgentScope 2.0 实战指南构建一套可观测、可上线的多智能体系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
