Bezpieczne przechowywanie klucza API: zmienna środowiskowa, .gitignore, naprawa wycieku

Trzymaj klucz w zmiennej środowiskowej, a nie w kodzie, i nie wrzucaj pliku .env do gita — dopisz odpowiednią linię do .gitignore. Jeśli klucz już trafił w miejsce publiczne, najpierw zajmij się kluczem, a porządki zrób później: czyszczenie historii gita, gdy klucz wciąż siedzi w kodzie i narzędziach, niczego nie naprawia.

To cała idea. Ten przewodnik to wersja praktyczna (podstawy są w What is an API key): trzy polecenia, jedno działające zapytanie i krótki plan na zły dzień.

Dlaczego klucz nie należy do twojego kodu#

Klucz API to hasło, które wydaje twoje pieniądze. Każdy, kto go ma, może wysyłać zapytania na twoje konto, a usługa nie odróżni go od ciebie.

Zwykle kończy się to nudno. Wklejasz klucz do skryptu, żeby pierwsze zapytanie zadziałało, skrypt działa, robisz git push, a repozytorium jest publiczne. Albo wysyłasz koledze plik konfiguracyjny. Albo robisz zrzut ekranu błędu z kluczem widocznym w rogu. Za każdym razem efekt jest ten sam.

GitHub dobrze zna ten schemat. Jego skanowanie sekretów (dokumentacja GitHub, sprawdzone 29 października 2026) przeszukuje całą historię Gita na wszystkich gałęziach w poszukiwaniu zaszytych na stałe danych uwierzytelniających, a także issues, pull requesty, dyskusje, wiki i sekretne gisty, i zgłasza alert, gdy coś znajdzie. To oznacza, że usunięcie linii w następnym commicie niczego nie zmienia: stary commit wciąż ją zawiera.

Oto ten sam skrypt przed i po.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key="<your-key>",  # pasted here: ends up in git
)

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

Drugą wersję możesz bez zmian wysłać na GitHuba, na czat albo do code review. Klucz żyje na twojej maszynie, poza plikiem.

Krok 1: umieść klucz w zmiennej środowiskowej#

Zmienna środowiskowa to nazwana wartość, którą terminal przekazuje każdemu uruchamianemu programowi. Skrypt prosi o CHEAPTOKENS_API_KEY po nazwie i nigdy nie widzi, skąd pochodzi.

Na macOS i Linuksie:

export CHEAPTOKENS_API_KEY="<your-key>"

W Windows PowerShell:

setx CHEAPTOKENS_API_KEY "<your-key>"

Dwa szczegóły często zaskakują. export działa tylko w tym oknie terminala, więc aby go zachować, dopisz linię do profilu powłoki (~/.zshrc lub ~/.bashrc). A setx nie zmienia okna, w którym go wpisałeś: przed testem otwórz nowy terminal.

Teraz pełne zapytanie. Korzysta z endpointu zgodnego z OpenAI, https://api.cheaptokens.dev/v1, oraz z DeepSeek-V4-Flash z pełnym identyfikatorem (deepseek-ai/DeepSeek-V4-Flash-0731; identyfikatory bierz z dokumentacji CheapTokens, bo nazwy różnią się między dostawcami):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

Krótkie powitanie to zapytanie o około 20 tokenów na wejściu i 20 na wyjściu, co przy obecnych cenach daje $0.0000023 (pełna lista jest na stronie z cenami). Jeśli nie wysłałeś jeszcze pierwszego zapytania, Your first API request with CheapTokens przeprowadzi cię przez to od zera.

Odpowiedź modelu wraca w choices[0].message.content, a usage pokazuje zliczone tokeny. Klucz nigdy nie pojawia się w pliku.

Krok 2: używaj pliku .env, ale go nie commituj#

Wpisywanie export w każdym nowym oknie się nudzi. Plik .env trzyma wartość w jednym miejscu, obok projektu:

CHEAPTOKENS_API_KEY=<your-key>

Python czyta go przez python-dotenv (pip install python-dotenv):

from dotenv import load_dotenv
load_dotenv()  # fills os.environ from .env

Plik jest bezpieczny tylko wtedy, gdy git go nie widzi. Dodaj go do .gitignore przed pierwszym commitem:

echo ".env" >> .gitignore
git check-ignore -v .env

Jeśli wszystko jest w porządku, drugie polecenie wypisze coś w rodzaju .gitignore:1:.env .env: git mówi, która reguła ignoruje plik. Jeśli nic nie wypisze, reguła nie działa. W Windows utwórz .gitignore w edytorze z linią .env albo użyj Add-Content .gitignore .env: >> w PowerShellu potrafi zapisać UTF-16, które git może zignorować.

Jedna pułapka: .gitignore działa tylko na plikach, których git jeszcze nie śledzi. Jeśli .env został już raz zacommitowany, uruchom git rm --cached .env, żeby git przestał go śledzić, i traktuj znajdujący się w nim klucz jako ujawniony (więcej o tym poniżej). Dobrym nawykiem jest commitowanie .env.example z nazwą zmiennej i placeholderem zamiast wartości, żeby kolega z zespołu wiedział, co ustawić.

Jeśli klucz wyciekł: co robić, po kolei#

Może klucz trafił do publicznego repo, może był na zrzucie ekranu, a może wkleiłeś całą konfigurację na forum. Kolejność ma większe znaczenie niż szybkość pojedynczego kroku.

Wskazówki samego GitHuba (ta sama strona, sprawdzone 29 października 2026) mówią, żeby natychmiast wymienić dane uwierzytelniające; przepisywanie historii Gita jest opcjonalne i często zbędne, gdy dane uwierzytelniające zostały unieważnione. Ludzie zwykle robią to odwrotnie: spędzają godzinę na czyszczeniu historii, podczas gdy klucz wciąż działa. Nie rób tego.

Po porządkach wyślij jedno małe zapytanie testowe, jak w kroku 1, i sprawdź saldo. Jeśli odpowiada, a saldo i liczba zapytań wyglądają normalnie, porządki są zakończone; obserwuj saldo przez kilka następnych dni. Klucz, który był publiczny, należy traktować jako ujawniony nawet po usunięciu go z kodu, więc pilnuj salda i liczby zapytań pod kątem czegoś, czego nie wysłałeś, i nie używaj tego klucza w nowych miejscach. Gdzie klucz zwykle bywa, opisuje Where to plug in your own API key.

Sprawdź się#