StellarAnchorBot

Appearance

代理集群部署 ​

本页对应官方教程中的“群组配置”，适用于由 BungeeCord / Waterfall 或 Velocity 代理连接多个 Bukkit 子服的网络。机器人 WebSocket 由代理统一连接，各子服通过独立 TCP 控制连接接入代理。

01安装组件代理网关 · Bukkit 子服02配置代理连接机器人 WebSocket03配置子服唯一标识 · TCP 接入04启动检查连接状态 · 白名单规则

安装组件 ​

  1. 在代理的 plugins 目录中安装与代理类型对应的 StellarAnchorBot-BungeeCord.jar 或 StellarAnchorBot-Velocity.jar。
  2. 在每个 Bukkit / Spigot / Paper 子服的 plugins 目录中安装 StellarAnchorBot.jar。
  3. 启动代理和所有子服，插件会自动生成各自的配置文件；配置生成后即可编辑对应配置。
实例配置文件运行模式
BungeeCord / Waterfall 网关plugins/StellarAnchorBot/config.yml代理网关配置
Velocity 网关plugins/StellarAnchorBot/config.yml代理网关配置
Bukkit / Paper 子服plugins/StellarAnchorBot/config.ymlPROXY_CLUSTER

配置代理网关 ​

打开生成的 config.yml，将 AutoOpen 设置为 true 即可，其余的如有需要可自行按下面的配置解释逐项修改（一般默认即可，不需要修改）：

yaml
# StellarAnchorBot 主程序扩展核心 WebSocket 配置
websocket:
  url: "ws://127.0.0.1:9090"
  # 断线最大重连次数，-1 代表无限次重连
  max_reconnect_times: 5
  # 心跳包发送间隔，单位：秒；最低 30 秒，默认 60 秒
  heartbeat_interval: 60
  # 是否在启动插件时自动连接
  # 此功能需提前开启机器人后台且机器人对接地址正确
  AutoOpen: true
  # 是否在机器人断开连接时自动重连
  Reconnect: true
配置项作用配置说明
websocket.url指定代理连接的机器人 WebSocket 地址机器人主程序与代理同机时使用 ws://127.0.0.1:9090；分机部署时改为机器人所在机器的可达内网地址。这里填写的是 WebSocket 端口，不是 Web 管理后台端口。
websocket.max_reconnect_times连接失败时的最大重连次数默认 5；需要持续重试时可改为 -1，表示无限重连。
websocket.heartbeat_intervalWebSocket 心跳间隔，单位为秒默认 60，最低不能低于 30。通常保持默认值即可。
websocket.AutoOpen代理插件启动时是否自动连接机器人确认机器人主程序已启动、地址可达后设为 true。设为 false 时需执行 /sab connect 手动连接。
websocket.Reconnect连接中断后是否自动重连建议保持 true，这样机器人或网络短暂重启后代理会自动恢复连接。

保存配置后，执行 /sab reload 重载代理插件，并执行 /sab status 检查 WebSocket 状态；显示连接正常后，再继续配置 Bukkit 子服。

配置 Bukkit 子服 ​

代理配置完成后，逐个编辑每台 Bukkit 子服生成的 plugins/StellarAnchorBot/config.yml。群组配置中，子服不直接连接机器人 WebSocket，而是使用 PROXY_CLUSTER 模式连接代理；每台子服都必须设置自己的唯一 server_id。

yaml
# STANDALONE：独立单服模式
# PROXY_CLUSTER：代理集群模式
# 可通过 /sab reload 热重载全部配置；连接与运行模式会立即按新值切换
run_mode: PROXY_CLUSTER

# 子服唯一标识ID(不可重复！！)
# 集群环境必填，集群网关依靠此ID分配事件
# 单机独立模式可自定义填写，无转发作用，用于日志区分多开子服
server_id: "sub_server_01"

# 是否在启动插件时自动连接
# 此功能需提前开启机器人后台且机器人对接地址正确
websocket:
  AutoOpen: true

按上面的示例为每台子服填写不同的 server_id，例如 sub_server_01、sub_server_02。子服控制连接参数保持插件生成的默认值即可；如果代理和 Bukkit 子服不在同一台机器，将 control.host 改为子服能够访问的代理内网地址。保存后在子服执行 /sab reload，插件会按新的运行模式连接代理。

当前版本中，PROXY_CLUSTER 子服通过 control TCP 连接代理，连接会自动建立；websocket.AutoOpen 不控制这条连接。该项按参考文档保留在示例中，群组连接状态以代理端 /sab status 和子服列表为准。

白名单只由一个子服处理 ​

白名单与验证码登录校验由 Bukkit 子服执行，代理仅路由请求，不参与玩家判定。 请只在登录服（玩家登录服务器时会进入的那个子服）启用白名单；其他子服保持关闭！！集群只允许一个子服启用 enabled: true 并使用 whitelist 或 captcha 模式，如果多个子服启用会拦截所有进服请求！！！

yaml
# 玩家进服白名单校验
# 集群模式注意：只能有一个子服启用白名单校验；机器人会在每次登录时实时查询权威白名单。
# 如果多个子服同时启用白名单，代理会让相关子服进入 conflict 模式并拦截进服，
# 同时暂停白名单请求路由，直到仅剩一个启用白名单的子服。
whitelist_check:
  # 总开关。开启时，玩家登录会向机器人查询白名单；插件不保存白名单归属数据。
  enabled: true
  # whitelist：无白名单直接提示玩家在群内申请
  # captcha：生成验证码，玩家在群内发送后重新连接即可进入
  mode: "whitelist"
  # 每次登录请求的最长等待时间；超时或并发达到上限时按不可用关闭失败
  login_query_timeout_ms: 1200

不要在多个子服同时启用白名单校验：代理检测到多个白名单目标时会报告冲突并拦截相关登录请求。

启动与检查 ​

保存代理与全部子服配置后，先启动机器人主程序，再启动代理和 Bukkit 子服。需要重新载入配置时，分别在子服和代理执行 /sab reload。

检查项验证方式
机器人 WebSocket代理执行 /sab status，确认机器人连接正常
子服控制连接代理执行 /sab servers，确认预期子服已接入
网络可达代理可访问机器人 WebSocket 地址；跨机器部署时子服可访问代理
子服标识每个 Bukkit 子服使用不同的 server_id
白名单路由集群仅有一个子服启用白名单登录校验

遇到连接问题时，先检查代理与子服控制台中的连接日志，再确认对应网络地址可达。

StellarAnchorBot 文档

Copyright © 2026 StellarAnchorBot