Laravel yapılandırma yedeklerini APP_KEY’ler arasında taşınabilir hale getirmek için şifreleme yapma

Son güncelleme: 13 Haziran 2026 08:33

Bir Laravel paketi geliştirdiniz. Bu paket, bir uygulamanın yapılandırmasını – .env dosyası ve veritabanında şifrelenmiş olarak saklanan ayarları – tek bir şifre korumalı ZIP dosyası olarak yedeklemeyi sağlayacak. Bu paketin en büyük avantajı taşınabilirlik: A sunucusundaki bir yedeği B sunucusuna geri yükleyebilirsiniz, hatta iki sunucunun farklı APP_KEY değerleri olsa bile. Ancak, geri yükleme sırasında anahtarı değiştiren bir test yazdığınızda, bu test başarısız oluyor. Veritabanı ayarları bozulmuş bir şekilde geri geliyor.

<p>Hatanın şifrelemede değil, orada unuttuğum bir önbellekte olduğunu fark ettim. Bugün <a href="https://github.com/cleaniquecoders/laravel-config-backup" target="_blank" rel="noopener noreferrer">laravel-config-backup</a> paketinin 1.1.0 sürümünü yayınladım ve bu taşınabilirlik düzeltmesi öne çıkan özellik oldu. Şimdi bunu anlatmak istiyorum, çünkü alınan ders bu paketten çok daha geniş bir yelpazeye yayılıyor.</p>

<h2>
    <a name="why-appkey-portability-is-even-a-thing" href="#why-appkey-portability-is-even-a-thing"> 
    </a>
    Neden APP_KEY taşınabilirliği önemli
</h2>

<p>Laravel, verileri <code>APP_KEY</code> ile şifreler. Şifrelenmiş Eloquent cast’leri, imzalanmış çerezler, oturumlar - bunların hepsi bu değerden faydalanır. Eğer bir tabloyu <code>mysqldump</code> ile şifrelenmiş sütunlarla dump edip başka bir sunucuya yüklemeyi denerseniz, her şifrelenmiş sütun artık, yeni anahtarın çözemeyeceği bir ciphertext olur. Tamamen bozuk veri elde edersiniz.</p>

<p>Paketin kullandığı yöntem, arşiv içeriğini <strong>şifresiz</strong> olarak saklamaktır. Veritabanını dışa aktardığımda, satırlar <em>cast’leri aracılığıyla</em> çıkar, böylece şifrelenmiş bir sütun ZIP dosyası içinde düz bir değer haline gelir (ZIP dosyası ise AES-256 şifreli bir şifreyle korunmuş halde saklanır, yani düz metin olarak kalmaz). İçe aktarma sırasında, her satır modelden geri yazılır; bu da her verinin, hedefte aktif olan <code>APP_KEY</code> ile yeniden şifreleneceği anlamına gelir.</p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>Server A (key A)              Archive (decrypted)         Server B (key B)

──────────────── ─────────────────── ────────────────
settings.payload ──decrypt──▶ “Portable” ──import──▶ settings.payload
(ciphertext A) (cast) (cast) (ciphertext B)

<p>Bunu, mobilya gönderiminde olduğu gibi düşünün: montajlı bir dolabı, sığmadığı bir kapıdan geçiremezsiniz; parçalarını düz paketleyerek taşırsınız ve varış noktasında mevcut vidalarla yeniden monte edersiniz.</p>

<h2>
    <a name="the-restore-sequence" href="#the-restore-sequence">
    </a>
    Geri Yükleme Sırası
</h2>

<p>Yeni bir <code>.env</code> dosyasıyla yapılan geri yükleme, <em>sipariş</em> konusunda dikkatli olmalıdır. Gerçek akış şu şekildedir:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">public</span> <span class="k">function</span> <span class="n">restore</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$absZipPath</span><span class="p">,</span> <span class="kt">string</span> <span class="nv">$password</span><span class="p">,</span> <span class="kt">array</span> <span class="nv">$sections</span><span class="p">,</span> <span class="kt">int</span><span class="o">|</span><span class="n">string</span><span class="o">|</span><span class="kc">null</span> <span class="nv">$userId</span> <span class="o">=</span> <span class="kc">null</span><span class="p">):</span> <span class="kt">array</span>

{
// 1. Şu anki yapılandırmanın güvenli bir anlık görüntüsünü alıyoruz.
$safety = $this->create(
ConfigBackupSection::values(),
$password,
‘Otomatik ön geri yükleme güvenlik yedeği’,
$userId,
isSafety: true,
);

<span class="nv">$zip</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">openArchive</span><span class="p">(</span><span class="nv">$absZipPath</span><span class="p">,</span> <span class="nv">$password</span><span class="p">);</span> <span class="c1">// şifreyi doğrular</span>
<span class="nv">$appKeyChanged</span> <span class="o">=</span> <span class="kc">false</span><span class="p">;</span>

<span class="c1">// 2. Önce .env dosyasını geri yükle. Eğer APP_KEY değişirse, aktif şifreleyici değiştirilmeli</span>
<span class="c1">//   böylece sonraki DB yeniden şifreleme işlemleri FİNAL anahtarını kullanır.</span>
<span class="k">if</span> <span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">wants</span><span class="p">(</span><span class="nv">$sections</span><span class="p">,</span> <span class="nc">ConfigBackupSection</span><span class="o">::</span><span class="no">ENV</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="cm">/* ... */</span><span class="p">)</span> <span class="p">{</span>
    <span class="nv">$oldKey</span> <span class="o">=</span> <span class="p">(</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1">'app.key'</span><span class="p">);</span>
    <span class="nc">File</span><span class="o">::</span><span class="nf">put</span><span class="p">(</span><span class="nf">base_path</span><span class="p">(</span><span class="s1">'.env'</span><span class="p">),</span> <span class="nv">$newEnv</span><span class="p">);</span>
    <span class="nv">$newKey</span> <span class="o">=</span> <span class="nc">Env</span><span class="o">::</span><span class="nf">parse</span><span class="p">(</span><span class="nv">$newEnv</span><span class="p">)[</span><span class="s1">'APP_KEY'</span><span class="p">]</span> <span class="o">??</span> <span class="nv">$oldKey</span><span class="p">;</span>

    <span class="k">if</span> <span class="p">(</span><span class="nv">$newKey</span> <span class="o">!==</span> <span class="s1">''</span> <span class="o">&amp;&amp;</span> <span class="nv">$newKey</span> <span class="o">!==</span> <span class="nv">$oldKey</span><span class="p">)</span> <span class="p">{</span>
        <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">useEncryptionKey</span><span class="p">(</span><span class="nv">$newKey</span><span class="p">);</span>
        <span class="nv">$appKeyChanged</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
    <span class="p">}</span>
<span class="p">}</span>

<span class="c1">// 3. DB ayarlarını geri yükle — şimdi aktif anahtar ile yeniden şifrelenmiş olarak.</span>
<span class="c1">// ...</span>

<span class="nc">ConfigRestored</span><span class="o">::</span><span class="nf">dispatch</span><span class="p">(</span><span class="nv">$restored</span><span class="p">,</span> <span class="nv">$databaseSummary</span><span class="p">,</span> <span class="nv">$appKeyChanged</span><span class="p">,</span> <span class="nv">$safety</span><span class="o">-&gt;</span><span class="n">uuid</span><span class="p">);</span>

<span class="k">return</span> <span class="p">[</span>
    <span class="s1">'safety_backup'</span>   <span class="o">=&gt;</span> <span class="nv">$safety</span><span class="o">-&gt;</span><span class="n">uuid</span><span class="p">,</span>
    <span class="s1">'restored'</span>        <span class="o">=&gt;</span> <span class="nv">$restored</span><span class="p">,</span>
    <span class="s1">'database'</span>        <span class="o">=&gt;</span> <span class="nv">$databaseSummary</span><span class="p">,</span>
    <span class="s1">'app_key_changed'</span> <span class="o">=&gt;</span> <span class="nv">$appKeyChanged</span><span class="p">,</span>
<span class="p">];</span>

}

<p><code>.env</code> dosyasını veritabanısından önce geri yükleme yapılmalı. Aksi takdirde, veritabanı eski anahtar ile yeniden şifrelenecek ve ardından anahtar değiştirilecektir; bu da tamamen tersine bir işlem olur.</p>

<h2>
    <a name="the-bug-a-warm-encrypter-cache" href="#the-bug-a-warm-encrypter-cache">
    </a>
    Hata: sıcak bir şifreleyici önbelleği
</h2>

<p>Peki test neden başarılı olmadı, sıralama doğru olmasına rağmen? Bakın 1. adıma: geri yükleme öncesi güvenlik anlık görüntüsü <strong>şifreli satırları okur</strong>. Şifreli verileri okumak, şifreleyiciyi çözer — ve <code>Crypt::getFacadeRoot()</code> bu örneği <em>önbelleğe alır</em>. 2. adımda <code>app.key</code> değiştirildiğinde, aslında kullanılan şifreleyici, <strong>eski</strong> anahtar ile önbelleklenmiş bir durumda kalıyordu. Dolayısıyla 3. adım, her şeyi ısrarla geçerli olmayan bir şifreleyici ile yeniden şifreledi. <code>.env</code> dosyasındaki anahtar B iken, disk üzerindeki baytlar hala A anahtarına göre şifrelenmişti.</p>

<p>Bu, bir önbellek hatasının klasik şeklidir: değiştirdiğiniz değer ile okunan değer, iki farklı yerden geliyor. <code>config(['app.key' =&gt; ...])</code> framework’ün yapılandırma deposunu günceller, ancak zaten çözülmüş olan <code>encrypter</code> singleton buna aldırmaz — kendi anahtarını tutuyor.</p>

<p>Çözüm, aktif bağlamayı değiştirmek ve ve çözümlenmiş facade örneğini temizlemektir; böylece cast’ler yeniden çözümlenir:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">protected</span> <span class="k">function</span> <span class="n">useEncryptionKey</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$appKey</span><span class="p">):</span> <span class="kt">void</span>

{
$key = $this->parseKey($appKey); // base64: ve decode edilmesi
$cipher = config(‘app.cipher’,‘AES-256-CBC’);

<span class="nc">Config</span><span class="o">::</span><span class="nf">set</span><span class="p">(</span><span class="s1">'app.key'</span><span class="p">,</span> <span class="nv">$appKey</span><span class="p">);</span>
<span class="nf">app</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">instance</span><span class="p">(</span><span class="s1>'encrypter'</span><span class="p">,</span> <span class="k">new</span> <span class="nc">Encrypter</span><span class="p">(</span><span class="nv">$key</span><span class="p">,</span> <span class="nv">$cipher</span><span class="p">));</span>
<span class="nc">Crypt</span><span class="o">::</span><span class="nf">clearResolvedInstance</span><span class="p">(</span><span class="s1>'encrypter'</span><span class="p">);</span> <span class="c1">// sonraki kullanımda yeniden çözülmesini zorlayın</span>

}

<p>O son satır, tüm çözümün özüdür. Bu satır olmadan, cast’lerin aldığı şifreleyici önbellekte eski olanıdır ve “taşınabilir” yedek durumu geçerli olmaktan çıkar.</p>

<h2>
    <a name="lock-the-test-around-the-actual-failure" href="#lock-the-test-around-the-actual-failure">
    </a>
    Testi Gerçek Başarısızlık Üzerine Kitle
</h2>

<p>Bu tür bir hata ile ilgili tehlikeli olan şey, sıradan bir testin geçmesidir. Testiniz, bir istekte geri yüklemeden sonraki değeri okuduğunda, sıcak bir şifreleyici ile her şey düzgün görünür. Hata, bir şeyin verileri <em>okuduğu</em> zaman, anahtar değişiminden önce gerçekleşir; bu da tam olarak üretim ortamındaki güvenlik anlık görüntüsünün yaptığı işlemdir.</p>

<p>Bu nedenle, regresyon testinin bu sıralamayı yeniden üretmesi gerekir: A anahtarı altında bir satır yazın, bir yedek alın, ardından B anahtarını taşıyan bir arşiv geri yükleyin ve diskteki baytların B altında çözülebilir ve A altında çözülemez olduğunu doğrulayın.</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nf">it</span><span class="p">(</span><span class="s1>'restore edildiği APP_KEY altında DB ayarlarını yeniden şifreler'</span><span class="p">,</span> <span class="k">function</span> <span class="p">()</span> <span class="p">{</span>
        <span class="c1">// Orijinal anahtar altında saklandı.</span>
        <span class="nc">Setting</span><span class="o">::</span><span class="nf">create</span><span class="p">([</span><span class="s1>'key'</span> <span class="o">=&gt;</span> <span class="s1>'smtp.password'</span><span class="p">,</span> <span class="s1>'value'</span> <span class="o">=&gt;</span> <span class="s1>'Portable'</span><span class="p">]);</span>

        <span class="nv">$path</span> <span class="o">=</span> <span class="nc">ConfigBackup</span><span class="o">::</span><span class="nf">backup</span><span class="p">([</span><span class="s1>'env'</span><span class="p">,</span> <span class="s1>'database'</span><span class="p">],</span> <span class="s1>'secret-pass'</span><span class="p">);</span>

        <span class="c1">// Arşiv, .env dosyasında farklı bir APP_KEY taşır.</span>
        <span class="nv">$result</span> <span class="o">=</span> <span class="nc">ConfigBackup</span><span class="o">::</span><span class="nf">restore</span><span class="p">(</span><span class="nv">$path</span><span class="p">,</span> <span class="s1>'secret-pass'</span><span class="p">,</span> <span class="p">[</span><span class="s1>'env'</span><span class="p">,</span> <span class="s1>'database'</span><span class="p">]);</span>

        <span class="nf">expect</span><span class="p">(</span><span class="nv">$result</span><span class="p">[</span><span class="s1>'app_key_changed'</span><span class="p">])</span><span class="o">-&gt;</span><span class="nf">toBeTrue</span><span class="p">();</span>

        <span class="c1">// Ham sütun, YENİ anahtar altında çözülebilir olmalı ve ESKİ anahtar altında başarısız olmalıdır.</span>
        <span class="nv">$raw</span> <span class="o">=</span> <span class="no">DB</span><span class="o">::</span><span class="nf">table</span><span class="p">(</span><span class="s1>'settings'</span><span class="p">)</span><span class="o">-&gt;</span><span class="nf">where</span><span class="p">(</span><span class="s1>'key'</span><span class="p">,</span> <span class="s1>'smtp.password'</span><span class="p">)</span><span class="o">-&gt;</span><span class="nf">value</span><span class="p">(</span><span class="s1>'value'</span><span class="p">);</span>
        <span class="nf">expect</span><span class="p">(</span><span class="nc">Crypt</span><span class="o">::</span><span class="nf">decryptString</span><span class="p">(</span><span class="nv">$raw</span><span class="p">))</span><span class="o">-&gt;</span><span class="nf">toBe</span><span class="p">(</span><span class="s1>'Portable'</span><span class="p">);</span> <span class="c1">// yeni anahtar aktiftir</span>
    <span class="p">});</span>

<p>Bir gün <code>clearResolvedInstance</code> satırını silerseniz, bu test başarısız olur. Amaç bu — test, tam davranışı sabitler; herhangi bir tesadüfi başarıyı değil.</p>

<h2>
    <a name="the-other-110-changes-briefly" href="#the-other-110-changes-briefly">
    </a>
    1.1.0 Sürümündeki Diğer Değişiklikler
</h2>

<p>Aynı sürümde, <em>sızdırma</em> ve <em>UI’ye güvenmeme</em> konularında önemli olan, iki özellik daha eklendi:</p>

<p><strong>Güvenli parola istemi.</strong> <code>config-backup:create</code>, komut satırında <code>--password</code> istemekteydi. Bu, doğrudan shell geçmişine ve süreç listesine sızar — <code>ps</code> erişimi olan herkes yedekleme parolanızı görebilir. Şimdi <code>--password</code> kullandığınızda, gizli ve onaylanan bir girişle istemektedir. Bayrak, TTY olmadığında zamanlanmış çalıştırmalar için hala çalışmaktadır.</p>

<p><strong>Route sınırında yetkilendirme.</strong> Paketin Livewire admin ekranı, yapılandırılabilir bir kapının arkasındadır. Kapı kontrolü Livewire bileşeni içinde yer alıyordu, bu, diğer bir şekilde rota üzerine gidecek birisinin bu durumu değiştirebilmesi için uygun değildir. Bu nedenle yetkilendirme artık merkezi bir yöntem ile tek bir yerde yapılmakta ve rota middleware olarak zorunlu hale gelmektedir:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">public</span> <span class="k">function</span> <span class="n">authorizes</span><span class="p">():</span> <span class="kt">bool</span>

{
$gate = $this->gate();

<span class="k">return</span> <span class="nv">$gate</span> <span class="o">===</span> <span class="kc">null</span> <span class="o">||</span> <span class="nc">Gate</span><span class="o">::</span><span class="nf">allows</span><span class="p">(</span><span class="nv">$gate</span><span class="p">);</span>

}

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// routes/web.php — güvenlik önlemleri</span>

if ($gate = config(<span class=”s1>’config-backup.gate’)) {
$middleware[] = <span class=”s1>’can:’.$gate;
}

<p>Tekbir gerçek kaynak (<code>authorizes()</code>), iki katmanda zorunlu hale getirildi. Pest paketi, dört durumu kapsamaktadır: kapı yapılandırılmadığında (izin ver), misafir (red), yanlış kullanıcı (red), doğru kullanıcı (izin ver). Ucuz testler ve onları bir paragrafın asla yapamayacağı kadar iyi belgeliyorlar.</p>

<h2>
    <a name="takeaway" href="#takeaway">
    </a>
    Sonuç
</h2>

<p>Taşınabilirlik düzeltmesi, aslında <strong><code>config()</code> ve çözümlenmiş bir singleton'ın aynı kaynak olmadığını</strong> hatırlatıyor. Runtime'da framework yapılandırmasını değiştirdiğinizde ve zaten çözümlenmiş hizmetlerin bunu fark etmesini bekliyorsanız, muhtemelen yeniden bağlantı kurmalı ve çözümlenmiş örneği temizlemelisiniz — şifreleyici, DB bağlantıları, önbellek depoları gibi tümü önbellek tutar. Böyle bir hata ile karşılaştığınızda, ortaya çıktığı sıralamayı yeniden üreten testi yazmayı unutmayın, kolay versiyonunu değil.</p>

<p>Paket ile ilgili daha fazla bilgi için: <a href="https://github.com/cleaniquecoders/laravel-config-backup" target="_blank" rel="noopener noreferrer">cleaniquecoders/laravel-config-backup</a>.</p>

Kaynak: Orijinal Makale

Laravel yapılandırma yedeklerini APP_KEY’ler arasında taşınabilir hale getirmek için şifreleme yapma

Sanal Medya

Son Eklenenler

Yapay Zeka Ajanları ile Elektrikli Araç Şarj İstasyonları Nasıl Korunur?

Acil: Yabancıların Fable 5 ve Mythos 5 Erişimi Askıya Alındı

Andrew Yang’a Göre Yaşam Maliyetlerini Düşürmek Büyük Fırsat

ABD’nin Talimatıyla Claude Fable 5 Offline, Anthropic Ne Açıklıyor?

Anthropic’in güvenlik uyarıları, en güçlü AI projesini durdurdu

Özelliğinizin testlerinin göremediği hatayı yakalayan bir test

Siber güvenlik, yapay zeka ve savunma sanayiinden; finans ve sinema dünyasına uzanan geniş bir yelpaze. Teknomers; teknoloji, strateji ve yazılım dünyasını sade bir dille sizlerle buluşturuyor.

Kurumsal

Kategoriler

Populer