|
| 1 | +# Minecraft Server auf Proxmox – Version 3.0 (aktualisiert 2026-06-08) |
| 2 | + |
| 3 | +> 🇬🇧 English version: [README.md](README.md) |
| 4 | +
|
| 5 | +<img src="assets/banner.png" alt="Minecraft Server on Proxmox Banner" width="600"> |
| 6 | + |
| 7 | +*Minecraft Server auf Proxmox* |
| 8 | + |
| 9 | +[](https://github.com/TimInTech/minecraft-server-Proxmox/stargazers) |
| 10 | +[](https://github.com/TimInTech/minecraft-server-Proxmox/fork) |
| 11 | +[](LICENSE) |
| 12 | +[](https://github.com/TimInTech/minecraft-server-Proxmox/releases/latest) |
| 13 | +[](https://buymeacoffee.com/timintech) |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Quick Links |
| 18 | + |
| 19 | +- Server-Befehle: [SERVER_COMMANDS.md](SERVER_COMMANDS.md) |
| 20 | +- Simulations-Leitfaden: [SIMULATION.md](SIMULATION.md) |
| 21 | +- Bedrock-Netzwerk: [docs/BEDROCK_NETWORKING.md](docs/BEDROCK_NETWORKING.md) |
| 22 | +- Copilot-Workflow: [.github/copilot-instructions.md](.github/copilot-instructions.md) |
| 23 | +- Issues — <https://github.com/TimInTech/minecraft-server-Proxmox/issues> |
| 24 | + |
| 25 | +--- |
| 26 | + |
| 27 | +## Neu in v3.0 |
| 28 | + |
| 29 | +### Breaking Changes & kritische Fixes |
| 30 | + |
| 31 | +- **PaperMC-API auf Fill v3 migriert** — Der alte Endpunkt `api.papermc.io/v2/` erhält seit dem 31. Dezember 2025 keine neuen Builds mehr und wird am 1. Juli 2026 vollständig abgeschaltet. Alle Skripte (`setup_minecraft.sh`, `setup_minecraft_lxc.sh`, eingebettetes `update.sh`) nutzen jetzt die neue REST-API `fill.papermc.io/v3/`. Dies behebt die Issues [#66](https://github.com/TimInTech/minecraft-server-Proxmox/issues/66), [#70](https://github.com/TimInTech/minecraft-server-Proxmox/issues/70) und [#71](https://github.com/TimInTech/minecraft-server-Proxmox/issues/71). |
| 32 | +- **`jq`-Versionsfix** — Die neueste Minecraft-Version wird jetzt ermittelt, indem die Fill-v3-Versionsgruppen-Keys semantisch sortiert, die neueste Gruppe ausgewählt und daraus die neueste Patch-Version genommen wird (`.versions as $v | (… sort | last …) as $g | $v[$g][0]`). Das behebt sowohl `Cannot index object with number`-Fehler **als auch** die `curl: (22) 404`-Fehler, die auftraten, wenn die bisherige Logik einen reinen Gruppen-Key (z. B. `26.1`) statt einer echten Version (z. B. `26.1.2`) zurückgab. Behebt [#71](https://github.com/TimInTech/minecraft-server-Proxmox/issues/71) und [#74](https://github.com/TimInTech/minecraft-server-Proxmox/issues/74). |
| 33 | +- **User-Agent-Header erforderlich** — Fill v3 lehnt Anfragen ohne gültigen `User-Agent` ab oder drosselt sie. Alle API-Aufrufe enthalten jetzt `minecraft-server-Proxmox/<version>`. |
| 34 | +- **Download-URLs in API-Antwort eingebettet** — Downloads kommen jetzt von `fill-data.papermc.io`. URLs werden nicht mehr manuell konstruiert, sondern direkt aus der API-Antwort gelesen. |
| 35 | +- **Filterung auf Stable-Channel** — Die neue API liefert Builds über mehrere Channels (alpha, beta, stable, recommended). Die Skripte filtern jetzt auf `channel == "STABLE"`, um keine experimentellen Builds zu ziehen. |
| 36 | + |
| 37 | +### Weitere Verbesserungen |
| 38 | + |
| 39 | +- **LXC-Skript: `screen`-Unterstützung ergänzt** — `setup_minecraft_lxc.sh` installiert jetzt `screen`, legt das Socket-Verzeichnis `/run/screen` an und startet den Server in einer Screen-Session (konsistent mit dem VM-Skript und der README). Behebt Issue [#67](https://github.com/TimInTech/minecraft-server-Proxmox/issues/67). |
| 40 | +- **Bedrock-SHA-Default auf 0 geändert** — `REQUIRE_BEDROCK_SHA` ist jetzt standardmäßig `0`. Mojang veröffentlicht keine Upstream-Prüfsummen, daher war der bisherige Default `1` ein für alle Nutzer unlösbarer Blocker. Der SHA256 wird weiterhin berechnet und zur manuellen Prüfung ausgegeben. |
| 41 | +- **CT-Helfer: zufälliges Passwort** — `proxmox_create_ct_bedrock.sh` erzeugt jetzt ein zufälliges 16-stelliges alphanumerisches Passwort für das CT-Root-Konto (am Ende des Setups ausgegeben). Das hartkodierte `changeme` wurde entfernt. |
| 42 | +- **Hinweis zur Minecraft-Versionierung** — Ab 2026 verwendet Mojang ein neues Versionsschema (`26.1` statt `1.x.x`). Die Skripte handhaben das transparent, da sie immer die neueste Version aus der API ziehen. |
| 43 | +- **Java-Badge korrigiert** — Java 21 ist die Mindestvoraussetzung (Java 17 reicht für aktuelle PaperMC-Builds nicht mehr aus). |
| 44 | +- **Bedrock-Regex aktualisiert** — Das URL-Scraping-Muster erkennt jetzt auch das neue `26.x`-Versionsschema, das seit Februar 2026 verwendet wird. |
| 45 | +- **Fix für Dateibesitz** — `eula.txt` und andere generierte Dateien werden jetzt von Anfang an mit korrektem Besitzer angelegt. |
| 46 | + |
| 47 | +--- |
| 48 | + |
| 49 | +## ✅ Voraussetzungen |
| 50 | + |
| 51 | +- Proxmox VE: 7.4+ / 8.x / 9.x |
| 52 | +- Gast-OS: Debian 12/13 oder Ubuntu 22.04 / 24.04 |
| 53 | +- CPU/RAM: ≥2 vCPU, ≥2–4 GB RAM (Java), ≥1–2 GB (Bedrock) |
| 54 | +- Speicher: ≥10 GB SSD |
| 55 | +- Netzwerk: Bridged NIC (vmbr0), Ports 25565/TCP und 19132/UDP |
| 56 | + |
| 57 | +Java 21 ist erforderlich. Fehlt OpenJDK 21 in deinen Repositories, greifen die Installer automatisch auf Amazon Corretto 21 zurück (APT mit signiertem Keyring). |
| 58 | +**Hinweis:** UFW muss installiert sein, bevor `ufw`-Befehle ausgeführt werden. Der JVM-Speicher wird vom Installer automatisch dimensioniert (siehe unten). |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +## Einführung |
| 63 | + |
| 64 | +Dieses Repository richtet in wenigen Minuten einen performanten Minecraft-Server (Java & Bedrock) auf Proxmox ein. VM und LXC werden unterstützt. Enthalten sind CLI-orientiertes Setup, Updater und Backup-Beispiele. |
| 65 | + |
| 66 | +> Nur Simulation: Führe in diesem Workspace keine Befehle aus. Siehe SIMULATION.md. |
| 67 | +
|
| 68 | +## Technologien & Abhängigkeiten |
| 69 | + |
| 70 | +[](https://pve.proxmox.com/) |
| 71 | +[](https://www.debian.org/) |
| 72 | +[](https://ubuntu.com/) |
| 73 | +[](https://openjdk.org/) |
| 74 | +[](https://www.minecraft.net/) |
| 75 | +[](https://www.gnu.org/software/bash/) |
| 76 | +[](https://systemd.io/) |
| 77 | +[](https://www.gnu.org/software/screen/) |
| 78 | + |
| 79 | +## 📊 Status |
| 80 | + |
| 81 | +Stabil. VM und LXC getestet. PaperMC-API auf Fill v3 aktualisiert (März 2026). Bedrock-Updates bleiben manuell. |
| 82 | + |
| 83 | +## Schnellstart |
| 84 | + |
| 85 | +### VM (DHCP) |
| 86 | + |
| 87 | +```bash |
| 88 | +wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft.sh |
| 89 | +chmod +x setup_minecraft.sh |
| 90 | +./setup_minecraft.sh |
| 91 | +sudo -u minecraft screen -r minecraft |
| 92 | +``` |
| 93 | + |
| 94 | +> Debian 12/13: Stelle sicher, dass `/run/screen` mit `root:utmp` und Modus `0775` existiert (siehe unten). |
| 95 | +
|
| 96 | +### VM (statische IP) |
| 97 | + |
| 98 | +```bash |
| 99 | +sudo tee /etc/netplan/01-mc.yaml >/dev/null <<'YAML' |
| 100 | +network: |
| 101 | + version: 2 |
| 102 | + ethernets: |
| 103 | + ens18: |
| 104 | + addresses: [192.168.1.50/24] |
| 105 | + routes: [{ to: default, via: 192.168.1.1 }] |
| 106 | + nameservers: { addresses: [1.1.1.1,8.8.8.8] } |
| 107 | +YAML |
| 108 | +sudo netplan apply |
| 109 | +``` |
| 110 | + |
| 111 | +### LXC/CT |
| 112 | + |
| 113 | +```bash |
| 114 | +wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft_lxc.sh |
| 115 | +chmod +x setup_minecraft_lxc.sh |
| 116 | +./setup_minecraft_lxc.sh |
| 117 | +sudo -u minecraft screen -r minecraft |
| 118 | +``` |
| 119 | + |
| 120 | +### Bedrock |
| 121 | + |
| 122 | +```bash |
| 123 | +wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_bedrock.sh |
| 124 | +chmod +x setup_bedrock.sh |
| 125 | +./setup_bedrock.sh |
| 126 | +sudo -u minecraft screen -r bedrock |
| 127 | +``` |
| 128 | + |
| 129 | +## 🗃 Backups |
| 130 | + |
| 131 | +### Option A: systemd |
| 132 | + |
| 133 | +```bash |
| 134 | +sudo tee /etc/mc_backup.conf >/dev/null <<'EOF' |
| 135 | +MC_SRC_DIR=/opt/minecraft |
| 136 | +MC_BEDROCK_DIR=/opt/minecraft-bedrock |
| 137 | +BACKUP_DIR=/var/backups/minecraft |
| 138 | +RETAIN_DAYS=7 |
| 139 | +EOF |
| 140 | + |
| 141 | +sudo tee /etc/systemd/system/mc-backup.service >/dev/null <<'EOF' |
| 142 | +[Unit] |
| 143 | +Description=Minecraft backup (tar) |
| 144 | +[Service] |
| 145 | +Type=oneshot |
| 146 | +EnvironmentFile=/etc/mc_backup.conf |
| 147 | +ExecStart=/bin/mkdir -p "${BACKUP_DIR}" |
| 148 | +ExecStart=/bin/bash -c 'tar -czf "${BACKUP_DIR}/java-$(date +%%F).tar.gz" "${MC_SRC_DIR}"' |
| 149 | +ExecStart=/bin/bash -c '[ -d "${MC_BEDROCK_DIR}" ] && tar -czf "${BACKUP_DIR}/bedrock-$(date +%%F).tar.gz" "${MC_BEDROCK_DIR}" || true' |
| 150 | +ExecStartPost=/bin/bash -c 'find "${BACKUP_DIR}" -type f -name "*.tar.gz" -mtime +"${RETAIN_DAYS:-7}" -delete' |
| 151 | +EOF |
| 152 | + |
| 153 | +sudo tee /etc/systemd/system/mc-backup.timer >/dev/null <<'EOF' |
| 154 | +[Unit] |
| 155 | +Description=Nightly Minecraft backup |
| 156 | +[Timer] |
| 157 | +OnCalendar=*-*-* 03:30:00 |
| 158 | +Persistent=true |
| 159 | +[Install] |
| 160 | +WantedBy=timers.target |
| 161 | +EOF |
| 162 | + |
| 163 | +sudo systemctl daemon-reload |
| 164 | +sudo systemctl enable --now mc-backup.timer |
| 165 | +``` |
| 166 | + |
| 167 | +### Option B: cron |
| 168 | + |
| 169 | +```bash |
| 170 | +crontab -e |
| 171 | +30 3 * * * tar -czf /var/backups/minecraft/mc-$(date +\%F).tar.gz /opt/minecraft |
| 172 | +45 3 * * * tar -czf /var/backups/minecraft/bedrock-$(date +\%F).tar.gz /opt/minecraft-bedrock |
| 173 | +``` |
| 174 | + |
| 175 | +## ♻ Auto-Update |
| 176 | + |
| 177 | +Java Edition: `update.sh` (erstellt von `setup_minecraft.sh`) lädt den neuesten stabilen PaperMC-Build über die Fill-v3-API mit SHA256- und Größenprüfung. |
| 178 | + |
| 179 | +```bash |
| 180 | +cd /opt/minecraft && ./update.sh |
| 181 | +crontab -e |
| 182 | +0 4 * * 0 /opt/minecraft/update.sh >> /var/log/minecraft-update.log 2>&1 |
| 183 | +``` |
| 184 | + |
| 185 | +> Bedrock erfordert einen manuellen Download. Führe `setup_bedrock.sh` erneut aus, um zu aktualisieren. |
| 186 | +
|
| 187 | +## Konfiguration |
| 188 | + |
| 189 | +### JVM-Speicher (Java) |
| 190 | + |
| 191 | +Der Installer setzt `Xms ≈ RAM/4` und `Xmx ≈ RAM/2` mit Untergrenzen `1024M/2048M` und einer `Xmx`-Obergrenze von `≤16G`. Überschreiben in `/opt/minecraft/start.sh`. |
| 192 | + |
| 193 | +## Integrität & Firewall |
| 194 | + |
| 195 | +**Java (PaperMC):** |
| 196 | + |
| 197 | +- Der Paper-Download wird per **SHA256** aus der Fill-v3-API-Antwort verifiziert. |
| 198 | +- Mindestgröße `server.jar > 5 MB`, um das Speichern von HTML-Fehlerseiten zu vermeiden. |
| 199 | +- Es werden nur Builds des **STABLE**-Channels heruntergeladen (alpha/beta/experimental ausgeschlossen). |
| 200 | + |
| 201 | +**Bedrock:** |
| 202 | + |
| 203 | +| Modus | Verwendung | Verhalten | |
| 204 | +|---|---|---| |
| 205 | +| Standard (`REQUIRE_BEDROCK_SHA=0`) | Einfach `setup_bedrock.sh` ausführen | SHA256 wird berechnet und ausgegeben; kein vorgegebener Wert nötig. | |
| 206 | +| Strikt (`REQUIRE_BEDROCK_SHA=1`) | Vor dem Ausführen `export REQUIRED_BEDROCK_SHA256=<sha>` | Das Skript bricht ab, wenn der berechnete SHA nicht passt. | |
| 207 | + |
| 208 | +Mojang veröffentlicht keine Upstream-Prüfsummen. Um einen bekannten guten Wert festzuhalten: einmal im Standardmodus ausführen, den ausgegebenen SHA notieren, dann `REQUIRED_BEDROCK_SHA256` für künftige Läufe setzen. |
| 209 | + |
| 210 | +Zusätzlich validiert der Installer den MIME-Typ per HTTP HEAD (`application/zip|octet-stream`), prüft die Größe (>1 MB) und testet das ZIP mit `unzip -tq` vor dem Entpacken. |
| 211 | + |
| 212 | +**screen-Socket (Debian 12/13):** |
| 213 | + |
| 214 | +```bash |
| 215 | +sudo install -d -m 0775 -o root -g utmp /run/screen |
| 216 | +printf 'd /run/screen 0775 root utmp -\n' | sudo tee /etc/tmpfiles.d/screen.conf |
| 217 | +sudo systemd-tmpfiles --create /etc/tmpfiles.d/screen.conf |
| 218 | +``` |
| 219 | + |
| 220 | +> **LXC-Hinweis:** In unprivilegierten LXC-Containern existiert die Gruppe `utmp` möglicherweise nicht. Die Skripte fangen das ab, indem sie bei Bedarf auf `root:root` mit Modus `0777` zurückfallen. |
| 221 | +
|
| 222 | +**UFW:** |
| 223 | + |
| 224 | +```bash |
| 225 | +sudo apt-get install -y ufw |
| 226 | +sudo ufw allow 25565/tcp |
| 227 | +sudo ufw allow 19132/udp |
| 228 | +sudo ufw enable |
| 229 | +``` |
| 230 | + |
| 231 | +## Proxmox-CT-Helfer (Bedrock) |
| 232 | + |
| 233 | +`scripts/proxmox_create_ct_bedrock.sh` erstellt einen Debian-12-Container und installiert Bedrock automatisch. |
| 234 | + |
| 235 | +```bash |
| 236 | +bash scripts/proxmox_create_ct_bedrock.sh |
| 237 | +``` |
| 238 | + |
| 239 | +Am Ende wird ein zufälliges 16-stelliges Root-Passwort erzeugt und ausgegeben. **Ändere es sofort** nach dem ersten Login: |
| 240 | + |
| 241 | +```bash |
| 242 | +pct exec 121 -- passwd root |
| 243 | +``` |
| 244 | + |
| 245 | +Standardwerte über Umgebungsvariablen überschreiben: |
| 246 | + |
| 247 | +```bash |
| 248 | +STORE=local CTID=122 MEM=4096 bash scripts/proxmox_create_ct_bedrock.sh |
| 249 | +``` |
| 250 | + |
| 251 | +## PaperMC-API-Migration (v2 → Fill v3) |
| 252 | + |
| 253 | +Wenn du eine bestehende Installation mit dem alten Endpunkt `api.papermc.io/v2/` hast, führe das Setup-Skript erneut aus oder aktualisiere dein `update.sh` in `/opt/minecraft/` manuell. Die wichtigsten Änderungen: |
| 254 | + |
| 255 | +| Aspekt | Alt (v2) | Neu (Fill v3) | |
| 256 | +|---|---|---| |
| 257 | +| Basis-URL | `api.papermc.io/v2/projects/paper` | `fill.papermc.io/v3/projects/paper` | |
| 258 | +| Versionsfeld | Array → `.versions \| last` | Objekt → `.versions \| .[<neueste Gruppe>][0]` | |
| 259 | +| Build-Auswahl | `jq '.builds \| last'` | `jq 'map(select(.channel=="STABLE")) \| .[0]'` | |
| 260 | +| Download-URL | Manuell konstruiert | Eingebettet in `.downloads."server:default".url` | |
| 261 | +| SHA256 | `.downloads.application.sha256` | `.downloads."server:default".checksums.sha256` | |
| 262 | +| User-Agent | Nicht erforderlich | **Erforderlich** (ohne abgelehnt/gedrosselt) | |
| 263 | +| Abschaltung | 1. Juli 2026 | Aktiv und unterstützt | |
| 264 | + |
| 265 | +## 🕹 Admin/Befehle |
| 266 | + |
| 267 | +Siehe **[SERVER_COMMANDS.md](SERVER_COMMANDS.md)**. |
| 268 | + |
| 269 | +## ☕ Support / Spenden |
| 270 | + |
| 271 | +Wenn dir dieses Projekt Zeit spart, unterstütze die weitere Pflege gerne über [Buy Me A Coffee](https://buymeacoffee.com/timintech). |
| 272 | + |
| 273 | +## Fehlerbehebung |
| 274 | + |
| 275 | +- **`jq: Cannot index object with number`** → Alter `.versions | last`-Bug. Lade das Skript erneut von `main` herunter. |
| 276 | +- **PaperMC-Download schlägt mit 404 fehl (`curl: (22) ... 404`)** → Entweder nutzt du noch die alte v2-API, oder du hast ein älteres Fill-v3-Skript, dessen Versionslogik einen reinen Versionsgruppen-Key (z. B. `26.1`) statt einer echten Version (z. B. `26.1.2`) zurückgab, wodurch die `/versions/<v>/builds`-Anfrage einen 404 ergab. Lade das Skript erneut von `main` herunter (behoben in [#74](https://github.com/TimInTech/minecraft-server-Proxmox/issues/74)). |
| 277 | +- **Zu wenig RAM im LXC** → Werte in `start.sh` reduzieren. |
| 278 | +- **Fehlendes `/run/screen`** → Folge dem Abschnitt „screen-Socket" oben. |
| 279 | +- **`/run/screen` mit Modus 777 im LXC** → In unprivilegierten Containern existiert `utmp` möglicherweise nicht. Verwende `chmod 0777 /run/screen` oder stelle sicher, dass die Gruppe `utmp` gemappt ist. |
| 280 | +- **Bedrock-ZIP-MIME-Typ-Problem** → Besuche die Mojang-Download-Seite erneut. |
| 281 | +- **Java 17 funktioniert nicht mehr** → PaperMC 1.21.8+ benötigt Java 21. Führe den Installer erneut aus, um den Corretto-21-Fallback zu erhalten. |
| 282 | +- **Bedrock-SHA-Mismatch mit `REQUIRE_BEDROCK_SHA=1`** → Mojang veröffentlicht keine Upstream-Prüfsummen. Führe einmal mit `REQUIRE_BEDROCK_SHA=0` aus, notiere den ausgegebenen SHA, dann setze `REQUIRED_BEDROCK_SHA256`. |
| 283 | + |
| 284 | +Verwende die PR-Vorlage. Führe in diesem Workspace nichts aus. Siehe **[.github/copilot-instructions.md](.github/copilot-instructions.md)**. |
| 285 | + |
| 286 | +Details zum sicheren Simulations-Workflow findest du in **[SIMULATION.md](SIMULATION.md)**. |
| 287 | + |
| 288 | +> **Simulations-CLI:** Für den schrittweisen Copilot-CLI-Workflow siehe [.github/copilot-instructions.md](.github/copilot-instructions.md). |
| 289 | +
|
| 290 | +## Referenzen |
| 291 | + |
| 292 | +- PaperMC: <https://papermc.io/> |
| 293 | +- PaperMC Fill v3 API-Doku: <https://docs.papermc.io/misc/downloads-service/> |
| 294 | +- PaperMC Fill v3 Swagger: <https://fill.papermc.io/swagger-ui/index.html> |
| 295 | +- Proxmox-Wiki: <https://pve.proxmox.com/wiki/Main_Page> |
| 296 | +- Mojang Bedrock Server: <https://www.minecraft.net/en-us/download/server/bedrock> |
| 297 | + |
| 298 | +## Lizenz |
| 299 | + |
| 300 | +[MIT](LICENSE) |
0 commit comments