A gyökérkörnyezet konfigurálása
Az egységes runtime a motherrepo gyökerében lévő .env fájlt olvassa. Ha a gép nincs előkészítve, kezdd az első installation útmutatóval. A pontos változókhoz használd a környezeti referenciát.
Új konfiguráció előkészítése
Állítsd vissza az ellenőrzött archívumot a környezeti titkok mentése és visszaállítása útmutatón keresztül, vagy csak új, üres példány esetén másold a .env.example fájlt. Ne írd felül a meglévő fájlt a sablonnal.
A fájl szöveges értékadásokat tartalmaz, nem shell-parancsokat. Változónként egy értékadás legyen. Ne futtasd source vagy export $(...) paranccsal. Az önálló szolgáltatások .env.example fájljai külön belépési pontokat írnak le. Nem írják felül az egységes gyökérszerződést.
Adatmegtartás esetén őrizd meg a példány-azonosítót, a tenant-azonosítót, az adatbázis-hitelesítő adatokat, a Kafka cluster-azonosítót és a titkosítási kulcsokat. Egy megváltoztatott jelszó-értékadás nem módosítja azt a jelszót, amelyet a szolgáltatás már tárol.
Elhelyezés és végrehajtás külön kiválasztása
ECS_DEPLOYMENT_MODE | ECS_REMOTE_SIMULATION | Eredmény |
|---|---|---|
Hiányzik vagy fulllocal | Hiányzik vagy false | A kiválasztott infrastruktúra helyben fut |
partialRemote | true | Valódi helyi szolgáltatások gyakorolják a remote konfigurációs útvonalat |
partialRemote | Hiányzik vagy false | Előkészített remote Kafka, ClamAV, Collabora, Tika és Qdrant |
fulllocal | true | Érvénytelen konfiguráció |
Valódi remote módban a BFF, az Account, a backend/.NET szolgáltatások, a PostgreSQL, a SeaweedFS/S3, az OpenSearch, a Dragonfly, a proxy és a kulcsok helyben maradnak. A szimuláció nem alacsonyabb memóriaigényű elhelyezés.
A development végrehajtás a forrást figyeli. A production végrehajtás lefordított kimenetet futtat. A mentett szolgáltatásmódok eltérhetnek. Lásd a végrehajtási módokat.
A távoli blokk kitöltése
Valódi remote mód kiválasztása előtt töltsd ki a remote előfeltételeket. A .env.example értékei helyi szimulációs példák, nem kész remote endpointok.
| Gyökérbemenet | Szükséges jelentés |
|---|---|
REMOTE_KAFKA_BOOTSTRAP_SERVERS | Három elérhető, meghirdetett host:port endpoint, vesszővel elválasztva |
REMOTE_KAFKA_SECURITY_PROTOCOL, REMOTE_KAFKA_SASL_MECHANISM | Brokerkompatibilis átvitel és SASL-mechanizmus |
REMOTE_KAFKA_APP_USERNAME, REMOTE_KAFKA_APP_PASSWORD | Távoli alkalmazásszerepkör hitelesítő adatai |
REMOTE_KAFKA_ADMIN_USERNAME, REMOTE_KAFKA_ADMIN_PASSWORD | Külön, távoli adminisztrációs szerepkör hitelesítő adatai |
REMOTE_KAFKA_EXPECTED_CLUSTER_ID | Várt, meglévő távoli cluster-azonosító |
REMOTE_CLAMAV_SCAN_URL, REMOTE_CLAMAV_SCAN_TOKEN | Hitelesített HTTPS scanner-URL, pontosan /scan végződéssel, a tokenjével |
REMOTE_KNOWLEDGE_EXTRACTOR_URL, REMOTE_KNOWLEDGE_EXTRACTOR_TOKEN | HTTPS extractor-origin, külön tokennel |
REMOTE_COLLABORA_URL | Collabora origin, hitelesítő adatok és endpoint-útvonal nélkül |
REMOTE_QDRANT_URL, REMOTE_QDRANT_API_KEY | Qdrant origin és API-kulcsa |
REMOTE_WOPI_ORIGIN, REMOTE_WOPI_ALLOWED_CIDRS | Elérhető helyi callback-origin és a korlátozott renderer-forráscímek |
WOPI_CALLBACK_MODE, WOPI_TAILSCALE_HOST, WOPI_TAILSCALE_BIND_IP, WOPI_TAILSCALE_PORT | Callback-mód és ennek a helyi gépnek a Tailscale HTTPS-kötése |
Szolgáltatás-originhez ne adj query-t, fragmentet vagy beágyazott hitelesítő adatot. A scanner a fix /scan útvonalat követeli meg. Az extractor-kliens saját útvonalat ad hozzá. A generált fogyasztói értékek kézi megadása helyett a gyökér REMOTE_* bemeneteket használd.
A REMOTE_CLAMAV_HOST és a REMOTE_CLAMAV_PORT a szimulációs TCP-scannert írja le. Valódi módban csak kifejezetten jóváhagyott, privát TCP-konfigurációhoz tartsd meg őket. A clamav Docker-név nem remote privát IP.
Coolify-értékek
A SERVICE_URL_* protokollt tartalmazó origin. A SERVICE_FQDN_* hosztnevet tartalmaz. A SERVICE_PASSWORD_* értékek ahhoz a Coolify-erőforráshoz tartoznak. A laptop nem tudja feloldani egy távoli erőforrás változóhivatkozását. A feloldott hitelesítő adatot biztonságosan szerezd be.
HTTP-doméneket a Coolify menedzselt proxyján keresztül állíts be. Egy belső szolgáltatásport nem feltétlenül nyilvános kliensport. Ne töröld a nem kapcsolódó proxy-erőforrásokat. A helyi setup nem hoz létre Coolify-erőforrásokat.
Kafka-szállítás és azonosság
A Kafka saját TCP-protokollt használ, nem HTTPS URL-t. A kliensek a bootstrap brokerhez csatlakoznak, majd a metaadatban megnevezett brokerekhez. Minden meghirdetett endpointnak működnie kell. Egyetlen port sikeres kapcsolódása nem elég.
Valódi sasl_plaintext csak kanonikus Tailscale IPv4 endpointokra használható, a 100.64.0.0/10 tartományban, PLAIN mechanizmussal. Más távoli Kafka-kapcsolat sasl_ssl-t kíván. A REMOTE_KAFKA_CA_PATH nem támogatott, és nem állít be egyedi megbízhatósági láncot.
A KAFKA_CLUSTER_ID a megtartott helyi azonosító. A REMOTE_KAFKA_EXPECTED_CLUSTER_ID a kiválasztott távoli clustert ellenőrzi. Egyiket se módosítsd csak azért, hogy egy tulajdonosi hibát elkerülj.
Office callback
A távoli Collabora a helyi BFF-től kapott, rövid életű, aláírt WOPI-engedéllyel olvas fájlt. A WOPI a renderer által használt dokumentumhozzáférési protokoll. A bejelentkezés, a Graph-jogosultság, a személyes e-mail-kulcsok és a WOPI-aláírókulcs külön szerepkörök.
WOPI_CALLBACK_MODE=tailscale-proof esetén a hosztnév és a bind IP a helyi fejlesztői gépet azonosítja. A REMOTE_WOPI_ALLOWED_CIDRS a távoli renderert korlátozza, általában egyetlen /32 forráscímre. Az érvényes TLS-t és a Tailscale-hozzáférési szabályokat külön készítsd elő. Egy konfigurációs értékadás nem ad hálózati hozzáférést.
Használd a meglévő NPM-proxyt és a korlátozott callback-útvonalakat. Ne tedd elérhetővé a teljes BFF/admin felületet, és ne küldj privát aláírókulcsot a renderernek. A callback-cím nem helyettesíti az Account vagy a BFF bejelentkezési címét.
fulllocal módban a megtartott távoli callback-beállítások inaktívak. Nem kell őket törölni.
Konfigurációmódosítás alkalmazása vagy visszavonása
Új gépen a konfigurációt a bash 0daysetup.sh előtt fejezd be. Működő gépen egy egyeztetett karbantartási ablakban használd a sima újraindítást.
- Őrizd meg a konfigurációt, a kulcsokat és az adatmentéseket. Válassz ki egy aktív, teljes stacket.
- A régi beállításokkal futtasd a
bash stopDevServer.shparancsot. Ez megőrzi a volume-okat. - Új távoli Kafka- vagy Qdrant-célpont előtt az operátor vigye át és ellenőrizze az állapotot, miközben az alkalmazásírók le vannak állítva.
- Csak a szükséges kiválasztókat és távoli mezőket módosítsd. A helyi adatbázis-, S3-, OpenSearch- és Dragonfly-értékeket tartsd meg.
- Futtasd az ellenőrzéseket, majd a sima újraindítást:
bash devstack.sh validate
bash restartDevServers.sh
bash devstack.sh status
A sima újraindítás megőrzi a mentett végrehajtási módokat. Ha a kiválasztott teljes stacket kifejezetten production módra akarod, add hozzá a --prod opciót. Egyik újraindítási útvonal sem futtat sémainicializálást. A sima újraindítás nem építi újra a lefordított artifactokat. Kódkiadáshoz használd a production publikálási eljárást. Ezután ellenőrizd a bejelentkezést, a mailboxadatokat, az üzenettörzseket, a keresést, az Office-t és a tudásbázis-lekérést a tényleges alkalmazáscímeken.
A Kafka-offsetek és az adatbázis-duplikációszűrő állapota együtt tartozik. Egy új, üres cluster nem egyenértékű az eredetivel. A fulllocal módba való visszaváltás nem másol újabb távoli eseményeket vagy Qdrant-pontokat a régi helyi volume-okba. Először ellenőrizd a frissességet és a visszafelé irányuló migrációt.
A quickStarter.sh a változatlan, előkészített konténereket folytatja. Nem alkalmazza ezt a konfigurációmódosítást. Remote mód a reset kérést akkor is elutasítja, ha szimuláció fut. Ne válts helyi módra a megkerüléséhez.
Forrásválasztás és izolált tesztek
Ha az ECS_APPLICATION_SOURCE_ROOT hiányzik, üres vagy ., akkor ez a checkout adja a forrást. Az abszolút, átnézett pillanatkép az alkalmazásforrást választja ki, miközben a gyökérkonfiguráció, az azonosító, az állapot, az engedélyezés és az adatok helyben maradnak. Lásd az átnézett forrást.
Külön tesztpéldányhoz saját fizikai pillanatkép, konfiguráció, friss adat, kulcsok és Kafka-/Qdrant-névtér kell. Egy shell-es ECS_INSTANCE_ID felülírás nem elegendő. Készítsd elő az elszigetelt tesztpéldányt egyeztetett útvonalakkal és kapacitással.