CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Woodpecker 允许通过一组预定义的 HTTP 端点将内部逻辑如流水线配置解析、镜像仓库凭证获取、密钥注入替换为外部扩展服务从而在不改动 CI/CD 引擎本身的前提下实现配置的动态生成、凭证的集中管理。读完本文你将掌握三类扩展Configuration / Registry / Secret Extension的全局与仓库级配置方式、请求/响应协议格式、HTTP 签名安全机制以及扩展网络访问控制WOODPECKER_EXTENSIONS_ALLOWED_HOSTS的完整规则。扩展机制总览用 HTTP 端点替换内部逻辑扩展Extensions是 Woodpecker 提供的一种插件化能力它允许你通过配置一个 HTTP 端点让外部服务接管引擎内部的特定职责。目前共提供三种类型的扩展详见本仓库的 扩展目录配置扩展Configuration extension在流水线触发时即时修改或生成流水线配置。注册表扩展Registry extension从扩展服务获取镜像仓库Registry的登录凭证。密钥扩展Secret extension从外部服务如 HashiCorp Vault、AWS Secrets Manager获取密钥。权限边界提示Woodpecker 的权限处理与 forge代码托管平台绑定。如果某个用户在 forge 上对仓库拥有管理员权限那么在 Woodpecker 中他也拥有该仓库的管理员权限可以修改已配置的扩展端点这可能被用于窃取 forge 用户的凭证。因此在启用扩展前请确保你信任所有能够登录 Woodpecker 的仓库管理员。安全基础HTTP 签名HTTP Signatures扩展会接收令牌、密钥等私密信息也可能返回会被执行器执行的恶意流水线配置因此你必须在信任扩展的前提下使用它。为了防御伪造请求等攻击Woodpecker 使用 HTTP Signaturesdraft-cavage-http-signatures 草案对所有发往扩展的 HTTP 请求进行签名签名算法基于 ed25519 公私钥对。如何获取并校验公钥扩展服务端必须使用 Woodpecker 的公钥验证每个请求的签名。公钥可以通过以下两种方式获取直接访问 HTTP 接口http://my-woodpecker.tld/api/signature/public-key打开 Woodpecker UI进入仓库设置的 Extensions 页面查看。该接口在本仓库中的实现位于 server/api/signature_public_key.go它使用x509.MarshalPKIXPublicKey将服务器的签名公钥序列化为 PEM 格式的PUBLIC KEY块后返回。扩展端可使用httpsign之类的库完成签名校验。签名实现细节源码佐证在 server/services/utils/http.go 中可以确认签名机制的具体实现使用httpsign.NewEd25519Signer创建签名器签名覆盖request-target与content-digest两个头部Content-Digest由库自动生成签名名称keyId为woodpecker-ci-extensions请求默认超时时间为 10 秒客户端带有server-extensions的 User-AgentSend方法内置重试逻辑最大重试 3 次采用指数退避backoff5xx 状态码与连接重置、超时等瞬时错误可重试4xx 客户端错误直接终止。配置扩展Configuration Extension动态生成与改写流水线配置配置扩展用于修改或生成 Woodpecker 的流水线配置。在仓库设置的 Extensions 页签中可以配置一个 HTTP 端点。典型的应用场景包括用 Go template 等模板引擎预处理原始配置文件将自定义属性转换为 Woodpecker 属性为配置补充默认值例如默认步骤将 GitLab CI、Starlark、Jsonnet 等完全不同的格式转换为 Woodpecker 配置在单一位置集中管理多个仓库的配置。⚠️ 安全警告Woodpecker 会把令牌等私密信息传给扩展并执行扩展返回的配置因此必须严格保护外部扩展。详见上文的安全签名机制。全局配置除了按仓库配置外也可以在服务器配置中设置一个全局端点适用于所有仓库。注意如果与别人共享 Woodpecker 服务器对方也会使用你的配置扩展。WOODPECKER_CONFIG_EXTENSION_ENDPOINThttps://example.com/ciconfig对应 CLI 标志为--config-extension-endpoint与--config-extension-netrc定义于 cmd/server/flags.go。工作流程流水线被触发后Woodpecker 先从仓库拉取流水线配置然后向配置的扩展发送一个 HTTP POST 请求JSON 载荷中包含仓库信息、流水线信息和从仓库获取到的当前配置文件。扩展随后可以返回修改后的、甚至是全新的流水线配置必须遵循 Woodpecker 官方的 YAML 格式。如果启用了exclusive独占设置全局和仓库级均可Woodpecker 将只调用你的扩展不再做任何其他事情从而可以完全跳过 forge此时发送给扩展的请求中不会附带配置文件。从源码上看这一逻辑体现在 server/services/manager.go 的ConfigServiceFromRepo当仓库配置了扩展端点且启用了ConfigExtensionExclusive时直接使用config.NewHTTP仅扩展否则使用config.NewCombined先本地配置服务、再合并扩展结果。仓库级字段定义在 server/model/repo.goConfigExtensionEndpoint、ConfigExtensionExclusive、ConfigExtensionNetrc。请求载荷扩展收到一个 HTTP POST 请求载荷结构如下class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用了 netrc 发送时才包含见下方说明 configuration?: { // 配置文件列表没有配置时不发送 name: string; // 配置文件名 data: string; // 配置文件内容 }[]; }ℹ️netrc字段仅在全局WOODPECKER_CONFIG_EXTENSION_NETRCtrue默认false或仓库级勾选 Send netrc credentials 时才会包含在请求中。Repo、Pipeline、Netrc的结构可参考 server/model/repo.go、server/model/pipeline.go、server/model/netrc.go。其中netrc数据非常强大包含访问仓库的凭证你可以用它克隆仓库甚至调用 forgeGitHub、GitLab 等的 API 获取仓库的更多信息。请求示例{ repo: { id: 100, uid: , user_id: 0, namespace: , name: woodpecker-test-pipeline, slug: , scm: git, git_http_url: , git_ssh_url: , link: , default_branch: , private: true, visibility: private, active: true, config: , trusted: false, protected: false, ignore_forks: false, ignore_pulls: false, cancel_pulls: false, timeout: 60, counter: 0, synced: 0, created: 0, updated: 0, version: 0 }, pipeline: { author: myUser, author_avatar: https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03, author_email: myemail.com, branch: main, changed_files: [some-filename.txt], commit: 2fff90f8d288a4640e90f05049fe30e61a14fd50, created_at: 0, deploy_to: , enqueued_at: 0, error: , event: push, finished_at: 0, id: 0, link_url: https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50, message: test old config\n, number: 0, parent: 0, ref: refs/heads/main, refspec: , clone_url: , reviewed_at: 0, reviewed_by: , sender: myUser, signed: false, started_at: 0, status: , timestamp: 1645962783, title: , updated_at: 0, verified: false }, configuration: [ { name: .woodpecker.yaml, data: steps:\n - name: backend\n image: alpine\n commands:\n - echo \Hello there from Repo (.woodpecker.yaml)\\n } ], netrc: { machine: myforge.com, login: myUser, password: forge-access-token } }响应格式扩展应返回一个 JSON 载荷包含 Woodpecker 官方 YAML 格式的新配置文件如果希望保留原有配置可以直接返回 HTTP 状态码204 No Content。class Response { configs: { name: string; // 配置文件名 data: string; // 配置文件内容 }[]; }响应示例{ configs: [ { name: central-override, data: steps:\n - name: backend\n image: alpine\n commands:\n - echo \Hello there from ConfigAPI\\n } ] }注册表扩展Registry Extension集中管理镜像仓库凭证注册表扩展用于获取镜像仓库Registry的登录凭证在仓库设置的 Extensions 页签中配置 HTTP 端点。适用场景集中管理注册表凭证使用外部存储保存凭证动态决定 Woodpecker 应该使用哪组凭证。⚠️ 同样地由于扩展会接收令牌等私密信息且返回的配置会被执行务必严格保护扩展请求均带签名。全局配置WOODPECKER_REGISTRY_EXTENSION_ENDPOINThttps://example.com/ciconfig对应 CLI 标志为--registry-extension-endpoint与--registry-extension-netrc见 cmd/server/flags.go。仓库级字段为RegistryExtensionEndpoint、RegistryExtensionNetrc见 server/model/repo.go。优先级规则如果全局扩展与仓库级扩展同时为某个注册表返回凭证Woodpecker 将使用仓库级扩展返回的凭证。从 server/services/manager.go 的RegistryServiceFromRepo可以看到仓库级扩展通过registry.NewWithExtension组合扩展凭证优先本地配置作为 fallback。工作流程流水线触发时Woodpecker 会向你的服务请求凭证作为兜底它会使用直接在 Woodpecker 中配置的凭证。请求载荷class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用了 netrc 发送时才包含见下方说明 }netrc字段同样受WOODPECKER_REGISTRY_EXTENSION_NETRC默认false或仓库级 Send netrc credentials 控制。请求 JSON 示例与配置扩展相同repo、pipeline、可选netrc三个字段具体结构请以 server/model/repo.go、server/model/pipeline.go、server/model/netrc.go 中的最新定义为准。响应格式class Response { registries: { address: string; // Docker 注册表地址 username: string; // 注册表用户名 password: string; // 注册表密码 }[]; }响应示例{ registries: [ { address: docker.io, username: woodpecker-bot, password: your-pass-word-123 } ] }密钥扩展Secret Extension从外部服务获取密钥密钥扩展用于从外部服务获取密钥同样在仓库设置的 Extensions 页签中配置 HTTP 端点。适用场景集中管理密钥例如 HashiCorp Vault、AWS Secrets Manager按流水线动态生成密钥。⚠️ 安全警告与前面两类扩展一致扩展接收令牌等私密信息必须严格保护所有请求均带签名。全局配置WOODPECKER_SECRET_EXTENSION_ENDPOINThttps://example.com/secrets WOODPECKER_SECRET_EXTENSION_NETRCfalse对应 CLI 标志为--secret-extension-endpoint与--secret-extension-netrc见 cmd/server/flags.go。仓库级字段为SecretExtensionEndpoint、SecretExtensionNetrc见 server/model/repo.go。优先级规则如果全局扩展与仓库级扩展返回了同名的密钥将使用仓库级扩展的密钥。从 server/services/manager.go 的SecretServiceFromRepo可以看到仓库级扩展通过secret.NewCombined与本地密钥服务组合扩展密钥按名称优先本地配置的密钥作为兜底。工作流程流水线触发时Woodpecker 会从你的服务获取密钥并将其与 Woodpecker 中直接配置的密钥合并扩展密钥按名称优先。如果扩展不可用则回退到本地配置的密钥。请求载荷class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用了 netrc 发送时才包含见下方说明 }netrc字段受WOODPECKER_SECRET_EXTENSION_NETRC默认false或仓库级 Send netrc credentials 控制。请求 JSON 示例与注册表扩展相同其中未启用 netrc 时netrc字段会被省略。响应格式class Response { secrets: { name: string; // 密钥名称与流水线配置中的 from_secret 匹配 value: string; // 密钥值 images?: string[]; // 可选限制仅用于指定插件 events?: string[]; // 可选限制仅用于指定流水线事件 }[]; }如果扩展不想新增任何密钥、希望保留现有密钥可以直接返回 HTTP 状态码204 No Content。响应示例{ secrets: [ { name: docker_password, value: your-secret-password-123 }, { name: deploy_token, value: super-secret-token, events: [push, tag] } ] }第三方扩展 危险提示以下第三方扩展未经 Woodpecker CI 开发或验证使用前务必确认你信任它们。官方文档在 55-secret-extension.md 末尾为第三方扩展保留了清单位置社区可在确认安全后自行补充。扩展的网络访问控制WOODPECKER_EXTENSIONS_ALLOWED_HOSTS出于安全考虑默认情况下扩展只能访问外部主机/IP 地址以防止扩展被用来调用本地服务例如元数据服务、内网端口扫描。可以通过环境变量WOODPECKER_EXTENSIONS_ALLOWED_HOSTS改变这一行为值为逗号分隔的列表支持以下三种形式内置网络Built-in networksloopbackIPv4 的 127.0.0.0/8 与 IPv6 的 ::1/128包含 localhostprivateRFC 191810.0.0.0/8、172.16.0.0/12、192.168.0.0/16与 RFC 4193FC00::/7即 LAN/内网external合法的非私有单播 IP可访问公网上的所有主机*允许所有主机。CIDR 列表IPv4 如1.2.3.0/8IPv6 如2001:db8::/32。通配主机名example.com、*.example.com、192.168.100.*。默认值与底层实现从源码看当该变量为空时默认值被设置为external见 server/services/utils/http.go 中的getHTTPClient并通过hostmatcher.NewDialContext将主机匹配器注入 HTTP 传输层从网络连接层面拦截不合规的目标。匹配规则实现在 server/services/utils/hostmatcher/hostmatcher.go每个列表项依次尝试按 CIDRnet.ParseCIDR、内置网络名、通配主机名模式解析内置网络的判定external要求ip.IsGlobalUnicast() !ip.IsPrivate()private要求ip.IsPrivate()loopback要求ip.IsLoopback()通配主机名使用filepath.Match进行匹配因此*、192.168.100.*、*.example.com这类模式均有效具体匹配入口为MatchHostName/MatchIPAddr/MatchHostOrIP。对应 CLI 标志为--extensions-allowed-hosts见 cmd/server/flags.go。实战建议与小结综合官方文档与仓库源码接入扩展的正确姿势可以归纳为以下几点信任先行扩展会收到令牌、netrc 凭证等敏感信息且配置扩展的返回值会被直接执行务必只使用可信服务并留意仓库管理员可修改扩展端点这一权限边界验证签名扩展端用httpsign等库校验每个请求的 HTTP 签名公钥通过/api/signature/public-key接口或 UI 的 Extensions 页获取签名实现细节可参考 server/services/utils/http.go按需收敛网络默认仅允许访问external公网主机若扩展需要访问内网 Vault、自建服务再按loopback/private/ CIDR / 通配主机名精确放开而不是直接使用*理解优先级与独占语义仓库级扩展优先于全局扩展注册表、密钥按名称覆盖配置扩展的exclusive设置可完全跳过 forge 与本地配置服务实现配置完全由扩展驱动协议对齐三类扩展均以 HTTP POST JSON 交互注意区分各自的响应结构configs/registries/secrets保持不变的场景统一返回204 No Content。一个同时提供配置扩展与密钥扩展端点的简易参考实现可参见 Woodpecker CI 官方维护的 example-extensions 示例项目。在将扩展投入生产前建议先在测试仓库中验证签名校验、网络白名单与优先级行为再逐步推广到全部仓库。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 扩展机制完全指南用 HTTP 端点替换内部逻辑配置、注册表与密钥扩展Woodpecker 扩展机制完全指南用 HTTP 端点替换内部逻辑配置、注册表与密钥扩展 Woodpecker 允许通过预定义的 HTTP 端点将内部逻CI/CDDevOpsMCP Everything Server 扩展指南Tools、Prompts、Resources 三类扩展点的注册机制与实战方法MCP Everything Server 扩展指南Tools、Prompts、Resources 三类扩展点的注册机制与实战方法 Everything SeMCP 服务AI 应用后端G6 扩展机制完全指南注册、使用与获取自定义扩展G6 扩展机制完全指南注册、使用与获取自定义扩展 本文基于 G6 官方文档 extension.zh.md https://link.gitcode.com/数据可视化前端图表库上一篇OKHttpUtils实战指南解决Android网络请求开发痛点下一篇TinyBase 性能优化10个提升应用响应速度的关键技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考