Developer Guide

Hướng Dẫn Triển Khai Hệ Thống Backup & Phục Hồi Dữ Liệu

Tài liệu chi tiết giải pháp sao lưu định kỳ tự động D1 SQLite, R2 Storage, xoay vòng lưu trữ và tích hợp OneDrive

Hướng Dẫn Triển Khai Hệ Thống Backup & Phục Hồi Dữ Liệu (Backup & Disaster Recovery Guide)

Tài liệu kỹ thuật hướng dẫn chi tiết về cơ chế sao lưu tự động (Automated Backup), khôi phục dữ liệu khi gặp sự cố (Disaster Recovery), chính sách dọn dẹp (Retention Policy) và tích hợp đồng bộ Cloud Storage (Microsoft OneDrive) cho dự án OpenStory.

1. Tổng Quan Về Cấu Trúc Dữ Liệu Cần Sao Lưu

Dự án OpenStory lưu trữ toàn bộ trạng thái dữ liệu trong 3 thành phần chính:

Thành PhầnĐịnh Dạng / Vị Trí Lưu TrữMô Tả
Cơ sở dữ liệu D1.wrangler/state/v3/d1/**/*.sqliteLưu trữ toàn bộ bảng dữ liệu người dùng, scenes, kịch bản, nhân vật, billing, v.v.
Media Storage (R2).wrangler/state/v3/r2/Lưu trữ các tài nguyên nhị phân: video render, ảnh phong cách, tệp âm thanh giọng đọc mẫu.
Cấu hình & Bí mật.env.local, .dev.vars, ecosystem.config.cjsChứa các khóa API, cấu hình bí mật kết nối và thông số khởi chạy PM2.

2. Kiến Trúc & Kỹ Thuật Sao Lưu An Toàn (Hot-Backup)

2.1. Cơ Chế Snapshot SQLite Không Khóa (Lock-Free)

Khi ứng dụng đang hoạt động, các thao tác đọc/ghi vào file .sqlite diễn ra liên tục. Nếu chỉ dùng lệnh cp thông thường có thể dẫn đến hiện tượng Database Corruption (hỏng file DB).

Script sao lưu của OpenStory xử lý bằng 2 cơ chế:

  1. Lệnh sqlite3 .backup (Ưu tiên): Sử dụng SQLite Online Backup API trực tiếp để tạo bản snapshot toàn vẹn 100% tại thời điểm sao lưu mà không cần dừng ứng dụng.
  2. Fallback Copy WAL/SHM: Nếu hệ thống chưa cài đặt công cụ CLI sqlite3, script sẽ tự động sao chép đồng thời cả 3 file: .sqlite, .sqlite-wal (Write-Ahead Log) và .sqlite-shm (Shared Memory Index) để đảm bảo tính nhất quán của giao dịch (ACID).

3. Các Công Cụ Đã Triển Khai Trong Mã Nguồn

3.1. Script Tự Động Sao Lưu: scripts/backup.sh

  • Đường dẫn: scripts/backup.sh
  • Chức năng chính:
    • Tự động quét và snapshot toàn bộ database SQLite trong .wrangler/state/v3/d1.
    • Sao chép toàn bộ tệp tin media trong .wrangler/state/v3/r2.
    • Thu thập các file cấu hình và biến môi trường.
    • Nén toàn bộ dữ liệu thành file định dạng openstory_backup_YYYYMMDD_HHMMSS.tar.gz.
    • Lưu trữ mặc định tại: ~/backups/openstory/.
    • Chính sách xoay vòng (Retention Policy): Tự động tìm và xóa các bản backup cũ hơn 7 ngày (có thể tùy chỉnh bằng biến RETENTION_DAYS).
    • Hook đồng bộ Cloud: Hỗ trợ đẩy file sang OneDrive thông qua rclone khi được cấu hình.

3.2. Script Phục Hồi Dữ Liệu: scripts/restore.sh

  • Đường dẫn: scripts/restore.sh
  • Chức năng chính:
    • Nhận đường dẫn tới 1 bản backup .tar.gz.
    • Yêu cầu người quản trị xác nhận an toàn trước khi ghi đè.
    • Tự động tạm dừng tiến trình PM2 openstory để chống xung đột ghi đĩa.
    • Giải nén và khôi phục chính xác cây thư mục D1 SQLite, R2 media và configs.
    • Tự động khởi động lại ứng dụng PM2 sau khi khôi phục thành công.

4. Hướng Dẫn Vận Hành Trên Máy Chủ

4.1. Chạy Thử Sao Lưu Thủ Công

cd ~/openstory
./scripts/backup.sh

Kiểm tra danh sách và dung lượng bản sao lưu:

ls -lh ~/backups/openstory/

4.2. Cấu Hình Tự Động Hóa Qua Linux Cron Job

Thiết lập máy chủ tự động thực hiện sao lưu vào lúc 02:00 sáng mỗi ngày:

  1. Mở cấu hình cron của user:
    crontab -e
  2. Thêm dòng sau vào cuối tệp:
    0 2 * * * /home/seatek/openstory/scripts/backup.sh >> /home/seatek/backups/openstory/backup.log 2>&1
  3. Lưu và thoát. Hệ thống cron sẽ tự động kích hoạt hàng ngày.

5. Quy Trình Khôi Phục Dữ Liệu Khi Gặp Sự Cố (Disaster Recovery)

Nếu xảy ra sự cố (hỏng database, vô tình xóa mất dữ liệu media, hoặc chuyển sang máy chủ mới):

cd ~/openstory

# Chạy script restore và chỉ định file backup muốn khôi phục
./scripts/restore.sh ~/backups/openstory/openstory_backup_20260923_020000.tar.gz

Hệ thống sẽ hỏi xác nhận:

CẢNH BÁO: Phục hồi sẽ ghi đè dữ liệu hiện tại trong /home/seatek/openstory.
Bạn có chắc chắn muốn tiếp tục không? (y/N): y

Sau khi nhập y, toàn bộ dữ liệu sẽ được khôi phục nguyên vẹn và ứng dụng sẽ tự động khởi chạy lại trên PM2.

6. Hướng Dẫn Tích Hợp Đồng Bộ Lên Microsoft OneDrive

Khi sẵn sàng đồng bộ các bản backup lên tài khoản OneDrive cá nhân / doanh nghiệp để lưu trữ an toàn ngoài máy chủ (Offsite Backup):

Bước 1: Cài đặt công cụ Rclone trên máy chủ

sudo apt update && sudo apt install -y rclone

Bước 2: Liên kết tài khoản OneDrive với Rclone

rclone config
  1. Chọn n (New remote).
  2. Đặt tên remote: onedrive.
  3. Chọn loại lưu trữ: tìm và chọn số tương ứng với Microsoft OneDrive (thường là mục onedrive).
  4. Làm theo hướng dẫn trên màn hình để xác thực và cấp quyền truy cập tài khoản Microsoft của bạn.
  5. Kiểm tra kết nối:
    rclone lsd onedrive:

Bước 3: Kích hoạt đồng bộ tự động trong Cron Job

Mở cấu hình crontab -e và cập nhật biến ONEDRIVE_REMOTE:

0 2 * * * ONEDRIVE_REMOTE="onedrive:OpenStoryBackups" /home/seatek/openstory/scripts/backup.sh >> /home/seatek/backups/openstory/backup.log 2>&1

Từ thời điểm này, mỗi khi file sao lưu .tar.gz được tạo thành công trên máy chủ, script sẽ tự động tải bản sao lưu đó lên thư mục OpenStoryBackups trên OneDrive.