# **AutoUpdatePlugins v12.1.2**
*保持服务器插件的最新状态——自动、安全，且跨平台。*
[](https://www.spigotmc.org/resources/autoupdateplugins.109683/)
-1F6FEB)
> **TL;DR**
> 丢入jar ➜ 列出您想要更新的插件 ➜ 它会从大量来源查找、下载、验证和暂存更新——按照计划、并行进行，而不会阻塞您的主线程。
---
## Highlights
* **一个列表，多个来源。** 从GitHub Releases/Actions、Jenkins、SpigotMC (Spiget)、dev.bukkit、Modrinth、Hangar、BusyBiscuit、blob.build、Guizhanss v2、MineBBS、CurseForge或任何带有直接`.jar`链接的页面拉取更新。
* **智能文件选择。** 使用`?get=
# AutoUpdatePlugins
`、`[N]`（选择第N个资源——适用于GitHub和Jenkins artifacts）、`?prerelease=true`、`?autobuild=true`（强制源构建）来精确选择您想要的目标资源。
* **零摩擦的配置演进。** 新选项会**自动添加到** `config.yml` 中，而不会覆盖您的注释或现有值。
* **HTTP灵活性。** 添加自定义标头、轮换User-Agent，以及在需要时通过代理路由。
* **内置性能。**
* 完全**异步**下载；不会阻塞主线程。
* **Java 11+ HTTP/2** 客户端，用于现代、非阻塞传输。
* **Java 21+ 虚拟线程** 用于超轻量级并发。
* **连接池**、**并行下载**和**使用指数退避重试**。
* **灵活的调度。** 间隔 + 启动延迟 *或* 使用时区支持的cron。
* **跨平台。** 适用于**Spigot**、**Paper**、**Folia**、**Velocity**、**BungeeCord**。
* **安全更新。** 下载 ➜ 验证 ➜ 原子替换，通过临时/更新路径暂存。
* **完整性 + 消除重复。** 可选的zip完整性检查和MD5比较跳过损坏或未修改的下载。
---
## 支持的来源和平台
### 下载来源
| 来源 | 发布/构建发现 | 支持的说明符/选择器 |
| --------------------- | ----------------------- | ---------------------------------------------------------- |
| **GitHub** | Releases & Actions | `[N]`, `?get=regex`, `?prerelease=true`, `?autobuild=true` |
| **Jenkins** | 最新构建 artifacts | `[N]`, `?get=regex` |
| **SpigotMC (Spiget)** | 资源页面URL | 自动解析最新 |
| **dev.bukkit** | 项目页面 | 自动解析最新 |
| **Modrinth** | 项目/版本URL | `?get=regex` |
| **Hangar** | 项目/版本 | `?get=regex` |
| **BusyBiscuit** | 项目索引 | 自动解析 |
| **blob.build** | 构建 artifacts | `?get=regex` |
| **Guizhanss v2** | 项目索引 | 自动解析 |
| **MineBBS** | 资源页面 | 自动解析 |
| **CurseForge** | 项目/文件 | `?get=regex` |
| **通用** | 直接`.jar`链接 | 确切的文件URL |
> **注意:** GitHub和Jenkins链接都接受`[N]`来选择他们在发布/构建页面上的**N-th** artifacts (从1开始计数)。
> **提示:** 您可以传递大多数资源（例如，GitHub源仓库或Spigot资源页面）的**项目根URL**，让AutoUpdatePlugins选择最新的artifacts。添加选择器以获得精度。
### 服务器平台
* **Spigot**, **Paper**, **Folia**
* **Velocity**, **BungeeCord**
### Minecraft & Java
* **Minecraft:** 1.8 → Latest
* **Java:** 8+ (自动在11+和21+上使用高级特性)
---
## 要求
* **Java 8或更高版本。**
* 使用Java 11+ HTTP/2 客户端，当可用时。
* 使用Java 21+ 虚拟线程，当可用时。
* **网络访问**，用于源构建（Gradle/Maven包装器或系统`gradle`/`mvn`，如果使用的话）。
---
## 安装
1. 从 **[Spigot](https://www.spigotmc.org/resources/autoupdateplugins.109683/)** 下载最新版的`.jar`。
2. 将其放入服务器的 **`plugins/`** 目录中。
3. 启动服务器以生成默认的配置文件。
4. 编辑 **`plugins/AutoUpdatePlugins/config.yml`** 和 **`plugins/AutoUpdatePlugins/list.yml`**。
5. 运行 **`/update`** 或 **`/aup update`**（或者重启）来启动第一次检查。
> **Velocity / BungeeCord:** 相同的过程 — 将jar 放入 `plugins/`，配置，然后触发一次更新运行。
---
## 快速开始
1. 在`list.yml`中添加几个条目：
```yaml
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]"
```
2. 将`updates.interval`设置为默认值（每120分钟），或者设置cron计划。
3. 可选：在`config.yml`中添加GitHub令牌，以避免速率限制。
4. 触发一次运行：
```
/update
```
5. 新的jar文件将以原子方式储存在您的插件文件夹中（底层使用temp/update路径）。**重启**服务器以加载更新的 jar 文件。
---
## 配置
### `config.yml`
> 插件会**自动添加新的选项**，而不会覆盖您的注释。 下面是带有默认值和注释的完整模式。
```yaml
################################################################################
# AutoUpdatePlugins — 主配置
################################################################################
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预发布版本
allowPreRelease: false
# 启用GitHub仓库的源代码构建回退
autoCompile:
enable: false
# 当发布没有.jar资产时构建
whenNoJarAsset: false
# 如果分支比最后一个（预）版本更新了N个月，则从源代码构建
branchNewerMonths: 6
# 详细的调试日志记录。 使用/aup debug on|off切换
debug: false
# 可选自定义路径
paths:
tempPath: ''
updatePath: ''
filePath: ''
# 性能和可靠性选项
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
# 插件列表配置
# 编辑此文件夹中生成的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= 以通过文件名匹配
# - 预发布版: 将 behavior.allowPreRelease: true 设置为 true 或在 GitHub 链接末尾附加 ?prerelease=true。
# - 强制从 GitHub 构建源代码：将 ?autobuild=true 添加到 GitHub 仓库 URL。
```
**关键选项说明**
* **`updates.schedule.cron` + `timezone`** — 设置后，cron **覆盖** `interval`/`bootTime`。
* **`updates.key`** — GitHub PAT 用于 Releases/Actions 访问和更高的速率限制（尤其适用于使用频繁的公共仓库或任何私有仓库）。
* **`http.userAgents`** — 简单的轮换，避免脆弱的服务器端过滤器。
* **`proxy`** — 对 HTTP/SOCKS 代理的全面支持。
* **`behavior.autoCompile`** — 对于 GitHub 仓库：如果不存在发布 jar（或分支比最后一个预发布版本更新），则可以 **从源构建**。
* **`behavior.zipFileCheck`** — 打开下载的 jar/zip 以确保它们未损坏后再安装。
* **`behavior.ignoreDuplicates`** — 如果新 jar 具有相同的 MD5，则跳过替换插件。
* **`behavior.useUpdateFolder`** — 将新的 jar 暂存于 `update/` 目录中，以便进行原子性交换。
* **`behavior.debug`** — 详细日志记录开关，也可以通过 `/aup debug` 控制。
* **`paths`** — 自定义 temp/暂存/输出位置（默认为合理值）。
* **`performance`** — 参见 [性能优化指南](#performance-tuning-guide)
---
### `list.yml`
一个简单的**插件显示名称 ➜ 源 URL (+ 可选选择器)** 的映射。
```yaml
# 要更新的插件列表。
# 格式：<插件名称>: <下载网址>
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]`** — 选择资源的**N-th** artifacts (从1开始计数)。 例如： `.../Essentials[3]`
* **`?get=`** — 选择文件名匹配正则表达式的文件。 例如: `?get=.*(paper|spigot).*\.jar`
* **`?prerelease=true`** — 允许预发布版本。
* **`?autobuild=true`** — 即使存在 jar asset，也强制从源代码构建 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 为空，插件将使用 **`interval`** (分钟) 带有初始 **`bootTime`** 延迟 (秒)。
---
### 性能调优指南
* **Java 21+ (虚拟线程):** 保持 `performance.maxParallel` 较高（例如 8-16），以便于许多小 artifacts。
* **Java 11+ (HTTP/2):** 默认的良好吞吐量。 如果单个来源托管了您的所有 jars，请调整 `maxPerHost`。
* **Java 8:** 增加 `readTimeoutMs`，如果看到大型下载超时; 如果网络饱和，请降低 `maxParallel`。
* **重试:** 插件会重试最大 `maxRetries` 次，并使用指数退避 (`backoffBaseMs` → `backoffMaxMs`)。
* **每个下载的超时:** 设置 `perDownloadTimeoutSec` 以防止卡住的传输; 保持 `0` 以禁用。
* **I/O 路径:** 如果可能，将 `tempPath`/`updatePath` 放置在快速本地存储上。
---
## 问题排查和常见问题解答
**Q: 下载后，服务器没有更改。**
A: 大多数平台仅在启动时加载 jar。 在运行后**重启**您的服务器。 避免对复杂插件使用热重载器。
**Q: GitHub 速率限制 / 无法访问 Actions artifact。**
A: 在 `config.yml` → `updates.key` 中添加 **GitHub PAT**。 对于私有仓库，请确保令牌具有读取 Releases/Actions artifact 的权限。
**Q: 选择了错误的文件。**
A: 添加 **`?get=regex`** 或使用 **`[N]`** 选择一个资产。 确认正则表达式转义了点（例如，`\\.jar`）。
**Q: 超时或下载速度慢。**
A: 增加 `readTimeoutMs`；降低 `maxParallel`；或设置 `perDownloadTimeoutSec` 并调整 `maxRetries`/退避。
**Q: 需要预发布版本。**
A: 在 URL 末尾添加 `?prerelease=true`（并确保 `behavior.allowPreRelease: true` 如果您希望全局允许），
**Q: 在企业代理之后。**
A: 配置 `proxy.type/host/port`。 如果您的代理进行 MITM TLS，请确保 Java 信任库具有代理 CA。
**Q: 源代码构建没有触发。**
A: 确保 `behavior.autoCompile.enable: true` 并使用 `?autobuild=true` 或在不存在 jar asset 时让其触发。 服务器必须具有出站网络访问权限。
---
## 从源代码构建
使用 **Maven:**
```bash
mvn -DskipTests package
```
构建的 `.jar` 将在 `target/` 中。
---
## 安全注意事项
* 优先使用 **最小权限令牌**。 对于 GitHub， 使用限制为需要来源并具有进行 Releases/Actions artifact 权限的 PAT。
* 将第三方下载链接视为不可信：保持 `zipFileCheck: true`。
* 考虑使用 `?get=regex` 固定来源，以避免意外切换到平台不兼容的 jar。
---
## 贡献、问题和支持
* **错误/功能请求:** 打开一个问题:
[https://github.com/NewAmazingPVP/AutoUpdatePlugins/issues](https://github.com/NewAmazingPVP/AutoUpdatePlugins/issues)
* 欢迎 PR! 请保持代码风格一致，并在 PR 描述中包含简要的测试计划。
---
## 许可证
AutoUpdatePlugins 使用 **MIT 许可证**。 参见 **`LICENSE`** 的详细信息。
---
### 变更日志快照（v12.x）
* 扩展了提供者覆盖范围和更智能的选择 (`[N]`, `?get=regex`, `?prerelease`, `?autobuild`)。
* HTTP 堆栈升级（Java 11+ 中的 HTTP/2，Java 21+ 中的虚拟线程）。
* 更好的并行性、重试/退避和连接池默认设置。
* 保留注释的配置再生和更丰富的调度控制。
---