الترقية من 1.x إلى 2.0

كان SnapOtter 1.x يخزّن كل شيء في ملف SQLite واحد ويعمل كحاوية واحدة. يستخدم SnapOtter 2.0 قاعدتي بيانات PostgreSQL وRedis. يرشدك هذا الدليل عبر نقل تثبيت 1.x إلى 2.0 دون فقدان البيانات.

النسخة المختصرة: أعِد استخدام وحدة تخزين /data الموجودة لديك، وسيستورد 2.0 قاعدة بيانات 1.x تلقائياً عند أول إقلاع. ينتقل مستخدموك وملفاتك المحفوظة وإعداداتك ومفاتيح API وخطوط الأنابيب. لا يُعدَّل قط قاعدة البيانات القديمة، لذا يمكنك دائماً التراجع.

ملاحظة لمستخدمي 1.x

وثق كثير منكم بـ SnapOtter منذ اليوم الأول، وقد صاغت ملاحظاتكم هذا الإصدار. يغيّر 2.0 الكثير في الخلفية، ووُجد هذا الدليل كي لا تكلّفكم النقلة أي شيء تهتمون به. تنتقل حساباتكم وملفاتكم وإعداداتكم ومفاتيح API وخطوط الأنابيب، ولا تُمسّ قاعدة بياناتكم القديمة قط. شكراً لكم على الترقية معنا.

قبل أن تبدأ: انسخ وحدة تخزين /data بالكامل احتياطياً

افعل هذا أولاً، في كل مرة. انسخ وحدة تخزين /data بالكامل احتياطياً، وليس ملف snapotter.db فقط.

إليك سبب أهمية ذلك. يُشغّل 1.x قاعدة SQLite في وضع WAL، لذا فإن حاوية 1.x المتوقفة تترك عادةً معظم بياناتها المُلتزَم بها في snapotter.db-wal بجانب snapotter.db شبه فارغ. نسخ snapotter.db فقط يلتقط قاعدة بيانات فارغة ويفقد كل شيء بصمت. تحمل وحدة التخزين snapotter.db وsnapotter.db-wal وsnapotter.db-shm ودليل files/ معاً، ويجب أن تنتقل كمجموعة.

# Adjust the volume name to match yours (see "Check your volume name" below).
docker run --rm -v SnapOtter-data:/data -v "$PWD":/backup \
  alpine tar czf /backup/snapotter-1x-data.tgz -C /data .

قم بالترقية إلى 1.17.2 أولاً

قم بترقية تثبيت 1.x الخاص بك إلى أحدث إصدار 1.x (1.17.2) قبل الانتقال إلى 2.0. يتيح ذلك لـ 1.x تشغيل ترحيلات المخطط النهائية الخاصة به، بحيث يستورد 2.0 من مخطط معروف ومكتمل. الترقية من 1.x أقدم مباشرة إلى 2.0 غير مدعومة.

تحقق من اسم وحدة التخزين الخاصة بك

يرى المستورد بياناتك فقط إذا كانت حزمة 2.0 تركّب وحدة التخزين نفسها التي استخدمها تثبيت 1.x الخاص بك. أسماء وحدات تخزين Docker حساسة لحالة الأحرف، وكانت مقتطفات README الأقدم تستخدم snapotter-data بأحرف صغيرة بينما تستخدم ملفات Compose SnapOtter-data. أكّد أيهما لديك:

docker volume ls | grep -i snapotter

استخدم ذلك الاسم بالضبط في تكوين 2.0 الخاص بك.

المسار A: حاوية واحدة (الأسرع)

إذا كنت تُشغّل SnapOtter بحاوية docker run واحدة، فاستمر في ذلك. يُقلع 2.0 قاعدة PostgreSQL وRedis مضمّنتين داخل الحاوية عندما لا تضبط DATABASE_URL أو REDIS_URL، ويكتشف ويستورد /data/snapotter.db تلقائياً عند أول إقلاع.

docker run -d --name snapotter -p 1349:1349 \
  -v SnapOtter-data:/data \
  snapotter/snapotter:latest

راقب السجلات بحثاً عن سطر مثل:

Imported 1.x SQLite database: {"tables":{"users":2,"teams":1,...},"blobs":{"present":1,"missing":0}}

هذا كل شيء. سجّل الدخول ببيانات اعتمادك الموجودة.

المسار B: Compose (موصى به للإنتاج)

تُشغّل حزمة Compose الخاصة بـ 2.0 ثلاث خدمات (التطبيق، Postgres، Redis). أعِد استخدام وحدة تخزين /data الخاصة بـ 1.x لخدمة التطبيق. يكتشف التطبيق /data/snapotter.db تلقائياً ويستورده إلى Postgres عند أول إقلاع.

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - SnapOtter-data:/data          # your existing 1.x volume
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://:snapotter@redis:6379
    # ...

إذا كنت تفضّل الإشارة إلى قاعدة البيانات القديمة بشكل صريح، اضبط SQLITE_MIGRATE_PATH=/data/snapotter.db. المسار الصريح يفوز دائماً على الاكتشاف التلقائي.

معاينة الاستيراد أولاً (اختياري)

لرؤية ما سيُستورَد بالضبط دون كتابة أي شيء، شغّل تشغيلاً تجريبياً مقابل ملف قاعدة البيانات الخاص بك:

pnpm --filter @snapotter/api migrate:sqlite -- /path/to/snapotter.db --dry-run

يطبع عدد الصفوف لكل جدول، وكم ملفاً من ملفات المكتبة المحفوظة عثر عليها على القرص، وأي حالات مهام سيُطبّعها. لا يحتاج إلى تشغيل Postgres.

ما ينتقل وما لا ينتقل

ما ينتقل:

• المستخدمون والقدرة على تسجيل الدخول. تجزئات كلمات المرور غير متغيرة، لذا يعمل اسم المستخدم وكلمة المرور نفسهما.
• الفرق والإعدادات (بما في ذلك هوية نسختك) والأدوار ومفاتيح API (تستمر في العمل) وخطوط الأنابيب المحفوظة.
• سجلات تاريخ المهام.
• مكتبة ملفاتك المحفوظة، السجلات والملفات الفعلية معاً، لأن /data/files محفوظ على وحدة التخزين.

ما لا ينتقل:

• جلسات تسجيل الدخول. يسجّل الجميع الدخول مرة واحدة بعد الترقية. بيانات الاعتماد غير متغيرة، لذا فهو تسجيل دخول واحد فقط، لا أكثر.
• ملفات الإدخال والإخراج لمهام المعالجة القديمة. كانت تلك موجودة في مساحة عمل مؤقتة وقد اختفت عن قصد. تبقى سجلات تاريخ المهام.
• أعلام موافقة التحليلات لكل مستخدم من 1.x، التي ليس لها مكافئ في 2.0 (تحليلات 2.0 إعداد على مستوى النسخة).

إيقاف الاستيراد

إذا كنت تريد عمداً قاعدة بيانات جديدة رغم وجود snapotter.db على وحدة التخزين، اضبط SQLITE_MIGRATE_PATH=off.

إذا كان لديك بالفعل بيانات في نسخة 2.0

يعمل المستورد فقط في قاعدة بيانات فارغة. إذا بدأت 2.0 من جديد (بإنشاء بيانات)، ثم ركّبت لاحقاً snapotter.db قديماً، فسيكتشفه 2.0 لكنه لن يستورده، لأن دمج مجموعتي بيانات قد يتعارض على المعرّفات. سترى تحذيراً في السجلات. لاستيراد بيانات 1.x تحتاج نسخة فارغة:

• إذا كانت نسخة 2.0 تحتوي المسؤول الافتراضي فقط (لم تستخدمها فعلاً)، أوقف الحزمة، وأزل وحدة تخزين Postgres (SnapOtter-pgdata)، وأقلع مجدداً مع وجود /data القديم. سيُستورَد بشكل نظيف. يمسح هذا بيانات Postgres المؤقتة فقط، لا قاعدة بيانات 1.x الخاصة بك.
• إذا كانت نسخة 2.0 تحتوي بيانات حقيقية تريد الاحتفاظ بها، فلا يمكن دمج مجموعتي البيانات تلقائياً. صدّر ما تحتاجه واستورد بيانات 1.x إلى نشر جديد منفصل.

التراجع

لا تُعدّل الترقية قط snapotter.db الخاص بـ 1.x أو تحذفه. إذا احتجت العودة إلى 1.x، أعِد نشر صورة 1.x مقابل وحدة التخزين نفسها. أي شيء أنشأته في 2.0 بعد الترقية موجود في Postgres ولن يكون في قاعدة بيانات 1.x، لذا تراجع بسرعة إن كنت ستفعل.