企业官网建设流程全解析

• AI Agent
• 人工智能
• 游戏开发

本文是基于 mindcraft 仓库 services/viaproxy/README.md 编写的实战指南。mindcraft（Minecraft AI with LLMs + Mineflayer）基于 mineflayer / minecraft-protocol 构建，对服务端版本有严格的兼容范围；当目标服务端运行在不被支持的版本上时，即可借助 ViaProxy 协议转换层，让 LLM 驱动的机器人顺利加入服务器。读完本文，你将掌握 ViaProxy 容器的一键启动、离线服快速接入、在线服微软账号登录与管理、配置持久化以及常见排错方法。

为什么需要 ViaProxy：mindcraft 的版本兼容边界

mindcraft 的机器人依赖 Mineflayer 生态与minecraft-protocol库与服务端通信，而协议库对 Minecraft 版本的支持是有限的。这一点在源码中有明确体现：

• src/mindcraft/mcserver.js 中的getServer()会在启动阶段 ping 目标服务器，读取其版本号，并用mc.supportedVersions判断版本是否受支持：isSupported检查通过后才会放行连接，否则直接抛出 "MC server was found ..., but version is unsupported" 错误；
• src/mindcraft/mindcraft.js 在创建每个 Agent 前调用getServer(settings.host, settings.port, settings.minecraft_version)，若minecraft_version为"auto"且探测失败，则降级为null后"尝试直接连接"；
• src/agent/connection_handler.js 将version_mismatch定义为致命错误（keywords 含outdated、version、client），一旦发生即视为无法恢复的连接失败。

这意味着当目标服务器使用过新、过旧或非标准协议版本时，机器人无法直接加入。ViaProxy（ViaVersion 系列工具的服务端实现）的作用正是在机器人客户端与目标服务器之间插入一层协议翻译：机器人按自己支持的版本与 ViaProxy 通信，ViaProxy 再以目标服务器的协议版本转发到真实服务端，从而突破版本限制。仓库主 README 在 Docker 章节也给出了提示："To connect to an unsupported minecraft version, you can try to use viaproxy"（见 README.md）。

一键启动：Docker Compose 中的 viaproxy 服务

仓库根目录的 docker-compose.yml 中已经内置了viaproxy服务定义，这也是使用它的最简方式：

viaproxy: #use this service to connect to an unsupported minecraft server versions. more info: ./services/viaproxy/README.md image: ghcr.io/viaversion/viaproxy:latest volumes: - ./services/viaproxy:/app/run ports: - "25568:25568" profiles: - viaproxy stdin_open: true tty: true

关键点说明：

• 镜像：ghcr.io/viaversion/viaproxy:latest，官方发布的 ViaProxy 容器镜像；
• 卷挂载：将仓库内services/viaproxy/目录挂载到容器的/app/run，ViaProxy 的配置文件、账号数据（saves.json）都会落盘到这个目录，便于持久化与备份；
• 端口：宿主机25568映射到容器25568，这是 mindcraft 机器人将连接的 ViaProxy 监听端口；
• profile：viaproxy属于可选 profile，默认docker-compose up不会启动它，必须显式指定--profile viaproxy；
• stdin_open/tty：保持容器交互式终端，这是后续docker attach进入容器执行account命令的前提。

启动命令：

docker-compose --profile viaproxy up

首次启动后，ViaProxy 会在挂载目录（即仓库的services/viaproxy/）中自动生成配置文件viaproxy.yml。该文件是后续所有接入配置（目标地址、认证方式、账号索引等）的核心所在。

离线服接入：三步完成

对于不需要正版验证（offline）的服务器，接入过程非常简单，按原文档的步骤执行即可：

第一步：编辑viaproxy.yml，设置目标服务器

修改自动生成的 services/viaproxy/viaproxy.yml（首次启动后才会生成），将target-address改为你真正要连接的服务端地址与端口。

第二步：修改settings.js，把机器人指向 ViaProxy

编辑仓库根目录的 settings.js，将连接目标改为 ViaProxy 容器的地址与端口：

"host": "host.docker.internal", "port": 25568,

• host使用host.docker.internal：这是 mindcraft 容器访问宿主机回环地址的特殊主机名。docker-compose.yml 中 mindcraft 服务已通过extra_hosts: "host.docker.internal:host-gateway"注入该映射；
• port固定为25568，对应 docker-compose.yml 中暴露的映射端口。

第三步：正常启动 mindcraft

node main.js

此时机器人先与 ViaProxy（协议版本由其自行协商支持）握手，再由 ViaProxy 转发到目标服务端。由于 offline 服务器不做正版验证，ViaProxy 以离线模式直连即可，无需任何账号配置。

补充：settings.js中minecraft_version可保持"auto"，启动时 src/mindcraft/mcserver.js 会从 ViaProxy 探测到的服务信息中解析版本号；ViaProxy 上报的通常是其自身"翻译后"的版本，从而绕过getServer()的supportedVersions校验。

在线服接入：微软账号登录与管理

如果目标服务器开启了正版验证（online），ViaProxy 必须以一个真实的正版账号身份与服务器通信。原文档明确指出这"involves more effort"（需要更多步骤），具体流程如下：

1. 启动容器并附加终端

先启动 ViaProxy 容器，然后在 mindcraft 目录下另开一个终端，附加到容器：

docker attach mindcraft-viaproxy-1

容器名mindcraft-viaproxy-1由 docker-compose 按"项目名-服务名-序号"自动生成（对应 docker-compose.yml 中的viaproxy服务与stdin_open: true、tty: true配置）。

2. 使用account命令管理账号

附加成功后，即可在容器交互终端中使用account命令族：

典型操作序列：account add microsoft完成交互式登录 →account list获取账号 id →account select <id>激活该账号。

3. 安全警告：切勿泄露saves.json

原文档对此给出了明确的[!WARNING]，必须原样继承：

如果你使用微软账号登录，访问令牌（access token）会存储在saves.json文件中。永远不要与任何人分享这个文件！否则对方可以用你的名义加入服务器！

由于services/viaproxy/目录被挂载为容器的/app/run，saves.json实际保存在仓库的 services/viaproxy/saves.json（首次账号登录后生成）。该文件属于敏感凭据，应像 keys.json 一样加入.gitignore并妥善保管，切勿提交到公开仓库或发送给他人。

4. 分离容器

账号配置完成后，使用快捷键CTRL-P然后CTRL-Q从容器终端分离，容器会继续在后台运行。

配置持久化：把账号设置写进viaproxy.yml

account命令的选择是运行时状态，容器重启后会丢失。若希望持久保留这些配置，原文档给出了两个配置项：

1. 将auth-method改为account；
2. 将minecraft-account-index设置为对应账号的 id（用account list查看）。

这样每次容器启动时，ViaProxy 都会自动使用指定账号进行正版登录，无需再手动account select。离线场景下则保持默认的离线认证方式即可。

与 mindcraft 的联动细节与排错建议

• host 必须用host.docker.internal吗？只有当 mindcraft 本体也运行在 Docker 容器中时才需要（mindcraft 容器通过host-gateway映射访问宿主机上的 ViaProxy 端口）。若 mindcraft 直接运行在宿主机上（node main.js），host直接写127.0.0.1、port写25568即可，参见 README.md 的说明。
• 连接报错时先看是哪种失败：参照 src/agent/connection_handler.js 的ERROR_DEFINITIONS，version_mismatch表示协议版本仍未对齐（检查 viaproxy.yml 的target-address与 mindcraft 的minecraft_version）；access_denied表示未被白名单/被封禁（在线服需确认账号已select）；network_error表示 ViaProxy 端口不可达（检查 25568 端口映射与容器运行状态）。
• 版本自动协商：settings.js中minecraft_version建议保持"auto"，与 src/mindcraft/mindcraft.js 的降级逻辑配合，尽可能避免因版本探测失败而中止启动。
• 端口冲突：若宿主机 25568 已被占用，可修改 docker-compose.yml 中 viaproxy 的ports映射（如"25569:25568"），并同步更新settings.js中的port。

小结

ViaProxy 是 mindcraft 应对"不支持的 Minecraft 服务端版本"这一边界场景的官方推荐方案：它通过 docker-compose.yml 中的viaproxyprofile 一键部署，离线服只需修改 services/viaproxy/viaproxy.yml 的target-address与 settings.js 的host/port即可接入；在线服则需通过docker attach进入容器，用account命令完成微软账号的添加、选择与持久化。全程注意保护保存了访问令牌的saves.json文件。结合 src/mindcraft/mcserver.js 的版本校验逻辑与 src/agent/connection_handler.js 的错误分类，你可以在接入失败时快速定位问题层级，将 LLM 驱动的机器人稳定地带入任何目标服务器。

• AI Agent
• 人工智能
• 游戏开发