Woodpecker CI 使用 Docker Compose 部署指南

章迅筝Diane

于 2025-06-08 09:15:11 发布

阅读量256

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00109/article/details/148508002

Woodpecker CI 使用 Docker Compose 部署指南

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker

前言

Woodpecker CI 是一个轻量级的持续集成工具，采用 Go 语言编写。本文将详细介绍如何使用 Docker Compose 部署 Woodpecker CI 服务端和代理端，帮助开发者快速搭建自己的 CI/CD 环境。

核心组件

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

服务端(Server)：负责管理用户界面、处理 Webhook 请求和协调构建任务
代理端(Agent)：负责实际执行构建任务，运行在 Docker 容器中

基础部署配置

1. 准备 docker-compose.yaml 文件

创建一个基本的 docker-compose.yaml 文件，包含服务端和代理端的配置：

version: '3'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3
    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:

2. 关键配置说明

持久化存储：
- woodpecker-server-data 卷用于存储 SQLite 数据库，包含所有用户和仓库信息
- woodpecker-agent-config 卷用于存储代理配置
网络端口：
- 服务端默认暴露 8000 端口用于 HTTP 访问
- 内部使用 9000 端口用于 gRPC 通信
环境变量：
- WOODPECKER_HOST：必须设置为 Woodpecker 的公网访问地址
- WOODPECKER_AGENT_SECRET：服务端和代理端共享的密钥，用于安全通信

高级配置选项

1. 自定义端口

可以通过环境变量修改默认端口：

environment:
  - WOODPECKER_GRPC_ADDR=:9000  # gRPC 端口
  - WOODPECKER_SERVER_ADDR=:8000  # HTTP 端口

2. 启用 gRPC TLS 加密

对于通过公网通信的场景，建议启用 TLS 加密：

environment:
  - WOODPECKER_GRPC_SECURE=true
  - WOODPECKER_GRPC_VERIFY=true

3. 代理端 Docker 访问

代理端需要访问宿主机 Docker 守护进程来运行构建容器：

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

安全最佳实践

1. 敏感信息管理

推荐使用 Docker Secrets 管理敏感信息：

services:
  woodpecker-server:
    environment:
      - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
    secrets:
      - woodpecker-agent-secret

secrets:
  woodpecker-agent-secret:
    external: true

创建 secret 的命令：

echo "your-secret-key" | docker secret create woodpecker-agent-secret -

2. 生成安全密钥

使用 OpenSSL 生成强密钥：

openssl rand -hex 32

部署与启动

创建 .env 文件，包含所有必要的环境变量
运行部署命令：

docker-compose up -d

验证服务运行状态：

docker-compose ps

常见问题解决

代理无法连接服务端：
- 检查 WOODPECKER_SERVER 地址是否正确
- 验证 WOODPECKER_AGENT_SECRET 是否匹配
- 确认网络连接和端口配置
构建任务无法启动：
- 检查代理端是否有 Docker 访问权限
- 验证 /var/run/docker.sock 挂载是否正确
服务无法访问：
- 检查 WOODPECKER_HOST 设置是否正确
- 验证防火墙和端口映射配置