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

Để cập nhật BookStack trên máy chủ offline, nguyên tắc cốt 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

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

Giai đoạn 1: Chuẩn bị trên Máy Online (Có Internet)

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

Bước 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

Bước 2: Giải nén:

unzip release.zip

Bước 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 phải làm việc này tại đây để tạo ra thư mục vendor.

# Di chuyển vào thư mục vừa giải nén
cd BookStack-release

# Cài đặt Dependencies
composer install --no-dev --prefer-dist

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.

# 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.zip BookStack-release

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 chúng ta 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ì, nên backup database và file config.

Backup Database:

mysqldump -u [username] -p [password] [database_name] > bookstack_backup.sql

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

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

Đổi tên thư mục cũ (dự phòng):
Bash
```
mv /var/www/bookstack /var/www/bookstack_old
```

Giải nén mã nguồn mới (file BookStack-release.zip vừa copy vào):
Bash

# Tạo lại thư mục chứa mã nguồn
mkdir /var/www/bookstack

# Di chuyển vào thư mục mới tạo
cd /var/www/bookstack

# Sao chép file nén đã tạo ở và giải nén
unzip BookStack-release.zip

# Di chuyển toàn bộ các file trong thư mục vừa giải nén ra thư mục mã nguồn
mv BookStack-release/* .

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

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

File cấu hình môi trường:
Bash

cp /var/www/bookstack_old/.env /var/www/bookstack/

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

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

Xóa cache để hệ thống nhận diện cấu hình và view mới.

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

Tóm tắt Checklist kiểm tra

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

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