HRConvert2 ile kendi dosya dönüştürücünüzü kurun

Neden kendi dosya dönüştürücünüzü barındırmalısınız

Kendi kendine barındırılan bir dosya dönüştürücü, dosyayı kendi diskinizde tutar. Bunu çalıştırmanın tek nedeni budur. Ücretsiz bir dönüştürücü sitesi yüklemeyi alır ve sonrasında dosyaya ne olduğu konusunda size hiçbir bilgi vermez; dosya imzalı bir müşteri sözleşmesi veya taranmış bir tıbbi kayıt olduğunda, yüklemenin kendisi bir güvenlik ihlalidir. HRConvert2, PHP ile yazılmış ve GPLv3 lisansına sahip, sürükle-bırak özellikli bir dosya dönüştürme sunucusudur. Bu kılavuz, 18 Ağustos 2026 tarihinde yayınlanan 3.7.4 sürümü esas alınarak hazırlanmıştır. Proje o tarihten bu yana hızla gelişmiştir: 13 Ekim 2026 itibarıyla en yeni sürüm, 6 Eylül 2026 tarihinde yayınlanan v3.9.1'dir ve proje 488 formatı desteklediğini belirtmektedir.

Veritabanı, hesap yönetimi veya çerez kullanımı yoktur. Bir kullanıcı, geçici bir dizinden ibarettir. Her dönüştürme işlemi, işi yapan yerel bir komut satırı aracıdır: belgeler için LibreOffice, ses ve video için FFmpeg, görseller için ImageMagick, optik karakter tanıma (OCR) için Tesseract ve geri kalan formatlar için çok sayıda küçük araç. HRConvert2; yükleme sayfası, işlem hattı ve bunların etrafındaki temizlik mekanizmasıdır.

Dosyayı bir formattan diğerine dönüştürür. Bir tarayıcı tabanlı ofis paketi değildir; bu nedenle, insanların bir sekme üzerinde belge düzenlemesini istiyorsanız, bunun yerine kendi kendine barındırılan OnlyOffice ve Collabora seçeneklerini karşılaştırın. Ayrıca bir depolama alanı da değildir. Dönüştürülen çıktıların silinmesi amaçlanmıştır; bu nedenle dosyaların bir yerde kalıcı olması gerekiyorsa, bu görev kendi kendine barındırılan bir dosya yöneticisine aittir.

Gereksinimler

Debian veya Ubuntu, Apache 2.4, PHP 8 veya üzeri ve bubblewrap gereklidir. Bubblewrap (bwrap) sandbox ortamıdır ve kullanımı zorunludur; sandbox oluşturamayan bir sunucu, güvenlik katmanı olmadan çalışmak yerine dönüştürme işlemini reddeder. Upstream README dosyası, Raspberry Pi Model B+ cihazının PHP kısmı için yeterli olduğunu belirtmektedir. Dönüştürücü ikili dosyaları donanım gereksinimlerini belirler; bu konu aşağıda detaylandırılmıştır.

Sistemi kurmanın iki yolu mevcuttur. Docker imajı hızlı bir kurulum sağlar. Apache ve PHP kurulumu ise bir akşam sürer ve sunucuda tam olarak nelerin çalıştığını görmenizi sağlar.

Docker ile bu gece çalıştırın

İmaj, tüm dönüştürücü ikili dosyalarını içerdiği için oldukça büyüktür: 2026 Ağustos ayı itibarıyla yaklaşık 3 GB. İmajı çekmeden önce diskte yeterli alan olup olmadığını kontrol edin.

Etiketler (tags) burada önemlidir. Bu kılavuz, 17 Ağustos 2026 tarihinde Docker Hub üzerindeki en güncel etiket olan ve aynı gün yayınlanan en yeni GitHub sürümüyle eşleşen v3.7.2 sürümünü sabitlemektedir. v3.7.4 sürümü 18 Ağustos'ta yayınlanmıştır. 13 Ekim 2026 itibarıyla en yeni GitHub sürümü v3.9.1 (6 Eylül 2026), en yeni Docker Hub etiketleri ise edge (22 Eylül 2026) ve v3.8.4 (31 Ağustos 2026) olan latest etiketidir. latest etiketi sürekli değiştiğinden ve bu uygulama geniş bir ayrıştırıcı yüzeyine sahip olduğundan, belirli bir sürümü sabitleyin ve güncellemeleri kontrollü bir şekilde yapın.

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/

Sağlıklı bir container Up durumunda kalır ve curl komutu HTTP/1.1 200 OK çıktısını verir. Sürekli yeniden başlayan bir container'ın başlatılma sorunu vardır; bu nedenle başka bir değişiklik yapmadan önce docker logs hrconvert2 içeriğini okuyun.

İki bayrak (flag) kritik öneme sahiptir. -p 127.0.0.1:8080:80, portu yalnızca loopback üzerinde yayınlar; böylece önüne bilinçli bir şekilde bir proxy koyana kadar dönüştürücüye dışarıdan erişilemez. Projenin mevcut örneği, genel arayüz dahil tüm arayüzleri dinleyen -p 8080:80 portunu eşlemektedir. --security-opt seccomp=unconfined bayrağı, bubblewrap'in kendi sandbox ortamını oluştururken kullandığı user namespace ve mount sistem çağrılarının Docker'ın varsayılan seccomp profili tarafından engellenmesi nedeniyle gereklidir. 3.7 sürümü config.php yorumları, bazı ana makinelerin --security-opt apparmor=unconfined bayrağına da ihtiyaç duyduğunu belirtir. Bu bayrak olmadan dönüştürme işlemleri başarısız olur ve uygulama size nedenini şu şekilde bildirir: A sandbox blocks the required syscalls unless it was started with the correct options.

Bu bayrak gerçek bir takas işlemidir. Uygulamanın kendi içinde daha sıkı bir sandbox oluşturabilmesi için container'ın sistem çağrısı filtresini gevşetirsiniz. Davranışı belirleyen iki ayar, Resources/config.php dosyasındaki $RequireSandbox ve $RequireSandboxOnDocker değerleridir. v3.7.4 sürümü bunları TRUE ve FALSE olarak sunar. Burada sabitlenen v3.7.2 etiketi ise her ikisini de FALSE olarak sunar, çünkü yorumlarında bir container'ın $RequireSandbox ayarını kapalı tutması ve kararı $RequireSandboxOnDocker değerine bırakması gerektiği belirtilir. Docker gereksinimi varsayılan olarak kapalı olduğundan, seccomp bayrağı olmayan bir container hiçbir sandbox olmadan dönüştürme yapabilir. Bayrak eklendiğinde $RequireSandboxOnDocker = TRUE; ayarını yapılandırarak reddetme davranışını container içinde tekrar aktif edebilirsiniz.

Daha yeni imajlar farklı şekilde başlar. Proje, v3.8.0 (25 Ağustos 2026) sürümünde Docker sürecini değiştirmiştir. Mevcut README dosyası ve Docker Hub sayfası, container'ı seccomp seçeneği yerine --cap-add SYS_ADMIN ile çalıştırmakta ve bu seçenek olmadan dönüştürme işlemlerinin reddedildiğini belirtmektedir. Sürüm sabitlemenizi 3.8 veya 3.9 etiketlerine taşırsanız, ilgili imajın dokümante ettiği bayrakları kullanın. Bu yetenek oldukça geniş kapsamlı olduğundan, 127.0.0.1 port bağlamasını korumaya devam edin.

Eğer bu makinede Docker yeniyse, önce daemon kurulumunu yapın. VPS üzerinde Docker çalıştırma rehberi; kurulumu, depolama sürücüsünü ve Docker'ın kendi güvenlik duvarı kurallarını nasıl yazdığını kapsamaktadır.

Bunun yerine Apache ve PHP üzerine kurun

v3.7.4 sürümüne kadar, depodaki Documentation/INSTALLATION_INSTRUCTIONS.txt dosyası bu işlemi dokuz adımlı manuel bir kurulum olarak açıklamaktaydı ve bu bölüm o kurulumu takip eder. v3.8.0 sürümünden itibaren aynı dosya bunun yerine bir kurulum betiğini tarif etmektedir. Klonlanmış depo içerisinden sudo bash Documentation/Build/hrconvert2-setup.sh komutunu çalıştırın; bu betik bağımlılıkları kurar, PHP ayarlarını php.ini dosyasını düzenlemek yerine bir ek dosya olarak yazar ve bubblewrap için AppArmor profilini genişletir. Ardından php convertCore.php -v ve --status komutları sonucu doğrular. Manuel yöntem daha uzun sürer ancak sunucuya tam olarak neyin yüklendiğini bilirsiniz. İşin yapısı şöyledir. Web sunucusu, dil ve sandbox ile başlayın:

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

php8.3-* isimleri Ubuntu 24.04 ile uyumludur. php -v komutunu çalıştırın ve sürümünüzle eşleşen ön eki kullanın; çünkü bu paket isimleri her PHP sürümüyle değişir ve yanlış olanı seçmek Unable to locate package hatasına yol açar.

Ardından dönüştürücüler. Bu kısım belgeleri, görselleri, sesleri, videoları ve OCR işlemlerini kapsar ki bunlar insanların aslında dönüştürdüğü içeriklerin büyük kısmını oluşturur:

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

Arşiv formatları, 3D modeller, e-kitaplar ve önyüklenebilir ISO imajları bundan daha fazla paket gerektirir ve bunların bazıları Ubuntu'nun multiverse bileşeninde yer alır. v3.7.4 sürümünde, resmi talimatların 3. adımı tam apt listesini, 5. adımı ise kaynak koddan derlemeleri içeriyordu. Mevcut kılavuzda paket listeleri bulunmamaktadır. Kurulum aracı Resources/Engine/Contract/depends.php manifest dosyasını okur ve php convertCore.php --setup --check-depends komutu mevcut listeyi ve durumunu yazdırır. İki bağımlılık kaynak koddan da derlenebilir. Depo, paketlenmiş FFmpeg'de bulunmayan kodlayıcılar için Documentation/Build/ffmpeg-build.sh dosyasını ve hala 6.9 dalını paketleyen Ubuntu 22.04 veya 24.04 üzerinde ImageMagick 7 için Documentation/Build/build-imagemagick-v7.sh dosyasını sunar. Ubuntu 25.10 ve 26.04 LTS, ImageMagick 7.1 paketlerini içerir. E-kitap desteği, 3.7 talimatlarında tek satır olarak verilen calibre'nin kendi kurulum aracından gelir:

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

Bu, root yetkisiyle bir kabuğa yönlendirilen bir üretici betiğidir. Bu, yukarı akış (upstream) yöntemidir ve isteğe bağlıdır: bunu atlarsanız kaybedeceğiniz tek şey e-kitap dönüştürme özelliğidir.

Sırada PHP limitleri var. Dönüştürme işlemleri yavaştır ve dosyalar büyüktür, bu nedenle varsayılan değerler çok düşüktür. 3.7 talimatları bunları php.ini dosyasında şu şekilde ayarlamıştır:

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

Bu sayılar, yeterli alanı olan bir makineyi varsayar. Küçük bir VPS üzerinde işlem yapmadan önce bu değerleri düşürün, çünkü upload_max_filesize = 5000M ve max_file_uploads = 100 kombinasyonu, 40 GB'lık bir diskin tutabileceğinden çok daha fazlasını yazabilen tek bir isteği tarif eder. Apache'yi yeniden başlatın ve PHP'nin gerçekte neyi yüklediğini doğrulayın:

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

Şimdi çalışma dizini. Resources/config.php içindeki $ConvertLoc bunu isimlendirir ve varsayılan değer /DATA/HRConvert2 şeklindedir. Web sunucusu kullanıcısı bu dizinin sahibi olmalıdır:

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

Sürümü Apache belge kök dizininizin altına açın. Varsayılan yapı onu bir HRProprietary/HRConvert2 klasörüne yerleştirir ve Resources/config.php içindeki $InstLoc, dosyaları gerçekte nereye koyduysanız orayı işaret etmelidir. Ardından, bir kullanıcı fark etmeden önce eksik bir bağımlılığı bulmanın en hızlı yolu olan yerleşik tanılama aracını çalıştırın:

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

-v tüm kurulumu tarar: çekirdek sürümleri, bağımlılık kontrolleri, sandbox durumu ve dil paketleri. Dosya dönüştürme işlemleri komut satırından desteklenmez, bu nedenle bu argüman seti yalnızca yönetim amaçlıdır.

FAQ

Neden yeni bir Ubuntu 24.04 kurulumunda tüm dönüştürme işlemleri başarısız oluyor?

Bunun nedeni sandbox yapısıdır ve bu, ilk gün karşılaşılan en yaygın sorundur. Ubuntu 24.04, AppArmor aracılığıyla varsayılan olarak ayrıcalıksız kullanıcı ad alanlarını (user namespaces) kısıtlar. Bubblewrap, sandbox ortamını oluşturmak için bir kullanıcı ad alanına ihtiyaç duyar; bu nedenle bwrap başlatılamaz ve uygulama sandbox olmadan dönüştürme yapmayı reddettiği için her bir iş başarısız olur.

Durumu doğrudan kontrol edin:

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

Erişim reddedildi (permission denied) hatası, ad alanının engellendiği anlamına gelir. Çözüm, bwrap ikili dosyası için bir AppArmor profili oluşturmaktır. Öncelikle ABI dosyalarını listeleyin ve mevcut en yüksek numarayı not edin:

ls /etc/apparmor.d/abi/

Ardından /etc/apparmor.d/bwrap dosyasını yazın ve 4.0 kısmını bu en yüksek numara ile değiştirin:

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

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

Profili yükleyin:

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

Çıktı alınmaması, profilin yüklendiği anlamına gelir. bwrap kontrolünü tekrar çalıştırın; bu sefer sandbox ok çıktısını vermesi gerekir. Bu noktadan itibaren dönüştürme işlemleri çalışacaktır.

Debian 12'de bu sorun yaşanmaz. Çekirdeği ayrıcalıksız kullanıcı ad alanlarına izin verir ve bubblewrap paketi önyükleme sırasında kernel.unprivileged_userns_clone değerini 1 olarak ayarlar; bu nedenle yukarıdaki kontrol orada bir profile gerek kalmadan geçer. v3.8.0 ve sonraki sürümlerde, kurulum betiği dağıtımın kendi bubblewrap AppArmor profilini sizin için genişletir.

Genel kullanıma açık bir dönüştürücü, yabancılara sunulan bir ayrıştırıcıdır

Bu bölüm, yazının geri kalanının varlık sebebidir. İnternetten erişilebilen bir dosya dönüştürücü, anonim bir kullanıcıdan rastgele bir dosya kabul eder ve bunu LibreOffice, ImageMagick, FFmpeg veya Ghostscript'e iletir. Bunlar, uzun bir ayrıştırıcı hatası geçmişine sahip büyük C ve C++ kod tabanlarıdır. Dosyayı yükleyen kişi formatı seçer; bu da hangi ayrıştırıcının ve o ayrıştırıcı içindeki hangi kod yolunun çalışacağını yükleyen kişinin belirlediği anlamına gelir.

HRConvert2'nin buna yanıtı, her bağımlılığı bir bubblewrap isim alanı (namespace) içinde çalıştırmaktır. Her dönüştürme işlemi iki dizin görür: salt okunur olarak bağlanan girdi dizini ve çıktının alınacağı dizin. Ağ bağlantısı paylaşılmaz; projenin ifadesiyle closes every URL handler in every dependency at once. Bu, kulağa geldiğinden daha önemlidir. Hem ImageMagick hem de Ghostscript, URL getiren referansları kabul eder; bir dönüştürücü, ağınızın içinden bir bulut meta veri uç noktasına ulaşmak için bu şekilde bir sunucu taraflı istek sahteciliği (SSRF) aracına dönüşür. İsim alanında ağ bağlantısı olmadığında, bu getirme işlemi gerçekleşemez.

Reddetme mekanizması işin diğer yarısıdır: A server that cannot build a sandbox refuses the conversion rather than quietly running without one. Kapalı durumda hata veren (fail closed) bir araç, kimsenin okumadığı bir günlükte uyarı veren bir araçtan daha değerlidir. Yukarıdaki AppArmor adımının isteğe bağlı olmamasının ve $RequireSandboxOnDocker seçeneğinin konteyneri dış dünyaya açmadan önce incelenmeyi hak etmesinin nedeni de budur.

ImageMagick'i policy.xml ile sıkılaştırma

ImageMagick'in kendi ilke dosyası, sandbox altında ikinci bir katman görevi görür ve yapılandırılması faydalıdır. Ubuntu 24.04 üzerinde ImageMagick 6 için ilgili dosya /etc/ImageMagick-6/policy.xml yolundadır. Mevcut aktif ayarları görüntüleyin:

identify -list policy

Proje, Documentation/Build/policy.xml yolunda iyi bir örnek teşkil eden bir ilke dosyası sunar. Bu dosya PS, PS2, PS3, EPS, XPS ve MVG kodlayıcılarını (coder) reddeder; ayrıca URL, HTTPS, HTTP ve gs delegelerini engellerken PDF kullanımına izin verir:

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

gs satırı kritik öneme sahiptir. ImageMagick, PostScript dosyalarını kendisi ayrıştırmaz. İşlemi Ghostscript'e devreder ve bilinen ImageMagick uzaktan kod yürütme (RCE) açıkları bu delege üzerinden gerçekleşir. Bu delegeyi reddettiğinizde, dosya türü ne iddia edilirse edilsin, ImageMagick yüklenen dosyayı hiçbir şekilde gs aracına iletmez.

Aynı ilke dosyası kaynak sınırlarını da belirler; bu sayede özel olarak hazırlanmış bir görselin sunucu kaynaklarını tüketmesi engellenir:

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

Decompression bomb (sıkıştırma bombası), çok küçük boyutlu olup açıldığında devasa boyutlara ulaşan dosyalardır. width, height ve area limitleri, bellek tahsisatı gerçekleşmeden önce bu dosyaları reddeder; böylece çekirdek (kernel) bir süreci sonlandırmak zorunda kalmadan işlem hata vererek durur.

Bu noktada bir tuzak mevcuttur. Ubuntu'nun varsayılan ilke dosyası PDF kodlayıcısını doğrudan reddeder; bu nedenle müdahale edilmemiş bir sistemde PDF işlemleri attempt to perform an operation not allowed by the security policy 'PDF' hatasıyla başarısız olur. Bu hata mesajı, ilke dosyasının görevini yaptığını gösterir. Kodlayıcıya tekrar izin vermek bilinçli bir karardır; bunu yaparken gs delegesini reddedilmiş durumda tutmanız gerekir.

Küçük bir VPS üzerinde bağımlılık zincirinin maliyeti

Boştayken bunların hiçbiri maliyetli değildir. Apache ve PHP birkaç on megabaytlık yer kaplar ve dönüştürücü ikili dosyaları (binaries) hiç çalışmaz. Tüm maliyet, bir dosya sisteme ulaştığı anda ortaya çıkar.

Bir belge dönüştürme işlemi, bir Java çalışma zamanını başlatan LibreOffice'i tetikler. Bir görsel dönüştürme işlemi, ImageMagick'e 256 MiB bellek ve yukarıdaki politikaya göre 512 MiB bellek eşlemesi (memory map) sağlar. Bir video dönüştürme işlemi ise sahip olduğunuz tüm çekirdekleri FFmpeg'e tahsis eder; çünkü FFmpeg video ile bu şekilde çalışır. PHP'nin kendi memory_limit değeri, proje yapılandırmasında 512M olarak belirlenmiştir. Bu rakamlar, tek bir iş sırasında işletim sistemi ve web sunucusunun üzerine eklenir.

Bu nedenle 1 GB RAM'e sahip bir VPS, ilk gerçek belgede takas (swap) alanına geçer ve ardından performans kaybı yaşar. Bellek tükendiğinde, çekirdeğin "out of memory killer" mekanizması, en büyük yerleşik boyuta (resident size) sahip süreci sonlandırır. Bu genellikle soffice.bin olur ve kullanıcı, hiçbir anlamlı hata mesajı almadan başarısız olan bir dönüştürme işlemiyle karşılaşır. Bazen bu süreç apache2 olur ve tüm site çöker. Durumu olay sonrasında dmesg -T | grep -i "killed process" ile doğrulayabilirsiniz.

Bu bir kıyaslama (benchmark) değil, boyutlandırma rehberidir: 4 GB RAM ve iki çekirdek küçük bir ekip için yeterlidir; 2 GB RAM ve bir swap dosyası ise yükünüz belge ve görsellerden oluşuyorsa ve bekleme süresini kabul ediyorsanız iş görür. Swap dosyası dönüştürme işlemini hızlandırmaz. Sadece ani yüklenmeleri ölümcül bir hata yerine yavaş bir sürece dönüştürür; bu da donmuş bir sayfa ile tamamen erişilemez bir site arasındaki farktır. Diske, gerekenden daha fazla alan ayırın; çünkü 3 GB'lık bir görsel, yüksek bir yükleme sınırı ve dönüştürülmüş çıktı, diğer tüm kaynaklarınız tükenmeden önce diski hızla dolduracaktır.

Dönüştürme işlemleri doğası gereği ani yüklenmelere (bursty) neden olur. Aynı anda video yükleyen iki kişi tüm çekirdekleri kullanacaktır ve bir sonraki istek onların arkasında bekleyecektir. Bunun önünde bir iş kuyruğu (job queue) bulunmadığından, sahip olduğunuz tek kontrol mekanizması sınırlamalardır.

Tek bir yüklemenin diski doldurmasını engelleyen limitleri ayarlayın

Önce PHP değerlerini kısıtlayın. upload_max_filesize = 512M, post_max_size = 512M ve max_file_uploads = 20 gibi değerler, 4 GB belleğe sahip paylaşımlı bir sunucu için makul bir başlangıç noktasıdır. max_execution_time = 1200 değerinin, bir PHP isteğinin yirmi dakika boyunca çalışmasına izin verdiğini unutmayın; uzun süren bir video dönüştürme işlemi için bu süre gerekli olabilir ancak aynı zamanda yavaş bir yüklemenin bir worker sürecini yirmi dakika boyunca meşgul edeceği anlamına gelir.

Ardından, istek PHP'ye ulaşmadan önce proxy katmanında boyut ve hız sınırlamalarını uygulayın:

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 değeri, dönüştürmek istediğiniz en büyük dosyadan en az o kadar büyük olmalıdır; aksi takdirde nginx 413 Request Entity Too Large hatası verir ve PHP yüklemeyi asla göremez. proxy_read_timeout değeri, en uzun dönüştürme sürenizi aşmalıdır; aksi takdirde proxy arkasında sorunsuz çalışan bir iş, tarayıcıya 504 Gateway Time-out hatası döndürür. TLS (transport layer security) sonlandırma dahil olmak üzere sunucu bloğunun geri kalanı, satır satır açıklanan bir nginx reverse proxy yapılandırması içerisinde ele alınmıştır.

Dönüştürülen dosyaları silme

Her dönüştürme işlemi, hassas bir dosyanın kopyasını web sunucusunun okuyabileceği bir dizinde bırakır. Temizlik işlemi, bir dönüştürücüyü, üzerinde dönüştürülmüş her şeyin arşivlendiği bir depodan ayıran temel farktır.

$DeleteThreshold, Resources/config.php içinde bir oturumun sona erme süresini dakika cinsinden belirler ve varsayılan değeri 60'tır. İçerik hassas olduğunda bu değeri 15'e düşürün. Temizlik işleminin kendisi, çekirdek üzerinde bir komut satırı argümanıdır:

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

-c, yapılandırılmış eşik değerini kullanarak süresi dolmuş oturumları her iki veri konumundan da temizler. -c=15, yalnızca o çalıştırma için on beş dakikalık bir süre kullanır. -c=now, o anda bir kullanıcının dönüştürme işlemi yapıp yapmadığına bakılmaksızın tüm oturumları siler; bu nedenle bu komutu bakım işlemleri için saklayın. Aynı argümanlar docker exec aracılığıyla container içinde de çalışır.

Temizlik işleminin bir sayfayı yükleyen kullanıcıya bağlı kalmaması için bu işlemi bir zamanlayıcıya bağlayın. /etc/cron.d/hrconvert2 içindeki bir satır yeterlidir:

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

Birkaç dakika sonra ls /DATA/HRConvert2 ile kontrol edin ve eski oturum dizinlerinin silindiğini gözlemleyin. Web sunucusu kullanıcısı o dizinin sahibi olduğu için, istismar edilmiş bir ayrıştırıcı (parser) tam olarak bu hesabı ele geçirecektir; bu nedenle bu hesap, değerli başka hiçbir şeyin sahibi olmamalıdır. VPS üzerinde en düşük yetkili kullanıcı hesapları genel bir modeldir ve burada her zamankinden daha fazla geçerlidir.

Erişim herkese açık değilse kimlik doğrulama arkasına alın

Varsayılan kurulum, tasarım gereği herhangi bir hesap içermez. Sayfaya erişebilen herkes dosya yükleyebilir ve dönüştürücü ikili dosyalarınızı çalıştırabilir; hız sınırlamaları (rate limits) bu durumu yalnızca yavaşlatır. Bu nedenle hangi durumda olduğunuzu belirleyin.

Eğer uygulama sadece siz ve birkaç iş arkadaşınız içinse, dış dünyaya kesinlikle açmayın. Container'ı yukarıda gösterildiği gibi loopback adresine bağlayın ve özel bir ağ veya SSH tüneli üzerinden erişin. Bu durumda internet üzerindeki hiçbir şey ona dosya gönderemez; bu da saldırı yüzeyini filtrelemek yerine tamamen ortadan kaldırır. Eğer iş arkadaşlarınızın bir ana makine adı yayınlamadan veya port açmadan tarayıcı üzerinden erişmesi gerekiyorsa, v3 onion servisi olarak sunmak, dönüştürücünün loopback üzerinde kalmasını sağlar ve onlara ziyaret edebilecekleri bir adres verir.

Eğer tarayıcıdan erişilebilir olması gerekiyorsa, proxy'nin önüne kimlik doğrulama ekleyin. Basic auth iki komutla kurulur ve yükleme formunu yabancılardan uzak tutar:

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

Nginx'i yeniden yükleyin ve sayfayı açın. Bir parola istemi geliyorsa işlem başarılıdır; istem gelmiyorsa düzenlediğiniz location bloğu isteği karşılayan blok değildir. Paylaşımlı bir parola yerine gerçek kullanıcı hesapları kullanmak istiyorsanız, tek oturum açma (SSO) sağlayıcısı ile sonlandırın: kendi kendine barındırılan bir Authentik SSO sunucusu, kendi giriş sistemi olmayan bir uygulamanın önüne ileri kimlik doğrulama (forward authentication) katmanı eklemenizi sağlar.

Eğer hedef gerçekten herkese açık bir dönüştürücü ise, bunun getirdiği sorumlulukları kabul edin ve planınızı buna göre yapın. Sandbox ortamının taranacağını varsayın. Image etiketini sabit tutun, ImageMagick politikasını sıkılaştırın, yükleme limitlerini düşük tutun ve uygulamayı içinde başka önemli verinizin bulunmadığı bir VPS üzerinde çalıştırın.

Hata modları ve karşılaşacağınız dizgeler

Tüm dönüştürme işlemleri anında başarısız oluyor. Sandbox oluşturulamıyor. Standart bir Ubuntu 24.04 kurulumunda bu durum AppArmor profilinden kaynaklanır. Sabitlenmiş 3.7 Docker imajında ise eksik olan --security-opt seccomp=unconfined bileşenidir. Uygulama bunu A sandbox blocks the required syscalls unless it was started with the correct options. olarak adlandırır ve See --Require Sandbox-- & --Require Sandbox On Docker-- in config.php. adresini işaret eder.

Yalnızca görsel dönüştürmeleri başarısız oluyor. Bubblewrap is missing or non functional, so this image conversion cannot be isolated! hatası, bwrap bileşeninin eksik olduğu veya web sunucusu kullanıcısının yolunda (PATH) bulunamadığı anlamına gelir.

Bir format başarısız oluyor ancak diğerleri çalışıyor. Eksik bir ikili dosya (binary) şu şekilde açıkça raporlanır: ImageMagick may not be installed, or may not be reachable on the system path used by the web server user.. Aynı mesaj hem FFmpeg hem de LibreOffice için geçerlidir. Kurulumun neleri bulabildiğini görmek için convertCore.php -v komutunu çalıştırın ve Apache işçi sürecinin PATH değişkeninin, sizin oturum açtığınız kabuğun PATH değişkeni ile aynı olmadığını unutmayın.

PDF işlemleri bir politika hatasıyla başarısız oluyor. attempt to perform an operation not allowed by the security policy 'PDF' hatası HRConvert2'den değil, ImageMagick'in policy.xml yapılandırmasından kaynaklanır.

Büyük yüklemeler 413 hatası döndürüyor. nginx client_max_body_size değeri dosyadan daha küçüktür. Zincirde üç farklı limit bulunur; biri nginx, ikisi PHP tarafındadır ve en küçük olan geçerli olur.

Dönüştürme işlemleri duruyor ve görünürde hiçbir şey değişmedi. The device where data is stored has an insufficient amount of storage space available. hatası. Boş disk alanını kontrol edin ve temizlik işleminin (cleanup sweep) gerçekten çalışıp çalışmadığını doğrulayın.

Temizlik işlemi günlük kayıtlarında hata veriyor. Could not clean the temporary location! ve Could not clean the convert location! sahiplik sorunlarıdır. Web sunucusu kullanıcısı, $ConvertLoc ile belirtilen dizinin sahibi olmalıdır.

FAQ

Self-hosted bir dosya dönüştürücüyü internete açmak güvenli midir?

Yabancılara açık bir ayrıştırıcı (parser) olarak değerlendirdiğiniz sürece yeterince güvenlidir. Her yükleme LibreOffice, ImageMagick, FFmpeg veya Ghostscript araçlarına iletilir ve yüklemeyi yapan kişi hangisinin kullanılacağını seçer. HRConvert2 bu araçları ağ erişimi olmayan ve salt okunur girdi dizinine sahip bir bubblewrap namespace içinde çalıştırır. Sandbox içine alamadığı hiçbir dönüştürme işlemini kabul etmez; bu güçlü bir varsayılan ayardır. Yine de kimlik doğrulama zorunluluğu getirmek, yükleme limitlerini düşük tutmak ve içerisinde başka değerli veri bulunmayan bir VPS üzerinde çalıştırmak daha güvenlidir.

Neden yeni bir Ubuntu 24.04 kurulumunda tüm dönüştürme işlemleri başarısız oluyor?

Ubuntu 24.04, AppArmor aracılığıyla ayrıcalıksız kullanıcı namespace'lerini kısıtlar; bubblewrap ise sandbox oluşturmak için buna ihtiyaç duyar. Uygulama, sandbox olmadan dönüştürme yapmayı reddettiği için işlemlerin bir kısmı değil, tamamı başarısız olur. /usr/bin/bwrap için flags=(unconfined) ile bir AppArmor profili yazın, sudo apparmor_parser -r /etc/apparmor.d/bwrap ile yükleyin ve ardından bwrap --ro-bind / / --dev /dev /bin/true ile doğrulayın. Debian 12, ayrıcalıksız kullanıcı namespace'lerine varsayılan olarak izin verir ve bu işleme ihtiyaç duymaz.

Neden dönüştürme işlemleri Docker içinde başarısız oluyor ama normal kurulumda çalışıyor?

Docker'ın varsayılan seccomp profili, bubblewrap'in kullandığı sistem çağrılarını engeller; bu nedenle konteyner içinde sandbox oluşturulamaz. Burada sabitlenen 3.7 sürümü imajı için, ilgili sürümün config.php yorumlarında belirtildiği üzere --security-opt seccomp=unconfined bayrağı ile başlatın. v3.8.0 sürümünden itibaren proje bunun yerine --cap-add SYS_ADMIN kullanımını belgelemektedir. $RequireSandboxOnDocker değerinin varsayılan olarak FALSE olduğunu unutmayın; bu nedenle bayrak eklenmemiş bir konteyner, hiçbir sandbox olmadan dönüştürme yapabilir. Seccomp bayrağı yerleştirildikten sonra bu değeri TRUE olarak ayarlayın.

Bir dosya dönüştürme sunucusu ne kadar RAM'e ihtiyaç duyar?

Boştayken az miktarda kaynak tüketir ancak aktif bir dönüştürme işlemi sırasında durum farklıdır. LibreOffice bir Java çalışma zamanı başlatır, ImageMagick mevcut politika altında 256 MiB bellek ve 512 MiB haritalama alanı kullanır, PHP'nin kendi sınırı ise 512M'dir. 1 GB'lık bir VPS üzerinde bu kombinasyon swap kullanımına yol açar ve out of memory killer, soffice.bin veya apache2 sürecini sonlandırır. Küçük bir ekip için 4 GB RAM ve iki çekirdekli işlemci planlayın; bir dönüştürme işlemi mesaj vermeden sonlandığında dmesg -T | grep -i "killed process" dosyasını kontrol edin.

Dönüştürülen dosyalar nereye gider ve ne zaman silinir?

Dosyalar, Resources/config.php içindeki $ConvertLoc tarafından belirtilen çalışma dizinine gider; bu dizin varsayılan olarak /DATA/HRConvert2 konumundadır. $DeleteThreshold, bir oturumun kaç dakika sonra sona ereceğini belirler ve varsayılan değeri 60'tır. Temizlik işlemi komut satırı üzerinden yürütülür: php convertCore.php -c süresi dolmuş oturumları temizler, -c=now ise aktif olanlar dahil tüm oturumları anında siler. Silme işleminin siteyi ziyaret eden kişilere bağlı kalmaması için -c komutunu bir cron girdisine veya systemd zamanlayıcısına ekleyin.