Hướng Dẫn Sửa Lỗi FASTPANEL Không Khởi Động Sau Khi Tự Update

Đây là hướng dẫn sửa lỗi cho ubuntu 20.04, nếu bạn sử dụng phiên bản khác, vui lòng sửa file ubu20.yml thành phiên bản của bạn, ví dụ như ubuntu 22.04 thì file sẽ là ubu22.yml

1. Hiện tượng lỗi

Khi kiểm tra log:

journalctl -u fastpanel2 -n 50 --no-pager

Xuất hiện lỗi:

ERROR: Unable to load './config/modules' config:
Cannot parse 'config/modules/ubu20.yml' file:
yaml: unmarshal errors:

line 723: cannot unmarshal !!str `24.6.0` into int
line 729: cannot unmarshal !!str `23.11.1` into int
...

Service liên tục restart:

fastpanel2.service: Scheduled restart job, restart counter is at 129316

FASTPANEL không thể khởi động.

2. Nguyên nhân

FASTPANEL tự động cập nhật lên phiên bản mới.

Trong file:

/usr/local/fastpanel2/config/modules/ubu20.yml

Các version NodeJS được khai báo dạng chuỗi, ví dụ:

24.6.0
23.11.1
22.18.0

Trong khi phiên bản FASTPANEL mới yêu cầu kiểu dữ liệu integer (major version), ví dụ:

24
23
22

Do sai kiểu dữ liệu nên YAML không parse được, dẫn tới service không khởi động.

Ngoài ra còn thiếu cột site_id trong database SQLite sau update.

3. Cách Fix Chi Tiết

Bước 1: Backup file cấu hình

cp /usr/local/fastpanel2/config/modules/ubu20.yml \
   /usr/local/fastpanel2/config/modules/ubu20.yml.bak

Bước 2: Chuyển version NodeJS từ x.y.z về x

Sửa các dòng dạng:

nodejs 24.6.0:

Thành:

nodejs 24:

Chạy lệnh:

sed -i -E 's/nodejs ([0-9]+)\.[0-9]+\.[0-9]+:/nodejs :/g' \
/usr/local/fastpanel2/config/modules/ubu20.yml

Bước 3: Sửa format version trong YAML

Chuyển:

version: '24.6.0'

Thành:

version: 24

Chạy:

sed -i -E "s/version: '([0-9]+)\.[0-9]+\.[0-9]+'/version: /g" \
/usr/local/fastpanel2/config/modules/ubu20.yml

Bước 4: Restart FASTPANEL

systemctl restart fastpanel2

Nếu vẫn chưa lên, tiếp tục bước sửa database.

Bước 5: Backup database FASTPANEL

cp /usr/local/fastpanel2/app/db/fastpanel2.db \
   /usr/local/fastpanel2/app/db/fastpanel2.db.backup

Bước 6: Thêm cột thiếu trong SQLite

Mở database:

sqlite3 /usr/local/fastpanel2/app/db/fastpanel2.db

Thêm cột:

ALTER TABLE site_upstream_target ADD COLUMN site_id INTEGER;

Thoát:

.exit

Bước 7: Restart lại service

systemctl restart fastpanel2

Kiểm tra trạng thái:

systemctl status fastpanel2 --no-pager

Nếu hiển thị:

Active: active (running)

Là đã fix thành công.

4. Kết quả sau khi sửa

Service chạy bình thường:

Active: active (running)
Main PID: xxxx (fastpanel)

FASTPANEL truy cập lại được bình thường.

5. Khuyến nghị

• Tắt auto update FASTPANEL nếu có thể.
• Hoặc kiểm soát update các module trong thư mục:

  /usr/local/fastpanel2/config/modules/

• Nên backup định kỳ:
  • Thư mục /usr/local/fastpanel2
  • Database /usr/local/fastpanel2/app/db/fastpanel2.db