متطلبات خادم Potato لقسم تقنية المعلومات

Potato تطبيق ويب مستضاف ذاتيًا لدراسات التعليق التوضيحي. تخدم عملية Potato واحدة دراسة واحدة، وتحتفظ بكل تعليق توضيحي في ملفات وقواعد بيانات SQLite داخل مجلد الدراسة، وتحتاج إلى وكيل عكسي أمام العملية لتوفير HTTPS. لا يرسل التثبيت الافتراضي شيئًا إلى خدمات خارجية، ولا تغادر البيانات الخادم إلا عبر الميزات التي يشغّلها إعداد الدراسة.

كُتبت هذه الصفحة لمن يديرون الخوادم في جامعة أو مستشفى أو شركة. يستطيع باحث يريد استضافة دراسته أن يرسل الصفحة كما هي، مع مجلد المشروع والإجابات المسرودة في القسم التالي. وتغطي صفحة انشر دراسة Potato على الإنترنت المسارات التي يستطيع الباحث سلوكها دون فريق تقنية معلومات.

معلومات من فريق البحث

يرسل فريق البحث مجلد المشروع، الذي يصدّره مصمم الدراسات بصفة Download project (.zip). يحتوي المجلد على config.yaml، وهو إعداد الدراسة، وعلى ملفات البيانات التي يذكرها الإعداد. وإلى جانب المجلد، يجيب فريق البحث عن هذه الأسئلة:

• كم معلّقًا يشارك، وهل يسجّل المعلّقون الدخول بحسابات مؤسسية أم بأسماء مستخدمين يسردها الباحث؟
• متى تبدأ الدراسة ومتى تنتهي؟
• هل تحتوي العناصر أو الإجابات على معلومات شخصية أو حساسة، وبأي موافقة أخلاقية تُجرى الدراسة؟
• هل يستخدم الإعداد ميزات ذكاء اصطناعي ترسل العناصر إلى مزوّد نماذج؟ تدل كتل مثل ai_support وchat_support وsolo_mode في config.yaml على ميزات كهذه.

البرمجيات

Potato تطبيق ويب بلغة Python مبني على Flask. أبسط تثبيت هو صورة Docker المنشورة، ghcr.io/davidjurgens/potato، المبنية لمعماريتي linux/amd64 وlinux/arm64. حجم الصورة نحو 900 MB، وتشغّل Python 3.11 تحت gunicorn بصفة المستخدم غير المميز potato (المعرّف uid 1000)، وتستمع على المنفذ 7860. يُركَّب مجلد المشروع في /app:

docker run -d --name potato-study --restart unless-stopped \
  -p 127.0.0.1:8000:7860 \
  -v /srv/potato/my-study:/app \
  -e POTATO_SECRET_KEY="$(openssl rand -hex 32)" \
  ghcr.io/davidjurgens/potato:2.14.0

ينشر الأمر الدراسة على المنفذ 8000 من واجهة loopback الخاصة بالمضيف فقط. ويكون الوكيل العكسي عندئذ الطريق الوحيد إلى الداخل. يتبع الوسم latest فرع التطوير في Potato، وينبغي للدراسة أن تثبّت وسم إصدار. ولّد POTATO_SECRET_KEY مرة واحدة واحتفظ بالقيمة، لأن مفتاحًا جديدًا عند كل بدء يُخرج كل معلّق من حسابه عند كل إعادة تشغيل. ترفض الحاوية البدء عندما لا يكون /app قابلًا للكتابة بالمعرّف uid 1000. شغّل الحاوية بالخيار --user "$(id -u):$(id -g)" أو سلّم المجلد إلى uid 1000. تغطي صفحة تشغيل Potato في Docker وسوم الصورة ومتغيرات البيئة.

من دون Docker، يُثبَّت Potato من PyPI على Python 3.9 أو أحدث بالأمر pip install potato-annotation. أضف الحزمة الإضافية hosting للنسخ الاحتياطية وتسجيل الدخول الموحّد، والحزمة الإضافية saml لتسجيل الدخول عبر SAML، وهي تُبنى مقابل libxmlsec1 في النظام. يشغّل potato start config.yaml خادم تطوير يغلق الاتصال بعد كل استجابة. وللمعلّقين العاملين عبر الإنترنت، شغّل Potato تحت gunicorn كما تعرض صفحة إعداد الإنتاج، أو ضع وكيلًا عكسيًا أمام potato start.

العملية وعدد العمال

يحتفظ Potato بمجموعة العناصر وطابور الإسناد وحالة كل معلّق في ذاكرة عملية واحدة. وسيحتفظ عامل gunicorn ثانٍ أو نسخة ثانية بنسخة منفصلة من الثلاثة، ويوزّع عناصر أسندتها العملية الأولى بالفعل، ويكتب فوق حفظ العملية الأولى. ولذلك ترفض الصورة البدء مع GUNICORN_WORKERS أكبر من 1. وللحصول على تزامن أكبر، ارفع GUNICORN_THREADS من القيمة الافتراضية 8. تضع وثائق Docker الخاصة بـPotato ثمانية خيوط عند العشرات من المعلّقين المتزامنين الذين تضمهم الدراسة المعتادة. شغّل عدة دراسات بوصفها عدة حاويات، لكل حاوية مجلد ومنفذ منفصلان.

حجم الخادم

تنمو الذاكرة بنمو عدد العناصر. تضع قياسات Potato كل عنصر عند 0.9 إلى 1.4 KB في الذاكرة، واستخدم الخادم على مجموعة البيانات المرجعية في Potato نحو 365 MB. يختار potato deploy، وهو أمر Potato السحابي نفسه، جهازًا بمعالج افتراضي أو اثنين وذاكرة 2 GB على معظم المضيفات، وهذا حجم بداية معقول.

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

الوصول إلى الشبكة وHTTPS

اعرض Potato عبر وكيل عكسي مثل nginx أو Apache أو Caddy. يحتفظ الوكيل بشهادة TLS ويمرّر الطلبات إلى منفذ الحاوية. لا يلزم فتح سوى المنفذ 443، والمنفذ 80 لإعادة التوجيه وتجديد الشهادة، على الإنترنت. تعرض صفحة الوكيل العكسي كيف تُقدَّم Potato تحت مسار URL مثل https://host.example.edu/my-study/، عبر POTATO_PROXY_FIX=1 مع الترويسة X-Forwarded-Prefix أو عبر POTATO_URL_PREFIX. تبثّ عارضات الوكلاء الحية بأحداث يرسلها الخادم. أوقف التخزين المؤقت في الوكيل على الموضع /api/ إذا كانت الدراسة تستخدم تلك العارضات.

لا يحتاج GET /health إلى مصادقة، ويعيد {"status": "ok"} متى صار الخادم جاهزًا، والحالة 503 ما دام الخادم يحمّل البيانات. وجّه موازن حمل أو فحص مراقبة إلى هذه النقطة.

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

• تستدعي ميزات الذكاء الاصطناعي نقطة نهاية النموذج التي يسميها الإعداد، ما لم تكن نقطة النهاية خادم نماذج محليًا مثل Ollama.
• تكتب النسخ الاحتياطية في مجموعة بيانات Hugging Face أو حاوية S3 التي يسميها الإعداد.
• يتصل تسجيل الدخول الموحّد بمزوّد الهوية.
• تقرأ مصادر البيانات البعيدة من الحاوية أو قاعدة البيانات التي يسميها الإعداد.
• العناصر التي تربط بالوسائط عبر URL تجعل متصفح المعلّق يجلب الوسائط من ذلك العنوان.

الملفات التي يكتبها Potato

يكتب Potato كل شيء في مجلد الدراسة:

ولذلك يضم دليل واحد الدراسة كلها. output_annotation_dir إعداد في config.yaml، ويضبط مصمم الدراسات قيمته على output.

النسخ الاحتياطية

يغطي نسخ احتياطي ليلي لمجلد المشروع ملفات التعليقات التوضيحية وقائمة الحسابات. انسخ ملفي SQLite بأمر النسخ الاحتياطي في SQLite نفسه لا كملفين عاديين، لأن نسخ ملف قاعدة بيانات في وضع WAL قد ينتج نسخة تالفة أو ينقصها ما كُتب حديثًا:

sqlite3 /srv/potato/my-study/project.sqlite ".backup /backups/my-study/project.sqlite"

ينسخ النسخ الاحتياطي المدمج في Potato مخرجات التعليقات ولقطات قواعد البيانات إلى حاوية متوافقة مع S3 أو إلى مجموعة بيانات خاصة على Hugging Face كل خمس دقائق. عند البدء، يستعيد النسخ الاحتياطي من الحاوية حين يكون القرص فارغًا، ولا يكتب أبدًا فوق تعليقات موجودة على القرص. ترسل الكتلة أدناه النسخة إلى مخزن كائنات جامعي. أضف الكتلة إلى config.yaml الخاص بالدراسة، واضبط POTATO_S3_ACCESS_KEY_ID وPOTATO_S3_SECRET_ACCESS_KEY في بيئة الحاوية:

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: s3
      bucket: research-backups
      prefix: potato/my-study
      endpoint_url: https://s3.example.edu

تتضمن الصورة المنشورة عملاء النسخ الاحتياطي. ويحتاج التثبيت بـpip إلى الحزمة الإضافية hosting.

خيارات تسجيل الدخول

يدعم Potato عدة طرق لتسجيل دخول المعلّقين، تُضبط في config.yaml:

تُجزَّأ كلمات المرور بـPBKDF2-SHA256 بمئة ألف تكرار وملح لكل مستخدم. وتُعاد تهيئة كلمة المرور المنسية عبر رابط يُستخدم مرة واحدة يعرضه Potato على الشاشة، ولا يرسل Potato بريدًا إلكترونيًا. خلف وكيل ينهي TLS، اضبط sp_base_url لـSAML على العنوان العام، وإلا فشلت استجابة مزوّد الهوية في فحص الوجهة لدى Potato. وتعطي صفحات SSO وOAuth وإدارة كلمات المرور وتكامل التعهيد الجماعي الإعداد الخاص بكل طريقة.

وصول المسؤول

تعرض لوحة المسؤول على /admin التقدم والاتفاق وإجابات كل معلّق، وتنزّل النتائج. تُفتح اللوحة بمفتاح مسؤول. اضبط المفتاح عبر POTATO_ADMIN_API_KEY، أو دع Potato يولّد admin_api_key.txt في مجلد المشروع عند أول استخدام، ومرّر المفتاح إلى الباحث عبر قناة تثق بها مؤسستك. أبقِ debug: false في config.yaml على أي خادم، لأن وضع التصحيح يفتح صفحات المسؤول دون مفتاح للطلبات التي تبدو محلية، وقد يجعل وكيل على الجهاز نفسه كل طلب يبدو محليًا.

حماية البيانات

Potato مستضاف ذاتيًا، ولذلك تبقى التعليقات التوضيحية وقائمة الحسابات والعناصر على الخادم الذي تديره. لا يحتوي Potato على تحليلات ولا على تقارير استخدام، ولا يجري التثبيت الافتراضي أي اتصالات صادرة. لا تغادر البيانات الخادم إلا عبر الميزات المسرودة تحت الوصول إلى الشبكة وHTTPS، ويجب أن يشغّل إعداد الدراسة كلًّا منها ويسمّي وجهة له.

قارن ثلاث نقاط بالموافقة الأخلاقية للدراسة:

• تسمّي ملفات التعليقات التوضيحية كل معلّق باسم المستخدم، ولذلك فإن أسماء المستخدمين التي هي عناوين بريد إلكتروني تضع عناوين البريد في البيانات.
• يمكن أن تجمع صفحات الاستبيان في دراسة معلومات شخصية، وتوجد الإجابات في ملفات كل معلّق نفسها.
• عندما يرسل الإعداد العناصر إلى مزوّد نماذج مستضاف، تغادر العناصر الخادم بموجب شروط ذلك المزوّد.

عندما تنتهي الدراسة، ينزّل فريق البحث النتائج من لوحة المسؤول. اتفق مع الفريق على المدة التي تُحفظ فيها نسخة الخادم، واحذف مجلد المشروع وأي حاوية نسخ احتياطي بعد ذلك التاريخ.

قراءات إضافية

• تشغيل Potato في Docker، لوسوم الصورة ومتغيرات البيئة وملكية الملفات
• إعداد الإنتاج، لـgunicorn وnginx وApache وDocker Compose
• الوكيل العكسي، لتقديم Potato تحت مسار URL
• النشر المعزول والعمل دون اتصال، للشبكات التي لا وصول صادر فيها
• انشر دراسة Potato على الإنترنت، وهي جانب الباحث من العملية نفسها