Cum să configurezi CODUL Collabora pe Kubernetes cu Helm

O pagină Collabora Online poate rămâne goală sau poate raporta că serverul de birou nu este disponibil chiar și după ce pod-ul CODE rulează. Un pod sănătos este doar o parte a configurării: browserul și aplicația dvs. WOPI trebuie să ajungă la Collabora prin numele public de gazdă, setările TLS și proxy trebuie să fie de acord, iar Collabora trebuie să aibă încredere în gazda WOPI. Diagrama oficială Collabora Helm implementează serverul în Kubernetes; nu instalează sau configurează Nextcloud, ownCloud sau o altă gazdă WOPI pentru dvs.

Acest ghid utilizează diagrama Helm întreținută de Collabora cu un exemplu NGINX Ingress. Înlocuiți domeniile eșantion cu ale dvs. CODE este Collabora Online Development Edition, destinată evaluării, utilizării acasă și echipelor mici; Collabora spune că nu este recomandat pentru mediile de producție care necesită o versiune stabilă și suportată. Pentru sarcinile de lucru de producție, evaluați oferta Collabora Online suportată și termenii acesteia de licențiere și asistență.

Ce aveți nevoie înainte de instalare

• Un cluster Kubernetes funcțional kubectlși Helm 3 cu acces la cluster.
• Un controler Ingress instalat în cluster. Exemplul de mai jos folosește ingress-nginx; diagrama Collabora documentează și HAProxy și acceptă alte configurații de rutare.
• Un nume DNS, cum ar fi cel office.example.comcare indică adresa publică de intrare, plus un certificat TLS stocat ca Kubernetes Secret în spațiul de nume Collabora.
• O aplicație WOPI precum Nextcloud, cu o adresă URL precum cloud.example.com. Collabora trebuie să poată accesa aplicația WOPI, iar aplicația și browserele utilizatorilor trebuie să poată accesa Collabora.
• Un plan TLS clar. Acest exemplu termină HTTPS la intrare și trimite HTTP către serviciul Collabora din interiorul clusterului.

Pentru o implementare rapidă acasă sau de testare, un singur pod CODE simplifică rutarea. Replicile multiple pot îmbunătăți capacitatea, dar ghidul Kubernetes de la Collabora menționează o cerință de echilibrare a încărcării bazată pe WOPISrc, astfel încât sesiunile de editare pentru același document să ajungă la același pod. Nu scalați replicile înainte de a confirma că controlerul dvs. de intrare poate oferi afinitatea necesară.

Pasul 1: Adăugați graficul oficial și selectați o versiune

Collabora publică diagrama sa din proiectul CollaboraOnline. Pagina de lansare listează în prezent versiunea 1.3.5 a diagramei (verificată pe 6 octombrie 2026). Inspectați versiunile disponibile în mediul dvs. și fixați versiunea diagramei, astfel încât o actualizare ulterioară a depozitului să nu modifice în mod silențios diagrama pe care o implementați:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

Depozitul oficial de diagrame este util pentru verificarea setărilor implicite curente înainte de a scrie suprascrieri:

helm show values collabora/collabora-online --version 1.3.5

Dacă depozitul dvs. listează o diagramă compatibilă mai nouă atunci când urmați acest ghid, consultați notele de lansare și valorile acesteia înainte de a înlocui acea versiune. Versiunea diagramei și versiunea imaginii aplicației CODE sunt intrări de lansare corelate, dar nu reprezintă aceeași setare.

Pasul 2: Creați un spațiu de nume și protejați parola de administrator

Creați spațiul de nume și un secret Kubernetes pentru acreditările opționale de administrator Collabora ale graficului. Înlocuiți parola substituentă cu un secret puternic sau creați secretul prin intermediul managerului de secrete al organizației dvs. sau al fluxului de lucru pentru secrete GitOps. Nu confirmați o parolă reală în fișierul values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

Diagrama acceptă referirea la un secret existent. Activarea acestei opțiuni evită plasarea parolei de administrator direct în fișierul cu valori Helm. Păstrați secretul limitat la spațiul de nume și la utilizatorii sau conturile de serviciu care administrează această implementare.

Pasul 3: Configurați numele de gazdă, gazda WOPI și intrarea

Creați un fișier numit collabora-values.yaml. Acest exemplu presupune ingress-nginx, un secret TLS numit office-example-com-tlsși Nextcloud la https://cloud.example.com. Grupul de aliasuri trebuie să denumească gazda aplicației WOPI pe care Collabora are permisiunea să o contacteze; nu este numele public de gazdă Collabora.

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

Exemplul documentat al graficului permite aliasgroupsaccesul gazdei WOPI și al acestor parametri SSL atunci când un proxy invers termină TLS. În acest aranjament, traficul extern utilizează office.example.comHTTPS, în timp ce traficul de intrare redirecționează traficul către Collabora prin HTTP în interiorul clusterului. Dacă traficul de intrare utilizează TLS passthrough sau un alt protocol intern, nu copiați orbește aceste semnalizatoare SSL; ajustați-le pentru a se potrivi cu calea TLS reală și cu valorile curente ale graficului.

Confirmați că secretul TLS există în spațiul collaborade nume. Dacă utilizați un alt controler de intrare, înlocuiți clasa și adnotările cu echivalentele documentate ale acelui controler. Mențineți traficul websocket activat și permiteți conexiuni de lungă durată; setările implicite ale controlerului variază.

Pasul 4: Randarea și instalarea graficului

Randează mai întâi manifestele pentru a detecta erorile YAML și examinează setările generate pentru Ingress, Service și workload. Apoi instalează versiunea graficului fixat:

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

Urmăriți resursele pe măsură ce încep:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Așteptați ca pod-ul să devină Gata înainte de a conecta aplicația WOPI. Dacă rămâne în așteptare, verificați dacă clusterul are suficient CPU și memorie programabile și dacă selectorii de noduri, contaminanții sau cotele de resurse împiedică plasarea. Diagrama lasă solicitările și limitele de resurse la latitudinea operatorului; README-ul Collabora oferă exemple de valori mai mari ale resurselor pentru mediile de producție, dar dimensionarea reală depinde de editarea concomitentă și de volumul de lucru al documentelor.

Pasul 5: Conectați Nextcloud sau o altă gazdă WOPI

Deschideți setările Office sau Collabora ale aplicației WOPI și introduceți adresa URL a serviciului extern https://office.example.com. În Nextcloud, manualul de administrare descrie setarea adresei URL a serverului Collabora Online în setările de administrare Office. Verificați și lista de permisiuni pentru solicitările WOPI din Nextcloud dacă configurația restricționează gazdele care se pot conecta. Adresa trebuie să fie accesibilă atât de browserele utilizatorilor finali, cât și de serverul de aplicații care face solicitări WOPI.

Dacă conexiunea eșuează și afișează un mesaj de tip „gazdă WOPI neautorizată” sau similar, comparați adresa URL reală a gazdei WOPI cu collabora.aliasgroups. Verificați schema, numele gazdei și portul și adăugați în mod deliberat orice nume de gazdă alternative legitime. Evitați modelele largi de gazdă, cu excepția cazului în care înțelegeți efectul acestora. Dacă utilizați mai multe aplicații WOPI, urmați structura grupurilor de aliasuri documentată din diagramă pentru fiecare gazdă, în loc să permiteți fiecare domeniu.

Când ar trebui să scalezi dincolo de un singur pod?

Pentru o perioadă de probă de mică amploare, o singură replică cu scalarea automată dezactivată evită complexitatea rutării. Pentru mai multe replici, diagrama README din Collabora arată afinitatea NGINX pe baza WOPISrcargumentului interogării. Adăugați adnotarea documentată la fișierul ingress atunci când utilizați ingress-nginx:

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

Aceasta direcționează cererile pentru același document către același pod backend, ceea ce este important pentru editarea colaborativă și cererile de clipboard. Verificați documentația pentru versiunea exactă a controlerului de intrare; o adnotare acceptată de ingress-nginx nu este automat validă pentru HAProxy, Traefik sau o implementare Gateway API. După activarea mai multor replici sau a scalării automate, testați editările simultane ale aceluiași document și urmăriți jurnalele Collabora și jurnalele de acces la intrare. Dimensionarea resurselor, comportamentul sesiunii și disponibilitatea ridicată necesită validare specifică sarcinii de lucru.

Verificați implementarea din exterior

1. Confirmați că Kubernetes raportează pod-ul ca fiind Ready și că Service și Ingress există kubectl get pods,svc,ingress -n collabora:.
2. Verificați endpoint-ul public de descoperire. Ar trebui să returneze XML în loc de o eroare de browser sau proxy:

   curl -fsS https://office.example.com/hosting/discovery | head -c 300

3. Deschideți aplicația WOPI și editați un document de test. Confirmați că editorul încarcă, salvează modificările și, la redeschiderea documentului, se afișează conținutul salvat.
4. Dacă utilizați mai multe replici, deschideți același document în două sesiuni și confirmați că ambele pot colabora fără reconectări repetate. Acest lucru ajută la identificarea afinității lipsă pentru sesiuni.
5. Verificați jurnalele pentru erori TLS, autorizare WOPI sau erori în amonte:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   Dacă diagrama creează o sarcină de lucru cu un nume diferit, utilizați kubectl get deployments -n collaborași înlocuiți numele real.

Un răspuns de descoperire reușit confirmă că endpoint-ul public servește metadate Collabora; nu dovedește că autentificarea WOPI sau salvarea documentelor funcționează. Testul complet al documentelor este verificarea finală.

Puncte comune de defecțiune

• Ingress returnează 404 sau 502: verificați DNS, clasa de intrare, secretul TLS și punctele finale ale serviciului. Confirmați că intrarea poate ajunge la serviciul Collabora pe portul de serviciu al graficului.
• Descoperirea funcționează, dar editorul rămâne gol: verificați erorile consolei browserului și jurnalele proxy. Verificați setările de terminare HTTPS, gestionarea websocket-urilor și timeout-urile lungi pentru solicitări.
• Gazdă WOPI neautorizată: permiteți originea aplicației WOPI în aliasgroups; nu înlocuiți numele de gazdă al serverului de birou.
• Pod-ul repornește sau este eliminat: inspectați kubectl describe podjurnalele containerului, apoi setați solicitări de resurse și limite realiste pentru clusterul disponibil.
• Editarea devine instabilă după adăugarea de replici: verificați afinitatea bazată pe WOPISrc și confirmați că controlerul păstrează argumentul de interogare la rutarea cererilor.

Odată ce diagrama este instalată, punctul final de descoperire este accesibil și un document real a fost deschis și salvat cu succes prin aplicația WOPI, implementarea CODE de bază funcționează. Păstrați versiunea diagramei fixată și repetați aceste verificări după actualizările diagramei, modificările de intrare sau modificările de scalare.

Referințe oficiale

• Diagramă și ghid de implementare Kubernetes Helm întreținute de Collabora
• Valorile graficului Collabora Helm
• Lansări în topul Collabora
• Ghid pentru ediția de dezvoltare online Collabora (CODE)
• Manual de configurare Nextcloud Office
• documentația adnotărilor ingress-nginx
• Referință comandă instalare Helm