indifferentbroccoli/hytale-server-docker

Hytale专用服务器Docker镜像

!https://github.com/user-attachments/assets/b8b4ae5c-06bb-46a7-8d94-903a04595036 ![]([]

镜像概述和主要用途

本Docker镜像用于运行Hytale专用服务器，通过官方Hytale Downloader CLI实现服务器文件的自动下载和更新。它提供了便捷的部署方式，简化了Hytale服务器的配置和管理流程，适用于希望快速搭建和运行Hytale游戏服务器的用户。

服务器要求

[!NOTE]

• Hytale需要Java 25（已包含在Docker镜像中）
• 服务器资源使用率很大程度上取决于玩家数量和视野距离
• 更大的视野距离会显著增加内存使用
• Hytale使用基于UDP的QUIC协议（非TCP），端口为5520

[!IMPORTANT] 首次设置：需要身份验证

首次启动时，您需要通过浏览器进行身份验证。服务器会在控制台中显示一个URL - 只需访问该URL并使用您的Hytale账户登录。服务器启动后，您需要通过出现的链接再次授权。

使用方法和配置说明

准备工作

将.env.example文件复制到新文件.env，并根据需要调整设置。

快速启动

bash
# 1. 启动服务器
docker-compose up -d

# 2. 查看日志获取OAuth URL
docker-compose logs -f

# 3. 在浏览器中访问URL并进行身份验证
# 身份验证后服务器将自动继续运行

Docker Compose配置

使用以下docker-compose.yml配置：

yaml
services:
  hytale:
    image: indifferentbroccoli/hytale-server-docker
    restart: unless-stopped
    container_name: hytale
    stop_grace_period: 30s
    ports:
      - 5520:5520/udp
    env_file:
      - .env
    volumes:
      - ./server-files:/home/hytale/server-files
    stdin_open: true
    tty: true

启动命令：

bash
docker-compose up -d

Docker Run命令

bash
docker run -d \
    --restart unless-stopped \
    --name hytale \
    --stop-timeout 30 \
    -p 5520:5520/udp \
    --env-file .env \
    -v ./server-files:/home/hytale/server-files \
    -it \
    indifferentbroccoli/hytale-server-docker

环境变量

您可以使用以下环境变量在启动时更改服务器设置：

端口配置

Hytale使用基于UDP的QUIC协议（非TCP）。请确保：

1. 在防火墙中开放UDP端口5520（或您的自定义端口）
2. 在家中托管时，在路由器中转发UDP端口5520
3. 为UDP配置防火墙规则

文件结构

首次运行后，server-files目录中将创建以下结构：

server-files/
├── Server/
│   ├── HytaleServer.jar       # 主服务器可执行文件
│   └── HytaleServer.aot       # 用于加快启动的AOT缓存
├── Assets.zip                 # 游戏资源
├── downloader/                # Hytale下载器CLI
├── .cache/                    # 优化的文件缓存
├── logs/                      # 服务器日志文件
├── mods/                      # 已安装的模组（将.jar或.zip文件放在此处）
├── universe/                  # 世界和玩家存档数据
│   └── worlds/                # 各个世界文件夹
├── bans.json                  # 被封禁玩家
├── config.json                # 服务器配置
├── permissions.json           # 权限配置
└── whitelist.json             # 白名单玩家

安装模组

1. 从CurseForge等来源下载模组（.jar或.zip文件）
2. 将它们放在server-files/mods/目录中
3. 重启服务器

视野距离与性能

视野距离是内存使用的主要驱动因素：

• 默认值：12区块（384 blocks）≈ 24个Minecraft区块
• 推荐最大值：12区块以获得最佳性能
• 内存影响：更大的视野距离会指数级增加内存需求

根据以下因素调整MAX_MEMORY和VIEW_DISTANCE：

• 并发玩家数量
• 玩家在世界中的分布情况
• 可用服务器资源

常用命令

查看服务器日志

bash
docker logs hytale -f
# 或
docker-compose logs -f

停止服务器

bash
docker-compose down

重启服务器

bash
docker-compose restart

更新服务器文件

如果DOWNLOAD_ON_START=true，重启时会自动更新服务器文件。强制更新：

bash
docker-compose restart

支持

• 官方Hytale服务器手册
• https://github.com/indifferentbroccoli/hytale-server-docker/issues

许可证

本项目采用MIT许可证 - 详见LICENSE文件。