[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6D2SBJ1959YBVRT97D8E6FD":3,"skill-same:01M6D2SBJ1959YBVRT97D8E6FD":81},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":47,"linkOnly":48,"markdownContent":49,"markdownBody":50,"frontMatter":51,"refName":52,"commitSha":53,"skillDirectory":54,"forksCount":55,"repositoryHtmlUrl":56,"repositoryHomepageUrl":6,"ownerHtmlUrl":57,"ownerBlogUrl":58,"ownerDescription":59,"updatedAt":60,"install":61,"resources":74},"01M6D2SBJ1959YBVRT97D8E6FD","minecraft-server-admin",null,"Set up, operate, tune, and troubleshoot Minecraft Java 26.x and legacy 1.21.x servers across Paper, Purpur, Folia, Velocity, Fabric, and NeoForge. Use for infrastructure, backups, proxies, and live operations, not plugin or mod development.","Jahrome907\u002Fminecraft-agent-skills","Jahrome907","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F222458345?v=4","01M6D2JFFY1EQCC572G6G3X1R2","Joe ","01M6D2JFS2EE87QN8QCFVFY6M8",199,"MIT","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fminecraft-codex-skills\u002Fskills\u002Fminecraft-server-admin\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46],"minecraft server admin","admin","server","minecraft","use","paper","live","proxies","across","velocity","Legacy","up","troubleshoot","operations","SET","java","fabric","development","infrastructure","plugin","2026-11-10 10:12:30",false,"---\nname: minecraft-server-admin\ndescription: \"Set up, operate, tune, and troubleshoot Minecraft Java 26.x and legacy 1.21.x servers across Paper, Purpur, Folia, Velocity, Fabric, and NeoForge. Use for infrastructure, backups, proxies, and live operations, not plugin or mod development.\"\n---\n\n# Minecraft Server Administration Skill\n\n## Scope and Routing Boundaries\n\n### Routing Boundaries\n- `Use when`: the task is infrastructure or live operations for Minecraft servers (deployment choice, tuning, backups, proxying, security, incident response).\n- `Do not use when`: the task is writing plugin code (`minecraft-plugin-dev`) or writing mods\u002Floaders (`minecraft-modding`, `minecraft-multiloader`).\n- `Do not use when`: the task is WorldEdit command workflows (`minecraft-worldedit-ops`) or EssentialsX workflow\u002Fpolicy design (`minecraft-essentials-ops`).\n- `Do not use when`: the task is datapack\u002Fresource-pack authoring (`minecraft-datapack`, `minecraft-resource-pack`).\n\n## References\n\n- Read `references\u002Fdeployment-checklists.md` when the task is an incident, rollout window, proxy change, or recovery drill and you need a compact checklist before acting.\n\n---\n\n## Deployment Decision Matrix\n\nUse this table when choosing a deployment. For an existing server, inspect its\nstack and version first and preserve them unless migration is requested.\n\n| Deployment profile | Recommended stack | Pick this when | Watch-outs |\n|---|---|---|---|\n| Small SMP on Paper | Paper only | Up to ~30 concurrent players, broad plugin compatibility, low ops overhead | Do not over-tune early; profile before changing many defaults |\n| Larger public Paper server | Paper + Spark + stricter plugin\u002Fchange control | Public server with frequent joins, moderate plugin set, uptime matters | Plugin sprawl is the top TPS risk |\n| Velocity-backed network | Velocity + multiple Paper backends | Hub\u002Fminigame\u002Ffactions split across servers, need shared entrypoint | Forwarding\u002Fauth mismatches can block joins |\n| Purpur gameplay-heavy server | Purpur (optionally behind Velocity) | You want gameplay knobs exposed in config without custom plugin code | Extra toggles increase misconfiguration risk |\n| Folia high-concurrency server | Folia + Folia-compatible plugins only | Very high concurrency with region-threading goals | Many plugins are not Folia-safe |\n| Fabric\u002FNeoForge mod server | Fabric or NeoForge server build | You require loader mods, custom content, modpack behavior | Bukkit\u002FPaper plugins do not apply |\n\n### Deployment Type Routing\n\n- Small SMP and most public plugin servers: use Paper baseline first.\n- Use Purpur only when you explicitly need Purpur gameplay controls.\n- Use Folia only when plugin compatibility has been validated for region-threading.\n- Use Velocity when one process is not enough or you need separate backend roles.\n- Use Fabric\u002FNeoForge when the requirement is mod-driven, not plugin-driven.\n\n### Java versions\n\n- Paper and Purpur: Minecraft 26.1+ requires Java 25; Minecraft 1.21.x uses\n  Java 21. Verify the exact Paper\u002FPurpur build and installed plugins before a\n  version change.\n- Current Velocity 4.x requires Java 25. For a legacy proxy, retain the Java\n  version required by that exact proxy release rather than applying the current\n  version by default.\n\n---\n\n## Playbook: Performance Tuning\n\n### Step 1: Establish baseline\n\nCollect a baseline before edits. Linux host example:\n\n```bash\nfree -h\ntop -b -n 1 | head -n 25\n```\n\nWindows PowerShell host example:\n\n```powershell\nGet-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize\nGet-Process java | Sort-Object CPU -Descending | Select-Object -First 5 Id,CPU,WorkingSet,Path\n```\n\nIn server console:\n\n```bash\ntps\nmspt\nspark healthreport\n```\n\nRecord:\n- peak player count\n- MSPT at idle and at peak activity\n- top plugins by CPU from Spark report\n\n### Step 2: Profile the real bottleneck\n\nUse Spark instead of guesswork:\n\n```bash\nspark profiler --timeout 180\nspark tps\nspark tickmonitor --threshold-tick 50\n```\n\nThe 50 ms threshold reports ticks that exceed one normal 20 TPS tick; adjust it\nonly when the incident threshold is intentionally different.\n\nThen identify whether the issue is:\n- plugin task load\n- entity count \u002F mob farm pressure\n- chunk generation \u002F disk I\u002FO\n- garbage-collection pauses\n\n### Step 3: Apply targeted fixes\n\nDo not tune everything at once. Apply one group at a time.\n\n1. Chunk and simulation pressure:\n- lower `view-distance` and `simulation-distance` first\n- pre-generate worlds for survival-heavy maps\n\n1. Entity pressure:\n- adjust despawn ranges and mob-spawn behavior in Paper world config\n- cap problematic entities where appropriate\n\n1. Plugin pressure:\n- disable or replace top offenders from Spark traces\n- reduce async task frequency where plugin settings allow\n\n### Step 4: Use stable startup flags\n\nFor Java 25 on current Paper\u002FPurpur, start with a simple measured baseline:\n\n```bash\njava -Xms4G -Xmx4G -jar server.jar --nogui\n```\n\nIncrease heap only when profiling and player load justify it. Add collector flags\nonly after validating them against the exact JDK and Paper version.\n\n### Step 5: Verify improvements\n\nAfter each change set:\n\n```bash\nspark tps\nspark healthreport\n```\n\nKeep the change only if MSPT\u002Ftick stability improves under representative load.\n\n---\n\n## Playbook: Plugin Operations\n\n### Safe plugin change workflow\n\n1. Build a plugin inventory:\n- plugin name and version\n- required dependencies\n- minimum server version\n\n1. Stage updates:\n- apply plugin updates in staging first\n- run smoke checks: joins, teleports, economy, permissions, saves\n\n1. Production rollout window:\n- announce maintenance window\n- stop server cleanly\n- snapshot plugin jars and config\n- deploy update batch\n\n1. Post-rollout verification:\n- watch startup logs for API warnings\n- run command and permission sanity checks\n- track TPS\u002FMSPT for 15-30 minutes\n\n### Rollback checklist\n\n- Keep previous plugin directory snapshot.\n- If severe regression occurs:\n  - stop server\n  - restore prior plugin jars\u002Fconfigs\n  - start and confirm login\u002Fworld integrity\n- Document failing plugin\u002Fversion pair for future blocks.\n\n---\n\n## Playbook: Proxy and Forwarding (Velocity)\n\n### Velocity baseline\n\n`velocity.toml` essentials:\n\n```toml\nbind = \"0.0.0.0:25565\"\nonline-mode = true\nplayer-info-forwarding-mode = \"modern\"\nforwarding-secret-file = \"forwarding.secret\"\n```\n\n### Backend server requirements\n\n`server.properties` on backend:\n\n```properties\nonline-mode=false\n```\n\nPaper backend forwarding support (`config\u002Fpaper-global.yml`):\n\n```yaml\nproxies:\n  velocity:\n    enabled: true\n    online-mode: true\n    secret: \"paste-the-shared-forwarding-secret-here\"\n```\n\nUse the same secret value stored in Velocity's `forwarding.secret` file; the backend\nconfig takes the secret string itself, not a file path.\n\nKeep `enforce-secure-profile` at the server default unless you are handling a\nspecific legacy-client or incident workaround. It is not part of the baseline\nVelocity setup. Also confirm `settings.bungeecord: false` in `spigot.yml`; do\nnot enable BungeeCord forwarding and Velocity modern forwarding at the same time.\n\n### Validation runbook\n\n1. Confirm proxy port is reachable from clients.\n2. Confirm backend is firewalled from direct internet access.\n3. Join through proxy and verify:\n- UUID consistency\n- skin\u002Fprofile forwarding\n- plugin permission behavior\n\n### Common proxy incidents\n\n- \"Invalid player info forwarding\":\n  - mismatch in forwarding mode or shared secret between Velocity and backend.\n- Random auth\u002Fsession failures:\n  - mixed `online-mode` expectations or direct backend exposure.\n\n---\n\n## Playbook: Backup and Recovery\n\n### Backup policy template\n\n| Asset | Frequency | Retention | Notes |\n|---|---|---|---|\n| Every configured world folder | Hourly incremental + daily full | 7 daily, 4 weekly | Include custom and externally stored worlds |\n| `plugins\u002F`, `config\u002F`, and root server state | Daily | 14 daily | Required for operational restore |\n| Proxy config\u002Fsecrets | Daily | 30 daily | Store encrypted off-host |\n| Container\u002Forchestration files | On change + weekly | 8 weeks | Git-tracked where possible |\n\n### Example backup script (Paper\u002FPurpur)\n\nFor a production server, quiesce world writes before copying live world folders.\nThe example below assumes a maintenance window and a cleanly stopped server. If\nyou use RCON-based live backups instead, choose a client\u002Fsecret mechanism that\ndoes not expose the password in command arguments. A safe implementation must\nrun `save-off`, then `save-all`, copy the data, and guarantee `save-on` cleanup\neven when the copy fails. Do not treat a flush or `save-all` alone as a live\nbackup protocol. Folia disables `save-all`; use a clean stop or a verified\nplatform snapshot there. Test the restore path before trusting any backup.\n\nFor Fabric or NeoForge recovery, additionally inventory `mods\u002F` and record the\nexact loader launch state: Minecraft and loader versions, Java version, launch\ncommand and arguments, launcher or installer artifacts, and any version or\nlibrary manifests used by that deployment. Restore those matching components\nwith the configured world folders; this Paper\u002FPurpur example does not capture\nthem for you.\n\nSupply the complete world-folder list as arguments, relative to `SERVER_ROOT`,\nafter checking `level-name` and any multi-world plugin configuration. Back up\nworlds stored outside that root separately; do not infer coverage from `world*`.\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\nset -euo pipefail\n\nif [[ \"${SERVER_STOPPED_CONFIRMED:-}\" != \"1\" ]]; then\n  echo \"Set SERVER_STOPPED_CONFIRMED=1 only after stopping the server cleanly.\" >&2\n  exit 1\nfi\n\nDATE=\"$(date +%Y-%m-%d_%H-%M-%S)\"\nBACKUP_ROOT=\"\u002Fbackups\u002Fminecraft\"\nSERVER_ROOT=\"\u002Fsrv\u002Fminecraft\"\nDEST=\"${BACKUP_ROOT}\u002F${DATE}\"\n\nif [[ \"$#\" -eq 0 ]]; then\n  echo \"Usage: backup.sh \u003Cworld-folder> [additional-world-folders...]\" >&2\n  exit 1\nfi\nfor world_dir in \"$@\"; do\n  if [[ ! -d \"$SERVER_ROOT\u002F$world_dir\" ]]; then\n    echo \"Missing configured world folder: $world_dir\" >&2\n    exit 1\n  fi\ndone\n\nmkdir -p \"$DEST\"\n\ntar -czf \"${DEST}\u002Fworlds.tar.gz\" -C \"$SERVER_ROOT\" -- \"$@\"\n\nstate_items=()\nfor item in \\\n  plugins config server.properties bukkit.yml spigot.yml paper-global.yml \\\n  paper-world-defaults.yml permissions.yml ops.json whitelist.json \\\n  banned-players.json banned-ips.json; do\n  [[ -e \"$SERVER_ROOT\u002F$item\" ]] && state_items+=(\"$item\")\ndone\n\nif [[ \"${#state_items[@]}\" -gt 0 ]]; then\n  tar -czf \"${DEST}\u002Fserver-state.tar.gz\" -C \"$SERVER_ROOT\" \"${state_items[@]}\"\nfi\n```\n\n### Recovery drill (must be tested)\n\n1. Stop server.\n2. Restore selected backup to staging directory.\n3. Validate ownership\u002Fpermissions.\n4. Start server in maintenance mode.\n5. Verify:\n- world spawn loads\n- player data is readable\n- key plugins initialize\n1. Reopen to players.\n\nDefine targets:\n- `RPO` (acceptable data loss window)\n- `RTO` (acceptable restore duration)\n\n---\n\n## Playbook: Live Troubleshooting\n\n### Incident triage flow\n\n1. Classify incident:\n- crash on startup\n- severe lag \u002F TPS collapse\n- join\u002Fauth failures\n- memory\u002Fdisk pressure\n\n1. Capture evidence first. Linux host example:\n\n```bash\ndf -h\nfree -h\n```\n\nWindows PowerShell host example:\n\n```powershell\nGet-PSDrive -PSProvider FileSystem\nGet-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize\n```\n\nFrom server\u002Fproxy console:\n\n```bash\nspark tps\nspark healthreport\n```\n\n1. Stabilize:\n- stop risky rollout changes\n- disable newest suspect plugin first\n- reduce player impact (maintenance mode, temporary queue, restricted worlds)\n\n1. Recover and document:\n- apply rollback or hotfix\n- document root cause and permanent preventive action\n\n### Fast symptom map\n\n| Symptom | First checks | Typical root cause |\n|---|---|---|\n| Startup crash after plugin update | latest logs, plugin dependency chain | incompatible plugin\u002FAPI mismatch |\n| High MSPT only at peak hours | Spark profiler, entity\u002Fchunk stats | mob farms, heavy scheduled tasks, chunk I\u002FO |\n| Players cannot join via proxy | forwarding mode + secret + backend exposure | Velocity\u002Fbackend config mismatch |\n| Periodic hard lag spikes | GC pauses + autosave + backup overlap | memory pressure, backup I\u002FO contention |\n\n---\n\n## Operational Config Reference\n\n### `server.properties` high-impact keys\n\n```properties\nmax-players=100\nview-distance=10\nsimulation-distance=8\nsync-chunk-writes=true\nmax-tick-time=60000\nenable-rcon=false\n```\n\n### `bukkit.yml` and `spigot.yml`\n\nUse Spigot\u002FBukkit docs as authoritative for version-specific defaults and side effects.\nTune conservatively and re-measure after every change set.\n\n### Paper config files\n\n- `config\u002Fpaper-global.yml`\n- `config\u002Fpaper-world-defaults.yml`\n\nAdjust these only after profiling identifies an actionable bottleneck.\n\n---\n\n## Deployment Patterns\n\n### Docker Compose (Paper)\n\n```yaml\nservices:\n  paper:\n    image: itzg\u002Fminecraft-server:java25\n    container_name: mc-paper\n    environment:\n      EULA: \"TRUE\"\n      TYPE: \"PAPER\"\n      VERSION: \"26.3\"\n      MEMORY: \"10G\"\n    ports:\n      - \"25565:25565\"\n    volumes:\n      - .\u002Fdata:\u002Fdata\n    restart: unless-stopped\n```\n\nThis Docker example targets current Paper 26.3 and Java 25. Re-check plugin\ncompatibility and take a restorable backup before changing an existing server's\nMinecraft or Java line.\n\n### Pterodactyl\u002FWings notes\n\n- Keep startup command and memory allocations consistent with tested JVM flags.\n- Pin panel and Wings versions to supported combinations.\n- Validate backup mount and restore workflow before production.\n\n---\n\n## Security Hardening Checklist\n\n- Keep `online-mode=true` unless proxy forwarding requires backend `online-mode=false`.\n- Never expose backend Paper ports directly when using Velocity.\n- Restrict RCON and panel\u002Fadmin surfaces by firewall\u002FIP allowlist.\n- Rotate secrets (`forwarding.secret`, panel credentials, backup credentials).\n- Keep plugin sources trusted; verify checksum\u002Frelease source before install.\n- Maintain off-host encrypted backups.\n- Keep Java runtime and host OS patched.\n\n---\n\n## References\n\n### Paper (primary)\n\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fgetting-started\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fadmin\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fprofiling\u002F\n\n### Spigot\u002FBukkit (primary config reference)\n\n- https:\u002F\u002Fwww.spigotmc.org\u002Fwiki\u002Fspigot-configuration\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Freference\u002Fbukkit-configuration\u002F\n- https:\u002F\u002Fwww.spigotmc.org\u002Fwiki\u002Fstart-up-parameters\u002F\n\n### Proxy and ecosystem docs\n\n- https:\u002F\u002Fdocs.papermc.io\u002Fvelocity\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fvelocity\u002Fgetting-started\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Ffolia\u002Ffaq\u002F\n- https:\u002F\u002Fspark.lucko.me\u002Fdocs\n- https:\u002F\u002Fspark.lucko.me\u002Fdocs\u002FCommand-Usage\n- https:\u002F\u002Fgithub.com\u002Fitzg\u002Fdocker-mc-backup\n- https:\u002F\u002Fgeysermc.org\u002Fwiki\u002Fgeyser\u002F\n- https:\u002F\u002Fdocs.pterodactyl.io\u002Fv1\u002Fpanel\u002Fgetting-started\n","# Minecraft Server Administration Skill\n\n## Scope and Routing Boundaries\n\n### Routing Boundaries\n- `Use when`: the task is infrastructure or live operations for Minecraft servers (deployment choice, tuning, backups, proxying, security, incident response).\n- `Do not use when`: the task is writing plugin code (`minecraft-plugin-dev`) or writing mods\u002Floaders (`minecraft-modding`, `minecraft-multiloader`).\n- `Do not use when`: the task is WorldEdit command workflows (`minecraft-worldedit-ops`) or EssentialsX workflow\u002Fpolicy design (`minecraft-essentials-ops`).\n- `Do not use when`: the task is datapack\u002Fresource-pack authoring (`minecraft-datapack`, `minecraft-resource-pack`).\n\n## References\n\n- Read `references\u002Fdeployment-checklists.md` when the task is an incident, rollout window, proxy change, or recovery drill and you need a compact checklist before acting.\n\n---\n\n## Deployment Decision Matrix\n\nUse this table when choosing a deployment. For an existing server, inspect its\nstack and version first and preserve them unless migration is requested.\n\n| Deployment profile | Recommended stack | Pick this when | Watch-outs |\n|---|---|---|---|\n| Small SMP on Paper | Paper only | Up to ~30 concurrent players, broad plugin compatibility, low ops overhead | Do not over-tune early; profile before changing many defaults |\n| Larger public Paper server | Paper + Spark + stricter plugin\u002Fchange control | Public server with frequent joins, moderate plugin set, uptime matters | Plugin sprawl is the top TPS risk |\n| Velocity-backed network | Velocity + multiple Paper backends | Hub\u002Fminigame\u002Ffactions split across servers, need shared entrypoint | Forwarding\u002Fauth mismatches can block joins |\n| Purpur gameplay-heavy server | Purpur (optionally behind Velocity) | You want gameplay knobs exposed in config without custom plugin code | Extra toggles increase misconfiguration risk |\n| Folia high-concurrency server | Folia + Folia-compatible plugins only | Very high concurrency with region-threading goals | Many plugins are not Folia-safe |\n| Fabric\u002FNeoForge mod server | Fabric or NeoForge server build | You require loader mods, custom content, modpack behavior | Bukkit\u002FPaper plugins do not apply |\n\n### Deployment Type Routing\n\n- Small SMP and most public plugin servers: use Paper baseline first.\n- Use Purpur only when you explicitly need Purpur gameplay controls.\n- Use Folia only when plugin compatibility has been validated for region-threading.\n- Use Velocity when one process is not enough or you need separate backend roles.\n- Use Fabric\u002FNeoForge when the requirement is mod-driven, not plugin-driven.\n\n### Java versions\n\n- Paper and Purpur: Minecraft 26.1+ requires Java 25; Minecraft 1.21.x uses\n  Java 21. Verify the exact Paper\u002FPurpur build and installed plugins before a\n  version change.\n- Current Velocity 4.x requires Java 25. For a legacy proxy, retain the Java\n  version required by that exact proxy release rather than applying the current\n  version by default.\n\n---\n\n## Playbook: Performance Tuning\n\n### Step 1: Establish baseline\n\nCollect a baseline before edits. Linux host example:\n\n```bash\nfree -h\ntop -b -n 1 | head -n 25\n```\n\nWindows PowerShell host example:\n\n```powershell\nGet-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize\nGet-Process java | Sort-Object CPU -Descending | Select-Object -First 5 Id,CPU,WorkingSet,Path\n```\n\nIn server console:\n\n```bash\ntps\nmspt\nspark healthreport\n```\n\nRecord:\n- peak player count\n- MSPT at idle and at peak activity\n- top plugins by CPU from Spark report\n\n### Step 2: Profile the real bottleneck\n\nUse Spark instead of guesswork:\n\n```bash\nspark profiler --timeout 180\nspark tps\nspark tickmonitor --threshold-tick 50\n```\n\nThe 50 ms threshold reports ticks that exceed one normal 20 TPS tick; adjust it\nonly when the incident threshold is intentionally different.\n\nThen identify whether the issue is:\n- plugin task load\n- entity count \u002F mob farm pressure\n- chunk generation \u002F disk I\u002FO\n- garbage-collection pauses\n\n### Step 3: Apply targeted fixes\n\nDo not tune everything at once. Apply one group at a time.\n\n1. Chunk and simulation pressure:\n- lower `view-distance` and `simulation-distance` first\n- pre-generate worlds for survival-heavy maps\n\n1. Entity pressure:\n- adjust despawn ranges and mob-spawn behavior in Paper world config\n- cap problematic entities where appropriate\n\n1. Plugin pressure:\n- disable or replace top offenders from Spark traces\n- reduce async task frequency where plugin settings allow\n\n### Step 4: Use stable startup flags\n\nFor Java 25 on current Paper\u002FPurpur, start with a simple measured baseline:\n\n```bash\njava -Xms4G -Xmx4G -jar server.jar --nogui\n```\n\nIncrease heap only when profiling and player load justify it. Add collector flags\nonly after validating them against the exact JDK and Paper version.\n\n### Step 5: Verify improvements\n\nAfter each change set:\n\n```bash\nspark tps\nspark healthreport\n```\n\nKeep the change only if MSPT\u002Ftick stability improves under representative load.\n\n---\n\n## Playbook: Plugin Operations\n\n### Safe plugin change workflow\n\n1. Build a plugin inventory:\n- plugin name and version\n- required dependencies\n- minimum server version\n\n1. Stage updates:\n- apply plugin updates in staging first\n- run smoke checks: joins, teleports, economy, permissions, saves\n\n1. Production rollout window:\n- announce maintenance window\n- stop server cleanly\n- snapshot plugin jars and config\n- deploy update batch\n\n1. Post-rollout verification:\n- watch startup logs for API warnings\n- run command and permission sanity checks\n- track TPS\u002FMSPT for 15-30 minutes\n\n### Rollback checklist\n\n- Keep previous plugin directory snapshot.\n- If severe regression occurs:\n  - stop server\n  - restore prior plugin jars\u002Fconfigs\n  - start and confirm login\u002Fworld integrity\n- Document failing plugin\u002Fversion pair for future blocks.\n\n---\n\n## Playbook: Proxy and Forwarding (Velocity)\n\n### Velocity baseline\n\n`velocity.toml` essentials:\n\n```toml\nbind = \"0.0.0.0:25565\"\nonline-mode = true\nplayer-info-forwarding-mode = \"modern\"\nforwarding-secret-file = \"forwarding.secret\"\n```\n\n### Backend server requirements\n\n`server.properties` on backend:\n\n```properties\nonline-mode=false\n```\n\nPaper backend forwarding support (`config\u002Fpaper-global.yml`):\n\n```yaml\nproxies:\n  velocity:\n    enabled: true\n    online-mode: true\n    secret: \"paste-the-shared-forwarding-secret-here\"\n```\n\nUse the same secret value stored in Velocity's `forwarding.secret` file; the backend\nconfig takes the secret string itself, not a file path.\n\nKeep `enforce-secure-profile` at the server default unless you are handling a\nspecific legacy-client or incident workaround. It is not part of the baseline\nVelocity setup. Also confirm `settings.bungeecord: false` in `spigot.yml`; do\nnot enable BungeeCord forwarding and Velocity modern forwarding at the same time.\n\n### Validation runbook\n\n1. Confirm proxy port is reachable from clients.\n2. Confirm backend is firewalled from direct internet access.\n3. Join through proxy and verify:\n- UUID consistency\n- skin\u002Fprofile forwarding\n- plugin permission behavior\n\n### Common proxy incidents\n\n- \"Invalid player info forwarding\":\n  - mismatch in forwarding mode or shared secret between Velocity and backend.\n- Random auth\u002Fsession failures:\n  - mixed `online-mode` expectations or direct backend exposure.\n\n---\n\n## Playbook: Backup and Recovery\n\n### Backup policy template\n\n| Asset | Frequency | Retention | Notes |\n|---|---|---|---|\n| Every configured world folder | Hourly incremental + daily full | 7 daily, 4 weekly | Include custom and externally stored worlds |\n| `plugins\u002F`, `config\u002F`, and root server state | Daily | 14 daily | Required for operational restore |\n| Proxy config\u002Fsecrets | Daily | 30 daily | Store encrypted off-host |\n| Container\u002Forchestration files | On change + weekly | 8 weeks | Git-tracked where possible |\n\n### Example backup script (Paper\u002FPurpur)\n\nFor a production server, quiesce world writes before copying live world folders.\nThe example below assumes a maintenance window and a cleanly stopped server. If\nyou use RCON-based live backups instead, choose a client\u002Fsecret mechanism that\ndoes not expose the password in command arguments. A safe implementation must\nrun `save-off`, then `save-all`, copy the data, and guarantee `save-on` cleanup\neven when the copy fails. Do not treat a flush or `save-all` alone as a live\nbackup protocol. Folia disables `save-all`; use a clean stop or a verified\nplatform snapshot there. Test the restore path before trusting any backup.\n\nFor Fabric or NeoForge recovery, additionally inventory `mods\u002F` and record the\nexact loader launch state: Minecraft and loader versions, Java version, launch\ncommand and arguments, launcher or installer artifacts, and any version or\nlibrary manifests used by that deployment. Restore those matching components\nwith the configured world folders; this Paper\u002FPurpur example does not capture\nthem for you.\n\nSupply the complete world-folder list as arguments, relative to `SERVER_ROOT`,\nafter checking `level-name` and any multi-world plugin configuration. Back up\nworlds stored outside that root separately; do not infer coverage from `world*`.\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\nset -euo pipefail\n\nif [[ \"${SERVER_STOPPED_CONFIRMED:-}\" != \"1\" ]]; then\n  echo \"Set SERVER_STOPPED_CONFIRMED=1 only after stopping the server cleanly.\" >&2\n  exit 1\nfi\n\nDATE=\"$(date +%Y-%m-%d_%H-%M-%S)\"\nBACKUP_ROOT=\"\u002Fbackups\u002Fminecraft\"\nSERVER_ROOT=\"\u002Fsrv\u002Fminecraft\"\nDEST=\"${BACKUP_ROOT}\u002F${DATE}\"\n\nif [[ \"$#\" -eq 0 ]]; then\n  echo \"Usage: backup.sh \u003Cworld-folder> [additional-world-folders...]\" >&2\n  exit 1\nfi\nfor world_dir in \"$@\"; do\n  if [[ ! -d \"$SERVER_ROOT\u002F$world_dir\" ]]; then\n    echo \"Missing configured world folder: $world_dir\" >&2\n    exit 1\n  fi\ndone\n\nmkdir -p \"$DEST\"\n\ntar -czf \"${DEST}\u002Fworlds.tar.gz\" -C \"$SERVER_ROOT\" -- \"$@\"\n\nstate_items=()\nfor item in \\\n  plugins config server.properties bukkit.yml spigot.yml paper-global.yml \\\n  paper-world-defaults.yml permissions.yml ops.json whitelist.json \\\n  banned-players.json banned-ips.json; do\n  [[ -e \"$SERVER_ROOT\u002F$item\" ]] && state_items+=(\"$item\")\ndone\n\nif [[ \"${#state_items[@]}\" -gt 0 ]]; then\n  tar -czf \"${DEST}\u002Fserver-state.tar.gz\" -C \"$SERVER_ROOT\" \"${state_items[@]}\"\nfi\n```\n\n### Recovery drill (must be tested)\n\n1. Stop server.\n2. Restore selected backup to staging directory.\n3. Validate ownership\u002Fpermissions.\n4. Start server in maintenance mode.\n5. Verify:\n- world spawn loads\n- player data is readable\n- key plugins initialize\n1. Reopen to players.\n\nDefine targets:\n- `RPO` (acceptable data loss window)\n- `RTO` (acceptable restore duration)\n\n---\n\n## Playbook: Live Troubleshooting\n\n### Incident triage flow\n\n1. Classify incident:\n- crash on startup\n- severe lag \u002F TPS collapse\n- join\u002Fauth failures\n- memory\u002Fdisk pressure\n\n1. Capture evidence first. Linux host example:\n\n```bash\ndf -h\nfree -h\n```\n\nWindows PowerShell host example:\n\n```powershell\nGet-PSDrive -PSProvider FileSystem\nGet-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize\n```\n\nFrom server\u002Fproxy console:\n\n```bash\nspark tps\nspark healthreport\n```\n\n1. Stabilize:\n- stop risky rollout changes\n- disable newest suspect plugin first\n- reduce player impact (maintenance mode, temporary queue, restricted worlds)\n\n1. Recover and document:\n- apply rollback or hotfix\n- document root cause and permanent preventive action\n\n### Fast symptom map\n\n| Symptom | First checks | Typical root cause |\n|---|---|---|\n| Startup crash after plugin update | latest logs, plugin dependency chain | incompatible plugin\u002FAPI mismatch |\n| High MSPT only at peak hours | Spark profiler, entity\u002Fchunk stats | mob farms, heavy scheduled tasks, chunk I\u002FO |\n| Players cannot join via proxy | forwarding mode + secret + backend exposure | Velocity\u002Fbackend config mismatch |\n| Periodic hard lag spikes | GC pauses + autosave + backup overlap | memory pressure, backup I\u002FO contention |\n\n---\n\n## Operational Config Reference\n\n### `server.properties` high-impact keys\n\n```properties\nmax-players=100\nview-distance=10\nsimulation-distance=8\nsync-chunk-writes=true\nmax-tick-time=60000\nenable-rcon=false\n```\n\n### `bukkit.yml` and `spigot.yml`\n\nUse Spigot\u002FBukkit docs as authoritative for version-specific defaults and side effects.\nTune conservatively and re-measure after every change set.\n\n### Paper config files\n\n- `config\u002Fpaper-global.yml`\n- `config\u002Fpaper-world-defaults.yml`\n\nAdjust these only after profiling identifies an actionable bottleneck.\n\n---\n\n## Deployment Patterns\n\n### Docker Compose (Paper)\n\n```yaml\nservices:\n  paper:\n    image: itzg\u002Fminecraft-server:java25\n    container_name: mc-paper\n    environment:\n      EULA: \"TRUE\"\n      TYPE: \"PAPER\"\n      VERSION: \"26.3\"\n      MEMORY: \"10G\"\n    ports:\n      - \"25565:25565\"\n    volumes:\n      - .\u002Fdata:\u002Fdata\n    restart: unless-stopped\n```\n\nThis Docker example targets current Paper 26.3 and Java 25. Re-check plugin\ncompatibility and take a restorable backup before changing an existing server's\nMinecraft or Java line.\n\n### Pterodactyl\u002FWings notes\n\n- Keep startup command and memory allocations consistent with tested JVM flags.\n- Pin panel and Wings versions to supported combinations.\n- Validate backup mount and restore workflow before production.\n\n---\n\n## Security Hardening Checklist\n\n- Keep `online-mode=true` unless proxy forwarding requires backend `online-mode=false`.\n- Never expose backend Paper ports directly when using Velocity.\n- Restrict RCON and panel\u002Fadmin surfaces by firewall\u002FIP allowlist.\n- Rotate secrets (`forwarding.secret`, panel credentials, backup credentials).\n- Keep plugin sources trusted; verify checksum\u002Frelease source before install.\n- Maintain off-host encrypted backups.\n- Keep Java runtime and host OS patched.\n\n---\n\n## References\n\n### Paper (primary)\n\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fgetting-started\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fadmin\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fprofiling\u002F\n\n### Spigot\u002FBukkit (primary config reference)\n\n- https:\u002F\u002Fwww.spigotmc.org\u002Fwiki\u002Fspigot-configuration\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Freference\u002Fbukkit-configuration\u002F\n- https:\u002F\u002Fwww.spigotmc.org\u002Fwiki\u002Fstart-up-parameters\u002F\n\n### Proxy and ecosystem docs\n\n- https:\u002F\u002Fdocs.papermc.io\u002Fvelocity\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Fvelocity\u002Fgetting-started\u002F\n- https:\u002F\u002Fdocs.papermc.io\u002Ffolia\u002Ffaq\u002F\n- https:\u002F\u002Fspark.lucko.me\u002Fdocs\n- https:\u002F\u002Fspark.lucko.me\u002Fdocs\u002FCommand-Usage\n- https:\u002F\u002Fgithub.com\u002Fitzg\u002Fdocker-mc-backup\n- https:\u002F\u002Fgeysermc.org\u002Fwiki\u002Fgeyser\u002F\n- https:\u002F\u002Fdocs.pterodactyl.io\u002Fv1\u002Fpanel\u002Fgetting-started\n",{"name":5,"description":7},"main","22d61ce6b7a0c5f215008824aa6b94ecc73f2a43","plugins\u002Fminecraft-codex-skills\u002Fskills\u002Fminecraft-server-admin",11,"https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills","https:\u002F\u002Fgithub.com\u002FJahrome907","joe-o.com","Product engineer building field tools, workflow automation, and polished web applications.","2026-10-30 08:19:45",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add Jahrome907\u002Fminecraft-agent-skills --skill minecraft-server-admin",{"tool":67,"command":68},"bunx","bunx skills add Jahrome907\u002Fminecraft-agent-skills --skill minecraft-server-admin",{"tool":70,"command":71},"pnpm","pnpm dlx skills add Jahrome907\u002Fminecraft-agent-skills --skill minecraft-server-admin","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fminecraft-codex-skills\u002Fskills\u002Fminecraft-server-admin\u002FSKILL.md",true,[75],{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Fdeployment-checklists.md","REFERENCE","参考文档",2192,"https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fminecraft-codex-skills\u002Fskills\u002Fminecraft-server-admin\u002Freferences\u002Fdeployment-checklists.md",[82,98,103,113,121,128],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":47},"01M6D2TV8CBAMB70CEC19VMVX5","minecraft-ci-release","Fixture with valid workflow YAML and a warning-only glob pattern.","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fwarn-only\u002FSKILL.md",[],[89,30,90,91,92,93,94,95,96,97],"minecraft ci release","ci","release","fixture","pattern","only","yaml","workflow","valid",{"skillNo":99,"name":97,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":47},"01M6D2TR1N9TNJPTRB66WDCY8X","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fvalid\u002FSKILL.md",[],[97],{"skillNo":104,"name":84,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":111,"publishedAt":47},"01M6D2TNBM97CCTYFCDKCFQ4AR","Fixture for a secretless workflow that passes strict validation.","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fsecretless-strict\u002FSKILL.md",[108],{"categoryNo":109,"categoryName":110,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[89,30,90,91,92,112,96],"validation",{"skillNo":114,"name":115,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":119,"publishedAt":47},"01M6D2TJ9FX4FH1TMGKQPYNZQX","non-workflow-yaml","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fnon-workflow-yaml\u002FSKILL.md",[118],{"categoryNo":109,"categoryName":110,"taxonomyType":21,"taxonomyTypeDesc":22},[120,95,96],"non workflow yaml",{"skillNo":122,"name":84,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":47},"01M6D2TFE807BSXTEREYPWFY3G","Fixture with a mutable remote action reference.","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fmutable-action\u002FSKILL.md",[],[89,30,90,91,127,92],"reference",{"skillNo":129,"name":84,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":133,"publishedAt":47},"01M6D2TBYJ0SM3B79908DH9ECE","Fixture with valid multiline flow collections in workflow YAML.","https:\u002F\u002Fgithub.com\u002FJahrome907\u002Fminecraft-agent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fmultiline-flow\u002FSKILL.md",[],[89,91,30,90,96,95,134,92,135,97],"flow","collections"]