DPTCloud
Quay lại danh sách
Tin tức công nghệ

Triển khai Woodpecker CI trên VPS: Hệ thống tích hợp liên tục siêu nhẹ chạy bằng Docker

1 tháng 6, 2026

Giới thiệu về Woodpecker CI và xu hướng tối ưu hóa tài nguyên

Trong kỷ nguyên chuyển đổi số, Tích hợp liên tục và Triển khai liên tục (CI/CD) đã trở thành xương sống của mọi quy trình phát triển phần mềm hiện đại. Tuy nhiên, đối với các doanh nghiệp vừa và nhỏ (SMEs) hoặc các nhóm phát triển độc lập, việc vận hành các hệ thống CI/CD lớn như Jenkins, GitLab CI hay Drone CI thường đi kèm với gánh nặng lớn về chi phí phần cứng và tài nguyên vận hành. Các công cụ này đòi hỏi mức RAM tối thiểu từ 2GB đến 4GB chỉ để duy trì trạng thái chờ, gây lãng phí nghiêm trọng trên các máy chủ ảo (VPS) có cấu hình khiêm tốn.

Đó là lý do Woodpecker CI xuất hiện như một giải pháp thay thế hoàn hảo. Được tách nhánh (fork) và phát triển độc lập từ mã nguồn mở của Drone CI (phiên bản trước khi chuyển sang giấy phép thương mại), Woodpecker CI kế thừa toàn bộ triết lý thiết kế hiện đại: cấu hình bằng YAML, thực thi bằng Docker container, nhưng được tối ưu hóa cấu trúc để đạt mức tiêu thụ tài nguyên cực thấp. Một hệ thống Woodpecker CI hoàn chỉnh bao gồm cả Server và Agent có thể vận hành mượt mà chỉ với chưa đầy 100MB RAM, giải phóng tối đa hiệu năng của VPS cho các tác vụ cốt lõi.

"Woodpecker CI mang lại trải nghiệm CI/CD hiện đại, dựa trên container độc lập mà không làm cạn kiệt tài nguyên VPS của bạn. Đây là vũ khí bí mật cho các kiến trúc sư giải pháp muốn tối ưu hóa chi phí vận hành."
---

Kiến trúc cốt lõi của Woodpecker CI

Để triển khai và vận hành Woodpecker CI hiệu quả, chúng ta cần hiểu rõ mô hình kiến trúc phân tán (Distributed Architecture) của hệ thống này. Woodpecker tách biệt hoàn toàn hai thành phần chính cấu thành nên hệ thống:

  • Woodpecker Server: Đóng vai trò là bộ não điều khiển trung tâm. Thành phần này chịu trách nhiệm quản lý giao diện người dùng (Web UI), xử lý các API, tiếp nhận Webhook từ các nền tảng Git (GitHub, GitLab, Gitea) và điều phối các tác vụ (jobs) vào hàng đợi.
  • Woodpecker Agent: Đóng vai trò là các công nhân thực thi (workers). Agent sẽ liên tục kết nối với Server qua giao thức gRPC bảo mật để nhận tác vụ, sau đó khởi chạy các Docker container tương ứng để thực hiện việc biên dịch, kiểm thử hoặc triển khai mã nguồn theo đúng kịch bản được định nghĩa.

Nhờ kiến trúc này, bạn có thể cài đặt Server và Agent trên cùng một VPS để tiết kiệm tài nguyên, hoặc dễ dàng mở rộng bằng cách đặt nhiều Agent ở các VPS khác nhau khi khối lượng công việc tăng lên.

---

Điều kiện tiên quyết trước khi cài đặt

Trước khi bắt đầu quá trình triển khai Woodpecker CI lên VPS, hãy đảm bảo hệ thống của bạn đáp ứng các yêu cầu kỹ thuật cơ bản sau:

  1. Một máy chủ VPS chạy hệ điều hành Linux (khuyến nghị Ubuntu 22.04 LTS hoặc mới hơn) có địa chỉ IP công khai (Public IP).
  2. Đã cài đặt Docker và Docker Compose v2 lên hệ thống.
  3. Một tên miền (Domain hoặc Subdomain) đã được trỏ về IP của VPS (ví dụ: ci.company.com).
  4. Tài khoản quản trị viên trên một nền tảng quản lý mã nguồn (được hỗ trợ là GitHub, GitLab, Gitea, hoặc Bitbucket) để cấu hình ứng dụng OAuth (OAuth Application).
---

Hướng dẫn từng bước triển khai Woodpecker CI bằng Docker Compose

Bước 1: Cấu hình OAuth Application trên Git Provider (Ví dụ với GitHub)

Để Woodpecker CI có thể xác thực người dùng và nhận sự kiện qua Webhook, bạn cần tạo một ứng dụng OAuth trên GitHub bằng cách truy cập vào Settings > Developer Settings > OAuth Apps > Register a new application. Điền thông tin như sau:

  • Application Name: Woodpecker CI
  • Homepage URL: [https://ci.company.com](https://ci.company.com)
  • Authorization callback URL: [https://ci.company.com/authorize](https://ci.company.com/authorize)

Sau khi đăng ký, hãy lưu lại hai thông số quan trọng là Client ID và Client Secret.

Bước 2: Tạo cấu trúc thư mục và tệp cấu hình môi trường

Truy cập vào VPS thông qua SSH và tạo một thư mục chuyên biệt cho Woodpecker CI để dễ dàng quản lý dữ liệu:

mkdir -p /opt/woodpecker
cd /opt/woodpecker
nano .env

Hãy sao chép và điều chỉnh nội dung sau vào tệp .env của bạn:

# Cấu hình chung
WOODPECKER_HOST=[https://ci.company.com](https://ci.company.com)
WOODPECKER_SECRET=khởi_tạo_một_chuỗi_ngẫu_nhiên_32_ký_tự

# Cấu hình GitHub OAuth
WOODPECKER_GITHUB=true
WOODPECKER_GITHUB_CLIENT=nhập_client_id_của_bạn
WOODPECKER_GITHUB_SECRET=nhập_client_secret_của_bạn

Bước 3: Xây dựng tệp docker-compose.yml

Tạo tệp cấu hình Docker Compose để định nghĩa dịch vụ cho cả Server và Agent kết nối đồng bộ với nhau:

nano docker-compose.yml

Nội dung tệp cấu hình cụ thể như sau:

version: '3.8'

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

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v2.4.0
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:8000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_SECRET}

volumes:
  woodpecker-server-data:
    driver: local

Bước 4: Khởi chạy hệ thống và cấu hình Reverse Proxy

Thực hiện lệnh sau để khởi chạy các container dưới dạng chạy ngầm (detached mode):

docker compose up -d

Để đảm bảo an toàn bảo mật dữ liệu, bạn nên cấu hình một Reverse Proxy như Nginx hoặc Caddy ở phía trước để xử lý chứng chỉ SSL/TLS miễn phí từ Let's Encrypt, chuyển hướng toàn bộ lưu lượng truy cập từ cổng 80/443 vào cổng 8000 của Woodpecker Server.

---

Xây dựng Pipeline đầu tiên với Woodpecker CI

Khi hệ thống đã hoạt động, bạn chỉ cần truy cập vào tên miền của mình, đăng nhập bằng tài khoản GitHub và kích hoạt kho lưu trữ mã nguồn (Repository) mong muốn. Để định nghĩa quy trình CI/CD, hãy tạo một tệp tin có tên là .woodpecker.yml tại thư mục gốc của dự án với cấu trúc sau:

pipeline:
  build:
    image: node:20-alpine
    commands:
      - npm install
      - npm run build

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

  deploy:
    image: appleboy/drone-ssh
    settings:
      host: production.server.com
      username: deploy
      key: 
        from_secret: deploy_key
      script:
        - cd /var/www/app && git pull && pm2 restart app
    when:
      branch: main
      event: push

Cấu trúc này cực kỳ dễ đọc và tường minh. Mỗi bước trong pipeline được thực thi bên trong một Docker container chuyên biệt cô lập hoàn toàn, giúp loại bỏ hoàn toàn tình trạng xung đột phiên bản phần mềm trên môi trường máy chủ xây dựng (Build Server).

---

Đánh giá ưu điểm vượt trội và kết luận

Qua quá trình triển khai và vận hành thực tế, Woodpecker CI chứng minh được giá trị vượt trội thông qua các chỉ số cụ thể:

Tiêu chí so sánh Jenkins Woodpecker CI
RAM tiêu thụ tối thiểu ~1.5 GB - 2 GB < 100 MB
Cấu hình Pipeline Groovy DSL / Web UI phức tạp Mã nguồn YAML tinh gọn
Môi trường thực thi Phụ thuộc vào hệ điều hành host Docker Container cô lập hoàn toàn

Tóm lại, việc tự triển khai Woodpecker CI trên VPS bằng Docker mang lại cho doanh nghiệp quyền kiểm soát hoàn toàn dữ liệu mã nguồn, tối ưu hóa triệt để chi phí hạ tầng phần cứng mà vẫn đảm bảo được hiệu năng mạnh mẽ, hiện đại của một quy trình DevOps chuẩn mực. Đây chắc chắn là mô hình kiến trúc hạ tầng xứng đáng đầu tư cho mọi dự án phần mềm linh hoạt hiện nay.

Triển khai Woodpecker CI trên VPS: Hệ thống tích hợp liên tục siêu nhẹ chạy bằng Docker | DPTCloud