
Fail appsettings.json dalam projek ASP.NET Core memang direka supaya mudah dicapai dan senang dibaca. Sebab itulah ramai pembangun—termasuk yang sudah berpengalaman—sering tergoda untuk menyumbat semua tetapan di dalamnya ketika mahu cepat menguji ciri baharu: kata laluan pangkalan data, kunci API gerbang pembayaran, kata laluan SMTP, hinggalah token perkhidmatan pihak ketiga.
Masalahnya bermula apabila fail itu masuk ke dalam commit Git bersama perubahan kod lain. Ramai beranggapan tidak mengapa selagi repositori bersifat peribadi (private). Hakikatnya, sebaik sahaja sesuatu secret berada dalam sejarah Git, ia sudah tersalin pada setiap mesin pembangun yang pernah melakukan git clone, sistem CI/CD, dan pelayan sandaran. Sebarang kunci yang pernah dikongsi dalam sejarah kod patut dianggap telah terdedah.
Asingkan konfigurasi umum dan secret
Langkah paling praktikal ialah memisahkan dengan tegas antara tetapan aplikasi yang boleh diketahui umum dengan maklumat rahsia yang memberi akses kepada data atau perkhidmatan berbayar.
Tetapan seperti tahap log (Logging:LogLevel), AllowedHosts, nama aplikasi, tempoh cache, atau URL titik akhir awam tidak ada masalah untuk kekal di dalam appsettings.json dan disimpan dalam Git. Sebaliknya, maklumat sensitif mesti datang daripada sumber luar yang tidak dikomit. Dokumentasi Microsoft juga menegaskan bahawa kata laluan dan kunci API tidak sepatutnya disimpan dalam kod sumber atau fail konfigurasi biasa.
Untuk pembangunan lokal di komputer sendiri, gunakan User Secrets yang sudah terbina dalam .NET SDK. Alat ini menyimpan nilai rahsia di luar folder projek (di bawah profil pengguna sistem operasi), jadi ia tidak akan tersentuh oleh Git:
dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Host=localhost;Database=app_dev;Username=dev;Password=rahsia_lokal"
dotnet user-secrets set "PaymentGateway:SecretKey" "sk_test_contoh_sahaja"
Apabila aplikasi dijalankan dalam persekitaran Development, WebApplication.CreateBuilder(args) akan memuatkan nilai daripada User Secrets secara automatik dan menindih nilai kosong yang ada dalam appsettings.json. Untuk pasukan yang turut menggunakan .env bagi skrip Docker atau perkhidmatan sampingan, pastikan .env disenaraikan dalam .gitignore sejak hari pertama projek dimulakan, dan sediakan fail templat seperti appsettings.Example.json atau .env.example dengan nilai kosong atau penanda jelas untuk panduan pembangun baharu.
Pengurusan di pelayan produksi
Di pelayan produksi—sama ada aplikasi berjalan di belakang Nginx sebagai servis systemd di Linux mahupun di dalam kontena Docker—jangan muat naik fail appsettings.Production.json yang penuh dengan kata laluan secara manual ke dalam folder kod. Sebaliknya, suntikkan nilai sensitif melalui pemboleh ubah persekitaran (environment variables) atau pengurus rahsia (secret manager).
ASP.NET Core memetakan pemboleh ubah persekitaran secara hierarki menggunakan tanda garis bawah berganda (__). Contohnya, untuk menindih ConnectionStrings:DefaultConnection, anda hanya perlu menetapkan pemboleh ubah persekitaran berikut pada servis atau fail konfigurasi pelayan yang dilindungi keizinan failnya:
ASPNETCORE_ENVIRONMENT=Production
ConnectionStrings__DefaultConnection=Host=10.0.0.12;Database=app_prod;Username=appuser;Password=kata_laluan_kuat
PaymentGateway__SecretKey=sk_live_contoh_sahaja
Susunan ini juga menyelesaikan tabiat buruk menampal nilai produksi ke dalam sembang kumpulan WhatsApp atau Slack semata-mata untuk “cuba sekejap di komputer sendiri”. Jika pembangun baharu tidak boleh menjalankan projek di mesin lokal tanpa menggunakan kunci API produksi yang sensitif, itu petanda aliran pembangunan lokal perlu diasingkan dengan lebih baik menggunakan persekitaran sandbox atau pangkalan data ujian.
Apa yang perlu dibuat jika sudah terlanjur commit
Kesilapan tetap boleh berlaku, terutama ketika mengejar tarikh akhir. Jika anda tersedar ada secret sudah masuk ke dalam commit dan telah ditolak (push) ke pelayan Git, memadam baris tersebut dalam commit baharu tidak menyelesaikan masalah—nilai lama itu masih boleh dilihat melalui git log -p.
Urutan tindakan yang betul ialah:
- Putar (rotate) kunci atau kata laluan tersebut serta-merta di penyedia asal (pangkalan data, Cloudflare, gerbang pembayaran, atau penyedia e-mel) dan kemas kini aplikasi produksi dengan nilai baharu.
- Semak log akses penyedia untuk memastikan kunci lama tidak disalahgunakan sepanjang tempoh ia terdedah.
- Bersihkan sejarah Git jika perlu bersama koordinasi pasukan (menggunakan alat seperti
git filter-repo), kerana penulisan semula sejarah memerlukan ahli pasukan lain melakukan clone semula atau reset cawangan masing-masing.
Memutar kunci sentiasa lebih mendesak daripada mencantikkan sejarah Git. Untuk mengelakkan kejadian berulang, letakkan pemeriksaan automatik seperti gitleaks dalam pre-commit hook atau saluran CI, dan semasa code review, jangan hanya mencari kata kunci seperti Password atau ApiKey. Sering kali maklumat sensitif tersembunyi di dalam rentetan sambungan (connection string), URL webhook, atau fail contoh yang lupa dibersihkan.