Nhảy đến nội dung chính

Hướng dẫn cập nhật phiên bản BookStack thủ công - Offline

image.png

ỞĐể trường hợp này, chúng ta sẽ cập nhật thủ công theo kiểu "Ghi đè" (Overwrite),BookStack trên máy chủ cóoffline, truynguyên cậptắc Internet.cốt Quy trình sẽlõi là: "Đóng gói toàn bộ mã nguồn VÀ thư viện phụ thuộc (dependencies) từ máy có mạng, sau đó chuyển sang máy nội bộ".

Dưới đây là quy trình chi tiết từng bước:

  • Tải code mới về thiết bị có Internet (Máy Lab/Laptop cá nhân)
  • Giải nén 
  • Cài đặt Dependencies
  • Đóng gói thành một file
  • Sao chép vào máy chủ BookStack nội bộ

Mô hình thực hiện

image.png

  1. Máy Online (Máy trạm):Ghi đèTải lêncode, chạy Composer để lấy thư viện (vendor), đóng gói.
  2. Máy Offline (Server): Backup, bung nén code cũmới,
  3. Chạychép lại dữ liệu cũ, chạy lệnh cập nhật.nhật database.

BướcGiai đoạn 1: SaoChuẩn lưubị filetrên cấuMáy hìnhOnline (CựcCó kỳ quan trọng)Internet)

Chúng ta cần cài đặt sẵn PHP và Composer trên máy này.

1. Tải xuống mã nguồn mới nhất:

#Tải xuống mã nguồn mới nhất của BookStack
wget https://github.com/BookStackApp/BookStack/archive/release.zip

2. Giải nén:

unzip release.zip

3. Di chuyển vào thư mục vừa giải nén và cài đặt Dependencies (Quan trọng nhất):
Vì server không chạy được composer install, chúng ta sắpphải ghilàm đè file, đầu tiên chúng ta cần backup file .env (chứa password database, key mã hóa). Nếu mất fileviệc này làtại mấtđây dữđể liệu.tạo ra thư mục vendor.

# Di chuyển vào thư mục chứa mã nguồn và thực hiện lệnh sao lưu file .env
cp .env .env.backup_2026

Bước 2: Tải và giải nén mã nguồn mới

Chạy lần lượt các lệnh sau để tải bản Release mới nhất từ GitHub:

# Tải file nén về - Yêu cầu kết nối Internet
wget https://github.com/BookStackApp/BookStack/archive/release.zip

# Giải nén (nó sẽ tạo ra một thư mục tên là BookStack-release)
unzip release.zip

image.png

image.png

Bước 3: Ghi đè mã nguồn mới

Bây giờ chúng ta copy toàn bộ nội dung trong thư mục vừa giải nén đè lên thư mục hiện tại.

Lưu ý: Lệnh cp này sẽ ghi đè các file hệ thống nhưng không làm mất thư mục storage hay public/uploads của website, nên dữ liệu ảnh vẫn an toàn.

# Copy đè file mới vào thư mục hiện tại
cp -r BookStack-release/* .

# Dọn dẹp thư mục rác và file zip đã tải về trước đó
rm -rfcd BookStack-release

release.zip

image.png

Bước 4: Chạy các lệnh cập nhật hệ thốngSau khi code đã mới, chúng ta cần cập nhật thư viện và database.

# 1.Cài Cậpđặt nhật thư viện Composer - Yêu cầu máy chủ kết nối InternetDependencies
composer install --no-dev --prefer-dist

image.pngimage.png
Lưu ý: Lệnh này sẽ tải toàn bộ thư viện cần thiết vào thư mục vendor.

# 2.Di chuyển ra khỏi thư mục chứa mã nguồn
cd ..

# Nén thư thư mục chứa mã nguồn
zip -r BookStack-release.ziu BookStack-release

image.png

Copy file này vào USB hoặc copy qua mạng LAN nội bộ vào máy chủ.

Giai đoạn 2: Thao tác trên Máy chủ Nội bộ (Offline)

Giả sử thư mục cài đặt BookStack hiện tại của anh là /var/www/bookstack.

Bước 1: Backup dữ liệu (Bắt buộc)

Trước khi làm bất cứ điều gì, hãy backup database và file config.

  1. Backup Database:
    Bash
    mysqldump -u [username] -p[password] [database_name] > bookstack_backup.sql
  2. Backup File Config và Uploads:
    Copy file .env và các thư mục chứa ảnh/file đính kèm ra một chỗ an toàn (ví dụ /tmp/bookstack_backup).
    Bash
    cp /var/www/bookstack/.env /tmp/bookstack_backup/
cp -r /var/www/bookstack/public/uploads /tmp/bookstack_backup/
cp -r /var/www/bookstack/storage/uploads /tmp/bookstack_backup/

Bước 2: Thay thế mã nguồn

Anh không nên ghi đè trực tiếp mà nên thay thế folder để tránh rác từ bản cũ.

  1. Đổi tên thư mục cũ (để dự phòng):
    Bash
    mv /var/www/bookstack /var/www/bookstack_old
  2. Giải nén mã nguồn mới (file bookstack-update.tar.gz anh vừa copy vào):
    Bash
    mkdir /var/www/bookstack
tar -xzf bookstack-update.tar.gz -C /var/www/bookstack --strip-components=1

    (Lệnh --strip-components=1 giúp bỏ thư mục gốc nếu khi nén anh nén cả folder cha).

Bước 3: Khôi phục cấu hình và dữ liệu cũ

Anh cần chép lại các file quan trọng từ bản cũ sang bản mới.

  1. File cấu hình môi trường:
    Bash
    cp /var/www/bookstack_old/.env /var/www/bookstack/
  2. Dữ liệu người dùng (Ảnh, files):
    Bash
    cp -r /var/www/bookstack_old/public/uploads/* /var/www/bookstack/public/uploads/
cp -r /var/www/bookstack_old/storage/uploads/* /var/www/bookstack/storage/uploads/

Bước 4: Cập nhật quyền (Permissions)

Rất quan trọng, nếu sai quyền webserver (Nginx/Apache) sẽ báo lỗi 500.

# Giả sử webserver chạy user là www-data (Ubuntu/Debian) hoặc apache (CentOS)
chown -R www-data:www-data /var/www/bookstack
chmod -R 755 /var/www/bookstack
chmod -R 775 /var/www/bookstack/storage
chmod -R 775 /var/www/bookstack/bootstrap/cache
chmod -R 775 /var/www/bookstack/public/uploads

Bước 5: Cập nhật Database

(Schema)

Vì -anh Nhậpkhông "Yes"có khimạng, đượcanh hỏikhông thể chạy composer nhưng anh có thể và bắt buộc phải chạy lệnh PHP artisan để cập nhật cấu trúc database cho khớp với code mới.

cd /var/www/bookstack
php artisan migrate --force

Bước 6: Dọn dẹp Cache

image.png

# 3. Xóa Cachecache để hệ thống nhận diện giaocấu diệnhình mớivà view mới.


php artisan cache:clear
php artisan view:clear
php artisan config:clear


image.png


BướcTóm 5:tắt KiểmChecklist kiểm tra lại phiên bản


  1. [ ] Đã copy thư mục #vendor Kiểmtừ máy online sang chưa? (Nếu thiếu cái này web sẽ sập ngay lập tức).
  2. [ ] Đã copy file .env cũ sang chưa? (Nếu thiếu sẽ mất kết nối DB và Key mã hóa).
  3. [ ] Đã chạy php artisan migrate chưa?


Sau khi hoàn tất, anh có thể truy cập vào web để kiểm tra lại phiên bản catmới. versionNếu mọi thứ ổn định, anh có thể xóa thư mục /var/www/bookstack_old
.


image.pngAnh có muốn tôi viết một script bash nhỏ để tự động hóa các bước backup và copy trên server Linux không?
Lên đầu trang