单服配置

本页对应官方教程中的“单端配置”，适用于一台 Bukkit / Spigot / Paper 服务端直接连接 StellarAnchorBot 的场景。单服模式不需要安装 BungeeCord 或 Velocity 网关。

01安装插件放入 plugins · 首次启动02连接机器人填写地址 · 自动连接03设置白名单普通白名单或验证码04检查状态重载 · 查看连接

安装并生成配置

将 StellarAnchorBot.jar 放入服务端的 plugins 目录并启动服务端，插件会自动在 plugins/StellarAnchorBot/ 下生成 config.yml。

适用范围

此配置用于独立运行的 Bukkit 子服。若服务端属于 BungeeCord / Waterfall 或 Velocity 群组网络，请改用代理集群部署。

配置 WebSocket 连接

打开生成的 config.yml，确认运行模式为 STANDALONE，并将 WebSocket 地址设置为机器人主程序的独立监听地址：

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

# 机器人WebSocket配置（代理集群模式下无效）
websocket:
  # 主程序扩展核心的独立 WebSocket 监听地址
  url: "ws://127.0.0.1:9090"
  # 断线最大重连次数，-1=无限循环重连
  max_reconnect_times: 5
  # 是否在启动插件时自动连接
  # 此功能需提前开启机器人后台且机器人对接地址正确
  AutoOpen: true
  # 是否在机器人断开连接时自动重连
  Reconnect: true

配置项	用途	建议
run_mode	选择插件运行模式	单服保持 STANDALONE
websocket.url	连接机器人主程序的 WebSocket 地址	同机默认 ws://127.0.0.1:9090；跨机器时填写机器人可达的内网地址
websocket.AutoOpen	插件启动时自动建立连接	确认机器人后台已启动后设为 true
websocket.Reconnect	连接断开后自动重连	建议保持 true

9090 是机器人主程序的独立 WebSocket 监听端口，不是 Web 管理后台端口。若修改了主程序监听配置，请同步修改这里的地址。

按需启用白名单

默认不启用进服白名单校验。需要此功能时，在同一份 Bukkit 配置中设置 whitelist_check：

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

模式	玩家进服行为	适合场景
whitelist	已绑定白名单的玩家直接进入；未绑定玩家会看到群内申请提示	希望用户手动在群内申请白名单的场景
captcha	玩家按提示在群内完成验证码，再在有效时间内重新连接	希望用户可以直接在群内发送验证码，简化申请流程的场景

验证码长度、有效时间和提示文字均可继续在 whitelist_check.captcha 中调整；普通白名单提示可通过 whitelist_prompt 自定义。机器人端也需要启用并匹配相应的白名单功能，具体申请方式见白名单与验证码。

mode 为 whitelist 时，机器人端也需要同步修改：

机器人端配置 · `whitelist` 模式

mode 为 captcha 时，机器人端也需要同步修改：

机器人端配置 · `captcha` 模式

验证连接

保存配置后启动服务端。若插件已经运行，可在游戏或控制台执行 /sab reload 载入配置；使用 /sab connect 手动连接，使用 /sab status 检查连接状态。

检查结果	处理方式
显示已连接	单服连接配置完成，可继续设置消息互通、变量解析等功能
无法连接或连接超时	检查机器人主程序是否运行、WebSocket 地址及端口是否可达
白名单查询不可用	检查机器人端白名单功能、群聊配置及 Bukkit 端 whitelist_check

如果你运行的是 BC / VC 群组网络，请前往代理集群部署查看对应的群组配置流程。