CI/CD on Zata-砸它

Docker 和 Traefik 一键安装脚本

Mon, 08 Jun 2026 00:30:00 +0800

在单台 VPS 上部署多个 Web 服务时，我现在更倾向于先准备一个公共入口层：Docker 负责跑应用，Traefik 负责根据域名把请求转发到不同容器，并自动接入 HTTPS。

这篇文章放一个可直接运行的脚本，用来在 Ubuntu/Debian 服务器上安装 Docker Engine、Docker Compose 插件，并启动一个基础 Traefik 网关。

脚本文件和这篇文章放在同一个目录里，可以直接查看或下载：install-docker-traefik.sh。

适用场景

适合这些情况：

一台新的 Ubuntu/Debian 云服务器。
准备用 Docker Compose 部署多个站点或服务。
想用 Traefik 统一管理 80、443 入口。
不想再为每个应用单独写 Nginx 配置。

不适合这些情况：

已经使用 Kubernetes Ingress。
已经由 1Panel、Coolify、Dokploy 等平台完整接管反向代理。
需要复杂的企业级网关策略，比如多租户权限、统一认证、灰度发布等。

快速运行

如果只是安装 Docker 和 Traefik，不需要立即配置 HTTPS：

chmod +x install-docker-traefik.sh
./install-docker-traefik.sh

如果要给真实网站签发 Let’s Encrypt 证书，建议填写 ACME_EMAIL（必须是真实邮箱，脚本会拒绝 you@example.com 这类占位值，Let’s Encrypt 也只会用占位邮箱会让证书一直申请失败）：

ACME_EMAIL=you@your-domain.com ./install-docker-traefik.sh

脚本会把 Traefik 配置写到：

/opt/traefik

Dashboard 默认只监听服务器本机：

http://127.0.0.1:8080/dashboard/

远程查看可以用 SSH 端口转发：

ssh -L 8080:127.0.0.1:8080 user@server

参数说明

常用环境变量如下：

变量	默认值	说明
`TRAEFIK_DIR`	`/opt/traefik`	Traefik 配置目录
`TRAEFIK_NETWORK`	`traefik`	公共 Docker 网络名
`TRAEFIK_IMAGE`	`traefik:v3.7`	Traefik 镜像版本
`ACME_EMAIL`	空	Let’s Encrypt 邮箱，不填则不启用自动 HTTPS
`ENABLE_HTTPS_REDIRECT`	自动判断	填了 `ACME_EMAIL` 时默认开启 HTTP 到 HTTPS 跳转
`INSTALL_SAMPLE`	`false`	是否启动 `whoami` 测试服务
`WHOAMI_HOST`	`whoami.localhost`	只给测试服务使用，不是你的真实网站域名

ACME_EMAIL 可以不填。不填时，脚本仍然会安装 Docker 和 Traefik，但不会配置 Let’s Encrypt 证书解析器。

WHOAMI_HOST 也可以不填。它只在 INSTALL_SAMPLE=true 时用于测试服务，真实网站应该在自己的 docker-compose.yml 里配置 Traefik labels。

真实网站接入方式

真实网站容器需要加入同一个 Traefik 网络：

networks:
 traefik:
 external: true

然后给 Web 服务加 labels：

services:
 site:
 image: your-site-image
 restart: unless-stopped
 networks:
 - traefik
 labels:
 - "traefik.enable=true"
 - "traefik.http.routers.site.rule=Host(`example.com`)"
 - "traefik.http.routers.site.entrypoints=websecure"
 - "traefik.http.routers.site.tls=true"
 - "traefik.http.routers.site.tls.certresolver=letsencrypt"
 - "traefik.http.services.site.loadbalancer.server.port=80"

networks:
 traefik:
 external: true

这里的 example.com 要替换成真实域名，并且 DNS 需要提前解析到这台服务器 IP。服务器安全组或防火墙也要放行 80 和 443。

后续如何做 CD

这个脚本只解决服务器入口层：安装 Docker、启动 Traefik、准备公共网络。它不会负责“代码变了以后怎么自动发布”。真正的 CD 需要额外建立一条发布链路：

push 代码
 -> CI/CD 平台构建 Docker 镜像
 -> 推送镜像到镜像仓库
 -> SSH 到服务器
 -> 更新应用 compose 的镜像 tag
 -> docker compose pull && docker compose up -d
 -> Traefik 根据 labels 接管流量

这里用 GitHub Actions 举例，但思路对 GitLab CI、Woodpecker CI、Gitea Actions 也一样。Traefik 不关心你用哪个 CI/CD 平台，它只关心最终跑起来的容器是否在同一个 Docker 网络里，并且有没有正确的 labels。

一、每个项目准备自己的镜像

每个要部署的项目都应该能被构建成一个 Docker 镜像。不同技术栈的 Dockerfile 不一样，但对 Traefik 来说只需要满足两点：

容器内部有一个 HTTP 服务端口，比如 80、3000、8080。
不要直接把业务容器的端口暴露到公网，公网入口交给 Traefik。

如果是静态站点，可以用 Nginx 承载构建产物：

FROM nginx:alpine
COPY public /usr/share/nginx/html

如果是 Node、Python、Go、Java 后端，则按对应技术栈构建镜像，只要最后服务监听一个明确端口即可。

二、服务器上每个项目一个目录

建议每个应用单独放到 /opt/apps/<app-name>：

sudo mkdir -p /opt/apps/my-app
cd /opt/apps/my-app

组织方案选择

每个项目目录里至少需要 .env（存放部署变量）和 docker-compose.yml（定义容器运行方式）。这两者的关系有几种组织方式：

方案 A：compose 文件直接放在项目目录（默认）

/opt/apps/my-app/
├── .env
└── docker-compose.yml

简单直观，适合 compose 文件不常变更的项目。

方案 B：compose 文件集中管理

如果多个项目的 compose 模板相似，想统一维护，可以把 compose 文件放到共享目录：

/opt/compose-templates/
├── traefik-app.yml
└── static-site.yml

/opt/apps/my-app/
└── .env

部署时用 -f 指定模板路径：

docker compose -f /opt/compose-templates/traefik-app.yml --env-file /opt/apps/my-app/.env up -d

CD 流水线里也这样写，每次更新 compose 模板时只需要改 /opt/compose-templates/ 下的文件。

方案 C：用脚本封装

在项目目录下放一个启动脚本，把模板路径写死在脚本里：

#!/bin/bash
# /opt/apps/my-app/deploy.sh
cd /opt/compose-templates
docker compose -f traefik-app.yml --env-file /opt/apps/my-app/.env "$@"

这样部署命令变成：

/opt/apps/my-app/deploy.sh up -d
./deploy.sh logs -f

脚本本身也可以加入检查、重试、通知等逻辑，适合有统一运维规范的项目。

方案 D：用 git 仓库管理 compose 文件

如果 CD 流水线已经配好了 SSH 密钥，服务器可以直接用 git 操作。只需要 clone 一次，之后 CD 时 git pull 拉取最新配置：

git clone git@github.com:your-org/server-configs.git /opt/configs

目录结构：

/opt/configs/
├── compose.yml # git 管理
└── .env.example # 提交 git，真实值在服务器上配置

/opt/apps/my-app/
└── .env # 不提交 git，只存在服务器

CD 部署时：

cd /opt/configs && git pull && cd /opt/apps/my-app && docker compose -f /opt/configs/compose.yml --env-file .env up -d

.env 里的密钥留在服务器本地，不进 git 仓库。compose 文件由 git 管理，可以 review 和回滚。

怎么选：如果 compose 模板基本固定、很少改，用默认的方案 A 就行。如果想统一管理模板、减少每个项目重复的 compose 内容，选方案 B 或 C。如果需要多人协作、版本控制和 PR review，选方案 D。

下面以方案 A 为例继续说明。如果选了其他方案，记得相应调整后面的路径和命令。

.env 只放部署层变量：

APP_IMAGE=ghcr.io/your-org/my-app:initial
APP_HOST=app.example.com
APP_PORT=3000

docker-compose.yml 写成通用模板：

services:
 app:
 image: ${APP_IMAGE}
 restart: unless-stopped
 networks:
 - traefik
 expose:
 - "${APP_PORT}"
 labels:
 - "traefik.enable=true"
 - "traefik.http.routers.my-app.rule=Host(`${APP_HOST}`)"
 - "traefik.http.routers.my-app.entrypoints=websecure"
 - "traefik.http.routers.my-app.tls=true"
 - "traefik.http.routers.my-app.tls.certresolver=letsencrypt"
 - "traefik.http.services.my-app.loadbalancer.server.port=${APP_PORT}"

networks:
 traefik:
 external: true

这里没有写 ports。业务容器不需要直接占用宿主机端口，Traefik 会通过 traefik 网络访问容器内部端口。

如果你的 Traefik 没有启用 Let’s Encrypt，可以先用 HTTP：

labels:
 - "traefik.enable=true"
 - "traefik.http.routers.my-app.rule=Host(`${APP_HOST}`)"
 - "traefik.http.routers.my-app.entrypoints=web"
 - "traefik.http.services.my-app.loadbalancer.server.port=${APP_PORT}"

真实项目的数据库密码、API key 等运行时环境变量，建议放在另一个只存在服务器上的文件，例如 app.env，然后在 compose 里引用：

env_file:
 - app.env

CD 流水线只更新 .env 里的 APP_IMAGE，不要覆盖服务器上的业务密钥文件。

三、准备部署用户和 SSH key

生产环境建议创建专门的部署用户，不要长期用 root 跑 CD：

sudo adduser --disabled-password --gecos "" deploy
sudo usermod -aG docker deploy

加入 docker 组后，需要重新登录这个用户，组权限才会生效。

生成一把专门给 CD 用的 SSH key：

ssh-keygen -t ed25519 -C "cd-my-app" -f ./cd-my-app -N ""

公钥放到服务器：

sudo install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
cat ./cd-my-app.pub | sudo tee -a /home/deploy/.ssh/authorized_keys
sudo chmod 600 /home/deploy/.ssh/authorized_keys
sudo chown -R deploy:deploy /home/deploy/.ssh

私钥内容放到 CI/CD 平台的 Secret 里。以 GitHub Actions 为例，进入：

Repository -> Settings -> Secrets and variables -> Actions

添加：

SERVER_HOST 服务器 IP 或域名
SERVER_USER deploy
SERVER_SSH_KEY cd-my-app 私钥完整内容

注意：私钥不要提交到 Git 仓库。公钥留在服务器的 authorized_keys，私钥只放 CI/CD Secret。

四、准备镜像仓库

镜像仓库可以用 GitHub Container Registry、Docker Hub、Harbor、阿里云/腾讯云镜像仓库等。通用原则是：

CI/CD 需要有 push 权限，用来推送新镜像。
服务器需要有 pull 权限，用来拉取新镜像。
CD 部署时尽量使用不可变 tag，例如 Git commit SHA。
latest 可以保留给人工查看，但不要只依赖 latest 做生产发布。

如果使用私有镜像，先在服务器上用部署用户登录一次：

sudo -iu deploy
echo "你的镜像仓库 token" | docker login ghcr.io -u your-user --password-stdin

登录信息会保存在部署用户自己的 Docker 配置里。之后 CD 执行 docker compose pull 时，就能拉取私有镜像。

五、GitHub Actions 通用 CD 模板

下面这个模板做三件事：

构建镜像。
推送 latest 和当前 commit SHA 两个 tag。
SSH 到服务器，把 .env 里的 APP_IMAGE 改成当前 commit SHA 对应的镜像，然后重启应用。

保存为：

.github/workflows/cd.yml

name: CD

on:
 push:
 branches:
 - main
 workflow_dispatch:

permissions:
 contents: read
 packages: write

env:
 REGISTRY_HOST: ghcr.io
 IMAGE_NAME: ghcr.io/your-org/my-app
 APP_DIR: /opt/apps/my-app

jobs:
 deploy:
 runs-on: ubuntu-latest

 steps:
 - name: Checkout
 uses: actions/checkout@v6

 - name: Set up Docker Buildx
 uses: docker/setup-buildx-action@v4

 - name: Login to registry
 uses: docker/login-action@v4
 with:
 registry: ${{ env.REGISTRY_HOST }}
 username: ${{ secrets.REGISTRY_USERNAME }}
 password: ${{ secrets.REGISTRY_TOKEN }}

 - name: Build and push image
 uses: docker/build-push-action@v7
 with:
 context: .
 push: true
 tags: |
 ${{ env.IMAGE_NAME }}:${{ github.sha }}
 ${{ env.IMAGE_NAME }}:latest

 - name: Deploy on server
 env:
 SERVER_HOST: ${{ secrets.SERVER_HOST }}
 SERVER_USER: ${{ secrets.SERVER_USER }}
 SERVER_SSH_KEY: ${{ secrets.SERVER_SSH_KEY }}
 IMAGE: ${{ env.IMAGE_NAME }}:${{ github.sha }}
 run: |
 mkdir -p ~/.ssh
 printf '%s\n' "$SERVER_SSH_KEY" > ~/.ssh/deploy_key
 chmod 600 ~/.ssh/deploy_key
 ssh-keyscan -H "$SERVER_HOST" >> ~/.ssh/known_hosts

 ssh -i ~/.ssh/deploy_key "$SERVER_USER@$SERVER_HOST" \
 "cd '${APP_DIR}' && \
 sed -i 's#^APP_IMAGE=.*#APP_IMAGE=${IMAGE}#' .env && \
 docker compose pull && \
 docker compose up -d --remove-orphans && \
 docker image prune -f"

对应需要在 GitHub Secrets 里添加：

REGISTRY_USERNAME 镜像仓库用户名
REGISTRY_TOKEN 镜像仓库 token
SERVER_HOST 服务器 IP 或域名
SERVER_USER SSH 部署用户
SERVER_SSH_KEY SSH 私钥

如果使用 GitHub Container Registry，并且镜像属于当前仓库，构建推送阶段也可以用 ${{ github.actor }} 和 ${{ secrets.GITHUB_TOKEN }}。但服务器拉取私有镜像时，仍然需要能 pull 该镜像的凭据，最清晰的做法是给服务器配置一份只读或低权限的 registry token。

六、发布后检查和回滚

部署完成后，至少检查三处：

cd /opt/apps/my-app
docker compose ps
docker compose logs -f
curl -I https://app.example.com

如果应用提供健康检查接口，可以在 workflow 里加一步：

curl -fsS https://app.example.com/health

回滚的本质是把 APP_IMAGE 改回旧镜像 tag：

cd /opt/apps/my-app
sed -i 's#^APP_IMAGE=.*#APP_IMAGE=ghcr.io/your-org/my-app:old-commit-sha#' .env
docker compose pull
docker compose up -d --remove-orphans

所以每次发布都用 commit SHA 做镜像 tag 很重要。它让你能明确知道当前服务器运行的是哪一次代码，也能快速回到上一个可用版本。

七、多项目部署约定

单台服务器跑多个项目时，建议保持这些约定：

每个项目一个目录：/opt/apps/<app-name>。
每个项目一个 compose：只管理自己的业务容器。
所有需要公网 HTTP/HTTPS 的服务都加入同一个 traefik 网络。
每个项目使用不同的 router/service 名称，例如 blog、api、admin。
每个项目只在 labels 里声明自己的域名和内部端口。
CD 流水线只更新项目目录，不要改 /opt/traefik。

这样 Traefik 是稳定的公共入口，业务项目各自独立发布。新增项目时，只需要新建项目目录、写自己的 compose、配置 DNS、接入一条 CD workflow。

完整脚本

完整脚本不再内嵌在正文里，避免博客内容和实际可执行文件不同步。脚本文件放在这篇文章同目录：install-docker-traefik.sh。

运行后检查

查看 Traefik 容器：

sudo docker compose --env-file /opt/traefik/.env -f /opt/traefik/docker-compose.yml ps

查看日志：

sudo docker compose --env-file /opt/traefik/.env -f /opt/traefik/docker-compose.yml logs -f

测试服务可以这样启动（同样，ACME_EMAIL 必须是真实邮箱）：

ACME_EMAIL=you@your-domain.com INSTALL_SAMPLE=true WHOAMI_HOST=whoami.example.com ./install-docker-traefik.sh

如果 whoami.example.com 能访问，说明 DNS、80/443、防火墙、Traefik 路由和证书申请基本都通了。

如果浏览器一直显示"此网站的证书无效"

按本博客早期示例用过 ACME_EMAIL=admin@example.com 之类占位邮箱的用户会撞到这个问题。Let’s Encrypt 静默拒绝占位邮箱，acme.json 一直不生成，Traefik 只能回落到自签证书。

修法是直接把 traefik.yml 里的 email: 改成真实邮箱，不需要重装：

# 1) 把真实邮箱替换进 traefik.yml
sudo sed -i 's#admin@example.com#you@your-domain.com#' /opt/traefik/traefik.yml
# （如果之前是别的占位值，把 sed 第一个参数里的字面量对应替换）

# 2) 清掉任何残留的 acme.json，让 Traefik 重新申请
sudo rm -f /opt/traefik/letsencrypt/acme.json
sudo touch /opt/traefik/letsencrypt/acme.json
sudo chmod 600 /opt/traefik/letsencrypt/acme.json

# 3) 重启 Traefik，让它从第一个 HTTPS 请求开始走真正的 LE 申请
cd /opt/traefik && sudo docker compose restart traefik

修完后用下面命令验证证书已经换成真证书：

echo | openssl s_client -connect your-domain.com:443 -servername your-domain.com 2>/dev/null \
 | openssl x509 -noout -issuer -subject -dates
# 应该看到 issuer 含 "Let's Encrypt"，subject 是你的域名

注意事项

脚本会按 Docker 官方安装方式添加 apt 仓库，并安装 docker-ce、docker-ce-cli、containerd.io、docker-buildx-plugin、docker-compose-plugin。
脚本会移除可能冲突的旧包，例如 docker.io、旧版 docker-compose、podman-docker、containerd、runc。
Traefik dashboard 使用 api.insecure: true，但端口只绑定到 127.0.0.1:8080，不要改成公网监听，除非你额外加认证。
Traefik 通过只读方式挂载 /var/run/docker.sock。这依然是高权限入口，生产环境要限制谁能创建带 Traefik labels 的容器。
Let’s Encrypt HTTP challenge 需要 80 端口能从公网访问，否则证书申请会失败。
ACME_EMAIL 必须是真实邮箱。脚本会拒绝 admin@example.com、you@example.com、*@example.com 等占位值；不要被早期示例误导。

参考

Woodpecker CI 使用教程

Sun, 07 Jun 2026 10:00:00 +0800

Woodpecker CI 是一个开源、轻量、容器优先的 CI/CD 工具。它的定位很清晰：代码仓库发生 push、pull request、tag、手动触发等事件后，Woodpecker 读取仓库里的 YAML 配置，然后把每个步骤放进容器里执行。

如果你已经熟悉 GitHub Actions，可以把 Woodpecker 理解成一个更偏自托管、更轻量、更贴近 Drone CI 风格的流水线系统。它不绑定某一家代码托管平台，可以接 GitHub、GitLab、Gitea、Forgejo、Bitbucket 等 forge，适合团队希望把 CI/CD 控制权放在自己服务器上的场景。

一、如何安装 Woodpecker CI

第一次了解 Woodpecker CI，建议先用 Docker Compose 跑一个最小可用版本。先跑起来，再理解 pipeline、workflow、step 这些概念会更直观。

下面以接入 GitHub 为例。如果你使用 Gitea、Forgejo 或 GitLab，整体步骤类似，只是 forge 相关环境变量不同。

这篇教程优先写 Docker Compose，是因为它最适合单台服务器和第一次试用。如果你已经有 Kubernetes 集群，应该优先看本节后面的 Helm 安装方式，Helm Chart 也是官方提供的部署方式。

1. 安装前准备

你需要准备：

一台已经安装 Docker 和 Docker Compose 的服务器。
一个能访问 Woodpecker Web UI 的地址，例如 https://ci.example.com。
一个代码平台账号，例如 GitHub、GitLab、Gitea、Forgejo。
目标仓库的管理员权限，因为 Woodpecker 需要创建 webhook。
一个 Server 和 Agent 共享的随机密钥。

生成共享密钥：

openssl rand -hex 32

2. 创建 GitHub OAuth App

如果接 GitHub，需要在 GitHub 创建 OAuth App，不是 GitHub App。

路径：

GitHub -> Settings -> Developer settings -> OAuth Apps -> New OAuth App

关键配置：

Homepage URL: https://ci.example.com
Authorization callback URL: https://ci.example.com/authorize

创建完成后，记录：

Client ID
Client Secret

它们会分别填到 WOODPECKER_GITHUB_CLIENT 和 WOODPECKER_GITHUB_SECRET。

3. 编写 docker-compose.yaml

创建一个目录，例如：

mkdir -p /opt/woodpecker
cd /opt/woodpecker

写入 docker-compose.yaml：

services:
 woodpecker-server:
 image: woodpeckerci/woodpecker-server:v3
 restart: always
 ports:
 - "8000:8000"
 volumes:
 - woodpecker-server-data:/var/lib/woodpecker/
 environment:
 - WOODPECKER_OPEN=true
 - WOODPECKER_HOST=${WOODPECKER_HOST}
 - WOODPECKER_GITHUB=true
 - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
 - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
 - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

 woodpecker-agent:
 image: woodpeckerci/woodpecker-agent:v3
 command: agent
 restart: always
 depends_on:
 - woodpecker-server
 volumes:
 - woodpecker-agent-config:/etc/woodpecker
 - /var/run/docker.sock:/var/run/docker.sock
 environment:
 - WOODPECKER_SERVER=woodpecker-server:9000
 - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

volumes:
 woodpecker-server-data:
 woodpecker-agent-config:

4. 编写 .env

同目录创建 .env：

WOODPECKER_HOST=https://ci.example.com
WOODPECKER_GITHUB_CLIENT=你的 GitHub OAuth App Client ID
WOODPECKER_GITHUB_SECRET=你的 GitHub OAuth App Client Secret
WOODPECKER_AGENT_SECRET=用 openssl rand -hex 32 生成的随机字符串

这里最容易写错的是 WOODPECKER_HOST。它必须是浏览器和代码平台 webhook 都能访问到的 Woodpecker 外部地址，不要写成容器内地址，也不要在末尾加 /。

5. 启动服务

docker compose up -d
docker compose ps

查看日志：

docker compose logs -f woodpecker-server
docker compose logs -f woodpecker-agent

如果一切正常，打开：

https://ci.example.com

使用 GitHub 登录，然后在 Woodpecker UI 里启用你的仓库。

6. 让仓库真正跑起来

Woodpecker 安装完成后，还需要在仓库里添加流水线配置。最小示例是：

.woodpecker/build.yaml

when:
 - event: push
 branch: main

steps:
 - name: hello
 image: alpine
 commands:
 - echo "hello woodpecker"

提交并 push 到 main 后，Woodpecker 应该会收到 webhook 并开始执行 pipeline。

7. 已有 Dokploy / Traefik：不需要 Nginx

如果你已经习惯用 Dokploy 配合 Traefik 快速部署应用，Woodpecker 并不会变难。Woodpecker 不自带 Traefik，但它可以像普通 Web 应用一样接入现有 Traefik 网关。

如果服务器还没有安装 Docker 和 Traefik，可以先按这篇文章准备公共入口层：Docker 和 Traefik 一键安装脚本。

核心思路是：

https://ci.example.com
 |
 v
Traefik / Dokploy 网关
 |
 v
woodpecker-server:8000

Agent 不需要从公网访问 https://ci.example.com。如果 woodpecker-server 和 woodpecker-agent 在同一个 Docker Compose 项目里，Agent 直接用内部地址连接即可：

WOODPECKER_SERVER=woodpecker-server:9000

也就是说，Traefik 只负责 Web UI、OAuth 回调、webhook 入口；Agent 和 Server 的 gRPC 通信可以留在 Docker 内部网络里。

如果由 Dokploy UI 管理域名，通常只需要：

用 Dokploy 创建一个 Docker Compose 应用。
填入 Woodpecker 的 compose 配置。
给 woodpecker-server 配域名，例如 ci.example.com。
让 Dokploy 把外部 HTTPS 转发到容器内部端口 8000。
.env 中保持 WOODPECKER_HOST=https://ci.example.com。

如果你直接写 Traefik labels，可以把 woodpecker-server 改成类似下面这样。网络名、证书 resolver、entrypoint 要替换成你现有 Traefik 的配置：

services:
 woodpecker-server:
 image: woodpeckerci/woodpecker-server:v3
 restart: always
 expose:
 - "8000"
 volumes:
 - woodpecker-server-data:/var/lib/woodpecker/
 environment:
 - WOODPECKER_OPEN=true
 - WOODPECKER_HOST=${WOODPECKER_HOST}
 - WOODPECKER_GITHUB=true
 - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
 - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
 - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
 labels:
 - "traefik.enable=true"
 - "traefik.http.routers.woodpecker.rule=Host(`ci.example.com`)"
 - "traefik.http.routers.woodpecker.entrypoints=websecure"
 - "traefik.http.routers.woodpecker.tls.certresolver=letsencrypt"
 - "traefik.http.services.woodpecker.loadbalancer.server.port=8000"
 networks:
 - traefik-public
 - default

 woodpecker-agent:
 image: woodpeckerci/woodpecker-agent:v3
 command: agent
 restart: always
 depends_on:
 - woodpecker-server
 volumes:
 - woodpecker-agent-config:/etc/woodpecker
 - /var/run/docker.sock:/var/run/docker.sock
 environment:
 - WOODPECKER_SERVER=woodpecker-server:9000
 - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

volumes:
 woodpecker-server-data:
 woodpecker-agent-config:

networks:
 traefik-public:
 external: true

注意这里没有暴露：

ports:
 - "8000:8000"

因为公网入口已经由 Traefik 接管。只有在没有 Traefik、Nginx、Caddy、Dokploy 这类网关时，才需要把端口直接映射出来。

8. Kubernetes 环境：用 Helm 安装

如果你的基础设施已经是 Kubernetes，不需要用上面的 Docker Compose。Woodpecker 官方提供了 Helm Chart，可以直接安装：

helm install woodpecker oci://ghcr.io/woodpecker-ci/helm/woodpecker --version <VERSION>

实际使用时建议带上 namespace：

helm install woodpecker oci://ghcr.io/woodpecker-ci/helm/woodpecker \
 --version <VERSION> \
 --namespace woodpecker \
 --create-namespace

这里的 <VERSION> 是 Helm Chart 版本，不一定等于 Woodpecker Server 的应用版本。安装前可以到官方 Helm 仓库或 release 页面确认当前 chart 版本。

生产环境通常会准备一个 values.yaml，把域名、OAuth、持久化、Ingress 等配置写进去。例如：

server:
 env:
 WOODPECKER_OPEN: "true"
 WOODPECKER_HOST: "https://ci.example.com"
 WOODPECKER_GITHUB: "true"
 WOODPECKER_GITHUB_CLIENT: "你的 GitHub OAuth App Client ID"
 WOODPECKER_GITHUB_SECRET: "你的 GitHub OAuth App Client Secret"
 WOODPECKER_AGENT_SECRET: "用 openssl rand -hex 32 生成的随机字符串"

 ingress:
 enabled: true
 ingressClassName: nginx
 hosts:
 - host: ci.example.com
 paths:
 - path: /
 pathType: Prefix

agent:
 enabled: true

然后执行：

helm upgrade --install woodpecker oci://ghcr.io/woodpecker-ci/helm/woodpecker \
 --version <VERSION> \
 --namespace woodpecker \
 --create-namespace \
 -f values.yaml

选择 Docker Compose 还是 Helm，可以这样判断：

场景	推荐方式
单台云服务器、先学习、先跑通	Docker Compose
已经用 Dokploy / Traefik 管理应用域名	Docker Compose + 现有 Traefik
已经有 Kubernetes 集群	Helm
需要 Ingress、StorageClass、PodMonitor、RBAC 等 K8s 能力	Helm
不熟悉 Kubernetes，只想给个人项目跑 CI	Docker Compose

Helm 不是更高级就一定更适合。它适合已经有 K8s 运维体系的团队；如果只是个人服务器或小团队单机部署，Docker Compose 反而更容易维护。

9. 中国服务器注意事项

如果服务器在中国大陆，安装本身没有特殊问题，但镜像和依赖源要提前规划：

把 woodpeckerci/woodpecker-server:v3、woodpeckerci/woodpecker-agent:v3 同步到国内镜像仓库。
如果使用 Helm，oci://ghcr.io/woodpecker-ci/helm/woodpecker 也可能受 GHCR 网络影响，必要时提前准备代理或内部镜像/制品仓库。
CI 里用到的 node、python、golang 等基础镜像也尽量走私有仓库。
npm、pip、Go modules 配置国内源。
如果 GitHub webhook 到国内服务器不稳定，更推荐自建 Gitea、Forgejo 或 GitLab。

二、为什么关注 Woodpecker CI

Woodpecker CI 值得了解的原因主要有几个：

轻量：核心组件少，部署成本比很多完整 DevOps 平台低。
容器化：每个 step 都运行在指定镜像里，构建环境可复现。
自托管友好：CI 服务、构建 agent、数据都可以放在自己的机器上。
YAML 简洁：常见的 build、test、deploy 流水线写法很直观。
多代码平台支持：不是只能依赖 GitHub Actions 这一类平台内置 CI。

它比较适合下面这些场景：

使用 Gitea、Forgejo、GitLab 自建代码平台，希望配一套轻量 CI。
项目需要访问内网环境，不方便把构建任务放到公有云 CI。
小团队想要一个足够简单、可维护、可迁移的 CI/CD 系统。
已经用 Docker 管理构建、测试和部署环境。

不太适合的场景：

团队已经深度依赖 GitHub Actions Marketplace 或 GitLab CI 生态。
需要复杂的企业级权限、审计、合规工作流。
不希望维护任何 CI 基础设施。

三、核心架构

Woodpecker CI 主要由两个组件组成：

1. Server

Server 负责 Web UI、用户登录、仓库管理、webhook 接收、流水线调度、状态回写等事情。

代码平台有新事件时，例如 push 到 main，平台会通过 webhook 通知 Woodpecker Server。Server 找到对应仓库的流水线配置，然后创建 pipeline。

2. Agent

Agent 负责真正执行流水线任务。它从 Server 接收任务，然后启动容器运行 step。

如果使用 Docker 后端，Agent 通常需要访问宿主机 Docker daemon，所以部署时经常会看到：

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

这意味着 Agent 可以控制宿主机 Docker，权限很高。生产环境里要认真限制谁能修改 CI 配置、谁能拿到 secret、哪些仓库可以运行构建。

3. 执行流程

一个典型流程是：

开发者 push 代码到仓库。
Git 平台通过 webhook 通知 Woodpecker。
Woodpecker Server 拉取仓库配置。
Server 创建 pipeline，并分配给 Agent。
Agent clone 代码，按 YAML 定义依次运行 step。
每个 step 在独立容器里执行命令。
Server 把成功或失败状态回写到代码平台。

四、基本概念

1. Pipeline

Pipeline 是一次完整的 CI/CD 执行，例如某次 push 触发的一轮构建。

2. Workflow

一个 pipeline 至少包含一个 workflow。workflow 是一组共享同一个 workspace 的 step。最简单的配置可以写在 .woodpecker.yaml，也可以把多个 workflow 拆成 .woodpecker/ 目录下的多个 YAML 文件。

例如：

.woodpecker/
 lint.yaml
 test.yaml
 deploy.yaml

Woodpecker 会把这些文件识别成多个 workflow。多个 workflow 可以并行执行，也可以通过 depends_on 建立依赖。

3. Step

Step 是 workflow 里的一个执行单元。每个 step 指定一个镜像，然后在容器里运行命令。

steps:
 - name: test
 image: node:22
 commands:
 - npm ci
 - npm test

4. Plugin

Plugin 本质上也是容器镜像，只是它把常见任务封装好了，例如上传文件、构建镜像、发送通知等。使用 plugin 时一般通过 settings 传参。

steps:
 - name: upload
 image: woodpeckerci/plugin-s3
 settings:
 bucket: my-bucket
 source: public/**/*
 target: /site/
 secret_key:
 from_secret: aws_secret_key

五、创建第一条流水线

在项目根目录创建：

.woodpecker/build.yaml

写入：

when:
 - event: push
 branch: main

steps:
 - name: install
 image: node:22
 commands:
 - npm ci

 - name: test
 image: node:22
 commands:
 - npm test

 - name: build
 image: node:22
 commands:
 - npm run build

这条流水线的含义：

只有 push 到 main 分支才运行。
使用 node:22 镜像作为执行环境。
依次执行安装依赖、测试、构建。
任意命令返回非 0 状态码，后续 step 默认不会继续执行，workflow 标记失败。

如果项目是 Python：

when:
 - event: [push, pull_request]

steps:
 - name: test
 image: python:3.12
 commands:
 - pip install -r requirements.txt
 - pytest

如果项目是 Go：

when:
 - event: [push, pull_request]

steps:
 - name: test
 image: golang:1.23
 commands:
 - go test ./...

六、条件执行

Woodpecker 使用 when 控制 workflow 或 step 在什么情况下执行。

1. 只在 main 分支执行

when:
 - event: push
 branch: main

2. tag 时发布

steps:
 - name: release
 image: alpine
 commands:
 - echo "release version $CI_COMMIT_TAG"
 when:
 - event: tag

3. pull request 只跑测试，不发布

steps:
 - name: test
 image: node:22
 commands:
 - npm ci
 - npm test

 - name: deploy
 image: alpine
 commands:
 - ./deploy.sh
 when:
 - event: push
 branch: main

这个模式很重要：不要在 pull request 事件里暴露部署密钥，尤其是公开仓库。

七、多个 workflow 的拆分

大型项目不建议把所有事情塞进一个 YAML。可以拆成：

.woodpecker/
 lint.yaml
 test.yaml
 docker.yaml
 deploy.yaml

例如 .woodpecker/lint.yaml：

steps:
 - name: lint
 image: node:22
 commands:
 - npm ci
 - npm run lint

.woodpecker/test.yaml：

steps:
 - name: test
 image: node:22
 commands:
 - npm ci
 - npm test

.woodpecker/deploy.yaml：

depends_on:
 - lint
 - test

when:
 - event: push
 branch: main

steps:
 - name: deploy
 image: alpine
 commands:
 - ./deploy.sh

这样做的好处：

lint 和 test 可以更早反馈。
不同 workflow 的状态可以分别回写到代码平台。
workflow 可以并行跑，提升整体速度。
deploy 明确依赖 lint 和 test 成功。

八、Secret 管理

CI/CD 经常要用密钥，例如 Docker registry 密码、SSH 私钥、云服务 token。不要把这些值写进仓库 YAML。

Woodpecker 的 secret 可以通过 UI 或 CLI 设置，然后在 YAML 中用 from_secret 引用：

steps:
 - name: deploy
 image: alpine
 environment:
 SSH_KEY:
 from_secret: production_ssh_key
 commands:
 - mkdir -p ~/.ssh
 - echo "$SSH_KEY" > ~/.ssh/id_rsa
 - chmod 600 ~/.ssh/id_rsa
 - ./deploy.sh

也可以传给 plugin：

steps:
 - name: publish-image
 image: woodpeckerci/plugin-docker-buildx
 settings:
 repo: registry.example.com/my-app
 tags: latest
 username:
 from_secret: registry_username
 password:
 from_secret: registry_password

Secret 使用建议：

不要在日志里 echo secret。
不要默认把 secret 暴露给 pull request。
公开仓库尤其要警惕来自 fork 的 PR。
为生产环境和测试环境使用不同 secret。
定期轮换部署密钥。

九、常见流水线模板

1. 前端项目：测试并构建

when:
 - event: [push, pull_request]

steps:
 - name: build
 image: node:22
 commands:
 - npm ci
 - npm run lint
 - npm test
 - npm run build

2. Docker 镜像构建

when:
 - event: push
 branch: main

steps:
 - name: docker
 image: woodpeckerci/plugin-docker-buildx
 settings:
 repo: registry.example.com/my-app
 tags:
 - latest
 - ${CI_COMMIT_SHA}
 username:
 from_secret: registry_username
 password:
 from_secret: registry_password

3. 部署到服务器

depends_on:
 - build

when:
 - event: push
 branch: main

steps:
 - name: deploy
 image: alpine:3.20
 environment:
 SSH_KEY:
 from_secret: production_ssh_key
 DEPLOY_HOST:
 from_secret: production_host
 commands:
 - apk add --no-cache openssh-client
 - mkdir -p ~/.ssh
 - echo "$SSH_KEY" > ~/.ssh/id_rsa
 - chmod 600 ~/.ssh/id_rsa
 - ssh -o StrictHostKeyChecking=no "$DEPLOY_HOST" "cd /opt/app && docker compose pull && docker compose up -d"

这个例子能跑通，但生产中建议更严谨：

不要长期关闭 StrictHostKeyChecking。
使用最小权限部署用户。
服务器端只允许执行必要命令。
部署前保留当前版本，方便回滚。

十、和 GitHub Actions 的区别

对比项	Woodpecker CI	GitHub Actions
部署方式	主要面向自托管	GitHub 托管为主，也支持 self-hosted runner
代码平台	可接多种 forge	深度绑定 GitHub
执行模型	step 基于容器镜像	action + shell + runner 环境
配置风格	简洁，接近 Drone CI	功能丰富，语法更庞大
生态	插件生态较小	Marketplace 很大
适合场景	自建 Git、内网部署、轻量 CI	GitHub 项目、丰富第三方 action、托管 CI

简单判断：

你的代码主要放 GitHub，并且不想维护 CI 服务器：优先 GitHub Actions。
你在用 Gitea/Forgejo，或者需要内网自托管：Woodpecker CI 很值得试。
你希望 CI 配置尽量贴近容器和 shell：Woodpecker CI 的心智负担较低。

十一、生产使用建议

1. 给 CI 单独准备机器

不要把 Woodpecker Agent 随便放在核心业务机器上。Agent 需要运行不可信代码，尤其在多人协作或开源仓库里，风险很高。

2. 限制仓库和用户权限

谁能启用仓库、谁能改 .woodpecker/ 配置、谁能读取 secret，都要明确。

3. 注意 Docker socket 风险

挂载 /var/run/docker.sock 等于让 Agent 拥有很高的宿主机控制能力。能不用特权就不用特权，能隔离 agent 就隔离 agent。

4. 持久化和备份数据

Server 数据目录里包含用户、仓库、流水线等信息。Docker Compose 部署时要持久化 /var/lib/woodpecker/，并做定期备份。

5. 使用 HTTPS

WOODPECKER_HOST 建议配置成 HTTPS 地址。已有 Dokploy、Traefik、Caddy、Nginx 或云平台网关时，直接复用现有网关即可，不需要为了 Woodpecker 额外改用 Nginx。

6. 把流水线当代码审查

.woodpecker/ 下的 YAML 能决定 CI 机器执行什么命令。它应该像业务代码一样经过 review。

十二、排查问题的思路

1. 仓库没有触发流水线

检查：

仓库是否已在 Woodpecker UI 中启用。
当前用户是否有仓库 admin 权限。
代码平台 webhook 是否创建成功。
.woodpecker.yaml 或 .woodpecker/*.yaml 路径是否正确。
when 条件是否把事件过滤掉了。

2. Agent 不执行任务

检查：

woodpecker-agent 容器是否在运行。
WOODPECKER_SERVER 是否能访问。
WOODPECKER_AGENT_SECRET 是否和 Server 一致。
gRPC 端口是否被网络或反向代理挡住。
Docker socket 是否挂载成功。

3. step 找不到文件

检查：

文件是否在仓库里。
前一个 step 生成的文件是否写在 workspace 内。
多 workflow 之间不共享 workspace，只有同一个 workflow 内的 step 共享。

4. secret 为空

检查：

secret 名称是否和 from_secret 一致。
当前事件是否允许使用该 secret。
pull request 是否被默认限制访问 secret。
secret 是否被限制到某些 plugin 或 image。

十三、总结

Woodpecker CI 的核心价值是：用较少的组件，搭建一套可自托管、容器化、配置直观的 CI/CD 系统。

学习它时可以按这个顺序：

先用 Docker Compose 或 Helm 跑一个最小实例。
在仓库里创建 .woodpecker/build.yaml，确认 webhook 能触发 pipeline。
再理解 Server、Agent、Pipeline、Workflow、Step 的关系。
掌握 steps、commands、when、depends_on、from_secret。
逐步拆分 lint、test、build、deploy 多个 workflow。
最后考虑生产环境的权限、安全、备份和 agent 隔离。

如果你维护的是自建 Git 平台，或者项目部署强依赖内网环境，Woodpecker CI 是一个很务实的选择。