Hướng dẫn này trình bày về việc khắc phục sự cố mod nâng cao cho các máy chủ Project Zomboid được lưu trữ với Legion Hosting. Nếu bạn chưa cài đặt mod, hãy bắt đầu với hướng dẫn cài đặt mod cơ bản trước. Bài viết này giải quyết các vấn đề liên quan đến mod phổ biến nhất được thấy trong các ticket hỗ trợ của Legion Hosting, bao gồm hỏng WorldDictionary, lỗi định dạng mod, xung đột thứ tự tải và sự không khớp phiên bản giữa máy chủ và client.

Trước Khi Bạn Bắt Đầu

• Đăng nhập vào GPanel và chọn máy chủ Project Zomboid của bạn.
• Dừng máy chủ của bạn trước khi thực hiện bất kỳ thay đổi cấu hình hoặc tệp nào.
• Sao lưu thư mục lưu thế giới của bạn (/.cache/saves/multiplayer/) qua SFTP hoặc GPanel trước khi thử bất kỳ cách khắc phục nào. Xem hướng dẫn SFTP nếu bạn không quen với việc chuyển tệp.
• Chuẩn bị sẵn đường dẫn tệp .ini của máy chủ: /.cache/server/<servername>.ini (ví dụ: servertest.ini).

1. Lỗi Định Dạng Mod (B42 so với B41)

Lý do phổ biến nhất khiến mod không tải được là định dạng không chính xác trong dòng Mods= của tệp .ini máy chủ. Build 42 và Build 41 sử dụng cú pháp khác nhau, và việc nhầm lẫn chúng sẽ khiến mod của bạn không tải được mà không báo lỗi.

Định Dạng B42 (Mặc Định Hiện Tại)

Build 42 yêu cầu một tiền tố dấu gạch chéo ngược trước mỗi Mod ID trong dòng Mods=:

Mods=\ModID1;\ModID2;\ModID3;

Định dạng DLMP kết hợp Workshop ID và Mod ID với một dấu phân tách gạch chéo ngược:

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

Dòng WorkshopItems= sử dụng cùng định dạng phân tách bằng dấu chấm phẩy trên cả hai build:

WorkshopItems=2392987841;1550458773;2786383654

Định Dạng B41 (Cũ)

Build 41 sử dụng các Mod ID phân tách bằng dấu chấm phẩy đơn giản với không có dấu gạch chéo ngược:

Mods=ModID1;ModID2;ModID3

Cách Khắc Phục

1. Mở /.cache/server/<servername>.ini trong GPanel File Manager.
2. Tìm dòng Mods= và kiểm tra định dạng so với các ví dụ ở trên.
3. Nếu định dạng sai với phiên bản build của bạn, hãy sửa nó. Sử dụng Legion Hosting Mod Organizer để tự động tạo các dòng được định dạng đúng.
4. Lưu tệp và khởi động máy chủ.

2. Hỏng WorldDictionary

WorldDictionary là một tệp (WorldDictionary.bin) ánh xạ tên vật phẩm với các ID số nội bộ. Khi mod được thêm hoặc xóa, từ điển này có thể bị hỏng, khiến máy chủ bị sập khi khởi động với một WorldDictionaryException.

Triệu Chứng

• Console hoặc debug.log hiển thị lỗi WorldDictionaryException hoặc WorldDictionary.
• Máy chủ sập ngay lập tức trong khi khởi động, cụ thể là trong quá trình tải thế giới.
• Sự cố sập bắt đầu sau khi thêm, xóa hoặc cập nhật mod.

Hiểu Về Rủi Ro

Các Bước Khôi Phục

1. Dừng máy chủ của bạn trong GPanel.
2. Sao lưu toàn bộ thư mục lưu của bạn qua SFTP: tải toàn bộ thư mục /.cache/saves/multiplayer/<YourWorldName>/ về máy của bạn.
3. Đầu tiên, hãy thử đơn giản hoàn tác thay đổi mod đã gây ra lỗi. Nếu bạn vừa thêm một mod, hãy xóa nó khỏi cả Mods= và WorkshopItems= trong tệp .ini. Nếu bạn vừa xóa một mod, hãy thêm nó lại. Khởi động máy chủ và xem sự cố sập có được giải quyết không.
4. Nếu việc hoàn tác thay đổi mod không hiệu quả, hãy kết nối qua SFTP và điều hướng đến /.cache/saves/multiplayer/<YourWorldName>/.
5. Xóa WorldDictionary.bin.
6. Khởi động máy chủ. Project Zomboid sẽ tái tạo từ điển khi khởi động.
7. Tham gia máy chủ và kiểm tra thế giới để tìm các vật phẩm bị hỏng, phương tiện bị thiếu, hoặc kho đồ bị lỗi. Nếu thế giới bị hư hại nghiêm trọng, hãy khôi phục từ bản sao lưu mà bạn đã tạo ở bước 2.

3. Xung Đột Mod Authentic Z

Authentic Z là một trong những bộ sưu tập mod Project Zomboid phổ biến nhất, nhưng nó là nguồn gốc thường xuyên của các ticket hỗ trợ vì nó chứa nhiều mod con xung đột với nhau.

Quy Tắc

Các Lỗi Thường Gặp

• Thêm cả Authentic Z - Current và Authentic Z - Litemode cùng một lúc.
• Thêm các mod con Authentic Z được thiết kế cho chế độ một người chơi cùng với phiên bản nhiều người chơi.
• Không nhận ra rằng các mod con Authentic Z khác nhau dùng chung một Workshop ID nhưng có các Mod ID khác nhau, vì vậy việc tải xuống Workshop thành công nhưng máy chủ tải các tệp mod xung đột.

Cách Khắc Phục

1. Mở /.cache/server/<servername>.ini trong GPanel File Manager.
2. Tìm trong dòng Mods= mọi mục chứa Authentic hoặc AuthenticZ.
3. Chỉ giữ lại một mod con Authentic Z (khuyến nghị: Authentic Z - Current). Xóa tất cả các mục Authentic Z khác khỏi cả dòng Mods= và WorkshopItems=.
4. Lưu tệp và khởi động lại máy chủ.

4. Vấn Đề Phân Biệt Chữ Hoa Chữ Thường Của Linux

Các máy chủ Legion Hosting chạy trên Linux, nơi tên tệp và thư mục phân biệt chữ hoa chữ thường. Một tệp tên MyMod.lua và mymod.lua được coi là hai tệp hoàn toàn khác nhau. Điều này gây ra vấn đề khi các tác giả mod phát triển trên Windows (không phân biệt chữ hoa chữ thường) và mod của họ chứa các tham chiếu tệp không khớp.

Triệu Chứng

• Một mod hoạt động hoàn hảo trong chế độ một người chơi trên máy tính Windows của bạn nhưng lỗi trên máy chủ.
• Console hoặc debug.log hiển thị lỗi FileNotFoundException hoặc can't find file tham chiếu đến một script Lua hoặc texture bên trong một mod.
• Lỗi chỉ đến một tệp thực sự tồn tại trong thư mục mod, nhưng với cách viết hoa khác (ví dụ: mã tham chiếu Items.txt nhưng tệp thực tế được đặt tên là items.txt).

Cách Chẩn Đoán

1. Kiểm tra console hoặc các tệp nhật ký /.cache/Logs/ để tìm đường dẫn tệp chính xác được đề cập trong lỗi.
2. Kết nối qua SFTP và điều hướng đến thư mục của mod tại /steamapps/workshop/content/108600/<WorkshopID>/.
3. So sánh tên tệp trên đĩa với tên tệp được tham chiếu trong thông báo lỗi. Tìm các khác biệt về cách viết hoa.

Cách Khắc Phục

• Nếu bạn có thể đổi tên tệp: Kết nối qua SFTP và đổi tên tệp để khớp với cách viết hoa mà mã của mod mong đợi. Lưu ý rằng cách khắc phục này sẽ bị ghi đè nếu mod cập nhật trên Steam Workshop.
• Nếu vấn đề nằm trong chính mod: Báo cáo lỗi cho tác giả mod trên trang Steam Workshop. Đề cập rằng tham chiếu tệp có sự không khớp về chữ hoa chữ thường và rằng nó lỗi trên các máy chủ Linux. Nhiều tác giả mod không biết về việc phân biệt chữ hoa chữ thường của Linux.
• Như một giải pháp thay thế tạm thời: Kiểm tra các bình luận trên trang Workshop của mod — những người vận hành máy chủ Linux khác có thể đã đăng một cách khắc phục hoặc một bản fork tương thích của mod.

5. Vấn Đề Thứ Tự Tải Mod

Project Zomboid tải mod theo thứ tự chúng xuất hiện trong dòng Mods=. Một số mod phụ thuộc vào việc các mod khác được tải trước. Nếu một mod phụ thuộc được tải sau mod yêu cầu nó, mod phụ thuộc có thể lỗi mà không báo hoặc gây ra lỗi.

Triệu Chứng

• Các tính năng mod hoạt động một phần — một số vật phẩm hoặc hệ thống từ một mod hiện diện nhưng những cái khác bị thiếu.
• Console hiển thị lỗi NullPointerException hoặc attempt to index a nil value tham chiếu đến các script Lua của một mod.
• Lỗi chỉ xuất hiện khi một tổ hợp mod cụ thể được cài đặt, nhưng mỗi mod hoạt động tốt riêng lẻ.

Cách Khắc Phục

1. Kiểm tra trang Steam Workshop của mỗi mod để tìm mục "Required Mods" hoặc "Load Order". Nhiều tác giả mod chỉ định mod nào phải được tải trước mod của họ.
2. Mở /.cache/server/<servername>.ini và tìm dòng Mods=.
3. Sắp xếp lại các mục sao cho các mod phụ thuộc xuất hiện trước các mod yêu cầu chúng. Ví dụ, nếu Mod B yêu cầu Mod A, dòng nên đọc là Mods=\ModA;\ModB; (định dạng B42).
4. Các mod framework và thư viện (chẳng hạn như ModFramework, TsarLib, hoặc Shark's Mod Utils) phải luôn được liệt kê đầu tiên trong dòng Mods=.
5. Lưu tệp và khởi động lại máy chủ.

6. Máy Chủ Sập Sau Khi Thêm Mod

Nếu máy chủ của bạn đang chạy tốt và sập sau khi thêm một hoặc nhiều mod, mod mới có khả năng là nguyên nhân. Phần này hướng dẫn cách cô lập mod gây vấn đề.

Cô Lập Từng Bước

1. Dừng máy chủ trong GPanel.
2. Mở /.cache/server/<servername>.ini trong File Manager.
3. Ghi chú tất cả các mod bạn vừa thêm. Xóa tất cả chúng khỏi cả dòng Mods= và WorkshopItems=.
4. Khởi động máy chủ. Nếu nó khởi động thành công, vấn đề nằm ở một trong các mod bạn đã xóa.
5. Thêm các mod lại từng cái một, khởi động lại máy chủ sau mỗi lần thêm. Khi sự cố sập quay lại, mod cuối cùng bạn thêm là nguyên nhân.
6. Sau khi xác định, hãy kiểm tra trang Workshop của mod để tìm:
   • Một ghi chú về khả năng tương thích B42 — nhiều mod B41 chưa được cập nhật cho B42.
   • Các xung đột đã biết với các mod khác bạn đang chạy.
   • Các mod phụ thuộc bắt buộc mà bạn có thể chưa cài đặt.

Đọc Nhật Ký Sập

Trước khi thực hiện quá trình cô lập, hãy kiểm tra nhật ký sập — nó thường chỉ thẳng đến mod gây vấn đề:

1. Trong GPanel, mở tab Console và cuộn đến cuối đầu ra.
2. Tìm các dòng STACK TRACE, Exception, hoặc ERROR.
3. Các dòng ngay phía trên stack trace thường tham chiếu đến tên tệp mod hoặc Mod ID — điều này cho bạn biết mod nào đã kích hoạt sự cố sập.
4. Để biết thêm chi tiết, hãy mở tệp nhật ký đầy đủ qua SFTP tại /.cache/Logs/ và kiểm tra tệp DebugLog-server.txt hoặc debug.log gần đây nhất.

7. Sự Không Khớp Phiên Bản Mod (Máy Chủ so với Client)

Project Zomboid yêu cầu máy chủ và tất cả các client kết nối phải có cùng phiên bản của mỗi mod. Nếu một mod cập nhật trên Steam Workshop và máy chủ tải phiên bản mới nhưng một người chơi vẫn còn lưu phiên bản cũ trong bộ nhớ đệm (hoặc ngược lại), sẽ xảy ra lỗi kết nối hoặc sập.

Triệu Chứng

• Người chơi nhận được lỗi "Mod mismatch" hoặc "Version mismatch" khi cố gắng kết nối.
• Một số người chơi có thể kết nối nhưng những người khác thì không — những người không thể kết nối có một phiên bản mod khác được lưu trong bộ nhớ đệm cục bộ.
• Máy chủ đang hoạt động tốt, sau đó một mod cập nhật trên Steam Workshop và đột nhiên một số người chơi không thể tham gia.
• Người chơi thấy texture, vật phẩm bị thiếu, hoặc các thành phần UI bị lỗi từ các mod được cập nhật gần đây.

Khắc Phục Cho Người Vận Hành Máy Chủ

1. Dừng máy chủ trong GPanel.
2. Khởi động lại máy chủ. Khi khởi động, máy chủ tải lại các phiên bản mới nhất của tất cả các mod Workshop. Điều này đảm bảo máy chủ đang chạy phiên bản mới nhất.
3. Nếu máy chủ vẫn còn lưu một phiên bản cũ trong bộ nhớ đệm, hãy kết nối qua SFTP và xóa thư mục bộ nhớ đệm Workshop của mod cụ thể tại /steamapps/workshop/content/108600/<WorkshopID>/. Khởi động lại máy chủ để buộc tải xuống sạch.

Khắc Phục Cho Người Chơi

Người chơi không thể kết nối do sự không khớp phiên bản mod nên:

1. Mở Steam và điều hướng đến Library → Project Zomboid.
2. Nhấp chuột phải vào Project Zomboid, chọn Properties → Local Files → Verify Integrity of Game Files.
3. Đồng thời điều hướng đến thư mục Steam Workshop của Project Zomboid trên máy của họ và xóa các tệp mod được lưu trong bộ nhớ đệm để buộc tải xuống lại.
4. Khởi chạy trò chơi và kết nối lại với máy chủ.

8. Xóa Bộ Nhớ Đệm Steam Workshop

Nếu nhiều vấn đề về mod vẫn tiếp diễn và bạn nghi ngờ bộ nhớ đệm tải xuống Workshop bị hỏng, bạn có thể buộc tải lại hoàn toàn tất cả các mod Workshop.

1. Dừng máy chủ trong GPanel.
2. Kết nối qua SFTP và điều hướng đến /steamapps/workshop/.
3. Xóa toàn bộ thư mục workshop/ (hoặc nội dung của nó).
4. Khởi động máy chủ. Steam sẽ tải lại tất cả các mục Workshop từ đầu.
5. Theo dõi GPanel Console để xác nhận tất cả các mod hoàn tất tải xuống trước khi máy chủ bắt đầu tải thế giới.

Tham Khảo Chẩn Đoán Nhanh

Vẫn Gặp Vấn Đề Về Mod?