getting-started
约 911 字大约 3 分钟
2026-05-23
本节将带你在 5 分钟内完成 WorldMagic 插件的安装和配置。
前置要求
在开始之前，请确认你的服务器满足以下条件：
| 要求 | 最低版本 |
|---|---|
| 操作系统 | Linux（x86_64 或 aarch64） |
| Minecraft 服务端 | PaperMC 1.21+ |
| Java 版本 | Java 21+ |
| 网络 | 能访问 GitHub 或配置国内镜像源 |
仅支持 Linux
当前版本的 WorldMagic 只支持 Linux 系统。tuic-server 下载的是 linux-musl 静态二进制，在 Windows/macOS 系统上无法运行。
第一步：下载插件
前往 GitHub Releases 下载最新版本的 world-magic.jar。
你也可以通过 GitHub Actions 的手动触发工作流构建最新代码：
# 克隆仓库
git clone https://github.com/anzhuo114514/world-magic.git
cd world-magic
# 构建（需要 JDK 21 和 Maven）
mvn clean package -DskipTests
# 构建产物位于
ls target/world-magic.jar第二步：放置插件
将 world-magic.jar 放入服务器的 plugins/ 目录：
your-minecraft-server/
├── plugins/
│ └── world-magic.jar ← 放这里
├── paper.jar
└── ...第三步：创建配置文件
在 plugins/ 目录（不是 plugins/WorldMagic/，而是和 plugins 目录平级，即服务器根目录）创建 application.properties 文件：
your-minecraft-server/
├── plugins/
│ └── world-magic.jar
├── application.properties ← 创建这里
└── paper.jar配置文件位置
application.properties 放在服务器工作目录（即执行 java -jar paper.jar 时所在的目录），不是 plugins/ 子目录内。
填入以下内容（根据实际情况修改）：
# 服务器域名或公网 IP
domain=your-server.example.com
# Tuic Server 监听端口（UDP），需在防火墙中开放
port=25565
# 认证 UUID（留空则自动生成随机 UUID）
uuid=
# 认证密码（留空则自动生成 8 位随机密码）
password=
# Tuic Server 版本
tuic-version=1.6.5
# 订阅节点名称前缀（用于在客户端识别节点）
remarks-prefix=my-server
# 下载源：foreign（GitHub 直连）或 china（国内镜像）
download-source=foreign关于 UUID 和密码
如果你不填写 uuid 和 password，插件首次启动时会自动随机生成，并加密存储到 config/ 目录。你可以之后通过 /wm status 命令查看实际使用的值。
第四步：开放端口
在服务器的防火墙/安全组中开放你配置的端口（UDP 协议）：
# UFW 示例
ufw allow 25565/udp
# iptables 示例
iptables -A INPUT -p udp --dport 25565 -j ACCEPT
# 阿里云/腾讯云安全组：在控制台添加 UDP 入站规则第五步：启动服务器
启动（或重启）你的 Minecraft 服务器：
java -jar paper.jar插件启动时会在控制台打印以下日志（异步执行，稍后出现）：
[WorldMagic] Loading configuration...
[WorldMagic] Starting tuic-server installation...
[WorldMagic] Downloading tuic-server from: https://github.com/...
[WorldMagic] tuic-server installed successfully.
[WorldMagic] Starting tuic-server...第六步：获取订阅链接
安装完成后，在服务器控制台或游戏内执行：
/wm status你会看到类似输出：
=== WorldMagic Status ===
工作目录: /opt/minecraft/.cache
tuic-server: ✓ 已安装
配置文件: ✓ 已生成
进程状态: ✓ 运行中
---
域名: your-server.example.com
端口: 25565
UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
密码: abcd1234
订阅前缀: my-server
下载源: foreign订阅文件存放于 .cache/<uuid> 文件中，内容为 Base64 编码的 Tuic 节点链接。详见 订阅节点 页面。
验证连接
使用 v2rayN、Clash.Meta 等支持 Tuic v5 的客户端导入节点，测试代理是否正常工作。
自签名证书
由于 Tuic 使用自签名 TLS 证书，客户端需要启用 允许不安全连接（allowInsecure） 选项。订阅链接中已自动包含此参数。