Ako opraviť chybu Django „ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty“

Ak Django vyvolá chybu django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, okamžitý problém je jednoduchý: modul nastavení, ktorý Django načítal, neposkytuje v čase behu použiteľnú hodnotu SECRET_KEY. Opravte hodnotu v module nastavení, ktorý sa skutočne používa, alebo sa uistite, že premenná prostredia, ktorá ju dodáva, dosiahne proces Django. Neriešte produkčné zlyhanie trvalým odovzdaním tajného kľúča do systému správy verzií.

Táto príručka bola overená podľa dokumentácie Django 6.1. Django 6.1 bolo vydané 5. augusta 2026. Základné pravidlo je explicitné: SECRET_KEY má predvolenú hodnotu prázdny reťazec, musí byť jedinečný a nepredvídateľný a Django odmietne spustiť, ak nie je nastavený. Pozrite si oficiálnu referenciu nastavenia SECRET_KEY v Django.

Čo vlastne znamená „SECRET_KEY setting must not be empty“?

Znamená to, že keď sa Django pokúsil použiť settings.SECRET_KEY, vyriešená hodnota bola prázdna alebo inak chýbala. V novovytvorenom projekte príkaz django-admin startproject zvyčajne zapíše generovaný kľúč do súboru settings.py. Táto chyba je preto obzvlášť častá po reorganizácii projektu pre viacero prostredí, presune do premenných prostredia, nasadení na novú službu alebo spustení s iným modulom nastavení.

Prvou užitočnou otázkou nie je „Ako vymyslím ľubovoľný reťazec, ktorý spustí server?“. Je ňou „Odkiaľ má toto nasadenie získať svoj tajný kľúč?“. Tento rozdiel je dôležitý, pretože existujúca produkčná aplikácia by mala zvyčajne obnoviť svoj zamýšľaný tajný kľúč namiesto tichého generovania iného pri každom spustení.

Bežné vzory kódu, ktoré spôsobujú túto chybu

SECRET_KEY = ""

# Chýbajúca premenná prostredia vráti None
SECRET_KEY = os.getenv("SECRET_KEY")

# Chýbajúca premenná prostredia ticho spadne na prázdny reťazec
SECRET_KEY = os.getenv("SECRET_KEY", "")

Všetky tri nechávajú Django bez použiteľného tajného kľúča, keď externá hodnota chýba. Pre produkčnú konfiguráciu Djangoho vlastný kontrolný zoznam nasadenia demonštruje formu fail-fast:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

S týmto vzorom chýbajúca premenná prostredia procesu zlyhá okamžite namiesto toho, aby sa ticho stala prázdnu hodnotou. Oficiálny kontrolný zoznam nasadenia Django tiež uvádza, že produkčný kľúč by mal byť veľká náhodná hodnota, udržiavaná v tajnosti, nepoužívaná inde a neukladaná do systému správy verzií.

Ktorý súbor nastavení Django skutočne načítava?

Pred úpravou súboru sa uistite, že ide o súbor, ktorý používa váš príkaz alebo aplikačný server. Django vyberá modul nastavení pomocou DJANGO_SETTINGS_MODULE, čo je cesta Pythonu, ako napríklad mysite.settings alebo config.settings.production. Oficiálna príručka nastavení Django dokumentuje tento mechanizmus a možnosť príkazového riadka --settings.

Napríklad zmena config/settings.py nepomôže, ak služba spúšťa Django s:

python manage.py runserver --settings=config.settings.local

Rovnako tak produkčný vstupný bod WSGI alebo ASGI môže nastavovať iný modul. Skontrolujte manage.py, wsgi.py, asgi.py a skutočný príkaz servera alebo konfiguráciu služby. Ak zámerne používate produkčný modul nastavení, testujte explicitne tento istý modul namiesto testovania vývojového súboru a predpokladania, že výsledok sa prenesie.

Mali by ste vygenerovať nový SECRET_KEY alebo obnoviť starý?

Pre úplne nový lokálny projekt: vygenerovanie novej zabezpečenej hodnoty je rozumné. Štandardný modul Pythonu secrets je určený na kryptograficky silnú náhodnosť. Jedným prenosným príkazom je:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Dokumentácia Pythonu opisuje modul secrets ako modul na generovanie zabezpečených náhodných hodnôt vhodných pre heslá, autentizačné tokeny a súvisiace tajné kľúče. Pozrite si oficiálnu dokumentáciu Pythonu secrets.

Pre existujúcu produkčnú aplikáciu, ktorá predtým fungovala: najprv sa pokúste obnoviť rovnaký zamýšľaný tajný kľúč z vášho úložiska tajných kľúčov alebo konfigurácie nasadenia. Django používa SECRET_KEY na kryptografické podpisovanie a pre niekoľko funkcií, vrátane určitých konfigurácií relácií a správ a tokenov na resetovanie hesla. Neočakávaná výmena kľúča môže zneplatniť podpísané údaje. Ak starý kľúč nebol kompromitovaný a výpadok je len chybou v injektáži prostredia, jeho obnovenie zvyčajne vyhne zbytočnej rotácii.

Ak bol starý kľúč odhalený: vykonajte jeho rotáciu. Django 6.1 podporuje SECRET_KEY_FALLBACKS pre plánovanú rotáciu, čo umožňuje dočasne prijímať staré kľúče, zatiaľ čo nové podpisovanie používa nový kľúč. Odstráňte záložné kľúče, keď ich prechodné obdobie skončí. Správanie a kompromis sú zdokumentované v oficiálnej referencii SECRET_KEY_FALLBACKS.

Aká je najrýchlejšia bezpečná oprava pre lokálny vývoj?

Ak sa len snažíte spustiť jednorazový lokálny projekt, môžete vložiť vygenerovanú hodnotu určenú len pre vývoj do aktívneho súboru nastavení dostatočne dlho na potvrdenie diagnózy:

SECRET_KEY = "nahraďte-toto-náhodnou-hodnotou-len-pre-vývoj"

Potom znova spustite Django. Ak chyba zmizne, potvrdili ste, že blokátorom bolo prázdne nastavenie. Nekopírujte produkčný tajný kľúč na vývojársky laptop len preto, aby bola lokálna inštalácia pohodlnejšia, a nepovažujte hardkódovanú vývojovú hodnotu za váš produkčný návrh.

Dosahuje premenná prostredia skutočne proces Django?

Toto je najdôležitejšia kontrola, keď váš súbor nastavení už obsahuje SECRET_KEY = os.environ["SECRET_KEY"] alebo ekvivalentné vyhľadávanie. Premenná musí existovať v prostredí presného procesu, ktorý importuje nastavenia Django. Nastavenie v jednom termináli automaticky nevloží premennú do už bežiacej služby, kontajnera, správcu procesov, úlohy CI alebo samostatného shellu.

Otestujte prítomnosť bez vytlačenia samotného tajného kľúča:

python -c "import os; print(bool(os.environ.get('SECRET_KEY')))"

Ak toto vytlačí False, opravte injektáž prostredia pre daný proces. Pre rýchly lokálny test shellu použite syntax pre váš shell a potom spustite Django z rovnakého shellu. Napríklad:

# macOS / Linux shell
export SECRET_KEY='vas-vygenerovany-lokalny-tajny-kľúč'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'vas-vygenerovany-lokalny-tajny-kľúč'
python manage.py runserver

Pre produkciu použite mechanizmus tajných kľúčov/konfigurácie poskytnutý vašou hostingovou platformou alebo správcom procesov namiesto vkladania hodnoty do príkazu, ktorý by mohol byť uložený v histórii shellu.

Prečo pridanie SECRET_KEY do súboru .env neopravilo Django?

Súbor .env je len súbor, kým niečo nenačíta jeho obsah do prostredia procesu alebo váš kód nastavení ho neprečíta. Oficiálny príklad Django číta os.environ; Django nevyžaduje ani nedokumentuje vstavaný automatický krok načítania .env. Ak váš projekt spolieha na knižnicu dotenv, obálku frameworku, konfiguráciu kontajnera alebo platformu nasadenia na načítanie tohto súboru, overte túto komponentu samostatne a overte, či sa spúšťa predtým, ako settings.py prečíta SECRET_KEY.

Užitočnou akciou je spustiť vyššie uvedenú boolean kontrolu prostredia z rovnakého kontajnera, účtu služby, shellu alebo fázy vykonávania, ktorá zlyháva. Ak vytlačí False, ladenie obsahu settings.py samo o sebe nevyrieši problém s konfiguráciou na úrovni procesu.

Čo ak sa chyba objaví len v Docker, CI, collectstatic, WSGI alebo ASGI?

To zvyčajne znamená, že iný proces alebo fáza vykonávania načítava projekt s iným prostredím alebo modulom nastavení. Chyba sa môže objaviť počas collectstatic, migrácií, testov, kontroly CI, štartu aplikačného servera alebo procesov na pozadí, hoci runserver funguje na vašom laptop.

Nepredpokladajte, že tajný kľúč dostupný v čase behu je dostupný aj počas zostavovania obrazu alebo kroku CI. Naopak, nepredpokladajte, že premenná exportovaná v interaktívnom shellu je viditeľná pre systémovú službu. Skontrolujte tieto dva fakty v zlyhávajúcom kontexte:

• Ktorá hodnota DJANGO_SETTINGS_MODULE alebo --settings sa používa?
• Má tento presný proces neprázdnu premennú prostredia SECRET_KEY predtým, ako Django importuje nastavenia?

Konkrétny spôsob injektáže tajného kľúča závisí od Docker, vášho poskytovateľa CI, vášho hostiteľa alebo vášho správcu procesov. Použite oficiálny mechanizmus správy tajných kľúčov danej platformy. Požiadavka na strane Django zostáva rovnaká: vybraná konfigurácia nastavení musí poskytnúť neprázdny tajný kľúč v čase behu.

Ako overíte opravu bez odhalenia kľúča?

Najprv nevytlačte skutočný produkčný kľúč do logov len preto, aby ste dokázali, že existuje. Overte prítomnosť boolean kontrolou a potom nechajte Django načítať konfiguráciu:

python manage.py check

Pre produkčnú konfiguráciu Django odporúča spúšťať kontroly nasadenia proti produkčnému súboru nastavení:

python manage.py check --deploy --settings=config.settings.production

Nahraďte cestu modulu vaším skutočným produkčným modulom nastavení. Oficiálny kontrolný zoznam nasadenia konkrétne odporúča check --deploy a varuje, že by sa mal spúšťať proti produkčným nastaveniam.

Nakoniec reštartujte skutočný proces aplikácie. Premenná pridaná po štarte služby zvyčajne neovplyvní už bežiaci proces. Ak reštartovaný proces prejde kontrolami Django a už nevyvoláva výnimku, problém s konfiguráciou je vyriešený.

Ktoré opravy by ste sa mali vyhnúť?

• Nenastavujte SECRET_KEY = "" ani nepoužívajte prázdnu predvolenú hodnotu. To reprodukuje podmienku, ktorú Django odmieta.
• Negenerujte nový kľúč pri každom štarte aplikácie. Meniaci sa kľúč môže zneplatniť podpísané údaje a vytvoriť nekonzistentné správanie medzi viacerými workerami.
• Nekopírujte tajný kľúč z tutoriálu alebo iného projektu. Django vyžaduje jedinečnú, nepredvídateľnú hodnotu a verejná hodnota poráža účel tajného kľúča.
• Neukladajte produkčný kľúč do Gitu. Kontrolný zoznam nasadenia Django výslovne odporúča držať ho mimo systému správy verzií.
• Nevytlačte celý kľúč do logov CI alebo produkcie. Kontrolujte len to, či je prítomný, pokiaľ nemáte kontrolovaný postup auditu tajných kľúčov.
• Nepredpokladajte, že súbor .env je načítaný len preto, že existuje. Potvrďte mechanizmus načítania a skutočné prostredie procesu.

Praktická cesta rozhodovania

Záverečný kontrolný zoznam

• Potvrďte presný modul nastavení, ktorý Django načítava.
• Potvrďte, že SECRET_KEY sa v danom prostredí vyrieši na neprázdnu hodnotu.
• Použite jedinečnú, nepredvídateľnú hodnotu; nepoužívajte znovu verejný alebo tutoriálový kľúč.
• Držte produkčný kľúč mimo systému správy verzií.
• Ak používate premenné prostredia, uistite sa, že premenná dosiahne každý proces, ktorý importuje nastavenia Django.
• Ak používate workflow .env, overte načítavač namiesto predpokladania, že Django číta súbor automaticky.
• Obnovte starý produkčný kľúč, ak je problémom náhodná strata konfigurácie; rotujte len vtedy, keď je to zamýšľané alebo vyžadované.
• Spustite python manage.py check a pre produkciu spustite check --deploy proti produkčnému modulu nastavení.
• Po zmene prostredia reštartujte skutočnú službu.

Kľúčovým bodom je, že táto výnimka nežiada konkrétny magický reťazec. Hovorí vám, že aktívne nastavenia Django neobsahujú použiteľný tajný kľúč. Opravte zdroj tejto konfigurácie, zachovajte zamýšľaný produkčný kľúč, ak je to vhodné, a overte výsledok v rovnakom prostredí procesu, ktoré pôvodne zlyhalo.