GITHUB  •  DOCUMENTATION  •  DISCORD

概述 - BileTools 的功能

BileTools 监视您的插件目录并驱动运行时生命周期更改，因此重建会落入正在运行的服务器，而不是重启。

• 自动热重载。 在现有插件 jar 上重新编译，BileTools 会自动检测内容更改。

• 热插拔。 将新 jar 放入插件目录中，它会被排队以进行运行时加载，而无需完全重启。

• 自动卸载。 删除跟踪的 jar，其插件将被卸载。

• 生命周期命令。 从 /bile 命令树手动加载、卸载、重载、安装和卸载。

• 依赖感知。 依赖插件在替换时被卸载和重新加载，而不是盲目地重新加载一个 jar。

• 本地插件库。 BileTools 看到的每个 jar 都按版本归档，且同一文件夹是 /bile install 读取的。备份和回滚是相同的功能。

• 远程部署。 将选定的 jar 更改推送到其他配置的服务器，经过身份验证、大小限制和 SHA-256 验证的传输。

检测，简而言之： 仅大小或时间戳更改会唤醒观察者。jar 的 SHA-256 决定是否实际重新加载，因此您触摸但未更改的 jar 会被忽略。

BileTools 是一个开发工具。 它故意在运行时操作插件生命周期状态。这正是使开发循环快速的原因，也正是它属于开发和测试服务器的原因。热重载不能替代在实时服务器上的干净重启。

兼容性 - 运行时和 Java

一个 jar 覆盖所有六个运行时，Minecraft 1.20.1 到当前的 26.x。

• Paper 通过服务器的公共 PluginManager 加载

• Purpur 相同的 Paper 家族加载和卸载路径

• Leaf Paper 家族分支，像 Paper 一样处理

• Folia 区域化调度，BileTools 声明支持 folia

• Canvas Folia 分支，相同的区域化规则

• Spigot 通过 plugin.yml 加载；仅包含 paper-plugin.yml 的 jar 会被拒绝

Java: Java 17 用于 Minecraft 1.20.1+，Java 25 用于 26.x+。匹配您的服务器已经要求的内容。

Folia 和 Canvas: 在区域化服务器上热重载本质上更脆弱。未声明 folia 支持的第三方插件在热加载时可能仍会失败。

命令和权限

根命令是 /biletools。别名： /bile， /bi， /b。

/bile load <plugin>                    从插件目录加载插件 jar
/bile unload <plugin>                  卸载已安装的插件
/bile reload <plugin>                  重新加载已安装的插件
/bile uninstall <plugin>               从插件目录删除插件 jar
/bile install <plugin> [version=..]    从 BileTools 库安装插件
/bile library [plugin=..]              列出库插件，或一个插件的版本

一个权限覆盖整个树：

bile.use     给予访问 BileTools 的权限     默认：op

手动命令始终绕过观察者过滤器。选项卡补全建议已安装的插件、库插件和存储版本。单独运行 /bile 会打开一个分页的悬停和点击帮助菜单。

可选参数必须命名。 位置传递会因 "意外参数" 而失败：

/bile install MyPlugin                   有效  (默认为 version=latest)
/bile install MyPlugin version=1.4.2     有效
/bile install MyPlugin version=latest    有效
/bile install MyPlugin 1.4.2             失败
/bile library                            有效  (列出所有内容)
/bile library plugin=MyPlugin            有效
/bile library MyPlugin                   失败

配置 - 完整默认 config.yml

remote-deploy:
  slave:
    slave-enabled: false
    slave-port: 9876
    slave-payload: pickapassword
  master:
    master-enabled: false
    master-deploy-to:
    - yourserver.com:9876:password
    master-deploy-signatures:
    - MyPlugin
    - AnotherPlugin
  socket-timeout-ms: 15000
  max-transfer-bytes: 268435456
archive-plugins: true
watcher:
  idle-poll-ticks: 20
  active-poll-ticks: 5
  fingerprint-debounce-ticks: 8
  ignore:
  - LuckPerms
  - Vault
  - ProtocolLib
  - packetevents
  - WorldGuard
  - CoreProtect
  - spark
  only: []
  coalesce-window-ticks: 10
observability:
  log-timings: true
lifecycle:
  health-check: true

每个选项的功能

• watcher.ignore 自动热插拔、重载和卸载将跳过的插件名称。默认值是通常在开发盒上自动重载时危险或无用的内容。

• watcher.only 当此列表不为空时，仅 这些插件会被自动管理。在繁忙的服务器上积极开发一两个项目时非常有用。

• watcher.active-poll-ticks / idle-poll-ticks 观察者在更改到达时扫描的频率，与目录稳定后扫描的频率。

• watcher.fingerprint-debounce-ticks jar 的指纹必须保持稳定的时间，才能开始生命周期工作。这可以防止半写的 jar 被加载。

• watcher.coalesce-window-ticks 将附近的 jar 写入批处理成一个依赖顺序的重载刷新，因此多模块构建不会触发五次单独的重载。

• archive-plugins 在替换之前将每个插件 jar 归档到库文件夹中。

• lifecycle.health-check 在加载或重新加载后，验证插件是否实际注册和启用。操作失败会将插件标记为脏，并暂停对其的自动重载。

• observability.log-timings 记录每个操作的每个阶段的时间（卸载、依赖、加载、健康）。

插件库和回滚

plugins/BileTools/library/<PluginName>/<version>.jar

当 archive-plugins 开启时，BileTools 看到的每个插件 jar 都会在被替换之前复制到这里。这意味着库也充当回滚历史，/bile library 列出您拥有的内容，/bile install <plugin> version=<version> 将其中任何内容放回正在运行的服务器。

远程部署

可选。让主服务器将选定的 jar 更改推送到一个或多个从服务器。

• 在每个接收服务器上：设置 remote-deploy.slave.slave-enabled: true，选择一个端口并将 slave-payload 设置为共享密码。

• 在发送服务器上：设置 remote-deploy.master.master-enabled: true，在下面的形式中列出每个目标，并在 master-deploy-to 中列出要转发的插件。

master-deploy-to:
- host:port:password

传输会落入临时 .part 文件中，只有在密码、文件名、传输大小和 SHA-256 都检查通过后才会被提升。文件名会被清理，任何会逃离插件文件夹的路径都会被拒绝。默认值是 256 MB 限制和 15 秒的套接字超时。

语言 - 所有 17 个区域代码

默认选择英语。要切换，请在 plugins/BileTools/language.yml 中设置 locale：

locale: en_US

de_DE    German (Germany)
es_ES    Spanish (Spain)
fi_FI    Finnish (Finland)
fr_FR    French (France)
he_IL    Hebrew (Israel)
it_IT    Italian (Italy)
ja-JP    Japanese (Japan)
ko_KR    Korean (South Korea)
lt_LT    Lithuanian (Lithuania)
nl_NL    Dutch (Netherlands)
pl_PL    Polish (Poland)
pt_PT    Portuguese (Portugal)
ru_RU    Russian (Russia)
tr_TR    Turkish (Turkey)
vi_VI    Vietnamese (Vietnam)
zh_CN    Chinese (Simplified)
zh_TW    Chinese (Traditional)

您还可以在不触及捆绑包的情况下覆盖单独的行。您在 language.yml 中的 messages: 部分下添加的任何内容都会生效；您遗漏的所有内容都会回退到所选语言，然后回退到英语。文件在保存时会热加载。

重载实际运行的方式

每个操作 热插拔、重载、安装、卸载、远程部署：通过一个序列化队列，带有去重键，在专用的插件操作线程上进行。生命周期变更本身始终在全局或主线程上运行。

detect -> stabilize -> fingerprint -> queue -> unload -> load -> dependents -> health check

实现 VolmLib 的 ReloadAware 合同的插件在其任务被取消和监听器被拆除之前，会获得一个 HOT_RELOAD 或 HOT_UNLOAD 回调，以便在调度程序仍然存活时排空正在进行的工作。

卸载会将插件从实时命令图、服务、消息通道和查找表中清除，然后关闭其类加载器，这就是为什么命令和选项卡补全会正确返回，而不是半连接的原因。

生命周期等待带有明确的超时。卡住的操作会被视为失败，并将插件标记为脏，而不是阻塞队列。打开 observability.log-timings 可以查看每个操作的每个阶段的时间。

热重载的已知限制

并非每个插件都可以干净地热重载，BileTools 也不假装如此。通常无法在类重载中存活的内容：

• 静态状态 在类重载中保持的字段

• 后台线程 在插件调度程序外部启动的工作

• 本机资源 绑定在 JVM 外部的任何内容

• 外部连接 具有自己生命周期的套接字和池

• 插件特定内部 其他插件拥有的缓存和注册表

将关键或不常见的插件保留在忽略列表中，在迭代时打开时间日志，当状态无法安全重建时，重启服务器。