Laravel Yapılandırma Yedeklerinizi APP_KEY Değişikliklerinde Taşınabilir Hale Getirin

Laravel projelerinde çalışan geliştiriciler, APP_KEY değeriyle ilişkili kritik bir sorunla karşılaşabilir: sunucular arası yedek aktarımında veri kaybı ve bozulmalar. Bu sorun, yapılandırma dosyalarının ve veritabanındaki şifrelenmiş verilerin farklı anahtarlara sahip sunucularda doğru şekilde restore edilememesinden kaynaklanıyor. Neyse ki, Laravel’in esnek mimarisiyle bu engel aşılabilir.

APP_KEY Değişikliklerinde Veri Taşınabilirliği Neden Önemli?

Laravel, APP_KEY değerini kullanarak veritabanındaki şifrelenmiş sütunları, oturumları ve çerezleri yönetir. Eğer bir veritabanı yedeğini farklı bir sunucuya aktarırsanız ve bu sunucunun farklı bir APP_KEY’si varsa, şifrelenmiş veriler artık çözülemez hale gelir. Bu durum, projelerinizi başka sunuculara taşırken ciddi bir engel oluşturur.

Bu soruna çözüm olarak geliştirilen laravel-config-backup paketi, verilerinizi şifrelenmeden önce arşiv haline getiriyor. Yedekleme işlemi sırasında veritabanındaki şifrelenmiş sütunlar, Laravel’in model cast’leri aracılığıyla düz metin olarak arşivleniyor. Restore işlemi sırasında ise yeni sunucunun APP_KEY’si kullanılarak veriler yeniden şifreleniyor. Bu sayede, verileriniz farklı sunucular arasında güvenle taşınabiliyor.

Düşünün ki, bir dolabı başka bir eve taşırken montajlı şekilde götürmeye çalışmak yerine, parçalarını söküp yeniden monte ediyorsunuz. Aynı mantık burada da geçerli: verilerinizi yeniden yapılandırılabilir hale getirerek farklı ortamlara uyum sağlıyorsunuz.

Restore İşleminin Adım Adım Akışı

Bir restore işlemi sırasında .env dosyasının ve veritabanı ayarlarının doğru şekilde aktarılması kritik önem taşıyor. İşte paketin sunduğu restore sırası:

1. Güvenlik yedeği oluşturulması: Restore işlemine başlamadan önce mevcut yapılandırma dosyalarının bir yedeği alınıyor. Bu, olası bir hata durumunda geri dönüşü sağlıyor.

1. .env dosyasının restore edilmesi: Eğer APP_KEY değeri değişecekse, bu adımda yeni anahtar uygulanıyor. Böylece, veritabanındaki veriler yeni anahtarla yeniden şifrelenebiliyor.

1. Veritabanı ayarlarının restore edilmesi: Veritabanındaki şifrelenmiş veriler, yeni APP_KEY kullanılarak yeniden şifreleniyor ve restore ediliyor.

public function restore(string $absZipPath, string $password, array $sections, int|string|null $userId = null): array
{
    // 1. Güvenlik yedeği oluştur
    $safety = $this->create(
        ConfigBackupSection::values(),
        $password,
        'Otomatik ön-restor yedeği',
        $userId,
        isSafety: true,
    );

    $zip = $this->openArchive($absZipPath, $password); // Doğrulama
    $appKeyChanged = false;

    // 2. Önce .env dosyasını restore et
    if ($this->wants($sections, ConfigBackupSection::ENV) && /* ... */) {
        $oldKey = (string) config('app.key');
        File::put(base_path('.env'), $newEnv);
        $newKey = Env::parse($newEnv)['APP_KEY'] ?? $oldKey;

        if ($newKey !== '' && $newKey !== $oldKey) {
            $this->useEncryptionKey($newKey);
            $appKeyChanged = true;
        }
    }

    // 3. Veritabanı ayarlarını restore et (yeni anahtarla şifrelenmiş)
    // ...

    return [
        'safety_backup' => $safety->uuid,
        'restored' => $restored,
        'database' => $databaseSummary,
        'app_key_changed' => $appKeyChanged,
    ];
}

Bu sıralama, APP_KEY değişikliklerinde verilerin doğru şekilde restore edilmesini sağlıyor. Aksi takdirde, veriler eski anahtarla şifrelenmeye devam eder ve yeni sunucuda kullanılamaz hale gelir.

Kritik Hata: Sıcak Şifreleyici Önbelleği

Restorasyon işlemi sırasında karşılaşılan bir hata, Laravel’in encrypter önbelleğinden kaynaklanıyordu. Güvenlik yedeği oluşturulurken, veritabanındaki şifrelenmiş veriler okunuyor ve bu işlem sırasında Crypt::getFacadeRoot() tarafından bir önbelleğe alınıyordu. Daha sonra APP_KEY değiştirildiğinde, modeller hala eski anahtarı kullanmaya devam ediyordu. Bu da restore edilen verilerin bozulmasına neden oldu.

Bu tip hatalar, önbellekleme sistemlerinin dikkatli yönetilmesini gerektiriyor. Özellikle, önbelleğe alınmış bir bileşenin anahtar değişikliklerinden etkilenmemesi için özen gösterilmeli.

Çözüm: Önbelleği Temizleyin ve Anahtarı Güncelleyin

Sorunun çözümü, hem APP_KEY’yi güncellemek hem de önbellekteki encrypter örneğini temizlemekten geçiyor. Aşağıdaki kod parçası, bu işlemi gerçekleştiriyor:

protected function useEncryptionKey(string $appKey): void
{
    $key = $this->parseKey($appKey); // base64: ve base64 kodunu kaldır
    $cipher = config('app.cipher', 'AES-256-CBC');
    Config::set('app.key', $appKey);
    app()->instance('encrypter', new Encrypter($key, $cipher));
    Crypt::clearResolvedInstance('encrypter'); // Yeniden çözümlemeye zorla
}

Bu çözüm sayesinde, modeller her zaman en güncel APP_KEY’yi kullanarak verileri şifreleyip çözebiliyor. Önbelleğin temizlenmesi, eski anahtarın kullanılmasını engelliyor ve veri bütünlüğünü koruyor.

Testlerin Kritik Önemi

Bu tip hataların tespit edilmesi, doğru test senaryolarıyla mümkün. Basit bir restore testi, hatayı ortaya çıkarmayabilir. Özellikle, güvenlik yedeği oluşturulması gibi adımların restore işleminden önce gerçekleştiği durumlarda, hatanın tespiti zorlaşır.

Aşağıdaki test, bu senaryoyu doğruluyor:

it('re-encrypts database settings under the restored APP_KEY', function () {
    // Orijinal anahtarla sakla
    Setting::create(['key' => 'smtp.password', 'value' => 'Portable']);
    $path = ConfigBackup::backup(['env', 'database'], 'secret-pass');

    // Farklı APP_KEY içeren arşivden restore et
    $result = ConfigBackup::restore($path, 'secret-pass', ['env', 'database']);
    expect($result['app_key_changed'])->toBeTrue();

    // Yeni anahtarla çözülebilmeli, eski anahtarla çözülememeli
    $raw = DB::table('settings')->where('key', 'smtp.password')->value('value');
    expect(Crypt::decryptString($raw))->toBe('Portable');

Bu test, restore işleminin doğru şekilde çalıştığını ve verilerin yeni APP_KEY ile uyumlu olduğunu doğruluyor. Unutmayın, önbellekleme sistemlerinin dikkatli yönetilmesi ve doğru test senaryolarının kullanılması, Laravel projelerindeki veri bütünlüğünü korumanın anahtarlarından biri.

Verilerinizin farklı sunucular arasında güvenle taşınabilmesi, projelerinizin esnekliğini ve ölçeklenebilirliğini artırıyor. Bu teknikleri kullanarak, Laravel projelerinizdeki yapılandırma ve veritabanı yedeklerini kolayca yönetebilirsiniz.