Kanesh
GitHub ★ Star

Operasional

Backup dan upgrade

Kenali data persisten dan kunci enkripsi yang harus disimpan, lalu build ulang dan jalankan Kanesh dengan penyimpanan yang sama.

Setelah membaca panduan ini, kamu akan tahu data dan secret yang harus disimpan sebelum mengganti image aplikasi, serta jaminan upgrade yang belum diverifikasi.

1. Kenali data persisten

Pada setup Docker di README, volume kanesh-data dipasang di /data. SQLite memakai DATA_DIR/kanesh.db kecuali ditimpa oleh SQLITE_PATH. Pada contoh Docker, lokasinya /data/kanesh.db; API development tanpa konfigurasi memakai api/.data/kanesh.db.

Simpan volume /data atau database SQLite yang dikonfigurasi. Untuk PostgreSQL atau MySQL, backup database eksternal beserta direktori data persisten yang digunakan. Upload file/image berupa blob database, jadi ekspor record tidak menggantikan backup database.

Simpan SETTINGS_ENCRYPTION_KEY bersama backup. Kunci ini mengenkripsi secret yang disimpan melalui Studio, seperti password SMTP, dan didahulukan dari alias SECRET. Tanpa keduanya, Studio tidak bisa menyimpan pengaturan secret. Mengganti kunci berarti memasukkan ulang seluruh secret tersimpan.

Note: Ekspor CSV/JSON tidak menyertakan upload biner dan link relasi, serta berupa pembacaan berpaginasi, bukan backup transaksional.

2. Salin isi volume Docker

README memakai docker cp untuk mengambil file dari container bernama. Untuk instalasi tersebut, perintah ini menyalin direktori yang dipasang dari kanesh-data ke direktori backup lokal:

docker cp kanesh:/data ./kanesh-data-backup

Ini contoh penyalinan direktori, bukan prosedur snapshot SQLite aktif yang terdokumentasi. Sumber yang diizinkan tidak menetapkan jaminan konsistensi untuk penyalinan database aktif atau menyediakan perintah backup database eksternal.

3. Ganti image aplikasi

Preview saat ini belum memiliki image atau rilis yang dipublikasikan. Build ulang API dan Studio bersama-sama dari root source Kanesh:

docker build --tag kanesh:local-review .

Untuk instalasi yang memakai image publik saat tersedia nanti, pull image penggantinya sebelum restart. Untuk image hasil build saat ini, jalankan ulang aplikasi dengan database dan direktori data yang sama. Perintah run di README memakai kembali volume bernama:

docker run --rm --name kanesh --publish 127.0.0.1:8080:8080 --volume kanesh-data:/data kanesh:local-review

Gunakan perintah run ini setelah container sebelumnya berhenti. Pertahankan konfigurasi database eksternal dan kunci enkripsi jika instalasimu memakainya.

4. Periksa kompatibilitas instalasi lama

Instalasi lama harus mengganti nama environment key yang sebelumnya memakai prefiks produk menjadi nama tanpa prefiks sebelum restart, sambil mempertahankan database dan direktori data yang sama. README menyebut HOST, PORT, DATA_DIR, DATABASE_DRIVER, DATABASE_URL, SQLITE_PATH, BOOTSTRAP_TOKEN, COOKIE_SECURE, MCP_ENABLED, dan SHUTDOWN_TIMEOUT. Studio development memakai API_URL; produksi memakai origin yang sama.

Selesaikan field kustom bernama created_at atau updated_at sebelum upgrade ke kontrak timestamp sistem. Skema versi 2 mempertahankan timestamp lama yang tidak diketahui sebagai null. Format respons REST lama tanpa envelope sudah berubah seperti dijelaskan di REST API; perbarui client dan build ulang API/Studio bersama-sama.

Note: Downgrade tidak didukung. Backup volume data dan database sebelum setiap upgrade agar kamu bisa memulihkan versi sebelumnya.

Pemecahan masalah

  • Secret tersimpan harus dimasukkan ulang: periksa apakah nilai asli SETTINGS_ENCRYPTION_KEY atau SECRET yang aktif tetap dipertahankan.
  • Instalasi lama masih memakai nama environment lama: ganti nama key berprefiks produk sebelum restart dan pertahankan path penyimpanannya.
  • Client mengharapkan respons REST tanpa envelope: perbarui untuk envelope data/meta atau error/meta.
  • Ekspor record tidak berisi file upload: ekspor berisi ID file, bukan blob database; simpan backup database.

Langkah berikutnya

Traktir kopi