Velocity Docker镜像文档

镜像概述与主要用途

Velocity Docker镜像是一个自动构建的Docker镜像，用于快速部署Velocity代理服务器。Velocity是一款下一代Minecraft代理服务器，专注于可扩展性和灵活性，允许服务器管理员将多个Minecraft服务器连接起来，使其呈现为一个统一的服务。本镜像集成了Velocity***文档推荐的优化Java参数，并通过GitHub Actions自动跟踪Velocity版本更新，确保用户能够便捷获取最新稳定版本。

核心功能与特性

Velocity核心特性

• 极速性能：优化的登录流程与服务器切换机制，充分利用硬件资源，同时注重安全性，可在提供插件支持的同时保持高抗性，保护后端服务器免受访问。

• 高可扩展性：支持单代理实例承载数千名玩家，适用于从大型网络到小型服务器的各种规模场景。

• 广泛兼容性：兼容Paper、Sponge、Forge、Fabric等多种服务端类型，支持Minecraft 1.7.2至1.18.1的所有版本。

Docker镜像特性

• 自动构建：通过GitHub Actions自动跟踪Velocity***版本，实时构建并推送最新镜像。

• 优化配置：默认集成Velocity***推荐的Java参数，确保服务器运行效率。

• 灵活扩展：支持通过环境变量和卷挂载自定义配置，满足不同场景需求。

使用场景与适用范围

Velocity Docker镜像适用于需要搭建Minecraft多服务器代理环境的场景，包括：

• 大型Minecraft网络：需连接多个后端服务器，实现玩家无缝切换与负载均衡。

• 中小型服务器集群：通过代理统一访问入口，简化玩家体验并增强安全性。

• 多版本兼容环境：需同时支持不同Minecraft版本玩家连接至对应后端服务器。

• 开发测试环境：快速部署Velocity代理进行插件开发或服务端配置测试。

使用方法与配置说明

快速启动Velocity服务器

使用以下命令可快速启动基础Velocity代理服务器：

docker run -p 25577:25577 treysu/velocity:stable

说明：25577为Velocity默认端口，此命令启动基础容器，建议结合环境变量与卷挂载优化配置。

详细配置与扩展

环境变量

通过环境变量自定义Java运行参数，关键变量说明如下：

JAVA_MEMORY

• 作用：设置JVM初始内存（-Xms）与最大内存（-Xmx）。
• 默认值：512M
• 建议：根据服务器硬件与玩家数量调整，例如2G内存可设置为2G。
• 示例：

  docker run -e JAVA_MEMORY=2G -p 25577:25577 treysu/velocity:stable
  

JAVA_FLAGS

• 作用：提供额外Java启动参数，与JAVA_MEMORY配合使用。
• 默认值：Velocity***推荐参数：

  -XX:+UseStringDeduplication -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch
  

• 使用场景：需自定义JVM参数（如GC调整、性能优化）时追加或覆盖默认值。
• 示例：

  docker run -e JAVA_FLAGS="-XX:+UseZGC -XX:+ParallelRefProcEnabled" -p 25577:25577 treysu/velocity:stable
  

数据持久化（卷挂载）

服务器配置、日志等数据存储于容器内/data目录，建议通过卷或绑定挂载持久化数据：

使用命名卷

docker volume create velocity-data
docker run -v velocity-data:/data -p 25577:25577 treysu/velocity:stable

使用绑定挂载（主机目录）

docker run -v /path/on/host/velocity-data:/data -p 25577:25577 treysu/velocity:stable

Docker Compose配置示例

创建docker-compose.yml文件，配置如下：

version: '3.8'

services:
  velocity:
    image: treysu/velocity:stable
    container_name: velocity-proxy
    ports:
      - "25577:25577"  # Velocity默认端口
    environment:
      - JAVA_MEMORY=2G  # 内存配置，根据实际需求调整
      - JAVA_FLAGS="-XX:+UseZGC -XX:+ParallelRefProcEnabled"  # 额外Java参数（可选）
    volumes:
      - velocity-data:/data  # 持久化数据卷
    restart: unless-stopped  # 自动重启策略

volumes:
  velocity-data:  # 自动创建命名卷

启动服务：

docker-compose up -d

镜像变体

treysu/velocity提供多种标签，适用于不同场景：

treysu/velocity:stable

• 特性：基于Velocity***稳定版构建，确保稳定性。
• 适用场景：生产环境，追求可靠性。
• 推荐：大多数用户首选此标签。

treysu/velocity:latest

• 特性：开发构建版本，包含最新开发特性。
• 适用场景：测试环境，需尝鲜新功能时使用。
• 注意：不推荐生产环境使用，可能存在不稳定因素。

treysu/velocity:<version>-SNAPSHOT

• 特性：特定版本的快照构建（如3.2.0-SNAPSHOT）。
• 适用场景：开发测试，需验证特定快照版本功能。
• 注意：快照版本稳定性未经验证，生产环境禁用。

许可证说明

使用本镜像需遵守以下许可证要求：

• Velocity核心：遵循GPLv3许可证，由Velocity开发团队提供。
• Docker镜像构建项目：代码以MIT许可证分发，包含镜像构建脚本及相关配置。

请务必区分两者，遵守各自许可条款。