Cum se configurează HTTPS și un certificat SSL pentru ONLYOFFICE Docker

Pentru a plasa ONLYOFFICE Docs în spatele protocolului HTTPS în Docker, utilizați un certificat care corespunde numelui public de gazdă, faceți-l disponibil în interiorul containerului și publicați portul HTTPS al containerului. HTTPS este conexiunea web criptată; un certificat TLS ajută browserele să verifice dacă au ajuns la serverul așteptat. Acest ghid utilizează un certificat și o cheie privată pe care le-ați obținut deja de la o autoritate de certificare (CA) de încredere. Dacă utilizați un proxy invers, urmați opțiunea separată de mai jos, deoarece proxy-ul poate gestiona HTTPS în schimb.

Ce configurație HTTPS se potrivește implementării dvs.?

ONLYOFFICE Docs poate servi HTTPS direct din containerul său Docker sau un proxy invers, cum ar fi NGINX sau Traefik, poate accepta HTTPS și redirecționa cererile către Docs. TLS direct este o alegere simplă pentru un server independent ale cărui porturi publice 80 și 443 sunt disponibile. Un proxy invers este adesea mai simplu atunci când un alt serviciu web deține deja acele porturi sau mai multe site-uri partajează un server. Evitați configurarea orbește a ambelor straturi: decideți ce componentă termină TLS și documentați dacă conexiunea proxy-container este HTTP sau HTTPS.

Această demonstrație configurează HTTPS direct cu un certificat emis de o autoritate de certificare. ONLYOFFICE documentează, de asemenea, o opțiune automată Let's Encrypt folosind LETS_ENCRYPT_DOMAINși LETS_ENCRYPT_MAIL; aceasta necesită ca porturile 80 și 443 să fie accesibile și să nu fie deja ocupate de un proxy. Un certificat autosemnat este util pentru o rețea privată de testare, dar browserele publice și serviciile de stocare conectate nu îl vor avea încredere automat.

Ce ar trebui să pregătești mai întâi?

• O gazdă Linux cu Docker Engine și pluginul Docker Compose instalate.
• O înregistrare DNS A pentru numele gazdei, cum ar fi docs.example.com, care indică adresa IPv4 publică a gazdei. Adăugați o înregistrare AAAA numai dacă IPv6 este configurat și accesibil.
• Reguli pentru firewall-ul de intrare și firewall-ul în cloud care permit TCP 443. Dacă solicitați sau reînnoiți certificate cu validare HTTP, este posibil să fie necesar și TCP 80.
• Un lanț de certificate pentru numele exact de gazdă și cheia privată corespunzătoare. Autoritățile de certificare furnizează de obicei un fișier lanț complet și un fișier cheie privată.
• Un director gazdă persistent pentru volumul de date ONLYOFFICE și un secret JWT puternic. JWT (JSON Web Token) este un secret partajat utilizat pentru autentificarea cererilor între Docs și o aplicație de integrare.

Pasul 1: Plasați certificatul și cheia privată pe gazdă

Pentru acest exemplu, gazda păstrează datele persistente sub /srv/onlyoffice/data. Înlocuiți numele de gazdă și căile eșantion cu ale dvs. Stocați lanțul complet al certificatului ca tls.crtși cheia privată corespunzătoare ca tls.keyîntr-un certssubdirector:

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

Păstrați cheia privată lizibilă doar de către contul sau serviciul care are nevoie de ea. Nu o lipiți într-un fișier Compose, într-un raport de problemă sau într-un depozit public. Dacă Docker nu poate citi cheia din cauza proprietății sau a permisiunilor, ajustați accesul în mod restrâns pentru timpul de execuție al containerului, în loc să faceți cheia lizibilă de către toată lumea.

Verificați datele și numele de gazdă ale certificatului înainte de a porni serviciul:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

Lista Nume Alternativ al Subiectului (SAN) ar trebui să includă numele exact de gazdă pe care îl vor vizita utilizatorii. Puteți compara cheile publice derivate din certificat și cheia privată; cele două hash-uri ar trebui să corespundă:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

Pasul 2: Configurați serviciul Docker Compose

Documentația Docker a ONLYOFFICE plasează certificatele sub /var/www/onlyoffice/Data/certs. Lista sa actuală de variabile de mediu oferă numele implicite ale fișierelor cu certificate ca tls.crtși tls.key, în timp ce instrucțiunile de instalare exemplificative utilizează, de asemenea onlyoffice.crt, și onlyoffice.key. Setarea căilor evită în mod explicit utilizarea unei convenții pentru numele de fișiere. Directorul gazdă este montat prin bind în directorul de date al containerului corespunzător, iar portul 443 este publicat ca port gazdă 443.

Creați un compose.yamlfișier ca acesta, înlocuind valoarea JWT exemplu cu un secret generat pentru instalarea dvs. Eticheta de imagine de mai jos este o versiune exemplu; verificați lista oficială de imagini și utilizați o versiune pe care intenționați să o mențineți.

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

Generați un secret puternic cu [data] openssl rand -hex 32și plasați-l în fișierul de mediu sau în configurația Compose cu permisiuni de fișier adecvate. Dacă o altă aplicație se integrează cu Docs, configurați aplicația respectivă cu același secret JWT și adresa publică HTTPS. Dacă aceasta este o instalare existentă, păstrați volumele, rețelele, alte variabile de mediu și setările de integrare atunci când editați fișierul Compose existent; nu înlocuiți o definiție de serviciu funcțională cu acest exemplu minimal.

Porniți sau recreați serviciul din directorul care conține fișierul Compose:

docker compose up -d
docker compose ps
docker compose logs --tail=100 documentserver

Pasul 3: Testați HTTPS și certificatul

Deschideți https://docs.example.comîntr-un browser, înlocuind numele de gazdă. Verificați dacă browserul afișează o conexiune securizată și nu raportează o nepotrivire de nume, un certificat expirat sau un emitent neîncrezător. Confirmați că se încarcă pagina de bun venit ONLYOFFICE Docs. Când Docs este conectat la Nextcloud, ownCloud sau o altă platformă, testați și deschiderea și salvarea unui document; blocarea browserului în sine nu dovedește că solicitările de apel invers ale integrării sau configurația JWT funcționează.

Dintr-o shell, cereți serverului certificatul TLS și testați răspunsul HTTPS:

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

Opțiunea -servernametrimite numele de gazdă utilizând Server Name Indication (SNI), care permite unui server să selecteze certificatul corect atunci când mai multe nume de gazdă partajează o adresă. Datele certificatului, emitentul și SAN-ul ar trebui să corespundă cu certificatul instalat. Verificați docker compose logsdacă browserul nu se poate conecta sau dacă containerul repornește în mod repetat.

Ce se întâmplă dacă un proxy invers gestionează deja HTTPS?

Dacă NGINX, Traefik, Caddy sau un gateway de găzduire deține deja porturile publice 80 și 443, ar putea fi mai bine să instalați certificatul public la acel proxy. În topologia respectivă, publicați containerul Docs doar pe o rețea Docker privată sau legați portul său HTTP la loopback, apoi configurați proxy-ul pentru a redirecționa cererile necesare și traficul WebSocket. Setați adresa ONLYOFFICE a aplicației de integrare la adresa https://URL publică. Urmați instrucțiunile actuale ale proxy-ului și ale ONLYOFFICE pentru anteturile redirecționate și TLS în amonte; nu publicați portul 443 al containerului pe același port gazdă pe care îl folosește deja proxy-ul.

Alegeți acest model atunci când un proxy direcționează traficul pentru mai multe servicii. Folosiți configurarea directă a containerului de mai sus atunci când Docs ar trebui să dețină endpoint-ul public HTTPS și porturile necesare sunt libere. Dacă proxy-ul se conectează la container prin HTTP, acel hop intern nu este criptat; păstrați-l într-o rețea privată de încredere sau configurați TLS în amonte dacă cerințele dvs. de securitate o impun.

Probleme comune și cum să le remediem

• Browserul spune că certificatul este invalid. Verificați numele de gazdă SAN, expirarea certificatului, lanțul complet și dacă DNS indică către gazda dorită. Un certificat pentru domeniul bare nu acoperă automat un subdomeniu.
• Containerul raportează un certificat sau o cheie lipsă. Verificați calea sursă a gazdei, destinația de montare a legăturii, numele exacte ale fișierelor și cele două SSL_..._PATHvalori. Sintaxa Docker --mountnecesită existența căii sursă; montările legăturilor Compose ar trebui să indice și către directorul existent dorit.
• Portul 443 este deja alocat. Opriți serviciul care intră în conflict, utilizați un proxy invers sau alegeți un alt port public al gazdei și asigurați-vă că URL-ul și firewall-ul îl reflectă. Dacă există un proxy în față, acesta ar trebui să dețină de obicei portul public 443.
• HTTPS funcționează, dar editarea documentului eșuează. Verificați adresa URL de integrare, secretul JWT pe ambele servicii, regulile de redirecționare proxy și dacă Docs poate ajunge la platforma de stocare. Testați un ciclu real de deschidere și salvare.
• Certificatul se reînnoiește, dar site-ul încă îl deservește pe cel vechi. Confirmați că reînnoirea a actualizat fișierul montat pe gazdă și că ONLYOFFICE l-a reîncărcat. Dacă este necesar, reporniți serviciul după reînnoire, de exemplu cu un hook de implementare Certbot care rulează docker compose restart documentserverdin directorul proiectului Compose. Testați reînnoirea cu opțiunea de rulare practică a Certbot înainte de a vă baza pe automatizare.

Mențineți certificatul la zi

Configurarea HTTPS nu este finalizată până când nu este planificată reînnoirea. Înregistrați cine emite și reînnoiește certificatul, unde este stocată cheia privată, ce proces copiază fișierele reînnoite în directorul montat și cum le reîncarcă serviciul. Rulați testul de simulare al clientului de reînnoire, monitorizați expirarea certificatului și verificați endpoint-ul public după fiecare reînnoire. Dacă utilizați variabilele Let's Encrypt încorporate în ONLYOFFICE în loc de un certificat gestionat de gazdă, urmați instrucțiunile Docker actuale pentru metoda respectivă și verificați comportamentul de reînnoire pentru imaginea și implementarea exactă pe care o rulați.

Pentru referință, consultați ghidul de instalare și HTTPS pentru Docker din ONLYOFFICE Docs , documentația Docker bind-mount , documentația Docker Compose , etichetele oficiale de imagine ONLYOFFICE Docker și instrucțiunile oficiale Certbot . Etichetele și detaliile interfeței disponibile se pot modifica; verificați-le atunci când pregătiți o nouă implementare.