Posted inHomeLab

Triển khai Semaphore UI trên Docker: Quản lý Ansible qua giao diện Web cho HomeLab

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

So sánh các phương pháp: Quản lý Ansible tại gia

Quản lý cấu hình trên nhiều máy chủ vật lý, máy ảo và các node Proxmox thường bắt đầu bằng lệnh ansible-playbook -i inventory.ini site.yml chạy trực tiếp từ máy trạm chính của bạn. Dùng lệnh CLI thủ công ban đầu khá tiện và hiệu quả.

Tuy nhiên, các điểm bất tiện sẽ sớm xuất hiện. Log của playbook bị trôi mất theo lịch sử cuộn terminal, các cron job tự động thiếu khả năng giám sát tập trung, và SSH private key lưu trữ không an toàn trong cấu hình shell cục bộ. Việc kích hoạt chạy playbook từ điện thoại hay laptop phụ gần như là bất khả thi.

Khi tìm kiếm một công cụ điều phối trung tâm trên giao diện web, các kỹ sư homelab thường cân nhắc ba hướng tiếp cận:

  • Dùng CLI thuần & Crontab: Không tốn tài nguyên và không cần cài đặt. Đổi lại, bạn mất đi lịch sử thực thi, khả năng phân quyền nhiều người dùng, quản lý secret tập trung và tích hợp webhook.
  • Red Hat AWX (Bản mã nguồn mở của Ansible Tower): Tiêu chuẩn dành cho doanh nghiệp. AWX cung cấp đầy đủ các tính năng điều phối tự động hóa, nhưng yêu cầu một cụm Kubernetes (hoặc K3s) và ngốn từ 4GB đến 8GB RAM ngay cả khi không tải. Trên một chiếc Intel NUC hay mini PC chỉ có 16GB RAM, mức tiêu thụ này chiếm quá nhiều dung lượng của hệ thống.
  • Semaphore UI: Bảng điều khiển web nhanh, mượt mà được viết bằng Go và Vue.js. Semaphore chạy gọn gàng trong các Docker container tiêu chuẩn, chỉ tiêu thụ khoảng 80MB đến 120MB RAM, hỗ trợ backend PostgreSQL, quản lý inventory và vault secret nguyên bản, đồng thời tích hợp sẵn tính năng lập lịch cron cùng webhook.

Bảng so sánh chi tiết

Tiêu chí CLI + Crontab Red Hat AWX Semaphore UI
Mức chiếm dụng RAM Tối thiểu (<50MB khi chạy) Rất nặng (4GB – 8GB RAM khi nhàn rỗi) Nhẹ nhàng (~100MB RAM)
Môi trường triển khai Máy vật lý / Máy trạm Kubernetes / K3s / Minikube Docker / Docker Compose
Giao diện Web & Log Không có (Chỉ có output terminal) Toàn diện, hướng tới doanh nghiệp Gọn gàng, nhanh, stream log thời gian thực
RBAC & Thông tin xác thực Phân quyền file thủ công RBAC chi tiết đến từng đối tượng Kho lưu trữ Team, Project & Key
Độ phù hợp với HomeLab Phù hợp để test nhanh Thường chiếm quá nhiều tài nguyên Cân bằng tối ưu giữa tính năng & tài nguyên

Ưu và nhược điểm của Semaphore UI

Trước khi khởi chạy container, hãy cùng đánh giá xem Semaphore phát huy thế mạnh ở đâu và có những giới hạn nào.

Ưu điểm

  • Tối ưu tài nguyên vượt trội: Bạn có thể chạy Semaphore mượt mà trên Raspberry Pi 4 2GB hoặc container LXC không đặc quyền mà không hề lo tràn RAM.
  • Tương thích nguyên bản với Ansible: Do Semaphore gọi trực tiếp các binary Ansible CLI ngầm bên dưới, toàn bộ playbook, role và collection hiện tại của bạn đều chạy bình thường mà không cần sửa đổi cú pháp.
  • Kho lưu trữ thông tin xác thực tập trung: SSH key, mật khẩu sudo và passphrase của Ansible Vault được mã hóa an toàn khi lưu trữ trong PostgreSQL và chỉ được nạp vào bộ nhớ tạm trong suốt quá trình chạy job.
  • API & Webhook tiện lợi: Tự động kích hoạt các lượt chạy thông qua push hook của Gitea hoặc cảnh báo từ Prometheus và Alertmanager.
  • Stream log trực tiếp: Theo dõi tiến độ thực thi tác vụ theo thời gian thực qua giao diện terminal trên trình duyệt với log phân màu trực quan và hiển thị chính xác thời gian chạy.

Nhược điểm

  • Không có công cụ trực quan hóa Dynamic Inventory: Semaphore thực thi các script dynamic inventory lấy từ Git repository, nhưng không hỗ trợ vẽ biểu đồ cấu trúc mạng hay topology trực quan trên giao diện UI.
  • Ma trận phân quyền tương đối đơn giản: Semaphore cô lập người dùng theo từng project, thiếu đi các chính sách phân quyền chi tiết cho từng inventory hay từng credential như trên AWX.
  • Quản lý phụ thuộc Collection: Nếu playbook phụ thuộc vào các collection như community.docker hoặc ansible.posix, bạn phải khai báo chúng trong file requirements.yml của repository hoặc build sẵn vào custom container image.

Kiến trúc cài đặt khuyến nghị

Chạy Semaphore song song với PostgreSQL bằng Docker Compose giúp cô lập các service rõ ràng và giúp việc sao lưu định kỳ hàng ngày trở nên đơn giản với tiện ích pg_dump tiêu chuẩn.

Mô hình triển khai mục tiêu bao gồm:

  1. PostgreSQL 16 Engine: Dù Semaphore hỗ trợ cả MySQL và SQLite, PostgreSQL xử lý migration mượt mà và đảm bảo tính đồng thời tin cậy khi kích hoạt nhiều playbook cùng lúc.
  2. Container Semaphore chính thức: Image dựa trên Alpine tích hợp sẵn Ansible Core, Git và OpenSSH client ngay khi khởi tạo.
  3. Mạng Docker Bridge cô lập: Giới hạn cổng kết nối database chỉ cho phép Semaphore truy cập, đồng thời điều hướng lưu lượng web qua cổng 3000 đến reverse proxy của bạn (như Traefik, Nginx Proxy Manager hoặc Caddy) kèm TLS.
  4. Named Persistent Volume: Giữ lại trạng thái cơ sở dữ liệu, secret mã hóa và bộ nhớ đệm playbook đã clone qua các lần nâng cấp container.

Hướng dẫn triển khai: Cài đặt Semaphore trên Docker

Bước 1: Thiết lập thư mục và Secret môi trường

Đăng nhập vào Docker host và tạo cấu trúc thư mục riêng cho stack:

mkdir -p ~/semaphore/{config,data/postgres}
cd ~/semaphore

Tạo các khóa mật mã để ký cookie, mã hóa cơ sở dữ liệu và xác thực PostgreSQL:

COOKIE_HASH=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -base64 32)
DB_PASS=$(openssl rand -hex 16)

cat <<EOF > .env
SEMAPHORE_COOKIE_HASH=${COOKIE_HASH}
SEMAPHORE_ACCESS_KEY_ENCRYPTION=${ENCRYPTION_KEY}
POSTGRES_PASSWORD=${DB_PASS}
EOF

chmod 600 .env
echo "Đã tạo file .env với các secret ngẫu nhiên."

Bước 2: Tạo file Docker Compose

Tạo file docker-compose.yml trong thư mục dự án:

nano docker-compose.yml

Thêm cấu hình dịch vụ bên dưới, tự động đọc thông tin xác thực trực tiếp từ file .env của bạn:

networks:
  semaphore-net:
    driver: bridge

volumes:
  semaphore-postgres:
  semaphore-data:
  semaphore-config:

services:
  postgres:
    image: postgres:16-alpine
    container_name: semaphore-postgres
    restart: unless-stopped
    networks:
      - semaphore-net
    volumes:
      - semaphore-postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: semaphore
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: semaphore
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U semaphore -d semaphore"]
      interval: 5s
      timeout: 5s
      retries: 5

  semaphore:
    image: semaphoreui/semaphore:v2.10.35
    container_name: semaphore-ui
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - semaphore-net
    ports:
      - "3000:3000"
    environment:
      SEMAPHORE_DB_USER: semaphore
      SEMAPHORE_DB_PASS: ${POSTGRES_PASSWORD}
      SEMAPHORE_DB_HOST: postgres
      SEMAPHORE_DB_PORT: "5432"
      SEMAPHORE_DB_DIALECT: postgres
      SEMAPHORE_DB: semaphore
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore
      SEMAPHORE_ADMIN_PASSWORD: InitialAdminPassword123!
      SEMAPHORE_ADMIN_NAME: Lab Admin
      SEMAPHORE_ADMIN_EMAIL: [email protected]
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: ${SEMAPHORE_ACCESS_KEY_ENCRYPTION}
      SEMAPHORE_COOKIE_HASH: ${SEMAPHORE_COOKIE_HASH}
    volumes:
      - semaphore-config:/etc/semaphore
      - semaphore-data:/tmp/semaphore

Bước 3: Khởi động các dịch vụ và kiểm tra Log

Khởi chạy stack ở chế độ chạy ngầm (detached mode):

docker compose up -d

Theo dõi quá trình khởi tạo container để xác nhận quá trình migrate cơ sở dữ liệu thành công:

docker compose logs -f semaphore

Trong vòng 10 đến 15 giây, bạn sẽ thấy log xác nhận hệ thống đã sẵn sàng:

Đang chạy DB Migrations...
Đã hoàn thành Migrations
Đã tạo Admin
Server đang chạy trên cổng :3000

Bước 4: Đăng nhập lần đầu và thiết lập Project

Mở trình duyệt web và truy cập địa chỉ http://<your-server-ip>:3000. Đăng nhập bằng thông tin khởi tạo mặc định: username admin và mật khẩu InitialAdminPassword123!. Ngay sau đó, hãy chuyển đến mục User Profile ở góc trên bên phải và đổi mật khẩu quản trị sang một chuỗi bảo mật hơn.

Tiếp theo, nhấn New Project và đặt tên là HomeLab Core. Project đóng vai trò như một không gian làm việc độc lập giúp đóng gói thông tin xác thực, repository và playbook.

Bước 5: Cấu hình Key Store, Repository và Inventory

Semaphore tổ chức các tác vụ tự động hóa qua năm thành phần cốt lõi:

1. Key Store (Thông tin xác thực)

Truy cập Key Store > New Key. Đây là nơi lưu private key mà Ansible sử dụng để truy cập các máy chủ đích:

  • Name: homelab-ssh-key
  • Type: SSH Key
  • Username: ansible (user triển khai đã được thiết lập trên các máy đích)
  • Private Key: Dán nội dung private key của bạn (ví dụ từ file ~/.ssh/id_ed25519).

2. Repositories

Truy cập Repositories > New Repository. Semaphore sẽ clone repository chứa playbook của bạn trước khi thực thi:

  • Name: homelab-playbooks
  • URL: https://github.com/your-username/homelab-infra.git (hoặc đường dẫn Gitea nội bộ của bạn)
  • Branch: main
  • Access Key: Chọn None cho repository công khai, hoặc chọn SSH deploy key từ Key Store đối với repository riêng tư.

3. Inventory

Truy cập Inventory > New Inventory:

  • Name: lan-servers
  • Type: Static
  • SSH Key: Chọn homelab-ssh-key
  • Inventory Contents: Nhập định nghĩa danh sách host theo cú pháp INI hoặc YAML tiêu chuẩn:
[proxmox]
192.168.1.10 hostname=pve-01.lan
192.168.1.11 hostname=pve-02.lan

[docker_hosts]
192.168.1.20 hostname=docker-apps.lan
192.168.1.21 hostname=docker-media.lan

[all:vars]
ansible_python_interpreter=/usr/bin/python3

4. Environment

Truy cập Environment > New Environment. Cung cấp các biến bổ sung lúc chạy dưới định dạng JSON, tương đương tham số --extra-vars của Ansible:

{
  "auto_upgrade_packages": true,
  "dns_servers": [
    "192.168.1.1",
    "1.1.1.1"
  ]
}

5. Task Templates

Truy cập Task Templates > New Template:

  • Name: Nightly Package Updates
  • Playbook Filename: playbooks/patch-all.yml (đường dẫn tương đối tính từ thư mục gốc của Git repository)
  • Inventory: lan-servers
  • Repository: homelab-playbooks
  • Environment: Chọn khối environment đã tạo ở bước trên.

Bước 6: Thực thi và lập lịch Playbook

Nhấn Run trên template tác vụ vừa tạo. Màn hình terminal ngay trên trình duyệt sẽ hiển thị stream kết quả thực thi từng dòng, đánh dấu màu trực quan cho các tác vụ ok, changed và failed.

Bạn muốn bảo trì tự động hoàn toàn? Hãy mở cài đặt task template, điền biểu thức cron tiêu chuẩn như 0 3 * * 0 (chạy vào 03:00 UTC mỗi Chủ Nhật), rồi nhấn Save. Semaphore sẽ tự động kích hoạt job theo lịch định sẵn và lưu lại toàn bộ log để bạn tiện tra cứu sau này.

Share:
Tags: