Cum să găzduiești Homarr în regim self-hosted în 2026: dashboarduri, secrete și tile-uri live

Un container Homarr poate fi într-o stare funcțională, deși problema importantă pentru utilizatori este rezolvată greșit. În cazul Homarr, această defecțiune ascunsă apare de obicei atunci când widgeturile nu pot ajunge la servicii deoarece folosesc adrese locale ale hostului. Acest ghid tratează drept test de acceptanță următoarea operațiune: „creează un board, adaugă un tile pentru un serviciu, configurează o integrare care folosește credențiale și confirmă starea live și căutarea după restart”, apoi construiește deploymentul pornind de la acest rezultat.

Homarr are un rol specific în stack: dashboard cu funcție de căutare și tile-uri live pentru servicii self-hosted. Prin urmare, întrebarea pentru producție nu este dacă portul 7575 răspunde o dată, ci dacă starea, dependențele și adresa publică rămân sincronizate după un restart, un update și o restaurare.

Definește mai întâi criteriile de succes pentru Homarr

Nu lăsa imaginea Homarr să aleagă accidental arhitectura de producție. Imaginea furnizează un proces pe portul 7575; stocarea, rutarea și cerințele externe au în continuare nevoie de cicluri de viață definite intenționat. Cerința locală de runtime constă în date persistente ale aplicației și credențiale pentru integrări live. Acestea trebuie incluse în planul de capacitate și mount-uri, cu un responsabil și o limită măsurabilă.

Deploymentul este pregătit pentru testare aprofundată atunci când poate crea un board, adăuga un tile pentru un serviciu, configura o integrare care folosește credențiale și confirma starea live și căutarea după restart. Urmărește tranzacția în loguri și monitorizează distribuția cererilor widgeturilor, latența API-urilor din aval, dimensiunea datelor aplicației și numărul de clienți concurenți ai dashboardului. Aceste observații arată dacă topologia actuală izolează componenta potrivită.

Repetă în prealabil schimbarea riscantă pentru Homarr

Un container funcțional este necesar, dar nu suficient. Indicatorul de nivel al serviciului este finalizarea cu succes a operațiunii „creează un board, adaugă un tile pentru un serviciu, configurează o integrare care folosește credențiale și confirmă starea live și căutarea după restart”, iar semnalele probabile de presiune sunt distribuția cererilor widgeturilor, latența API-urilor din aval, dimensiunea datelor aplicației și numărul de clienți concurenți ai dashboardului.

Controlul schimbărilor este important deoarece migrările de schemă Homarr și continuitatea cheii de criptare pot afecta credențialele integrărilor stocate. Păstrează imaginea veche, testează migrările pe o copie a stării și documentează dacă rollback-ul este acceptat după modificarea schemei. Dacă widgeturile nu pot ajunge la servicii deoarece folosesc adrese locale ale hostului, diagnostichează prima limită care diferă de mediul funcțional.

Documentează un deployment Homarr validat

Nu folosi traficul primului utilizator drept test de acceptanță pentru Homarr. Pregătește o stare de test inofensivă și rulează acțiunea completă „creează un board, adaugă un tile pentru un serviciu, configurează o integrare care folosește credențiale și confirmă starea live și căutarea după restart”. Notează URL-ul public exact, rezultatul, referința imaginii și intervalul din loguri asociat rulării.

Înlocuiește containerul și repetă testul fără să reconstruiești datele. Apoi, efectuează restaurarea pe un host gol; condiția de recuperare este ca boardurile, utilizatorii, integrările și asseturile personalizate să reapară, iar widgeturile care folosesc credențiale să se reconecteze. Monitorizează distribuția cererilor widgeturilor, latența API-urilor din aval, dimensiunea datelor aplicației și numărul de clienți concurenți ai dashboardului la fiecare trecere și definește o alertă în jurul degradării tranzacției, nu în jurul metricilor unui container inactiv.

O verificare finală ar trebui să eșueze intenționat: trimite date de test inofensive aproape de limita de resurse sau de format asociată acestei situații: widgeturile nu pot ajunge la servicii deoarece folosesc adrese locale ale hostului. Verifică dacă mesajul Homarr rezultat identifică limita relevantă, fără să declanșeze ștergerea datelor sau un restart infinit. Restabilește condiția validă și confirmă că aceeași tranzacție de test reușește. Păstrează acest exercițiu scurt în checklistul de release.

Rulează prima instanță apropiată de configurația de producție

Primul container ar trebui să poată fi șters și recreat cu ușurință. Păstrează datele în afara writable layer-ului, expune portul 7575 doar acolo unde proxy-ul poate ajunge la el și transmite configurația la runtime.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Fixează versiunea imaginii după testul inițial. Citește cea mai veche eroare de startup, nu mesajul final de restart, verifică fiecare mount cu docker inspect și urmărește logurile în timp ce creezi un board, adaugi un tile pentru un serviciu, configurezi o integrare care folosește credențiale și confirmi starea live și căutarea după restart. Această secvență diferențiază o comandă greșită pentru imagine de o problemă de dependențe sau permisiuni.

Volumele sunt doar primul nivel de recuperare

Pentru Homarr, siguranța la redeploy începe cu boardurile, utilizatorii, integrările, secretele și asseturile personalizate. Montează /appdata înainte de bootstrap, scrie date de test inofensive și înlocuiește containerul pentru a demonstra că acea cale este într-adevăr persistentă. Testează calea înlocuind containerul cât timp există date de test inofensive; astfel poți identifica mount-urile îndreptate cu un director prea sus sau prea jos.

Apoi testează recuperarea în caz de dezastru pe un host gol. Folosește, când este necesar, un export al bazei de date consistent la nivelul aplicației și verifică dacă boardurile, utilizatorii, integrările și asseturile personalizate reapar, iar widgeturile care folosesc credențiale se reconectează. Ghidul pentru backup-uri de baze de date testate prin restaurare oferă un obiectiv mai solid decât simpla verificare a faptului că a fost creat un fișier de arhivă.

Împiedică succesul proxy-ului să ascundă o defecțiune a aplicației

Browserul, clientul API și Homarr trebuie să folosească aceeași origine. Pentru a obține acest lucru, setează hostname-ul HTTPS extern și originile permise. Păstrează hostul și protocolul originale, asigurând în același timp că portul 7575 nu este disponibil ca adresă publică alternativă.

Ghidul pentru depanarea situației în care site-ul este indisponibil ajută la diferențierea unei rute inaccesibile de o aplicație care răspunde. Această distincție este importantă aici: widgeturile nu pot ajunge la servicii deoarece folosesc adrese locale ale hostului. Doar primul caz se rezolvă prin modificări de ingress; al doilea necesită inspectarea logurilor, stării sau workload-ului Homarr.

Închide accesul temporar de configurare

Un deployment Homarr securizat începe prin eliminarea autorității inutile. Evită schimbarea cheii de criptare după stocarea secretelor integrărilor; în schimb, păstrează SECRET_ENCRYPTION_KEY stabilă, protejează editarea boardurilor și limitează credențialele fiecărui widget la strictul necesar.

Generează SECRET_ENCRYPTION_KEY o singură dată, păstreaz-o în afara Git și salveaz-o împreună cu manifestul de recuperare, deoarece schimbarea ei poate invalida starea criptată sau semnată a aplicației. Restricționează rutele administrative, folosește DNS privat pentru dependențe și verifică fiecare bind mount. Când logurile sunt trimise centralizat, filtrează secretele și conținutul privat înainte să părăsească serverul.

Mută lucrările de infrastructură repetabile în Dockup

Pentru Homarr, Dockup este cel mai util la limita dintre o imagine și un serviciu durabil. Păstrează asociate ruta către 7575, TLS-ul, valorile secretelor și stocarea în timpul înlocuirii containerelor, indiferent dacă infrastructura de calcul aparține Dockup sau serverului atașat.

Încheie cu verificările specifice aplicației: setează hostname-ul HTTPS extern și originile permise; confirmă cerința locală — date persistente ale aplicației și credențiale pentru integrări live; apoi rulează această verificare: creează un board, adaugă un tile pentru un serviciu, configurează o integrare care folosește credențiale și confirmă starea live și căutarea după restart. Păstrează rezultatul drept verificare de deployment, astfel încât următorul update al imaginii să fie evaluat după comportament, nu după starea containerului.

Întrebări frecvente

De ce are nevoie Homarr pentru un deployment de producție?

Rutează containerul Homarr prin portul 7575 și o singură origine HTTPS. Cerința locală de runtime constă în date persistente ale aplicației și credențiale pentru integrări live. Nu considera Homarr pregătit până când nu poți crea un board, adăuga un tile pentru un serviciu, configura o integrare care folosește credențiale și confirma starea live și căutarea după restart.

Ce date Homarr trebuie incluse într-un backup?

Păstrează /appdata și include boardurile, utilizatorii, integrările, secretele și asseturile personalizate în același manifest de recuperare. O restaurare Homarr validă se încheie cu succes doar atunci când boardurile, utilizatorii, integrările și asseturile personalizate reapar, iar widgeturile care folosesc credențiale se reconectează.

Are Homarr nevoie de HTTPS în spatele unui reverse proxy?

Folosește HTTPS pentru originea publică Homarr și păstrează portul 7575 pe ruta internă. Aplică setarea Homarr corect: setează hostname-ul HTTPS extern și originile permise. Pentru Homarr, HTTPS protejează credențialele sau conținutul utilizatorilor în tranzit și menține consecvent comportamentul clientului sensibil la origine.

Cum trebuie testat un upgrade Homarr?

Restaurează starea Homarr actuală într-un deployment izolat, aplică versiunea candidat și repetă tranzacția de acceptanță. Acordă o atenție deosebită acestui proces, deoarece migrările de schemă Homarr și continuitatea cheii de criptare pot afecta credențialele integrărilor stocate. Păstrează imaginea Homarr anterioară până când limitele migrării datelor și ale rollback-ului sunt înțelese.