安装问题

Q：插件启动后控制台没有任何 WorldMagic 相关日志

可能原因：

• 插件 JAR 文件损坏或版本不匹配
• Java 版本低于 21

解决方案：

1. 确认服务器 Java 版本：java -version，需要 Java 21+
2. 重新下载最新的 world-magic.jar
3. 检查服务器日志是否有报错（[ERROR] 或异常堆栈）

---

Q：下载 tuic-server 时超时或失败

可能原因：国内服务器访问 GitHub 受限

解决方案：

1. 在游戏内执行 /wm source china 切换到国内镜像
2. 重启服务器

如果仍然失败，可以手动下载并放置到 .cache/ 目录。

---

Q：提示 "config/ 目录中未找到有效的配置文件"

可能原因：

• 首次安装但未创建 application.properties
• config/ 目录中的加密文件被修改导致 MD5 校验失败

解决方案：

1. 在服务器根目录创建 application.properties 并填入配置
2. 如果 config/ 目录存在，删除其中的所有文件
3. 重启服务器

---

Q：application.properties 不见了

这是正常现象。插件首次读取明文配置后，会将其加密存储到 config/ 目录，然后删除原始明文文件。加密后的配置依然完整，只是以密文形式保存。

如需修改配置，重新创建 application.properties 并删除 config/ 目录即可。

---

运行问题

Q：/wm status 显示进程未运行

排查步骤：

1. 检查 .cache/ 目录是否存在 tuic-server 文件：

   ls -la /path/to/minecraft/.cache/

2. 手动测试是否能执行：

   /path/to/minecraft/.cache/tuic-server --version

3. 检查端口是否被占用：

   ss -tulnp | grep <port>

4. 手动运行启动脚本查看错误输出：

   cd /path/to/minecraft/.cache/
   ./tuic-server -c tuic-config.json

5. 检查控制台日志是否有重启失败的错误信息

---

Q：代理连接失败（客户端无法连接）

排查清单：

• 防火墙是否已开放对应端口的 UDP 流量
• 云服务器安全组是否已添加 UDP 入站规则
• 客户端配置的服务器地址和端口是否与 application.properties 一致
• 客户端是否启用了 "允许不安全连接" / skip-cert-verify: true（必须启用，因为使用自签名证书）
• 本地网络是否封锁了 UDP 流量（部分企业/校园网络）

---

Q：tuic-server 频繁崩溃重启

可能原因：

• 配置文件 tuic-config.json 格式有误
• 端口已被其他进程占用
• 服务器内存不足

解决方案：

1. 检查 .cache/tuic-config.json 内容是否正确
2. 确认端口未被占用：ss -tulnp | grep <port>
3. 删除 .cache/ 目录中的所有文件，重启服务器让插件重新生成

---

Q：/wm restart 命令没有效果

这是已知的限制。当前版本的 restart 命令是占位符实现，尚未完整开发。

临时解决方案：

• 重启整个 Minecraft 服务器
• 或手动终止 tuic-server 进程（插件会自动检测并重启）：

  pkill -f tuic-server

---

配置问题

Q：如何查看当前实际使用的 UUID 和密码？

执行 /wm status 命令，输出中包含当前配置的所有值（包括随机生成的 UUID 和密码）。

---

Q：如何更换 UUID 或密码？

1. 在服务器根目录重新创建 application.properties，填入新的 uuid 和 password
2. 删除 config/ 目录（或其中的所有文件）
3. 重启服务器
4. 更新客户端代理配置

---

Q：想使用不同于 Minecraft 端口的 Tuic 端口

在 application.properties 中设置 port 为你想要的值：

port=8443

然后确保在服务器防火墙中开放该 UDP 端口。

---

Q：tuic-version 填什么版本比较好？

推荐使用项目默认的 1.6.5，这是经过验证的稳定版本。

如需使用其他版本，请先确认 GitHub Releases 中确实存在对应版本的 linux-musl 二进制文件。

---

平台兼容性

Q：能在 Windows 服务器上使用吗？

当前版本不完全支持 Windows 服务器。下载的 tuic-server 是 Linux 静态二进制（linux-musl），无法在 Windows 上运行。

WorldMagic 主要面向 Linux 环境设计。

---

Q：支持 ARM 服务器吗？

支持。插件会自动检测 CPU 架构：

• 检测到 ARM/aarch64 架构时，下载 tuic-server-aarch64-linux-musl
• 其他架构默认下载 tuic-server-x86_64-linux-musl

---

Q：支持 Paper 以外的服务端（Spigot、Bukkit）吗？

plugin.yml 中声明的 api-version: '1.21' 以及代码中使用的 API 均为标准 Bukkit/Paper API，理论上也可以在 Spigot 等服务端上运行。但插件目前仅在 PaperMC 上经过测试，其他服务端的兼容性不作保证。

---

安全相关

Q：RSA 密钥公开是否存在安全风险？

是的，这是项目中的一个已知安全问题。由于 RSA 公钥和私钥均硬编码在公开的源码 (AppConst.java) 中，任何人都能用相同的私钥解密其他服务器上插件存储的 config/ 配置文件。

这意味着：如果攻击者能访问你服务器上的 config/ 目录，他们可以解密获取你的 UUID 和密码。

缓解措施：

• 限制服务器文件系统的访问权限
• 不要将 config/ 目录暴露到公网
• 考虑在 Tuic 端额外设置 IP 白名单