Woodpecker 与 Gitea 集成

Woodpecker CI 是 Drone CI 的社区开源分支，是一款轻量级的持续集成/持续部署（CI/CD）平台。它原生支持 Gitea、GitHub、GitLab 等代码托管平台，使用简洁的 YAML 语法定义构建管道，每个构建步骤都在隔离的 Docker 容器中执行。Woodpecker 资源占用少、配置简单，非常适合在搬瓦工 VPS 上与 Gitea 搭配使用。

一、前置准备

已安装并运行 Gitea。
已安装 Docker 和 Docker Compose。
至少 1GB 内存。

二、在 Gitea 中创建 OAuth 应用

Woodpecker 通过 OAuth 与 Gitea 集成。在 Gitea 中创建 OAuth 应用：

进入 Gitea 管理界面 -> "应用" -> "创建新的 OAuth2 应用"。
应用名称填写 Woodpecker CI。
回调地址填写 https://ci.your-domain.com/authorize。
记录生成的 Client ID 和 Client Secret。

三、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"
    volumes:
      - woodpecker-data:/var/lib/woodpecker
    environment:
      - WOODPECKER_HOST=https://ci.your-domain.com
      - WOODPECKER_OPEN=true
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=https://git.your-domain.com
      - WOODPECKER_GITEA_CLIENT=YOUR_GITEA_CLIENT_ID
      - WOODPECKER_GITEA_SECRET=YOUR_GITEA_CLIENT_SECRET
      - WOODPECKER_AGENT_SECRET=YourAgentSecretKeyHere123456
      - WOODPECKER_ADMIN=your-gitea-admin-username

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

volumes:
  woodpecker-data:
EOF

docker compose up -d

四、Nginx 反向代理

cat > /etc/nginx/sites-available/woodpecker <<'EOF'
server {
    listen 443 ssl http2;
    server_name ci.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/ci.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ci.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -sf /etc/nginx/sites-available/woodpecker /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

五、编写 Pipeline

在 Git 仓库根目录创建 .woodpecker.yml 文件定义构建管道。

5.1 基础构建

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

5.2 多步骤管道

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

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

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

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

5.3 Docker 镜像构建

steps:
  - name: build-docker
    image: plugins/docker
    settings:
      repo: registry.your-domain.com/myapp
      registry: registry.your-domain.com
      username:
        from_secret: registry_user
      password:
        from_secret: registry_pass
      tags:
        - latest
        - ${CI_COMMIT_TAG}
    when:
      event: tag

5.4 部署步骤

steps:
  - name: deploy
    image: appleboy/drone-ssh
    settings:
      host:
        from_secret: deploy_host
      username:
        from_secret: deploy_user
      key:
        from_secret: deploy_key
      script:
        - cd /opt/myapp
        - docker compose pull
        - docker compose up -d
    when:
      branch: main
      event: push

六、管理 Secrets

在 Woodpecker Web 界面中，进入仓库设置添加 Secrets。Secrets 在 Pipeline 中通过 from_secret 引用，构建日志中不会显示 Secret 的值。

七、条件触发

steps:
  - name: deploy-staging
    image: alpine
    commands:
      - echo "Deploying to staging"
    when:
      branch: develop

  - name: deploy-production
    image: alpine
    commands:
      - echo "Deploying to production"
    when:
      branch: main
      event: tag

八、常见问题

OAuth 回调失败

确保 Gitea 的 OAuth 回调地址与 Woodpecker 的 WOODPECKER_HOST 一致。

Agent 无法连接 Server

确保 WOODPECKER_AGENT_SECRET 在 Server 和 Agent 配置中完全一致。

总结

Woodpecker CI 是与 Gitea 搭配使用的理想 CI/CD 工具，配置简单且资源占用低。在搬瓦工 VPS 上可以轻松构建完整的代码托管和自动化部署体系。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 折扣。相关教程：Gitea Actions 教程、Act Runner 配置。