更新README.md为中文使用指南，专注于如何使用整合包

2026-04-04 21:32:20 +08:00
parent bd8cade79b
commit fa20c2323a
1 changed files with 100 additions and 59 deletions
--- a/README.md
+++ b/README.md
@ -1,84 +1,125 @@
-# Server Modpack Repository
+# 服务器整合包使用指南

-This repository contains the automated modpack synchronization system for the Minecraft server hosted at jianfgit.xyz.
+本仓库存放自动生成的最小客户端整合包，用于连接到 jianfgit.xyz Minecraft 服务器。

-## Overview
+## 如何使用此整合包

-This system automatically:
-1. Monitors the server's mod list (`/tmp/server_mods.txt`)
-2. Creates a minimal client modpack in Modrinth format
-3. Packs the modpack with corresponding TACZ gun packs
-4. Commits and pushes updates to this git repository when changes are detected
-5. Increments version numbers using decimal versioning (0.0.1, 0.0.2, etc.)
-6. Runs every 12 hours via systemd timer
+此整合包采用 Modrinth 格式，支持一键导入所有所需模组和 TACZ 弹药包。

-## Files
+### 前置条件

- `sync_modpack.sh` - Main synchronization script
- `modpack/modrinth.index.json` - Modrinth format modpack index
- `state/mods.json` - Current list of required mods (for change detection)
- `state/gunpacks.json` - Current list of TACZ gun packs (for change detection)
- `VERSION` - Current version number of the modpack
- `README.md` - This file
+1. **Minecraft Java Edition 1.20.1**
+2. **Forge 加载器** (1.20.1 版本)
+3. 支持 Modrinth 整合包格式的启动器：
+   - Prism 启动器 (推荐)
+   - Modrinth 应用程序
+   - PolyMC
+   - ATLauncher
+   - 或任何支持 Modrinth 索引文件的启动器

-## Modrinth Format
+### 一键导入方法（推荐使用 Prism 启动器）

-The modpack follows the [Modrinth index format](https://docs.modrinth.com/docs/getting-started/index-format/) with:
- Format version: 1
- Game: Forge 1.20.1
- Environment: Client required, Server unsupported
- Files: All mods and gunpacks with SHA1 hashes
+1. **下载并安装 Prism 启动器**
+   - 访问 https://prismlauncher.org/download/
+   - 下载适用于您操作系统的版本
+   - 安装并启动应用程序

-## Installation & Setup
+2. **添加整合包**
+   - 在 Prism 启动器中，转到 "实例" 选项卡
+   - 点击 "+" 按钮添加新实例
+   - 选择 "Modrinth" 作为源类型
+   - 在 "Modrinth URL 或索引" 字段中，粘贴以下内容：
+     ```
+     raw.githubusercontent.com/jianf/servermods/main/modpack/modrinth.index.json
+     ```
+     注意：由于这是私有仓库，您可能需要：
+     - 克隆仓库：`git clone ssh://git@jianfgit.xyz:220/jianf/servermods.git`
+     - 在 Prism 启动器中选择 "从文件夹导入" 或 "从 ZIP 导入"
+     - 导航到克隆的仓库的 `modpack/` 目录
+     - 选择 `modrinth.index.json` 文件

-The system is already configured and running on the server. To manually trigger a sync:
+3. **安装整合包**
+   - Prism 启动器将自动下载所有所需模组和弹药包
+   - 它会创建一个名为 "minimal-client-modpack" 的新实例
+   - 选择该实例并点击 "播放"

-```bash
-/tmp/mod_repo/sync_modpack.sh
-```
+### 手动安装方法

-## Versioning
+如果您更喜欢手动安装：

- Version format: Major.Minor.Patch (e.g., 0.0.1)
- Only the patch number is incremented on each change (0.0.1 → 0.0.2 → 0.0.3)
- This ensures that even small mod changes trigger a new version, preventing version conflicts
- Critical: Mod versions must match exactly for clients to connect to the server
+1. **下载整合包索引**
+   - 访问仓库获取 `modrinth.index.json` 文件（位于 `modpack/` 目录）
+   - 由于这是私有仓库，您需要从服务器管理员处获取此文件

-## TACZ Gun Packs
+2. **创建整合包文件夹结构**
+   ```
+   minimal-client-modpack/
+   ├── mods/
+   └── tacz/
+   ```

-TACZ gun packs are stored in the `tacz/` directory and included in the modpack index.
-The system automatically detects new gun packs added to this directory.
+3. **下载所需文件**
+   对于 `modrinth.index.json` 中 `files` 数组中的每个条目：
+   - 如果路径以 `mods/` 开头 → 将文件放入 `mods/` 文件夹
+   - 如果路径以 `tacz/` 开头 → 将文件放入 `tacz/` 文件夹
+   - 您可以从服务器管理员处获取这些文件，或直接请求

-## Monitoring
+4. **安装 Forge**
+   - 从 https://files.minecraftforge.net/ 下载 Forge 1.20.1
+   - 运行安装程序并选择 "安装客户端"

-Check the status of the automated sync:
+5. **启动 Minecraft**
+   - 在您的 Minecraft 启动器中，创建一个新安装
+   - 选择您安装的 Forge 版本
+   - 将游戏目录设置为您的 `minimal-client-modpack` 文件夹
+   - 启动游戏

-```bash
-# Check timer status
-systemctl list-timers --all | grep modpack
+## 重要提示

-# Check service logs
-journalctl -u modpack-sync.service -f
+### 版本匹配
+- 整合包版本 **必须** 完全匹配服务器期望的版本
+- 如果您看到 "服务器握手失败" 或 "无效会话" 错误，这通常表示版本不匹配
+- 请始终确保您拥有最新版本通过定期更新整合包

-# Check current version
-cat /tmp/mod_repo/VERSION
-```
+### 更新整合包
+- 服务器上的整合包每 12 小时自动更新一次
+- 要更新您的客户端：
+  - **Prism 启动器**：选择实例并点击更新箭头
+  - **手动方法**：下载最新的 `modrinth.index.json` 并重新下载哈希值已更改的文件
+  - **Git 方法**：在您克隆的仓库中执行 `git pull` 并在启动器中刷新整合包

-## Manual Mod Addition
+## 故障排除

-To add a new mod to the server:
-1. Place the mod `.jar` file in `/home/minecraft/mods/`
-2. Add the mod name (without version) to `/tmp/server_mods.txt`
-3. The next sync cycle (or manual run) will detect the change and update the modpack
+### "缺失模组" 错误
+1. 验证 `modrinth.index.json` 中列出的所有文件都存在于您的 `mods/` 和 `tacz/` 文件夹中
+2. 检查文件名是否完全匹配（区分大小写）
+3. 验证您下载了正确的版本（高级用户可检查 SHA1 哈希值）

-## Troubleshooting
+### "模组加载错误" 或崩溃
+1. 确保您使用的是 Forge 1.20.1，而不是其他版本
+2. 检查是否有与整合包冲突的其他模组安装在外部
+3. 尝试删除所有模组，然后从零开始使用索引重新安装

-If the sync fails:
-1. Check the service logs: `journalctl -u modpack-sync.service`
-2. Verify git connectivity: `ssh -T -p 220 git@jianfgit.xyz`
-3. Ensure the script is executable: `ls -l /tmp/mod_repo/sync_modpack.sh`
-4. Check disk space: `df -h /tmp`
+### 连接问题
+1. 确认服务器地址正确
+2. 验证您的互联网连接
+3. 检查服务器是否在线且未维护
+4. 确保您的整合包版本与服务器当前版本匹配

-## License
+## 技术细节

-This system is internal to the jianfgit.xyz Minecraft server infrastructure.
+此整合包采用官方 Modrinth 索引格式版本 1：
+- `formatVersion`: 1
+- `game.type`: "forge"
+- `game.version`: "1.20.1"
+- `versionId`: 十进制版本（例如："0.0.3"）
+- `files.array`: 包含对象的列表，每个对象包含：
+  - `path`: 模组包内文件位置（`mods/` 或 `tacz/`）
+  - `hashes.sha1`: 用于文件验证的 SHA1 哈希值
+  - `env.client`: ["required"] - 客户端必需
+  - `env.server`: ["unsupported"] - 服务器端不需要/不允许
+  - `downloads`: [] - 空数组，因为我们使用直接文件分发
+
+TACZ（弹药）包被视为常规模组，但为了组织目的存储在 `tacz/` 子文件夹中。它们对于在此服务器上获得完整游戏体验是必需的。
+
+如需进一步帮助，请联系服务器管理员。