Özel uzak dağıtım

Bu yapılandırmada Libre WebUI, Ollama ve Cloudflare Tunnel tek bir Docker ana bilgisayarında çalışır; uygulama veya Ollama portları yayımlanmaz. Cloudflare Access dış kimlik sınırını, Libre WebUI kimlik doğrulaması iç sınırı oluşturur. Work ve Watchtower ayrı ayrı etkinleştirilir ve root düzeyine eşdeğer yetkiler verir.

Şablon tek replikalı solo topolojisi için tasarlanmıştır: SQLite, yerel şifreli ikili nesneler, gömülü vektörler, yerel koordinasyon ve yerleşik kalıcı iş işleyicisi uygulamanın veri birimini birlikte kullanır. .env içindeki sunucu seçicilerini değiştirerek bu yapılandırmayı team dağıtımına dönüştürmeyin. team için depodaki docker-compose.team.yml (Work etkinse docker-compose.team.work.yml de) kullanılmalıdır. Bu dosyalar PostgreSQL/PGVector, sürümlü S3 depolaması, Redis, dış worker ve ağ geçidini tek ve uyumlu bir topoloji olarak birlikte sağlar.

Başlangıç noktası olarak deploy/private/docker-compose.yml dosyasını kullanın. Varsayılan imaj main’dir:

LIBRE_WEBUI_IMAGE=ghcr.io/libre-webui/libre-webui:main

dev etiketi yalnızca açıkça geliştirmeyi seçmiş bir örnek için uygundur; normal istemci dağıtımı için değildir.

Güvenlik modeli

• Cloudflare Access, /api/* ve WebSocket yükseltmeleri dâhil tüm ana bilgisayar adını korur. Genel bypass yolları eklemeyin.
• Uygulama API’leri geçerli Libre WebUI hesabı ister. Model ve Work yaşam döngüsü işlemleri, veritabanındaki geçerli rolün yönetici olmasını gerektirir.
• Uygulama, Ollama, SearXNG ve cloudflared yalnızca özel Compose ağını kullanır. Ana bilgisayar uygulama portlarını yayımlamaz.
• Yerleşik SearXNG hizmeti isteğe bağlı web araması sağlar. Yalnızca ağ içinde erişilebilir ve yönetici Settings > Search bölümünden aramayı etkinleştirene kadar kullanılmaz; yığını başlatmadan önce .env içinde SEARXNG_SECRET ayarlayın.
• Uygulama root olmadan, salt okunur kök dosya sistemiyle, ek Linux capabilities olmadan, no-new-privileges ve CPU, bellek, PID sınırlarıyla çalışır.
• Work, geçersiz kılma dosyalarından biri eklenene kadar kapalıdır. Work kapsayıcıları kendi salt okunur kök dosya sistemini, bırakılmış capabilities değerlerini, kaynak sınırlarını, çalışma alanı birimini ve varsayılan olarak reddeden ağ ilkesini alır.

Temel yığın Docker soketini bağlamaz. Work docker-compose.work-proxy.yml ile etkinleştirildiğinde bu özellik korunur: iç ağdaki soket proxy’si sokete sahip olur ve yalnızca Work’ün kullandığı API bölümlerini (containers, images, volumes, networks, exec, info) iletir. swarm, secrets, build ve system bölümleri proxy’de engellenir; uygulamanın soket bağlamasına veya soketin grubuna üye olmasına gerek kalmaz. Proxy Docker API yüzeyini daraltır, ancak izin verilen işlemlerin verebileceği zararın kapsamını daraltmaz: kapsayıcı oluşturabilen bir süreç ana bilgisayar yollarını yine bağlayabilir. Bu nedenle bu gerçek bir güçlendirme katmanıdır, ancak çok kiracılı yalıtım değildir.

Ham soket seçenekleri en geniş güven sınırı olmaya devam eder: docker-compose.work.yml ve Watchtower geçersiz kılması kapsayıcıya, rastgele Docker API çağrıları gönderebilen ve ana bilgisayarı yönetebilen bir süreç verir. Soketi salt okunur bağlamak Docker API erişimini salt okunur yapmaz. Yerleşik yedekleme aracı ham soketi devralmayı reddeder; zamanlanmış tümleşik yedeklere güvenmeden önce Work’ü filtrelenmiş proxy’ye taşıyın.

İlk kurulum

1. sudo yetkisi bulunan, root olmayan bir işletmeci oluşturun; SSH üzerinden root girişini kapatmadan önce anahtarla SSH girişini sınayın.
2. deploy/private/.env.example dosyasını /opt/libre-webui/.env konumuna kopyalayın, 0600 modunu ayarlayın, benzersiz sırlar oluşturun ve ana bilgisayar için BLOB_QUOTA_BYTES_PER_USER değerini seçin. BLOB_QUOTA_RESERVATION_TTL_MS terk edilmiş yükleme ayırmalarının süresini sınırlar; varsayılan bir saattir.
3. Work etkinleştirilecekse DOCKER_GID değerini /var/run/docker.sock sahibi grubun sayısal ID’sine ayarlayın.
4. Cloudflare Tunnel belirtecini /opt/libre-webui/secrets/tunnel-token içinde 0640 veya daha sıkı modla saklayın.
5. Cloudflare Access içinde tam ana bilgisayar adı için kendi barındırdığınız bir uygulama oluşturun, 24 saatlik oturum ayarlayın ve yalnızca gereken kimliklere izin verin. Tunnel rotası için Protect with Access özelliğini etkinleştirin. İzleme sisteminin genel durum denetimi gerekiyorsa yalnızca /health/live için ayrı bir uygulama veya ilke oluşturun. Ana uygulamaya hiçbir zaman genel Bypass ilkesi eklemeyin: eşleşen Bypass, uygulamanın Allow ilkesini geçersiz kılar.
6. ENABLE_SIGNUP=false olarak bırakın. Access izin listesi ana bilgisayar adını koruduktan sonra ilk yerel yöneticiyi oluşturun; boş veritabanı bu tek başlangıç hesabını otomatik kabul eder. Kaydı daha sonra yalnızca bilerek sınırlandırılmış kısa süre için açın.
7. Turnstile ana bilgisayar adı kısıtlamasını yapılandırın ve TURNSTILE_EXPECTED_HOSTNAME değerini tam genel adla ayarlayın.

Yığını başlatıp doğrulayın:

cd /opt/libre-webui
docker compose config --quiet
docker compose up -d
docker compose ps

Work’ü etkinleştirmek için soket proxy geçersiz kılmasını bilerek ekleyin:

docker compose -f docker-compose.yml -f docker-compose.work-proxy.yml up -d

Ham soket seçeneği (docker-compose.work.yml), buna ihtiyaç duyan dağıtımlar için yukarıdaki güven sonuçlarıyla birlikte kullanılabilir.

Access etkinleştirildikten sonra, tam yolda dar bir bypass yoksa komut satırı denetimleri için Cloudflare Access hizmet belirteci gerekir. Kimlik bilgilerini kabuk geçmişinin dışında tutun ve iki başlığı da gönderin:

curl --fail --silent --show-error \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
  https://your-hostname.example/api/auth/system-info

Korunan uygulama API’sine kimliği doğrulanmamış istek 401 döndürmelidir:

curl --output /dev/null --write-out '%{http_code}\n' \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
  https://your-hostname.example/api/work/tasks

Ana bilgisayarı güçlendirme

Dizinde ek sshd yapılandırması ve fail2ban jail bulunur. Uygulamadan önce başka bir terminalde sudo yetkili, root olmayan işletmeci oturumunu sınayın. SSH’yi yeniden yüklemeden önce sshd -t ile yapılandırmayı doğrulayın.

UFW’yi veya eşdeğer güvenlik duvarını varsayılan olarak gelen trafiği reddedecek biçimde yapılandırın; yalnızca hız sınırlı SSH’ye izin verin. Bu şablonda Docker hizmet portlarını yayımlamaz:

ufw default deny incoming
ufw default allow outgoing
ufw limit OpenSSH
ufw enable

Otomatik güvenlik güncellemelerini açık bırakın. Dağıtımın belgelenmiş gereksinimi yoksa X11, agent ve TCP iletimini kapatın.

Yedeklemeler ve kurtarma

Yedek oluşturmadan önce çalışan kapsayıcı içinde salt okunur kurtarma envanterini çalıştırın. Bu, dağıtılan uygulamanın tam sürümünü, ortamını ve bağlı veri birimini denetler. Ana bilgisayardaki çalışma kopyasından verilen komut farklı bir veritabanını veya imajdan farklı kaynak kodunu denetleyebilir.

docker exec libre-webui \
  libre-webui recovery-check --json --data-dir /app/backend/data

Çıkış kodu 0 kurtarma hazırlığını engelleyen sorun olmadığını, 1 JSON raporunda engeller bulunduğunu, 2 komutun çalıştırılamadığını gösterir. Rapor yalnızca şifreleme anahtarı parmak izini ve sırların varlık işaretlerini içerir; anahtarlar ve diğer sır değerleri hiçbir zaman yazdırılmaz. Kurtarmadan önce uygulama sürümünü, şema parmak izini, beklenen Work kaynaklarını ve istisnaları karşılaştırmak için envanteri ilgili yedekle birlikte saklayın.

Tam olarak dağıtılan imajı kullanarak ayrı yedek şifreleme ve imza anahtarları oluşturun. Dizini uygulama biriminin dışında tutun; şifreleme anahtarı ile özel imza anahtarını ayrı ve korunan bir kurtarma konumuna kopyalayın:

install -d -m 0700 /etc/libre-webui/backup-keys
image_ref=$(docker inspect libre-webui --format '{{.Image}}')
docker run --rm --user 0:0 --read-only --network none --cap-drop ALL \
  --security-opt no-new-privileges \
  --mount type=bind,src=/etc/libre-webui/backup-keys,dst=/backup-keys \
  --entrypoint /usr/local/bin/libre-webui "$image_ref" \
  backup keygen \
  --directory /backup-keys

Anahtar üretimi mevcut dosyaların üzerine yazmayı reddeder. Mevcut yedek kümesinin üzerine asla yeni anahtar üretmeyin: arşiv şifreleme anahtarını veya imza kimliğini kaybetmek ilgili kurtarma kanıtını kullanılamaz hâle getirir.

Sağlanan yedekleme ve kurtarma betikleriyle systemd birimlerini kurun, ardından zamanlayıcıyı etkinleştirin:

install -d -m 0700 /var/backups/libre-webui
install -m 0750 deploy/private/libre-webui-backup \
  /usr/local/sbin/libre-webui-backup
install -m 0750 deploy/private/libre-webui-restore \
  /usr/local/sbin/libre-webui-restore
install -m 0644 deploy/private/libre-webui-backup.{service,timer} \
  /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now libre-webui-backup.timer

Birim, isteğe bağlı olarak yalnızca bakım amaçlı /etc/libre-webui/backup.env geçersiz kılmalarını okur; uygulamanın .env dosyası yüklenmez. Dosyayı yalnızca geçersiz kılma gerektiğinde root olarak oluşturun:

install -d -m 0750 /etc/libre-webui
install -m 0600 /dev/null /etc/libre-webui/backup.env

Burada LIBRE_WEBUI_STACK_DIR, LIBRE_WEBUI_BACKUP_RETENTION_DAYS, LIBRE_WEBUI_CONTAINER_NAME ve LIBRE_WEBUI_BACKUP_KEY_DIR doğrudan ayarlanabilir. Sahip root olarak kalmalı, mod 0600 olmalıdır. Özel anahtar dizini systemd korumalı alanı içinden root tarafından erişilebilir olmalıdır.

LIBRE_WEBUI_BACKUP_DIR değişikliği systemd’nin yazılabilir sınırını da değiştirir. Dizin hizmet başlamadan önce var olmalı ve birime karşılık gelen ek kural eklenmelidir. Örneğin backup.env içinde LIBRE_WEBUI_BACKUP_DIR=/srv/backups/libre-webui ayarlandıktan sonra:

install -d -m 0700 /srv/backups/libre-webui
systemctl edit libre-webui-backup.service

Düzenleyiciye tam yolu ekleyin ve birimi yeniden yükleyin:

[Service]
ReadWritePaths=/srv/backups/libre-webui

systemctl daemon-reload
systemctl start libre-webui-backup.service

Karşılık gelen ReadWritePaths= satırı olmadan ProtectSystem=strict, zamanlayıcının özel dizine yazmasını doğru biçimde engeller.

Yedekleme hizmeti büyük arşivler için altı saate kadar süre tanır. Araç ana bilgisayar kilidini alır, uygulamayı yalnızca çalışıyorsa durdurur ve durmuş birimin arşivini tam dağıtılmış imajla oluşturur. Arşiv imzalı manifest ve işletmeci tarafından şifrelenmiş veriler içerir; veri dizini, çalışma zamanı yapılandırması ve durumu açmak için gereken sırlar dâhildir. Araç daha sonra tüm arşivi bağımsız olarak doğrular ve meta veri raporunu atomik biçimde yayımlar. Salt okunur dosya sistemli bakım kapsayıcıları SQLite ve arşiv doğrulaması için özel, yazılabilir /tmp tmpfs alır; geçici açık metin kapsayıcı katmanında saklanmaz. İki dosyayı ve ayrı korunan kurtarma anahtarlarını ana bilgisayar dışına kopyalayın.

Work docker-compose.work-proxy.yml kullandığında kurtarma, veritabanında listelenen her Work biriminin varlığını da kanıtlamalıdır. Araç dağıtılmış uygulamanın DOCKER_HOST değerini okur, aynı çalışan Compose projesindeki socket-proxy hizmetini bulur ve gerçek Docker bağlantılarından tek bir ortak iç ağ belirler. Compose, ağ adına proje adını ekler; varsayılan ağ adını yapılandırmayın veya sabitlemeyin. Yalnızca arşiv oluşturma kapsayıcısı iç ağa katılır ve filtrelenmiş proxy’ye erişebilir; ham soket verilmez. Bağımsız arşiv doğrulaması --network none ile çalışır. Eksik proxy, beklenmeyen uç nokta, dış veya belirsiz ortak ağ ya da ham soket bağlantısı, uygulama durdurulmadan ve arşiv yayımlanmadan önce hataya yol açar.

Çalışan birimin yerine geçirmeden yeni bir birimde kurtarma provası yapın:

LIBRE_WEBUI_RESTORE_IMAGE="$image_ref" \
  libre-webui-restore \
  /var/backups/libre-webui/libre-webui-integrated-YYYYMMDDTHHMMSSZ.lwb \
  libre-webui-restore-drill

Kurtarma aracı mevcut birimi veya yapılandırma dizinini kullanmayı reddeder, arşivi ve iç envanteri geçici depoda doğrular, sonra verileri yeni birime kopyalar ve kurtarılan runtime.json ile secrets.json dosyalarını özel izinlerle yazar. Çalışan yığını asla yeniden yapılandırmaz veya başlatmaz. Kurtarılan yapılandırmayı inceleyin, dağıtıma bağlı değerleri bilerek güncelleyin ve birimi yalıtılmış yığında sınayın.

Ollama modelleri yeniden indirilebilir. Docker Work birimleri, Kubernetes Work PVC’leri ve ana bilgisayara bağlı Work dizinleri uygulamanın veri dizini dışındadır; kendi uyumlu anlık görüntülerine ve saklama ilkelerine ihtiyaç duyar.

Güncellemeler

İmaj etiketi değişken olsa bile Libre WebUI durumu korur. Temel Compose dosyası uygulamayı kalıcı olarak Watchtower dışında işaretler. Yalnızca koordineli bir işletmeci eylemiyle güncelleyin:

1. Çalışan imajın ID’sini kaydedin ve yalnızca doğrulanmış, değişmez digest ile değiştirin.
2. libre-webui recovery-check çalıştırın, yedekleme hizmetini başlatın ve devam etmeden önce yeni arşiv ile doğrulama raporunu zorunlu kılın.
3. LIBRE_WEBUI_IMAGE değerini doğrulanmış digest olarak ayarlayın, imajı indirin ve Docker Compose ile yalnızca libre-webui hizmetini yeniden oluşturun. Veri birimini silmeyin veya yeniden oluşturmayın.
4. Başarılı /health/ready, giriş, oturum/geçmiş denetimi, belge getirme ve temel Work sınamalarını zorunlu kılın. Hata olursa kaydedilen imaj digest’ine dönün; başarısız durumu ve doğrulanmış yedeği tanılama için koruyun.

Ana bilgisayardaki sıra bilerek elle yürütülür. digest’i yalnızca doğrulamadan sonra değiştirin ve indirmeden önce en yeni .lwb ile .json çiftini inceleyin:

docker inspect libre-webui --format '{{.Config.Image}} {{.Image}}'
docker exec libre-webui \
  libre-webui recovery-check --json --data-dir /app/backend/data
systemctl start libre-webui-backup.service
systemctl --no-pager --full status libre-webui-backup.service
ls -lt /var/backups/libre-webui/libre-webui-integrated-* | head

# Set LIBRE_WEBUI_IMAGE=ghcr.io/libre-webui/libre-webui@sha256:REVIEWED_DIGEST
# in the root-owned .env, then recreate only the application.
docker compose pull libre-webui
docker compose up -d --no-deps libre-webui
docker inspect libre-webui --format '{{.State.Health.Status}} {{.Image}}'

Soketli isteğe bağlı Watchtower geçersiz kılması, temel dosyada açıkça işaretlenmiş yardımcı kapsayıcılar için kullanılabilir:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.watchtower.yml \
  up -d

Watchtower Ollama ve SearXNG’yi 30 dakikada bir denetler. Ollama model verileri adlandırılmış birimde, SearXNG yapılandırması ana bilgisayara bağlı dizinde kalır. Watchtower Libre WebUI’yi, cloudflared’ı, Work soket proxy’sini veya Work korumalı alanlarını güncellemez. İstemci dağıtımı main dalını izler; deneysel örnek :dev seçebilir, ancak uygulama yine zorunlu yedek üzerinden elle güncelleme ister. Bu özel solo yığınını team kalıcılık hizmetlerine asla bağlamayın; bunun yerine tam team topolojisini dağıtın.