WorkSmartHub Dockeren és Kubernetesen

WorkSmartHub Dockeren és Kubernetesen

Ezen az oldalon

Ez a repository elkészíti a WorkSmartHub konténer-image-ét, és futtatja Dockerrel vagy Kubernetesen; ez a dokumentum mindkét üzemeltetési mód leírása. A WorkSmartHub (WorkWise Solutions) egyetlen webalkalmazás: az ASP.NET Core szervert és az Angular portált ugyanaz a konténer szolgálja ki, ugyanazon a porton.

A repository tartalma#

Útvonal Mi ez
build/build-image.sh, build/build-image.ps1 A worksmarthub:<verzió> image elkészítése a Backend és a Frontend forrásmappájából (bash vagy PowerShell)
docker/linux/ worksmarthub-run.sh (a konténer indítása), worksmarthub-service-install.sh / worksmarthub-service-uninstall.sh (systemd szolgáltatás)
docker/win/ Ugyanez Windowsra, Docker Desktoppal: worksmarthub-run.ps1, worksmarthub-service-install.ps1 / worksmarthub-service-uninstall.ps1 (ütemezett feladat)
kubernetes-helm-chart/ A worksmarthub Helm chart: az alkalmazás, egy tartós adatkötet, opcionálisan beépített PostgreSQL és Redis, Ingress, NetworkPolicy-k
test-local/ Tesztszkriptek helyi Docker démonhoz és minikube-hoz (lásd test-local/README.md)

Előfeltételek#

  • Docker: Linuxon Docker Engine 20.10 vagy újabb, Windowson Docker Desktop (részletek: Docker előfeltételek).
  • Kubernetes: egy fürt, kubectl és Helm 3 (részletek: Kubernetes előfeltételek).
  • Az image elkészítéséhez: a Backend .NET SDK-ja (WorkSmartHub/global.json), Node.js és npm, Docker, valamint bash (Windowson Git Bash) vagy PowerShell 5.1 vagy 7.
  • Az image az ASP.NET Core 10.0 futtatókörnyezetet tartalmazza Ubuntu 24.04 LTS-en, és a nem root appuser felhasználóként (uid 1001) fut. A gépekre nem kell .NET futtatókörnyezet; a futtatókörnyezet frissítése új image-dzsel érkezik.

Az image elkészítése#

Nincs registry és nincs pipeline: az image helyben készül a két forrásmappából.

bash
# ebből a repositoryból, ha a források a ../WorkSmartHub-Backend és ../WorkSmartHub-Frontend testvérmappákban vannak
bash build/build-image.sh --version 23
powershell
.\build\build-image.ps1 -Version 23

A szkript

  1. lefordítja a Frontendet (npm ci && npm run build; a csomag a .br és .gz fájljaival a dist/ mappájába kerül); a --skip-frontend-build / -SkipFrontendBuild a meglévő dist/ mappát használja;
  2. a Backend forrását egy ideiglenes munkamappába másolja (.git, bin, obj, helyi adatbázisok, naplók és File Storage nélkül), a Frontend csomagot a másolat WorkSmartHub/wwwroot/Frontend mappájába teszi, és a verziót ReleaseId-ként beírja a másolat wwwroot/version.json fájljába (az alkalmazás által mutatott kiadásszám; csak pozitív egész kerül be, egy 23-rc1 jellegű címke esetén a fájl változatlan marad);
  3. lefuttatja a dotnet publish -c Release parancsot a másolaton;
  4. lefuttatja a docker build --pull parancsot a publish kimenet Dockerfile-jával, és worksmarthub:<verzió>, valamint worksmarthub:latest címkét ad.

A forrásmappák nem változnak: a build fájlokat generál újra (az API klienst, az appsettings.template.json-t), és ez a munkamappa másolatában történik, amelyet a szkript a végén töröl (a --keep-staging / -KeepStaging megtartja). Az image címkéi: org.opencontainers.image.version, valamint a két forrásmappa Git revíziója (com.workwise.worksmarthub.backend.revision, ...frontend.revision, nem commitolt változásnál +dirty utótaggal).

Kapcsoló (bash / PowerShell) Alapérték Jelentés
--backend <mappa> / -Backend ../WorkSmartHub-Backend A Backend mappa (a submodules/WorkWise.Common almodullal)
--frontend <mappa> / -Frontend ../WorkSmartHub-Frontend A Frontend mappa
--skip-frontend-build / -SkipFrontendBuild A <frontend>/dist újrahasználása
--changelog <file> / -Changelog <file> ../WorkSmartHub-Changelog/changelog.html A portálon megjelenő kiadási jegyzék, az image-be wwwroot/changelog.html néven kerül
--version <v> / -Version a WorkSmartHub/wwwroot/version.json ReleaseId értéke, ha pozitív Az image címkéje. Fejlesztői munkapéldányban ott -1 áll, ezért adja meg a verziót
--repository <név> / -Repository worksmarthub Az image neve, registryhez pl. docker.io/cegnev/worksmarthub
--no-latest / -NoLatest Ne kerüljön át a latest címke
--minikube / -Minikube A minikube Docker démonjában készül; másik profilhoz --minikube-profile <név> / -MinikubeProfile
--save <fájl.tar> / -Save Az image-et tar fájlba is kiírja
--no-cache / -NoCache Rétegcache nélkül készül, így az image a legfrissebb Ubuntu biztonsági frissítéseket kapja
--staging <mappa> / -Staging új ideiglenes mappa Ide kerül a másolat és a publish kimenet (üres kell legyen)
--keep-staging / -KeepStaging A munkamappa megtartása

Másik gépre. Fájlként vigye át: --save worksmarthub-23.tar, a fájl átmásolása, majd a célgépen docker load -i worksmarthub-23.tar.

minikube. A --minikube közvetlenül a minikube Docker démonjában építi az image-et (eval $(minikube docker-env)), így a fürt registry nélkül is megtalálja. A minikube image load ekkora image-nél Windowson nem használható: hibával leáll.

bash
minikube start --driver=docker
bash build/build-image.sh --version 23 --minikube

Később registryvel. A --repository registry.example.com/worksmarthub kapcsolóval készítse, docker push mindkét címkére, és ugyanezt a repositoryt állítsa be a Docker szkriptekben (WSH_IMAGE vagy --image) és a chartban (app.image.repository).

Mi van az image-ben. A publish kimenet a /app alatt (belépési pont dotnet WorkSmartHub.dll, az appuser tulajdonában), a 8080-as figyelési port, és a /app/data adatmappa, amelybe a /app/database.db, /app/FileStorage és /app/Logs hivatkozás mutat (lásd Adatmegőrzés). Az image-ben van bash, sh, tar és openssl, de nincs curl vagy wget, és nincs HEALTHCHECK utasítás (lásd Állapotellenőrzés).


Docker#

A docker/linux és a docker/win mappa szkriptjei Docker-konténerként futtatják az alkalmazást: előtérben, háttérben, vagy a gép indulásakor induló szolgáltatásként.

Docker előfeltételek#

  • Linux: Docker Engine 20.10 vagy újabb (docker version), a Docker saját csomagtárolójából telepítve, induláskor engedélyezve (sudo systemctl enable --now docker). A szkripteket sh paranccsal futtassa; a szolgáltatás telepítő és eltávolító szkriptje rootjogot kér (sudo sh ...).
  • Windows: Docker Desktop WSL 2 háttérrel, Linux-konténerekkel. Az indítószkripthez nem kell rendszergazdai jog, a szolgáltatás telepítéséhez és eltávolításához igen.
  • A worksmarthub:<verzió> image a gépen: ott készült (Az image elkészítése), vagy docker load -i paranccsal betöltötték.
  • Opcionálisan egy appsettings.json és egy worksmarthub.env az indítószkript mellett (lásd Beállítások).
  • Szolgáltatásként telepítéshez olyan szkriptmappa, amelyet a gép más felhasználói nem írhatnak (lásd A szkriptmappa védelme).

Beállítások#

Az alkalmazás a /app/appsettings.json fájlt és a környezeti változókat olvassa; a környezeti változó felülírja a fájlt. A változó neve a beállítás útvonala, a szakaszok között __ jellel, tömbelemeknél __0, __1: ConnectionStrings__InternalDb, CacheSettings__Type, HttpSettings__Urls__0, PublicBaseUrl.

Fájl nélkül a konténer az image-be épített appsettings.json-nal fut: SQLite az adatkötetben, memóriabeli cache, helyi felhasználók. Az indítószkript minden esetben beállítja a HttpSettings__Urls__0=http://+:8080 figyelési címet. További beállításhoz két út van:

  • worksmarthub.env az indítószkript mellett: környezeti változók, soronként egy NÉV=érték, idézőjelek és export nélkül. A szkript --env-file kapcsolóval adja át. Titkos értékekhez ez a megfelelő hely; csak a rendszergazdák olvashassák (sudo chown root:root worksmarthub.env && sudo chmod 600 worksmarthub.env).
  • appsettings.json az indítószkript mellett: a teljes beállításfájl, a /app/appsettings.json helyére csatolva. Az image gyári fájljából induljon ki:
    bash
    docker run --rm --entrypoint cat worksmarthub:23 /app/appsettings.json > appsettings.json
    Az alkalmazás minden induláskor beleírja a fájlba egy újabb verzió új beállításkulcsait, és megtartja az Ön értékeit (előtte biztonsági másolatot ír a konténer /app mappájába: appsettings.json.backup.<időpont>). Ehhez az alkalmazásnak (uid 1001) írnia kell tudnia a fájlt: Linuxon sudo chown 1001:root appsettings.json && sudo chmod 600 appsettings.json. Root tulajdonú, 644-es módú fájllal is működik: ekkor az alkalmazás naplózza, hogy appsettings.json is read-only; new settings keep their defaults until the file is updated, és az új kulcsokat az alapértékükkel, memóriában használja. Root tulajdonú, 600-as vagy 640-es módú fájlt nem tud olvasni, és nem indul el. Mindenki által írhatóvá soha ne tegye a fájlt.

A fájl megjegyzésekkel kiegészített JSON; minden beállítás magyarázata benne van. A szakaszok:

Szakasz Szerepe
ConnectionStrings A belső adatbázis: InternalDbType (0 SQLite, 1 SQL Server, 2 PostgreSQL, 3 MySQL), InternalDb (kapcsolati karakterlánc), Schema (csak SQL Server és PostgreSQL; SQLite-nál és MySQL-nél üres kell legyen), MySqlServerVersion (csak MySQL)
CacheSettings Type: InMemory (alapérték), None, Redis, SqlServer, Postgres, MySql, mindegyikhez saját beállításblokkal
PublicBaseUrl A cím, amelyen a felhasználók megnyitják az alkalmazást (lásd lent)
HttpSettings Urls (figyelési címek; a konténerben http://+:8080), Cors
Swagger Enabled: az interaktív API-leírás a /swagger címen
Serilog Naplókimenetek (konzol és a Logs/log-.txt napi fájlok) és naplózási szintek
UseDetailedExceptions Hibarészletek az API hibaválaszaiban
UserSettings A felhasználótár: Local (alapérték), LDAP, AzureAD (Microsoft Entra ID), ActiveDirectory
LoginSettings AuthType (Local, ActiveDirectory, AppleConnect, OAuth), a munkamenet hossza, az OAuth szolgáltatók (Okta, Google, Microsoft, Custom), a bejelentkezési süti, a JWT aláírókulcs
Notifications A Microsoft Teams szolgáltatás címe
EmailSettings Az alkalmazás által küldött e-mailek SMTP szervere
TicketAttachment, ImageConfiguration A munkalap-mellékletek és alkatrészképek hivatkozásainak aláírókulcsa, élettartama és a feltöltés darabmérete
ConfigSync Milyen gyakran veszik át a csomópontok az Admin felületen tett beállításváltozásokat (alapérték 10 másodperc)

Minden más (File Storage-ok, értesítési csatornák, a Számlázz.hu kapcsolat, szolgáltatás felhasználói katalógusok, biztonsági fejlécek, háttérfolyamatok, megjelenés) az Admin felületen állítható, és az adatbázisban tárolódik.

Az első éles használat előtt beállítandók#

Beállítás Miért
LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey A bejelentkezési és a személyes hozzáférési tokeneket írja alá. A gyári érték nyilvános: azzal bárki hamisíthatna tokent bármely felhasználó nevében. Későbbi módosítása mindenkit kijelentkeztet, és érvényteleníti a hozzáférési tokeneket.
TicketAttachment.DownloadLink.SymmetricSecurityKey A munkalap-mellékletek letöltési hivatkozásait írja alá. Későbbi módosítása érvényteleníti a korábban feltöltött mellékletek hivatkozásait.
ImageConfiguration.ImageLink.SymmetricSecurityKey Az alkatrészképek hivatkozásait írja alá. Későbbi módosítása érvényteleníti a korábban feltöltött képek hivatkozásait.
PublicBaseUrl pl. https://wsh.example.com/. Ebből készülnek az e-mailekben lévő hivatkozások (jelszó-visszaállítás, leiratkozás, az értesítések lábléce, a háttérfolyamatok által küldött e-mailekben is), a későbbi e-mailekhez tárolt hivatkozások és a mobilos aktiválás QR-kódja. Ha üres, ezek minden kérés címéből készülnek, amelyet a kérés küldője választhat meg.
EmailSettings Az SMTP szerver, a port, a felhasználó, a jelszó és a feladó, ha az alkalmazás e-mailt küld.
UseDetailedExceptions A gyári fájlban true. Éles üzemben false, hogy az API-hibák ne tartalmazzanak belső részleteket.

Minden kulcshoz más, hosszú, véletlen értéket adjon (például openssl rand -base64 48), minden csomóponton ugyanazt. Az alkalmazás minden induláskor SECURITY: figyelmeztetést naplóz, amíg egy kulcs a gyári értéken van, vagy a PublicBaseUrl üres. A worksmarthub.env fájlban:

text
LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey=<hosszú véletlen érték>
TicketAttachment__DownloadLink__SymmetricSecurityKey=<egy másik hosszú véletlen érték>
ImageConfiguration__ImageLink__SymmetricSecurityKey=<egy harmadik hosszú véletlen érték>
PublicBaseUrl=https://wsh.example.com/
UseDetailedExceptions=false

Ha a csatolt fájl a ConnectionStrings helyett az újabb InternalDatabaseSettings szakaszt használja, az erősebb a ConnectionStrings szakasznál és a ConnectionStrings__* környezeti változóknál; ekkor InternalDatabaseSettings__* változókat használjon.

Naplózási szintek#

Csatorna appsettings.json kulcs Környezeti változó
Alapértelmezett (az alkalmazás) Serilog:MinimumLevel:Default Serilog__MinimumLevel__Default
Microsoft (ASP.NET Core, Entity Framework) Serilog:MinimumLevel:Override:Microsoft Serilog__MinimumLevel__Override__Microsoft
Rendszer Serilog:MinimumLevel:Override:System Serilog__MinimumLevel__Override__System
  • Érvényes értékek: Verbose, Debug, Information, Warning, Error, Fatal, kis- és nagybetű nem számít. Beállítás nélkül a szint Information; éles üzemben a Microsoft csatornára a Warning jó választás.
  • A fájl vagy a környezet változásai a következő induláskor érvényesek.
  • Az Admin felületen az App Konfiguráció > Log Szintek oldalon van a Szerver naplózási szintek felülírása kapcsoló. Kikapcsolva a fenti szerverbeállítás érvényes. Bekapcsolva az oldalon választott három szint érvényes minden csomóponton a ConfigSync időközön belül, újraindítás nélkül. Minden módosítás a rendszergazda nevével együtt naplózódik.
  • A kérésnaplók soha nem tartalmazzák a hitelesítő lekérdezési paraméterek értékét (access_token, hivatkozás-tokenek, OAuth code és state, és minden paraméter, amelynek nevében token, secret, auth, key, password vagy session szerepel); ezek helyén *** áll.
  • Éles üzemben soha ne hagyja bekapcsolva a Debug vagy Verbose szintet: sokkal több adatot írnak, akár személyes adatot is, és gyorsan megtöltik a lemezt.

Biztonsági beállítások#

  • Aláírókulcsok és PublicBaseUrl: lásd a fenti táblázatot.
  • Swagger: a Swagger:Enabled (a gyári fájlban true) a /swagger címen szolgálja ki az API-leírást és a tesztfelületet; az API végpontjai így is hitelesítést kérnek. false értéknél minden /swagger útvonal 404-et ad. Ahol senkinek nincs rá szüksége, állítsa be: Swagger__Enabled=false.
  • Biztonsági fejlécek: az Admin felületen, az App Konfiguráció > Biztonsági fejlécek oldalon állíthatók, és minden csomóponton érvényesek. Alapértelmezésben be van kapcsolva az X-Frame-Options, az X-Content-Type-Options: nosniff, a Referrer-Policy: no-referrer, a Permissions-Policy és egy Content-Security-Policy; a Strict-Transport-Security (HSTS) ki van kapcsolva. A HSTS-t akkor kapcsolja be, amikor az alkalmazás már csak HTTPS-en érhető el (alapértelmezett max-age 30 nap).
  • Bejelentkezési süti: a LoginSettings.CookieAuthenticationSettings.SecureCookie értéke true: a böngészők csak HTTPS-en küldik a sütit. Az alkalmazást HTTPS-en szolgálja ki (TLS a fordított proxyn, a terheléselosztón vagy az Ingress-en).
  • CORS: a gyári fájlban a HttpSettings.Cors.AllowOrigin értéke http://localhost:4200 (a Frontend fejlesztői szervere). A portál ugyanarról az originről jön, mint az API, ezért nincs szüksége CORS-ra; ne nyissa meg *-ra.
  • Az Admin felületen megadott titkos értékek csak írhatók: a felület és az API soha nem adja vissza őket, az üresen hagyott mező megtartja a tárolt értéket. Ha megváltoztatja, hova kerül egy titkos érték (SMTP szerver, egy File Storage végpontja, a Vault címe), ugyanabban a mentésben a titkos értéket is újra meg kell adni.
  • Munkamenetek: a bejelentkezési sütiket védő kulcsok az adatbázisban vannak. Az adatbázist és a mentéseit ennek megfelelően védje.

Fordított proxy és továbbított fejlécek#

A konténer a 8080-as porton sima HTTP-t beszél; a TLS egy fordított proxyn, terheléselosztón vagy a Kubernetes Ingress-en végződik. Az alkalmazás az eredeti kliens címét, sémáját és hostját az X-Forwarded-For, X-Forwarded-Proto és X-Forwarded-Host fejlécből veszi, és ezeket bármely forrástól elfogadja. Ezért:

  • a proxy állítsa be és írja felül ezeket a fejléceket (a kliens által küldött értékeket soha ne adja tovább), nginx-nél:
    nginx
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    client_max_body_size 50m;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
  • a konténer portját csak a proxy felé tegye elérhetővé (WSH_HTTP_PORT=127.0.0.1:8080, ha a proxy ugyanazon a gépen fut), hogy a proxyt megkerülve senki ne érje el az alkalmazást.

A melléklet- és képhivatkozások és az OAuth redirect_uri a kérésből készül (a továbbított hostból és sémából); az e-mailek hivatkozásai a PublicBaseUrl értékből. Az 50 MB-os feltöltési korlát és a 600 másodperces időkorlát a 25 MB-os feltöltési darabokhoz igazodik (TicketAttachment.UploadChunkSize, ImageConfiguration.ImageChunkSize).

HTTPS a konténerben (opcionális)#

Ha a TLS-nek magában a konténerben kell végződnie, adjon meg egy HTTPS figyelési címet, és a Kestrel szabványos változóival egy tanúsítványt. Az indítószkriptek csak a 8080-as portot teszik elérhetővé, ezért kézi docker run parancsot használjon (lásd Futtatás a szkriptek nélkül):

bash
docker run -d --name worksmarthub --restart unless-stopped --stop-timeout 60 \
  -p 8443:8443 \
  -e HttpSettings__Urls__0=http://+:8080 -e HttpSettings__Urls__1=https://+:8443 \
  -e ASPNETCORE_Kestrel__Certificates__Default__Path=/certs/wsh.pfx \
  --env-file /opt/worksmarthub/worksmarthub.env \
  --mount type=bind,source=/opt/worksmarthub/wsh.pfx,target=/certs/wsh.pfx,readonly \
  -v worksmarthub-data:/app/data worksmarthub:23

Az ASPNETCORE_Kestrel__Certificates__Default__Password=<pfx jelszó> a worksmarthub.env fájlba kerüljön, ne a parancssorba. A tanúsítványfájlt az uid 1001-nek olvasnia kell tudni.

Saját CA-tanúsítványok (kimenő TLS)#

Az alkalmazás TLS-sel kapcsolódik kifelé: STARTTLS-es SMTP, LDAPS, Microsoft Entra ID és az OAuth szolgáltatók, HashiCorp Vault, Számlázz.hu, Slack, Teams, a File Storage-ok objektumtárai, és a TLS-es külső adatbázis. Ha valamelyik belső vagy önaláírt CA tanúsítványát mutatja, a kapcsolat addig sikertelen, amíg a konténer nem bízik meg abban a CA-ban. Az alkalmazás az image operációs rendszerének tanúsítványtárát használja (/etc/ssl/certs/ca-certificates.crt). A CA kétféleképpen adható hozzá:

Származtatott image (az indítószkriptekkel működik). Tegye a CA-fájlt (PEM, .crt) egy Dockerfile mellé:

dockerfile
FROM worksmarthub:23
USER root
COPY internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt
RUN update-ca-certificates
USER appuser
bash
docker build -t worksmarthub:23-ca .
sh worksmarthub-run.sh --version 23-ca --detach

Minden új verzióhoz készítse el újra.

Csatolt tanúsítványcsomag (kézi docker run). Fűzze hozzá a CA-t az image csomagjához, és az eredményt csak olvashatóan csatolja a helyére:

bash
docker run --rm --entrypoint cat worksmarthub:23 /etc/ssl/certs/ca-certificates.crt > ca-bundle.crt
cat internal-ca.crt >> ca-bundle.crt
# a docker run parancshoz:
#   --mount type=bind,source=/opt/worksmarthub/ca-bundle.crt,target=/etc/ssl/certs/ca-certificates.crt,readonly

Minden frissítéskor az új image-ből készítse el újra a csomagot, hogy a frissített nyilvános CA-k is benne legyenek. Kubernetesen a chart elvégzi ezt az összefűzést (lásd 6. lépés). A CA-t a PKI csapattól kérje; hogy egy szerver milyen láncot küld, így látható: openssl s_client -connect smtp.example.com:587 -starttls smtp -showcerts </dev/null. Adatbázis-kapcsolatnál a kapcsolati karakterláncban az ellenőrzés lazítható is (PostgreSQL SSL Mode=Require, SQL Server TrustServerCertificate=true); a CA megbízhatóvá tétele a jobb megoldás.

Kimenő kapcsolatok#

Az alkalmazás kliens is. Hogy mihez kapcsolódik, a beállításokon múlik:

Cél Port Mikor
DNS 53 Mindig
Belső adatbázis 5432 PostgreSQL, 1433 SQL Server, 3306 MySQL SQLite-on kívül mindig
Redis vagy az adatbázis-cache 6379, illetve az adatbázis portja CacheSettings.Type Redis / SqlServer / Postgres / MySql
SMTP szerver 587 (STARTTLS), 25 EmailSettings és az e-mail értesítési csatornák. A 465-ös implicit TLS küldésre nem támogatott.
Slack (slack.com) 443 Slack értesítési csatornák
Microsoft Teams (Bot Framework, smba.trafficmanager.net, login.microsoftonline.com) 443 Teams értesítési csatornák
Számlázz.hu (www.szamlazz.hu) 443 Számlázás
File Storage hátterek: Amazon S3, Azure Blob, MinIO, Box, SharePoint, Google Cloud Storage 443 (MinIO: a saját portja) Az ezeken létrehozott File Storage-ok
HashiCorp Vault a címe (gyakran 8200) Vault szolgáltatás felhasználói katalógus
Microsoft Entra ID / Graph (login.microsoftonline.com, graph.microsoft.com) 443 UserStore: AzureAD, Microsoft OAuth
OAuth szolgáltatók (Okta, Google, egyedi) 443 AuthType: OAuth
LDAP / Active Directory tartományvezérlők 389, 636 UserStore: LDAP
AppleConnect a címei AuthType: AppleConnect

A UserStore: ActiveDirectory és az ActiveDirectory bejelentkezés tartományba léptetett Windows szervert igényel, és Linux-konténerben nem működik; ott LDAP (Active Directory változattal) vagy AzureAD használható.

Az alkalmazás futtatása#

Linux#

bash
cd docker/linux
sh worksmarthub-run.sh --version 23 --detach     # --detach nélkül előtérben fut, Ctrl+C állítja le

Windows#

powershell
cd docker\win
.\worksmarthub-run.ps1 -Version 23 -Detach

Nyissa meg a http://<gép>:8080/ címet, és hozza létre az első felhasználót. --version / -Version nélkül a szkriptek a worksmarthub:latest image-et futtatják; a --image <hivatkozás> / -Image bármely más image-et (pl. registryből).

Amit az indítószkript tesz:

  • ellenőrzi a Docker motort és az image-et, és nem indul el (78-as kilépési kód), ha azonos nevű konténer fut, vagy ha létezik egy leállított, /app/data kötet nélküli konténer (adatot tárolhat, lásd Adatok kimentése egy konténerből); a leállított, adatkötettel rendelkező konténer maradvány, és törli;
  • worksmarthub nevű konténert indít (gépenként egy példány);
  • a worksmarthub-data nevű kötetet a /app/data mappába csatolja (a Docker az első induláskor hozza létre, és belemásolja az image üres FileStorage és Logs mappáját);
  • a 8080-as portot teszi elérhetővé, és beállítja a HttpSettings__Urls__0=http://+:8080 értéket;
  • csatolja az appsettings.json-t és átadja a worksmarthub.env-et, ha ezek a szkript mellett vannak;
  • 60 másodpercet ad a leállásra (--stop-timeout 60): az alkalmazás 45 másodpercet hagy a háttérfolyamatainak, majd lezárja az adatbázist;
  • előtérben a konténer leálláskor törlődik (--rm), és a szkript kivárja; --detach / -Detach esetén unless-stopped újraindítási szabállyal fut: a Docker összeomlás után és a démon indulásakor újraindítja, hacsak Ön nem állította le.
Beállítás (környezeti változó) Alapérték Jelentés
WSH_IMAGE worksmarthub:latest Az image (a --version és az --image felülírja)
WSH_CONTAINER_NAME worksmarthub A konténer neve
WSH_DATA_VOLUME worksmarthub-data A nevesített kötet; Linuxon abszolút gépi mappa is lehet
WSH_HTTP_PORT 8080 A gépi port, vagy cím:port, pl. 127.0.0.1:8080, hogy csak a gép loopback címén figyeljen
WSH_DATA_MOUNT_OPTS (üres) Csak Linuxon: további csatolási opciók, pl. :Z SELinuxos gépen

A --preflight-only / -PreflightOnly csak az ellenőrzéseket futtatja, nem indít semmit. A konténer órája UTC, ezért a háttérfolyamatok időpontjai (Admin felület, App Konfiguráció > Háttérfolyamatok) UTC szerintiek.

Telepítés szolgáltatásként#

Linux (systemd szolgáltatás)#

A szkripteket olyan mappában tartsa, amelyet csak a root írhat, például /opt/worksmarthub (lásd A szkriptmappa védelme), az appsettings.json és a worksmarthub.env fájllal együtt:

bash
sudo sh worksmarthub-service-install.sh --version 23

A szkript ellenőrzi a mappa jogosultságait, leállítja a futó szolgáltatást, lefuttatja az indítás előtti ellenőrzéseket, megírja az /etc/systemd/system/worksmarthub.service fájlt, majd engedélyezi és elindítja. A telepítéskor beállított WSH_* értékek (sudo WSH_HTTP_PORT=8081 sh worksmarthub-service-install.sh ...) bekerülnek a unitba. A szolgáltatás:

  • előtérben futtatja a szkriptmappából a worksmarthub-run.sh szkriptet (a mappát hagyja a helyén), a Docker szolgáltatás után (docker.service, snap csomagnál snap.docker.dockerd.service);
  • kilépés után 10 másodperccel újraindítja, kivéve 78-as kilépési kódnál (sikertelen indítás előtti ellenőrzés, amelyen az újraindítás nem segít: RestartPreventExitStatus=78);
  • docker stop -t 60 paranccsal állítja le (TimeoutStopSec=90).
bash
systemctl status worksmarthub      # állapot
systemctl restart worksmarthub     # újraindítás (az appsettings.json és a worksmarthub.env változásait is érvényesíti)
systemctl stop worksmarthub        # leállítás
journalctl -u worksmarthub -f      # a szolgáltatás naplója (a konténer konzolkimenete)

A WSH_SERVICE_NAME a szolgáltatás nevét változtatja meg. Frissítéshez futtassa újra a telepítőszkriptet az új --version értékkel.

Windows (ütemezett feladat)#

Rendszergazdaként, a szkriptmappában:

powershell
.\worksmarthub-service-install.ps1 -Version 23

A szkript ellenőrzi a mappa jogosultságait, leállítja a meglévő feladatot és a konténerét, lefuttatja az indítás előtti ellenőrzéseket, bekéri a feladatot futtató fiókot (a jelszót a Feladatütemező kapja meg, máshol nem tárolódik), regisztrálja a WorkSmartHub feladatot, és elindítja. A feladat:

  • nem interaktívan, a legmagasabb jogosultsággal futtatja a worksmarthub-run.ps1 -Image <image> parancsot a gép indulásakor (legfeljebb egy perc véletlen késleltetéssel) és minden bejelentkezéskor, mert a Docker Desktop csak egy felhasználó bejelentkezése után fut;
  • bármeddig megvárja a Docker motort, és az indulási üzeneteit a szkript melletti worksmarthub-task.log fájlba írja;
  • hiba esetén a Feladatütemező legfeljebb tízszer, percenként újraindítja.

A Docker Desktopnak automatikusan kell indulnia: Settings > General > Start Docker Desktop when you sign in.

powershell
Get-ScheduledTask -TaskName WorkSmartHub | Get-ScheduledTaskInfo     # utolsó futás és eredménye
Stop-ScheduledTask -TaskName WorkSmartHub; docker stop worksmarthub  # leállítás
Start-ScheduledTask -TaskName WorkSmartHub                           # indítás
docker logs -f worksmarthub                                          # az alkalmazás naplója

Csak a Docker újraindítási szabálya. A --detach / -Detach elég, ha a Docker démon a gép indulásakor elindul. Ne kombinálja a szolgáltatással vagy az ütemezett feladattal.

A szolgáltatás eltávolítása#

bash
cd docker/linux
sudo sh worksmarthub-service-uninstall.sh
sudo sh worksmarthub-service-uninstall.sh --remove-image worksmarthub:23    # az image-et is törli
powershell
cd docker\win
.\worksmarthub-service-uninstall.ps1                           # rendszergazdaként
.\worksmarthub-service-uninstall.ps1 -RemoveImage worksmarthub:23

A szolgáltatás vagy a feladat és a konténer törlődik. Az adatkötet megmarad, és a következő telepítés újra használja. Az image-ek megmaradnak, hacsak meg nem nevez egyet, mert a helyben készült image-et nem lehet újra letölteni. Az adatokat csak akkor törölje a docker volume rm worksmarthub-data paranccsal, ha mindet el akarja távolítani.

Adatmegőrzés#

Mi marad meg#

Minden futás közbeni adat a worksmarthub-data kötetben van, amely a /app/data mappába csatolódik:

Tartalom A kötetben Megjegyzés
SQLite adatbázis (az alapértelmezett InternalDbType: 0, Data Source=database.db;) database.db, database.db-wal, database.db-shm A /app/database.db ide mutat. A -wal és -shm fájl az adatbázis része; mindig együtt másolja őket.
Fizikai File Storage (alapértelmezett gyökérútvonal: FileStorage) FileStorage/ A /app/FileStorage ide mutat. A Physical háttérrel létrehozott File Storage-ok (Admin felület, App Fájltárolók) munkalap-mellékletei és alkatrészképei, valamint a File Storage nélküli munkajegyek számla PDF-jei (az automatikus Számlák (automatikus) tároló).
Naplófájlok Logs/ A /app/Logs ide mutat. Napi fájlok, az Admin felületen is láthatók (Naplófájlok). A docker logs a konzolkimenetet mutatja.
Élő e-mail- és értesítéssablonok LiveEmailTemplates/, LiveNotificationTemplates/ Induláskor jönnek létre; a hiányzó alapsablonok bekerülnek, a szerkesztett fájlokat semmi nem írja felül.

A relatív útvonalak a köteten belülre mutatnak: Data Source=database.db, a FileStorage gyökérútvonal és a Logs/log-.txt. A fizikai File Storage gyökérútvonala maradjon relatív (FileStorage, vagy más útvonal a data/ alatt): a konténer más részére mutató abszolút útvonal nem marad meg. Külső adatbázissal és külső File Storage háttérrel a kötetben csak a naplók és a sablonok vannak.

Nincs a kötetben: az appsettings.json és a worksmarthub.env (a szkriptek mellett), valamint a licenc és a bejelentkezési sütik kulcsai (az adatbázisban). Maga a konténer eldobható: bármikor törölhető és újra létrehozható, és újraindítás, a gép újraindulása, összeomlás vagy frissítés soha nem visz el adatot.

Sablon szerkesztése. Másolja ki, szerkessze, másolja vissza. A következő e-mail már ezt használja, újraindítás nélkül:

bash
docker cp worksmarthub:/app/data/LiveEmailTemplates/ResetPassword.cshtml .
docker cp ResetPassword.cshtml worksmarthub:/app/data/LiveEmailTemplates/

A docker cp után a fájl a root tulajdonában marad; az alkalmazás csak olvassa. Az alapsablon visszaállításához törölje a fájlt a mappából, és indítsa újra az alkalmazást.

A szkriptmappa védelme#

A szolgáltatás minden induláskor rootként (Linux) vagy a legmagasabb jogosultsággal (Windows) futtatja az indítószkriptet, és a mappában van az appsettings.json és a worksmarthub.env a titkos értékeivel. Aki ezeket a fájlokat módosítani tudja, az irányítja az alkalmazást és a gépet, ezért a telepítőszkriptek nem telepítenek, ha más felhasználók írhatják a mappát:

  • Linux: a mappa, az indítószkript, az appsettings.json és a worksmarthub.env nem lehet a csoport vagy bárki által írható, és egyik szülőmappa sem lehet bárki által írható sticky bit nélkül. Root tulajdonú mappát használjon, például /opt/worksmarthub (sudo chown -R root:root /opt/worksmarthub && sudo chmod -R go-w /opt/worksmarthub); utána az appsettings.json-t adja az uid 1001 tulajdonába, ha az alkalmazásnak bele kell írnia az új kulcsokat. Soha ne telepítsen a /tmp mappából.
  • Windows: a mappát és a fájlokat csak a Rendszergazdák, a SYSTEM és a telepítő felhasználó írhatja. A közvetlenül a C:\ alatt létrehozott mappa örökli a Hitelesített felhasználók: Módosítás jogot, ezért elutasítja; előbb távolítsa el az öröklött jogokat: icacls "C:\WorkSmartHub" /inheritance:r /grant:r "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F".

Az uid 1001 egy Linuxos gépen rendes helyi fiók is lehet (getent passwd 1001); az a fiók ekkor olvashatja az alkalmazás tulajdonában lévő fájlokat, éppúgy, mint az alkalmazás.

Frissítés#

  1. Készítse el vagy töltse be az új image-et (worksmarthub:24), és készítsen mentést (lásd lent).
  2. Indítsa el az új image-et ugyanazon a köteten:
    • Linux szolgáltatás: sudo sh worksmarthub-service-install.sh --version 24;
    • Windows feladat: .\worksmarthub-service-install.ps1 -Version 24;
    • kézi indítás: docker stop worksmarthub, majd sh worksmarthub-run.sh --version 24 --detach.
  3. Az új verzió induláskor migrálja az adatbázist (a docker logs -f worksmarthub kimenetében Migrating database és Migration complete látható), és írható appsettings.json esetén beleírja az új beállításkulcsokat. A felhasználók bejelentkezve maradnak.

Korábbi verzióra visszatérni a frissítés előtt készült mentés visszaállításával lehet: az adatbázis visszafelé soha nem migrálódik. Az új verzió változásnaplójában nézze meg, kell-e valamilyen lépés. worksmarthub:latest esetén (--version nélkül) egy új build áthelyezi a címkét, és a szolgáltatás újraindítása az új image-et indítja.

Mentés és visszaállítás#

Előbb állítsa le az alkalmazást: a write-ahead-log módú SQLite adatbázis futás közbeni másolata következetlen lehet. A segédkonténer az alkalmazás image-ét használja, hálózat nélkül. Az archívum hitelesítő adatokat tartalmaz, ezért csak Ön olvashatja.

bash
# Linux: előbb leállítás (amelyik vonatkozik)
sudo systemctl stop worksmarthub      # szolgáltatás
docker stop worksmarthub              # kézi indítás
docker run --rm --network none -v worksmarthub-data:/app/data -v "$PWD":/backup --user "$(id -u):$(id -g)" \
  --entrypoint sh worksmarthub:23 -c 'umask 077; tar czf "/backup/worksmarthub-data-$(date +%F).tgz" -C /app/data .'
sudo systemctl start worksmarthub     # vagy futtassa újra az indítószkriptet
powershell
# Windows: előbb leállítás (amelyik vonatkozik), olyan mappában, amelyet csak a rendszergazdák olvashatnak
Stop-ScheduledTask -TaskName WorkSmartHub; docker stop worksmarthub     # feladat
docker stop worksmarthub                                                # kézi indítás
docker run --rm --network none -v worksmarthub-data:/app/data -v "${PWD}:/backup" `
  --entrypoint tar worksmarthub:23 czf "/backup/worksmarthub-data-$(Get-Date -Format yyyy-MM-dd).tgz" -C /app/data .
Start-ScheduledTask -TaskName WorkSmartHub                              # vagy futtassa újra az indítószkriptet

Visszaállítás (leállított alkalmazással; a teljes kötetet lecseréli; a parancs törlés előtt végigolvassa az archívumot). Windowson -v "${PWD}:/backup:ro" kell, a sortörésekhez pedig backtick:

bash
docker run --rm --network none -u 0 --cap-drop ALL --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER \
  -v worksmarthub-data:/app/data -v "$PWD":/backup:ro --entrypoint sh worksmarthub:23 \
  -c 'tar tzf /backup/worksmarthub-data-YYYY-MM-DD.tgz >/dev/null && find /app/data -mindepth 1 -delete && tar xzf /backup/worksmarthub-data-YYYY-MM-DD.tgz -C /app/data && chown -R 1001:1001 /app/data'

A segédkonténer csak azért fut rootként a konténeren belül, hogy olvassa az archívumot és az alkalmazás felhasználójának adja a fájlokat, hálózat nélkül és csak a szükséges három képességgel. Csak saját készítésű archívumot állítson vissza. Az appsettings.json és a worksmarthub.env fájlt külön mentse; külső adatbázist a saját eszközeivel mentsen.

A mentések hitelesítő adatokat tartalmaznak. Az adatbázis a File Storage-kulcsokat, az e-mail-, értesítési és Számlázz.hu hitelesítő adatokat és a bejelentkezési sütik kulcsait olyan formában tárolja, amelyet az alkalmazás más adat nélkül is használni tud; az appsettings.json az aláírókulcsokat tartalmazza. A mentéseket korlátozott jogosultsággal és titkosítva tárolja, az ideiglenes másolatokat törölje.

A kötet védelme#

  • A nevesített kötet túléli a docker stop, docker rm, docker rmi parancsot, az image frissítését és az eltávolítószkripteket.
  • Amíg a konténer le van állítva és törölve, a kötet használaton kívülinek számít: 23-asnál régebbi Docker Engine-en a docker volume prune és a docker system prune --volumes törli a használaton kívüli nevesített köteteket, 23-astól a docker volume prune -a is. A Docker Desktop Clean / Purge data és Reset to factory defaults művelete minden kötetet töröl. Ezek előtt készítsen mentést.
  • Az összes alkalmazásadat szándékos törlése: docker volume rm worksmarthub-data, leállított alkalmazással.

Alternatíva: gépen lévő mappa a nevesített kötet helyett (Linux)#

Ha az adatokat saját kezelésű mappában tartaná (külön lemezen, meglévő mentési feladat alatt), hozza létre helyi fájlrendszeren (ne NFS-en vagy SMB-n: az SQLite write-ahead logjának helyi zárolás és osztott memória kell) mindkét almappával, és adja az uid 1001 tulajdonába:

bash
sudo mkdir -p /srv/worksmarthub/FileStorage /srv/worksmarthub/Logs
sudo chown -R 1001:1001 /srv/worksmarthub
sudo chmod 700 /srv/worksmarthub
sudo WSH_DATA_VOLUME=/srv/worksmarthub sh worksmarthub-service-install.sh --version 23

Az abszolút WSH_DATA_VOLUME bind mountként csatolódik. Az indítószkript ellenőrzi, hogy a mappa és mindkét almappa létezik, és az uid 1001 a tulajdonos, különben nem indul el (az almappák nélkül a File Storage és a naplófájlok nem működnének). 700-as móddal az indításnak rootként kell futnia (a szolgáltatás így fut). SELinuxos gépen állítsa be a WSH_DATA_MOUNT_OPTS=:Z értéket is. Windowson nem ajánlott: az NTFS-ről csatolt mappa lassú, és az SQLite zárolása rajta megbízhatatlan.

Több csomópont és magas rendelkezésre állás#

Az adatkötet egy Docker gépen van. Több alkalmazáscsomópont (terheléselosztott gépek, Kubernetes replikák) akkor használhat közös adatbázist, ha mindez teljesül:

Rész Több csomóponthoz Több csomóponthoz nem
Adatbázis SQL Server, PostgreSQL, MySQL SQLite
Cache Redis vagy az adatbázis-cache (SqlServer, Postgres, MySql) InMemory (a jogosultságok, a licencállapot, a törzsadatlisták és az OAuth bejelentkezési állapot csomópontonként eltérne; az alkalmazás induláskor naplózza ezt a tanácsot)
File Storage S3, Azure Blob, MinIO, Box, SharePoint, Google Cloud Storage, vagy egy közös hálózati kötet Physical helyi lemezen
Beállítások minden csomóponton ugyanazok az appsettings.json értékek, az aláírókulcsok és a PublicBaseUrl is

Ekkor:

  • Az adatbázis-migrációk induláskor csomópontok közötti zárolás alatt futnak (PostgreSQL advisory lock, SQL Server application lock, MySQL named lock): egy csomópont migrál, a többi vár, majd nem talál teendőt, új adatbázison is.
  • A munkamenetek minden csomóponton érvényesek (a kulcsok az adatbázisban vannak).
  • Az ütemezett háttérfolyamatok minden alkalommal egyszer futnak az összes csomópont közül: futás előtt a csomópont lefoglalja az alkalmat az adatbázisban, így az e-mailek, a Teams- és Slack-üzenetek és a Számlázz.hu hívások nem ismétlődnek. A Run-once claim cleanup folyamat törli a régi foglalásokat (alapértelmezésben bekapcsolva, naponta 04:15-kor, 7 napot tart meg). Több csomóponton legfeljebb 1 napos időközöket használjon, és tartsa szinkronban az órákat.
  • Az Admin felületen tett beállításváltozások a ConfigSync időközön (10 másodperc) belül minden csomóponthoz eljutnak.
  • Az objektumtárak hitelesítő adatainak az olvasás és írás mellett listázási és törlési jog is kell, és minden telepítésnek saját bucket vagy előtag kell: az adatbázis másolata (visszaállított mentés, tesztkörnyezet) megtartja a File Storage definíciókat a hitelesítő adataikkal, ezért élesítése előtt irányítsa őket máshová.
  • Az élő sablonok csomópontonként külön vannak, hacsak az adatmappa nem közös; a szerkesztett sablont másolja minden csomópontra.

Adatok kimentése egy konténerből#

A kötet nélkül, kézzel indított konténer a konténeren belül tartja az adatbázist és a fájlokat, és a konténer törlése ezeket is törli. Az indítószkript nem indul el, amíg létezik egy leállított, /app/data kötet nélküli worksmarthub nevű konténer, és ilyet soha nem töröl. Előbb másolja az adatokat a kötetbe:

bash
docker stop worksmarthub                        # ha fut; egy --rm kapcsolóval indított konténert ez töröl, lásd lent
mkdir -m 700 wsh-migrate
docker cp worksmarthub:/app/data/. wsh-migrate/
docker run --rm --network none -u 0 --cap-drop ALL --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER \
  -v worksmarthub-data:/app/data -v "$PWD/wsh-migrate":/migrate:ro --entrypoint sh worksmarthub:23 \
  -c 'cp -a /migrate/. /app/data/ && mkdir -p /app/data/FileStorage /app/data/Logs && chown -R 1001:1001 /app/data'
  • Az image mindent a /app/data alatt tart, így a docker cp mindent kimásol. A régebbi, e mappa nélküli image-ek a fájlokat itt tartották: /app/database.db (a -wal fájllal), /app/FileStorage, /app/Logs, /app/wwwroot/LiveEmailTemplates, /app/wwwroot/LiveNotificationTemplates: ezeket másolja a wsh-migrate mappába (az adatbázisfájlokat docker cp -L paranccsal).
  • Egy --rm kapcsolóval indított, futó konténer leálláskor törlődik. Futás közben másoljon belőle, egy következetes pillanatkép után: docker commit worksmarthub wsh-rescue (rövid időre megállítja), docker create --name wsh-rescue-c wsh-rescue, és a docker cp parancsot a wsh-rescue-c konténerre futtassa.
  • Indítsa el az új telepítést, ellenőrizze az adatokat, majd törölje a wsh-migrate mappát (hitelesítő adatokat tartalmaz), a mentő konténert és image-et, végül a régi konténert (docker rm worksmarthub).

Ha inkább üres adatbázissal indulna, a régi konténert törölje maga.

Futtatás a szkriptek nélkül (kézi telepítés)#

Ha az Önöknél érvényes szabályok nem engedik a szkripteinket, sima Docker parancsokkal ugyanez elérhető. A lényeg: fix konténernév, az adatkötet, a gépről csatolt beállítások és egy újraindítási mechanizmus.

1. lépés: A gép előkészítése#

  1. Telepítse a Dockert (Linuxon Docker Engine, Windowson Docker Desktop), és készítse el vagy töltse be az image-et.
  2. Hozzon létre egy mappát a beállításoknak, amelyet csak a rendszergazdák írhatnak, például /opt/worksmarthub (root tulajdonú, 755-ös mód). Ebbe kerül az appsettings.json (opcionális; az uid 1001 tulajdonában, 600-as móddal, ha az alkalmazásnak bele kell írnia az új kulcsokat) és a worksmarthub.env (600-as mód).
  3. Hozza létre egyszer az adatkötetet: docker volume create worksmarthub-data.

2. lépés: A konténer indítása#

Linux:

bash
docker run -d --name worksmarthub --restart unless-stopped --stop-timeout 60 \
  -p 8080:8080 -e HttpSettings__Urls__0=http://+:8080 \
  --mount type=bind,source=/opt/worksmarthub/appsettings.json,target=/app/appsettings.json \
  --env-file /opt/worksmarthub/worksmarthub.env \
  -v worksmarthub-data:/app/data \
  worksmarthub:23

Windows (PowerShell):

powershell
docker run -d --name worksmarthub --restart unless-stopped --stop-timeout 60 `
  -p 8080:8080 -e HttpSettings__Urls__0=http://+:8080 `
  --mount "type=bind,source=C:\Users\<admin>\WorkSmartHub\appsettings.json,target=/app/appsettings.json" `
  --env-file "C:\Users\<admin>\WorkSmartHub\worksmarthub.env" `
  -v worksmarthub-data:/app/data `
  worksmarthub:23
Kapcsoló Szerepe
-d Háttérben fut.
--name worksmarthub Fix név: véletlenül nem indul második példány, és a lenti parancsok így érik el.
--restart unless-stopped A Docker összeomlás után és a démon indulásakor (a gép újraindulásakor) újraindítja, hacsak Ön nem állította le.
--stop-timeout 60 A docker stop legfeljebb 60 másodpercet vár: az alkalmazás 45 másodpercet hagy a háttérfolyamatainak, majd lezárja az adatbázist.
-p 8080:8080 A webes felület a gép 8080-as portján (az első szám; csak loopbackhez 127.0.0.1:8080:8080).
-e HttpSettings__Urls__0=http://+:8080 A figyelési cím a konténerben; a port a -p konténer felőli oldala.
--mount type=bind,...appsettings.json Opcionális: a saját beállításfájl a gépről. Nélküle a gyári fájl érvényes.
--env-file ... Opcionális: beállítások és titkos értékek környezeti változóként; felülírják a fájlt.
-v worksmarthub-data:/app/data A tartós adatkötet.

3. lépés: Indulás a gép indításakor#

Linux, A változat (a legegyszerűbb): a Docker újraindítási szabálya. A --restart unless-stopped kapcsolóval és induláskor engedélyezett Docker szolgáltatással (sudo systemctl enable docker) nincs más teendő.

Linux, B változat: systemd unit. Ne kombinálja a --restart unless-stopped kapcsolóval; ekkor a systemd kezeli az életciklust. Hozza létre az /etc/systemd/system/worksmarthub.service fájlt:

ini
[Unit]
Description=WorkSmartHub
After=docker.service
Requires=docker.service

[Service]
TimeoutStartSec=0
TimeoutStopSec=90
Restart=always
RestartSec=10
ExecStartPre=-/usr/bin/docker rm worksmarthub
ExecStart=/usr/bin/docker run --rm --name worksmarthub --stop-timeout 60 -p 8080:8080 -e HttpSettings__Urls__0=http://+:8080 --mount type=bind,source=/opt/worksmarthub/appsettings.json,target=/app/appsettings.json --env-file /opt/worksmarthub/worksmarthub.env -v worksmarthub-data:/app/data worksmarthub:23
ExecStop=/usr/bin/docker stop -t 60 worksmarthub

[Install]
WantedBy=multi-user.target

Az ExecStart előtérben futtatja a konténert (-d nélkül), hogy a systemd követni tudja; a --rm törli a leállt konténert, így a következő indításkor nincs névütközés, az ExecStartPre pedig eltakarítja a szabálytalan leállás utáni maradványt (ártalmatlanul hibát ad, és futó konténert soha nem állít le). A docker program valódi útvonalát használja (command -v docker); snap csomagnál az After= és a Requires= sorban snap.docker.dockerd.service álljon. Ezután:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now worksmarthub
journalctl -u worksmarthub -f

Windows, A változat (ajánlott): a Docker újraindítási szabálya. Kapcsolja be a Start Docker Desktop when you sign in beállítást; a démon indulásakor minden --restart unless-stopped kapcsolóval indított konténert újraindít. A Docker Desktop egy felhasználó bejelentkezése előtt nem fut.

Windows, B változat: ütemezett feladat, amely megvárja a motort, és elindítja a meglévő konténert (a Feladatütemező nem próbálja újra a hibával kilépő programot, a Docker Desktopnak pedig a bejelentkezés után egy-két perc kell):

powershell
$command = 'while ($true) { docker version *> $null; if ($LASTEXITCODE -eq 0) { break }; Start-Sleep -Seconds 15 }; docker start worksmarthub'
$action   = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -NonInteractive -Command `"$command`""
$triggers = @((New-ScheduledTaskTrigger -AtStartup), (New-ScheduledTaskTrigger -AtLogOn))
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Hours 1)
Register-ScheduledTask -TaskName "WorkSmartHub" -Action $action -Trigger $triggers -Settings $settings

A feladat a regisztráló felhasználóként fut, akinek a docker-users csoport tagjának kell lennie. A docker start nem csinál semmit, ha a konténer már fut.

4. lépés: Mindennapi parancsok#

Feladat Parancs
Naplók docker logs -f worksmarthub
Leállítás / indítás docker stop worksmarthub (legfeljebb 60 mp-et vár) / docker start worksmarthub
Az appsettings.json változásának érvényesítése docker restart worksmarthub
A worksmarthub.env változásának érvényesítése törlés és újraindítás (docker stop worksmarthub && docker rm worksmarthub, majd a 2. lépés): a környezeti változók a konténer létrehozásakor rögzülnek
Frissítés docker stop worksmarthub && docker rm worksmarthub, majd a 2. lépés az új image-dzsel. A kötet megmarad.
Mentés / visszaállítás Lásd Mentés és visszaállítás.
Eltávolítás docker stop worksmarthub && docker rm worksmarthub; ha az image-nek is mennie kell, docker rmi worksmarthub:23. A kötet megmarad.

Kubernetes#

A kubernetes-helm-chart mappában van a worksmarthub Helm chart (chartverzió 1.0.0). Minden beállítás leírása a kubernetes-helm-chart/values.yaml fájlban van.

Kubernetes előfeltételek#

  • Egy futó fürt (EKS, AKS, GKE, saját üzemeltetésű; helyi teszthez minikube) és hozzá beállított kubectl.
  • Helm 3.
  • Az alkalmazás image-e ott, ahonnan a csomópontok elérik: a csomópont Docker démonjában építve (minikube), a csomópontokra betöltve, vagy egy, a fürt által elérhető registrybe feltöltve.
  • Alapértelmezett StorageClass (vagy egy megnevezett) a PersistentVolumeClaim-ekhez.
  • ingress-nginx vezérlő a chart Ingress-éhez; más vezérlőnél vagy service mesh esetén kapcsolja ki az Ingress-t (8. lépés).
  • Kimenő hozzáférés a Docker Hubhoz a postgres:16-alpine, redis:7-alpine és busybox:1.38.0 image-hez, vagy ezek másolata a saját registryben (Elszigetelt és korlátozott hálózatok).

Gyors kezdés#

A chart alapértékeivel egyetlen fájl szerkesztése nélkül teljes telepítés indul:

bash
bash build/build-image.sh --version 23 --minikube      # vagy töltse fel az image-et egy, a fürt által elérhető registrybe
helm install worksmarthub ./kubernetes-helm-chart --set app.image.tag=23
kubectl get pods -n worksmarthub -w
kubectl port-forward -n worksmarthub svc/worksmarthub 8080:80      # majd http://localhost:8080/

A worksmarthub névtérbe telepít:

Összetevő Mi ez
Alkalmazás Egy worksmarthub:<címke> pod GET /health próbákkal, appsettings.json ConfigMapből, adatkötet a /app/data mappában
Adatkötet A worksmarthub-data-claim PersistentVolumeClaim (5 Gi, ReadWriteOnce, alapértelmezett StorageClass): fizikai File Storage, naplók, élő sablonok, és SQLite esetén az adatbázisfájl
PostgreSQL postgres:16-alpine, egy replika, postgres-data-claim PVC (5 Gi). A chart appsettings.json-ja ezt választja (InternalDbType: 2, Server=db)
Redis redis:7-alpine, egy replika, csak cache. A chart appsettings.json-ja ezt választja (CacheSettings.Type: Redis, cache:6379)
Ingress ingress-nginx vezérlőhöz, feltöltési korlátokkal (8. lépés)
NetworkPolicy-k A beépített PostgreSQL-hez és Redishez csak a névtér podjai kapcsolódhatnak

Változtassa meg az adatbázis jelszavát. A beépített PostgreSQL a nyilvános alapértelmezett user felhasználóval és password jelszóval indul. Bármilyen, nem eldobható próbatelepítés előtt adjon meg sajátot az internalDatabase.settings alatt, és ugyanezt a kubernetes-helm-chart/appsettings.json kapcsolati karakterláncában (vagy egy Secretben), lásd Adatbázisjelszó. Később megváltoztatni csak az adatbázison belüli lépéssel lehet.

Ez a beállítás első telepítéshez és kipróbáláshoz való. Élesítés előtt állítsa be az aláírókulcsokat és a PublicBaseUrl értéket is (7. lépés), és menjen végig az Élesítési ellenőrzőlistán.

A módosításait saját values fájlban tartsa (-f sajat-values.yaml), és ezt őrizze meg a frissítésekhez; a lenti lépések a kulcsokat mutatják.

Hálózati és kapcsolódási követelmények#

A bejövő forgalmat az Ingress (vagy a Service) kezeli: amint 80/443-on elérhetővé teszi az alkalmazást, a felhasználók elérik. A kimenő kapcsolatokat az alkalmazás kezdeményezi; mindegyikhez két dolog kell: hova kapcsolódjon (alkalmazásbeállítás: appsettings.json, Secretek vagy az Admin felület) és elérheti-e a pod (platform beállítás, csak akkor kell, ha a kimenő forgalom korlátozott, vagy a cél olyan hálózaton van, amelyet a fürt nem ér el, például egy helyi SMTP relay vagy LDAP szerver).

Bejövő:

Port Forrás Szerepe
80 / 443 A felhasználók böngészői, API kliensek, a terheléselosztó A portál és a REST API, ugyanabból a konténerből és portról

A TLS az Ingress-en vagy a terheléselosztón végződik; a konténer a 8080-as porton figyel (HttpSettings.Urls), a Service a 80-ason.

Kimenő: a Kimenő kapcsolatok táblázata érvényes, és image letöltéskor a konténer-registry (443). A fürtön belüli szolgáltatásokat (a beépített adatbázist és cache-t) Service DNS-en éri el (db:5432, cache:6379), ez a forgalom nem hagyja el a fürtöt. A pod külső célok felé irányuló forgalma a csomópont címére fordítódik (source NAT), így a külső tűzfalak a csomópont IP-jét látják: a csomópontoknak (vagy egy külön csomópontkészletnek, 9. lépés) engedélyezze az egyes célokat.

A kimenő forgalom korlátozása (opcionális). NetworkPolicy-képes CNI-vel (Calico, Cilium) a névtérre alapértelmezett tiltó kimenő szabály tehető, az alkalmazás podjaira pedig engedélyező lista. Az engedélyező listának mindent tartalmaznia kell, amit az alkalmazás használ, különben leáll a működése:

yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-egress
  namespace: worksmarthub
spec:
  podSelector: {}
  policyTypes: [Egress]
  egress: []
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: worksmarthub-app-egress
  namespace: worksmarthub
spec:
  podSelector:
    matchLabels:
      app: worksmarthub-pod
  policyTypes: [Egress]
  egress:
  - ports:                                   # DNS
    - { protocol: UDP, port: 53 }
    - { protocol: TCP, port: 53 }
  - to:                                      # beépített PostgreSQL
    - podSelector: { matchLabels: { app: db, wsh-internal-service: db } }
    ports:
    - { protocol: TCP, port: 5432 }
  - to:                                      # beépített Redis
    - podSelector: { matchLabels: { app: cache, wsh-internal-service: cache } }
    ports:
    - { protocol: TCP, port: 6379 }
  - ports:                                   # Számlázz.hu, Slack, Teams, Entra ID, OAuth, objektumtárak
    - { protocol: TCP, port: 443 }
  - ports:                                   # SMTP (STARTTLS)
    - { protocol: TCP, port: 587 }
  # Vegye fel, amire a beállításainak szüksége van: külső adatbázis (1433/3306/5432) vagy cache (6379) ipBlock-ként,
  # LDAP (389/636), HashiCorp Vault (8200), SMTP a 25-ös porton, egy MinIO port.

Az alapértelmezett tiltó szabály a beépített PostgreSQL és Redis podjaira is vonatkozik, amelyeknek nincs szükségük kimenő forgalomra. A NetworkPolicy névtérre szól; ha a fürt minden más alkalmazását távol kell tartani egy céltól, a tűzfalszabályt egy külön csomópontkészletre szűkítse.

1. lépés: Névtér#

yaml
nameSpace: "worksmarthub"
installNameSpace: True

installNameSpace: True esetén a chart hozza létre a névteret, és a helm uninstall mindennel együtt törli. Ha a névtér (és a benne létrehozott Secretek) a release-től függetlenül kell maradjon, hozza létre maga, és állítsa be az installNameSpace: False értéket:

bash
kubectl create namespace worksmarthub
helm install worksmarthub ./kubernetes-helm-chart --set app.image.tag=23 --set installNameSpace=False

Az útmutató parancsai a worksmarthub névteret használják; ha megváltoztatja, helyettesítse a sajátjával.

2. lépés: Az alkalmazás image-e#

yaml
app:
  image:
    repository: "worksmarthub"
    tag: "23"               # kötelező
  imagePullSecrets: []
global:
  imagePullPolicy: "IfNotPresent"
  • Az app.image.tag kötelező; nélküle a chart nem renderel. Egy sha256:... alakú címke digestként szerepel (repository@sha256:...).
  • Az imagePullPolicy: IfNotPresent (a chart minden konténerére) a csomóponton már meglévő image-et használja. A helyben készült image-nek erre szüksége van: Always esetén a kubelet registryt kérdez, és a pod ErrImagePull hibával leáll. A másik oldala: egy csomópont a már meglévő címkét soha nem tölti le újra, ezért minden buildnek új címke kell (a build szkript a verziót adja címkének), és a frissítés az új címkét állítja be. A latest címkét ne telepítse.
  • Az image eljuttatása a csomópontokra: minikube-on annak démonjában építse (build-image.sh --minikube); más fürtön registry nélkül töltse be a tar fájlt minden csomópontra a csomópont konténer-futtatójával; registryvel töltse fel az image-et, és állítsa be az app.image.repository értéket (pl. registry.example.com/worksmarthub).
  • Privát registry: hozzon létre egy pull secretet, és hivatkozzon rá:
    bash
    read -rs REGISTRY_PASSWORD      # gépelje be; nem jelenik meg és nem tárolódik
    kubectl create secret docker-registry regcred -n worksmarthub --docker-server=registry.example.com \
      --docker-username=<felhasználó> --docker-password="$REGISTRY_PASSWORD"
    yaml
    app:
      imagePullSecrets:
      - name: regcred

3. lépés: Belső adatbázis#

A beépített PostgreSQL (alapértelmezés)#

postgres:16-alpine, egy replika, a postgres-data-claim PVC-n (internalDatabase.persistence: 5 Gi, ReadWriteOnce, alapértelmezett StorageClass), a nem root 70-es felhasználóként, fsGroup: 70 beállítással. A Service-e db:5432, és a chart appsettings.json-ja az internalDatabase.settings értékeivel kapcsolódik hozzá. Újraütemezés után is megmarad, de egyetlen példány átállás (failover) nélkül, és a podja minden újraindításakor rövid ideig nem érhető el (Recreate stratégia).

  • internalDatabase.persistence.storageClass: tartós blokktároló osztály (gp3, managed-csi, premium-rwo); existingClaim saját kezelésű PVC-hez; enabled: false emptyDir-hez (az adat a poddal elvész; csak eldobható tesztekhez).
  • Az internalDatabase.fixDataPermissions: True egy egyszeri, rootként futó init konténert ad hozzá, amely chown-nal rendbe teszi az adatmappát. Csak olyan tárolóhoz, amely figyelmen kívül hagyja az fsGroup-ot, és a kötetet root tulajdonban, szigorú jogokkal hozza létre; szabályozott fürtön hagyja kikapcsolva.
  • internalDatabase.image: másolat a saját registryben vagy újabb címke. A konténerek uid 70-ként futnak, ez az Alpine változat postgres felhasználója; Debian alapú image-hez (uid 999) a runAsUser értéket a templates/internaldb.yaml fájlban és a wait-for-db init konténerben is módosítani kell. Egy meglévő adatbázis főverziójának cseréje nem helyben végezhető: a PostgreSQL nem indul el más főverzió adatmappáján, ezért mentés és visszatöltés kell.

Adatbázisjelszó#

A PostgreSQL az első indulásakor (üres adatmappánál) az internalDatabase.settings értékeiből hozza létre a felhasználót, a jelszót és az adatbázist (user / password / worksmarthub), és a chart appsettings.json-ja ugyanezekkel kapcsolódik:

json
"InternalDbType": 2,
"InternalDb": "Server=db;Port=5432;Database=worksmarthub;User id=user;Password=password;",

Ezek az alapértékek nyilvánosak. Az első telepítés előtt mindkét helyen adjon meg sajátot:

yaml
internalDatabase:
  settings:
    userName: wsh
    password: <erős jelszó>
    dbName: worksmarthub

és a kubernetes-helm-chart/appsettings.json fájlban "InternalDb": "Server=db;Port=5432;Database=worksmarthub;User id=wsh;Password=<ugyanaz a jelszó>;", vagy inkább egy Secret a ConnectionStrings__InternalDb kulccsal (7. lépés); a values.yaml és a ConfigMap egyszerű szövegként tárolja az értékeket.

Az internalDatabase.settings későbbi módosítása a meglévő adatbázist nem változtatja meg. Egy telepítés jelszavának cseréjéhez előbb az adatbázisban változtassa meg, utána a values fájlban és a kapcsolati karakterláncban, majd helm upgrade:

bash
kubectl exec -n worksmarthub deploy/db-deployment -- psql -U user -d worksmarthub -c "ALTER USER \"user\" PASSWORD '<új jelszó>';"

Az alkalmazás podja a wait-for-db init konténerben várja meg a PostgreSQL-t. Ez a values.yaml adataival jelentkezik be, és a naplójába írja, ha a PostgreSQL elutasítja őket (kubectl logs -n worksmarthub <app pod> -c wait-for-db); az alkalmazás ekkor is elindul, az appsettings.json vagy egy Secret kapcsolati karakterláncával.

Külső adatbázis (élesre ajánlott)#

Állítsa be az internalDatabase.skipDeployment: True értéket, és a kapcsolatot egy Secretben vagy a chart appsettings.json fájljában adja meg. Felügyelt szolgáltatás (Amazon RDS, Azure Database, Google Cloud SQL) vagy saját szerver:

Adatbázis InternalDbType InternalDb példa
SQL Server 1 Data Source=sql.example.com;Initial Catalog=wsh;User id=wsh;Password=...;Connection Timeout=60;Encrypt=True;TrustServerCertificate=False;
PostgreSQL 2 Server=pg.example.com;Port=5432;Database=wsh;User id=wsh;Password=...;SSL Mode=Require;
MySQL 3 Server=mysql.example.com;Port=3306;Database=wsh;Uid=wsh;Pwd=...;SslMode=Required; (és MySqlServerVersion, pl. 8.0.28)
  • A Schema SQL Serveren és PostgreSQL-en egy sémába teszi a táblákat; MySQL-nél (és SQLite-nál) üres kell legyen.
  • Az alkalmazás adatbázis-felhasználójának táblák létrehozására és módosítására is jogot kell adni: a migrációk minden induláskor futnak.
  • Adatbázismotorok közötti átállás nincs beépítve; egy meglévő telepítés megtartja a motorját.

SQLite, egy replika#

PostgreSQL és Redis nélküli kis telepítésnél az SQLite az adatkötetre kerül (ugyanaz, mint a test-local/values-sqlite.yaml):

yaml
app:
  replicationFactor: 1
  env:
  - name: ConnectionStrings__InternalDbType
    value: "0"
  - name: ConnectionStrings__InternalDb
    value: "Data Source=database.db;"
  - name: CacheSettings__Type
    value: "InMemory"
  dataVolume:
    persistence:
      enabled: true
internalDatabase:
  skipDeployment: True
cacheSystem:
  skipDeployment: True

A chart elutasítja az SQLite-ot egynél több replikával, és adatkötet nélkül is (kivéve app.allowNonPersistentSqlite: true esetén, eldobható tesztekhez). Blokktárolós StorageClass-t használjon, ne NFS-t.

4. lépés: Cache#

A chart redis:7-alpine cache-t telepít (csak cache: nincs perzisztencia és jelszó; a NetworkPolicy-ja csak a névtér podjait engedi), és a chart appsettings.json-ja ezt választja:

json
"CacheSettings": {
  "Type": "Redis",
  "RedisCacheSettings": { "Configuration": "cache:6379", "InstanceName": "worksmarthub" }
}
  • Egynél több replikához közös cache kell: Redis vagy adatbázis-cache. A chart elutasítja az InMemory értéket egynél több replikával. A memóriabeli cache podonként külön van, így a jogosultságok, a licencállapot, a törzsadatlisták és az OAuth bejelentkezési állapot podonként eltérne; az alkalmazás figyelmeztetést naplóz, ha Kubernetesen InMemory cache-sel fut.
  • Külső Redis (Amazon ElastiCache, Azure Cache for Redis): cacheSystem.skipDeployment: True, és egy Secretben CacheSettings__RedisCacheSettings__Configuration=redis.example.com:6380,password=...,ssl=true.
  • Adatbázis-cache: CacheSettings__Type SqlServer, Postgres vagy MySql, a hozzá tartozó ...CacheSettings__ConnectionString, séma és táblanév értékkel (lásd appsettings.json).
  • Egy replika Redis nélkül: cacheSystem.skipDeployment: True és CacheSettings__Type=InMemory.

Az alkalmazás podja a wait-for-cache init konténerben legfeljebb 5 percig várja a beépített Redist, így egy később induló cache pod nem indítja újra az alkalmazást; 5 perc után az alkalmazás mindenképp elindul.

Konténer-image-ek és biztonsági szabályok#

A chart kétféle image-et használ:

  • Az alkalmazás image-ét, amelyet Ön készít a forrásból, támogatott Microsoft alap-image-re (ASP.NET Core 10.0 Ubuntu 24.04 LTS-en), az aktuális operációsrendszer-biztonsági frissítésekkel (változatlan verzió újraépítésekor --no-cache).
  • Infrastruktúra image-eket: postgres:16-alpine (internalDatabase.image), redis:7-alpine (cacheSystem.image), busybox:1.38.0 (busyboxImage, a wait-for-cache és a fix-db-permissions init konténer). Ezek upstream image-ek, nem a termék részei; frissen tartásuk üzemeltetői feladat. Irányítsa őket a saját registryjére, vagy egy olyan újabb címkére, amely átmegy a szkennerén; a hivatkozás megváltoztatása IfNotPresent mellett is új letöltést jelent.

Egy szkenner-találatnál nézze meg, melyik image-hez tartozik: infrastruktúra image-nél egy újabb upstream címke termékkiadás nélkül megoldja; az alkalmazás image-énél újraépítés (OS csomagok) vagy új verzió (alkalmazáscsomagok).

5. lépés: Alkalmazásbeállítások#

A kubernetes-helm-chart/appsettings.json a gyári fájl, a charthoz szükséges négy módosítással: a beépített PostgreSQL (ConnectionStrings), a beépített Redis (CacheSettings) és a http://+:8080 figyelési cím. A chart a worksmarthub-config ConfigMapbe teszi, és csak olvashatóan csatolja a /app/appsettings.json helyére; a módosítása a következő helm upgrade során újraindítja az alkalmazás podját (checksum annotáció). Mivel a fájl csak olvasható, egy újabb verzió új beállításkulcsai az alapértékükkel, memóriában működnek, és a naplóban appsettings.json is read-only áll.

Az app.env egyszerű környezeti változókat állít be, amelyek felülírják a fájlt. Az értékek szövegek. Titkos értéket soha ne tegyen ide (a Deploymentben egyszerű szövegként látszik); arra a Secretek valók.

yaml
app:
  env:
  - name: PublicBaseUrl
    value: "https://wsh.example.com/"
  - name: Serilog__MinimumLevel__Override__Microsoft
    value: "Warning"
  - name: Swagger__Enabled
    value: "false"
  - name: UseDetailedExceptions
    value: "false"

Amit még érdemes átnézni: UserSettings és LoginSettings (Kubernetesen Local, LDAP vagy AzureAD; az ActiveDirectory Windows gépet igényel), EmailSettings, a naplózási szintek (lásd Naplózási szintek) és a biztonsági beállítások (lásd Biztonsági beállítások). Az aláírókulcsok Secretbe valók.

Adatkötet és File Storage#

Az app.dataVolume.persistence (alapértelmezésben bekapcsolva) a worksmarthub-data-claim PVC-t csatolja a /app/data mappába, a Docker kötettel azonos szerkezettel (Mi marad meg):

yaml
app:
  dataVolume:
    persistence:
      enabled: true
      size: 5Gi
      storageClass: ""          # "" = alapértelmezett; tartós, titkosított osztály
      accessMode: ReadWriteOnce
      existingClaim: ""
  • Egy init konténer (prepare-data, az alkalmazás image-e, uid 1001) új köteten létrehozza a FileStorage és a Logs mappát; a pod fsGroup: 1001 beállítása írási jogot ad az alkalmazásnak.
  • ReadWriteOnce kötettel a Deployment Recreate stratégiára vált: a régi pod leáll, mielőtt az új elindul, ezért a frissítés rövid kieséssel jár.
  • Kötet nélkül (enabled: false) a naplók, az élő sablonok és a fizikai File Storage minden poddal elvesznek.
  • helm uninstall esetén a PVC a StorageClass visszanyerési szabályát követi; a megtartásához Retain vagy existingClaim kell.

A File Storage-ok az Admin felületen jönnek létre (App Fájltárolók, és munkaterületenként), nem az appsettings.json fájlban. A Physical háttér az adatkötetre ír (gyökérútvonal FileStorage), és egy replikához való. Több replikához külső háttér kell (S3, Azure Blob, MinIO, Box, SharePoint, Google Cloud Storage), vagy ReadWriteMany adatkötet. Az objektumtárak hitelesítő adatainak listázási és törlési jog is kell, és minden telepítésnek saját bucket vagy előtag.

Élő sablon szerkesztése:

bash
POD=$(kubectl get pod -n worksmarthub -l app=worksmarthub-pod -o jsonpath='{.items[0].metadata.name}')
kubectl cp -n worksmarthub -c worksmarthub-container $POD:/app/data/LiveEmailTemplates/ResetPassword.cshtml ./ResetPassword.cshtml
# a fájl szerkesztése, majd:
kubectl cp -n worksmarthub -c worksmarthub-container ./ResetPassword.cshtml $POD:/app/data/LiveEmailTemplates/ResetPassword.cshtml

A következő e-mail már ezt használja. Az alapsablon visszaállításához törölje a fájlt (kubectl exec ... -- rm <fájl>) és a podot.

6. lépés: Saját CA-tanúsítványok#

Belső vagy önaláírt CA-t használó végpontok felé irányuló kimenő TLS-hez (lásd Saját CA-tanúsítványok) a chart az alkalmazáskonténer tanúsítványtárába fűzi a saját CA-tanúsítványait:

bash
kubectl create configmap wsh-ca-certs -n worksmarthub --from-file=internal-ca.crt=/path/to/internal-ca.crt
yaml
customCaCerts:
  enabled: true
  configMapName: wsh-ca-certs     # vagy secretName: wsh-ca-certs

A merge-ca-certs init konténer (az alkalmazás image-e, uid 65534) a rendszer tanúsítványcsomagját és a ConfigMap vagy Secret minden *.crt fájlját (PEM) egy emptyDir-be fűzi össze, amely csak olvashatóan a /etc/ssl/certs/ca-certificates.crt helyére csatolódik. Alkalmazásbeállítás nem kell; a következő pod-indításkor érvényes (a ConfigMap módosítása után kubectl rollout restart -n worksmarthub deploy/worksmarthub-deployment). Ez csak a kimenő megbízhatóságra vonatkozik; a bejövő TLS az Ingress-en végződik.

7. lépés: Hitelesítő adatok biztonságos kezelése#

Jelszót és kulcsot ne tartson az appsettings.json vagy a values.yaml fájlban: ezek titkosítatlanul egy ConfigMapbe és a Helm release-be kerülnek. Tegye őket Kubernetes Secretekbe; a chart környezeti változóként adja át őket, és ezek felülírják az appsettings.json értékeit. A chart soha nem hoz létre Secretet, csak hivatkozik rá.

1. módszer: egy Secret összes kulcsa (secrets.envFromSecret). Minden kulcs egy környezeti változó neve:

bash
kubectl create namespace worksmarthub        # egyszer, ha nem a chart hozza létre (installNameSpace: False)
kubectl create secret generic wsh-secrets -n worksmarthub \
  --from-literal=ConnectionStrings__InternalDb='Server=pg.example.com;Port=5432;Database=wsh;User id=wsh;Password=<jelszó>;SSL Mode=Require;' \
  --from-literal=LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey="$(openssl rand -base64 48)" \
  --from-literal=TicketAttachment__DownloadLink__SymmetricSecurityKey="$(openssl rand -base64 48)" \
  --from-literal=ImageConfiguration__ImageLink__SymmetricSecurityKey="$(openssl rand -base64 48)" \
  --from-literal=EmailSettings__SmtpPassword='<smtp jelszó>'
yaml
secrets:
  envFromSecret: "wsh-secrets"

Az érvénytelen környezetiváltozó-nevű kulcsok szó nélkül kimaradnak. envFromSecret mellett a chart nem látja, melyik adatbázist és cache-t választja a Secret, ezért az SQLite és InMemory replika-ellenőrzései kimaradnak.

2. módszer: egyes kulcsok (secrets.env), más kulcsnevű Secretekhez:

yaml
secrets:
  env:
  - name: ConnectionStrings__InternalDb
    secretName: wsh-db
    key: connection-string
  - name: LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey
    secretName: wsh-keys
    key: jwt
appsettings.json útvonal Környezeti változó
ConnectionStrings.InternalDb ConnectionStrings__InternalDb
CacheSettings.RedisCacheSettings.Configuration CacheSettings__RedisCacheSettings__Configuration
LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey
TicketAttachment.DownloadLink.SymmetricSecurityKey TicketAttachment__DownloadLink__SymmetricSecurityKey
ImageConfiguration.ImageLink.SymmetricSecurityKey ImageConfiguration__ImageLink__SymmetricSecurityKey
EmailSettings.SmtpPassword EmailSettings__SmtpPassword
UserSettings.LdapSettings.Password UserSettings__LdapSettings__Password
UserSettings.AzureADSettings.ClientSecret UserSettings__AzureADSettings__ClientSecret
LoginSettings.OAuthSettings.Okta.AppSecret (és Google, Microsoft, Custom) LoginSettings__OAuthSettings__Okta__AppSecret

A titkos értékeket a parancssorba gépelje, vagy a titokkezelője hozza létre a Secretet; ne tartsa őket fájlban. Az External Secrets Operator HashiCorp Vaultból, AWS Secrets Managerből vagy Azure Key Vaultból szinkronizál egy Secretet; az így létrejövő Secretre ugyanígy kell hivatkozni:

yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: wsh-secrets
  namespace: worksmarthub
spec:
  refreshInterval: 1h
  secretStoreRef: { name: vault-backend, kind: ClusterSecretStore }
  target: { name: wsh-secrets }
  data:
  - secretKey: ConnectionStrings__InternalDb
    remoteRef: { key: secret/data/wsh/database, property: connection-string }
  - secretKey: LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey
    remoteRef: { key: secret/data/wsh/keys, property: jwt }

A környezeti változókat a konténer induláskor olvassa; egy Secret módosítása után indítsa újra a podokat: kubectl rollout restart -n worksmarthub deploy/worksmarthub-deployment.

A beépített PostgreSQL internalDatabase.settings.password értéke a values.yaml fájlban marad (a PostgreSQL közvetlenül olvassa); élesre inkább olyan külső adatbázist használjon, amelynek kapcsolati karakterlánca csak Secretben van. A nem titkos beállítások (InternalDbType, Schema, CacheSettings.Type, UserSettings, naplózási szintek) maradjanak az appsettings.json fájlban vagy az app.env alatt. Az adatbázis-kapcsolatokra kényszerítse a TLS-t: PostgreSQL SSL Mode=Require (vagy VerifyFull), SQL Server Encrypt=True;TrustServerCertificate=False, MySQL SslMode=Required.

8. lépés: Service típusa és Ingress#

A Service típusa (app.serviceType) határozza meg, hogyan érhető el az alkalmazás a fürtön kívülről; a Service az advanced.app.servicePort (80) porton figyel, és a 8080-as konténerportra továbbít.

Típus Honnan érhető el Mikor
ClusterIP (alapérték) A fürtön belülről Ingress vagy service mesh mögött; teszthez kubectl port-forward
NodePort <csomópont IP>:<30000-32767> Gyors elérés ingress vezérlő nélkül; fürtszabályok gyakran tiltják
LoadBalancer A platform által adott IP Közvetlen elérés felhőben; belsőként az app.serviceAnnotations értékkel (networking.gke.io/load-balancer-type: "Internal", service.beta.kubernetes.io/aws-load-balancer-scheme: "internal", service.beta.kubernetes.io/azure-load-balancer-internal: "true")

Egy belépési pontot válasszon: az Ingress-t ClusterIP-vel, vagy egy LoadBalancer-t.

Ingress (alapértelmezésben advanced.ingress.enabled: true, advanced.ingress.className: nginx). Az app.hostName a host szabályt adja (üresen: minden host). TLS:

yaml
app:
  hostName: "wsh.example.com"
advanced:
  ingress:
    annotations:
      cert-manager.io/cluster-issuer: "your-issuer"
    tls:
    - hosts:
      - wsh.example.com
      secretName: wsh-tls

Feltöltési korlátok és időkorlátok. Az ingress-nginx alapértelmezésben 1 MB-os kéréstörzset fogad el, és 60 másodperc után lezárja a továbbított kérést, a munkalap-mellékletek és alkatrészképek viszont 25 MB-os darabokban töltődnek fel. A chart beállítja:

yaml
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "600"

A saját advanced.ingress.annotations értékei ezek fölé kerülnek: azonos kulcsnál az Ön értéke érvényes, a többi annotációja megmarad. Az Ingress annotációja erősebb a vezérlő ConfigMapjénél, ezért az ott megemelt korlátot itt is be kell állítani. Ha a darabméretet megemeli (TicketAttachment.UploadChunkSize, ImageConfiguration.ImageChunkSize), a proxy-body-size maradjon fölöttük. Más ingress vezérlők figyelmen kívül hagyják ezeket az annotációkat; nekik adja meg ugyanezeket a korlátokat, és minden, a fürt előtt álló terheléselosztónak vagy WAF-nak is.

Az Ingress kikapcsolása (advanced.ingress.enabled: false) service mesh vagy saját útválasztás esetén: a worksmarthub Service 80-as portjára irányítson, és állítsa be a továbbított fejléceket a Fordított proxy és továbbított fejlécek szerint.

9. lépés: Replikák és skálázás#

yaml
app:
  replicationFactor: 1
  resources:
    requests: { memory: 512M, cpu: 250m }
    limits: { memory: 2000M, cpu: 2000m }

Egy replika (az alapérték) minden beállítással működik. Egynél több replikához mindegyik kell:

  • közös adatbázis: a beépített PostgreSQL vagy külső (az SQLite csak egy replikát támogat);
  • közös cache: Redis (az alapérték) vagy adatbázis-cache;
  • minden pod által csatolható adatkötet: accessMode: ReadWriteMany RWX StorageClass-szal (NFS, EFS, Azure Files, Filestore), vagy adatkötet nélkül (enabled: false; a naplók és az élő sablonok ekkor podonként külön vannak);
  • külső File Storage háttér a mellékletekhez és képekhez.

A chart nem renderel (a helm install és a helm upgrade üzenettel leáll), ha egynél több replika mellett ReadWriteOnce adatkötet, SQLite vagy memóriabeli cache van beállítva; a helm lint ezt INFO sorként mutatja. A több replika viselkedése (zárolt migrációk, munkamenetek, alkalmanként egyszer futó háttérfolyamatok) a Több csomópont és magas rendelkezésre állás részben olvasható. A replikákat egy preferált pod anti-affinity szórja szét a csomópontokon.

Elhelyezés csomópontokon: az advanced.nodeConfiguration.appNodesConfiguration, dbNodesConfiguration és cacheNodesConfiguration a megfelelő podokra nodeSelector, affinity és tolerations értéket vesz át. Egy külön csomópontkészlet az alkalmazásnak lehetővé teszi, hogy egy tűzfalszabály csak azokról a csomópontokról engedje a kimenő kapcsolatait:

yaml
advanced:
  nodeConfiguration:
    appNodesConfiguration:
      nodeSelector:
        role: wsh
      tolerations:
      - { key: role, operator: Equal, value: wsh, effect: NoSchedule }

Az itt megadott affinity a chart anti-affinity beállítását helyettesíti.

10. lépés: Telepítés#

Ebből a repositoryból:

bash
helm install worksmarthub ./kubernetes-helm-chart -f sajat-values.yaml --set app.image.tag=23

Előtte nézze meg az eredményt: helm template worksmarthub ./kubernetes-helm-chart -f sajat-values.yaml --set app.image.tag=23. A test-local szkriptjei egy helyi fürtön ellenőrzik a chartot, mielőtt máshová telepítené (test-local/README.md).

11. lépés: Ellenőrzés#

bash
kubectl get pods -n worksmarthub
# worksmarthub-deployment-...  1/1 Running   (alkalmazás; init konténerek: prepare-data, wait-for-db, wait-for-cache)
# db-deployment-...            1/1 Running   (beépített PostgreSQL)
# cache-deployment-...         1/1 Running   (beépített Redis)

kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container
# ... Migrating database ... Applying migration '...' ... Migration complete

kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c wait-for-db      # PostgreSQL accepts the login from values.yaml.
kubectl get pvc,svc,ingress -n worksmarthub

Az első indulás minden migrációt lefuttat (kis fürtön körülbelül egy perc); a pod akkor Ready, amikor a /health válaszol. Az alkalmazás megnyitása:

  • Ingress-szel és hostnévvel: https://wsh.example.com/;
  • Ingress-szel hostnév nélkül: az Ingress címe (kubectl get ingress -n worksmarthub);
  • Ingress nélkül: kubectl port-forward -n worksmarthub svc/worksmarthub 8080:80, majd http://localhost:8080/.

Az első felhasználót a kezdőoldalon hozza létre.

12. lépés: A licenc aktiválása#

A licencet az alkalmazásban kell feltölteni, és az adatbázisban tárolódik; Helm érték nincs hozzá. Túléli a pod újraindítását és a frissítést, és minden replika ugyanazt a licencet olvassa.

A portálon: nyissa meg a Licenc oldalt (/portal/license), és válassza az Új licenc fájl feltöltése gombot. Az oldal mutatja az állapotot, az ügyfelet, a kezdő, a lejárati és a lejárati figyelmeztetés dátumát.

Ki tölthet fel. Amíg az alkalmazásnak nincs érvényes licence (nincs, lejárt vagy sérült), bárki feltölthet egyet, bejelentkezve vagy anélkül, így egy új telepítés az első felhasználó létrehozása előtt is licencelhető. Az érvényes licencet, a lejárati figyelmeztetés időszakában lévőt is, csak Super Admin (a SuperAdmin jogosultság) cserélheti le; más hívó generic.not_authorized hibát kap. Az érvénytelen licencfájlt az alkalmazás license.error hibával utasítja el.

API-n keresztül:

bash
# még nincs érvényes licenc: bejelentkezés nem kell
curl -X POST https://wsh.example.com/api/licensing/set \
  -H "Content-Type: application/octet-stream" --data-binary @license.key

# állapot (bejelentkezés nem kell)
curl https://wsh.example.com/api/licensing/status

Érvényes licenc API-n keresztüli cseréjéhez egy Super Admin személyes hozzáférési tokenje kell (a Személyes Hozzáférési Tokenek oldalon hozható létre, /portal/pat). A refresh tokenjét cserélje access tokenre, és azt küldje Bearer tokenként. Minden frissítés új refresh tokent ad vissza, az előző pedig érvényét veszti, ezért az újat tárolja el:

bash
RESPONSE=$(curl -s -X POST https://wsh.example.com/api/pats/refresh-token \
  -H "Content-Type: application/json" -d '{"refreshToken": "<refresh token>"}')
NEW_REFRESH_TOKEN=$(echo "$RESPONSE" | jq -r '.refreshToken.token')     # ezt tárolja a régi helyett
ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken.token')

curl -X POST https://wsh.example.com/api/licensing/set \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" --data-binary @license.key

Az access token ?access_token=<access token> paraméterként is küldhető; a fejléc távol tartja a hozzáférési naplóktól. A személyes hozzáférési token csak API-hívásokat hitelesít, böngészős munkamenetet soha nem indít.

Frissítés és visszaállás#

bash
bash build/build-image.sh --version 24 --minikube       # vagy töltse fel a worksmarthub:24-et a registryjébe
helm upgrade worksmarthub ./kubernetes-helm-chart -f sajat-values.yaml --set app.image.tag=24
kubectl rollout status -n worksmarthub deploy/worksmarthub-deployment
kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container | grep -E "Migrat|ERR|FTL"
  • Előtte mentse az adatbázist (a parancsok az Átköltözés környezetek között részben).
  • Ugyanazokat a values értékeket használja, mint a telepítéskor, és csak a címkét változtassa meg. A repository újabb verziója új chart-alapértékeket hozhat: frissítés előtt vesse össze a values.yaml és az appsettings.json fájlját a sajátjával.
  • Az alkalmazás podja lecserélődik (ReadWriteOnce adatkötetnél előbb a régi pod áll le: rövid kiesés), induláskor migrálja az adatbázist, és megtartja az adatkötetet. Az adatbázis és a cache podja, a kötetek és a felhasználók munkamenetei megmaradnak.
  • A chart appsettings.json fájljának módosítása is újraindítja az alkalmazás podját; egy Secret módosításához kubectl rollout restart kell.

Visszaállás. A helm history worksmarthub felsorolja a revíziókat; a helm rollback worksmarthub <revízió> visszaállítja annak a revíziónak a manifestjét és image-ét. Az adatbázis nem migrálódik vissza: a korábbi verzió ekkor az újabb sémán fut. Korábbi alkalmazásverzióra való visszatéréshez a frissítés előtt készült adatbázis-mentést állítsa vissza.

A frissítés előzetes kipróbálása. A test-local/upgrade-test.sh minikube-on végigjátssza a folyamatot: telepítés az A image-dzsel, adatok létrehozása (első felhasználó, egy második felhasználó, bejelentkezés, jelölőfájl az adatkötetre, egy szerkesztett sablon), helm upgrade a B image-re, és ellenőrzi, hogy csak az alkalmazás podja cserélődött (0 újraindítással), a PVC-k, az adatbázis és a cache podja megtartotta az UID-ját, az adatok és a frissítés előtti bejelentkezés működnek, és lefutottak a migrációk; végül helm rollback és ugyanezek az ellenőrzések:

bash
bash test-local/upgrade-test.sh --from 23 --to 24

Átköltözés környezetek között#

Egy telepítés költöztetéséhez (például Dockerről vagy Windows szerverről Kubernetesre, vagy másik fürtre) másolja át az adatbázist és az adatkötetet; együtt a teljes állapotot tartalmazzák: felhasználók, munkaterületek, munkalapok, ügyfelek, számlák, a File Storage és az értesítési csatornák definíciói, a licenc, a bejelentkezési kulcsok és az auditnapló. A tárolt hitelesítő adatok az új telepítésen a régi gép bármilyen adata nélkül visszafejthetők.

  • Maradjon ugyanaz az adatbázismotor (beépített átalakítás nincs), és az új oldalon ugyanaz vagy újabb alkalmazásverzió fusson; az első indulásakor migrálja a sémát.
  • Használja ugyanazokat az aláírókulcsokat (TicketAttachment.DownloadLink.SymmetricSecurityKey, ImageConfiguration.ImageLink.SymmetricSecurityKey, LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey), különben a meglévő hivatkozások és tokenek nem működnek; a PublicBaseUrl legyen az új cím.
  • Utána ne fusson a két telepítés ugyanazokkal a külső File Storage bucketekkel (lásd Több csomópont és magas rendelkezésre állás).

A beépített PostgreSQL-lel (előbb állítsa le az alkalmazást: kubectl scale -n worksmarthub deploy/worksmarthub-deployment --replicas=0):

bash
# adatbázis ki a régi telepítésből és be az újba
kubectl exec -n worksmarthub deploy/db-deployment -- sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > wsh-db.dump
kubectl exec -i -n <új névtér> deploy/db-deployment -- sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner' < wsh-db.dump

# adatkötet (amíg létezik alkalmazás pod, pl. közvetlenül azután, hogy az újat 1-re skálázta)
kubectl exec -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container -- tar czf - -C /app/data . > wsh-data.tgz
kubectl exec -i -n <új névtér> deploy/worksmarthub-deployment -c worksmarthub-container -- tar xzf - -C /app/data < wsh-data.tgz

Dockerről a kötet mentése (Mentés és visszaállítás) az adatarchívum, és egy SQLite adatbázis is vele együtt költözik (az archívum database.db fájlja; az új oldalon az SQLite értékeket használja). Az adatbázist az új alkalmazás első indulása előtt állítsa vissza, vagy indítsa el egyszer, állítsa le, állítsa vissza, és indítsa újra. Utána törölje a mentés- és archívumfájlokat; hitelesítő adatokat tartalmaznak.

Eltávolítás#

bash
helm uninstall worksmarthub
  • installNameSpace: True esetén (az alapérték) a névtér a release része, és mindennel együtt törlődik, a worksmarthub-data-claim és a postgres-data-claim PVC-vel is. Hogy az adatok megmaradnak-e, a StorageClass visszanyerési szabályán múlik: Delete (a gyakori) törli őket, Retain Released állapotban megtartja a PersistentVolume-okat.
  • Megmarad: az existingClaim-ként megadott PVC, a saját magának létrehozott névtér (installNameSpace: False) a benne lévő Secretekkel (törlése: kubectl delete namespace worksmarthub), és az image-ek a csomópontokon.
  • Előtte mentse az adatbázist és az adatkötetet (a parancsok az Átköltözés környezetek között részben).

Élesítési ellenőrzőlista#

Az alapértékek első telepítéshez valók, nem éles üzemhez. Élesítés előtt:

Adatok és tartósság

  • [ ] Külső, felügyelt adatbázis mentéssel és időpontra visszaállítással, vagy legalább a beépített PostgreSQL rendszeres mentése (3. lépés). A beépített egyetlen példány, átállás nélkül.
  • [ ] Tartós StorageClass titkosítással, és Retain vagy existingClaim, ahol az adatnak túl kell élnie a helm uninstall parancsot (5. lépés).
  • [ ] A File Storage a replikák számához illik: egy replikához Physical az adatkötetre, többhöz külső háttér.
  • [ ] Közös cache (Redis), ha egynél több replika fut (4. lépés).

Biztonság

  • [ ] Az alapértelmezett adatbázisjelszó megváltoztatva (Adatbázisjelszó).
  • [ ] Saját aláírókulcsok a LoginSettings.JwtAuthenticationSettings, TicketAttachment.DownloadLink és ImageConfiguration.ImageLink alatt, Secretből; induláskor nincs SECURITY: figyelmeztetés (7. lépés).
  • [ ] A PublicBaseUrl a nyilvános címre állítva.
  • [ ] A hitelesítő adatok Secretekben, nem a values.yaml vagy az appsettings.json fájlban.
  • [ ] TLS az Ingress-en érvényes tanúsítvánnyal; HSTS bekapcsolva a Biztonsági fejlécek oldalon; a Service ClusterIP.
  • [ ] TLS az adatbázis felé (SSL Mode=Require, Encrypt=True, SslMode=Required).
  • [ ] UseDetailedExceptions false; Swagger:Enabled false, ha nincs rá szükség.
  • [ ] Az éles identitásszolgáltató (LDAP vagy AzureAD, vagy OAuth), ha nem helyi felhasználókkal fut.
  • [ ] NetworkPolicy érvényesítés (képes CNI) és a biztonsági csapat által kért kimenő szabályok.

Rendelkezésre állás és üzemeltetés

  • [ ] A replikák és az erőforrások méretezve; több replikánál minden többcsomópontos feltétel teljesül (9. lépés).
  • [ ] Naplógyűjtés a standard kimenetről (kubectl logs) a naplózó rendszerbe; a naplózási szint Information vagy Warning.
  • [ ] A licenc aktiválva (12. lépés).
  • [ ] Egy frissítés kipróbálva egy másolaton (Frissítés és visszaállás).

Fontos tudnivalók#

Biztonsági környezet. Minden konténer nem root felhasználóként, minden Linux-képesség elvételével és jogosultság-emelés nélkül fut, minden podon seccompProfile: RuntimeDefault van, és az alkalmazás ServiceAccount-ja nem csatol API tokent. Ez megfelel a restricted Pod Security Standardnek, kivéve az opcionális fix-db-permissions init konténert:

Konténer UID Megjegyzés
Alkalmazás (worksmarthub-container) 1001 appuser
prepare-data (init, adatkötettel) 1001 Létrehozza a FileStorage és a Logs mappát
wait-for-db (init, beépített PostgreSQL-lel) 70 psql bejelentkezési ellenőrzés
wait-for-cache (init, beépített Redisszel) 65534 nc ellenőrzés, legfeljebb 5 percig
merge-ca-certs (init, customCaCerts mellett) 65534 PEM fájlok összefűzése
PostgreSQL 70 fsGroup: 70
Redis 999
fix-db-permissions (init, csak internalDatabase.fixDataPermissions: True mellett) 0 A CHOWN kivételével minden képességet elvesz; alapértelmezésben ki van kapcsolva

Hálózati szabályok. A beépített PostgreSQL és Redis bejövő NetworkPolicy-t kap (internalServicesNetworkPolicy.enabled, alapértelmezésben bekapcsolva), amely csak a névtér podjait engedi be; az internalServicesNetworkPolicy.extraIngress a névtéren kívüli forrásokat ad hozzá (például egy mentési feladat névterét). A podokat az app címkével együtt a chart saját wsh-internal-service: db / cache címkéje alapján választják ki, így soha nem érintik más alkalmazás podjait. A NetworkPolicy-kat csak az ezt támogató CNI érvényesíti (Calico, Cilium, Weave Net).

Próbák. GET /health a 8080-as porton: az indulási próba 10 percet ad az első indulásra (migrációk), a készenléti próba kiveszi a podot a Service-ből, ha nem válaszol, az élőségi próba pedig 2,5 perc válasz nélkül újraindítja. A terminationGracePeriodSeconds: 60 lefedi, hogy az alkalmazás 45 másodpercet hagy a háttérfolyamatainak leálláskor. A PostgreSQL podnak pg_isready készenléti próbája, a Redis podnak TCP próbája van.

Beállításváltozások: a chart appsettings.json fájljának módosítása újraindítja az alkalmazás podját (checksum/config annotáció).

Elszigetelt és korlátozott hálózatok#

Kimenő internet-hozzáférés nélkül:

  1. Az alkalmazás image-e: ott készítse el, ahol a források vannak, --save worksmarthub-23.tar, és töltse be a csomópontokra, vagy töltse fel a belső registryjébe (app.image.repository).
  2. Infrastruktúra image-ek: a postgres:16-alpine, redis:7-alpine és busybox:1.38.0 image-et kívül töltse le, töltse fel a registryjébe, és állítsa be az internalDatabase.image, cacheSystem.image és busyboxImage értéket. A wait-for-db init konténer az internalDatabase.image, a prepare-data és a merge-ca-certs az alkalmazás image-ét használja.
    bash
    for i in postgres:16-alpine redis:7-alpine busybox:1.38.0; do docker pull $i; docker tag $i registry.example.com/$i; docker push registry.example.com/$i; done
  3. Letöltési szabály: maradjon IfNotPresent, hogy a pod-újraindításhoz ne kelljen registry.
  4. Az alkalmazás saját kimenő kapcsolataihoz (Számlázz.hu, Slack, Teams, Entra ID, objektumtárak) a Kimenő kapcsolatok céljai kellenek, különben az ezeket használó funkciók nem működnek.

Állapotellenőrzés#

A GET /health hitelesítés nélkül 200 {"status":"Healthy"} választ ad, amint az alkalmazás kiszolgálja a kéréseket, vagyis az indulási migrációk után. Mást nem érint: nincs adatbázishívás, nincs verzió- vagy csomópontadat. A chart próbái ezt használják. Az image-ben nincs HEALTHCHECK utasítás, sem curl vagy wget; a benne lévő bash el tudja küldeni a kérést, például Docker Compose-ban:

yaml
healthcheck:
  test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8080 && printf 'GET /health HTTP/1.0\\r\\nHost: localhost\\r\\n\\r\\n' >&3 && grep -q '^HTTP/1.[01] 200' <&3"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 120s

Terheléselosztók és megfigyelőrendszerek a GET /health 200-as állapotkódját figyeljék. Az Admin felület állapotoldala és a naplófájlok részletesebb adatot mutatnak a rendszergazdáknak.

Hibaelhárítás#

Hol vannak a naplók. Docker: docker logs -f worksmarthub (a szolgáltatásnál journalctl -u worksmarthub -f, az ütemezett feladat indulásáról a Windows-szkript melletti worksmarthub-task.log). Kubernetes: kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container -f, az init konténereké -c prepare-data, -c wait-for-db, -c wait-for-cache, -c merge-ca-certs kapcsolóval, egy összeomlott konténer előző futásáé --previous kapcsolóval. A napi fájlok az adatkötet Logs/ mappájában és az Admin felületen vannak (Naplófájlok).

Teendőt nem igénylő üzenetek az első induláskor PostgreSQL-lel. Új, üres PostgreSQL adatbázison a naplóban megjelenik a Cannot load library libgssapi_krb5.so.2 (a PostgreSQL meghajtó az opcionális Kerberos könyvtárat keresi, ami nincs az image-ben, és nélküle folytatja), valamint egyszer az ERR Failed executing DbCommand ... SELECT "MigrationId" ... FROM "__EFMigrationsHistory" sor (a migrációs előzmény tábla még nem létezik; közvetlenül utána létrejön, majd következnek az Applying migration sorok és a Migration complete). Már migrált adatbázisnál egyik sor sem jelenik meg.

Az indítószkript 78-as kóddal lép ki. Egy indítás előtti ellenőrzés nem sikerült, és az üzenet megnevezi: hiányzik az image, már fut egy ilyen nevű konténer, létezik egy adatkötet nélküli leállított konténer, vagy a gépi mappa nincs előkészítve. A systemd szolgáltatás erre a kilépési kódra nem indít újra.

A podok Pending állapotban maradnak. kubectl describe pod -n worksmarthub <pod>: többnyire nincs kötve a PVC (nincs alapértelmezett StorageClass, elírt storageClass, vagy egy ReadWriteOnce kötet még máshoz van csatolva), vagy kevés a CPU vagy a memória a kérésekhez.

ErrImagePull / ImagePullBackOff. A csomóponton nincs meg az image: építse annak a csomópontnak a démonjába (--minikube), töltse be oda, vagy töltse fel registrybe, és állítsa be az app.image.repository és az app.imagePullSecrets értéket. Egy olyan címkével futtatott helm upgrade, amely nincs meg a csomópontokon, ugyanígy hibát ad.

Az adatbázis podja CrashLoopBackOff állapotban van. kubectl logs -n worksmarthub deploy/db-deployment. Permission denied az adatmappán: a tároló figyelmen kívül hagyja az fsGroup-ot; állítsa be az internalDatabase.fixDataPermissions: True értéket, vagy használjon CSI osztályt. database files are incompatible with server: az image főverziója eltér az adatmappáétól.

Az alkalmazás podja újraindul, a naplóban 28P01: password authentication failed áll. Az adatbázis elutasította a jelszót. A beépített PostgreSQL-nél az adatkötet korábban, más jelszóval jött létre (később megváltoztatták a values fájlban, vagy megtartott kötetre telepítettek újra); a wait-for-db naplójából kiderül, hogy a values.yaml adatait is elutasítja-e. Állítsa az adatbázis jelszavát a kapcsolati karakterláncban lévőre (Adatbázisjelszó), vagy állítsa vissza az eredetit; adatok nélküli új telepítésnél el is távolíthatja a release-t, törölheti a postgres-data-claim PVC-t, és újratelepíthet.

Az alkalmazás nem éri el az adatbázist. A beépített adatbázis hostneve db (a Service), a portja 5432; a kapcsolati karakterlánc adatainak egyezniük kell az internalDatabase.settings értékeivel. Külső adatbázisnál ellenőrizze a podból a DNS-t (kubectl exec ... -- getent hosts <host>), a tűzfalat és a TLS-beállításokat.

SQLite migrációs zárolás. A migrációk zárolást használnak; SQLite-on ez egy sor a __EFMigrationsLock táblában, és a migráció közben leállított folyamat (megölt konténer, csomóponthiba) bent hagyja ezt a sort. Az SQLite csak egy csomópontot szolgál ki, ezért az alkalmazás az ilyen sort elavultnak tekinti: a következő induláskor törli, naplózza (Removed a stale SQLite migration lock left by an earlier start that did not finish migrating), és migrál. SQL Serveren, PostgreSQL-en és MySQL-en a zárolást az adatbázis-kapcsolat tartja, és azzal együtt megszűnik; egy második csomópont megvárja, amíg az első befejezi a migrációt.

A pod nem lesz Ready / a próbák sikertelenek. A kubectl describe pod mutatja a próbák eredményét. A próbák a 8080-as port /health címét hívják; a figyelési címnek (HttpSettings.Urls vagy HttpSettings__Urls__0) ezt a portot kell használnia. Az első induláskor az indulási próba legfeljebb 10 percig várja a migrációkat; a lassabb indulás (nagy adatbázis, lassú lemez) újraindításként és az eseményekben Startup probe failed üzenetként jelenik meg.

appsettings.json is read-only a naplóban. Csak tájékoztatás: a fájl csak olvashatóan van csatolva (Kubernetesen mindig), vagy az uid 1001 nem tudja írni. Egy újabb verzió új beállításkulcsai az alapértékükkel, memóriában működnek; ha más érték kell, vegye fel őket a saját fájljába.

SECURITY: figyelmeztetések induláskor. Egy aláírókulcs még a gyári értéken van, vagy a PublicBaseUrl üres; lásd Az első éles használat előtt beállítandók.

A feltöltés 413 Request Entity Too Large hibával leáll. Egy proxy elutasította a kéréstörzset. Ebben a sorrendben ellenőrizze: az advanced.ingress.annotations alatt megadott proxy-body-size értéket (az Öné érvényes), a saját kezelésű Ingress-t vagy vezérlőt (az ingress-nginx alapértéke 1 MB), a Docker előtti fordított proxyt (client_max_body_size), és minden terheléselosztót vagy WAF-ot. Az nginx nevét viselő 413-as oldal proxytól jön, nem az alkalmazástól. A 60 másodperc utáni 504 a proxy olvasási időkorlátja.

Sikertelen kimenő TLS (The remote certificate is invalid, unable to get local issuer certificate). A végpont CA-ja nem megbízható: adja hozzá (Saját CA-tanúsítványok, 6. lépés).

Frissítés után a böngésző az előző verziót mutatja. A szerver a kezdőoldalt Cache-Control: no-cache fejléccel küldi, így a böngésző minden betöltéskor ellenőrzi, és az új portált kapja; a szkript- és stíluscsomagok fájlneve tartalmi hash-t tartalmaz. Az a böngésző, amely egy olyan régebbi build kezdőoldalát tárolta el, amely még nem küldte ezt a fejlécet, addig tartja meg, amíg a gyorsítótára le nem jár vagy ki nem ürítik.

Az Ingress nem működik. Ellenőrizze a vezérlőt (kubectl get pods -n ingress-nginx) és az osztályt (advanced.ingress.className). Más vezérlő vagy service mesh esetén kapcsolja ki a chart Ingress-ét, és a worksmarthub Service 80-as portjára irányítson.

Nem találta, amit keresett?

Írjon nekünk, vagy foglaljon időpontot. Válaszolunk a funkciókkal, a telepítéssel és a licenceléssel kapcsolatos kérdésekre.

Kapcsolat