PaperMC 服务器 AI 运维

采用“安全优先”原则的 AI 托管式 PaperMC Minecraft 服务器运维方案。

适用场景

当您需要执行以下操作时，请使用本技能：

• 管理 PaperMC 服务器生命周期（状态、日志、重启）
• 创建备份（世界存档、插件、PaperMC jar 文件）
• 安全地安装或更新插件
• 升级 PaperMC 服务端版本
• 监控服务器健康状况并诊断问题
• 智能插件升级与风险评估（v2.0 新增）

运行要求

• 基于 systemd 的 Linux 系统
• Java 21+（ARM 架构推荐使用 Zulu JDK）
• Python 3.10+
• 已部署 PaperMC 服务端

快速上手

1. 配置

编辑各脚本中的路径配置：

# 在 manage_server.py、plugin_manager.py、update_paper.py 中修改
SERVER_DIR = Path("/path/to/your/papermc-server")

2. 查看状态

python3 manage_server.py status

3. 创建备份

python3 manage_server.py backup

核心脚本

manage_server.py

服务端生命周期管理：

python3 manage_server.py status          # 服务状态
python3 manage_server.py logs -n 50      # 查看日志
python3 manage_server.py backup          # 备份世界存档
python3 manage_server.py restart         # 安全重启

plugin_manager.py

插件管理操作：

python3 plugin_manager.py list                           # 列出已安装插件
python3 plugin_manager.py backup            # 备份指定插件
python3 plugin_manager.py install-url  --filename 

update_paper.py

PaperMC 版本更新：

python3 update_paper.py backup-jar                    # 备份当前 jar 文件
python3 update_paper.py update-from-url 

plugin_upgrade_framework.py（v2.0 新增）

具备风险评估能力的智能插件升级框架：

# 升级指定插件（方法一）
python3 plugin_upgrade_framework.py --plugin ViaVersion --version 5.8.0

# 扫描可升级插件候选列表（方法二）
python3 plugin_upgrade_framework.py --method 2 --scan-limit 20

# 运行示例脚本
python3 upgrade_examples.py

安全规范

❌ 禁止直接执行命令

• kill、kill -9
• rm -rf
• systemctl stop/restart
• 直接覆盖文件

✅ 必须通过脚本执行

所有操作均需经由已批准的 Python 脚本完成。

📦 备份先行策略

在执行任何高风险操作前，必须完成以下步骤：

1. 运行备份命令
2. 确认备份已成功生成
3. 再执行变更操作

插件升级框架（v2.0 新增）

本技能基于 ViaVersion 5.7.2 → 5.8.0 升级实践（2026-03-28），新增智能插件升级框架。

核心升级方法

方法一：指定插件升级

全自动升级指定插件：

from plugin_upgrade_framework import PluginUpgradeFramework

framework = PluginUpgradeFramework()
result = framework.method1_specific_plugin_upgrade("ViaVersion", "5.8.0")

方法二：扫描并评估升级项

适用于周期性维护与批量升级规划：

result = framework.method2_scan_and_assess_upgrades(limit=20)

风险评估逻辑

Hangar 代理配置

如遇代理问题，请配置 NO_PROXY：

export NO_PROXY="localhost,127.0.0.1,192.168.8.165,hangar.papermc.io,papermc.io,hangarcdn.papermc.io"

下载 URL 模式

Hangar 插件下载地址遵循如下格式：

https://hangarcdn.papermc.io/plugins/{plugin}/{plugin}/versions/{version}/PAPER/{plugin}-{version}.jar

升级后验证步骤

1. 检查服务器日志是否存在错误
2. 确认插件加载成功提示
3. 测试核心功能是否正常
4. 监控服务器性能指标
5. 确保回滚方案就绪

ViaVersion 升级实践

详见 viaversion_upgrade_report.json，其中包含 ViaVersion 5.7.2 → 5.8.0 成功升级的完整记录，涵盖：

• 代理问题解决过程
• 风险评估验证结果
• 完整升级流程
• 经验总结与改进点

健康监测

bash scripts/health_check.sh

检测内容包括：

• 服务状态
• 日志错误
• 插件数量
• 备份时效性
• 磁盘空间
• 内存使用率

版本管理策略

均衡升级策略

采用滞后一个版本的策略以兼顾稳定性。

周度升级评分系统

python3 scripts/weekly-upgrade-scorer.py

评分标准（满分 100 分）：

1. PaperMC 稳定性（30 分）

   • 官方 API 兼容性确认
   • 发布时长（≥2 周）
   • 是否包含安全补丁

2. 插件兼容性（40 分）

   • 核心插件兼容性
   • 全部插件兼容性
   • 插件近期更新情况
   • 无严重警告信息

3. 测试与验证（20 分）

   • 测试环境验证结果
   • 性能基准测试数据
   • 功能完整性验证

4. 风险管理（10 分）

   • 备份准备就绪
   • 回滚方案已测试

升级决策矩阵

• ≥ 80 分：可执行升级（低风险）
• 60–79 分：需进一步人工评估
• < 60 分：禁止升级（高风险）

周度扫描流程

1. 周一：运行自动化评分脚本
2. 复核：分析报告与各项得分
3. 决策：≥80 分需人工确认后方可执行
4. 执行：在完成全量备份前提下执行计划升级

紧急回滚

触发条件：

• 服务器启动失败
• TPS 持续低于 15
• 关键插件崩溃
• 玩家数据损坏

回滚步骤：

1. 立即停止服务器
2. 从最新备份恢复
3. 还原至前一版本
4. 验证功能并重启

目录结构

papermc-server/
├── manage_server.py              # 主控脚本
├── plugin_manager.py             # 插件管理脚本
├── update_paper.py               # PaperMC 更新脚本
├── plugin_upgrade_framework.py   # 智能插件升级框架（NEW）
├── upgrade_examples.py           # 升级使用示例（NEW）
├── viaversion_upgrade_report.json # ViaVersion 升级实践记录（NEW）
├── backup.sh                     # 备份自动化脚本
├── scripts/
│   └── health_check.sh           # 健康监测脚本
├── docs/
│   ├── architecture.md           # 系统设计文档
│   ├── changelog.md              # 版本变更日志
│   └── Turret_Plugin_User_Manual.md  # Turret 插件用户手册（NEW）
├── backup/                       # 世界存档备份目录
├── plugin_backup/                # 插件备份目录
└── jar_backup/                   # PaperMC jar 文件备份目录

工作流示例

日常健康检查

bash scripts/health_check.sh

传统插件更新前准备

python3 manage_server.py backup
python3 plugin_manager.py backup OldPlugin.jar
python3 plugin_manager.py install-url  --filename NewPlugin.jar
python3 manage_server.py restart
python3 manage_server.py status

智能插件升级（NEW）

# 扫描可升级插件候选列表
python3 plugin_upgrade_framework.py --method 2 --scan-limit 20

# 对指定插件执行带风险评估的升级
python3 plugin_upgrade_framework.py --plugin ViaVersion --version 5.8.0 --auto-restart

# 运行批量升级规划示例
python3 upgrade_examples.py

PaperMC 更新流程

python3 update_paper.py backup-jar
python3 update_paper.py update-from-url 
python3 manage_server.py restart
python3 manage_server.py status

配置

环境变量（.env）

SERVER_NAME=my-server
SERVER_DIR=/path/to/server
BACKUP_RETENTION=10

故障排查

服务无法启动

python3 manage_server.py logs -n 100

检查磁盘空间

df -h

验证 Java 环境

java -version

安全第一

本技能强制实施运维纪律：

• 所有操作必须通过受控接口执行
• 任何变更前必须完成备份
• 禁止使用破坏性直连命令
• 全程操作可追溯、可审计

切勿为所谓“快速修复”而绕过脚本层。

参阅

• docs/architecture.md — 系统架构说明
• docs/changelog.md — 版本历史记录
• docs/Turret_Plugin_User_Manual.md — Turret 插件完整用户手册
• scripts/health_check.sh — 健康监测脚本
• manage_server.py — 主控脚本
• plugin_manager.py — 插件管理脚本
• update_paper.py — PaperMC 更新脚本
• plugin_upgrade_framework.py — 智能插件升级框架
• upgrade_examples.py — 升级使用示例脚本
• viaversion_upgrade_report.json — ViaVersion 升级实践记录

许可证

MIT 许可证 — 详见 LICENSE 文件

技能版本：2.0.0（增强版，新增插件升级框架）
基于版本：v1.0.0 发布版
经验来源：ViaVersion 5.7.2 → 5.8.0 升级实践（2026-03-28）
核心价值：融合 AI 托管的“安全优先”运维范式与基于真实场景的智能插件升级能力。
ClawHub Slug：papermc-ai-ops
GitHub：https://github.com/yanxi1024-git/PaperMC-Ai-Agent