Posted inHomeLab

Đừng đoán mò cấu hình nữa: Xây dựng Wiki HomeLab chuyên nghiệp với BookStack

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

Thực tế phũ phàng lúc 2 giờ sáng

Đã khuya rồi. Node Proxmox chính của tôi vừa gặp lỗi kernel panic, và DNS nội bộ thì sập. Tôi đang dán mắt vào terminal, cố nhớ xem mình đã gán recovery bridge cho VLAN 10 hay 20. Tôi lục lọi trong file notes.txt lộn xộn trên laptop vốn đã không được cập nhật suốt 14 tháng qua, thầm trách bản thân vì đã quá lười biếng trong việc viết tài liệu.

Nếu bạn đã vận hành HomeLab hơn một tuần, bạn sẽ hiểu nỗi ức chế này. Chúng ta xây dựng các hệ thống phức tạp nhưng lại coi việc viết tài liệu là chuyện phụ. Sau nhiều năm làm hỏng đủ thứ, tôi nhận ra rằng một Wiki tập trung, có thể tìm kiếm được không phải là thứ xa xỉ—nó là xương sống của một lab ổn định. Không có nó, bạn không phải đang chạy HomeLab; bạn đang quản lý một “lâu đài cát” sớm muộn gì cũng sụp đổ.

Chọn chiến lược viết tài liệu

Tôi đã thử gần như mọi phương pháp để theo dõi cấu hình lab của mình. Dưới đây là hiệu quả thực tế của các chiến lược phổ biến nhất khi xảy ra sự cố.

Cách tiếp cận file phẳng (Markdown & Git)

Nhiều kỹ sư thích lưu trữ các file Markdown trong một kho lưu trữ Git. Nó có tính di động cao và được quản lý phiên bản, điều này rất tuyệt cho code. Tuy nhiên, nó thất bại khi bạn cần chia sẻ nhanh một hướng dẫn cho người thân—những người không biết dùng VS Code. Việc tìm kiếm qua hơn 50 thư mục lồng nhau trong terminal khi mạng đang ngoại tuyến thực sự là một cơn ác mộng.

Cách tiếp cận đám mây (Notion/Confluence)

Notion có giao diện đẹp, và Confluence là tiêu chuẩn của doanh nghiệp. Nhưng có một nhược điểm lớn: quyền riêng tư và khả năng truy cập. Tôi không muốn sơ đồ IP nội bộ hay SSH key của mình nằm trên máy chủ của bên thứ ba. Quan trọng hơn, nếu internet bị ngắt, tài liệu của bạn cũng biến mất đúng lúc bạn cần nó nhất để sửa gateway.

Giải pháp BookStack

BookStack tạo ra sự cân bằng hợp lý. Nó sử dụng mô hình thư viện đơn giản: Kệ sách (Shelves) > Sách (Books) > Chương (Chapters) > Trang (Pages). Nó là phần mềm self-hosted, nhẹ và có bộ máy tìm kiếm thực sự hiệu quả. BookStack hỗ trợ cả Markdown và trình soạn thảo WYSIWYG, giúp việc sử dụng trở nên dễ dàng ngay cả khi bạn không ở trong trạng thái của một “lập trình viên”.

Tại sao BookStack lại hiệu quả

Ưu điểm

  • Cấu trúc phân cấp logic: Hệ thống Kệ/Sách giúp tránh tình trạng “thư mục vô tận”. Tôi dùng kệ “Networking” cho cấu hình switch và kệ “Servers” cho thông số phần cứng.
  • Sao lưu dễ dàng: Toàn bộ hệ thống chỉ gồm một cơ sở dữ liệu MySQL và một thư mục hình ảnh. Bạn có thể tự động hóa quy trình backup chỉ với một script năm dòng.
  • Tích hợp sẵn Draw.io: Bạn có thể nhúng sơ đồ mạng trực tiếp vào trang tài liệu. Điều này cực kỳ hữu ích để ghi chép cách đi dây tủ rack hoặc các mạng Docker phức tạp.
  • Phân quyền chi tiết: Bạn có thể cấp quyền “Chỉ đọc” cho người thân vào xem hướng dẫn Plex, trong khi vẫn khóa chặt cuốn sách chứa mật khẩu root cho riêng tài khoản admin.

Đánh đổi

  • Cấu trúc cố định: BookStack buộc bạn tuân theo hệ thống phân cấp của nó. Nếu bạn thích cấu trúc phẳng hoàn toàn hoặc dạng mạng lưới (Zettelkasten), bạn sẽ thấy nó hơi gò bó.
  • Phụ thuộc vào cơ sở dữ liệu: Không giống như các file phẳng, nếu cơ sở dữ liệu bị hỏng và bạn không có bản sao lưu, tài liệu của bạn sẽ mất sạch.

Cách triển khai khuyến nghị

Tôi luôn khuyến nghị chạy BookStack bên trong Docker. Cách này giúp tách biệt các phụ thuộc PHP khỏi hệ điều hành máy chủ và giúp việc di chuyển phần cứng trở nên đơn giản. Chúng ta sẽ sử dụng file docker-compose với hai container: ứng dụng BookStack và cơ sở dữ liệu MariaDB.

Bước 1: Tạo cấu trúc thư mục

Đầu tiên, hãy thiết lập một không gian riêng cho dữ liệu Wiki. Tôi thường lưu trữ dữ liệu của mình tại ~/homelab/bookstack.

mkdir -p ~/homelab/bookstack/config
mkdir -p ~/homelab/bookstack/db_data
cd ~/homelab/bookstack

Bước 2: Cấu hình Docker Compose

Tạo file docker-compose.yml. Chúng ta sẽ sử dụng image từ linuxserver.io vì họ cung cấp các bản cập nhật thường xuyên và tài liệu hướng dẫn tuyệt vời cho người dùng HomeLab.

version: "3.8" 
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Ho_Chi_Minh
      - APP_URL=http://192.168.1.50:6875 # Sử dụng IP tĩnh của máy chủ
      - DB_HOST=bookstack_db
      - DB_USER=bookstack
      - DB_PASS=DùngMậtKhẩuMạnhTạiĐây
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Ho_Chi_Minh
      - MYSQL_ROOT_PASSWORD=MậtKhẩuRootCủaBạn
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=DùngMậtKhẩuMạnhTạiĐây
    volumes:
      - ./db_data:/config
    restart: unless-stopped

Lưu ý kỹ thuật: Đảm bảo APP_URL khớp chính xác với IP hoặc tên miền DNS bạn sẽ sử dụng. Nếu sai, BookStack sẽ không tải được CSS và JavaScript, dẫn đến một trang web bị lỗi chỉ toàn chữ.

Bước 3: Khởi chạy

Khởi chạy stack bằng một câu lệnh duy nhất:

docker compose up -d

Đợi khoảng 30 giây để cơ sở dữ liệu khởi tạo. Bạn có thể theo dõi tiến trình bằng cách chạy lệnh docker logs -f bookstack.

Bước 4: Bảo mật ban đầu

Truy cập giao diện tại http://your-server-ip:6875. Đăng nhập mặc định là [email protected] với mật khẩu password. Hãy thay đổi chúng ngay lập tức. Trong một HomeLab, Wiki chứa đựng toàn bộ “bản thiết kế” cho đời sống số của bạn. Hãy bảo mật nó cẩn thận như cách bạn bảo mật trình quản lý mật khẩu.

Tổ chức tài liệu để ứng phó sự cố

Đừng chỉ đổ đống văn bản thô vào các trang. Hãy sử dụng cấu trúc của BookStack để tạo ra một bản đồ chức năng. Đây là thiết lập 3 tầng phù hợp với hầu hết các lab:

  1. Kệ: Cơ sở hạ tầng (Infrastructure)
    • Sách: Mạng (VLAN ID, sơ đồ switch 24 cổng, quy tắc Firewall)
    • Sách: Ảo hóa (IP của các Node, các điểm gắn ổ cứng lưu trữ dùng chung)
  2. Kệ: Dịch vụ (Services)
    • Sách: Truyền thông (Thư viện Plex, các đoạn mã Docker compose)
    • Sách: Tự động hóa (Các thực thể Home Assistant, sơ đồ kênh Zigbee)
  3. Kệ: Bảo trì (Maintenance)
    • Sách: Khôi phục sau thảm họa (Các bước “Bước 1, Bước 2” cụ thể để khôi phục từ bản sao lưu)

Bước cuối cùng: Sao lưu tự động

Một Wiki mà không có bản sao lưu là một rủi ro lớn. Vì chúng ta đang dùng Docker, việc trích xuất cơ sở dữ liệu và nén thư mục cấu hình rất dễ dàng. Tôi chạy script này qua một cron job vào mỗi 3 giờ sáng hàng ngày:

#!/bin/bash
# Script sao lưu BookStack
BACKUP_DIR="/mnt/nas/backups/bookstack"
DATE=$(date +%Y-%m-%d)

# Xuất cơ sở dữ liệu
docker exec bookstack_db /usr/bin/mariadb-dump -u bookstack -pDùngMậtKhẩuMạnhTạiĐây bookstackapp > $BACKUP_DIR/db_$DATE.sql

# Nén cấu hình và hình ảnh
tar -czf $BACKUP_DIR/files_$DATE.tar.gz ~/homelab/bookstack/config

# Xóa các bản sao lưu cũ hơn 14 ngày
find $BACKUP_DIR -type f -mtime +14 -delete

Việc thiết lập này chỉ mất 20 phút nhưng sẽ giúp bạn tiết kiệm hàng giờ đồng hồ khắc phục hậu quả. Lần tới khi lab của bạn bị lỗi, bạn sẽ không phải đoán mò nữa. Bạn sẽ mở BookStack, tìm hướng dẫn đã viết từ sáu tháng trước và xử lý vấn đề trong vài phút. Đó là cách bạn nâng tầm từ một người chơi hệ phong trào thành một quản trị viên chuyên nghiệp.

Share:
Tags: