> ## Documentation Index > Fetch the complete documentation index at: https://gomodel.enterpilot.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Referencje do sekretów > Odczytuj klucze API, DSN-y i inne dane uwierzytelniające ze zmiennych środowiskowych lub zamontowanych plików za pomocą referencji ${env:...} i ${file:...}. Referencja do sekretu mówi GoModel, skąd odczytać wartość, zamiast przechowywać samą wartość: ```yaml theme={null} server: master_key: ${file:/run/secrets/gomodel-master-key} providers: openai: type: openai api_key: ${env:OPENAI_KEY} ``` Referencje działają w każdym ustawieniu tekstowym `config.yaml`, w zmiennych środowiskowych, które ustawiają te ustawienia, oraz w zmiennych środowiskowych providerów: ```bash theme={null} OPENAI_API_KEY='${file:/run/secrets/openai}' POSTGRES_URL='${file:/run/secrets/postgres-url}' ``` W shellu ujmij wartość w pojedyncze cudzysłowy, aby shell jej nie rozwinął; pliki `.env` nie wymagają cudzysłowów. Docker Compose interpoluje `${...}` we własnych plikach, więc wpisz tam `$${file:...}`; Compose przekaże `${file:...}` dalej do GoModel. ## Składnia Referencja ma postać `${:}`. Może znajdować się wewnątrz większej wartości, a jedna wartość może zawierać kilka referencji: ```yaml theme={null} providers: openai: type: openai api_key: ${env:OPENAI_KEY} proxy_url: http://gomodel:${file:/run/secrets/proxy-pass}@proxy:3128 mcp: servers: github: url: https://mcp.example.com/mcp headers: Authorization: Bearer ${env:GITHUB_TOKEN} ``` Rozwiązana wartość jest używana bez zmian. Może zawierać znaki nowej linii, cudzysłowy lub dowolne inne bajty, więc działa np. plik JSON konta usługi, i nigdy nie jest przeszukiwana pod kątem kolejnych referencji. ## Schematy | Schemat | Referencja | Wartość | | - | - | - | | `env` | nazwa zmiennej | wartość zmiennej; nieustawiona lub pusta zatrzymuje uruchamianie | | `file` | ścieżka bezwzględna | zawartość pliku z usuniętym jednym końcowym znakiem nowej linii; maksymalnie 1 MiB; brakujący lub pusty plik zatrzymuje uruchamianie | `file` odczytuje bezpośrednio sekrety montowane przez Dockera i Kubernetesa, więc nie potrzebujesz skryptu entrypoint, który kopiowałby je do zmiennych środowiskowych. Ścieżka musi wskazywać zwykły plik lub symlink do niego, tak jak w przypadku tych montowań; FIFO lub urządzenie są odrzucane, ponieważ GoModel odczytuje plik ponownie przy każdym przeładowaniu. `env` różni się od zwykłej formy `${NAME}` na dwa sposoby: jest restrykcyjne i działa w zmiennych środowiskowych, a nie tylko w `config.yaml`. Zwykła forma się nie zmienia: `${NAME}` i `${NAME:-default}` są rozwijane w `config.yaml`, a nieustawione `${NAME}` pozostaje bez zmian, co powoduje pominięcie providera, którego jest kluczem. Zewnętrzne menedżery sekretów (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault) podłącza się jako kolejne schematy w [GoModel Pro](https://gomodel.enterpilot.io/docs/pl/pro/overview.md). ## Błędy zatrzymują uruchamianie Referencja, której nie da się rozwiązać, zatrzymuje gateway z błędem podającym ustawienie i schemat, ale nigdy wartość: ```text theme={null} failed to resolve secret references: providers.openai.api_key: secret reference ${file:...}: open /run/secrets/openai: no such file or directory ``` Klucz API providera ustawiony przez zmienną środowiskową jest raportowany pod nazwą tej zmiennej, np. `OPENAI_API_KEY_2: secret reference ${file:...}`. Schemat, którego GoModel nie zna, nie jest powtarzany w błędzie, ponieważ jest to tekst pochodzący z wartości; sprawdź wskazane ustawienie pod kątem literówki. Nieudane [przeładowanie](https://gomodel.enterpilot.io/docs/pl/advanced/cli.md#przeładowanie-konfiguracji) zachowuje działającą konfigurację. GoModel nigdy nie uruchamia się z nierozwiązaną referencją ani nie wysyła jej do upstreamu. Każda referencja ma 30 sekund na rozwiązanie. Taka, która trwa dłużej, np. plik na zawieszonym montowaniu sieciowym, kończy się błędem `context deadline exceeded`, zamiast blokować uruchamianie, przeładowanie lub zapis w dashboardzie. Rozwiązywane są tylko używane wartości: wartość providera w `config.yaml` nadpisana przez zmienną środowiskową, zmienna środowiskowa providera ignorowana przez GoModel (np. `OPENAI_MODELS`, gdy istnieje kilku providerów `openai` i żaden nie nazywa się `openai`) ani provider pominięty z powodu brakujących danych uwierzytelniających nie są odczytywane. ## Rotacja GoModel nie odpytuje cyklicznie referencji `env` ani `file`. Po rotacji jednej z nich wykonaj przeładowanie: `gomodel --reload` lub `SIGHUP`. Rozszerzenia obserwujące menedżer sekretów, takie jak vaulty GoModel Pro, informują GoModel o zmianie wartości. GoModel wtedy ponownie rozwiązuje każdą referencję oraz: * podmienia klucze API providerów w miejscu, gdy zmieniły się tylko one. Requesty w trakcie realizacji kończą się na kluczu, z którym się rozpoczęły. Sesje przypięte do usuniętego klucza przechodzą na inny; większość pozostałych sesji zachowuje swój klucz. * przeładowuje konfigurację, tak jak `SIGHUP`, gdy zmieniło się cokolwiek innego w `config.yaml` lub w środowisku (DSN, master key, URL proxy, JSON konta usługi). Nieudane przeładowanie zachowuje działającą konfigurację i jest ponawiane przy następnej zmianie. Referencje zapisane z dashboardu nigdy nie przeładowują konfiguracji; zobacz [Dane uwierzytelniające zarządzane z dashboardu](#dane-uwierzytelniające-zarządzane-z-dashboardu). * zachowuje wszystkie bieżące wartości, gdy referencji nie da się ponownie rozwiązać, i zapisuje ostrzeżenie w logach z nazwą ustawienia. Linia logu podaje nazwy zmienionych ustawień, ale nigdy ich wartości: ```text theme={null} rotated provider API keys in place providers=[openai] fields=[providers.openai.api_keys[1]] ``` Zmiana klucza providera używanego przez embedder semantycznego cache'u także powoduje przeładowanie, ponieważ embedder przechowuje własną kopię kluczy. ## Dane uwierzytelniające zarządzane z dashboardu Dane uwierzytelniające providerów, nagłówki serwerów MCP i pola sekretów guardrails zapisywane z dashboardu lub przez Admin API także akceptują referencje w tej samej składni: | Encja | Pola | | - | - | | Dane uwierzytelniające providerów | klucze API, JSON konta usługi i JSON w base64, URL proxy | | Serwery MCP | wartości nagłówków | | Guardrails | pola sekretów pluginu | * Referencja jest zapisywana tak, jak ją wpisano; GoModel rozwiązuje ją podczas budowania providera, połączenia MCP lub guardraila. * Referencja nie jest sekretem, więc dashboard i Admin API pokazują bez maskowania wartość składającą się wyłącznie z referencji; nagłówek MCP może też zaczynać się od schematu uwierzytelniania (`Bearer ${env:TOKEN}`), a URL proxy jest pokazywany, gdy jego hasło jest referencją. Dosłowne sekrety oraz wartości łączące dosłowny tekst z referencją pozostają zamaskowane, a odesłanie maski zachowuje zapisaną wartość. * Referencja, której nie da się rozwiązać, jest odrzucana przy zapisie z błędem `400` podającym pole i schemat. * Tylko master key może dodać lub zmienić referencję. Referencja jest rozwiązywana na hoście gatewaya, więc może odczytać dowolną zmienną środowiskową lub plik dostępne dla gatewaya, łącznie z master key. Każde inne dane uwierzytelniające, np. zarządzany klucz z dostępem do dashboardu, otrzymują `403` (`secret_reference_requires_master_key`) z nazwą pola. Nadal mogą zapisywać dosłowne sekrety, odsyłać maskę i ponownie zapisywać encję, której referencje się nie zmieniły. Bez master key dane uwierzytelniające dashboardu zapisują referencje tak jak wcześniej. * Z tego samego powodu tylko master key może zmienić miejsce, do którego encja zawierająca referencję ją wysyła: `url` serwera MCP, `type`, `base_url`, `backend` lub `proxy_url` providera albo typ lub URL usługi guardraila (np. `analyzer_url` Presidio). Inne dane uwierzytelniające otrzymują ten sam `403` z nazwą pola i nadal mogą edytować wszystkie pozostałe pola. * Każde wywołanie resolvera przenosi ścieżkę pola na potrzeby audytu, np. `provider_credentials.openai.api_keys[0]`, `mcp_servers.github.headers.Authorization` lub `guardrail_definitions.pii.config.api_key`. * Gdy wartość wskazywana przez referencję [podlega rotacji](#rotacja), ponownie instalowana jest tylko dotknięta encja: klucze providera są podmieniane w miejscu, każda inna zmiana providera powoduje jego przebudowanie, serwer MCP jest ponownie łączony, a guardrail przebudowywany. Jeśli referencji nie da się rozwiązać, encja zachowuje bieżącą wartość. Reguły guardrails zadeklarowane w `config.yaml` są przechowywane w ten sam sposób: referencja w polu sekretu pluginu jest zapisywana tak, jak ją wpisano, i rozwiązywana przy budowaniu guardraila, więc baza danych nigdy nie przechowuje sekretu. Jeśli zapisanej referencji nie da się rozwiązać przy starcie, dane uwierzytelniające providera lub serwer MCP są logowane i pomijane, a reszta gatewaya się uruchamia. Przy przeładowaniu działające dane uwierzytelniające providera lub serwer MCP nigdy nie są w ten sposób usuwane, także wtedy, gdy klucz rozwiązuje się teraz do pustej wartości: przeładowanie kończy się błędem z nazwą encji i pola, a działająca konfiguracja, łącznie z tą encją, nadal obsługuje ruch. Napraw lub usuń encję, a następnie ponownie wykonaj przeładowanie. Encja, która została już wcześniej pominięta, jest pomijana ponownie i nie blokuje przeładowania. Guardrails ładują się jako całość i blokują w razie błędu (fail closed): uruchamianie kończy się błędem, przeładowanie zachowuje działającą konfigurację, a okresowe odświeżanie zachowuje dotychczasowe guardrails. Wartości zapisane, zanim pojawiły się referencje, są odczytywane w ten sam sposób, więc zapisany dosłowny tekst zawierający `${scheme:...}` jest teraz traktowany jako referencja. Zapisz go ponownie z `$${`, aby pozostał dosłowny. Rozszerzenie może zarejestrować secret writer. Dosłowna wartość wpisana w dashboardzie jest wtedy przechowywana w menedżerze sekretów, a zapisywana jest tylko referencja; sekrety writera są usuwane, gdy usuwana jest ich encja lub pole. Zapis, który nadal zawiera zapisaną przez writera referencję, której encja już nie przechowuje (np. formularz otwarty, zanim ktoś inny zastąpił ten sekret), jest odrzucany: odśwież stronę i zapisz ponownie. Podstawowy GoModel nie zawiera żadnego writera. ## Dosłowne `${` Wpisz `$${`, aby uzyskać dosłowne `${`. `pa$${x}` staje się `pa${x}`. ## Ograniczenia * Referencje `env` i `file` są rozwiązywane przy ładowaniu lub przeładowaniu konfiguracji; zobacz [Rotacja](#rotacja). * Dotyczą ustawień tekstowych. Ustawienie logiczne lub liczbowe nie może być referencją, a zmienna środowiskowa, którą GoModel parsuje jako liczbę, wartość logiczną, czas trwania lub listę (`LOGGING_ENABLED`, `HTTP_TIMEOUT`, `ENABLED_PASSTHROUGH_PROVIDERS`, ...), zatrzymuje uruchamianie, jeśli zawiera referencję. Zmienne JSON akceptują referencje wewnątrz swoich wartości tekstowych. * Wyjątkiem są zmienne środowiskowe providerów: `OPENAI_MODELS`, `OPENAI_MODEL_FILTER_*` i `OPENAI_SESSION_STICKY_KEYS` są rozwiązywane przed parsowaniem. * W encjach zarządzanych z dashboardu referencje akceptują tylko pola wymienione w sekcji [Dane uwierzytelniające zarządzane z dashboardu](#dane-uwierzytelniające-zarządzane-z-dashboardu). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.