Jak samodzielnie hostować konwerter plików HRConvert2

Dlaczego warto samodzielnie hostować konwerter plików

Samodzielnie hostowany konwerter plików pozwala zachować pliki na własnym dysku. To jedyny powód, dla którego warto go uruchomić. Darmowe serwisy konwertujące przyjmują przesłany plik, nie dając żadnej gwarancji, co się z nim później dzieje. W przypadku podpisanego kontraktu z klientem lub zeskanowanej dokumentacji medycznej, samo przesłanie pliku stanowi incydent bezpieczeństwa. HRConvert2 to serwer do konwersji plików typu „przeciągnij i upuść”, napisany w PHP i udostępniony na licencji GPLv3. Wersja 3.7.4 została wydana 18 sierpnia 2026 roku, a projekt deklaruje obsługę 488 formatów.

Narzędzie nie korzysta z bazy danych, nie posiada kont użytkowników ani plików cookie. Użytkownik jest traktowany jako katalog tymczasowy. Każda konwersja jest wykonywana przez lokalne narzędzie wiersza poleceń: LibreOffice dla dokumentów, FFmpeg dla audio i wideo, ImageMagick dla obrazów, Tesseract do optycznego rozpoznawania znaków (OCR) oraz szereg mniejszych narzędzi dla pozostałych formatów. HRConvert2 stanowi stronę przesyłania, potok przetwarzania oraz mechanizm czyszczenia plików.

Aplikacja służy do zmiany formatu pliku. Nie jest to pakiet biurowy w przeglądarce, więc jeśli celem jest edycja dokumentów w karcie przeglądarki, należy rozważyć samodzielnie hostowane OnlyOffice i Collabora. Nie jest to również rozwiązanie do przechowywania danych. Przekonwertowane pliki powinny być usuwane, więc jeśli pliki mają być trwale przechowywane, zadanie to należy powierzyć samodzielnie hostowanemu menedżerowi plików.

Wymagania

System Debian lub Ubuntu, Apache 2.4, PHP 8 lub nowszy oraz bubblewrap. Bubblewrap (bwrap) stanowi środowisko izolowane (sandbox) i jest wymagany: serwer, który nie może utworzyć środowiska izolowanego, odmawia przeprowadzenia konwersji zamiast uruchamiać proces bez zabezpieczeń. Dokumentacja upstream wskazuje, że Raspberry Pi Model B+ jest wystarczające dla części PHP. Binaria konwertera określają rzeczywiste wymagania sprzętowe, co zostało opisane w dalszej części.

Dostępne są dwie metody instalacji. Obraz Docker pozwala na uruchomienie usługi natychmiast. Instalacja Apache i PHP zajmuje jeden wieczór i pozwala na pełną weryfikację zawartości serwera.

Uruchomienie w nocy przy użyciu Docker

Obraz zawiera wszystkie pliki binarne konwerterów, dlatego jest duży: około 3 GB według stanu na sierpień 2026. Przed pobraniem sprawdź ilość wolnego miejsca na dysku.

Tagi mają tutaj znaczenie. Najnowszy tag opublikowany w Docker Hub na dzień 17 sierpnia 2026 to v3.7.2, podczas gdy najnowsze wydanie na GitHub to v3.7.4. Tag latest jest zmienny, a ponieważ aplikacja posiada dużą powierzchnię parsowania, należy przypiąć konkretną wersję i aktualizować ją świadomie.

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/

Poprawnie działający kontener pozostaje w stanie Up, a polecenie curl zwraca HTTP/1.1 200 OK. Kontener, który ciągle się restartuje, ma problem przy starcie, dlatego przed wprowadzeniem jakichkolwiek zmian należy przeczytać docker logs hrconvert2.

Dwie flagi mają kluczowe znaczenie. Flaga -p 127.0.0.1:8080:80 publikuje port tylko na interfejsie loopback, więc nic nie dotrze do konwertera, dopóki celowo nie umieścisz przed nim proxy. Przykład z projektu mapuje -p 8080:80 -p 8443:443, co powoduje nasłuchiwanie na wszystkich interfejsach, w tym publicznym. Flaga --security-opt seccomp=unconfined jest wymagana, ponieważ bubblewrap buduje swoją piaskownicę (sandbox) przy użyciu wywołań systemowych user namespace oraz mount, które domyślny profil seccomp w Docker blokuje. Bez tej flagi konwersje kończą się niepowodzeniem, a aplikacja informuje o przyczynie: A sandbox blocks the required syscalls unless it was started with the correct options.

Ta flaga to istotny kompromis. Rozluźniasz filtr wywołań systemowych kontenera, aby aplikacja mogła zbudować własną, ściślejszą piaskownicę wewnątrz. Dwa ustawienia decydujące o zachowaniu to $RequireSandbox oraz $RequireSandboxOnDocker w pliku Resources/config.php, które domyślnie mają wartości TRUE i FALSE. Ponieważ wymaganie Dockera jest domyślnie wyłączone, kontener bez flagi seccomp może przeprowadzać konwersję bez żadnej piaskownicy. Gdy flaga jest aktywna, ustaw $RequireSandboxOnDocker = TRUE;, aby przywrócić zachowanie polegające na odmowie dostępu wewnątrz kontenera.

Jeśli Docker jest nową instalacją na tej maszynie, najpierw skonfiguruj demona. Uruchamianie Docker na VPS omawia instalację, sterownik pamięci masowej oraz sposób, w jaki Docker tworzy własne reguły zapory sieciowej.

Instalacja na Apache i PHP

Plik Documentation/INSTALLATION_INSTRUCTIONS.txt w repozytorium jest dokumentacją nadrzędną i obejmuje dziewięć kroków. Oto ich przebieg. Rozpocznij od serwera WWW, języka oraz środowiska izolowanego:

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

Nazwy php8.3-* odpowiadają systemowi Ubuntu 24.04. Uruchom php -v i użyj prefiksu zgodnego z posiadaną wersją, ponieważ nazwy pakietów zmieniają się wraz z każdym wydaniem PHP, a błędny wybór spowoduje Unable to locate package.

Następnie zainstaluj konwertery. Obejmują one dokumenty, obrazy, dźwięk, wideo oraz OCR, co stanowi większość typowych konwersji:

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

Formaty archiwów, modele 3D, e-booki oraz startowe obrazy ISO wymagają dodatkowych pakietów, z których część znajduje się w komponencie multiverse systemu Ubuntu. Kroki 3 i 5 oficjalnej instrukcji zawierają pełną listę w odpowiedniej kolejności. Dwie zależności nie są pakietami apt: repozytorium dostarcza Documentation/Build/ffmpeg-build.sh oraz Documentation/Build/build-imagemagick-v7.sh dla użytkowników wymagających enkoderów lub wersji ImageMagick 7, której Ubuntu nie posiada w swoich pakietach. Obsługa e-booków pochodzi z instalatora calibre, który w instrukcji podano jako jedną linię:

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

Jest to skrypt dostawcy przesyłany potokiem do powłoki z uprawnieniami root. Jest to zalecana metoda producenta i jest opcjonalna: pominięcie jej spowoduje jedynie brak możliwości konwersji e-booków.

Następnie skonfiguruj limity PHP. Konwersje są procesami długotrwałymi, a pliki zajmują dużo miejsca, dlatego wartości domyślne są zbyt niskie. Projekt definiuje je w 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

Wartości te zakładają posiadanie maszyny z odpowiednią ilością zasobów. Obniż je przed uruchomieniem na małym VPS, ponieważ upload_max_filesize = 5000M wraz z max_file_uploads = 100 opisuje pojedyncze żądanie, które może zapisać znacznie więcej danych, niż mieści dysk o pojemności 40 GB. Zrestartuj Apache i sprawdź, jakie wartości PHP zostały faktycznie załadowane:

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

Teraz skonfiguruj katalog roboczy. $ConvertLoc w Resources/config.php wskazuje jego nazwę, a wartością domyślną jest /DATA/HRConvert2. Użytkownik serwera WWW musi być właścicielem tego katalogu:

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

Rozpakuj wydanie w katalogu głównym dokumentów Apache. Domyślny układ umieszcza je w folderze HRProprietary/HRConvert2, a $InstLoc w Resources/config.php musi wskazywać rzeczywistą lokalizację plików. Następnie uruchom wbudowaną diagnostykę, co jest najszybszym sposobem na wykrycie brakujących zależności przed użytkownikami:

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

-v weryfikuje całą instalację: wersje rdzenia, sprawdzenie zależności, status środowiska izolowanego oraz pakiety językowe. Konwersja plików nie jest obsługiwana z poziomu wiersza poleceń, więc ten zestaw argumentów służy wyłącznie do celów administracyjnych.

Dlaczego każda konwersja kończy się niepowodzeniem na świeżej instalacji Ubuntu 24.04?

Przyczyną jest piaskownica (sandbox) i jest to najczęstszy problem pierwszego dnia. Systemy Ubuntu 24.04 oraz Debian 12 domyślnie ograniczają przestrzenie nazw użytkowników bez uprawnień (unprivileged user namespaces). Bubblewrap wymaga przestrzeni nazw użytkownika do zbudowania swojej piaskownicy, dlatego bwrap nie może się uruchomić, a ponieważ aplikacja odmawia konwersji bez piaskownicy, każde zadanie kończy się błędem.

Sprawdź to bezpośrednio:

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

Błąd "permission denied" oznacza, że przestrzeń nazw została zablokowana. Rozwiązaniem jest profil AppArmor dla pliku binarnego bwrap. Najpierw wyświetl listę plików ABI i zanotuj najwyższą obecną liczbę:

ls /etc/apparmor.d/abi/

Następnie utwórz /etc/apparmor.d/bwrap, zastępując 4.0 tą najwyższą liczbą:

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

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

Załaduj profil:

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

Brak komunikatu wyjściowego oznacza, że profil został załadowany. Uruchom ponownie test bwrap; powinien on wyświetlić sandbox ok. Od tego momentu konwersje będą działać.

Publiczny konwerter to parser udostępniony osobom z zewnątrz

Ta sekcja stanowi główny cel niniejszego wpisu. Konwerter plików dostępny z poziomu Internetu przyjmuje dowolny plik od anonimowego użytkownika i przekazuje go do LibreOffice, ImageMagick, FFmpeg lub Ghostscript. Są to rozbudowane bazy kodu w C i C++, posiadające długą historię błędów w parserach. Użytkownik przesyłający plik wybiera format, co oznacza, że wybiera również parser, który zostanie uruchomiony, oraz ścieżkę wykonania kodu wewnątrz niego.

Rozwiązaniem HRConvert2 jest uruchamianie każdej zależności wewnątrz przestrzeni nazw bubblewrap. Każda konwersja widzi dwa katalogi: ten zawierający dane wejściowe, zamontowany w trybie tylko do odczytu, oraz ten, do którego trafia wynik. Sieć jest odizolowana, co, jak podaje projekt, closes every URL handler in every dependency at once. Ma to większe znaczenie, niż mogłoby się wydawać. Zarówno ImageMagick, jak i Ghostscript akceptują odwołania pobierające dane z URL, co sprawia, że konwerter może stać się narzędziem do przeprowadzania ataków typu server side request forgery (SSRF), służącym do uzyskania dostępu do punktu końcowego metadanych chmury z wnętrza sieci. Brak dostępu do sieci w przestrzeni nazw uniemożliwia takie pobranie.

Odmowa wykonania operacji to druga połowa zabezpieczeń: A server that cannot build a sandbox refuses the conversion rather than quietly running without one. Narzędzie, które w razie błędu blokuje działanie, jest cenniejsze niż takie, które jedynie wysyła ostrzeżenie do dziennika, którego nikt nie czyta. Jest to również powód, dla którego krok z AppArmor opisany powyżej nie jest opcjonalny, oraz dlaczego $RequireSandboxOnDocker warto rozważyć przed wystawieniem kontenera na zewnątrz.

Utwardzanie ImageMagick za pomocą policy.xml

Własny plik polityki ImageMagick stanowi drugą warstwę zabezpieczeń pod piaskownicą i warto go skonfigurować. W systemie Ubuntu 24.04 z ImageMagick 6 plik ten znajduje się w /etc/ImageMagick-6/policy.xml. Wyświetl aktualnie aktywną konfigurację:

identify -list policy

Projekt dostarcza przykładową politykę w Documentation/Build/policy.xml, która stanowi dobry wzorzec. Blokuje ona koderzy PS, PS2, PS3, EPS, XPS oraz MVG, a także delegaty URL, HTTPS, HTTP i gs, zezwalając jednocześnie na PDF:

<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" />

Linia gs jest kluczowa. ImageMagick nie analizuje samodzielnie plików PostScript. Wywołuje w tym celu Ghostscript, a to właśnie w tym delegacie występują znane luki umożliwiające zdalne wykonanie kodu (RCE) w ImageMagick. Zablokowanie delegata sprawia, że ImageMagick w ogóle nie przekaże przesłanego pliku do gs, niezależnie od tego, za co plik się podaje.

Ta sama polityka ustala limity zasobów, co zapobiega sytuacji, w której spreparowany obraz wyczerpuje zasoby maszyny:

<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"/>

Bomba dekompresyjna to niewielki plik, który deklaruje ogromne wymiary. Limity width, height oraz area odrzucają go przed dokonaniem alokacji, dzięki czemu proces kończy się poprawnie, zamiast zostać zabitym przez jądro systemu.

Istnieje jednak pułapka w drugą stronę. Domyślna polityka Ubuntu całkowicie blokuje koder PDF, więc w niezmodyfikowanym systemie operacje na plikach PDF kończą się błędem attempt to perform an operation not allowed by the security policy 'PDF'. Ten komunikat oznacza, że polityka działa zgodnie z przeznaczeniem. Przywrócenie dostępu do kodera jest świadomą decyzją, przy której należy zachować zablokowany delegat gs.

Koszt łańcucha zależności na małym VPS

W stanie spoczynku żadna z tych usług nie jest kosztowna. Apache i PHP zajmują kilkadziesiąt megabajtów, a pliki binarne konwerterów nie są uruchomione. Cały koszt pojawia się w momencie przesłania pliku.

Konwersja dokumentu uruchamia LibreOffice, który z kolei inicjuje środowisko uruchomieniowe Java. Konwersja obrazu przydziela ImageMagick 256 MiB pamięci oraz 512 MiB mapowania pamięci zgodnie z powyższą polityką. Konwersja wideo przydziela FFmpeg wszystkie dostępne rdzenie, ponieważ tak działa FFmpeg przy przetwarzaniu wideo. Własny memory_limit dla PHP jest ustawiony na 512M w konfiguracji projektu. Wartości te sumują się podczas pojedynczego zadania, nakładając się na zużycie zasobów przez system operacyjny i serwer WWW.

Z tego powodu VPS z 1 GB pamięci RAM zaczyna korzystać ze swapu przy pierwszym większym dokumencie, a następnie wpada w stan thrashingu. Gdy pamięć się wyczerpie, mechanizm out of memory killer jądra systemu kończy proces o największym rozmiarze rezydentnym. Zazwyczaj jest to soffice.bin, a użytkownik otrzymuje informację o nieudanej konwersji bez żadnego użytecznego komunikatu. Czasami jest to apache2, co powoduje awarię całej witryny. Można to potwierdzić po fakcie za pomocą dmesg -T | grep -i "killed process".

Poniższe wskazówki dotyczące doboru rozmiaru serwera nie są wynikami benchmarków: 4 GB pamięci RAM i dwa rdzenie zapewniają komfortową pracę dla małego zespołu, natomiast 2 GB z plikiem wymiany (swap) wystarczą, jeśli obciążenie stanowią dokumenty i obrazy, a użytkownik akceptuje czas oczekiwania. Plik wymiany nie przyspiesza konwersji. Sprawia jedynie, że nagły wzrost zapotrzebowania na zasoby powoduje spowolnienie, a nie błąd krytyczny, co stanowi różnicę między zawieszeniem strony a całkowitą awarią. Należy przydzielić dyskowi więcej miejsca, niż wydaje się to konieczne, ponieważ plik obrazu o rozmiarze 3 GB, wysoki limit przesyłania oraz przekonwertowany wynik końcowy zapełnią dysk znacznie szybciej niż wyczerpią się inne zasoby.

Konwersje mają z natury charakter skokowy. Dwie osoby przesyłające wideo w tym samym czasie wykorzystają wszystkie dostępne rdzenie, a kolejne żądanie będzie musiało czekać w kolejce. Ponieważ przed tym procesem nie ma kolejki zadań, jedyną dostępną formą kontroli są limity.

Ustawienie limitów zapobiegających zapełnieniu dysku przez pojedyncze przesłanie

Najpierw należy ograniczyć wartości PHP. Ustawienia takie jak upload_max_filesize = 512M, post_max_size = 512M oraz max_file_uploads = 20 stanowią rozsądny punkt wyjścia dla współdzielonego serwera o pojemności 4 GB. Należy pamiętać, że max_execution_time = 1200 pozwala pojedynczemu żądaniu PHP działać przez dwadzieścia minut, co jest niezbędne przy długiej konwersji wideo, ale oznacza również, że wolne przesyłanie blokuje proces roboczy na dwadzieścia minut.

Następnie należy wymusić limity rozmiaru i czasu na poziomie proxy, zanim żądanie dotrze do PHP:

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;
    }
}

Wartość client_max_body_size musi być co najmniej tak duża, jak największy plik przeznaczony do konwersji, w przeciwnym razie nginx zwróci 413 Request Entity Too Large, a PHP nigdy nie otrzyma przesyłanego pliku. Wartość proxy_read_timeout musi przekraczać czas trwania najdłuższej konwersji, inaczej zadanie działające poprawnie za proxy zwróci 504 Gateway Time-out do przeglądarki. Pozostała część tego bloku serwera, w tym terminacja TLS (transport layer security), została omówiona w szczegółowym wyjaśnieniu konfiguracji reverse proxy nginx.

Usuwanie przekonwertowanych plików

Każda konwersja pozostawia kopię poufnego pliku w katalogu dostępnym dla serwera WWW. Regularne czyszczenie odróżnia konwerter od archiwum wszystkich plików, które kiedykolwiek zostały na nim przetworzone.

$DeleteThreshold w Resources/config.php określa czas wygaśnięcia sesji w minutach; wartość domyślna to 60. W przypadku danych poufnych należy ją obniżyć do 15. Samo czyszczenie wywołuje się jako argument linii poleceń głównego modułu:

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

-c usuwa wygasłe sesje z obu lokalizacji danych, stosując skonfigurowany próg czasowy. -c=15 używa wartości piętnastu minut tylko dla tego konkretnego uruchomienia. -c=now usuwa wszystkie sesje bez względu na ich wiek, włącznie z tą, w której użytkownik aktualnie wykonuje konwersję, dlatego należy używać tego polecenia wyłącznie w celach konserwacyjnych. Te same argumenty działają wewnątrz kontenera za pośrednictwem docker exec.

Zadanie czyszczenia należy dodać do harmonogramu, aby nie zależało ono od aktywności użytkowników na stronie. Wystarczy wpis w /etc/cron.d/hrconvert2:

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

Po kilku minutach należy sprawdzić działanie za pomocą ls /DATA/HRConvert2 i zweryfikować, czy stare katalogi sesji zniknęły. Ponieważ użytkownik serwera WWW jest właścicielem tego katalogu, jest to dokładnie ten poziom uprawnień, który przejąłby atakujący w przypadku wykorzystania luki w parserze, dlatego konto to nie powinno posiadać dostępu do żadnych innych wartościowych zasobów. Konta o najniższych wymaganych uprawnieniach na serwerze VPS to ogólny wzorzec, który w tym przypadku ma szczególne znaczenie.

Umieść usługę za uwierzytelnianiem, chyba że celem jest dostęp publiczny

Domyślna instalacja nie posiada kont, co jest założeniem projektowym. Każdy, kto uzyska dostęp do strony, może przesłać plik i uruchomić pliki binarne konwertera, a limity szybkości jedynie spowalniają ten proces. Należy zatem określić, w jakiej sytuacji znajduje się użytkownik.

Jeśli usługa jest przeznaczona dla administratora i kilku współpracowników, nie należy wystawiać jej na zewnątrz. Należy powiązać kontener z interfejsem loopback, jak pokazano powyżej, i uzyskiwać do niego dostęp przez sieć prywatną lub tunel SSH. Wówczas żaden podmiot z publicznego Internetu nie będzie mógł przesłać pliku, co eliminuje całą powierzchnię ataku zamiast ją jedynie filtrować.

Jeśli usługa musi być dostępna z poziomu przeglądarki, należy umieścić uwierzytelnianie przed proxy. Basic auth wymaga wykonania dwóch poleceń i chroni formularz przesyłania plików przed niepowołanymi osobami:

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;
}

Przeładuj nginx i wczytaj stronę. Pojawienie się monitu oznacza, że konfiguracja działa; brak monitu oznacza, że edytowany blok location nie obsługuje tego żądania. W przypadku korzystania z rzeczywistych kont zamiast współdzielonego hasła, należy zastosować terminację przy dostawcy SSO: samodzielnie hostowany serwer Authentik SSO umożliwia uwierzytelnianie typu forward przed aplikacją, która nie posiada własnego mechanizmu logowania.

Jeśli celem jest stworzenie w pełni publicznego konwertera, należy zaakceptować wynikające z tego konsekwencje i odpowiednio zaplanować zabezpieczenia. Należy założyć, że piaskownica będzie badana pod kątem podatności. Należy przypiąć tag obrazu, zachować restrykcyjną politykę ImageMagick, ustawić niskie limity przesyłania plików i uruchomić usługę na VPS, na którym nie znajdują się żadne inne istotne dane.

Tryby awarii i komunikaty błędów

Każda konwersja kończy się natychmiastowym niepowodzeniem. Nie można zbudować środowiska izolowanego (sandbox). W standardowej instalacji przyczyną jest profil AppArmor. W środowisku Docker brakuje --security-opt seccomp=unconfined. Aplikacja wskazuje na ten problem: A sandbox blocks the required syscalls unless it was started with the correct options. i odwołuje się do See --Require Sandbox-- & --Require Sandbox On Docker-- in config.php..

Niepowodzenie dotyczy tylko konwersji obrazów. Bubblewrap is missing or non functional, so this image conversion cannot be isolated! oznacza, że bwrap jest nieobecny lub niedostępny w ścieżce (PATH) użytkownika serwera WWW.

Jeden format nie działa, pozostałe funkcjonują poprawnie. Brak pliku binarnego jest zgłaszany wprost: ImageMagick may not be installed, or may not be reachable on the system path used by the web server user.. Ten sam komunikat dotyczy zarówno FFmpeg, jak i LibreOffice. Uruchom convertCore.php -v, aby sprawdzić, co widzi instalacja. Należy pamiętać, że zmienna PATH użytkownika serwera Apache różni się od PATH powłoki logowania.

Przetwarzanie plików PDF kończy się błędem polityki. attempt to perform an operation not allowed by the security policy 'PDF' pochodzi z pliku policy.xml programu ImageMagick, a nie z HRConvert2.

Przesyłanie dużych plików zwraca błąd 413. Dyrektywa client_max_body_size w nginx jest mniejsza niż rozmiar pliku. W łańcuchu przetwarzania istnieją trzy limity: jeden w nginx i dwa w PHP. Obowiązuje najniższa z ustawionych wartości.

Konwersje zatrzymują się bez wyraźnej przyczyny. The device where data is stored has an insufficient amount of storage space available. Sprawdź ilość wolnego miejsca oraz czy proces czyszczenia (cleanup) jest uruchomiony.

Dziennik zgłasza błędy czyszczenia. Could not clean the temporary location! oraz Could not clean the convert location! to problemy z uprawnieniami. Użytkownik serwera WWW musi być właścicielem katalogu wskazanego przez $ConvertLoc.

FAQ

Czy udostępnianie własnego konwertera plików w Internecie jest bezpieczne?

Jest to wystarczająco bezpieczne tylko wtedy, gdy traktuje się go jak parser udostępniony osobom trzecim. Każdy przesłany plik jest przekazywany do LibreOffice, ImageMagick, FFmpeg lub Ghostscript, a użytkownik przesyłający wybiera narzędzie. HRConvert2 uruchamia te narzędzia wewnątrz przestrzeni nazw bubblewrap bez dostępu do sieci i z katalogiem wejściowym w trybie tylko do odczytu. Aplikacja odrzuca każdą konwersję, której nie może uruchomić w piaskownicy, co stanowi bezpieczne ustawienie domyślne. Mimo to zaleca się wymaganie uwierzytelniania, utrzymywanie niskich limitów przesyłania oraz uruchamianie usługi na serwerze VPS, na którym nie znajdują się żadne inne cenne dane.

Dlaczego każda konwersja kończy się niepowodzeniem na świeżej instalacji Ubuntu 24.04?

Ubuntu 24.04 oraz Debian 12 ograniczają przestrzeń nazw nieuprzywilejowanych użytkowników, a bubblewrap wymaga jej do utworzenia piaskownicy. Ponieważ aplikacja odmawia wykonania konwersji bez piaskownicy, każde zadanie kończy się błędem. Należy utworzyć profil AppArmor dla /usr/bin/bwrap za pomocą flags=(unconfined), załadować go poleceniem sudo apparmor_parser -r /etc/apparmor.d/bwrap, a następnie potwierdzić za pomocą bwrap --ro-bind / / --dev /dev /bin/true.

Dlaczego konwersje nie działają w Dockerze, mimo że działają w standardowej instalacji?

Domyślny profil seccomp w Dockerze blokuje wywołania systemowe używane przez bubblewrap, przez co piaskownica nie może zostać utworzona wewnątrz kontenera. Należy uruchomić go z flagą --security-opt seccomp=unconfined, co jest zgodne z oficjalną komendą uruchomieniową projektu. Należy pamiętać, że $RequireSandboxOnDocker jest domyślnie ustawione na FALSE, więc kontener bez odpowiedniej flagi może przeprowadzać konwersję bez żadnej piaskownicy. Po zastosowaniu flagi seccomp należy ustawić tę wartość na TRUE.

Ile pamięci RAM potrzebuje serwer konwersji plików?

W stanie spoczynku zapotrzebowanie jest niewielkie, ale podczas aktywnej konwersji wzrasta. LibreOffice uruchamia środowisko uruchomieniowe Java, ImageMagick zajmuje 256 MiB pamięci oraz 512 MiB mapowania zgodnie z dostarczoną polityką, a limit PHP wynosi 512M. Na serwerze VPS z 1 GB pamięci RAM taka kombinacja powoduje użycie swapu, a mechanizm out of memory killer kończy proces soffice.bin lub apache2. Dla małego zespołu należy zaplanować 4 GB pamięci RAM i dwa rdzenie procesora, a w przypadku, gdy konwersja kończy się bez komunikatu, należy sprawdzić dmesg -T | grep -i "killed process".

Gdzie trafiają przekonwertowane pliki i kiedy są usuwane?

Trafiają one do katalogu roboczego określonego przez $ConvertLoc w Resources/config.php, którego domyślną wartością jest /DATA/HRConvert2. $DeleteThreshold określa czas wygaśnięcia sesji w minutach, domyślnie ustawiony na 60. Czyszczenie uruchamia się z wiersza poleceń: php convertCore.php -c usuwa wygasłe sesje, a -c=now usuwa natychmiast wszystkie sesje, w tym aktywne. Należy dodać -c do wpisu w cron lub timera systemd, aby usuwanie plików nie zależało od wizyt użytkowników na stronie.