Privát Office callback-útvonal beállítása

Használd ezt az útmutatót olyan előkészített fizikai teszt-runtime-hoz, amely távoli Office renderert használ. A callback lehetővé teszi, hogy a renderer dokumentumokat kérjen le a cél BFF-től a meglévő megosztott HTTPS proxyn keresztül.

Mielőtt elkezded

Készítsd elő a runtime-ot a külön teszt-környezet útmutatóval. Használj abszolút fizikai könyvtárat, symlinkek nélkül. A célkönyvtárnak tartalmaznia kell a .env és a compose.yaml fájlt, a példányazonosítójának pedig el kell térnie az eredeti gyökértől.

Tartsd a meglévő megosztott Nginx Proxy Managert (NPM) egészséges és futó állapotban, a meglévő HTTPS port-leképezésével. Futtasd a helyi Tailscale-t úgy, hogy a meglévő listener elérhető legyen ennek a gépnek a Tailscale-címén. A setup ellenőrzi ezt a címet és a listenert, mielőtt erőforrásokat hoz létre. Nem hoz létre proxyt vagy listenert, és nem visz át éles útvonalat.

A setupOfficeCallback.sh futtatásához tartsd meg a meglévő CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_ZONE_ID és CLOUDFLARE_TOKEN értékeket az eredeti forrásgyökérben. A callback parancs ebből a gyökérből olvassa a kezelési hitelesítő adatokat, ezért csak a callback setup miatt nem kell átmásolnod őket a célkörnyezetbe. A kiválasztott aktív zónának ehhez a fiókhoz kell tartoznia, és tartalmaznia kell a callback hosztnevet. A tokennek DNS-hozzáférés kell a tanúsítványkiállításhoz és a saját tulajdonú DNS-rekordhoz. Ne másold át ezeket a kezelési hitelesítő adatokat a célalkalmazás-szolgáltatások környezetébe.

Ez a forrásgyökérre vonatkozó szabály csak a callback setupra érvényes. Egy külön engedélyezett providerrel futó runtime igényelhet privát kezelési beállításokat a saját életciklus-gyökér .env fájljában. Bekapcsolt Microsoft mellett az indításhoz saját Graph callback URL-ek és teljes Cloudflare kezelési beállítások kellenek. Lásd a Microsoft-előfeltételeket külön snapshothoz. Ezek az életciklus-beállítások nem valók az alkalmazás-szolgáltatások környezetébe.

Az eredeti gyökérnek a meglévő NPM-konténert és az adminisztrátori hitelesítő adatokat is ki kell választania. Használj valódi e-mail-címet a hitelesített NPM-adminisztrátorhoz. Az NPM ennek a felhasználónak az e-mail-címét használja tanúsítvány-kapcsolattartóként, és a felhasználási feltételek (Terms of Service) elfogadásával hívja meg a certbotot. A setup a DNS- vagy tanúsítványmódosítások előtt elutasítja a hibás formátumú címeket, valamint a fenntartott helyi vagy példa domaineket. Ez a korlátos ellenőrzés nem bizonyítja a külső e-mail-kézbesíthetőséget.

Az NPM-felhasználó e-mail-címe egyben az adminisztrátori bejelentkezési név is. Ha módosítod a tanúsítvány-kapcsolattartót, frissítsd ugyanennek a felhasználónak az e-mail-címét. A meglévő jelszavát és szerepköreit hagyd változatlanul. Szinkronizáld az NPM_ADMIN_EMAIL értéket mindenhol, ahol ennek a fióknak a kezelési hitelesítő adatait használod. Frissítsd az eredeti gyökeret és minden olyan teszt-runtime-ot is, amely ezeket használja.

A célkonfigurációban állítsd a REMOTE_WOPI_ALLOWED_CIDRS értékét a tényleges renderer Tailscale IPv4-címekre /32 CIDR formában, a 100.64.0.0/10 tartományon belül. Ez a setup nem fogad el tetszőleges privát RFC1918-címeket. Ha több renderer küld callbacket, használj vesszővel elválasztott listát. A renderernek privát hálózati hozzáféréssel kell elérnie a helyi Tailscale-címet és a meglévő HTTPS-portot.

A callback név kiválasztása

Állítsd be ezeket az értékeket a kiválasztott célkonfigurációban:

ECS_ORIGIN_DEPLOYMENT_ID=ttrmb
ECS_PUBLIC_HOST_PREFIX=test
WOPI_CALLBACK_DOMAIN_SUFFIX=ecs.t42.hu

Az NPM_HTTPS_PORT=8443 beállítással az origin-számítás ezt adja:

REMOTE_WOPI_ORIGIN=https://test.wopi.ttrmb.ecs.t42.hu:8443
WOPI_CALLBACK_MODE=private

A suffix opcionális. Ha nincs beállítva vagy üres, az origin-számítás megtartja a korábbi callback-módokat és beállításokat. Lásd a callback környezeti referenciát.

Az explicit setup futtatása

Az eredeti projektgyökérből futtasd:

bash setupOfficeCallback.sh --target-runtime /absolute/physical/runtime

Cseréld le az /absolute/physical/runtime értéket az előkészített teszt-runtime könyvtárára. A parancs soha nem választja ki az éles környezetet alapértelmezett célként.

A setup pontos tulajdonjogú, DNS-only A rekordot hoz létre, amely az ellenőrzött helyi Tailscale IPv4-címre mutat. Nyilvános tanúsítványt szerez a DNS-01 challenge segítségével, vagy újrahasznál egy érvényes, meglévő tanúsítványt. Az újrahasználathoz érvényes nyilvános lánc, hosztnév-lefedettség, elegendő hátralévő érvényesség és egyező privát kulcs kell.

A setup külön privát callback hosztot hoz létre a meglévő NPM-ben. Csak a szűk WOPI dokumentum GET útvonalakat továbbítja a cél BFF-hez, és a forrásokat a beállított renderer CIDR-ekre korlátozza. Más útvonalak nem teszik elérhetővé a BFF alkalmazást.

A parancs jelzi, hogy a callback konfigurálva van. Nem váltja át a böngészős Office-módot, és nem igazolja a teljes alkalmazás-folyamatot. A szokásos hibrid placement-váltást külön alkalmazd. Lásd a privát placement-változatokat.

A nyilvános DNS-név és a nyilvános tanúsítvány nem teszi nyilvánosan elérhetővé a privát IP-címet. Ez a setup nem módosítja a távoli renderer trust store-ját.

A renderer-folyamat ellenőrzése

A további callback origin engedélyezése

A távoli Coolify Collabora szolgáltatásnak a böngészős origintől külön kell megbíznia a callback hosztban. Tartsd meg a kötelező WOPI_CALLBACK_ORIGIN változót az aliasgroup1 mezőben, és őrizd meg az összes meglévő jóváhagyott origint. Az opcionális WOPI_ADDITIONAL_CALLBACK_ORIGIN adja az aliasgroup2 értékét:

aliasgroup1: ${WOPI_CALLBACK_ORIGIN:?Reviewed callback origin required}
aliasgroup2: ${WOPI_ADDITIONAL_CALLBACK_ORIGIN:-}

Változó	Fogyasztó	Cél	Típus vagy formátum	Mikor kötelező	Alapérték	Példa	Korlátok vagy biztonság
WOPI_ADDITIONAL_CALLBACK_ORIGIN	Távoli Coolify Collabora aliasgroup2	Egy további WOPI callback origin engedélyezése	Kanonikus, pontos HTTPS origin a kiválasztott porttal együtt	Ha második callback originre van szükség	Üres. Nem ad hozzá hosztot.	https://test.wopi.ttrmb.ecs.t42.hu:8443	Nincs wildcard, hitelesítő adat vagy elérési út. Őrizd meg az elsődleges aliasgroup1 értéket és a meglévő jóváhagyott origineket.

A példa a fenti származtatott DNS-setupból származik. A távoli üzemeltető egyszer másolja át a tényleges származtatott REMOTE_WOPI_ORIGIN értéket a távoli környezetbe WOPI_ADDITIONAL_CALLBACK_ORIGIN néven. A helyi origin-számítás nem frissíti automatikusan a távoli Coolify környezetet.

Tartsd összhangban a Coolify mentett nyers Compose, generált Compose, szolgáltatás-környezeti és renderelt konténer-környezeti értékeit ezzel a leképezéssel és értékkel. Újralétrehozás előtt ellenőrizd a pontos saját tulajdonú Collabora erőforrást és szolgáltatást. Csak ezt az ellenőrzött Collabora szolgáltatást hozd létre újra a mentett konfigurációból. Őrizd meg az összes többi konténert, a meglévő adatokat és a proof key-t.

A Collabora a --use-env-vars kapcsolón keresztül támogatja a számozott aliasgroupN környezeti változókat. Az initializeEnvOptions függvényben az üres alias-group karakterlánc nem hoz létre hoszt-bejegyzést.

A böngészős beágyazás engedélyezése

A távoli Collabora renderernek engedélyeznie kell a pontos böngészős MAILGEN_PUBLIC_URL origint a net.content_security_policy beállítás frame-ancestors direktívájában. A böngészős origin tartalmazza a sémát, a hosztnevet és a portot. Ez eltér a callback origintől (REMOTE_WOPI_ORIGIN). A callback hoszt megbízhatósága, a böngészős CSP és a DNS/TLS külön előfeltétel. Állítsd be a callback-megbízhatóságot és a böngészős beágyazást is. A sikeres DNS/TLS önmagában egyik policyt sem elégíti ki.

A renderer coolwsd.xml fájljában az alábbi példa mutatja a <net> blokkon belüli beállítást, ha a policy még nem tartalmaz direktívákat:

<net>
    <content_security_policy>frame-ancestors https://browser.example.invalid:8443;</content_security_policy>
</net>

Cseréld le a https://browser.example.invalid:8443 értéket a pontos böngészős MAILGEN_PUBLIC_URL originre. Meglévő policy esetén add hozzá ezt az origint a jelenlegi frame-ancestors listához. Tartsd meg az összes meglévő jóváhagyott origint és minden más direktívát. Ne írd felül a meglévő policyt ezzel a példával. A net.frame_ancestors beállítás elavult.

Az aktuális előkészített Coolify rendererhez a docker/coolify/compose.yaml megköveteli a COLLABORA_CONTENT_SECURITY_POLICY változót. Állítsd be a teljes, ellenőrzött content security policyt (CSP), beleértve a pontos jóváhagyott böngészős origint. Tartsd meg a meglévő jóváhagyott origineket és minden más direktívát.

Változó	Fogyasztó	Cél	Típus vagy formátum	Mikor kötelező	Alapérték	Példa	Korlátok vagy biztonság
COLLABORA_CONTENT_SECURITY_POLICY	Távoli Coolify collabora szolgáltatás	A net.content_security_policy beállítása böngészős beágyazáshoz	Teljes, ellenőrzött CSP-karakterlánc	Aktuális előkészített Coolify renderer	Nincs. A be nem állított vagy üres érték blokkolja a Compose-interpolációt.	frame-ancestors https://browser.example.invalid:8443;	Cseréld le a példát a pontos jóváhagyott böngészős originre. Tartsd meg a meglévő jóváhagyott origineket és direktívákat. Önmagában a példa csak akkor érvényes, ha nincs más policy.

A Compose command tömbje egyetlen elemet tartalmaz:

command:
  - "--o:net.content_security_policy=${COLLABORA_CONTENT_SECURITY_POLICY:?Reviewed renderer CSP required}"

A tömb egyetlen argumentumként őrzi meg a policy szóközeit, és elkerüli a shell-idézőjelezést. A renderer entrypoint közvetlenül a /usr/bin/coolwsd --use-env-vars parancsot futtatja. A meglévő extra_params értéket hagyd változatlanul.

Mentsd el tartósan a változót és a command konfigurációt a tényleges Coolify szolgáltatás-beállításokban. A csak a futó konténeren belül végzett módosítás nem marad meg az újralétrehozás után. A felelős üzemeltető csak a saját tulajdonú collabora szolgáltatást hozza létre újra ezekből a tartósított beállításokból. Őrizd meg a nem kapcsolódó szolgáltatásokat, a meglévő adatokat és a proof key-t. Ez a konfigurációs előfeltétel nem igazolja az éles renderelés elfogadását.

A valódi renderer környezetből ellenőrizd a DNS-feloldást a tervezett Tailscale-címre, valamint a TLS-hosztnév és a tanúsítványlánc elfogadását. Ezután ellenőrizd a valódi callbacket és a teljes Office alkalmazás-folyamatot a kiválasztott runtime-ban. Az elfogadás addig függőben marad, amíg egy tényleges dokumentum be nem tölt a gyökéralkalmazásban. A sikeres setup-parancs, a tanúsítványkiállítás vagy a dependency-próba nem helyettesíti ezeket az ellenőrzéseket.

Tartsd külön a böngészős tanúsítvány-megbízhatóságot a renderer megbízhatóságától. A böngésző hosztoknak továbbra is szükségük lehet a meglévő helyi tanúsítvány-beállításukra.

Erőforrások megtartása és placement váltása

A célkörnyezet a privát tulajdonjogi állapotot a .docker-state/office-callback/ownership.json fájlban tárolja. A mentett nonce, az erőforrás-azonosítók és az operation intentek igazolják a tulajdonjogot. Őrizd meg ezt a fájlt a runtime-mal együtt. A fájl nem tartalmazza a Cloudflare-tokent. Az NPM a tanúsítványmegújításhoz a szabványos DNS-01 hitelesítőadat-mechanizmusán keresztül tárolja a tokent.

Az ismételt setup biztonságosan újrahasználja a pontos tulajdonjogú erőforrásokat. Elutasítja az idegen erőforrásokat és a váratlan módosításokat. A normál FullLocal váltás csak a saját tulajdonú callback hosztot tiltja le. Egy későbbi hibrid váltás újra engedélyezi azt. A DNS és a tanúsítványok elérhetők maradnak az újrahasználatra.

Állítsd le a kiválasztott példányt a privát placement-változatok váltása előtt. Őrizd meg az adatait, a kulcsait és a volume-okat. A FullLocal akkor is helyben tartja az Office-t, ha az opcionális callback név beállítva marad.

Helyreállítás félbeszakadt tanúsítványkiállítás után

A mentett certificate_intent blokkolja a duplikált tanúsítvány POST-ot. Elveszett válasz után az újrapróbálkozás újrahasználhat egy érvényes, meglévő tanúsítványt. Ne törölj bizonytalan vagy folyamatban lévő intentet azért, hogy újabb kiállítást kényszeríts ki.

1. Vizsgáld meg a kiválasztott NPM tanúsítványrekordjait a pontos callback domainre és a cél tulajdonjogi fájljában szereplő tanúsítványazonosítóra. Hasonlítsd össze a saját tulajdonú útvonalat és domaint ezzel a fájllal.
2. Vizsgáld meg az NPM kiállítási naplóit és az aktív certbot-folyamatokat erre a domainre. Ha a kiállítás még aktív vagy a kimenetele bizonytalan, tartsd meg az intentet, és először ezt az állapotot rendezd.
3. Csak ismert sikertelen kísérlet után ellenőrizd, hogy nem létezik egyező tanúsítvány, és nincs aktív kiállítás. Javítsd a jelzett okot, szükség esetén az NPM-kapcsolattartót és a szinkronizált bejelentkezési beállításokat is.
4. Szerkesztés előtt készíts privát biztonsági mentést a cél .docker-state/office-callback/ownership.json fájljáról. Használj 0700 módú privát könyvtárat és 0600 módú mentési fájlt. Csak a sikertelen certificate_intent mezőt távolítsd el a saját tulajdonú JSON-ból. Őrizd meg az identitást, a nonce értéket, a dns_id mezőt és minden más mezőt. Ez védett kézi helyreállítás, nem külön termékparancs.
5. Futtasd újra a bash setupOfficeCallback.sh --target-runtime /absolute/physical/runtime parancsot az eredeti projektgyökérből ugyanazzal a céllal.

Soha ne töröld a teljes tulajdonjogi fájlt vagy az idegen tanúsítványokat. Őrizd meg az éles útvonalakat és minden nem kapcsolódó proxy-erőforrást.