本文涵盖专用 Hytale 服务器的设置、配置和操作。
目标受众：服务器管理员和托管专用服务器的玩家。
[HR][/HR]

目录

[TABLE]
[TR]
[TH][LEFT]章节[/LEFT][/TH]
[TH][LEFT]主题[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]服务器设置[/LEFT][/TD]
[TD][LEFT]Java 安装、服务器文件、系统要求[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]运行 Hytale 服务器[/LEFT][/TD]
[TD][LEFT]启动命令、认证、端口、防火墙、文件结构[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]技巧与窍门[/LEFT][/TD]
[TD][LEFT]模组、AOT 缓存、哨兵、推荐插件、视距[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]多服务器架构[/LEFT][/TD]
[TD][LEFT]玩家推荐，重定向，备用方案，建筑代理[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]其他细节[/LEFT][/TD]
[TD][LEFT]JVM 参数，协议更新，配置文件[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]未来新增内容[/LEFT][/TD]
[TD][LEFT]服务器发现、群组、集成支付、SRV 记录、API 端点[/LEFT][/TD]
[/TR]
[/TABLE]

[HR][/HR]

服务器设置

Hytale 服务器可以在任何至少拥有 4GB 内存且安装了 Java 25 的设备上运行。系统支持 x64 和 arm64 架构。
我们建议在服务器运行时监控 RAM 和 CPU 使用情况，以了解针对您的玩家数量和游戏风格典型的资源消耗——资源使用情况严重依赖于玩家的行为。

总体指南：

CPU：高玩家或实体数量（NPC、怪物）
RAM：大型的已加载世界区域（高视距，玩家独立探索）

注意：如果没有专门的工具，很难确定 Java 进程实际需要多少分配的 RAM。尝试使用不同的值来设置 Java 的 -Xmx 参数。内存压力的一个典型症状是由于垃圾回收导致的 CPU 使用率增加。

安装 Java 25

安装 Java 25。我们推荐 Adoptium。

确认安装

通过运行以下命令来验证安装：

java --version

预期输出：

openjdk 25.0.1 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode, sharing)

服务器文件

获取服务器文件有两种方式：

从你的启动器安装中手动复制
使用 Hytale 下载器 CLI

从启动器手动复制

最适合：快速测试。持续更新很烦人。
在你的启动器安装文件夹中找到文件：

Windows: %appdata%\Hytale\install\release\package\game\latest
Linux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest
MacOS: ~/Application Support/Hytale/install/release/package/game/latest

列出目录内容：

ls

《Hytale 服务器手册 – Hypixel Studios》
复制
Directory: C:\Users\...\Hytale\install\release\package\game\latest

Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 12/25/2025 9:25 PM Client
d----- 12/25/2025 9:25 PM Server
-a---- 12/25/2025 9:04 PM 3298097359 Assets.zip

将 Server 文件夹和 Assets.zip 复制到你的目标服务器文件夹。

Hytale 下载器 CLI

最适合：生产服务器。易于更新。
一个使用 OAuth2 认证下载 Hytale 服务器和资源文件的命令行工具。参见存档中的 QUICKSTART.md。
下载：hytale-downloader.zip (Linux & Windows)

[TABLE]
[TR]
[TH][LEFT]命令[/LEFT][/TH]
[TH][LEFT]描述[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader[/LEFT][/TD]
[TD][LEFT]下载最新版本[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader -print-version[/LEFT][/TD]
[TD][LEFT]显示游戏版本而不下载[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader -version[/LEFT][/TD]
[TD][LEFT]显示 hytale-downloader 版本[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader -check-update[/LEFT][/TD]
[TD][LEFT]检查 hytale-downloader 更新[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader -download-path game.zip[/LEFT][/TD]
[TD][LEFT]下载到特定文件[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader -patchline pre-release[/LEFT][/TD]
[TD][LEFT]从预发布渠道下载[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]./hytale-downloader -skip-update-check[/LEFT][/TD]
[TD][LEFT]跳过自动更新检查[/LEFT][/TD]
[/TR]
[/TABLE]
[HR][/HR]

运行 Hytale 服务器

使用以下命令启动服务器：

java -jar HytaleServer.jar --assets PathToAssets.zip

身份验证

首次启动后，请对您的服务器进行身份验证。

[QUOTE] /auth login device[/QUOTE]
===================================================================
DEVICE AUTHORIZATION
===================================================================
Visit: https://accounts.hytale.com/device
Enter code: ABCD-1234
Or visit: https://accounts.hytale.com/device?user_code=ABCD-1234
===================================================================
Waiting for authorization (expires in 900 seconds)...

[User completes authorization in browser]

[QUOTE] Authentication successful! Mode: OAUTH_DEVICE[/QUOTE]

身份验证通过后，您的服务器即可接受玩家连接。

额外身份验证信息

Hytale 服务器需要认证才能与我们的服务 API 进行通信并防止滥用。
注意：每个 Hytale 游戏许可证最多支持 100 个服务器，以防止早期滥用。如果您需要更多容量，请购买额外的许可证或申请服务器提供者账户。
如果您需要认证大量服务器或自动动态认证服务器，请阅读服务器提供者认证指南以获取详细信息。

帮助

审查所有可用参数：

java -jar HytaleServer.jar --help

预期输出：

Option Description
------ -----------
--accept-early-plugins Acknowledge that loading early plugins
is unsupported and may cause stability issues
--allow-op
--assets <Path> Asset directory (default: ..\HytaleAssets)
--auth-mode <authenticated|offline> Authentication mode (default: AUTHENTICATED)
-b, --bind <InetSocketAddress> Address to listen on (default: 0.0.0.0:5520)
--backup Enable automatic backups
--backup-dir <Path> Backup directory
--backup-frequency <Integer> Backup interval in minutes (default: 30)
[...]

端口

默认端口是 5520。使用 --bind 参数更改它：

java -jar HytaleServer.jar --assets PathToAssets.zip --bind 0.0.0.0:25565

防火墙与网络配置

Hytale 使用基于 UDP 的 QUIC 协议（而非 TCP）。相应地配置您的防火墙和端口转发。

端口转发

如果通过路由器进行托管，请将 UDP 端口 5520（或您的自定义端口）转发到您的服务器机器。不需要 TCP 转发。

防火墙规则

Windows Defender 防火墙:

New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow

Linux（iptables）:

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

Linux (ufw):

sudo ufw allow 5520/udp

NAT 注意事项

QUIC 在大多数情况下都能很好地处理 NAT 穿越。如果玩家连接遇到问题：

确保端口转发是专门针对 UDP，而不是 TCP
对称 NAT 配置可能导致问题 - 考虑使用 VPS 或专用服务器
位于运营商级 NAT（移动网络常见）后的玩家应能正常作为客户端连接

文件结构

[TABLE]
[TR]
[TH][LEFT]路径[/LEFT][/TH]
[TH][LEFT]描述[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT].cache/[/LEFT][/TD]
[TD][LEFT]优化文件的缓存[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]logs/[/LEFT][/TD]
[TD][LEFT]服务器日志文件[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]mods/[/LEFT][/TD]
[TD][LEFT]已安装的模组[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]universe/[/LEFT][/TD]
[TD][LEFT]世界和玩家存档数据[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]bans.json[/LEFT][/TD]
[TD][LEFT]被封禁的玩家[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]config.json[/LEFT][/TD]
[TD][LEFT]服务器配置[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]permissions.json[/LEFT][/TD]
[TD][LEFT]权限配置[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]whitelist.json[/LEFT][/TD]
[TD][LEFT]白名单玩家[/LEFT][/TD]
[/TR]
[/TABLE]

宇宙结构

universe/worlds/ 目录包含所有可玩世界。每个世界都有自己的 config.json：

{
"Version": 4,
"UUID": {
"$binary": "j2x/idwTQpen24CDfH1+OQ==",
"$type": "04"
},
"Seed": 1767292261384,
"WorldGen": {
"Type": "Hytale",
"Name": "Default"
},
"WorldMap": {
"Type": "WorldGen"
},
"ChunkStorage": {
"Type": "Hytale"
},
"ChunkConfig": {},
"IsTicking": true,
"IsBlockTicking": true,
"IsPvpEnabled": false,
"IsFallDamageEnabled": true,
"IsGameTimePaused": false,
"GameTime": "0001-01-01T08:26:59.761606129Z",
"RequiredPlugins": {},
"IsSpawningNPC": true,
"IsSpawnMarkersEnabled": true,
"IsAllNPCFrozen": false,
"GameplayConfig": "Default",
"IsCompassUpdating": true,
"IsSavingPlayers": true,
"IsSavingChunks": true,
"IsUnloadingChunks": true,
"IsObjectiveMarkersEnabled": true,
"DeleteOnUniverseStart": false,
"DeleteOnRemove": false,
"ResourceStorage": {
"Type": "Hytale"
},
"Plugin": {}
}

每个世界都在自己的主线程上运行，并将并行工作卸载到共享线程池中。
[HR][/HR]

技巧与窍门

安装模组

从 CurseForge 等来源下载模组（.zip 或 .jar），并将它们放入 mods/ 文件夹。

禁用哨兵崩溃报告

重要提示：在开发插件期间禁用 Sentry。
我们使用 Sentry 来追踪崩溃。使用 --disable-sentry 来禁用它，以避免提交您的开发错误：

java -jar HytaleServer.jar --assets PathToAssets.zip --disable-sentry

利用前置缓存

服务器自带一个预训练的前置缓存（HytaleServer.aot），通过跳过 JIT 预热来提高启动时间。参见 JEP-514。

java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets PathToAssets.zip

视距

视距是 RAM 使用的主要驱动因素。我们建议为了性能和游戏体验，将最大视距限制在 12 个区块（384 个方块）。
对比而言：Minecraft 服务器的默认值是 10 个区块（160 个方块）。Hytale 的默认值 384 个方块大致相当于 24 个 Minecraft 区块。使用默认设置时，预计 RAM 使用量会更高——请根据预期的玩家数量调整此值。
[HR][/HR]

多服务器架构

Hytale 支持在服务器之间路由玩家的原生机制。不需要像 BungeeCord 这样的反向代理。

玩家推荐

将已连接的玩家转移到另一台服务器。服务器发送一个包含目标主机、端口和一个可选的 4KB 有效载荷的推荐数据包。客户端与目标建立新连接，并在握手过程中展示有效载荷。

PlayerRef.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)

⚠️ 安全警告：有效负载通过客户端传输，可能被篡改。对有效负载进行加密签名（例如，使用共享密钥的 HMAC），以便接收服务器可以验证其真实性。
用例：在游戏服务器之间转移玩家、传递会话上下文、通过匹配进行访问控制。
即将推出：为回退连接按顺序尝试的目标数组。

连接重定向

在连接握手过程中，服务器可以拒绝玩家并将他们重定向到其他服务器。客户端会自动连接到重定向的地址。

PlayerSetupConnectEvent.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)

使用场景：负载均衡、区域服务器路由、强制执行大厅优先连接。

断开连接回退

当玩家意外断开连接（服务器崩溃、网络中断）时，客户端会自动重新连接到预先配置的回退服务器，而不是返回主菜单。
应用场景：在游戏服务器崩溃后，将玩家重新引导回大厅，在重启期间保持玩家参与度。
即将推出：预计在早期访问启动后几周内实现后备数据包功能。

构建代理

使用 Netty QUIC 构建自定义代理服务器。Hytale 仅使用 QUIC 进行客户端与服务器之间的通信。
数据包定义和协议结构可在 HytaleServer.jar 中找到：
com.hypixel.hytale.protocol.packets

使用这些来解码、检查、修改或转发客户端与后端服务器之间的流量。
[HR][/HR]

杂项详情

JAVA 命令行参数

参见重要 JVM 参数指南了解如何使用 -Xms 和 -Xmx 等参数控制堆内存大小。

协议更新

Hytale 协议使用哈希值来验证客户端与服务器之间的兼容性。如果哈希值不匹配，连接将被拒绝。
当前限制：客户端和服务器必须使用完全相同的协议版本。当我们发布更新时，服务器必须立即更新，否则新版本玩家将无法连接。
即将推出：允许客户端与服务器版本差异±2 的协议兼容性。服务器运营商将有一个更新窗口，而不会中断玩家连接。

配置文件

配置文件（config.json、permissions.json 等）在服务器启动时读取，并在游戏内操作发生时（例如通过命令分配权限）写入。服务器运行时手动更改可能会被覆盖。

MAVEN 中央组件

HytaleServer jar 将发布到 Maven Central，用于模组项目中的依赖。

<dependency>
<groupId>com.hypixel.hytale</groupId>
<artifactId>Server</artifactId>
</dependency>

具体的版本信息等细节将在发布时确定。请查看模组社区资源以获取使用这些依赖的最新信息。
[HR][/HR]

未来更新

服务器与小游戏发现

一个可通过主菜单访问的发现目录，玩家可以在其中浏览和找到服务器及小游戏。服务器运营商可选择加入目录，直接向玩家推广其内容。

列表要求：

[TABLE]
[TR]
[TH][LEFT]需求[/LEFT][/TH]
[TH][LEFT]描述[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]服务器运营商指南[/LEFT][/TD]
[TD][LEFT]服务器必须遵守运营商指南和社区标准[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]自我评级[/LEFT][/TD]
[TD][LEFT]运营商必须准确评级其服务器内容。评级用于内容过滤和家长控制[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]执行[/LEFT][/TD]
[TD][LEFT]违反自评等级的服务器将根据服务器运营商政策采取执法行动[/LEFT][/TD]
[/TR]
[/TABLE]

玩家数量验证：

服务器发现中显示的玩家数量是通过客户端遥测收集的，而不是服务器报告的数据。这可以防止数量欺骗，并确保玩家在浏览服务器时能够信任他们看到的数字。服务器仍然可以向添加服务器（未通过服务器发现）的用户报告未验证的玩家数量。

聚会

一个允许玩家组队并在服务器转移和小游戏排队时保持在一起的系统。

与服务器发现功能的集成：

玩家可以与队伍一起浏览服务器并一起加入。在加入前会显示队伍规模要求和限制，以便组队成员事先知道是否可以一起游戏。
该系统为无缝社交体验提供了基础，让朋友们可以作为一个团队在 Hytale 生态系统中移动，无需手动协调。

集成支付系统

一个集成在客户端的支付网关，服务器可以使用它来接受玩家的支付。可选但推荐。

对服务器操作者的好处：

无需处理支付详情或构建基础设施即可接受支付
通过可信、安全的系统处理交易

玩家的好处：

无需访问外部网站
所有交易安全且可追溯
支付信息保留在 Hytale 生态系统中

SRV 记录支持

SRV 记录允许玩家使用域名（例如 play.example.com）连接，而无需指定端口号，DNS 将处理查找以解析实际服务器地址和端口号。
当前状态：不支持。正在评估中。
为什么目前还不提供：
目前没有经过实战检验的 C# 库用于 SRV 记录解析。现有选项要么需要引入完整的 DNS 客户端实现，这会引入不必要的复杂性和潜在稳定性风险，要么缺乏我们作为核心网络功能所需的上线准备。
我们正在评估替代方案，并在找到合适的解决方案时重新审视这个问题。

第一方 API 端点

经过认证的服务器将能够访问官方 API 端点，用于玩家数据、版本控制和服务器操作。这些端点减少了第三方服务的需求，并直接从 Hytale 提供权威数据。

计划中的端点：

[TABLE]
[TR]
[TH][LEFT]端点[/LEFT][/TH]
[TH][LEFT]描述[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]UUID ↔ 名称查询[/LEFT][/TD]
[TD][LEFT]将玩家名称解析为 UUID，反之亦然。支持单个和批量查询[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]游戏版本[/LEFT][/TD]
[TD][LEFT]查询当前游戏版本、协议版本，并检查更新[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]玩家资料[/LEFT][/TD]
[TD][LEFT]获取玩家资料数据，包括外观物品、头像渲染和公开资料信息[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]服务器遥测[/LEFT][/TD]
[TD][LEFT]报告服务器状态、玩家数量和元数据以用于发现集成[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]报告[/LEFT][/TD]
[TD][LEFT]报告违反服务条款的玩家[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]支付[/LEFT][/TD]
[TD][LEFT]使用我们内置的支付网关处理支付[/LEFT][/TD]
[/TR]
[/TABLE]

考虑中：

[TABLE]
[TR]
[TH][LEFT]端点[/LEFT][/TH]
[TH][LEFT]描述[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]全球制裁[/LEFT][/TD]
[TD][LEFT]查询玩家是否具有平台级别的制裁（非服务器特定封禁）[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]好友列表[/LEFT][/TD]
[TD][LEFT]获取玩家的好友列表（需适当权限）以支持社交功能[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]Webhook 订阅[/LEFT][/TD]
[TD][LEFT]订阅推送通知，以接收玩家名称变更或制裁更新等事件[/LEFT][/TD]
[/TR]
[/TABLE]

设计目标：

充足的速率限制：批量端点和缓存友好的响应，以支持大型网络
认证访问：所有端点都需要服务器认证，以防止滥用

HYTALE 服务器手册