PaperMC AI Operations_IT运维与安全 skill-PHP中文网

PaperMC AI Operations

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

通过安全、受控的接口管理 PaperMC Minecraft 服务器，用于服务器生命周期管理、备份、插件操作和健康监控……

PaperMC 服务器 AI 操作

功能概述

PaperMC 服务器 AI 操作是一项面向实际任务的技能，主要用于由 APIC 管理, 安全第一的 PaperMC Minecraft 服务器操作；当使用此技能时；

核心要点

当您需要时使用此技能。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。

使用与执行

该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；

结果检查与注意事项

若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

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 脚本完成。

📦 备份先行策略

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

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

插件升级框架（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)

风险评估逻辑

风险等级	版本跨度	建议操作
低	补丁更新（x.x.1 → x.x.2）	推荐升级
中	次要更新（x.1.x → x.2.x）	上线前需测试
高	主要更新（1.x.x → 2.x.x）	需详细评估

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

升级后验证步骤

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

ViaVersion 升级实践

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

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

健康监测

bash scripts/health_check.sh

检测内容包括：

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

版本管理策略

均衡升级策略

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

周度升级评分系统

python3 scripts/weekly-upgrade-scorer.py

评分标准（满分 100 分）：

PaperMC 稳定性（30 分）
- 官方 API 兼容性确认
- 发布时长（≥2 周）
- 是否包含安全补丁
插件兼容性（40 分）
- 核心插件兼容性
- 全部插件兼容性
- 插件近期更新情况
- 无严重警告信息
测试与验证（20 分）
- 测试环境验证结果
- 性能基准测试数据
- 功能完整性验证
风险管理（10 分）
- 备份准备就绪
- 回滚方案已测试

升级决策矩阵

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

周度扫描流程

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

紧急回滚

触发条件：

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

回滚步骤：

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

目录结构

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