跳转至

TabQQVelocity 插件（三合一）部署指南

本文是运维经验笔记，适用于「Velocity + 多后端（Paper/Folia）」架构的服务器。文中的具体地址、端口、凭据均已省略，请以自己的环境为准。

是什么

TabQQVelocity 是比奇堡自研的三合一通用插件（借鉴 LuckPerms 的多平台模式）：一个 jar 同时包含 Bukkit 与 Velocity 双入口描述符，部署到哪个端就自动激活对应模块。它取代了原先的三个插件（TabVelocity + QQVelocity + ItemProvider），消除多插件之间的格式不一致与版本漂移问题。

模块 运行端 功能
common 共享 消息格式构建器（本服条/跨服条统一来源，单格式保证一致）
bukkit 每个后端服 物品数据 / 简中翻译（官方 zh_cn）/ 地图数据接收 / 本服聊天条
velocity 代理端 ×1 跨服聊天转发 / QQ 互通 / 物品图片渲染 / tab 服务器列表

功能一览

  • 聊天条：[服务器标签] 头像 玩家名: 消息 —— 点标签传送到对应服、点玩家名预填 /msg 回复、名字前显示皮肤头像
  • 跨服转发：本服显示 + 其他服同款格式转发（不回流发送者）
  • QQ 互通：MC ↔ QQ 群双向文字；[item] 渲染成物品 tooltip 图片发群
  • 物品链接：聊天中发 [item]，MC 内显示行内物品图标（1.21.9+ Atlas Sprite 贴图）+ 悬停物品 tooltip
  • tab 列表：玩家 tab 界面的服务器列表与前缀

构建

  • Gradle 多模块工程（common / bukkit / velocity），产物 TabQQVelocity-<版本>.jar
  • 产物命名带版本号（版本来自根 build.gradle，git 管理、每批改动 commit）

部署要点（血泪教训）

  1. 删旧再传，禁留多版本：同插件 ID 多个版本 jar 并存时，先加载者占坑（日志报 Refusing to load plugin ... same ID），后传的新版永远不生效。部署 = 先删 plugins 里全部旧版本 jar → 传新版 → 重启。
  2. 逐端核对：上传后列出 plugins 目录确认只剩一个 jar，再重启。
  3. 配置：
  4. 代理端：plugins/tabqqvelocity/config.toml（QQ 机器人凭据、群开关、跨服、tablist）
  5. 每个后端：plugins/TabQQVelocity/config.yml（分服标签）： 
    chat:
  enabled: true
  server-name: 空岛            # 本服标签（空岛/生存/大厅/地皮…）
  server-command: /server skyllia
  6. 全子服安装：每个后端都要放 jar（本服条由各后端自己渲染），代理端放一份（跨服/QQ/tab）。

验证清单

进服发条消息逐项核对：

  1. 聊天单条显示 [标签] 🧑 玩家名: 消息（不双条、不掉线）
  2. 点标签 → 传送到对应服；点玩家名 → 聊天框预填 /msg 玩家名
  3. 手持物品发 [item] → MC 内行内物品图标 + 悬停 tooltip
  4. QQ 群收到同条消息；带 [item] 时收到物品 tooltip 图片
  5. 按 tab → 服务器列表正常

常见坑

现象 原因 处理
一条消息显示两遍 旧插件（ItemProvider/TabVelocity/SignedVelocity 等）残留并行运行 停进程→移除旧 jar→核实→重启（勿吞 mv 报错）
新功能不生效、日志有 Refusing ... same ID plugins 里堆了多版本 jar 删旧版本只留一个
QQ 收到文字 [item] 不出图 物品数据通道未注册（日志应有 Item channel registered） 确认为最新版 jar；查代理端启动日志
MC 内 [item] 显示原文 hover 缓存空（后端未推送物品数据） 查后端日志"已发送物品信息"；确认全子服都装了插件
聊天变回原版 后端 chat.enabled 未开或 config 未生成 确认 config.yml 三键；插件需调用 saveDefaultConfig