AutoUpdatePlugins v12.2.0
让您的服务器插件自动、安全且跨平台地保持最新 - 自动化更新。
TL;DR(太长不看)
放入 jar 包 ➜ 列出您想要更新的插件 ➜ 它会自动从众多来源查找、下载、验证并暂存更新 - 支持定时调度、并行处理,且不阻塞主线程。
目录
亮点
-
一个列表,多种来源。 从 GitHub Releases/Actions、Jenkins、SpigotMC (Spiget)、dev.bukkit、Modrinth、Hangar、BusyBiscuit、blob.build、Guizhanss v2、MineBBS、CurseForge,或任何包含直接 .jar 链接的页面拉取更新。
-
本地源。 指向本地的 jar 文件,或运行输出 jar 路径的脚本以支持自定义/修改版构建。
-
智能文件选择。 使用 ?get=<regex>、[N](选取第 N 个资源——适用于 GitHub 和 Jenkins 制品)、?artifact=2 用于 GitHub Actions 包、?prerelease=true、?alpha=true、?beta=true、?latest=true、?channel=Alpha、?autobuild=true——自由组合以获取您所需的精确构建版本。
-
无缝配置演进。 新选项会自动添加到 config.yml 中,且不会覆盖您的注释或现有值。
-
HTTP 灵活性。 可添加自定义请求头、轮换 User-Agent,并在需要时通过代理路由。
-
内置性能优化。
-
完全异步下载;不会阻塞主线程。
- 基于 Java 11+ HTTP/2 客户端,支持现代非阻塞传输。
- 利用 Java 21+ 虚拟线程实现超轻量级并发。
- 支持连接池、并行下载以及指数退避重试。
-
灵活的调度机制。 支持间隔时间 + 启动延迟 或 带时区支持的 cron 表达式。
-
跨平台兼容。 适用于 Spigot、Paper、Folia、Velocity、BungeeCord。
-
安全更新流程。 下载 ➜ 验证 ➜ 原子替换,通过临时/更新路径进行 staged 部署。
-
完整性校验与去重。 可选的 zip 完整性检查,并通过 MD5 比对跳过损坏或未更改的下载文件。
-
回滚安全网。 自动快照备份旧版 jar 包,若新版本启动失败则自动恢复。
支持的来源与平台
下载来源
| 来源 |
发布/构建发现方式 |
备注 / 支持的参数 |
| GitHub |
Releases & Actions |
[N], ?artifact=2, ?get=regex, ?prerelease=true, ?alpha=true, ?beta=true, ?latest=true, ?autobuild=true |
| Jenkins |
Latest build artifacts |
[N], ?get=regex |
| SpigotMC (Spiget) |
Resource page URL |
自动解析最新版本 |
| dev.bukkit |
Project page |
自动解析最新版本 |
| Modrinth |
Project/version URL |
?get=regex, ?alpha=true, ?beta=true, ?latest=true |
| Hangar |
Project/releases |
?get=regex, ?alpha=true, ?beta=true, ?latest=true, ?channel=Alpha |
| BusyBiscuit |
Project index |
自动解析 |
| blob.build |
Build artifacts |
?get=regex |
| Guizhanss v2 |
Project index |
自动解析 |
| MineBBS |
Resource page |
自动解析 |
| CurseForge |
Project/files |
?get=regex |
| Generic |
Direct .jar link |
精确文件 URL |
| Local file |
Local path |
file:, local:, path: 或绝对/相对路径 |
| Local script |
Script stdout path |
script: 或 exec:(脚本将 jar 路径打印到标准输出) |
注意: GitHub 和 Jenkins 链接均接受 [N] 以选择其发布/构建页面上的第 N 个工件(从 1 开始计数)。
提示: 对于大多数来源,您可以仅传递 项目根 URL(例如 GitHub 仓库或 Spigot 资源页面),并让 AutoUpdatePlugins 选择最新工件。添加参数以实现精确控制。
服务器平台
- Spigot, Paper, Folia
- Velocity, BungeeCord
Minecraft 与 Java
- Minecraft: 1.8 → 最新版本
- Java: 8+(在 11+ 和 21+ 上自动使用高级特性)
要求
安装
- 从 Spigot 下载最新的
.jar 文件。
- 将其放入服务器的
plugins/ 目录中。
- 启动服务器以生成默认配置文件。
- 编辑
plugins/AutoUpdatePlugins/config.yml 和 plugins/AutoUpdatePlugins/list.yml。
- 运行
/update 或 /aup update(或重启服务器)以启动首次检查。
Velocity / BungeeCord: 过程相同——将 jar 放入 plugins/,进行配置,然后触发更新运行。
快速入门
-
在 list.yml 中添加几项条目:
ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"
EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"
-
保持 updates.interval 为默认值(每 120 分钟一次),或设置 cron 计划。
-
可选:在 config.yml 中添加 GitHub token 以避免速率限制。
-
触发运行:
/update
-
新的 jar 文件会以原子方式暂存在您的插件文件夹中(底层使用 temp/update 路径)。重启服务器以加载更新的 jar 文件。
配置
config.yml
该插件会自动添加新选项而不会覆盖您的注释。以下是带有默认值和备注的完整 schema。
################################################################################
# AutoUpdatePlugins - Main Configuration
################################################################################
updates:
# 插件更新运行的频率(分钟)。默认值:120(每 2 小时)
interval: 120
# 服务器启动后首次运行前的延迟时间(秒)。默认值:50
bootTime: 50
# 计划任务(实验性):使用 cron 表达式精确控制更新运行的时间。
# 设置此项后,它将覆盖 interval 和 bootTime。
# 示例:
# 每天凌晨 03:30:"30 3 * * *"
# 每 15 分钟: "*/15 * * * *"
# 工作日每小时过 5 分钟:"5 * * * 1-5"
schedule:
cron: "" # Cron 表达式(UNIX 5 字段)。留空表示禁用。
timezone: "UTC" # cron 计划的时间区,例如 "America/New_York"
# 可选的 GitHub 个人访问令牌 (PAT)。强烈建议使用,
# 如果您使用许多 GitHub 链接,以避免在列出发布版本/工件时遇到 API 速率限制。
# 作用域:对于公共仓库,public_repo 就足够了。
# 生成令牌:https://github.com/settings/tokens
key:
# HTTP 配置(可选)
http:
# 如果为空,将使用轮换的真实 User-Agent 池。
userAgent: ""
# 添加到每个请求的额外请求头。仅在您需要时才添加。
headers: [ ]
# 验证 TLS 证书(设置为 false 以信任所有证书;仅在必需时使用)
sslVerify: true
# 可选的 User-Agent 池;插件将在它们之间轮换,以避免
# 严格的 CDN 阻止自动化操作。
userAgents:
- { ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" }
- { ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15" }
- { ua: "Mozilla/5.0 (X11; Linux x86_64; rv/126.0) Gecko/20100101 Firefox/126.0" }
# 代理配置(可选)
proxy:
type: "NONE" # HTTP | SOCKS | (其他任何值 = 禁用)
host: "proxy.example"
port: 8080
# 行为开关
behavior:
useUpdateFolder: true
# 在安装前打开下载的 .jar/.zip 文件以确保完整性(推荐)
zipFileCheck: true
# 如果新 jar 的 MD5 与现有插件相同,则跳过替换
ignoreDuplicates: true
# 默认允许 GitHub/Modrinth/Hangar 预发布版本用于发布查询。
allowPreRelease: false
# 启用 GitHub 仓库的源码构建回退机制。
autoCompile:
enable: false
# 当发布版本没有 .jar 资产(仅有 zip)时进行构建
whenNoJarAsset: true
# 如果主分支比最新(预)发布版本早 N 个月,则从源码构建
branchNewerMonths: 6
# 详细调试日志。通过 /aup debug on|off 切换
debug: false
# 更新后自动重启服务器/代理。
restartAfterUpdate: false
# 更新后重启前的延迟时间(秒)。
restartDelaySec: 5
# 重启前广播的消息(支持 {delay} 变量)。
restartMessage: "Server restarting to apply updates."
# 可选自定义路径
paths:
tempPath: ''
updatePath: ''
filePath: ''
rollbackPath: ''
# 性能与可靠性选项
performance:
# 最大并行下载数。越高越快,但会占用更多 IO/CPU。
# 如果设置高于 CPU 核心数,内部会自动限制。
maxParallel: 4
# 每次请求的 HTTP 连接超时时间(毫秒)。
connectTimeoutMs: 10000
# 每次请求的 HTTP 读取超时时间(毫秒)。
readTimeoutMs: 30000
# 可选的每次下载硬性超时时间(秒)。0 表示禁用上限。
perDownloadTimeoutSec: 0
# 瞬态 HTTP 错误(403/429/5xx)的重试行为
maxRetries: 3
# 重试之间的指数退避基础值和最大延迟(毫秒)
backoffBaseMs: 500
backoffMaxMs: 5000
# 限制每主机的并发下载数,以避免 429 错误并提高稳定性
maxPerHost: 3
rollback:
# 在更新插件时保留前一版本的备份,并在插件加载失败时自动回滚(实验性功能!)
enabled: false
# 每个插件保留的旧版本最大数量(0 = 无限制)
maxBackups: 3
# 当在日志中匹配到以下不区分大小写的正则表达式模式时触发回滚。
filters:
- "Unsupported API version"
- "Could not load plugin"
- "Error occurred while enabling"
- "Unsupported MC version"
- "You are running an unsupported server version"
# 插件列表配置
# 编辑此文件夹中生成的 list.yml。格式如下:
# {保存文件名}: {插件链接}
#
# 示例 list.yml 模板:https://github.com/NewAmazingPVP/AutoUpdatePlugins/blob/main/list.yml
# 示例:
# ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
# Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"
# EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"
#
# 支持的来源:GitHub (Releases & Actions)、Jenkins、SpigotMC (Spiget)、dev.bukkit、Modrinth、Hangar、
# BusyBiscuit、blob.build、Guizhanss v2、MineBBS、CurseForge、本地文件路径、本地脚本,以及带有直接 .jar 链接的通用页面。
#
# 提示:
# - 选择资产:追加 [N] 以选择第 N 个资产,或使用 ?get=<regex> 按文件名匹配。
# - GitHub Actions ZIP 包:使用 ?artifact=2(或 ?index=/ ?zip=)选择特定的构建,默认为第一个。
# - 预发布版本:设置 behavior.allowPreRelease: true 或在 GitHub 链接后追加 ?prerelease=true。
# - 频道标志:?beta=true, ?alpha=true, ?latest=true,或为 Hangar 使用 ?channel=Alpha/Beta。
# - Modrinth/Hangar 遵循相同的标志 (?alpha, ?beta, ?latest) 以在需要时选择非发布版构建。
# - 强制从 GitHub 源码构建:在 GitHub 仓库 URL 后追加 ?autobuild=true。
安全与恢复
behavior.zipFileCheck: 在 .jar 下载文件从归档文件中解压并到达 plugins
目录之前,对其有效性进行验证。
behavior.ignoreDuplicates: 如果传入的 jar 与已安装的校验和匹配,则跳过部署,避免不必要的
重启。
rollback.*: 快照上一个 jar 文件,保留轮换历史记录,并在控制台输出
匹配配置的故障模式时自动恢复。
高级选择器速查表
| Flag / Selector |
Effect |
Providers |
?get=<regex> |
选择文件名匹配正则表达式的资源 |
GitHub, Jenkins, Modrinth, etc |
[N] |
选择第 N 个资源(索引从 1 开始) |
GitHub Releases, Jenkins |
?artifact=2 / ?index= |
选择第 N 个 GitHub Actions 产物(默认为 1) |
GitHub Actions |
?prerelease=true |
无论稳定性级别如何,都安装最新的构建版本 |
GitHub, Modrinth, Hangar |
?alpha=true / ?beta=true |
优先使用该渠道;如果没有匹配的构建版本,则回退到较新的发布版本 |
GitHub, Modrinth, Hangar |
?latest=true |
与 ?prerelease=true 相同,但旨在实现明确的“始终使用最新版本”行为 |
GitHub, Modrinth, Hangar |
?channel=Alpha / Beta |
固定在 Hangar 的特定渠道 |
Hangar |
?autobuild=true |
当二进制文件缺失时触发 Gradle/Maven 源码构建 |
GitHub |
关键选项说明
updates.schedule.cron + timezone - 设置后,cron 表达式将覆盖 interval/bootTime。
updates.key - 用于访问 Releases/Actions 并提高速率限制的 GitHub PAT(尤其适用于在高负载下使用的公共仓库或任何私有仓库)。
http.userAgents - 简单的轮换策略,以避免脆弱的服务端过滤器拦截。
proxy - 完全支持 HTTP/SOCKS 代理。
behavior.autoCompile - 对于 GitHub 仓库:如果没有 release jar(或者分支比上次发布的版本更新,由 branchNewerMonths 决定),该仓库可以从源码构建,使用 Gradle/Maven。
behavior.zipFileCheck - 在安装前打开下载的 jars/zips 以确保它们没有损坏。
behavior.ignoreDuplicates - 如果新 jar 的 MD5 值相同,则跳过替换插件。
behavior.useUpdateFolder - 将新 jar 暂存到服务器的 update/ 目录中,以便进行原子交换。
behavior.restartAfterUpdate - 自动在更新后重启服务器(延迟通过 behavior.restartDelaySec 控制,消息通过 behavior.restartMessage 发送)。
behavior.debug - 详细日志记录开关,也可通过 /aup debug 控制。
rollback - 配置自动快照、保留策略和日志匹配触发器,以实现自我修复更新。
paths - 自定义临时/暂存/输出位置(若无设置则回退到合理的默认值)。
performance - 参见 性能调优指南。
list.yml
一个简单的映射关系:插件显示名称 ➜ 源 URL(+ 可选的选择器)。
# A list of plugins to update.
# Format: <plugin-name>: <download-url>
ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"
EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"
用 # 注释掉一行以暂时禁用该条目。/aup enable 和 /aup disable 命令可为您切换此状态。
可用的选择器
[N] - 从发布页面或 Jenkins 构建页面中选择第 N 个 jar 资源(索引从 1 开始)。例如:
.../Essentials[3]
?get=<regex> - 选择文件名匹配正则表达式的文件。例如:?get=.*(paper|spigot).*\.jar
?artifact=2 - 选择特定的 GitHub Actions 产物(默认为第一个)。
?prerelease=true - 允许预发布版本。
?autobuild=true - 即使存在 jar 资源,也强制在 GitHub 上进行源码构建。
技巧: 组合使用选择器,例如 ...?prerelease=true&get=.*spigot.*\.jar。
计划任务速查表
常见的 cron 表达式(示例使用 America/New_York 时区):
- 每 2 小时:
0 */2 * * *
- 每天凌晨 05:00:
0 5 * * *
- 每周一和周四凌晨 03:30:
30 3 * * 1,4
- 每 15 分钟:
*/15 * * * *
如果 cron 为空,插件将使用间隔时间(分钟)以及初始启动延迟(秒)。
性能调优指南
- Java 21+(虚拟线程): 保持较高的
performance.maxParallel 值(例如 8–16),以处理大量小型产物。
- Java 11+(HTTP/2): 默认吞吐量极佳。如果单个源托管了大部分 jar 包,请调整
maxPerHost。
- Java 8: 如果在下载大文件时看到超时,请增加
readTimeoutMs;如果网络已饱和,请降低 maxParallel。
- 重试机制: 插件会以指数退避方式重试**
maxRetries**次(退避基数 backoffBaseMs → 最大退避时间 backoffMaxMs)。
- 单次下载超时: 设置
perDownloadTimeoutSec 以防止传输卡死;设置为 0 以禁用此功能。
- I/O 路径: 如果可能,请将
tempPath/updatePath 放置在快速的本地存储上。
命令与权限
命令
/update - 触发一次更新运行。
/aup download [names...] - 更新所有插件,或仅更新指定名称的插件。
/aup update [names...] - download 的别名。
/aup stop - 请求停止当前的更新进程。
/aup reload - 重新加载插件配置。
/aup add <name> <link> - 向 list.yml 添加新条目。
/aup remove <name> - 从 list.yml 移除条目。
/aup list [page] - 查看已配置的插件列表。
/aup debug <on|off|toggle|status> - 切换详细日志记录并持久化设置。
/aup enable|disable <name> - 切换条目的启用状态(在 list.yml 中取消/添加注释)。
权限
autoupdateplugins.update - 允许使用 /update。
autoupdateplugins.manage - 允许使用 /aup ... 命令。
提示: 大多数服务器仍需重启才能加载更新后的 jar 文件。该插件负责下载和暂存;
由你决定何时重启(可通过 behavior.restartAfterUpdate 启用自动重启)。
工作原理(底层机制)
- 发现。 对于
list.yml 中的每个条目,插件会检测提供程序(GitHub、Jenkins、SpigotMC 等),并使用你的选择器计算最新匹配的制品。
- 下载(异步)。 文件通过连接池获取;在 Java 11+ 上使用 HTTP/2 客户端;在 Java 21+ 上,当可用时使用虚拟线程调度下载。
- 验证。 可选的 zip 完整性检查和重复检测(
name + size)可避免不必要的写入。
- 暂存与原子替换。 文件先写入 temp 目录,然后原子地移动到 *
update/plugins* 目标位置,确保服务器永远不会处于部分状态。
- 重复执行。 根据你的 interval 或 cron 计划进行,并在临时故障时进行重试/退避。
各来源示例
以下模式仅供参考。 请使用你项目的实际 URL,并根据需要应用选择器。
-
GitHub Releases(选取第 2 个资产,仅限 spigot):
MyPlugin: "https://github.com/Owner/MyPlugin[2]?get=.*spigot.*\\.jar"
-
GitHub Actions(最新的 alpha 制品,回退到源码构建):
MyActionsPlugin: "https://github.com/Owner/MyActionsPlugin/actions?alpha=true&artifact=1"
MyActionsPluginSource: "https://github.com/Owner/MyActionsPlugin?autobuild=true"
-
Jenkins(匹配阴影 jar;使用 [N] 按索引选择):
CoolThing: "https://ci.example.com/job/CoolThing/lastSuccessfulBuild/artifact/?get=.*-all\\.jar"
# 第二个制品
CoolThingAlt: "https://ci.example.com/job/CoolThing/lastSuccessfulBuild/artifact/[2]"
-
SpigotMC(资源页面):
ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
-
dev.bukkit:
Vault: "https://dev.bukkit.org/projects/vault"
-
Modrinth(匹配平台风味,最新的 alpha 构建):
Fancy: "https://modrinth.com/plugin/fancy?alpha=true&get=.*(paper|spigot).*\\.jar"
-
Hangar(快照通道):
HangarThing: "https://hangar.papermc.io/Owner/Project?channel=Alpha&get=.*spigot.*\\.jar"
-
CurseForge(过滤文件名):
CFThing: "https://www.curseforge.com/minecraft/bukkit-plugins/cfthing/files?get=.*release.*\\.jar"
-
通用直接 jar:
DirectJar: "https://downloads.example.com/plugins/DirectJar-1.2.3.jar"
-
本地文件(磁盘上的补丁 jar):
PatchedPlugin: "file:/home/me/builds/PatchedPlugin.jar"
-
本地脚本(构建 jar 并打印路径):
PatchedPlugin: "script:./scripts/build-plugin.sh"
故障排除与常见问题
问:更新了已下载,但服务器没有变化。
答:大多数平台仅在启动时加载 jar 文件。运行后请重启服务器。避免对复杂插件使用热重载工具。
问:GitHub 速率限制 / 无法访问 Actions 制品。
答:在 config.yml → updates.key 中添加 GitHub PAT。对于私有仓库,请确保令牌具有读取 Releases/Actions 制品的权限。
问:选错了文件。
答:添加 ?get=regex 或使用 [N] 来选择资产索引。确认正则表达式转义了点号(例如 \\.jar)。
问:超时或下载缓慢。
答:增加 readTimeoutMs;减少 maxParallel;或设置 perDownloadTimeoutSec 并调整 maxRetries/退避策略。
问:需要预发布版本。
答:使用每链接标志如 ?prerelease=true、?beta=true、?alpha=true 或 ?latest=true(适用于 GitHub、
Modrinth 和 Hangar)。Hangar 也支持 ?channel=Alpha/Beta。如果你希望将其设为默认值,请设置 behavior.allowPreRelease: true。
问:位于企业代理后面。
答:配置 proxy.type/host/port。如果你的代理对 TLS 进行中间人攻击(MITM),请确保 Java 信任库中包含代理 CA。
问:从源码构建未触发。
答:确保 behavior.autoCompile.enable: true 并使用 ?autobuild=true,或者在没有 jar 资产存在时让它自动触发。
服务器必须具有出站网络访问权限。
从源码构建
使用 Maven:
mvn -DskipTests package
构建好的 .jar 将位于 target/ 中。
安全须知
- 优先使用最小权限令牌。对于 GitHub,使用仅限于你需要的仓库且具有足够读取 Releases/Actions 制品权限的 PAT。
- 将第三方下载链接视为不可信:保持
zipFileCheck: true。
- 考虑使用
?get=regex 固定来源,以避免意外切换到平台不兼容的 jar 文件。
贡献、问题与支持
- 错误 / 功能请求: 提交 Issue:
- 欢迎 PR!请保持代码风格一致,并在 PR 描述中包含简要测试计划。
致谢
这是原始的 AutoUpdatePlugins 项目。 社区中有该插件的多个分支;许多
他们的好想法和改进随着时间的推移也被整合到了这里。特别感谢 ApliNi/AutoUpdatePlugins 等项目以及其他贡献者提供的灵感和功能。
许可证
AutoUpdatePlugins 根据 MIT License 授权。详情请参阅 LICENSE。
变更日志快照 (v12.x)
- 扩大了提供程序覆盖范围并改进了选择逻辑 (
[N], ?get=regex, ?prerelease, ?autobuild)。
- HTTP 栈升级(Java 11+ 支持 HTTP/2,Java 21+ 支持虚拟线程)。
- 更好的并行处理、重试/退避以及连接池默认值。
- 保留注释的配置重新生成以及更丰富的调度控制。
AutoUpdatePlugins v12.2.0
Keep your server’s plugins up-to-date - automatically, safely, and across platforms.
TL;DR
Drop in the jar ➜ list the plugins you want ➜ it finds, downloads, validates, and stages updates from a ton of
sources - on a schedule, in parallel, without blocking your main thread.
Table of Contents
Highlights
-
One list, many sources. Pull updates from GitHub Releases/Actions, Jenkins, SpigotMC (Spiget), dev.bukkit,
Modrinth, Hangar, BusyBiscuit, blob.build, Guizhanss v2, MineBBS, CurseForge, or any page with a direct .jar link.
-
Local sources. Point at local jar files or run scripts that output a jar path for custom/patched builds.
-
Smart file selection. Use ?get=<regex>, [N] (pick the N-th asset - works for both GitHub and Jenkins
artifacts), ?artifact=2 for GitHub Actions bundles, ?prerelease=true, ?alpha=true, ?beta=true, ?latest=true,
?channel=Alpha, ?autobuild=true - mix and match to land on the exact build you need.
-
Zero-friction config evolution. New options are auto-added to config.yml without clobbering your comments or
existing values.
-
HTTP flexibility. Add custom headers, rotate User-Agents, and route through proxies when needed.
-
Performance built-in.
- Fully async downloads; no main-thread stalls.
- Java 11+ HTTP/2 client for modern, non-blocking transfers.
- Java 21+ virtual threads for ultra-lightweight concurrency.
- Connection pooling, parallel downloads, and retry with exponential backoff.
-
Flexible scheduling. Interval + boot delay or cron with timezone support.
-
Cross-platform. Works on Spigot, Paper, Folia, Velocity, BungeeCord.
-
Safe updates. Download ➜ validate ➜ atomic replace, staged through temp/update paths.
-
Integrity + dedupe. Optional zip integrity checks and MD5 comparison skip corrupted or unchanged downloads.
-
Rollback safety net. Snapshot the previous jar and auto-restore if the new build fails to start.
Supported Sources & Platforms
Download Sources
| Source |
Release/Build Discovery |
Notes / Selectors Supported |
| GitHub |
Releases & Actions |
[N], ?artifact=2, ?get=regex, ?prerelease=true, ?alpha=true, ?beta=true, ?latest=true, ?autobuild=true |
| Jenkins |
Latest build artifacts |
[N], ?get=regex |
| SpigotMC (Spiget) |
Resource page URL |
Auto-resolves latest |
| dev.bukkit |
Project page |
Auto-resolves latest |
| Modrinth |
Project/version URL |
?get=regex, ?alpha=true, ?beta=true, ?latest=true |
| Hangar |
Project/releases |
?get=regex, ?alpha=true, ?beta=true, ?latest=true, ?channel=Alpha |
| BusyBiscuit |
Project index |
Auto-resolves |
| blob.build |
Build artifacts |
?get=regex |
| Guizhanss v2 |
Project index |
Auto-resolves |
| MineBBS |
Resource page |
Auto-resolves |
| CurseForge |
Project/files |
?get=regex |
| Generic |
Direct .jar link |
Exact file URL |
| Local file |
Local path |
file:, local:, path:, or absolute/relative path |
| Local script |
Script stdout path |
script: or exec: (script prints jar path to stdout) |
Note: GitHub and Jenkins links both accept [N] to pick the N-th artifact on their release/build pages (
1-indexed).
Tip: You can pass just the project root URL for most sources (e.g., a GitHub repo or Spigot resource page) and
let AutoUpdatePlugins choose the latest artifact. Add selectors for precision.
Server Platforms
- Spigot, Paper, Folia
- Velocity, BungeeCord
Minecraft & Java
- Minecraft: 1.8 → Latest
- Java: 8+ (uses advanced features automatically on 11+ and 21+)
Requirements
Installation
- Download the latest
.jar from Spigot.
- Place it into your server’s
plugins/ directory.
- Start the server to generate default config files.
- Edit
plugins/AutoUpdatePlugins/config.yml and plugins/AutoUpdatePlugins/list.yml.
- Run
/update or /aup update (or restart) to kick off the first check.
Velocity / BungeeCord: Same process - drop the jar in plugins/, configure, then trigger an update run.
Quick Start
-
Add a few entries to list.yml:
ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"
EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"
-
Leave updates.interval at the default (every 120 minutes), or set a cron schedule.
-
Optional: Add a GitHub token in config.yml to avoid rate limits.
-
Trigger a run:
/update
-
New jars are staged atomically in your plugins folder (using temp/update paths under the hood). Restart the
server to load the updated jars.
Configuration
config.yml
The plugin adds new options automatically without overwriting your comments. Below is the full schema with
defaults and notes.
################################################################################
# AutoUpdatePlugins - Main Configuration
################################################################################
updates:
# How often to run plugin updates (minutes). Default: 120 (every 2 hours)
interval: 120
# Delay after server startup (seconds) before the first run. Default: 50
bootTime: 50
# Schedule (experimental): Use a cron expression to control exactly when
# updates run. When set, this overrides both interval and bootTime.
# Examples:
# Every day at 03:30: "30 3 * * *"
# Every 15 minutes: "*/15 * * * *"
# At 5 past every hour on weekdays: "5 * * * 1-5"
schedule:
cron: "" # Cron expression (UNIX 5-field). Leave blank to disable.
timezone: "UTC" # Timezone for the cron schedule, e.g. "America/New_York"
# Optional GitHub personal access token (PAT). Strongly recommended if you use
# many GitHub links to avoid API rate-limits when listing releases/artifacts.
# Scope: public_repo is enough for public repos.
# Generate a token: https://github.com/settings/tokens
key:
# HTTP configuration (optional)
http:
# If blank, a rotating pool of realistic User-Agents will be used.
userAgent: ""
# Extra request headers added to every request. Only add if you know you need it.
headers: [ ]
# Verify TLS certificates (set to false to trust all; only if you must)
sslVerify: true
# Optional pool of User-Agents; the plugin will rotate between them to avoid
# strict CDNs blocking automation.
userAgents:
- { ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" }
- { ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15" }
- { ua: "Mozilla/5.0 (X11; Linux x86_64; rv:126.0) Gecko/20100101 Firefox/126.0" }
# Proxy configuration (optional)
proxy:
type: "NONE" # HTTP | SOCKS | (anything else = disabled)
host: "proxy.example"
port: 8080
# Behavior toggles
behavior:
useUpdateFolder: true
# Open downloaded .jar/.zip to ensure integrity before install (recommended)
zipFileCheck: true
# Skip replacing an existing plugin if the new jar has the same MD5
ignoreDuplicates: true
# Allow GitHub/Modrinth/Hangar pre-releases by default for release queries.
allowPreRelease: false
# Enable source-build fallback for GitHub repositories.
autoCompile:
enable: false
# Build when a release has no .jar asset (zip-only)
whenNoJarAsset: true
# Build from source if default branch is newer than latest (pre)release by N months
branchNewerMonths: 6
# Verbose debug logging. Toggle with /aup debug on|off
debug: false
# Restart the server/proxy automatically after updates.
restartAfterUpdate: false
# Delay in seconds before restarting after updates.
restartDelaySec: 5
# Broadcast message before restarting (supports {delay}).
restartMessage: "Server restarting to apply updates."
# Optional custom paths
paths:
tempPath: ''
updatePath: ''
filePath: ''
rollbackPath: ''
# Performance and reliability options
performance:
# Maximum parallel downloads. Higher is faster but uses more IO/CPU.
# If set above CPU cores, it is clamped internally.
maxParallel: 4
# HTTP connect timeout in milliseconds per request.
connectTimeoutMs: 10000
# HTTP read timeout in milliseconds per request.
readTimeoutMs: 30000
# Optional per-download hard timeout in seconds. 0 disables the cap.
perDownloadTimeoutSec: 0
# Retry behavior for transient HTTP errors (403/429/5xx)
maxRetries: 3
# Exponential backoff base and max delay in milliseconds between retries
backoffBaseMs: 500
backoffMaxMs: 5000
# Limit concurrent downloads per host to avoid 429s and improve stability
maxPerHost: 3
rollback:
# Keep a backup of the previous version when updating a plugin and automatically revert back on plugin load failure (experimental!)
enabled: false
# Maximum number of old versions to keep per plugin (0 = unlimited)
maxBackups: 3
# Case-insensitive regex patterns that trigger rollback when matched in logs.
filters:
- "Unsupported API version"
- "Could not load plugin"
- "Error occurred while enabling"
- "Unsupported MC version"
- "You are running an unsupported server version"
# Plugins List Configuration
# Edit the generated list.yml in this folder. Format:
# {FileSaveName}: {link.to.plugin}
#
# Example list.yml template: https://github.com/NewAmazingPVP/AutoUpdatePlugins/blob/main/list.yml
# Examples:
# ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
# Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"
# EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"
#
# Supported sources: GitHub (Releases & Actions), Jenkins, SpigotMC (Spiget), dev.bukkit, Modrinth, Hangar,
# BusyBiscuit, blob.build, Guizhanss v2, MineBBS, CurseForge, local file paths, local scripts, plus generic pages with direct .jar links.
#
# Tips:
# - Select assets: append [N] to pick the Nth asset or use ?get=<regex> to match by filename.
# - GitHub Actions ZIPs: use ?artifact=2 (or ?index=/ ?zip=) to pick a specific build, default is the first.
# - Pre-releases: set behavior.allowPreRelease: true or append ?prerelease=true on a GitHub link.
# - Channel flags: ?beta=true, ?alpha=true, ?latest=true, or ?channel=Alpha/Beta for Hangar.
# - Modrinth/Hangar obey the same flags (?alpha, ?beta, ?latest) to pick non-release builds when desired.
# - Force source build from GitHub: append ?autobuild=true to a GitHub repo URL.
Safety & Recovery
behavior.zipFileCheck: validates .jar downloads extracted from archives before they ever reach the plugins
directory.
behavior.ignoreDuplicates: skips deployment if the incoming jar matches the installed checksum, avoiding pointless
restarts.
rollback.*: snapshots the previous jar, keeps a rotating history, and restores automatically when console output
matches the configured failure patterns.
Advanced Selectors Cheat Sheet
| Flag / Selector |
Effect |
Providers |
?get=<regex> |
Picks assets whose filename matches a regex |
GitHub, Jenkins, Modrinth, etc |
[N] |
Chooses the N‑th asset (1-indexed) |
GitHub Releases, Jenkins |
?artifact=2 / ?index= |
Chooses the N‑th GitHub Actions artifact (defaults to 1) |
GitHub Actions |
?prerelease=true |
Install the newest build regardless of stability tier |
GitHub, Modrinth, Hangar |
?alpha=true / ?beta=true |
Prefer that channel while falling back to newer releases if no matching build exists |
GitHub, Modrinth, Hangar |
?latest=true |
Same as ?prerelease=true, but intended for explicit "always newest" behaviour |
GitHub, Modrinth, Hangar |
?channel=Alpha / Beta |
Stick to a specific Hangar channel |
Hangar |
?autobuild=true |
Trigger Gradle/Maven source builds when binaries are missing |
GitHub |
Key options explained
updates.schedule.cron + timezone - When set, cron overrides interval/bootTime.
updates.key - GitHub PAT for Releases/Actions access and higher rate limits (especially useful for public repos
under heavy use or any private repos).
http.userAgents - Simple rotation to avoid brittle server-side filters.
proxy - Full support for HTTP/SOCKS proxies.
behavior.autoCompile - For GitHub repos: if there’s no release jar (or if the branch is newer than the last
release by branchNewerMonths), the repo can be built from source using Gradle/Maven.
behavior.zipFileCheck - Open downloaded jars/zips to ensure they aren't corrupt before install.
behavior.ignoreDuplicates - Skip replacing a plugin if the new jar has the same MD5.
behavior.useUpdateFolder - Stage new jars in the server’s update/ directory for atomic swaps.
behavior.restartAfterUpdate - Automatically restart after updates (delay via behavior.restartDelaySec, message
via behavior.restartMessage).
behavior.debug - Verbose logging toggle, also controllable via /aup debug.
rollback - Configure automatic snapshots, retention, and log-match triggers for self-healing updates.
paths - Customize temp/staging/output locations (falls back to sane defaults).
performance - See Performance Tuning Guide.
list.yml
A simple mapping of plugin display name ➜ source URL (+ optional selectors).
# A list of plugins to update.
# Format: <plugin-name>: <download-url>
ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"
EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"
Comment out a line with # to temporarily disable an entry. The /aup enable and /aup disable commands toggle this
for you.
Selectors you can use
[N] - Select the N-th jar asset (1-indexed) from a release or Jenkins build page. Example:
.../Essentials[3]
?get=<regex> - Choose files whose names match a regex. Example: ?get=.*(paper|spigot).*\.jar
?artifact=2 - Pick a specific GitHub Actions artifact (defaults to the first).
?prerelease=true - Permit pre-releases.
?autobuild=true - Force a source build on GitHub even if a jar asset exists.
Pro tip: Combine selectors, e.g. ...?prerelease=true&get=.*spigot.*\.jar.
Scheduling Cheat Sheet
Common cron expressions (with examples using America/New_York):
- Every 2 hours:
0 */2 * * *
- Every day at 05:00:
0 5 * * *
- Every Monday & Thursday at 03:30:
30 3 * * 1,4
- Every 15 minutes:
*/15 * * * *
If cron is empty, the plugin uses interval (minutes) with an initial bootTime delay (seconds).
Performance Tuning Guide
- Java 21+ (virtual threads): Keep
performance.maxParallel higher (e.g., 8–16) for many small artifacts.
- Java 11+ (HTTP/2): Great default throughput. Tune
maxPerHost if a single origin hosts most of your jars.
- Java 8: Increase
readTimeoutMs if you see timeouts on large downloads; lower maxParallel if network is
saturated.
- Retries: The plugin retries
maxRetries times with exponential backoff (backoffBaseMs → backoffMaxMs).
- Per-download timeout: Set
perDownloadTimeoutSec to protect against stuck transfers; keep 0 to disable.
- I/O Paths: Put
tempPath/updatePath on fast local storage if possible.
Commands & Permissions
Commands
/update - Trigger an update run.
/aup download [names...] - Update all, or only the named plugins.
/aup update [names...] - Alias of download.
/aup stop - Request to stop the current updating process.
/aup reload - Reload the plugin configuration.
/aup add <name> <link> - Add a new entry to list.yml.
/aup remove <name> - Remove an entry from list.yml.
/aup list [page] - View the configured plugin list.
/aup debug <on|off|toggle|status> - Toggle verbose logging and persist the setting.
/aup enable|disable <name> - Toggle an entry (comment/uncomment in list.yml).
Permissions
autoupdateplugins.update - Allows /update.
autoupdateplugins.manage - Allows /aup ... commands.
Heads-up: Most servers still require a restart to load updated jars. The plugin handles download & staging;
you decide when to reboot (auto-restart available via behavior.restartAfterUpdate).
How It Works (Under the Hood)
- Discovery. For each entry in
list.yml, the plugin detects the provider (GitHub, Jenkins, SpigotMC, etc.) and
computes the latest matching artifact using your selectors.
- Download (async). Files are fetched with pooled connections; on Java 11+ it uses the HTTP/2 client; on Java 21+
it schedules downloads on virtual threads when available.
- Validation. Optional zip integrity checks and duplicate detection (
name + size) avoid unnecessary writes.
- Staging & Atomic Replace. Files are written to a temp directory, then moved atomically into the *
update/plugins* target so the server is never left in a partial state.
- Repeat. According to your interval or cron schedule, with retries/backoff on transient failures.
Examples for Every Source
Patterns below are illustrative. Use your project’s actual URLs and apply selectors as needed.
-
GitHub Releases (pick 2nd asset, spigot-only):
MyPlugin: "https://github.com/Owner/MyPlugin[2]?get=.*spigot.*\\.jar"
-
GitHub Actions (latest alpha artifact, fallback to source build):
MyActionsPlugin: "https://github.com/Owner/MyActionsPlugin/actions?alpha=true&artifact=1"
MyActionsPluginSource: "https://github.com/Owner/MyActionsPlugin?autobuild=true"
-
Jenkins (match shaded jar; select by index with [N]):
CoolThing: "https://ci.example.com/job/CoolThing/lastSuccessfulBuild/artifact/?get=.*-all\\.jar"
# second artifact
CoolThingAlt: "https://ci.example.com/job/CoolThing/lastSuccessfulBuild/artifact/[2]"
-
SpigotMC (resource page):
ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"
-
dev.bukkit:
Vault: "https://dev.bukkit.org/projects/vault"
-
Modrinth (match platform flavor, latest alpha build):
Fancy: "https://modrinth.com/plugin/fancy?alpha=true&get=.*(paper|spigot).*\\.jar"
-
Hangar (snapshot channel):
HangarThing: "https://hangar.papermc.io/Owner/Project?channel=Alpha&get=.*spigot.*\\.jar"
-
CurseForge (filter file name):
CFThing: "https://www.curseforge.com/minecraft/bukkit-plugins/cfthing/files?get=.*release.*\\.jar"
-
Generic direct jar:
DirectJar: "https://downloads.example.com/plugins/DirectJar-1.2.3.jar"
-
Local file (patched jar on disk):
PatchedPlugin: "file:/home/me/builds/PatchedPlugin.jar"
-
Local script (builds jar and prints path):
PatchedPlugin: "script:./scripts/build-plugin.sh"
Troubleshooting & FAQ
Q: Updates downloaded, but server didn’t change.
A: Most platforms load jars only at startup. Restart your server after a run. Avoid hot-reloaders for complex
plugins.
Q: GitHub rate-limited / cannot access Actions artifacts.
A: Add a GitHub PAT in config.yml → updates.key. For private repos, ensure the token has read access to
Releases/Actions artifacts.
Q: Wrong file selected.
A: Add a ?get=regex or use [N] to pick an asset index. Confirm the regex escapes dots (e.g., \\.jar).
Q: Timeouts or slow downloads.
A: Increase readTimeoutMs; decrease maxParallel; or set perDownloadTimeoutSec and tune maxRetries/backoff.
Q: Need pre-releases.
A: Use per-link flags like ?prerelease=true, ?beta=true, ?alpha=true, or ?latest=true (works on GitHub,
Modrinth, and Hangar). Hangar also respects ?channel=Alpha/Beta. Set behavior.allowPreRelease: true if you want
this to be the default.
Q: Behind a corporate proxy.
A: Configure proxy.type/host/port. If your proxy MITM-s TLS, ensure the Java trust store has the proxy CA.
Q: Build from source didn’t trigger.
A: Ensure behavior.autoCompile.enable: true and use ?autobuild=true or let it kick in when no jar asset exists. The
server must have outbound network access.
Building from Source
Use Maven:
mvn -DskipTests package
The built .jar will be in target/.
Security Notes
- Prefer least-privileged tokens. For GitHub, use a PAT limited to the repos you need with read permissions
sufficient for Releases/Actions artifacts.
- Treat third-party download links as untrusted: keep
zipFileCheck: true.
- Consider pinning sources with
?get=regex to avoid accidentally switching to platform-incompatible jars.
Contributing, Issues & Support
- Bugs / Feature requests: Open an issue:
- PRs welcome! Please keep code style consistent and include a brief test plan in your PR description.
Acknowledgements
This is the original AutoUpdatePlugins project. There are several forks of this plugin in the community; many of
their good ideas and improvements have been incorporated here over time as well. Thanks especially to contributors and
projects like ApliNi/AutoUpdatePlugins and others for inspiration and features.
License
AutoUpdatePlugins is licensed under the MIT License. See LICENSE for details.
Changelog Snapshot (v12.x)
- Expanded provider coverage and smarter selection (
[N], ?get=regex, ?prerelease, ?autobuild).
- HTTP stack upgrades (HTTP/2 on Java 11+, virtual threads on Java 21+).
- Better parallelism, retry/backoff, and connection pooling defaults.
- Comment-preserving config regeneration and richer scheduling controls.
评论 0
登录后参与评分
还没有评论,来抢沙发吧