HRConvert2 selbst hosten: Dateikonverter auf dem VPS

Warum einen Dateikonverter selbst hosten

Ein selbst gehosteter Dateikonverter speichert die Datei auf Ihrer eigenen Festplatte. Das ist der wesentliche Grund, einen solchen Dienst zu betreiben. Eine kostenlose Konverter-Website nimmt den Upload entgegen, und Sie haben keine Möglichkeit festzustellen, was danach damit geschieht. Wenn es sich bei der Datei um einen unterschriebenen Kundenvertrag oder eine gescannte Krankenakte handelt, ist bereits der Upload der Sicherheitsvorfall. HRConvert2 ist ein per Drag-and-drop bedienbarer Dateikonvertierungsserver, der in PHP geschrieben ist und unter der GPLv3 lizenziert wird. Dieser Leitfaden basiert auf Version 3.7.4, die am 18. August 2026 veröffentlicht wurde. Das Projekt hat sich seitdem schnell weiterentwickelt: Die neueste Version zum 13. Oktober 2026 ist v3.9.1 und wurde am 6. September 2026 veröffentlicht. Das Projekt gibt an, 488 Formate zu unterstützen.

Es gibt keine Datenbank, keine Benutzerkonten und keine Cookies. Für jeden Benutzer wird ein temporäres Verzeichnis verwendet. Jede Konvertierung wird von einem lokalen Kommandozeilenprogramm ausgeführt: LibreOffice für Dokumente, FFmpeg für Audio und Video, ImageMagick für Bilder, Tesseract für optische Zeichenerkennung (OCR) sowie zahlreiche kleinere Tools für die übrigen Formate. HRConvert2 stellt die Upload-Seite, die Verarbeitungspipeline und die Bereinigung dieser Komponenten bereit.

Der Dienst konvertiert eine Datei von einem Format in ein anderes. Er ist keine browserbasierte Office-Suite. Wenn Sie möchten, dass Benutzer Dokumente in einem Browser-Tab bearbeiten, vergleichen Sie stattdessen selbst gehostetes OnlyOffice und Collabora. Der Dienst ist außerdem kein Speicher. Konvertierte Ausgabedateien sollten gelöscht werden. Wenn Dateien dauerhaft gespeichert werden müssen, ist das die Aufgabe von einem selbst gehosteten Dateimanager.

Was benötigt wird

Debian oder Ubuntu, Apache 2.4, PHP 8 oder höher sowie bubblewrap. Bubblewrap (bwrap) stellt die Sandbox bereit und ist zwingend erforderlich: Ein Server, der keine Sandbox erstellen kann, verweigert die Konvertierung, statt ohne Sandbox zu laufen. In der Upstream-README steht, dass ein Raspberry Pi Model B+ ausreicht. Das trifft auf den PHP-Teil zu. Die Binärdateien des Konverters bestimmen jedoch die tatsächlichen Hardwareanforderungen. Darauf gehen wir weiter unten ein.

Es gibt zwei Möglichkeiten. Das Docker-Image funktioniert noch heute. Die Installation von Apache und PHP dauert einen Abend und zeigt Ihnen genau, welche Komponenten auf dem System vorhanden sind.

Heute Abend mit Docker ausführen

Das Image enthält jedes Konverter-Binary und ist daher groß: Stand August 2026 etwa 3 GB. Prüfen Sie vor dem Pull, ob genügend Speicherplatz frei ist.

Tags sind hier wichtig. Diese Anleitung verwendet fest v3.7.2, den neuesten Tag auf Docker Hub am 17. August 2026 und zugleich das neueste GitHub-Release an diesem Tag. v3.7.4 folgte am 18. August. Am 13. Oktober 2026 ist das neueste GitHub-Release v3.9.1 (6. September 2026). Die neuesten Docker-Hub-Tags sind edge (22. September 2026) und latest, also v3.8.4 (31. August 2026). Der Tag latest kann sich ändern, und diese Anwendung bietet eine große Parser-Angriffsfläche. Legen Sie daher eine Version fest und führen Sie Upgrades bewusst durch.

docker pull zelon88/hrconvert2:v3.7.2
docker run -d --name hrconvert2 \
  -p 127.0.0.1:8080:80 \
  --security-opt seccomp=unconfined \
  zelon88/hrconvert2:v3.7.2

docker ps
curl -I http://127.0.0.1:8080/

Ein gesunder Container bleibt im Zustand Up, und curl gibt HTTP/1.1 200 OK zurück. Ein Container, der ständig neu startet, hat ein Startproblem. Lesen Sie daher zuerst docker logs hrconvert2, bevor Sie etwas anderes ändern.

Zwei Flags sind besonders wichtig. -p 127.0.0.1:8080:80 veröffentlicht den Port nur auf Loopback. Der Konverter ist dadurch nicht erreichbar, bis Sie bewusst einen Proxy davorschalten. Das aktuelle Beispiel des Projekts bindet -p 8080:80, das auf jeder Schnittstelle lauscht, einschließlich der öffentlichen. --security-opt seccomp=unconfined ist erforderlich, weil bubblewrap seine Sandbox mithilfe von User-Namespace- und Mount-Systemaufrufen erstellt, die das standardmäßige Docker-seccomp-Profil blockiert. Die Kommentare in config.php für Version 3.7 ergänzen, dass manche Hosts außerdem --security-opt apparmor=unconfined benötigen. Ohne dieses Flag schlagen Konvertierungen fehl. Die Anwendung erklärt den Grund: A sandbox blocks the required syscalls unless it was started with the correct options.

Dieses Flag ist ein echter Kompromiss. Sie lockern den Syscall-Filter des Containers, damit die Anwendung darin ihre eigene, strengere Sandbox erstellen kann. Die beiden Einstellungen, die das Verhalten bestimmen, sind $RequireSandbox und $RequireSandboxOnDocker in Resources/config.php. Das Release v3.7.4 liefert sie als TRUE und FALSE aus. Der hier festgelegte Tag v3.7.2 liefert beide als FALSE aus, weil seine Kommentare besagen, dass ein Container $RequireSandbox deaktiviert lassen und $RequireSandboxOnDocker entscheiden lassen muss. Da die Docker-Anforderung standardmäßig deaktiviert ist, kann ein Container ohne das Seccomp-Flag ohne Sandbox konvertieren. Sobald das Flag gesetzt ist, aktivieren Sie $RequireSandboxOnDocker = TRUE;, damit das gewünschte Ablehnungsverhalten im Container wieder gilt.

Neuere Images starten anders. Das Projekt änderte seinen Docker-Prozess in v3.8.0 (25. August 2026). Das aktuelle README und die Docker-Hub-Seite starten den Container mit --cap-add SYS_ADMIN statt mit der Seccomp-Option und geben an, dass Konvertierungen ohne diese Option abgelehnt werden. Wenn Sie Ihre Festlegung auf einen 3.8- oder 3.9-Tag ändern, verwenden Sie die Flags, die das jeweilige Image dokumentiert. Diese Berechtigung ist weitreichend. Behalten Sie daher die Bindung des 127.0.0.1-Ports bei.

Wenn Docker auf diesem Rechner neu ist, richten Sie zuerst den Daemon ein. Docker auf einem VPS ausführen behandelt die Installation, den Storage-Treiber und die Art, wie Docker seine eigenen Firewall-Regeln schreibt.

Stattdessen mit Apache und PHP installieren

Bis v3.7.4 beschrieb die Datei Documentation/INSTALLATION_INSTRUCTIONS.txt im Repository eine manuelle Installation in neun Schritten. Dieser Abschnitt folgt dieser Anleitung. Seit v3.8.0 beschreibt dieselbe Datei stattdessen ein Setup-Skript. Führen Sie sudo bash Documentation/Build/hrconvert2-setup.sh im geklonten Repository aus. Das Skript installiert die Abhängigkeiten, schreibt die PHP-Einstellungen als Drop-in-Datei, statt php.ini zu bearbeiten, und erweitert das AppArmor-Profil für bubblewrap. Mit php convertCore.php -v und --status prüfen Sie anschließend das Ergebnis. Der manuelle Weg dauert länger. Dafür ist genau nachvollziehbar, was auf dem System installiert wurde. Der Ablauf sieht so aus. Beginnen Sie mit Webserver, Sprache und Sandbox:

sudo apt update
sudo apt install -y apache2 php libapache2-mod-php php-all-dev php8.3-zip php8.3-gd bubblewrap

Die Namen in php8.3-* entsprechen Ubuntu 24.04. Führen Sie php -v aus und verwenden Sie das Präfix, das zu Ihrer Version passt. Die Paketnamen ändern sich mit jeder PHP-Version. Das falsche Präfix führt zu Unable to locate package.

Als Nächstes folgen die Konverter. Damit werden Dokumente, Bilder, Audio, Video und OCR abgedeckt. Das entspricht dem größten Teil der Konvertierungen in der Praxis:

sudo apt install -y imagemagick ffmpeg libreoffice-common libreoffice-java-common \
  default-jre ghostscript poppler-utils libgxps-utils tesseract-ocr inkscape \
  xvfb clamav curl tar libxcb-cursor0

Archivformate, 3D-Modelle, E-Books und bootfähige ISO-Images benötigen weitere Pakete. Einige davon befinden sich in der Ubuntu-Komponente multiverse. In v3.7.4 enthielt Schritt 3 der offiziellen Anleitung die vollständige apt-Paketliste. Schritt 5 beschrieb die Builds aus den Quellen. Die aktuelle Anleitung enthält keine Paketlisten. Das Installationsprogramm liest das Manifest Resources/Engine/Contract/depends.php. Mit php convertCore.php --setup --check-depends geben Sie die aktuelle Liste und ihren Status aus. Zwei Abhängigkeiten können ebenfalls aus den Quellen gebaut werden. Das Repository enthält Documentation/Build/ffmpeg-build.sh für Encoder, die in der paketierten FFmpeg-Version fehlen. Außerdem enthält es Documentation/Build/build-imagemagick-v7.sh für ImageMagick 7 auf Ubuntu 22.04 oder 24.04. Diese Versionen liefern weiterhin den Zweig 6.9 als Paket aus. Ubuntu 25.10 und 26.04 LTS liefern ImageMagick 7.1 als Paket aus. Die E-Book-Unterstützung kommt vom eigenen Installationsprogramm von calibre. Die Anleitung für v3.7 gab dafür eine einzelne Befehlszeile an:

sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdin

Dabei wird ein Anbieterskript als root in eine Shell weitergeleitet. Das ist die Methode des Upstream-Projekts und optional. Wenn Sie es überspringen, verlieren Sie nur die E-Book-Konvertierung.

Als Nächstes konfigurieren Sie die PHP-Limits. Konvertierungen dauern lange und Dateien können groß sein. Die Standardwerte sind daher zu niedrig. Die Anleitung für v3.7 setzte diese Werte in php.ini:

max_execution_time = 1200
max_input_time = 90
memory_limit = 512M
post_max_size = 5000M
upload_max_filesize = 5000M
max_file_uploads = 100
display_errors = Off
zlib.output_compression = On

Diese Werte setzen einen Rechner mit ausreichenden Ressourcen voraus. Reduzieren Sie sie, bevor Sie die Anwendung auf einem kleinen VPS einsetzen. upload_max_filesize = 5000M mit max_file_uploads = 100 beschreibt eine einzelne Anfrage, die deutlich mehr Daten schreiben kann, als auf eine 40-GB-Festplatte passen. Starten Sie Apache neu. Prüfen Sie anschließend, welche Werte PHP tatsächlich geladen hat:

sudo service apache2 restart
php -i | grep -E "upload_max_filesize|post_max_size|memory_limit"

Legen Sie jetzt das Arbeitsverzeichnis fest. $ConvertLoc in Resources/config.php benennt dieses Verzeichnis. Der Standardwert ist /DATA/HRConvert2. Der Benutzer des Webservers muss Eigentümer des Verzeichnisses sein:

sudo mkdir -p /DATA/HRConvert2
sudo chmod -R 0755 /DATA/HRConvert2
sudo chown -R www-data:www-data /DATA/HRConvert2

Entpacken Sie das Release unterhalb des Apache-Dokumentenstamms. Die Standardstruktur legt es in einem Ordner HRProprietary/HRConvert2 ab. $InstLoc in Resources/config.php muss den tatsächlichen Installationspfad enthalten. Führen Sie anschließend die integrierte Diagnose aus. Damit finden Sie fehlende Abhängigkeiten am schnellsten, bevor ein Benutzer darauf stößt:

sudo php /path/to/HRConvert2/convertCore.php -v

-v prüft die gesamte Installation: Core-Versionen, Abhängigkeiten, Sandbox-Status und Sprachpakete. Dateikonvertierungen werden über die Befehlszeile nicht unterstützt. Diese Argumente dienen daher ausschließlich der Administration.

Warum schlägt jede Konvertierung bei einer frischen Ubuntu-24.04-Installation fehl?

Die Ursache ist die Sandbox. Das ist am ersten Tag das mit Abstand häufigste Problem. Ubuntu 24.04 beschränkt nicht privilegierte User-Namespaces standardmäßig über AppArmor. Bubblewrap benötigt einen User-Namespace, um seine Sandbox zu erstellen. Deshalb kann bwrap nicht starten. Da die Anwendung Konvertierungen ohne Sandbox ablehnt, schlägt jeder einzelne Auftrag fehl.

Prüfen Sie dies direkt:

bwrap --ro-bind / / --dev /dev /bin/true && echo sandbox ok

Eine Fehlermeldung mit „permission denied“ bedeutet, dass der Namespace blockiert wurde. Die Lösung ist ein AppArmor-Profil für die Binärdatei bwrap. Listen Sie zuerst die ABI-Dateien auf und notieren Sie die höchste vorhandene Nummer:

ls /etc/apparmor.d/abi/

Schreiben Sie anschließend /etc/apparmor.d/bwrap. Ersetzen Sie 4.0 durch diese höchste Nummer:

abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}

Laden Sie das Profil:

sudo apparmor_parser -r /etc/apparmor.d/bwrap

Keine Ausgabe bedeutet, dass das Profil geladen wurde. Führen Sie die Prüfung bwrap erneut aus. Sie sollte sandbox ok ausgeben. Ab diesem Zeitpunkt funktionieren Konvertierungen.

Debian 12 hat dieses Problem nicht. Sein Kernel erlaubt nicht privilegierte User-Namespaces. Außerdem setzt das Paket bubblewrap beim Booten kernel.unprivileged_userns_clone auf 1. Daher ist die Prüfung oben dort auch ohne Profil erfolgreich. Ab v3.8.0 erweitert das Setup-Skript das AppArmor-Profil der Distribution für bubblewrap automatisch.

Ein öffentlicher Konverter ist ein Parser, der Fremden zugänglich ist

Für diesen Abschnitt wurde der restliche Beitrag geschrieben. Ein aus dem Internet erreichbarer Dateikonverter akzeptiert eine beliebige Datei von einer anonymen Person und übergibt sie an LibreOffice, ImageMagick, FFmpeg oder Ghostscript. Diese Programme basieren auf großen C- und C++-Codebasen mit einer langen Geschichte von Parser-Fehlern. Die hochladende Person wählt das Format. Damit bestimmt sie, welcher Parser ausgeführt wird und welcher Codepfad darin zum Einsatz kommt.

HRConvert2 führt jede Abhängigkeit in einem bubblewrap-Namespace aus. Jede Konvertierung sieht zwei Verzeichnisse: das Verzeichnis mit der Eingabedatei, das schreibgeschützt eingebunden wird, und das Verzeichnis, in dem die Ausgabe abgelegt wird. Das Netzwerk wird nicht gemeinsam genutzt. In den Worten des Projekts closes every URL handler in every dependency at once. Das ist wichtiger, als es zunächst klingt. ImageMagick und Ghostscript akzeptieren beide Referenzen, die eine URL abrufen. Dadurch kann ein Konverter zu einem Werkzeug für Server-Side Request Forgery (SSRF) werden, mit dem sich ein Cloud-Metadatenendpunkt aus Ihrem Netzwerk erreichen lässt. Ohne Netzwerk im Namespace kann der Abruf nicht stattfinden.

Die Verweigerung ist die andere Hälfte: A server that cannot build a sandbox refuses the conversion rather than quietly running without one. Ein Werkzeug, das bei Fehlern standardmäßig den Vorgang abbricht, ist wertvoller als eines, das eine Warnung in ein Protokoll schreibt, das niemand liest. Deshalb ist auch der oben beschriebene AppArmor-Schritt nicht optional. Außerdem sollten Sie $RequireSandboxOnDocker prüfen, bevor Sie den Container öffentlich zugänglich machen.

ImageMagick mit policy.xml härten

Die eigene Policy-Datei von ImageMagick bildet eine zweite Schutzschicht unterhalb der Sandbox und sollte konfiguriert werden. Unter Ubuntu 24.04 mit ImageMagick 6 befindet sich die Datei unter /etc/ImageMagick-6/policy.xml. Geben Sie die aktuell aktive Konfiguration aus:

identify -list policy

Das Projekt liefert unter Documentation/Build/policy.xml eine Policy mit, die sich als Vorlage eignet. Sie verweigert die Coder PS, PS2, PS3, EPS, XPS und MVG. Außerdem verweigert sie die Delegates URL, HTTPS, HTTP und gs, während sie PDF zulässt:

<policy domain="coder" rights="none" pattern="PS" />
<policy domain="coder" rights="none" pattern="MVG" />
<policy domain="delegate" rights="none" pattern="URL" />
<policy domain="delegate" rights="none" pattern="gs" />
<policy domain="coder" rights="read|write" pattern="PDF" />

Die Zeile mit gs ist entscheidend. ImageMagick verarbeitet PostScript nicht selbst. Stattdessen startet es Ghostscript als externen Prozess. In diesem Delegate liegen die bekannten Sicherheitslücken zur Remotecodeausführung in ImageMagick. Wenn Sie den Delegate verweigern, übergibt ImageMagick keine hochgeladene Datei an gs, unabhängig davon, welchen Dateityp die Datei angibt.

Dieselbe Policy legt Ressourcenlimits fest. Dadurch kann ein einzelnes manipuliertes Bild den Rechner nicht vollständig auslasten:

<policy domain="resource" name="memory" value="256MiB"/>
<policy domain="resource" name="map" value="512MiB"/>
<policy domain="resource" name="disk" value="1GiB"/>
<policy domain="resource" name="width" value="16KP"/>
<policy domain="resource" name="height" value="16KP"/>
<policy domain="resource" name="area" value="128MP"/>

Eine Dekompressionsbombe ist eine kleine Datei, die sehr große Dimensionen angibt. Die Limits width, height und area weisen die Datei zurück, bevor die Speicherzuweisung erfolgt. Der Prozess wird beendet, statt dass der Kernel einen anderen Prozess beendet.

In die andere Richtung gibt es eine wichtige Einschränkung. Die Standard-Policy von Ubuntu verweigert den Coder PDF vollständig. Auf einem unveränderten System schlägt die Verarbeitung von PDF-Dateien daher mit attempt to perform an operation not allowed by the security policy 'PDF' fehl. Diese Meldung zeigt, dass die Policy greift. Ob Sie den Coder wieder zulassen, müssen Sie bewusst entscheiden. Der Delegate gs bleibt dabei weiterhin verweigert.

Die Kosten der Abhängigkeitskette auf einem kleinen VPS

Im Leerlauf ist das alles nicht teuer. Apache und PHP belegen nur einige Dutzend Megabyte, und die Konverter-Binärdateien laufen überhaupt nicht. Die gesamten Kosten entstehen auf einmal, sobald eine Datei eingeht.

Eine Dokumentkonvertierung startet LibreOffice, das wiederum eine Java-Laufzeitumgebung startet. Eine Bildkonvertierung weist ImageMagick gemäß der obigen Richtlinie 256 MiB Arbeitsspeicher und eine 512 MiB große Speicherabbildung zu. Eine Videokonvertierung gibt FFmpeg jeden verfügbaren Kern, weil FFmpeg Videos auf diese Weise verarbeitet. memory_limit von PHP ist in der Projektkonfiguration auf 512M gesetzt. Diese Werte addieren sich während eines einzelnen Auftrags. Das Betriebssystem und der Webserver kommen noch hinzu.

Ein VPS mit 1 GB wechselt daher beim ersten echten Dokument auf den Swap und gerät anschließend in eine Auslastungsschleife. Wenn der Arbeitsspeicher knapp wird, beendet der Out-of-Memory-Killer des Kernels den Prozess mit der größten residenten Speichergröße. Meistens ist das soffice.bin. Der Benutzer sieht dann eine fehlgeschlagene Konvertierung ohne brauchbare Fehlermeldung. Manchmal ist es apache2, und die gesamte Website fällt aus. Nachträglich lässt sich das mit dmesg -T | grep -i "killed process" bestätigen.

Das ist eine Empfehlung zur Dimensionierung und kein Benchmark: 4 GB RAM und zwei Kerne bieten für ein kleines Team ausreichend Reserven. 2 GB mit einer Swap-Datei funktionieren ebenfalls, wenn hauptsächlich Dokumente und Bilder verarbeitet werden und Sie die Wartezeit akzeptieren. Eine Swap-Datei macht eine Konvertierung nicht schneller. Sie macht eine Lastspitze langsam statt fatal. Das ist der Unterschied zwischen einer blockierten Seite und einem Ausfall. Planen Sie mehr Speicherplatz ein, als zunächst erforderlich erscheint. Das 3-GB-Bild, ein großes Upload-Limit und die konvertierte Ausgabe füllen den Datenträger zusammen deutlich früher, als andere Ressourcen knapp werden.

Konvertierungen verursachen naturgemäß Lastspitzen. Zwei Personen, die gleichzeitig Videos hochladen, verwenden alle Kerne. Die nächste Anfrage wartet dann, bis sie abgeschlossen sind. Davor befindet sich keine Auftragswarteschlange. Die einzige Steuerungsmöglichkeit sind daher Limits.

Limits festlegen, die verhindern, dass ein einzelner Upload die Festplatte füllt

Reduzieren Sie zuerst die PHP-Werte. upload_max_filesize = 512M, post_max_size = 512M und max_file_uploads = 20 sind ein sinnvoller Ausgangspunkt für einen gemeinsam genutzten Server mit 4 GB. Beachten Sie, dass max_execution_time = 1200 eine PHP-Anfrage bis zu zwanzig Minuten ausführen lässt. Das ist für eine lange Videokonvertierung erforderlich. Gleichzeitig belegt ein langsamer Upload dadurch zwanzig Minuten lang einen Worker.

Begrenzen Sie Größe und Rate anschließend am Proxy, bevor die Anfrage PHP überhaupt erreicht:

limit_req_zone $binary_remote_addr zone=convert:10m rate=6r/m;

server {
    listen 443 ssl;
    server_name convert.example.com;

    client_max_body_size 512M;
    client_body_timeout 300s;

    location / {
        limit_req zone=convert burst=4 nodelay;
        proxy_pass http://127.0.0.1:8080;
        proxy_read_timeout 1200s;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

client_max_body_size muss mindestens so groß sein wie die größte Datei, die Sie konvertieren möchten. Andernfalls antwortet nginx mit 413 Request Entity Too Large, und PHP erhält den Upload nie. proxy_read_timeout muss länger sein als Ihre längste Konvertierung. Andernfalls gibt ein Auftrag, der hinter dem Proxy problemlos ausgeführt wird, im Browser 504 Gateway Time-out zurück. Der restliche Server-Block einschließlich der TLS-Terminierung (Transport Layer Security) wird in einer zeilenweisen Erklärung einer nginx-Reverse-Proxy-Konfiguration behandelt.

Konvertierte Dateien löschen

Jede Konvertierung hinterlässt eine Kopie einer vertraulichen Datei in einem Verzeichnis, das der Webserver lesen kann. Die Bereinigung unterscheidet einen Konverter von einem Archiv aller Dateien, die jemals darauf konvertiert wurden.

$DeleteThreshold in Resources/config.php gibt das Alter in Minuten an, nach dem eine Sitzung abläuft. Der Standardwert ist 60. Bei vertraulichen Inhalten sollten Sie den Wert auf 15 reduzieren. Der Bereinigungslauf selbst wird als Befehlszeilenargument an den Core übergeben:

sudo -u www-data php /path/to/HRConvert2/convertCore.php -c
sudo -u www-data php /path/to/HRConvert2/convertCore.php -c=15

-c löscht abgelaufene Sitzungen aus beiden Datenverzeichnissen anhand des konfigurierten Schwellenwerts. -c=15 verwendet für diesen Lauf nur fünfzehn Minuten. -c=now löscht jede Sitzung unabhängig von ihrem Alter, einschließlich der Sitzung, die ein Benutzer gerade für eine Konvertierung verwendet. Verwenden Sie diesen Befehl daher nur für Wartungsarbeiten. Dieselben Argumente funktionieren innerhalb des Containers über docker exec.

Führen Sie die Bereinigung über einen Timer aus, damit sie nie davon abhängt, dass jemand eine Seite lädt. Eine Zeile in /etc/cron.d/hrconvert2 genügt:

*/10 * * * * www-data php /path/to/HRConvert2/convertCore.php -c

Prüfen Sie den Timer einige Minuten später mit ls /DATA/HRConvert2 und beobachten Sie, wie alte Sitzungsverzeichnisse verschwinden. Da der Webserver-Benutzer Eigentümer dieses Verzeichnisses ist, hätte ein kompromittierter Parser genau die Rechte dieses Kontos. Das Konto sollte daher keine weiteren wertvollen Ressourcen besitzen. Benutzerkonten mit den geringsten erforderlichen Rechten auf einem VPS ist das allgemeine Muster. Hier ist es besonders wichtig.

Stellen Sie eine Authentifizierung davor, sofern keine öffentliche Erreichbarkeit erforderlich ist

Die Standardinstallation enthält absichtlich keine Konten. Jeder, der die Seite erreichen kann, kann eine Datei hochladen und Ihre Konverter-Binärdateien ausführen. Ratenbegrenzungen verlangsamen dies lediglich. Legen Sie daher fest, welche Situation auf Sie zutrifft.

Wenn Sie den Dienst selbst und mit wenigen Kollegen verwenden, sollten Sie ihn überhaupt nicht öffentlich erreichbar machen. Binden Sie den Container wie oben gezeigt an Loopback und greifen Sie über ein privates Netzwerk oder einen SSH-Tunnel darauf zu. Dann kann niemand aus dem öffentlichen Internet eine Datei an den Dienst senden. Dadurch entfällt die gesamte Angriffsfläche, statt sie lediglich zu filtern. Wenn diese Kollegen die Seite in einem Browser öffnen müssen, ohne dass Sie einen Hostnamen veröffentlichen oder einen Port öffnen, hält der Betrieb als v3-Onion-Service den Konverter an Loopback gebunden und stellt ihnen trotzdem eine aufrufbare Adresse bereit.

Wenn der Dienst über einen Browser erreichbar sein muss, schalten Sie eine Authentifizierung vor den Proxy. Basic Auth lässt sich mit zwei Befehlen einrichten und hält das Upload-Formular von Fremden fern:

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd alice

location / {
    auth_basic "Converter";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:8080;
}

Laden Sie nginx neu und rufen Sie die Seite auf. Eine Eingabeaufforderung zeigt, dass die Konfiguration funktioniert. Wird keine Eingabeaufforderung angezeigt, verarbeitet der von Ihnen bearbeitete location-Block die Anfrage nicht. Für echte Konten statt eines gemeinsamen Passworts beenden Sie die Authentifizierung bei einem Single-Sign-on-Anbieter: ein selbst gehosteter Authentik-SSO-Server ermöglicht eine vorgeschaltete Authentifizierung vor einer Anwendung, die keine eigene Anmeldung besitzt.

Wenn das Ziel ein wirklich öffentlicher Konverter ist, müssen Sie die Konsequenzen akzeptieren und entsprechend planen. Gehen Sie davon aus, dass die Sandbox gezielt untersucht wird. Fixieren Sie das Image-Tag, halten Sie die ImageMagick-Richtlinie restriktiv, begrenzen Sie die Uploads auf kleine Größen und betreiben Sie den Dienst auf einem VPS, auf dem sich nichts anderes befindet, das für Sie wichtig ist.

Fehlerbilder und die angezeigten Meldungen

Jede Konvertierung schlägt sofort fehl. Die Sandbox kann nicht erstellt werden. Bei einer normalen Ubuntu-24.04-Installation ist dafür das AppArmor-Profil verantwortlich. Im festgelegten 3.7-Docker-Image fehlt --security-opt seccomp=unconfined. Die Anwendung meldet: A sandbox blocks the required syscalls unless it was started with the correct options. und verweist auf See --Require Sandbox-- & --Require Sandbox On Docker-- in config.php.

Nur Bildkonvertierungen schlagen fehl. Bubblewrap is missing or non functional, so this image conversion cannot be isolated! bedeutet, dass bwrap fehlt oder über den Pfad, den der Webserver-Benutzer verwendet, nicht erreichbar ist.

Ein Format schlägt fehl, die übrigen funktionieren. Eine Binärdatei fehlt. Die Meldung lautet eindeutig: ImageMagick may not be installed, or may not be reachable on the system path used by the web server user. Dieselbe Meldung gibt es für FFmpeg und LibreOffice. Führen Sie convertCore.php -v aus, um zu sehen, was die Installation findet. Beachten Sie, dass der PATH des Apache-Workers nicht dem PATH Ihrer Login-Shell entspricht.

PDF-Verarbeitung schlägt mit einem Policy-Fehler fehl. attempt to perform an operation not allowed by the security policy 'PDF' stammt aus der policy.xml von ImageMagick und nicht aus HRConvert2.

Große Uploads liefern 413 zurück. client_max_body_size von nginx ist kleiner als die Datei. In der Kette gibt es drei Limits: eines in nginx und zwei in PHP. Das kleinste Limit gilt.

Konvertierungen werden beendet, obwohl scheinbar nichts geändert wurde. The device where data is stored has an insufficient amount of storage space available. Prüfen Sie den freien Speicherplatz und ob der Bereinigungslauf tatsächlich ausgeführt wird.

Die Bereinigung erzeugt Fehlermeldungen im Log. Could not clean the temporary location! und Could not clean the convert location! sind Eigentumsprobleme. Der Webserver-Benutzer muss Eigentümer des von $ConvertLoc angegebenen Verzeichnisses sein.

FAQ

Ist es sicher, einen selbst gehosteten Dateikonverter im Internet bereitzustellen?

Das ist nur dann ausreichend sicher, wenn Sie ihn wie einen Parser behandeln, der nicht vertrauenswürdigen Benutzern offensteht. Jeder Upload wird an LibreOffice, ImageMagick, FFmpeg oder Ghostscript übergeben. Die hochladende Person bestimmt, welches dieser Programme verwendet wird. HRConvert2 führt diese Werkzeuge in einem bubblewrap-Namespace ohne Netzwerkzugriff und mit einem schreibgeschützten Eingabeverzeichnis aus. Konvertierungen, die nicht in einer Sandbox ausgeführt werden können, werden abgelehnt. Das ist eine robuste Standardeinstellung. Trotzdem sollten Sie eine Authentifizierung verlangen, die Upload-Limits niedrig halten und den Dienst auf einem VPS betreiben, auf dem keine anderen wichtigen Daten liegen.

Warum schlägt jede Konvertierung bei einer neuen Ubuntu-24.04-Installation fehl?

Ubuntu 24.04 beschränkt nicht privilegierte User-Namespaces durch AppArmor. bubblewrap benötigt einen solchen Namespace, um seine Sandbox zu erstellen. Da die Anwendung Konvertierungen ohne Sandbox ablehnt, schlagen alle Aufträge fehl. Schreiben Sie mit /usr/bin/bwrap ein AppArmor-Profil für flags=(unconfined), laden Sie es mit sudo apparmor_parser -r /etc/apparmor.d/bwrap und prüfen Sie das Ergebnis anschließend mit bwrap --ro-bind / / --dev /dev /bin/true. Debian 12 erlaubt nicht privilegierte User-Namespaces standardmäßig und benötigt diesen Schritt nicht.

Warum schlagen Konvertierungen in Docker fehl, funktionieren aber in einer normalen Installation?

Das standardmäßige seccomp-Profil von Docker blockiert die Systemaufrufe, die bubblewrap verwendet. Daher kann die Sandbox innerhalb des Containers nicht erstellt werden. Starten Sie das hier festgelegte Image 3.7 mit --security-opt seccomp=unconfined. Dies entspricht den Kommentaren config.php in dieser Version. Ab v3.8.0 dokumentiert das Projekt stattdessen --cap-add SYS_ADMIN. Beachten Sie, dass $RequireSandboxOnDocker standardmäßig auf FALSE gesetzt ist. Ein Container ohne dieses Flag kann daher vollständig ohne Sandbox konvertieren. Setzen Sie den Wert auf TRUE, sobald das seccomp-Flag aktiv ist.

Wie viel RAM benötigt ein Server für Dateikonvertierungen?

Im Leerlauf ist der Speicherbedarf gering. Eine laufende Konvertierung benötigt jedoch deutlich mehr Ressourcen. LibreOffice startet eine Java-Laufzeitumgebung. ImageMagick verwendet unter der mitgelieferten Richtlinie 256 MiB Speicher und ein 512 MiB großes Mapping. Das PHP-eigene Limit beträgt 512M. Auf einem VPS mit 1 GB führt diese Kombination zu Swap-Aktivität, und der Out-of-Memory-Killer beendet soffice.bin oder apache2. Planen Sie für ein kleines Team 4 GB RAM und zwei CPU-Kerne ein. Prüfen Sie dmesg -T | grep -i "killed process", wenn eine Konvertierung ohne Fehlermeldung beendet wird.

Wo werden konvertierte Dateien gespeichert, und wann werden sie gelöscht?

Sie werden im Arbeitsverzeichnis gespeichert, das in Resources/config.php durch $ConvertLoc festgelegt wird. Standardmäßig ist dies /DATA/HRConvert2. $DeleteThreshold legt fest, nach wie vielen Minuten eine Sitzung abläuft. Der Standardwert ist 60. Die Bereinigung wird über die Befehlszeile ausgeführt: php convertCore.php -c löscht abgelaufene Sitzungen. -c=now löscht sofort alle Sitzungen, einschließlich aktiver Sitzungen. Fügen Sie -c einem cron-Eintrag oder einem systemd-Timer hinzu, damit die Löschung nicht davon abhängt, dass jemand die Website besucht.