revernomad17/arma-modlist-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
45cb023513f629d11bfd7e27cafa4cdee1cb8f1f
arma-modlist-tools/docs/huong-dan-su-dung.md
Tran G. (Revernomad) Khoa e0c2dfb32a docs: update README and VI guide for orphan cleanup and test count 
- Add quick-reference card at top of README (short-form cheat sheet)
- Document clean_orphans.py in ToC, Individual Scripts, folder structure
- Update GUI Tools view table: note Clean Orphans tab
- Fix Running Tests: 96 → 142, remove stale '1 failing test' note, list all 15 groups
- Add clean_orphans.py to folder structure tree
- Add cleaner.py to arma_modlist_tools/ listing
- VI guide: add summary table for Tools tabs, document Clean Orphans tab in full
- VI guide: add 'Mod thừa / Orphan' to glossary
2026-04-08 20:11:41 +07:00

410 lines
17 KiB
Markdown
Raw Blame History

# Hướng dẫn sử dụng Arma Mod Manager
Tài liệu này dành cho người dùng **chưa biết gì** về dự án. Bạn không cần kiến thức lập trình để sử dụng ứng dụng này.
---
## Mục lục
1. [Arma Mod Manager là gì?](#1-arma-mod-manager-là-gì)
2. [Yêu cầu hệ thống](#2-yêu-cầu-hệ-thống)
3. [Khởi động lần đầu — Trình thiết lập](#3-khởi-động-lần-đầu--trình-thiết-lập)
4. [Giao diện chính](#4-giao-diện-chính)
5. [Tổng quan (Dashboard) — Quy trình cơ bản](#5-tổng-quan-dashboard--quy-trình-cơ-bản)
6. [Danh sách Mod](#6-danh-sách-mod)
7. [Công cụ nâng cao](#7-công-cụ-nâng-cao)
- [Check Names](#tab-check-names--kiểm-tra-tên-thư-mục)
- [Update Mods](#tab-update-mods--cập-nhật-mod)
- [Link Mods](#tab-link-mods--quản-lý-liên-kết)
- [Sync / Report Missing](#tab-sync-missing--đồng-bộ-mod-thiếu)
- [Clean Orphans](#tab-clean-orphans--dọn-dẹp-mod-thừa)
8. [Nhật ký (Logs)](#8-nhật-ký-logs)
9. [Cài đặt](#9-cài-đặt)
10. [Đổi sang giao diện tiếng Việt](#10-đổi-sang-giao-diện-tiếng-việt)
11. [Xử lý sự cố thường gặp](#11-xử-lý-sự-cố-thường-gặp)
12. [Bảng thuật ngữ](#12-bảng-thuật-ngữ)
---
## 1. Arma Mod Manager là gì?
**Arma Mod Manager** là công cụ giúp bạn tải về và quản lý các mod cho **Arma 3 Server** từ một máy chủ lưu trữ riêng (Caddy server). Thay vì tải từng mod thủ công, bạn chỉ cần:
1. Xuất danh sách mod từ Arma 3 Launcher dưới dạng tệp HTML (gọi là **preset**)
2. Chọn preset trong ứng dụng
3. Nhấn nút **Chạy toàn bộ quy trình**
Ứng dụng sẽ tự động:
- Đọc danh sách mod từ các preset
- So sánh, tìm mod dùng chung và mod riêng giữa các preset
- Tải mod từ máy chủ về máy tính của bạn
- Tạo liên kết (junction/symlink) để Arma 3 Server nhận ra các mod
---
## 2. Yêu cầu hệ thống
| Yêu cầu | Thông tin |
|---------|-----------|
| Hệ điều hành | Windows 10/11 (64-bit) |
| Python | 3.9 trở lên |
| Arma 3 Server | Đã cài đặt trên máy |
| Kết nối mạng | Cần thiết để tải mod từ máy chủ |
**Cài đặt thư viện cần thiết** (chỉ cần làm một lần):
Mở Command Prompt, điều hướng tới thư mục ứng dụng, chạy:
```
pip install -r requirements.txt
```
---
## 3. Khởi động lần đầu — Trình thiết lập
Khi khởi động ứng dụng lần đầu (chưa có tệp `config.json`), cửa sổ **Thiết lập** sẽ tự động hiện ra gồm 3 bước:
### Bước 1 / 3 — Kết nối máy chủ
![Bước 1](placeholder)
| Trường | Mô tả |
|--------|-------|
| **URL máy chủ** | Địa chỉ đầy đủ của máy chủ Caddy lưu mod, ví dụ: `https://mods.example.com/` |
| **Tên đăng nhập** | Tài khoản được cấp bởi người quản trị máy chủ |
| **Mật khẩu** | Mật khẩu tương ứng |
- Nhấn **Kiểm tra kết nối** để xác nhận thông tin trước khi tiếp tục.
- `✓ Đã kết nối` — thành công, nhấn **Tiếp theo →**
- `✗ HTTP 401` — sai tên đăng nhập hoặc mật khẩu
- `✗ ...` — lỗi mạng hoặc URL sai
### Bước 2 / 3 — Thư mục Arma 3 Server
Nhấn **Duyệt** để chọn thư mục gốc của Arma 3 Server trên máy tính (thư mục chứa `arma3server.exe`).
> Ví dụ: `C:\servers\arma3`
Các thư mục khác (downloads, presets) sẽ tự động được tạo bên cạnh ứng dụng.
### Bước 3 / 3 — Xem lại & Lưu
Kiểm tra thông tin đã nhập rồi nhấn **Lưu & Mở**. Ứng dụng sẽ lưu cấu hình và mở giao diện chính.
> **Mẹo:** Để mở lại trình thiết lập bất cứ lúc nào, vào **Cài đặt → Mở trình thiết lập**.
---
## 4. Giao diện chính
Giao diện gồm thanh điều hướng bên trái và khu vực nội dung bên phải.
```
┌─────────────────┬──────────────────────────────────┐
│ Arma Mod │ │
│ Manager │ Khu vực nội dung │
│─────────────────│ (thay đổi theo mục chọn) │
│ Tổng quan │ │
│ Danh sách Mod │ │
│ Công cụ │ │
│ Nhật ký │ │
│ Cài đặt │ │
└─────────────────┴──────────────────────────────────┘
```
| Mục | Chức năng |
|-----|-----------|
| **Tổng quan** | Chọn preset, xem trạng thái pipeline, chạy quy trình tải mod |
| **Danh sách Mod** | Xem tất cả mod theo nhóm, trạng thái tải/liên kết/máy chủ |
| **Công cụ** | Các tác vụ bảo trì nâng cao |
| **Nhật ký** | Xem toàn bộ output của pipeline và công cụ |
| **Cài đặt** | Cấu hình giao diện, ngôn ngữ, mở lại trình thiết lập |
---
## 5. Tổng quan (Dashboard) — Quy trình cơ bản
Đây là trang chính bạn sẽ dùng thường xuyên nhất.
### 5.1 Thêm tệp preset
**Preset** là tệp HTML xuất từ Arma 3 Launcher chứa danh sách mod bạn đang dùng.
**Cách xuất preset từ Arma 3 Launcher:**
1. Mở Arma 3 Launcher
2. Vào tab **Mods**
3. Nhấn **Preset** → **Export to HTML**
4. Lưu tệp vào máy tính
**Thêm preset vào ứng dụng:**
1. Ở mục **Tệp Preset**, nhấn **+ Thêm tệp Preset**
2. Chọn tệp `.html` vừa xuất
3. Tệp sẽ xuất hiện trong danh sách với ô tick
### 5.2 Chọn preset để xử lý
- **Tick** vào các preset bạn muốn so sánh (cần ít nhất **2 preset**)
- Nhấn **Tất cả** để chọn tất cả, hoặc **Bỏ chọn** để bỏ hết
- Nhãn `Đã chọn X / Y` cho biết số lượng đã chọn:
- Màu xanh: đã chọn đủ (≥ 2)
- Màu vàng: mới chọn 1
- Màu đỏ: chưa chọn
### 5.3 Trạng thái Pipeline
Cột bên phải hiển thị 4 bước của quy trình:
| Bước | Mô tả | Dấu hiệu hoàn thành |
|------|-------|-------------------|
| Phân tích preset | Đọc danh sách mod từ tệp HTML | Có ≥ 2 preset được chọn |
| So sánh preset | Tìm mod chung và riêng | Tệp `comparison.json` tồn tại |
| Tải mod | Tải tệp mod từ máy chủ | Có thư mục mod trong `downloads/` |
| Liên kết với Arma | Tạo junction tới thư mục Arma 3 | Thư mục Arma 3 Server tồn tại |
Biểu tượng `✓` (xanh) = đã xong, `○` (xám) = chưa xong.
### 5.4 Chạy toàn bộ quy trình
1. Đảm bảo đã chọn ít nhất 2 preset
2. Nhấn **▶ Chạy toàn bộ quy trình**
3. Ứng dụng tự động chuyển sang tab **Nhật ký** và hiển thị tiến trình
4. Chờ cho đến khi thấy dòng `✓ Pipeline complete.` (hoặc tiếng Việt: `✓ Hoàn thành`)
> **Lưu ý:** Quá trình này có thể mất vài phút đến hàng giờ tùy số lượng và kích thước mod.
---
## 6. Danh sách Mod
Trang này hiển thị tất cả mod được nhóm theo preset (tab).
### Các tab nhóm
- **shared (X)** — Mod có mặt trong **tất cả** preset đã chọn
- **[tên preset] (X)** — Mod chỉ có trong preset đó
Nhấn vào tên tab để chuyển nhóm.
### Các cột thông tin
| Cột | Ý nghĩa |
|-----|---------|
| **Tên Mod** | Tên mod theo danh sách preset |
| **Đã tải** | `✓` = đã có trong thư mục downloads · `✗` = chưa tải |
| **Đã liên kết** | `✓` = đã tạo junction tới Arma 3 · `✗` = chưa · `—` = chưa tải nên không liên kết được |
| **Trạng thái máy chủ** | Xem bên dưới |
### Trạng thái máy chủ
Nhấn nút **☁ Kiểm tra cập nhật** để kiểm tra từng mod với máy chủ:
| Trạng thái | Ý nghĩa |
|-----------|---------|
| `✓ Đã cập nhật` | Tệp local khớp với máy chủ |
| `⚠ X tệp cũ` | Có X tệp cần cập nhật, nhấn **Cập nhật** ở cuối hàng |
| `Không có trên máy chủ` | Mod này không tồn tại trên máy chủ |
| `—` | Mod chưa được tải về |
| `✗ Lỗi` | Không thể kiểm tra (lỗi mạng) |
### Tìm kiếm mod
Gõ vào ô **Tìm kiếm:** để lọc mod theo tên trong tab đang xem.
---
## 7. Công cụ nâng cao
Trang **Công cụ** có 5 tab phụ cho các tác vụ bảo trì. Mỗi tab đều có nút chạy ở góc phải phía dưới, output hiển thị trong **Nhật ký**.
| Tab | Chức năng tóm tắt |
|-----|-------------------|
| Check Names | Kiểm tra và sửa tên thư mục mod |
| Update Mods | Tải lại tệp mod đã thay đổi trên máy chủ |
| Link Mods | Tạo / xóa junction tới Arma 3 Server |
| Sync / Report Missing | Đồng bộ và báo cáo mod còn thiếu |
| **Clean Orphans** | Xóa thư mục mod thừa từ preset cũ |
### Tab "Check Names" — Kiểm tra tên thư mục
Quét thư mục mod trên máy tính và so sánh với máy chủ. Báo cáo các vấn đề:
| Vấn đề | Ý nghĩa |
|--------|---------|
| `MISMATCH` | Tên thư mục local khác với tên trên máy chủ |
| `NOT_ON_SERVER` | Thư mục local không tìm thấy trên máy chủ |
| `ID_COLLISION` | Tệp `meta.cpp` chứa Steam ID sai |
**Tùy chọn:**
- `--fix`: Tự động đổi tên thư mục sai → Dùng cẩn thận, sẽ di chuyển tệp
- `--fix-ids`: Tự động sửa Steam ID trong `meta.cpp` → Dùng cẩn thận, sẽ ghi đè tệp
### Tab "Update Mods" — Cập nhật mod
Tải lại các tệp mod có kích thước khác với bản trên máy chủ.
- **Nhóm**: Chọn `Tất cả nhóm` hoặc một nhóm cụ thể
- **Thư mục mod**: Nhập tên thư mục cụ thể (ví dụ `@ace`) nếu muốn cập nhật một mod
- **--force**: Tải lại **tất cả** tệp bất kể kích thước — cẩn thận với mod nặng
### Tab "Link Mods" — Quản lý liên kết
Tạo hoặc xóa junction giữa thư mục `downloads/` và thư mục Arma 3.
| Lệnh | Chức năng |
|------|-----------|
| **Status** | Hiển thị trạng thái liên kết hiện tại |
| **Link** | Tạo junction còn thiếu |
| **Unlink** | Xóa junction (tệp mod **KHÔNG** bị xóa) |
> **Lưu ý:** Phải chọn một nhóm cụ thể trước khi chạy Unlink.
### Tab "Sync Missing" — Đồng bộ mod thiếu
Thử tải lại các mod bị thiếu từ lần chạy pipeline trước. Hữu ích khi máy chủ vừa bổ sung mod mới sau khi bạn đã chạy pipeline.
### Tab "Report Missing" — Báo cáo mod thiếu
Kiểm tra mod nào trong `comparison.json` chưa có trên máy chủ và lưu báo cáo vào `missing_report.json`. Dùng để theo dõi mod cần yêu cầu admin bổ sung.
### Tab "Clean Orphans" — Dọn dẹp mod thừa
Khi bạn đổi preset và chạy lại pipeline, các mod của preset cũ vẫn còn trong thư mục `downloads/` nhưng không được dùng nữa — gọi là **mod thừa** (orphan). Tab này giúp tìm và xóa chúng để giải phóng dung lượng ổ đĩa.
**Cách dùng:**
1. Nhấn **Quét mod thừa** — ứng dụng sẽ so sánh thư mục `downloads/` với `comparison.json` hiện tại
2. Danh sách mod thừa hiện ra kèm tên nhóm và dung lượng
3. Dùng **Chọn tất cả** hoặc tick thủ công từng mục
4. Nhấn **Xóa đã chọn** — xuất hiện hộp thoại xác nhận
5. Nhấn **Xác nhận xóa** để thực hiện; danh sách sẽ tự động quét lại sau khi xóa
> **Lưu ý an toàn:** Ứng dụng chỉ xóa thư mục `@ModName` trong `downloads/`, không đụng tới thư mục Arma 3 Server. Junction (liên kết) sẽ bị xóa đúng cách mà không làm mất tệp gốc.
**Yêu cầu:** Cần có `comparison.json` (chạy pipeline ít nhất một lần trước).
---
## 8. Nhật ký (Logs)
Trang này hiển thị toàn bộ output khi chạy pipeline hoặc công cụ.
- **Sao chép**: Copy toàn bộ nội dung nhật ký vào clipboard
- **Xóa**: Xóa sạch nội dung nhật ký
Output được giữ nguyên khi bạn chuyển sang trang khác và quay lại.
**Ký hiệu trong log:**
- `✓` — bước hoàn thành thành công
- `✗` — có lỗi xảy ra
- `SKIP` — bỏ qua (ví dụ preset không được chọn)
---
## 9. Cài đặt
### Cấu hình máy chủ & đường dẫn
Nhấn **Mở trình thiết lập** để thay đổi URL máy chủ, tài khoản, hoặc thư mục Arma 3.
### Giao diện
Chọn chế độ hiển thị: **Dark** (tối), **Light** (sáng), hoặc **System** (theo hệ thống).
### Ngôn ngữ
Xem phần [10. Đổi sang giao diện tiếng Việt](#10-đổi-sang-giao-diện-tiếng-việt).
### Cấu hình hiện tại
Hiển thị các đường dẫn đang dùng: URL máy chủ, thư mục Arma, thư mục downloads, thư mục presets.
---
## 10. Đổi sang giao diện tiếng Việt
1. Nhấn **Cài đặt** ở thanh bên trái
2. Cuộn xuống đến mục **Ngôn ngữ**
3. Chọn **Tiếng Việt** từ danh sách thả xuống
4. Giao diện sẽ chuyển sang tiếng Việt ngay lập tức — không cần khởi động lại
Để chuyển lại tiếng Anh, chọn **English** trong cùng mục đó.
> Lựa chọn ngôn ngữ được lưu vào `config.json` và sẽ được ghi nhớ cho lần khởi động tiếp theo.
---
## 11. Xử lý sự cố thường gặp
### Không kết nối được máy chủ
**Triệu chứng:** Wizard hiển thị `✗ HTTP 401` hoặc `✗ [lỗi kết nối]`
**Kiểm tra:**
- URL có bắt đầu bằng `https://` không?
- URL có dấu `/` ở cuối không? (ví dụ `https://mods.example.com/`)
- Tên đăng nhập và mật khẩu có đúng không? (kiểm tra phân biệt hoa thường)
- Máy tính có kết nối internet không?
- Máy chủ có đang hoạt động không? (hỏi admin)
### Pipeline chạy xong nhưng không tải được mod
**Triệu chứng:** Log hiển thị `missing from server` hoặc `NOT_ON_SERVER`
**Giải thích:** Mod tồn tại trong preset nhưng chưa có trên máy chủ.
**Xử lý:**
- Vào **Công cụ → Report Missing** để tạo báo cáo
- Gửi báo cáo cho admin để bổ sung mod
- Sau khi mod được thêm, vào **Công cụ → Sync Missing** để tải về
### Mod tải về rồi nhưng không liên kết được
**Triệu chứng:** Cột "Đã tải" là `✓` nhưng "Đã liên kết" là `✗`
**Xử lý:**
- Vào **Công cụ → Link Mods**, chọn lệnh **Link**, chọn nhóm tương ứng, nhấn **Tạo liên kết**
- Nếu vẫn lỗi, kiểm tra quyền ghi vào thư mục Arma 3 (có thể cần chạy ứng dụng với quyền Administrator)
### Tên thư mục mod bị sai
**Triệu chứng:** Arma 3 Server không nhận ra mod dù đã tạo junction
**Xử lý:**
- Vào **Công cụ → Check Names**, nhấn **Chạy kiểm tra tên**
- Xem log để tìm dòng `MISMATCH`
- Nếu muốn tự động sửa, tick vào **Tự động sửa tên thư mục** rồi chạy lại
### Ứng dụng không khởi động / lỗi Python
**Triệu chứng:** Màn hình đen nháy tắt ngay
**Xử lý:**
- Mở Command Prompt, chạy `python gui.py` để xem thông báo lỗi
- Đảm bảo đã cài đủ thư viện: `pip install -r requirements.txt`
- Kiểm tra phiên bản Python: `python --version` (cần ≥ 3.9)
---
## 12. Bảng thuật ngữ
| Thuật ngữ | Giải thích |
|-----------|------------|
| **Preset** | Tệp HTML xuất từ Arma 3 Launcher chứa danh sách mod |
| **Pipeline** | Chuỗi 4 bước tự động: phân tích → so sánh → tải → liên kết |
| **Junction / Symlink** | Liên kết thư mục ảo — Arma 3 thấy mod trong thư mục của mình nhưng tệp thực sự nằm ở `downloads/` |
| **Shared mods** | Mod xuất hiện trong tất cả preset đã chọn |
| **Unique mods** | Mod chỉ có trong một preset cụ thể |
| **Caddy server** | Phần mềm máy chủ lưu trữ tệp mod (HTTP file server) |
| **meta.cpp** | Tệp metadata của mỗi mod, chứa `publishedid` (Steam Workshop ID) |
| **Steam ID / publishedid** | Mã định danh mod trên Steam Workshop |
| **comparison.json** | Tệp kết quả so sánh preset, lưu danh sách mod theo nhóm |
| **missing_report.json** | Báo cáo mod có trong preset nhưng chưa có trên máy chủ |
| **downloads/** | Thư mục chứa tệp mod đã tải về |
| **Mod thừa (Orphan)** | Thư mục mod còn trong `downloads/` nhưng không còn trong preset nào đang dùng |
| **config.json** | Tệp cấu hình lưu thông tin máy chủ và đường dẫn |
---
*Phiên bản tài liệu: 2026-04 (cập nhật: thêm Clean Orphans). Nếu có vấn đề, liên hệ người quản trị máy chủ.*
Reference in New Issue View Git Blame Copy Permalink