Kaip išspręsti Django klaidą „ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty“

Jei Django meta klaidą django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, tiesioginė problema yra paprasta: Django įkeltas nustatymų modulis vykdymo metu nepateikia tinkamos SECRET_KEY reikšmės. Pataisykite reikšmę tame nustatymų modulyje, kuris iš tikrųjų yra naudojamas, arba įsitikinkite, kad aplinkos kintamasis, kuris ją pateikia, pasiekia Django procesą. Nespręskite gamybos aplinkos gedimo įtraukdami nuolatinį slaptažodį į šaltinio kodo valdymo sistemą.

Šis vadovas buvo patikrintas pagal Django 6.1 dokumentaciją. Django 6.1 buvo išleistas 2026 m. rugpjūčio 5 d. Pagrindinė taisyklė yra aiški: SECRET_KEY numatytoji reikšmė yra tuščia eilutė, ji turi būti unikali ir nenuspėjama, o Django atsisako paleisti, jei ji nenustatyta. Žiūrėkite oficialią Django SECRET_KEY nustatymo nuorodą.

Ką iš tikrųjų reiškia „SECRET_KEY setting must not be empty“?

Tai reiškia, kad bandant naudoti settings.SECRET_KEY, išspręsta reikšmė buvo tuščia arba jos nebuvo. Naujai sukurtame projekte komanda django-admin startproject paprastai įrašo sugeneruotą raktą į settings.py. Todėl ši klaida ypač dažna po to, kai projektas buvo pertvarkytas kelioms aplinkoms, perkeltas į aplinkos kintamuosius, išdiegtas naujoje paslaugoje arba paleistas su kitu nustatymų moduliu.

Pirmasis naudingas klausimas nėra „Kaip sugalvoti bet kokią eilutę, kad serveris paleistųsi?“. Tai yra „Iš kur šis diegimas turėtų gauti savo slaptažodį?“. Šis skirtumas yra svarbus, nes esamai gamybos aplinkos programai paprastai turėtų būti atkurtas numatytasis slaptažodis, o ne tyliai generuojamas kitas kiekvieno paleidimo metu.

Dažni kodo šablonai, sukeliantys šią klaidą

SECRET_KEY = ""

# Trūkstamas aplinkos kintamasis grąžina None
SECRET_KEY = os.getenv("SECRET_KEY")

# Trūkstamas aplinkos kintamasis tyliai grąžina tuščią eilutę
SECRET_KEY = os.getenv("SECRET_KEY", "")

Visi trys variantai palieka Django be tinkamo slaptažodžio, kai išorinė reikšmė nėra nustatyta. Gamybos konfigūracijai Django diegimo kontrolinis sąrašas demonstruoja „fail-fast“ (greito gedimo) formą:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Taikant šį šabloną, trūkstamas proceso aplinkos kintamasis sukelia nedelsiant gedimą, o ne tyliai tampa tuščia reikšme. Oficialus Django diegimo kontrolinis sąrašas taip pat nurodo, kad gamybos raktas turi būti didelis atsitiktinis dydis, laikomas slapta, nenaudojamas kitur ir neįtraukiamas į šaltinio kodo valdymo sistemą.

Kurį nustatymų failą Django iš tikrųjų įkelia?

Prieš redaguodami failą, įsitikinkite, kad tai yra failas, kurį naudoja jūsų komanda arba programų serveris. Django pasirenka nustatymų modulį per DJANGO_SETTINGS_MODULE, Python kelią, pvz., mysite.settings arba config.settings.production. Oficiali Django nustatymų vadovas dokumentuoja šį mechanizmą ir --settings komandinės eilutės parametrą.

Pavyzdžiui, keisti config/settings.py nepadės, jei tarnyba paleidžia Django su:

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

Taip pat gamybos WSGI arba ASGI įėjimo taškas gali nustatyti kitą modulį. Patikrinkite manage.py, wsgi.py, asgi.py ir faktinę serverio komandą arba tarnybos konfigūraciją. Jei sąmoningai naudojate gamybos nustatymų modulį, testuokite būtent tą modulį aiškiai, o ne testuokite plėtros failą ir manykite, kad rezultatas bus perkeltas.

Ar turėtumėte generuoti naują SECRET_KEY, ar atkurti senąjį?

Naujam vietiniam projektui: sugeneruoti naują saugią reikšmę yra pagrįsta. Python standartinis secrets modulis yra sukurtas kriptografiškai stipriam atsitiktinumui. Vienas portatyvus komandos pavyzdys:

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

Python dokumentacija apibūdina secrets kaip modulį, skirtą generuoti saugius atsitiktinius dydžius, tinkamus slaptažodžiams, autentifikavimo žetonams ir susijusiems slaptažodžiams. Žiūrėkite oficialią Python secrets dokumentaciją.

Esamai gamybos aplinkos programai, kuri anksčiau veikė: pirmiausia pabandykite atkurti tą pačią numatytąją slaptažodžio reikšmę iš savo slaptažodžių saugyklos arba diegimo konfigūracijos. Django naudoja SECRET_KEY kriptografiniam pasirašymui ir kelioms funkcijoms, įskaitant tam tikras sesijų ir pranešimų konfigūracijas bei slaptažodžio atstatymo žetonus. Netikėtas rakto pakeitimas gali sugadinti pasirašytus duomenis. Jei senasis raktas nebuvo pažeistas ir gedimas yra tik aplinkos įterpimo klaida, jo atkūrimas paprastai leidžia išvengti nereikalingo rotavimo.

Jei senasis raktas buvo atskleistas: jį pakeiskite (rotuokite). Django 6.1 palaiko SECRET_KEY_FALLBACKS planuotam rotavimui, leidžiantį laikinai priimti senus raktus, kol nauji parašai naudoja naują raktą. Pašalinkite atsarginius raktus, kai jų perėjimo laikotarpis baigsis. Elgsena ir kompromisai yra dokumentuoti oficialioje SECRET_KEY_FALLBACKS nuorodoje.

Koks yra greičiausias saugus sprendimas vietinei plėtrai?

Jei tik bandote paleisti vienkartinį vietinį projektą, galite į aktyvų nustatymų failą įrašyti sugeneruotą tik plėtrai skirtą reikšmę, kad patvirtintumėte diagnozę:

SECRET_KEY = "replace-this-with-a-random-development-only-value"

Tada vėl paleiskite Django. Jei klaida dingsta, patvirtinote, kad tuščias nustatymas buvo kliūtis. Nekopijuokite gamybos slaptažodžio į kūrėjo nešiojamąjį kompiuterį tik tam, kad vietinis nustatymas būtų patogesnis, ir nelaikykite kodo lygyje įrašytos plėtros reikšmės savo gamybos dizainu.

Ar aplinkos kintamasis tikrai pasiekia Django procesą?

Tai yra svarbiausia patikra, kai jūsų nustatymų faile jau yra SECRET_KEY = os.environ["SECRET_KEY"] arba panaši užklausa. Kintamasis turi egzistuoti to proceso, kuris importuoja Django nustatymus, aplinkoje. Nustatymas viename terminale automatiškai nepatalpina jo į jau veikiančią tarnybą, konteinerį, proceso valdiklį, CI darbą ar atskirą shell.

Patikrinkite buvimą nepaisant paties slaptažodžio:

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

Jei tai atspausdina False, pataisykite aplinkos įterpimą tam procesui. Greitam vietiniam shell testui naudokite savo shell sintaksę, tada paleiskite Django iš to paties shell. Pavyzdžiui:

# macOS / Linux shell
export SECRET_KEY='your-generated-local-secret'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'your-generated-local-secret'
python manage.py runserver

Gamybai naudokite slaptažodžių/konfigūracijos mechanizmą, kurį teikia jūsų prieglobos platforma arba proceso valdiklis, o ne įterpkite reikšmę į komandą, kuri gali būti išsaugota shell istorijoje.

Kodėl SECRET_KEY pridėjimas į .env failą neišsprendė Django klaidos?

.env failas yra tik failas, kol kažkas neįkelia jo turinio į proceso aplinką arba jūsų nustatymų kodas jo neperskaito. Oficialus Django pavyzdys skaito os.environ; Django nereikalauja ir nedokumentuoja integruoto automatinio .env įkėlimo žingsnio. Jei jūsų projektas remiasi dotenv biblioteka, framework wrapperiu, konteinerio konfigūracija arba diegimo platforma, kad įkeltų tą failą, atskirai patikrinkite tą komponentą ir įsitikinkite, kad jis veikia prieš tai, kai settings.py perskaito SECRET_KEY.

Naudingas veiksmas yra paleisti aukščiau minėtą loginį aplinkos patikrinimą iš to paties konteinerio, tarnybos paskyros, shell arba vykdymo etapo, kuriame įvyksta klaida. Jei jis atspausdina False, vien settings.py turinio derinimas neišspręs proceso lygmens konfigūracijos problemos.

Ką daryti, jei klaida pasirodo tik Docker, CI, collectstatic, WSGI arba ASGI?

Tai paprastai reiškia, kad kitas procesas arba vykdymo etapas įkelia projektą su kita aplinka arba nustatymų moduliu. Klaida gali pasirodyti collectstatic, migracijų, testų, CI patikros, programų serverio paleidimo arba fono proceso metu, net jei runserver veikia jūsų nešiojamajame kompiuteryje.

Nemanykite, kad slaptažodis, prieinamas vykdymo metu, taip pat yra prieinamas vaizdo kūrimo arba CI žingsnio metu. Atvirkščiai, nemanykite, kad interaktyviame shell eksportuotas kintamasis yra matomas sistemos tarnybai. Patikrinkite šiuos du faktus nepavykusioje aplinkoje:

• Koks DJANGO_SETTINGS_MODULE arba --settings reikšmė yra naudojama?
• Ar tas tikslus procesas turi netuščią SECRET_KEY aplinkos kintamąjį prieš Django importuojant nustatymus?

Konkretus būdas įterpti slaptažodį priklauso nuo Docker, jūsų CI teikėjo, jūsų hosto arba proceso valdiklio. Naudokite oficialų tos platformos slaptažodžių valdymo mechanizmą. Django pusės reikalavimas lieka tas pats: pasirinkta nustatymų konfigūracija turi pateikti netuščią slaptažodį vykdymo metu.

Kaip patikrinti pataisymą neatskleidžiant rakto?

Pirmiausia, nespausdinkite tikrojo gamybos rakto į žurnalus tik tam, kad įrodytumėte, jog jis egzistuoja. Patikrinkite buvimą loginiu patikrinimu, tada leiskite Django įkelti konfigūraciją:

python manage.py check

Gamybos konfigūracijai Django rekomenduoja paleisti diegimo patikras prieš gamybos nustatymų failą:

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

Pakeiskite modulio kelią į savo tikrąjį gamybos nustatymų modulį. Oficialus diegimo kontrolinis sąrašas konkrečiai rekomenduoja check --deploy ir įspėja, kad jis turėtų būti paleistas prieš gamybos nustatymus.

Galiausiai, paleiskite iš naujo tikrąjį programos procesą. Kintamasis, pridėtas po to, kai tarnyba jau buvo paleista, paprastai neturės įtakos tam jau veikiančiam procesui. Jei paleistas iš naujo procesas praeina Django patikras ir nebekelia išimties, konfigūracijos problema yra išspręsta.

Kurių pataisymų turėtumėte vengti?

• Nenustatykite SECRET_KEY = "" arba nenaudokite tuščios numatytosios reikšmės. Tai atkartoja sąlygą, kurią Django atmeta.
• Negeneruokite naujo rakto kiekvieno programos paleidimo metu. Keičiamas raktas gali sugadinti pasirašytus duomenis ir sukelti nenuoseklų elgesį tarp kelių darbuotojų (workers).
• Nekopijuokite slaptažodžio iš pamokos arba kito projekto. Django reikalauja unikalios, nenuspėjamos reikšmės, o vieša reikšmė panaikina slaptažodžio prasmę.
• Neįtraukite gamybos rakto į Git. Django diegimo kontrolinis sąrašas aiškiai pataria laikyti jį už šaltinio kodo valdymo sistemos ribų.
• Nespausdinkite pilno rakto į CI arba gamybos žurnalus. Tikrinkite tik tai, ar jis yra, nebent turite kontroliuojamą slaptažodžių audito procedūrą.
• Nemanykite, kad .env failas yra įkeltas vien todėl, kad jis egzistuoja. Patvirtinkite įkėlimo mechanizmą ir faktinę proceso aplinką.

Praktinis sprendimų kelias

Galutinis kontrolinis sąrašas

• Patvirtinkite tikslų nustatymų modulį, kurį Django įkelia.
• Patvirtinkite, kad SECRET_KEY išsprendžiamas į netuščią reikšmę toje aplinkoje.
• Naudokite unikalią, nenuspėjamą reikšmę; nepakartokite viešo arba pamokos rakto.
• Laikykite gamybos raktą už šaltinio kodo valdymo sistemos ribų.
• Jei naudojate aplinkos kintamuosius, įsitikinkite, kad kintamasis pasiekia kiekvieną procesą, kuris importuoja Django nustatymus.
• Jei naudojate .env darbo eigą, patikrinkite įkeltuvą, o ne manykite, kad Django automatiškai perskaito failą.
• Atkurkite senąjį gamybos raktą, jei problema yra atsitiktinis konfigūracijos praradimas; rotuokite tik tada, kai tai numatyta arba būtina.
• Paleiskite python manage.py check, o gamybai paleiskite check --deploy prieš gamybos nustatymų modulį.
• Paleiskite iš naujo tikrąją tarnybą pakeitus jos aplinką.

Svarbiausia yra tai, kad ši išimtis neprašo konkrečios magiškos eilutės. Ji sako, kad aktyvūs Django nustatymai neturi tinkamo slaptažodžio. Pataisykite tos konfigūracijos šaltinį, išsaugokite numatytąjį gamybos raktą, kai tai tinkama, ir patikrinkite rezultatą toje pačioje proceso aplinkoje, kurioje iš pradžių įvyko klaida.