企业官网建设流程全解析

• CI/CD
• DevOps

本文是 Woodpecker CI/CD 引擎（当前仓库为 Woodpecker 3.18 版本线）的使用侧排障指南，聚焦两条最典型的线上问题：流水线克隆（clone）阶段的认证与网络故障，以及SELinux 环境下 Agent 无法访问 Docker 套接字。读完本文你将掌握：用WOODPECKER_AUTHENTICATE_PUBLIC_REPOS解决私有仓库克隆认证问题、用skip_clone+ 容器内手工git fetch定位网络/认证根因，以及针对 SELinux 的四级递进解决方案。

克隆（clone）阶段问题排查

当流水线在 clone 步骤报出类似下面的错误时，问题通常出在认证或网络连通性两个层面：

fatal: could not read Username for 'https://<url>': No such device or address

该错误的字面含义是：git 在需要用户名/密码时，发现当前环境既没有可交互的终端（No such device），也没有可用的凭据来源。Woodpecker 的 clone 步骤运行在隔离容器中，不会像本地终端那样弹出密码提示，因此这类报错几乎总是由「凭据未注入」或「容器网络不通」导致。

排查方向一：认证配置（WOODPECKER_AUTHENTICATE_PUBLIC_REPOS）

如果目标仓库是内部/私有仓库（例如公司 GitLab、Gitea、Forgejo 等），首选检查项是服务器端环境变量WOODPECKER_AUTHENTICATE_PUBLIC_REPOS：

WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=true

该开关对应服务器的authenticate-public-repos启动参数，在源码中的定义位于 cmd/server/flags.go，其官方用途说明为："Always use authentication to clone repositories even if they are public. Needed if the SCM requires to always authenticate as used by many companies."（即使仓库是公开的也始终使用认证克隆；当 SCM 强制要求认证时——许多企业内部场景如此——必须开启）。

它对应的完整配置条目记录在 docs/versioned_docs/version-3.18/30-administration/10-configuration/10-server.md：

• 环境变量名：WOODPECKER_AUTHENTICATE_PUBLIC_REPOS
• 默认值：false
• 建议：当你的 forge 规定「即便是公开仓库也必须携带凭据访问」时，将其设为true

从实现上看，Woodpecker 通过netrc机制把凭据注入 clone 步骤。pipeline/backend/local/clone.go（本地后端）与 Docker 后端都会在 clone 前写入 netrc 文件，并保证克隆结束后删除（见 pipeline/backend/local/clone.go 中writeNetRC的逻辑）。同时，出于安全考虑，netrc 只会注入到受信任的 clone 镜像中——pipeline/frontend/yaml/linter/linter.go中有一条对应检查规则："Specified clone image does not match allow list, netrc is not injected"（指定的 clone 镜像不在允许列表中时，不注入 netrc），具体见 pipeline/frontend/yaml/linter/linter.go。因此若你使用了自定义 clone 插件却拿不到凭据，还需要在项目设置中把它登记为受信任插件。

排查方向二：容器到 Git 服务器的网络连通性

如果开启WOODPECKER_AUTHENTICATE_PUBLIC_REPOS后问题依旧，下一步应确认流水线容器是否能访问你的 Git 服务器。Woodpecker 提供了非常实用的「挂起容器」排查法：

1. 在流水线配置中禁用默认 clone 步骤，并让一个步骤"挂起"（sleep 很长一段时间）：

skip_clone: true steps: build: image: debian:stable-backports commands: - apt update - apt install -y inetutils-ping wget - ping -c 4 git.example.com - wget git.example.com - sleep 9999999

skip_clone: true会告诉 Woodpecker 不要自动注入默认 clone 步骤。该字段在 YAML 中的解析定义位于 pipeline/frontend/yaml/types/workflow.go（SkipClone bool），而默认 clone 步骤的注入逻辑在 pipeline/frontend/yaml/compiler/compiler.go：只有!local && 未自定义 clone && !skip_clone && 配置了默认 clone 插件时才自动追加。完整语法说明见 docs/versioned_docs/version-3.18/20-usage/20-workflow-syntax.md。

2. 流水线运行并"挂起"后，在宿主机上找到该容器并进入：

# 用 docker ps 查看运行中的容器，复制第一列的容器 ID docker exec -it 1234asdf bash

（将1234asdf替换为实际的容器 ID）

3. 在容器内手工重放失败流水线的克隆命令，验证是认证问题还是网络问题：

git init git remote add origin https://git.example.com/username/repo.git git fetch --no-tags origin +refs/heads/branch:

（将 URL 与分支替换为实际值，并使用你的用户名与密码作为登录凭据）

如果ping、wget均失败，说明是网络层（防火墙、DNS、代理）问题；如果网络通但git fetch报认证错误，说明是凭据注入问题——回到WOODPECKER_AUTHENTICATE_PUBLIC_REPOS与 netrc/受信任 clone 镜像的排查。这步操作把「黑盒失败」变成「白盒验证」，是定位 clone 问题最高效的手段。

补充：关于默认 clone 步骤的行为

值得了解的是，Woodpecker 默认注入的 clone 步骤由defaultClonePlugin（通常为woodpeckerci/plugin-git）承担，并会针对 tag 事件附加tags: true设置、默认depth: 0（完整克隆），见 pipeline/frontend/yaml/compiler/compiler.go。若你需要调整克隆行为（如设置depth: 50、partial: false或换用自定义 clone 镜像），可以通过clone段配置，示例见 docs/versioned_docs/version-3.18/20-usage/20-workflow-syntax.md。另外注意skip_clone的警告：默认 clone 步骤以root执行并确保工作目录权限为0777，若使用无 root 权限的步骤容器配合skip_clone，需自行准备可写目录（如/tmp）。

SELinux 环境下的 Agent 权限问题

在 RHEL、CentOS、Fedora 以及其他 Enterprise Linux 发行版上，SELinux 默认会拦截 Agent 对 Docker 套接字的访问。这是木鸟啄木鸟式的经典坑：镜像拉取、容器创建都依赖 Docker socket，一旦被 SELinux 拒绝，整个 Agent 都无法工作。

症状识别

如果 SELinux 正在阻断访问，Agent 日志中会出现类似错误：

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

看到permission denied出现在 Docker socket 连接处，且系统为启用 SELinux 的发行版时，应优先怀疑 SELinux 策略而非 Docker 本身。项目官方 Docker Compose 安装示例中即包含该 socket 挂载（见 docs/versioned_docs/version-3.18/30-administration/05-installation/10-docker-compose.md），这正说明 socket 访问是 Agent 运行的基础。

解决方案一：临时切换 Permissive 模式（仅用于验证）

先用最小代价确认问题根源确实在 SELinux：

setenforce 0

若切换后 Agent 恢复连接，则可确认是 SELinux 策略所致。若要长期关闭（不推荐用于生产），编辑/etc/selinux/config将SELINUX改为permissive：

# 编辑 /etc/selinux/config SELINUX=permissive

注意：Permissive 模式只做记录不强制拦截，仅适合测试验证；生产环境应优先采用下面的策略或卷标方案。

解决方案二：为 Agent 生成自定义 SELinux 策略（推荐）

保持 SELinux 开启的同时，为 docker 进程生成放行策略模块，是兼顾安全与功能的推荐做法：

# 1. 依据审计日志生成策略源文件 ausearch -c 'docker' -avc | audit2allow -R -o woodpecker-docker.te # 2. 编译策略模块 checkmodule -M -m -o woodpecker-docker.mod woodpecker-docker.te # 3. 打包策略包 semodule_package -o woodpecker-docker.pp -m woodpecker-docker.mod # 4. 装载策略 semodule -i woodpecker-docker.pp

该方案只放行被拒绝的具体操作（写入.te的规则），其余 SELinux 保护依然生效，适合生产环境。

解决方案三：使用带 SELinux 选项的 Docker 卷挂载

在 Docker Compose 或docker run中挂载/var/run/docker.sock时，为卷追加:z或:Z标签：

volumes: - /var/run/docker.sock:/var/run/docker.sock:z

• :z：让 Docker 自动为卷内容重新打上 SELinux 标签（shared 语义），可满足多个容器共享访问；
• :Z：将卷内容重标为仅供当前容器独占使用，安全性更高但需谨慎，因为其他容器将无法访问该卷。

官方 Docker Compose 安装文档的 SELinux 备注中也出现了:z的写法，见 docs/versioned_docs/version-3.18/30-administration/05-installation/10-docker-compose.md。

解决方案四：改用 Podman

如果不想处理 SELinux 策略，可以考虑用 Podman 替代 Docker 作为 Agent 的执行后端。Podman 与 SELinux 的集成更完善（支持无根模式、原生处理卷标），能规避大部分此类问题。需要注意的是，官方文档指出 Podman 并没有官方支持，但可以尝试将DOCKER_HOST指向 Podman 的 socket（如unix:///run/podman/podman.sock）来试验，参见 docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/10-docker.md。

小结：排查路径速查

遇到 clone 或 Docker socket 问题时，按照「先认证、后网络、再安全策略」的顺序逐层排除，即可快速定位并修复，让 Woodpecker 流水线恢复稳定运行。

• CI/CD
• DevOps