Reference proměnných prostředí
Kompletní reference konfiguračních proměnných MazeVault
Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-04-26
Všechny komponenty MazeVault se konfigurují pomocí proměnných prostředí. Tato stránka poskytuje centralizovanou referenci pro všechny podporované proměnné napříč backendem, agentem, gateway a frontendem.
Citlivé hodnoty
Proměnné označené 🔐 obsahují tajemství. Ukládejte je do správce tajemství nebo zapečetěných Kubernetes secrets — nikdy je necommitujte do správy verzí.
1. Základní / Povinné
Tyto proměnné musí být nastaveny pro spuštění backendu.
| Proměnná |
Příklad |
Popis |
🔐 MAZEVAULT_MASTER_KEY |
base64:... |
Hlavní šifrovací klíč pro všechna tajemství v klidu |
🔐 MAZEVAULT_JWT_KEY |
base64:... |
JWT podepisovací klíč pro přístupové tokeny |
🔐 DATABASE_URL |
postgres://user:pass@host:5432/mazevault |
Připojovací řetězec PostgreSQL |
MAZEVAULT_LISTEN_ADDR |
:8443 |
Adresa a port pro naslouchání backendu |
MAZEVAULT_BASE_URL |
https://vault.example.com |
Veřejně dostupná URL platformy |
2. Databáze
| Proměnná |
Výchozí |
Popis |
🔐 DATABASE_URL |
— |
Úplný připojovací řetězec PostgreSQL |
DB_MAX_OPEN_CONNS |
25 |
Maximální počet otevřených spojení |
DB_MAX_IDLE_CONNS |
5 |
Maximální počet neaktivních spojení |
DB_CONN_MAX_LIFETIME |
5m |
Maximální životnost spojení |
🔐 ORACLE_PASSWORD |
— |
Heslo databáze Oracle (vyžadováno při použití Oracle SQL integrace) |
3. Autentizace a SSO (Entra ID)
| Proměnná |
Výchozí |
Popis |
ENTRA_ENABLED |
false |
Povolení Entra ID (Azure AD) SSO |
ENTRA_TENANT_ID |
— |
Azure AD tenant ID |
ENTRA_CLIENT_ID |
— |
Application (client) ID |
🔐 ENTRA_CLIENT_SECRET |
— |
Application client secret |
ENTRA_REDIRECT_URI |
— |
OAuth2 redirect URI |
ENTRA_SCOPES |
openid profile email |
Požadované OAuth2 scopes |
ENTRA_AUTO_CREATE_USERS |
true |
Automatické vytváření uživatelů při prvním SSO přihlášení |
ENTRA_DEFAULT_ROLE |
viewer |
Výchozí role pro automaticky vytvořené uživatele |
MAZEVAULT_ENFORCE_OIDC_NONCE |
false |
Vynutí ověření nonce v OIDC tokenech — doporučeno true v produkci |
4. TLS
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_TLS_ENABLED |
true |
Povolení TLS pro backend |
MAZEVAULT_TLS_CERT_FILE |
— |
Cesta k TLS certifikátu PEM |
MAZEVAULT_TLS_KEY_FILE |
— |
Cesta k privátnímu klíči TLS PEM |
MAZEVAULT_TLS_CA_FILE |
— |
Cesta ke CA bundle pro mTLS ověření |
MAZEVAULT_TLS_MIN_VERSION |
1.2 |
Minimální verze TLS (1.2 nebo 1.3) |
5. Šifrovaný trezor secrets (Volitelné)
Proměnné pro povolení šifrovaného souboru vault jako alternativy k .env pro citlivá tajemství. Viz Šifrovaný trezor secrets pro úplné informace.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_VAULT_FILE |
— |
Cesta k šifrovanému souboru secrets.vault. Pokud není nastaveno, používá se starší režim .env |
MAZEVAULT_VAULT_KEY_FILE |
vault.key |
Cesta k souboru s heslem vault (on-premise režim) |
MAZEVAULT_VAULT_AKV_URL |
— |
URL Azure Key Vault pro načtení hesla vault (Azure režim) |
MAZEVAULT_VAULT_AKV_SECRET |
mazevault-vault-key |
Název AKV secret obsahujícího heslo vault |
6. Email / SMTP
| Proměnná |
Výchozí |
Popis |
SMTP_ENABLED |
false |
Povolení SMTP odesílání emailů |
SMTP_HOST |
— |
Hostname SMTP serveru |
SMTP_PORT |
587 |
Port SMTP serveru |
SMTP_FROM |
— |
Adresa odesílatele |
🔐 SMTP_USERNAME |
— |
Uživatelské jméno pro SMTP autentizaci |
🔐 SMTP_PASSWORD |
— |
Heslo pro SMTP autentizaci |
SMTP_TLS |
true |
Použití TLS pro SMTP spojení |
Office 365 (Volitelné — má přednost před SMTP, pokud je povoleno)
| Proměnná |
Výchozí |
Popis |
O365_EMAIL_ENABLED |
false |
Povolení Office 365 Graph API pro odesílání emailů (má přednost před SMTP) |
O365_TENANT_ID |
— |
Azure AD tenant ID |
O365_CLIENT_ID |
— |
Client ID registrace aplikace (vyžaduje oprávnění Mail.Send) |
🔐 O365_CLIENT_SECRET |
— |
Client secret (pro metodu autentizace client_secret) |
O365_SENDER_EMAIL |
— |
Adresa odesílatele (uživatel nebo sdílená schránka) |
O365_AUTH_METHOD |
client_secret |
Metoda autentizace: client_secret, certificate, managed_identity |
O365_CERTIFICATE_PATH |
— |
Cesta k certifikátu PFX/PEM (pro autentizaci certificate) |
🔐 O365_CERTIFICATE_PASSWORD |
— |
Heslo certifikátu (pro autentizaci certificate) |
O365_MANAGED_IDENTITY_CLIENT_ID |
— |
Client ID Managed Identity (pro autentizaci managed_identity v Azure) |
7. Cache (Redis)
| Proměnná |
Výchozí |
Popis |
REDIS_URL |
— |
Připojovací řetězec Redis (redis://host:6379) |
🔐 REDIS_PASSWORD |
— |
Heslo Redis (pokud je povolena autentizace) |
CACHE_TTL |
300 |
Výchozí TTL cache v sekundách |
8. Azure Gateway Mode
Proměnné pro provoz MazeVault backendu v režimu gateway, připojeného k primárnímu on-premise backendu.
8.1 Základní gateway
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_MODE |
primary |
Nastavte na gateway pro spuštění v režimu gateway |
PRIMARY_BACKEND_URL |
— |
URL primárního on-premise backendu (povinné v režimu gateway) |
🔐 GATEWAY_BOOTSTRAP_TOKEN |
— |
Jednorázový token pro počáteční registraci (vygenerujte z admin UI primárního serveru) |
GATEWAY_NAME |
— |
Čitelný název této gateway instance |
MAZEVAULT_PRIMARY_ENVIRONMENTS |
— |
Čárkou oddělený seznam prostředí obsluhovaných přímo primárním backendem (volitelné — nastaví se při prvním spuštění; následné změny přes UI → Nasazení → Gateway) |
8.2 Multi-Gateway identita
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_GATEWAY_ENVIRONMENT |
— |
Prostředí, které tato gateway obsluhuje (NPR, PRO) |
MAZEVAULT_GATEWAY_ENVIRONMENTS |
— |
Multi-env režim: čárkami oddělený seznam (přepisuje singulární) |
MAZEVAULT_GATEWAY_ROLE |
primary |
Role gateway: primary nebo dr-standby |
MAZEVAULT_GATEWAY_STATE_FILE |
/etc/mazevault/gateway-state.json |
Cesta k souboru s perzistentním stavem gateway |
MAZEVAULT_VERSION |
— |
Verze softwaru reportovaná v heartbeatech |
8.3 Azure Managed Identity
| Proměnná |
Výchozí |
Popis |
AZURE_MANAGED_IDENTITY_CLIENT_ID |
— |
Client ID Azure Managed Identity pro přístup do Key Vault |
8.4 mTLS a zabezpečení
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_MTLS_CA_FILE |
— |
Cesta k vlastnímu CA certifikátu pro mTLS ověření |
GATEWAY_BOOTSTRAP_TTL |
24h |
TTL pro bootstrap tokeny (min 5m, max 24h) |
9. Agent
Viz také Průvodce nasazením agenta pro úplné detaily.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_SERVER_URL |
— |
URL backendu pro komunikaci agenta |
🔐 MAZEVAULT_BOOTSTRAP_TOKEN |
— |
Jednorázový registrační token |
MAZEVAULT_AGENT_NAME |
hostname |
Zobrazovaný název agenta v UI |
MAZEVAULT_PROJECT_ID |
— |
Project scope pro tajemství |
MAZEVAULT_CERT_STORE_PATH |
/var/lib/mazevault/certs |
Adresář úložiště certifikátů |
MAZEVAULT_STATE_DIR |
/etc/mazevault |
Adresář konfigurace a stavu |
MAZEVAULT_LOG_LEVEL |
info |
Úroveň logování (debug, info, warn, error) |
MAZEVAULT_LOG_FORMAT |
text |
Formát logů (text, json) |
SYNC_INTERVAL_SECONDS |
300 |
Interval synchronizace tajemství v sekundách |
MAZEVAULT_AGENT_INSTALL_CHAIN_TO_TRUSTSTORE |
true |
Nainstalovat interní CA řetězec do systémového úložiště důvěryhodných certifikátů na hostu agenta |
MAZEVAULT_AGENT_TRUST_STORE_PATH |
auto |
Přepsat výchozí systémový adresář trust store (pouze Linux; pokud je prázdné, auto-detekováno) |
10. OCSP Responder
| Proměnná |
Výchozí |
Popis |
OCSP_ENABLED |
false |
Povolení OCSP responderu |
OCSP_LISTEN_ADDR |
:8888 |
Adresa pro naslouchání OCSP responderu |
OCSP_CACHE_TTL |
300 |
Doba cache OCSP odpovědí v sekundách |
11. Multi-Datacenter
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_DC_NAME |
— |
Identifikátor datacentra |
MAZEVAULT_DC_PRIMARY |
true |
Zda se jedná o primární DC |
MAZEVAULT_DC_REPLICAS |
— |
Čárkou oddělené URL replik |
MAZEVAULT_DC_SYNC_INTERVAL |
30s |
Interval replikace mezi DC |
12. Frontend (Vite)
Proměnné frontendu se vkládají při buildu. Musí být prefixovány VITE_.
| Proměnná |
Výchozí |
Popis |
VITE_API_URL |
/api |
Základní URL backend API |
VITE_WEBSOCKET_URL |
— |
URL WebSocket endpointu |
VITE_ENTRA_ENABLED |
false |
Zobrazení SSO přihlašovacího tlačítka |
VITE_DOCS_URL |
— |
Odkaz na dokumentační portál |
VITE_SUPPORT_URL |
— |
Odkaz na portál podpory |
13. Bezpečnostní příznaky
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_CORS_ORIGINS |
— |
Povolené CORS originy (čárkou oddělené) |
MAZEVAULT_RATE_LIMIT |
100 |
API požadavků za minutu na klienta |
MAZEVAULT_SESSION_TIMEOUT |
30m |
Časový limit neaktivity relace |
MAZEVAULT_MFA_REQUIRED |
false |
Vyžadování MFA pro všechny uživatele |
MAZEVAULT_AUDIT_RETENTION_DAYS |
365 |
Retence auditních logů ve dnech |
14. Režim nasazení
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_ENV |
production |
Název prostředí (development, staging, production) |
MAZEVAULT_DEBUG |
false |
Povolení debug režimu (nepoužívejte v produkci) |
MAZEVAULT_LOG_LEVEL |
info |
Úroveň logování backendu |
MAZEVAULT_LOG_FORMAT |
json |
Formát logů backendu |
SWAGGER_ENABLED |
true |
Povolení Swagger UI na /swagger/index.html |
FRONTEND_URL |
https://localhost |
Veřejná URL frontendu — používá se pro SSO redirect URI a CORS konfiguraci |
15. Registrace licence / organizace
Proměnné identifikující organizaci na licenčním serveru MazeVault při prvním spuštění.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_CUSTOMER_NAME |
— |
Název organizace (pro registraci licence) |
MAZEVAULT_CUSTOMER_EMAIL |
— |
Kontaktní email administrátora |
MAZEVAULT_COMPANY_ID |
— |
IČO společnosti |
MAZEVAULT_VAT_ID |
— |
DIČ — alternativa k MAZEVAULT_COMPANY_ID |
MAZEVAULT_INSTANCE_ID |
auto |
Unikátní identifikátor instance (auto-generován, pokud je prázdný) |
MAZEVAULT_REGION |
EU |
Geografický region pro soulad s licencí (EU, US, APAC) |
16. Režim Orchetrátora
Rídí, zda MazeVault ukládá citlivé hodnoty lokálně nebo je přenáší do externího poskytovatele. Neměnné po první inicializaci.
Viz Šifrování — Režim Orchetrátora pro úplné detaily.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_ORCHESTRATOR_MODE |
false |
Povolení režimu Orchetrátora — secrets a soukromé klíče jsou přenášeny do Azure Key Vault, AWS Secrets Manager nebo HashiCorp Vault; lokálně se ukládají pouze metadata |
Neměnné po inicializaci
Jakmile je platforma inicializována s MAZEVAULT_ORCHESTRATOR_MODE=true, toto nastavení nelze změnit. Plánujte režim nasazení před prvním spuštěním.
17. ACME DNS-01
Volitelné proměnné pro automatizaci wildcard certifikátů přes DNS-01 challenge.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_ACME_DNS_PROVIDER |
none |
DNS poskytovatel pro ACME DNS-01 challenges (cloudflare, none) |
🔐 MAZEVAULT_ACME_DNS_API_TOKEN |
— |
API token pro DNS poskytovatele (šifrován v klidu) |
18. Správa KeyTab (v1.0.36+)
Volitelné proměnné pro správu životního cyklu Kerberos KeyTab.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_KEYTAB_ENABLED |
true |
Povolení modulu správy KeyTab |
MAZEVAULT_KEYTAB_MAX_SIZE_MB |
10 |
Maximální velikost nahrávaného keytab souboru v MB |
MAZEVAULT_KEYTAB_DEFAULT_EXPIRY_DAYS |
365 |
Výchozí doba exspirace pro nově importované keytaby |
19. Proxy binárních souborů agenta (v1.0.39+)
Volitelné proměnné pro hostování binárních souborů agenta lokálně z privátního repozitáře GitHub.
| Proměnná |
Výchozí |
Popis |
🔐 AGENT_BINARY_GITHUB_TOKEN |
— |
Fine-grained PAT s oprávněním Contents: Read na MazeVault/maze-release |
AGENT_BINARY_CACHE_DIR |
/data/agent-binaries |
Lokální disková cache pro stažené binární soubory |
AGENT_BINARY_RELEASE_API_URL |
https://api.github.com/repos/MazeVault/maze-release/releases |
URL GitHub Releases API |
AGENT_DOWNLOAD_BASE_URL |
https://github.com/MazeVault/maze-release/releases |
Základní URL servovaná agentům pro stahování |
AGENT_VERSION |
latest |
Verze agenta k distribuci (latest nebo vX.Y.Z) |
AGENT_ROLLOUT_PERCENTAGE |
100 |
Procento agentů, které obdrží notifikaci o aktualizaci (0–100) — deterministické rozdělení per-agent |
AGENT_MAX_CONCURRENT_DOWNLOADS |
10 |
Maximální počet paralelních stahování binárních souborů |
MAZEVAULT_SERVER_URL |
— |
Veřejné URL backendu — fallback pro self-update odkazy agenta, když reverse proxy nepropaguje hlavičky Origin/Host |
Související