搬瓦工 VPS 搭建 Woodpecker CI 轻量持续集成教程

Woodpecker CI 是 Drone CI 的社区开源分支，是一款轻量级的持续集成/持续部署平台。Woodpecker 使用 Docker 容器执行构建任务，通过 YAML 文件定义 Pipeline，支持 Gitea、GitHub、GitLab、Forgejo 等多种 Git 平台。相比 Jenkins 等重量级 CI 系统，Woodpecker 资源占用极小，配置简洁直观，非常适合在搬瓦工 VPS 上运行个人或小团队的 CI/CD 系统。部署前请确保已安装好 Docker 和 Docker Compose。

一、Woodpecker 架构

Server：提供 Web 界面和 API，管理 Pipeline 并接收 Git Webhook 事件。
Agent：执行构建任务的工作节点，通过 gRPC 与 Server 通信，可以部署多个 Agent 扩展并发能力。
Pipeline：用 YAML 定义的构建流程，每个步骤在独立的 Docker 容器中运行，保证环境隔离。

二、Docker Compose 部署

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

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    restart: always
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      WOODPECKER_HOST: https://ci.example.com
      WOODPECKER_OPEN: "true"
      WOODPECKER_GITEA: "true"
      WOODPECKER_GITEA_URL: https://git.example.com
      WOODPECKER_GITEA_CLIENT: your_gitea_oauth_client_id
      WOODPECKER_GITEA_SECRET: your_gitea_oauth_secret
      WOODPECKER_AGENT_SECRET: agent_shared_secret_2026
      WOODPECKER_DATABASE_DRIVER: sqlite3
      WOODPECKER_DATABASE_DATASOURCE: /var/lib/woodpecker/woodpecker.sqlite
    volumes:
      - woodpecker_data:/var/lib/woodpecker

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent
    restart: always
    depends_on:
      - woodpecker-server
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000
      WOODPECKER_AGENT_SECRET: agent_shared_secret_2026
      WOODPECKER_MAX_WORKFLOWS: 2
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  woodpecker_data:
EOF

docker compose up -d

三、对接 GitHub

如果使用 GitHub 而非 Gitea，修改环境变量：

# 替换 Gitea 配置为 GitHub
WOODPECKER_GITHUB: "true"
WOODPECKER_GITHUB_CLIENT: your_github_oauth_app_client_id
WOODPECKER_GITHUB_SECRET: your_github_oauth_app_secret

在 GitHub 上创建 OAuth App，回调 URL 设置为 https://ci.example.com/authorize。

四、Pipeline 配置

在代码仓库根目录创建 .woodpecker.yml：

when:
  branch: main
  event: [push, pull_request]

steps:
  - name: install
    image: node:20-alpine
    commands:
      - npm ci

  - name: lint
    image: node:20-alpine
    commands:
      - npm run lint

  - name: test
    image: node:20-alpine
    commands:
      - npm test

  - name: build
    image: node:20-alpine
    commands:
      - npm run build
    when:
      event: push
      branch: main

  - name: deploy
    image: alpine
    when:
      branch: main
      event: push
    commands:
      - apk add --no-cache openssh-client
      - mkdir -p ~/.ssh
      - echo "$SSH_KEY" > ~/.ssh/id_ed25519
      - chmod 600 ~/.ssh/id_ed25519
      - ssh -o StrictHostKeyChecking=accept-new root@production "cd /opt/app && git pull && npm install --production && systemctl restart app"
    secrets: [ssh_key]

五、Secret 管理

在 Web 界面的仓库设置中添加 Secret，或通过 CLI：

# 安装 Woodpecker CLI
wget https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli_linux_amd64.tar.gz
tar xzf woodpecker-cli_linux_amd64.tar.gz
mv woodpecker-cli /usr/local/bin/

# 配置
export WOODPECKER_SERVER=https://ci.example.com
export WOODPECKER_TOKEN=your_personal_token

# 添加 Secret
woodpecker-cli secret add \
  --repository owner/repo \
  --name ssh_key \
  --value "$(cat ~/.ssh/deploy_key)" \
  --event push,deployment

六、Docker 镜像构建 Pipeline

steps:
  - name: build-docker
    image: plugins/docker
    settings:
      repo: registry.example.com/myapp
      tags:
        - latest
        - "${CI_COMMIT_SHA:0:8}"
      registry: registry.example.com
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password

  - name: deploy-k8s
    image: bitnami/kubectl
    commands:
      - kubectl set image deployment/myapp myapp=registry.example.com/myapp:${CI_COMMIT_SHA:0:8}
    when:
      branch: main
      event: push

七、多 Pipeline 支持

# .woodpecker/test.yml
when:
  event: [push, pull_request]

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

# .woodpecker/deploy.yml
depends_on:
  - test

when:
  branch: main
  event: push

steps:
  - name: deploy
    image: alpine
    commands:
      - echo "Deploying to production..."

八、Nginx 反向代理

cat > /etc/nginx/conf.d/woodpecker.conf <<'EOF'
server {
    listen 443 ssl http2;
    server_name ci.example.com;

    ssl_certificate /etc/letsencrypt/live/ci.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ci.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

nginx -t && systemctl reload nginx

九、常见问题

Agent 无法连接 Server

确保 WOODPECKER_AGENT_SECRET 在 Server 和 Agent 的环境变量中完全一致。

docker logs woodpecker-agent
docker logs woodpecker-server

Pipeline 步骤超时

默认超时 60 分钟，可在步骤中添加 timeout: 120m 增加超时时间。

总结

Woodpecker CI 是轻量高效的 CI/CD 方案，搭配 Gitea 可以构建完全自托管的代码管理和持续集成系统。如果需要本地调试 GitHub Actions Workflow，推荐 Act。构建的镜像可以推送到 Harbor 镜像仓库。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。