الحوسبة السحابية وبدائلها الأدلة التقنية

Appwrite على سيرفرك: Backend متكامل للويب والجوال

كيف تثبت Appwrite على سيرفرك وتبني عليه جدولاً بصلاحيات على مستوى الصف ومجلد ملفات ودالة وتطبيق ويب، وما الثمن الحقيقي بالذاكرة والقرص.

Appwrite على سيرفرك: Backend متكامل للويب والجوال

في دليل Supabase على سيرفرك بنينا الخلفية Backend فوق PostgreSQL، فكانت الصلاحيات Permissions سياسات SQL داخل قاعدة البيانات Database، والتطبيق يكلم جداول علائقية. لكن ليس كل فريق يريد أن يكتب SQL، فكثير من فرق الجوال تأتي من Firebase وتعودت على نموذج آخر: مستندات أو صفوف تحمل كل منها صلاحياتها، ولوحة إدارة يضبط منها المطور كل شيء بالضغط، ودوال Functions بلغات متعددة، ومكتبات SDK رسمية ل Flutter وAndroid وiOS وReact Native. وهذا بالضبط ما يقدمه Appwrite، وهو منصة مفتوحة المصدر بترخيص BSD-3-Clause تجمع المصادقة Authentication وقاعدة البيانات والتخزين Storage والدوال والتحديث الفوري Realtime والرسائل Messaging خلف واجهة واحدة، وتستضيفها على سيرفرك.

وفكرة ال Backend as a Service، ولماذا تصبح قواعد الوصول هي الحارس الوحيد عندما يكلم التطبيق قاعدة البيانات مباشرة، شرحناها في ما هو Backend as a Service؟ فلن نعيدها. وسوف نناقش في هذا الدليل ما يلي:

  • ما الذي يعمل داخل Appwrite 2.7.4 المستضاف، ولماذا يحتاج ثماني عشرة خدمة.
  • التثبيت بالمعالج Installer من المتصفح، وما فعلناه عندما ظهر أن ال Images تحتاج أكثر من 11 جيجابايت.
  • خطأ في الإعداد جعل كل طلب ينتظر ثلاث ثوان، وكيف وجدنا سببه.
  • المشروع Project ومفتاح API، ثم جدول بصلاحيات على مستوى الصف Row-Level Permissions، ومجلد تخزين Bucket، ودالة بلغة Node.js.
  • تطبيق ويب صغير بمستخدمين في متصفحين، ونرى بالمخرجات ماذا يستطيع كل منهما أن يرى، والثغرة التي يفتحها العميل لنفسه.
  • لماذا فشلت الدالة في أول تشغيل، وزمن التشغيل البارد Cold Start.
  • الذاكرة والقرص والزمن كما قسناها، وما تحتاجه قبل الإنتاج، ومتى يناسبك Appwrite.

ما الذي يعمل داخل Appwrite المستضاف؟

Appwrite مكتوب أساساً بلغة PHP فوق خادم Swoole، وأغلب خدماته تخرج من Docker Image واحدة هي appwrite/appwrite، لكن بأوامر تشغيل مختلفة: واحدة للواجهة البرمجية API، وأخرى للتحديث الفوري عبر WebSocket، وثالثة للعمال Workers الذين ينفذون الطوابير Queues، وأخرى للجدولة والصيانة. وبجانبها قاعدة البيانات وRedis وبوابة traefik ولوحة الإدارة Console ومنفذ الدوال Executor وخدمات مساعدة. والصورة التالية تبين ما يولده المعالج في الإصدار 2.7.4:

تطبيق الويب وتطبيق الجوال يتصلان ببوابة traefik على 127.0.0.1:28880، والبوابة توجه إلى خدمات من Docker Image واحدة appwrite/appwrite:2.7.4 هي appwrite وappwrite-realtime وappwrite-worker وtask-scheduler وtask-maintenance وmqtt وtask-interval، وتحتها postgresql وredis، وبجانبها appwrite-console بحجم 4.5 جيجابايت، والدوال عبر executor وorchestrator، وخدمات مساعدة clickhouse وappwrite-geo وappwrite-exiftool
ملف Compose واحد بثماني عشرة خدمة، شغلنا منها أربع عشرة

والجدول التالي يجمع الخدمات كما ظهرت في ملف docker-compose.yml الذي ولده المعالج:

الخدمةما تفعلهDocker Image
traefikالبوابة: توجه الطلبات إلى الواجهة البرمجية واللوحة والتحديث الفوريtraefik:3.6
appwrite وappwrite-realtime وappwrite-worker والمهام task-*الواجهة البرمجية وWebSocket والطوابير والجدولة والصيانةappwrite/appwrite:2.7.4
appwrite-consoleلوحة الإدارةappwrite/new:1.2.181-self-hosted
postgresql وredisالبيانات، والطوابير والذاكرة المؤقتة Cacheappwrite/postgres:0.1.0 وredis:7.4.7-alpine
openruntimes-executor وorchestratorبناء الدوال وتشغيلها في Containers مستقلةopenruntimes/executor:1.3.7
clickhouseإحصاءات الاستخدام وسجلات التنفيذclickhouse/clickhouse-server:26.4.3-alpine
appwrite-geo وappwrite-exiftoolمعرفة الدولة من عنوان IP، وقراءة بيانات الملفات المرفوعةappwrite/geo:0.3.2 وghcr.io/appwrite/exiftool:0.1.1
appwrite-browser وappwrite-embedding وappwrite-autogravityلقطات المواقع، والمتجهات للذكاء الاصطناعي، وقص الصور الذكيلم نشغلها في المختبر

ولاحظ أن قاعدة البيانات الافتراضية في سلسلة 2.x أصبحت PostgreSQL، والمعالج يسمح باختيار MariaDB أو MongoDB بدلها، كما في توثيق قواعد البيانات، وهذا يختلف عن الإصدارات القديمة التي كانت MariaDB فيها الخيار الوحيد. والمهم أن التطبيق لا يكلم PostgreSQL مباشرة كما في Supabase، وإنما يكلم واجهة Appwrite، وهي التي تقرر الصلاحيات، فقاعدة البيانات هنا تفصيل داخلي لا تكتب فيه سياسات.

ما الذي تحتاجه قبل أن تبدأ؟

  • سيرفر Linux مع Docker Engine وDocker Compose 2: كما في تثبيت Docker على Ubuntu، والتوثيق يطلب معالجين 2 CPU وذاكرة 4 جيجابايت وذاكرة تبديل Swap بحجم 2 جيجابايت كحد أدنى.
  • القرص: هنا المفاجأة الأولى، فقد بلغ مجموع ال Images التي شغلناها قرابة 11.6 جيجابايت، منها 4.5 جيجابايت للوحة الإدارة وحدها و1.75 جيجابايت لخدمة geo، وهذا دون الخدمات الثلاث التي لم نشغلها، فاحسب 20 جيجابايت على الأقل للنظام قبل بياناتك.
  • نطاق وشهادة HTTPS: فالدوال والتطبيقات تحتاج عنواناً حقيقياً، كما سوف نرى في خطأ الدالة.
  • سيرفر بريد SMTP: لرسائل التحقق واستعادة كلمة المرور Password Reset ودعوات الفريق.

التثبيت بالمعالج من المتصفح

الطريقة الرسمية في دليل التثبيت هي أن تشغل Docker Image نفسها بنقطة دخول اسمها install، فتفتح معالجاً على المنفذ 20080 يسألك أربعة أسئلة ثم يولد الملفات ويشغل كل شيء. وقد غيرنا في الأمر الرسمي أمرين: ربط المنفذ على 127.0.0.1 فقط، والتشغيل في الخلفية:

mkdir appwrite
docker run -d --name sc5-aw-install -p 127.0.0.1:20080:20080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD/appwrite:/usr/src/code/appwrite:rw" \
  --entrypoint install appwrite/appwrite:2.7.4
docker logs sc5-aw-install

والمخرج سوف يكون كما يلي، وقد حذفنا القيمة السرية:

Starting Appwrite installation...
Starting web installer...
Press Ctrl+C to cancel installation
Installer secret: <redacted>
Open your browser at: http://localhost:20080/?secret=<redacted>

ولاحظ أمرين قبل أن تكمل. الأول أن المعالج يحمل مقبس Docker، أي /var/run/docker.sock، وهذا يعني أنه يملك صلاحية كاملة على السيرفر، وهذا مقبول لأداة تثبيت رسمية تعمل دقائق ثم تحذف، لكنه سبب إضافي لألا يصل أحد إلى المنفذ 20080 غيرك، ولهذا يحمل الرابط سراً، وإذا كنت على سيرفر بعيد فافتح المنفذ عبر نفق SSH بدل فتحه في جدار الحماية Firewall. والثاني أن تنزيل Docker Image المعالج نفسها، وحجمها 791 ميجابايت، استغرق عندنا 165 ثانية.

والصورة التالية من الخطوة الأولى، وفيها اسم السيرفر Hostname وقاعدة البيانات والإعدادات المتقدمة، ومنها المنافذ ونمط العمال Topology، وقد جعلنا منفذ HTTP هو 28880 بدل 80:

الخطوة الأولى من معالج تثبيت Appwrite بعنوان Setup your app وفيها حقل Hostname بالقيمة localhost وخيار Use HTTPS، واختيار قاعدة البيانات بين PostgreSQL وMariaDB وMongoDB، وفي الإعدادات المتقدمة اختيار Combined أو Separate للعمال ومنفذا HTTP وHTTPS
الخطوة الأولى: اسم السيرفر وقاعدة البيانات والمنافذ

والخطوة الثانية تولد مفتاحاً سرياً يستخدمه Appwrite لتشفير البيانات الحساسة داخل قاعدة البيانات، وهو المتغير _APP_OPENSSL_KEY_V1 في ملف .env، والمعالج يقول بوضوح إنك لن تراه مرة أخرى، فاحفظه في مدير كلمات المرور، والسبب أن ضياعه مع بقاء قاعدة البيانات يعني أن ما شفر به لا يمكن فكه. والخطوة الثالثة تنشئ حساب المدير، والرابعة تعرض المراجعة:

صفحة Review your setup في المعالج وفيها Hostname localhost وDatabase PostgreSQL وPublic API protocol HTTP وHTTP port 28880 وHTTPS port 28443 والبريد admin@example.com وSecret key Generated وزر Install
مراجعة الإعدادات قبل التثبيت

وعند الضغط على Install ولد المعالج ثلاثة ملفات في المجلد، هي docker-compose.yml و.env وملفا إعداد ClickHouse، ثم بدأ تشغيل الخدمات:

شاشة Installing Appwrite وفيها ثلاث خطوات مكتملة: Configuration files created وDocker Compose file generated وEnvironment variables configured، والخطوة الرابعة Starting Docker containers بالعداد 0/18
ثماني عشرة خدمة في الطريق

عندما لا يتسع القرص

عند هذه الشاشة توقفنا، فقد حسبنا الأحجام المضغوطة لل Images المطلوبة من Docker Hub، فكانت وحدها قرابة 2.8 جيجابايت مضغوطة، أي أضعاف ذلك بعد فك الضغط، والقرص في جهاز المختبر لا يتسع لها كلها. فأوقفنا المعالج بحذف ال Container الخاص به، وهذا يوقف عملية التنزيل التي يديرها، ثم فتحنا ملف Compose الذي ولده لنفهم ما الذي يعتمد على ماذا:

grep -nE '^  [a-z0-9-]+:$|^    image:|^    container_name' appwrite/docker-compose.yml

ووجدنا أن الخدمة الرئيسية appwrite تعتمد في depends_on على redis وpostgresql وثلاث خدمات مساعدة هي geo وautogravity وexiftool، وأن الخدمات browser وembedding لا يعتمد عليها شيء. فكتبنا ملف Override يربط البوابة على 127.0.0.1، ويشغل الخدمة الرئيسية دون الخدمات المساعدة، ثم شغلنا ما نحتاجه بالاسم:

# docker-compose.override.yml (first version)
services:
  traefik:
    ports: !override
      - 127.0.0.1:28880:80
  appwrite:
    depends_on: !override
      redis:
        condition: service_started
      postgresql:
        condition: service_healthy
docker compose -p sc5-aw up -d --no-deps postgresql redis appwrite appwrite-console appwrite-realtime \
  appwrite-worker appwrite-task-scheduler openruntimes-executor orchestrator appwrite-exiftool traefik
curl -s http://127.0.0.1:28880/v1/health/version
health after 126s
{"version":"2.7.4"}

ولاحظ ports: !override وdepends_on: !override، فبدونهما يدمج Compose القائمة الجديدة مع القديمة بدل أن يستبدلها، فيبقى المنفذ مفتوحاً على كل الواجهات. ولماذا 127.0.0.1؟ لأن Docker يفتح المنفذ المنشور على كل الواجهات ويتجاوز جدار الحماية UFW، كما شرحنا في تأمين خادم VPS.

كل طلب ينتظر ثلاث ثوان

عمل كل شيء، وسجلنا الدخول إلى اللوحة، لكن كل صفحة كانت بطيئة بشكل غريب، وعندما فتحنا سجل الخدمة الرئيسية وجدنا هذا السطر قبل كل طلب تقريباً:

docker logs appwrite --since 3m 2>&1 | grep -A6 'DNS Lookup'
DNS Lookup resolve timeout
http.request · 3.01s · 83a62027

  level              info
  http.method        GET
  http.uri           /v1/health/version
  http.response.code 200

حتى مسار الصحة الذي لا يفعل شيئاً أخذ 3.01 ثانية. وبالبحث في ملف .env عن العناوين الداخلية وجدنا السبب:

grep -nE 'http://|HOST=' appwrite/.env | head
62:_APP_GEO_ENDPOINT="http://appwrite-geo/v1"
69:_APP_DB_HOST="postgresql"
94:_APP_REDIS_HOST="redis"
158:_APP_EXECUTOR_HOST="http://exc1/v1"
161:_APP_JOBS_HOST="http://orchestrator:8080"
164:_APP_BROWSER_HOST="http://appwrite-browser:3000/v1"

فالخدمة الرئيسية تسأل خدمة geo مع كل طلب عن دولة العنوان IP، وعندما لا يوجد Container بهذا الاسم ينتظر البحث في DNS حتى المهلة ثم يكمل، فيبدو كل شيء يعمل لكن ببطء. وفي سجل الخدمة نفسها رسالة ثانية تقول Usage schema setup failed. Retrying، وسببها غياب ClickHouse. فنزلنا الخدمتين، واستغرق ذلك 354 ثانية، وأضفنا geo إلى الاعتماديات في ملف ال Override، ثم أعدنا إنشاء الخدمات:

docker compose -p sc5-aw up -d --no-deps appwrite-geo clickhouse
docker compose -p sc5-aw up -d --no-deps --force-recreate appwrite appwrite-worker appwrite-realtime
curl -s -o /dev/null -w "%{time_total}s %{http_code}\n" http://127.0.0.1:28880/v1/health/version
0.104662s 200

من 3.01 ثانية إلى 0.1 ثانية. والدرس أن ملف Compose الذي يولده المعالج ليس قائمة اقتراحات، فالخدمات المساعدة جزء من مسار الطلب، وإذا أردت أن تحذف شيئاً منها فاقرأ أولاً أين يستخدم، والطريقة الأسهل أن تبحث عن اسمه في ملف .env.

الخدمات تعمل: الحالة والذاكرة

docker ps --filter label=com.docker.compose.project=sc5-aw --format '{{.Names}}\t{{.Status}}'
docker stats --no-stream --format '{{.Name}}\t{{.MemUsage}}' $(docker ps -q --filter label=com.docker.compose.project=sc5-aw)
appwrite                 381.9MiB
appwrite-worker          89.55MiB
appwrite-realtime        69.8MiB
sc5-aw-clickhouse-1      1.243GiB
appwrite-geo             36.65MiB
appwrite-traefik         34.15MiB
appwrite-task-scheduler  146.8MiB
orchestrator             14.8MiB
exc1                     49.27MiB
appwrite-redis           10.62MiB
appwrite-postgresql      162.4MiB
appwrite-console         250.1MiB
appwrite-exiftool        359.4MiB
exc1-6aff79…-6aff7c…     30.8MiB

والمجموع قرابة 2.8 جيجابايت دون أي ضغط، منها 1.24 جيجابايت ل ClickHouse وحده، وهو للإحصاءات وليس لبياناتك، وهذا رقم يجب أن تضعه في حسابك عند اختيار حجم السيرفر، فالحد الأدنى الذي يذكره التوثيق، أي 4 جيجابايت، يترك لبياناتك ونموها مساحة قليلة. ولاحظ السطر الأخير، فهو Container الدالة الذي أنشأه المنفذ عند أول تنفيذ، ولا يظهر في ملف Compose أصلاً.

المؤسسة والمشروع ومفتاح API

عند أول دخول إلى اللوحة أنشأ Appwrite مؤسسة Organization اسمها Personal Projects، وطلب إنشاء أول مشروع. ويذكر دليل التثبيت أن النسخة المستضافة تسمح بمؤسسة واحدة فقط، ومن يسجل بعد ذلك لا يرى شيئاً حتى تدعوه، وأن المتغير _APP_CONSOLE_WHITELIST_ROOT مفعل افتراضياً فلا يسجل في اللوحة إلا أول مستخدم، وهذا إعداد آمن اتركه كما هو.

والمشروع في Appwrite هو الخلفية الكاملة لتطبيق واحد: مستخدموه وبياناته وملفاته ودواله، وأنشأنا مشروعاً اسمه todo-lab، ثم أنشأنا له مفتاح API بالصلاحيات Scopes التي يحتاجها سكربت الإعداد فقط، ثم سجلنا منصة ويب Web Platform باسم المضيف localhost، والسبب أن Appwrite يرفض طلبات المتصفح التي تأتي من أصل Origin غير مسجل في المشروع، وهذه حماية من مواقع أخرى تستخدم مشروعك، وفكرتها في شرح CORS وسياسة المصدر الواحد.

⚠️
مفتاح API يتجاوز كل صلاحيات المستخدمين، فمكانه السيرفر وسكربتات الإعداد والدوال فقط، ولا تضعه في تطبيق الجوال أو الويب أبداً، وأعطه أقل الصلاحيات التي يحتاجها، فمفتاح سكربت الإعداد مثلاً لا يحتاج صلاحية users.write إلا إذا كان سيستورد مستخدمين.

الجدول والتخزين والدالة من سكربت

تستطيع أن تنشئ كل ما يلي من اللوحة، لكن السكربت يتكرر بالنتيجة نفسها على سيرفر الإنتاج، وهذا ما تريده. والسكربت التالي يستخدم مكتبة السيرفر node-appwrite بالإصدار 32.0.0 ومفتاح API:

// Creates the server side of the todo app with an API key: a table with row security, a bucket and a function
import { Client, TablesDB, Storage, Functions, Permission, Role } from 'node-appwrite'
import { InputFile } from 'node-appwrite/file'
import { Runtime } from 'node-appwrite'

const client = new Client().setEndpoint(process.env.AW_ENDPOINT).setProject(process.env.AW_PROJECT).setKey(process.env.AW_KEY)
const db = new TablesDB(client), storage = new Storage(client), functions = new Functions(client)

// 1) a database and a table: any signed-in user may create rows; each row carries its own permissions
await db.create({ databaseId: 'todo', name: 'todo' })
await db.createTable({ databaseId: 'todo', tableId: 'todos', name: 'todos',
  permissions: [Permission.create(Role.users())], rowSecurity: true })
await db.createVarcharColumn({ databaseId: 'todo', tableId: 'todos', key: 'title', size: 200, required: true })
await db.createBooleanColumn({ databaseId: 'todo', tableId: 'todos', key: 'done', required: false, xdefault: false })
await db.createVarcharColumn({ databaseId: 'todo', tableId: 'todos', key: 'attachment', size: 36, required: false })
console.log('table todos: rowSecurity on, create for Role.users()')

// 2) a bucket: signed-in users upload, each file carries its own read permission
await storage.createBucket({ bucketId: 'attachments', name: 'attachments', permissions: [Permission.create(Role.users())],
  fileSecurity: true, maximumFileSize: 5 * 1024 * 1024, allowedFileExtensions: ['txt', 'png', 'jpg', 'pdf'] })
console.log('bucket attachments: fileSecurity on, 5 MB, txt/png/jpg/pdf')

// 3) a function any signed-in user may execute
await functions.create({ functionId: 'todo-stats', name: 'todo-stats', runtime: Runtime.Node22, execute: [Role.users()],
  entrypoint: 'src/main.js', commands: 'npm install', timeout: 15 })
const dep = await functions.createDeployment({ functionId: 'todo-stats', code: InputFile.fromPath('todo-stats.tar.gz', 'todo-stats.tar.gz'), activate: true })
console.log('function todo-stats: deployment', dep.$id, dep.status)
docker run --rm --network appwrite -e AW_ENDPOINT=http://appwrite/v1 -e AW_PROJECT=6aff799000122338169d -e AW_KEY=$AW_KEY \
  -v "$PWD/lab:/app" -w /app node:22-alpine sh -c 'tar czf todo-stats.tar.gz -C functions/todo-stats . && node setup.mjs'

وفي التشغيل الأول توقف السكربت في السطر الثاني بهذا الخطأ:

SyntaxError: The requested module 'node-appwrite' does not provide an export named 'InputFile'

والسبب أن الإصدارات الحديثة من المكتبة نقلت InputFile إلى مسار مستقل هو node-appwrite/file، وأغلب الأمثلة المنشورة على الإنترنت ما زالت تستورده من المسار الرئيسي، فإذا ظهر لك الخطأ نفسه فهذا هو الحل. وبعد التصحيح:

table todos: rowSecurity on, create for Role.users()
bucket attachments: fileSecurity on, 5 MB, txt/png/jpg/pdf
function todo-stats: deployment 6aff7aa314caa274b7d9 waiting

في الإعداد أعلاه لاحظ التالي:

  • الأسماء في Appwrite تغيرت منذ الإصدار 1.8، فما كان يسمى مجموعات Collections ومستندات Documents وخصائص Attributes أصبح جداول Tables وصفوفاً Rows وأعمدة Columns في واجهة اسمها TablesDB، والواجهة القديمة ما زالت موجودة، لكن الأمثلة الجديدة كلها بالأسماء الجديدة.
  • الجدول يعطي صلاحية الإنشاء create لكل مستخدم مسجل، ولا يعطي القراءة لأحد، ومع rowSecurity: true تأتي القراءة والتعديل والحذف من صلاحيات كل صف، وهذا قريب من قواعد Firebase التي تقارن request.auth.uid بمالك المستند.
  • مجلد التخزين بالنموذج نفسه، أي fileSecurity: true، مع حد للحجم وقائمة امتدادات، ولا تقم بترك قائمة الامتدادات فارغة في تطبيق يرفع فيه المستخدمون ملفات، والسبب أن الملف المرفوع قد يكون صفحة HTML تفتح من نطاقك.
  • الدالة يستطيع أي مستخدم مسجل أن ينفذها، والأمر npm install يعمل أثناء البناء Build داخل Container مؤقت.

المنفذ نزل ستة Docker Images لم نطلبها

بعد 28 ثانية أصبح النشر جاهزاً، وسجل البناء فيه تثبيت الحزم وحفظ ذاكرة البناء المؤقتة Build Cache:

[22:39:48] [open-runtimes] Build cache miss.
added 4 packages in 13s
[22:40:04] [open-runtimes] Build command execution finished.
[22:40:06] [open-runtimes] Build cache saved. (2482176 bytes)
[22:40:06] [open-runtimes] Build finished.
[22:40:16] [appwrite] Deployment finished.

لكن عندما نظرنا إلى قائمة ال Images وجدنا ما لم نتوقعه:

docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep openruntimes
openruntimes/executor:1.3.7 709MB
openruntimes/php:v5-8.0 356MB
openruntimes/ruby:v5-3.0 405MB
openruntimes/python:v5-3.9 678MB
openruntimes/static:v5-1 62.2MB
openruntimes/flutter:v5-3.29 1.96GB
openruntimes/node:v5-22 1.18GB
openruntimes/node:v5-16.0 332MB

فالمنفذ عند تشغيله ينزل Docker Image لكل بيئة تشغيل Runtime مذكورة في المتغير _APP_FUNCTIONS_RUNTIMES، وقيمته الافتراضية في الملف الذي ولده المعالج هي node-16.0,node-22,php-8.0,python-3.9,ruby-3.0، ومعها بيئتا المواقع Sites، فكان المجموع قرابة 5 جيجابايت ونحن لا نستخدم إلا Node.js 22. وتوثيق الدوال ينصح صراحة بأن تفعل البيئات التي تحتاجها فقط لتوفير القرص، فاجعل القيمة مثلاً _APP_FUNCTIONS_RUNTIMES=node-22 قبل التشغيل الأول، ولاحظ أن Node.js 16 منتهي الدعم أصلاً.

صلاحيات الجدول وصلاحيات الصف

قبل التطبيق لنفهم النموذج، فهو أهم ما في Appwrite. فلكل جدول قائمة صلاحيات، ولكل صف قائمة صلاحيات، والصلاحية نص مثل read("user:6aff…") يربط عملية بدور Role، والأدوار هي: any أي أي شخص حتى الزائر، وusers أي أي مستخدم مسجل، وuser:<id> مستخدم محدد، وteam:<id> فريق، وlabel:<name> مستخدمون يحملون وسماً، كما في توثيق الصلاحيات. والصورة التالية من تبويب Security للجدول بعد سكربت الإعداد:

تبويب Security لجدول todos في لوحة Appwrite وفيه قسم Permissions بدور All users ومعه CREATE فقط، وقسم Row level security (RLS) مفعل مع شرح أن المستخدم يصل إلى الصف إذا كانت له صلاحية الصف أو صلاحية الجدول، وأن الإنشاء يحتاج دائماً صلاحية الجدول
صلاحية الإنشاء على الجدول، والقراءة والتعديل من صلاحيات كل صف

ونص الشرح في اللوحة مهم: المستخدم يصل إلى الصف إذا كانت له صلاحية على الصف أو على الجدول، أي أن الصلاحيتين تجمعان ولا تتقاطعان، فإذا أعطيت الجدول صلاحية read(users) فكل مستخدم مسجل يقرأ كل الصفوف مهما كانت صلاحيات الصف، وهذا أشيع خطأ عند من يأتي من Firebase. والإنشاء يحتاج دائماً صلاحية الجدول.

تطبيق ويب صغير: سارة وعمر في متصفحين

مكتبة الويب appwrite تحفظ جلسة المستخدم في Cookie من نوع HttpOnly، فلا يقرؤها كود JavaScript، وهذا جيد للأمان، لكنه يعني أن المكتبة لا تعمل بشكل طبيعي من Node.js، لأنه لا يحفظ Cookies بين الطلبات، ولذلك شغلنا التطبيق في متصفح حقيقي: صفحة HTML صغيرة يقدمها سيرفر بسيط، ونفتحها في Google Chrome على الجهاز بملفي تعريف Profiles منفصلين، أحدهما لسارة والآخر لعمر، ونقودهما عبر DevTools. والكود التالي هو التطبيق كله بالإصدار 29.3.1 من المكتبة:

// The small web client: ?user=sara writes a todo with a file; ?user=omar listens, then tries to reach sara's data
const { Client, Account, TablesDB, Storage, Functions, Realtime, ID, Permission, Role } = Appwrite
const P = new URLSearchParams(location.search), user = P.get('user'), email = `${user}@example.com`, password = 'Lab-Pass-2026!'
const client = new Client().setEndpoint('http://localhost:28880/v1').setProject(P.get('project'))
const account = new Account(client), db = new TablesDB(client), storage = new Storage(client), fn = new Functions(client)
const out = (...a) => { const s = a.map(x => typeof x === 'string' ? x : JSON.stringify(x)).join(' '); console.log(s); document.getElementById('log').textContent += s + '\n' }
const err = (e) => `${e.code} ${e.message}`
const T = { databaseId: 'todo', tableId: 'todos' }
const mine = (id) => [Permission.read(Role.user(id)), Permission.update(Role.user(id)), Permission.delete(Role.user(id))]
const show = async () => { const { rows } = await db.listRows(T); document.getElementById('list').innerHTML = rows.map(r => `<li>${r.title}${r.attachment ? ' 📎' : ''}</li>`).join('') ; return rows }

window.run = async () => {
  // 1) sign up and sign in: the session is an HttpOnly cookie for localhost
  const me = await account.create({ userId: ID.unique(), email, password })
  await account.createEmailPasswordSession({ email, password })
  document.getElementById('who').textContent = email
  out('signup', user, me.$id)

  if (user === 'omar') {
    // 2) realtime: every row event in the todos table
    window.events = []
    await new Realtime(client).subscribe('databases.todo.tables.todos.rows', (e) => window.events.push(`${e.events[0].split('.').pop()}: ${e.payload.title}`))
    out('realtime omar subscribed')
    window.ready = true
    while (!window.TARGET) await new Promise(r => setTimeout(r, 200))      // the driver passes sara's ids here
    await db.createRow({ ...T, rowId: ID.unique(), data: { title: 'ملاحظة عمر' }, permissions: mine(me.$id) })
    await new Promise(r => setTimeout(r, 1500))
    out('list omar sees:', (await show()).map(r => r.title))
    out('realtime omar received:', window.events)
    await db.getRow({ ...T, rowId: window.TARGET.row }).catch(e => out('get sara row ->', err(e)))
    await db.updateRow({ ...T, rowId: window.TARGET.row, data: { title: 'hacked' } }).catch(e => out('update sara row ->', err(e)))
    await storage.getFile({ bucketId: 'attachments', fileId: window.TARGET.file }).catch(e => out('get sara file ->', err(e)))
    await db.createRow({ ...T, rowId: ID.unique(), data: { title: 'forged' }, permissions: [Permission.read(Role.user(window.TARGET.user))] })
      .catch(e => out('create row readable by sara ->', err(e)))
  } else {
    // 3) a file only sara may read, then a row pointing at it
    const file = await storage.createFile({ bucketId: 'attachments', fileId: ID.unique(),
      file: new File(['نراجع الخطة يوم الأحد'], 'plan.txt', { type: 'text/plain' }), permissions: [Permission.read(Role.user(me.$id))] })
    const row = await db.createRow({ ...T, rowId: ID.unique(), data: { title: 'خطة الإطلاق', attachment: file.$id }, permissions: mine(me.$id) })
    await db.createRow({ ...T, rowId: ID.unique(), data: { title: 'موردون', done: true }, permissions: mine(me.$id) })
    out('list sara sees:', (await show()).map(r => r.title))
    const view = await fetch(storage.getFileView({ bucketId: 'attachments', fileId: file.$id }), { credentials: 'include' })
    out('file view sara ->', view.status, await view.text())
    await db.createRow({ ...T, rowId: ID.unique(), data: { title: 'للجميع' }, permissions: [Permission.read(Role.any())] })
      .then(r => out('create row readable by anyone -> created', r.$permissions)).catch(e => out('create row readable by anyone ->', err(e)))
    // 4) the function runs with sara's JWT
    const ex = await fn.createExecution({ functionId: 'todo-stats', async: false })
    out('function ->', ex.responseStatusCode, ex.responseBody, `${Math.round(ex.duration * 1000)} ms`)
    window.TARGET = { user: me.$id, row: row.$id, file: file.$id }
  }
  window.done = true
}

والترتيب في التجربة: يفتح عمر الصفحة ويشترك في التحديث الفوري وينتظر، ثم تفتح سارة الصفحة فتسجل وترفع ملفاً وتضيف ثلاثة صفوف وتنفذ الدالة، ثم يكمل عمر بمحاولة الوصول إلى بياناتها. والمخرج سوف يكون كما يلي:

=== sara
signup sara 6aff7d2a003496e50ed7
list sara sees: ["خطة الإطلاق","موردون"]
file view sara -> 200 نراجع الخطة يوم الأحد
create row readable by anyone -> created ["read(\"any\")"]
function -> 200 {"user":"6aff7d2a003496e50ed7","todos":3,"done":1} 7298 ms

=== omar
signup omar 6aff7d27002d92b0840e
realtime omar subscribed
list omar sees: ["للجميع","ملاحظة عمر"]
realtime omar received: ["create: للجميع","create: ملاحظة عمر"]
get sara row -> 404 Row with the requested ID '6aff7d2b001f0890f7f3' could not be found.
update sara row -> 401 The current user is not authorized to perform the requested action.
get sara file -> 404 The requested file could not be found.
create row readable by sara -> 401 Permissions must be one of: (any, users, user:6aff7d27002d92b0840e, user:6aff7d27002d92b0840e/unverified, users/unverified)

في المخرج أعلاه لاحظ التالي:

  • القائمة listRows دون أي شرط أعادت لكل مستخدم ما يسمح له به فقط، وهذا التصفية على السيرفر بصلاحيات الصف.
  • طلب عمر قراءة صف سارة رد ب 404 وكأن الصف غير موجود، أما طلب التعديل فرد ب 401 مع رسالة صريحة، أي أن الواجهة لا تعامل الحالتين بالطريقة نفسها، فلا تعتمد في تطبيقك على رمز معين لتقرر هل الصف موجود.
  • ملف سارة رد لعمر ب 404، ولسارة ب 200 عبر الرابط وال Cookie، وهذا ما يجعل credentials: 'include' ضرورياً عند جلب الملف من أصل آخر.
  • محاولة عمر أن يعطي سارة صلاحية على صف ينشئه رفضت، والرسالة تكشف القاعدة: العميل يمنح فقط أدواراً يملكها هو، أي نفسه، أو المستخدمين المسجلين، أو الجميع.

والصورة التالية من صفحة عمر بعد التجربة، وفيها القائمة كما يراها:

صفحة تطبيق الويب الصغير بعنوان مهامي omar@example.com وفيها مهمتان: للجميع وملاحظة عمر، وتحتها سجل المخرجات: الاشتراك في Realtime ووصول حدثين ورفض قراءة صف سارة ب 404 وتعديله ب 401 وملفها ب 404
عمر يرى مهمته، ومعها مهمة لسارة جعلتها هي عامة

الثغرة التي يفتحها العميل لنفسه

السطر الأهم في المخرج هو create row readable by anyone -> created، فقد أنشأت سارة من المتصفح صفاً بصلاحية read("any") وقبله السيرفر، فظهر لعمر في القائمة وفي التحديث الفوري، وكان سيظهر لأي زائر دون تسجيل. وهذا منطقي من وجهة نظر Appwrite، فالمستخدم يملك صفه، والقائمة المسموحة في رسالة الخطأ تضم any، لكن تخيل تطبيقاً تتحكم فيه الواجهة بقائمة الصلاحيات، ثم يعدل شخص الطلب من أدوات المطور، فيجعل بياناته أو بيانات فريقه عامة. والصورة التالية تبين النموذج والنتائج الثلاث:

الجدول todos بصلاحية create لكل المستخدمين وrowSecurity مفعل دون صلاحية read على الجدول، وثلاثة صفوف: صف سارة الخاص بصلاحيات user:sara فرد على عمر ب 404 و401، وصف سارة بصلاحية read any ظهر لعمر في القائمة وRealtime، ومحاولة عمر منح سارة صلاحية رفضت ب 401، وقائمة الأدوار المسموحة للعميل any وusers وuser:me
العميل لا يمنح غيره صلاحية، لكنه يستطيع أن يجعل صفه عاماً

والحل ليس في الواجهة، وإنما في السيرفر: إذا كانت البيانات لا يجوز أن تكون عامة أبداً، فلا تترك العميل ينشئ الصف مباشرة، وإنما اجعل الإنشاء عبر دالة تعمل بمفتاح API وتضع الصلاحيات بنفسها، وأزل صلاحية create عن الجدول، أو افحص الصفوف الجديدة في دالة يطلقها حدث Event الإنشاء وتصحح صلاحياتها. والصورة التالية من صفحة الصفوف في اللوحة، وفيها الصف العام بين صفوف المستخدمين:

صفحة Rows لجدول todos في لوحة Appwrite وفيها أربعة صفوف: ملاحظة عمر وللجميع وموردون بقيمة done true وخطة الإطلاق ومعها معرف ملف في عمود attachment، مع عمود $createdAt
المشرف يرى الصفوف كلها، والصلاحيات تظهر عند فتح كل صف
💡
في 20 مايو 2021 نشرت Check Point Research بحثاً عن تطبيقات Android شائعة تركت قواعد بياناتها الفورية Real-time Databases وتخزينها السحابي بإعدادات تسمح لأي شخص بالقراءة، فانكشفت بيانات أكثر من 100 مليون مستخدم، من أسماء ورسائل محادثة وعناوين وصور. ولم يخترق الباحثون شيئاً، وإنما طلبوا البيانات بالمفتاح الموجود في التطبيق نفسه. والدرس أن الصلاحيات في خدمات BaaS هي الحارس الوحيد، فاختبر كل جدول ومجلد من خارج التطبيق قبل الإطلاق، ولا تفترض أن ما لا تعرضه الواجهة لا يطلبه أحد.

التحديث الفوري Realtime

اشترك عمر في القناة databases.todo.tables.todos.rows، أي كل أحداث الصفوف في الجدول، ووصله حدثان فقط: صفه هو، وصف سارة العام، أما صفاها الخاصان فلم يصلا، والسبب أن خدمة appwrite-realtime تتحقق من صلاحية القراءة لكل مشترك قبل أن ترسل الحدث، كما في توثيق Realtime. والاتصال من نوع WebSocket يحمل جلسة المستخدم نفسها، وقد ظهر في سجل الخدمة عند إغلاقه معرف المستخدم وعدد اشتراكاته. ولا تقم بالاعتماد على الأحداث وحدها، والسبب أن ما يحدث أثناء انقطاع الاتصال لا يعاد، فاقرأ القائمة عند فتح الشاشة وعند عودة الاتصال.

الدالة: لماذا فشلت أول مرة؟

الدالة todo-stats تحسب مهام المستخدم الذي استدعاها، والفكرة أنها لا تستخدم مفتاح API، وإنما توكن JWT Token الخاص بالمستخدم الذي يضيفه Appwrite في الترويسة x-appwrite-user-jwt، فتبقى صلاحيات الصف مطبقة عليها، وهذا أفضل من مفتاح يرى كل شيء ثم شرط تكتبه بنفسك:

// todo-stats: counts the caller's todos with the caller's own JWT, so row permissions still apply
import { Client, TablesDB } from 'node-appwrite'

export default async ({ req, res, log }) => {
  const jwt = req.headers['x-appwrite-user-jwt']
  if (!jwt) return res.json({ error: 'not signed in' }, 401)

  const client = new Client()
    .setEndpoint(process.env.API_ENDPOINT ?? process.env.APPWRITE_FUNCTION_API_ENDPOINT)   // see the text: localhost is the runtime itself
    .setProject(process.env.APPWRITE_FUNCTION_PROJECT_ID)
    .setJWT(jwt)
  const { rows, total } = await new TablesDB(client).listRows({ databaseId: 'todo', tableId: 'todos' })
  const done = rows.filter(r => r.done).length
  log(`user ${req.headers['x-appwrite-user-id']} has ${total} todos`)
  return res.json({ user: req.headers['x-appwrite-user-id'], todos: total, done })
}

لكن السطر الذي يحدد العنوان لم يكن هكذا في البداية، وإنما كان يأخذ APPWRITE_FUNCTION_API_ENDPOINT وحده، وفي التشغيل الأول ردت الدالة ب 500 بعد 11.3 ثانية، وسجل التنفيذ يقول:

TypeError: fetch failed
    at fetch (/usr/local/server/src/function/node_modules/undici/index.js:113:13)
    at async _Client.call (file:///usr/local/server/src/function/node_modules/node-appwrite/dist/client.mjs:718:22)
    at async Module.default (file:///usr/local/server/src/function/src/main.js:12:27)

فدخلنا إلى Container الدالة لنرى القيمة التي وصلتها:

docker exec exc1-6aff799000122338169d-6aff7aa314caa274b7d9 sh -c 'env | grep APPWRITE_FUNCTION_API_ENDPOINT'
docker inspect exc1-6aff799000122338169d-6aff7aa314caa274b7d9 --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}'
APPWRITE_FUNCTION_API_ENDPOINT=http://localhost/v1
runtimes

والسبب أن Appwrite يبني هذا العنوان من اسم السيرفر الذي أدخلناه في المعالج، أي localhost، وlocalhost داخل Container الدالة هو ال Container نفسه، وليس السيرفر، والصورة التالية تبين ذلك:

سارة في المتصفح تطلب createExecution من appwrite الذي يضيف توكن JWT ويطلب التنفيذ من executor، وContainer الدالة على شبكة runtimes يحمل APPWRITE_FUNCTION_API_ENDPOINT = http://localhost/v1 فيعود الطلب إلى الدالة نفسها ويفشل ب fetch failed و500 بعد 11.3 ثانية، والحل نطاق حقيقي في _APP_DOMAIN في الإنتاج أو متغير API_ENDPOINT في المختبر، والنتيجة 200 بعد 7.3 ثانية ثم 11 إلى 14 مللي ثانية
المشكلة لا تظهر على سيرفر له نطاق حقيقي، وتظهر في كل تجربة محلية

وفي الإنتاج لن تواجه هذا، لأن _APP_DOMAIN سيكون نطاقاً حقيقياً مثل api.example.com يصل إليه ال Container عبر الإنترنت أو عبر DNS داخلي، أما في المختبر فأضفنا للدالة متغيراً اسمه API_ENDPOINT يشير إلى السيرفر عبر host.docker.internal الذي يوفره Docker Desktop، ورفعنا نشراً جديداً، وهذا حل خاص بجهاز التطوير، فلا تنقله إلى الإنتاج. وبعدها ردت الدالة بالأرقام الصحيحة: ثلاث مهام لسارة منها واحدة منتهية، كما ظهر في المخرج السابق. والصورة التالية من صفحة التنفيذات Executions، وفيها القصة كلها بالترتيب:

صفحة Executions للدالة todo-stats وفيها خمسة تنفيذات: الأقدم Failed بالرمز 500 ومدته 11.3 ثانية من النشر الأول، ثم Completed بالرمز 200 ومدته 7.3 ثانية، ثم ثلاثة Completed بالرمز 401 ومدة كل منها بين 11 و14 مللي ثانية
فشل ثم تشغيل بارد ثم تنفيذات دافئة في أجزاء من الثانية

ولاحظ الفرق بين 7.3 ثانية للتنفيذ الأول بعد النشر و11 إلى 14 مللي ثانية للتنفيذات التالية، فالأول يشمل إنشاء Container الدالة وتشغيل Node.js وتحميل الكود، وهذا هو التشغيل البارد Cold Start، والتنفيذات التالية ردت ب 401 لأننا استدعيناها بمفتاح API دون مستخدم، والمهم فيها هنا هو الزمن. فإذا كانت دالتك في مسار يراه المستخدم مباشرة، كزر في التطبيق، فاحسب أن أول ضغطة بعد كل نشر أو بعد خمول طويل قد تأخذ ثواني، وفكرة الدوال بلا سيرفر Serverless وحدودها في Serverless على سيرفرك.

الدالة عند حدث وعلى جدول زمني

استدعينا الدالة من التطبيق مباشرة، لكن هذا أحد ثلاثة طرق لتشغيلها، والطريقان الآخران هما ما يجعل الدوال مفيدة فعلاً، كما في توثيق تطوير الدوال:

  • الأحداث Events: كل تغيير في Appwrite يطلق حدثاً باسم له شكل المسار، مثل databases.todo.tables.todos.rows.*.create عند إنشاء أي صف في جدول المهام، أو users.*.create عند تسجيل مستخدم جديد، وتربط الدالة بالحدث عند إنشائها في الحقل events، فتعمل في الخلفية بعد الحدث. وهنا المكان المناسب لإصلاح صلاحيات الصف العام الذي رأيناه، أو لإرسال بريد الترحيب، وفكرة الأحداث بين الأنظمة شرحناها في Webhooks.
  • الجدولة Schedule: تعبير Cron في الحقل schedule، فتعمل الدالة كل ليلة مثلاً لتنظيف المهام المنتهية، وتنفذها الخدمة appwrite-task-scheduler.
  • التنفيذ غير المتزامن Async: إذا استدعيت الدالة ب async: true يعود الطلب فوراً بمعرف التنفيذ، وتقرأ النتيجة لاحقاً، وهذا ما تحتاجه لأي عمل يتجاوز ثواني قليلة، والسبب أن الاستدعاء المتزامن مقيد بمهلة الدالة، وهي 15 ثانية في دالتنا.

ولاحظ في سكربت الإعداد الحقل scopes في إنشاء الدالة، فهو يجعل Appwrite يعطي كل تنفيذ مفتاح API مؤقتاً بالصلاحيات التي تحددها فقط، في الترويسة x-appwrite-key، فلا تحتاج أن تضع مفتاحاً دائماً في متغيرات الدالة. ولا تقم بإعطاء هذا المفتاح صلاحيات أوسع من حاجة الدالة، والسبب أن أي ثغرة في كود الدالة، كمكتبة npm مخترقة، تصبح ثغرة بحجم هذه الصلاحيات.

المصادقة والفرق Teams

اختبرنا البريد وكلمة المرور فقط، لكن خدمة المصادقة في Appwrite أوسع من ذلك: رابط سحري Magic URL يصل بالبريد، ورمز مؤقت بالبريد Email OTP، ورقم الجوال برسالة نصية عبر مزود SMS تضبطه، وحسابات خارجية عبر OAuth2 لعشرات المزودين، ومستخدم مجهول Anonymous يحول لاحقاً إلى حساب كامل، والمصادقة متعددة العوامل MFA. والجلسة في المتصفح Cookie كما رأينا، وفي تطبيقات الجوال تحفظها المكتبة الرسمية بنفسها، وإذا احتاج سيرفر آخر عندك أن يعرف المستخدم، كالدالة التي كتبناها، فالطريقة هي توكن JWT قصير المدة تولده المكتبة ب account.createJWT()، فكرته في الجلسات وملفات تعريف الارتباط وJWT.

والفرق Teams هي الطريقة الصحيحة للمشاركة، فبدل أن تضيف إلى كل صف صلاحية لكل عضو، تنشئ فريقاً للمشروع، وتعطي الصف صلاحية read(team:<id>)، ومع الدور داخل الفريق تستطيع أن تجعل التعديل لمن يحمل دور editor فقط، أي update(team:<id>/editor). والميزة هنا أن إضافة عضو جديد أو إخراجه تعديل واحد في الفريق، وليس في آلاف الصفوف. ويذكر دليل التثبيت أن قيد المؤسسة الواحدة في النسخة المستضافة يخص فرق لوحة الإدارة، أما فرق مستخدمي تطبيقك داخل المشروع فلا حد لها.

التخزين أبعد من رفع ملف

المجلد Bucket في Appwrite يحمل إعدادات تؤثر في الأمان والقرص معاً، وقد ظهرت كلها في توقيع الدالة createBucket في المكتبة:

  • الضغط Compression: gzip أو zstd للملفات قبل حفظها، ويوفر القرص في الملفات النصية، ولا يفيد في الصور والفيديو لأنها مضغوطة أصلاً.
  • التشفير Encryption: تشفير الملف على القرص بمفتاح المشروع الذي ولده المعالج، وهذا سبب إضافي لحفظ _APP_OPENSSL_KEY_V1، فبدونه لا تفتح الملفات المشفرة من نسختك الاحتياطية.
  • فحص الفيروسات Antivirus: يعتمد على خدمة ClamAV، وملف .env الذي ولده المعالج يشير إلى مضيف اسمه clamav، لكن الخدمة نفسها غير موجودة في ملف Compose الذي ولده، فإذا فعلت الخيار فأضف الخدمة بنفسك واختبرها، وإلا فلن يفحص شيء.
  • التحويلات Transformations: معاينات مصغرة للصور بالحجم المطلوب، تولد عند الطلب.

والقرار المهم هنا مكان الملفات: افتراضياً تحفظ في Volume على السيرفر نفسه، ويمكن أن تحفظ في تخزين متوافق مع S3 عبر المتغير _APP_STORAGE_DEVICE، فيصبح نسخها وتوسيعها أسهل، والفكرة في تخزين الكائنات S3 على سيرفرك.

الرسائل Messaging والمواقع Sites

في القائمة الجانبية للمشروع خدمتان لم نجربهما في المختبر، لكن يجب أن تعرف ما تفعلانه قبل أن تختار Appwrite. الأولى Messaging، وهي ترسل إلى مستخدميك بريداً ورسائل نصية SMS وإشعارات Push من مكان واحد، مع مواضيع Topics يشترك فيها المستخدمون، وجدولة للرسائل. لكن لاحظ أنها لا ترسل بنفسها، وإنما عبر مزودين تضبطهم: سيرفر SMTP أو خدمة بريد للبريد، ومزود SMS للرسائل النصية، وFCM وAPNs للإشعارات. أي أنها توحد الواجهة وسجل الإرسال، لكنها لا تخرجك من Google وApple في الإشعارات، وهذا الاستثناء الصادق الذي ذكرناه في مقال BaaS، وتفصيله في مقال الإشعارات بدون Firebase.

والثانية Sites، وهي استضافة لتطبيقات الويب، ثابتة أو بإطار عمل مثل Next.js، تبنيها من مستودع Git وتنشرها على نطاق فرعي، أي أنها تنافس منصات النشر مثل Coolify في هذا الجزء، والفكرة العامة في تثبيت Coolify. وفي النسخة المستضافة تحتاج نطاقاً لكل موقع وشهادات، وهي الإعدادات _APP_DOMAIN_SITES و_APP_DOMAIN_TARGET التي ظهرت في ملف .env. والقرار هنا بسيط: إذا كان عندك منصة نشر تعمل فلا تحتاج Sites، وإذا كان Appwrite هو كل ما على السيرفر فوجودها يوفر عليك أداة.

من التطبيق على الجوال

اختبرنا مكتبة الويب، لكن أغلب من يختار Appwrite يكتب تطبيق جوال، والمكتبات الرسمية موجودة ل Flutter وAndroid بلغة Kotlin وiOS بلغة Swift وReact Native، وتعمل بالنموذج نفسه: Client بعنوان الواجهة البرمجية ومعرف المشروع، ثم الخدمات. والفرق في المنصة Platform التي تسجلها في المشروع، فبدل اسم المضيف localhost الذي سجلناه للويب تسجل معرف الحزمة Package Name في Android ومعرف الحزمة Bundle ID في iOS، والسبب نفسه: يرفض Appwrite طلبات العملاء من منصة غير مسجلة. وتذكر أن هذا ليس حماية حقيقية من شخص يرسل الطلبات بنفسه، فمعرف الحزمة يرسل في الطلب ويمكن تقليده، والحماية الحقيقية هي الصلاحيات التي رأيناها. وإذا كان تطبيقك على الجوال يحتاج أن يعمل دون اتصال، فهذه مسألة تصميم في التطبيق نفسه وليست في الخلفية، وقد شرحناها في تطبيق يعمل دون إنترنت Offline-first.

عامل واحد أم عامل لكل طابور؟

في الإعدادات المتقدمة للمعالج خيار اسمه Container topology، وقيمته الافتراضية Combined، أي Container واحد اسمه appwrite-worker ينفذ كل الطوابير: البريد، والدوال، والإحصاءات، والحذف، والشهادات، والنسخ. والخيار الثاني Separate يجعل لكل طابور Container خاصاً به، كما في توثيق التوزيع. والقاعدة بسيطة: على سيرفر واحد صغير ابدأ ب Combined، لأن كل Container إضافي ذاكرة إضافية، وانتقل إلى Separate عندما ترى طابوراً واحداً يؤخر الباقين، كطابور بريد كبير يؤخر تنفيذ الدوال، أو عندما توزع العمال على أكثر من سيرفر. وفي الحالتين تقرأ حالة الطوابير من صفحة الصحة في الواجهة البرمجية، وهي جزء من المراقبة التي شرحناها في دليل المراقبة.

الذاكرة والقرص والزمن: ما قسناه

القياسالقيمةملاحظة
الخدمات في ملف Compose18شغلنا منها 14 مع Container الدالة
حجم ال Images التي عملتقرابة 11.6 جيجابايتمنها 4.5 للوحة و1.75 ل geo و1.18 لبيئة Node.js 22
بيئات تشغيل نزلها المنفذ دون طلبقرابة 3.7 جيجابايت إضافيةحذفناها، وتمنعها بضبط _APP_FUNCTIONS_RUNTIMES
زمن التنزيل على اتصال المختبر165 + 356 + 354 ثانيةالمعالج، ثم الخدمات الأساسية، ثم geo وClickHouse
من التشغيل حتى رد مسار الصحة126 ثانيةوال Images موجودة
الذاكرة دون ضغطقرابة 2.8 جيجابايتمنها 1.24 ل ClickHouse
بناء الدالة28 ثانيةمع npm install
تنفيذ الدالة7.3 ثانية باردة، ثم 11 إلى 14 مللي ثانيةNode.js 22

وللمقارنة، استهلك Supabase المستضاف في دليله قرابة 1.2 جيجابايت، واستهلك PocketBase في دليله أقل من 30 ميجابايت، والمقارنة الكاملة بالتطبيق نفسه على الثلاثة في مقال المقارنة ضمن هذه المرحلة.

أين تذهب بياناتك؟ اثنا عشر Volume

قبل أن تخطط للنسخ الاحتياطي اعرف ما الذي تنسخه، وفي آخر ملف Compose الذي ولده المعالج قائمة ال Volumes كاملة:

volumes:
  appwrite-postgresql: ~
  appwrite-redis: ~
  appwrite-cache: ~
  appwrite-clickhouse: ~
  appwrite-uploads: ~
  appwrite-imports: ~
  appwrite-certificates: ~
  appwrite-functions: ~
  appwrite-sites: ~
  appwrite-builds:
    name: appwrite-builds
  appwrite-config: ~
  appwrite-models: ~

في الإعداد أعلاه لاحظ التالي:

  • البيانات التي لا تعوض في ثلاثة: appwrite-postgresql للمستخدمين والجداول والصلاحيات وإعدادات المشاريع، وappwrite-uploads للملفات المرفوعة، وappwrite-functions لكود الدوال المنشور، ومعها ملف .env الذي فيه مفتاح التشفير، والأربعة معاً هي النسخة الاحتياطية الحقيقية.
  • appwrite-cache وappwrite-builds يمكن أن تعاد بناؤها، وappwrite-clickhouse إحصاءات، فخسارتها تعني فقدان أرقام الاستخدام وسجلات التنفيذ القديمة وليس بيانات تطبيقك.
  • appwrite-builds له اسم ثابت في Docker، أي لا يسبقه اسم المشروع كالبقية، فإذا شغلت تثبيتين على السيرفر نفسه للتجربة اشتركا فيه، وهذا من الأشياء التي لا تلاحظها حتى يحدث تعارض.
  • النسخ يجب أن يكون متسقاً، أي أن نسخة القاعدة ونسخة الملفات من اللحظة نفسها تقريباً، وإلا وجدت صفوفاً تشير إلى ملفات غير موجودة، والطريقة في Volumes وBind Mounts والنسخ الاحتياطي Backup.

من Firebase إلى Appwrite: ما الذي يشبهه وما الذي يختلف؟

  • قواعد Firebase مقابل صلاحيات الصف: في Firebase تكتب شرطاً مثل request.auth.uid == resource.data.owner، وفي Appwrite يحمل الصف نفسه قائمة الأدوار، فلا يوجد شرط يقارن حقلاً بحقل، وإنما قائمة تكتبها عند الإنشاء، وهذا أبسط في القراءة، لكنه يعني أن تغيير قاعدة لاحقاً يحتاج تعديل صلاحيات كل الصفوف الموجودة.
  • المستخدمون وكلمات المرور: Appwrite يقبل استيراد المستخدمين بهاش scrypt المعدل الخاص ب Firebase، ويقبل معرف المستخدم القديم كما هو، وقد اختبرنا ذلك في مقال الانتقال من Firebase.
  • أداة الانتقال المدمجة: في اللوحة أداة Migrations تنقل من Firebase المستخدمين وبيانات Firestore والملفات، لكنها تحتاج حساب خدمة Service Account من مشروع Firebase حقيقي، وصفحتها تذكر حدودها: Firestore فقط دون Realtime Database، والمستوى الأول فقط دون المجموعات الفرعية، ودون مستخدمي OAuth، ودون الدوال.
  • الإشعارات: خدمة Messaging في Appwrite ترسل Push لكن عبر مزودين خارجيين هما FCM وAPNs، أي أنها لا تلغي الحاجة إليهما، والتفصيل في مقال الإشعارات بدون Firebase.

قبل الإنتاج

  • اجعل _APP_DOMAIN و_APP_DOMAIN_FUNCTIONS نطاقات حقيقية بشهادة HTTPS، وفعل _APP_OPTIONS_FORCE_HTTPS، وتأكد أن الدوال تصل إلى الواجهة البرمجية من داخل شبكة runtimes.
  • اضبط _APP_FUNCTIONS_RUNTIMES على البيئات التي تستخدمها فقط قبل التشغيل الأول.
  • لا تحذف الخدمات المساعدة من ملف Compose قبل أن تعرف أين تستخدم، كما رأينا مع geo.
  • اضبط سيرفر SMTP في .env، واختبر رسالة التحقق واستعادة كلمة المرور فعلاً، وإذا لم يكن عندك سيرفر بريد فقد شرحنا البريد التفاعلي Transactional Email.
  • راجع صلاحيات كل جدول ومجلد: لا تعط الجدول read(users) إذا كانت القراءة يجب أن تكون للمالك فقط، وقرر هل يجوز للعميل أن يجعل صفه عاماً، واختبر بمستخدمين في متصفحين كما فعلنا.
  • النسخ الاحتياطي Backup عليك: صفحة النسخ الاحتياطي تقول إن النسخ التلقائي ميزة في النسخة السحابية، وإن النسخة المستضافة تحتاج نسخاً يدوياً لقاعدة البيانات وVolumes الملفات والدوال وملف .env، ولاحظ أن الصفحة عند كتابة هذا الدليل تشرح أوامر MariaDB وMongoDB فقط مع أن PostgreSQL أصبحت الافتراضية، فاستخدم معها pg_dump كما في نسخ قواعد البيانات بشكل متسق، وارفع النسخ إلى مكان آخر.
  • التحديث Upgrade بخطوات: دليل التحديث يطلب أن تشغل أداة الترحيل Migration بعد تثبيت الإصدار الجديد، وأن تمر بآخر إصدار تصحيحي من كل إصدار فرعي في الطريق، فلا تقفز من إصدار قديم إلى الأحدث مباشرة، وخذ نسخة احتياطية قبل كل تحديث.
  • راقب الذاكرة والقرص، فClickHouse وحده يحتاج أكثر من جيجابايت، والسجلات وإحصاءات الاستخدام تكبر مع الوقت، كما في تخطيط السعة.

متى يناسبك Appwrite، ومتى لا؟

الحالةالقراروالسبب
فريق جوال يأتي من Firebase ولا يريد كتابة SQLAppwriteصلاحيات على مستوى الصف ولوحة كاملة ومكتبات رسمية للجوال
دوال كثيرة بلغات مختلفةAppwriteبيئات تشغيل متعددة ل Node.js وPython وDart وغيرها
انتقال من Firebase مع الحفاظ على كلمات المرور ومعرفات المستخدمينAppwrite أو Supabaseكلاهما يقبل هاش scrypt الخاص ب Firebase
تقارير واستعلامات SQL معقدة وعلاقات كثيرةSupabaseتكتب SQL على PostgreSQL مباشرة
سيرفر صغير بذاكرة 2 جيجابايت أو أقلPocketBaseAppwrite وحده استهلك 2.8 جيجابايت دون ضغط
فريق لا يملك وقتاً لتشغيل 18 خدمة وتحديثهاالنسخة السحابية أو PocketBaseكل خدمة إضافية شيء يتعطل ويحتاج متابعة

أخطاء شائعة

  • صلاحية read على الجدول: تجمع مع صلاحيات الصف، فيقرأ الجميع كل شيء.
  • ترك العميل يكتب الصلاحيات دون تحقق: فيجعل بياناته عامة ب read("any").
  • اسم السيرفر localhost: فتفشل الدوال التي تكلم الواجهة البرمجية.
  • ترك قائمة البيئات الافتراضية: فينزل المنفذ جيجابايتات لا تحتاجها.
  • حذف خدمة مساعدة: فيتأخر كل طلب ثلاث ثوان دون أي رسالة خطأ واضحة.
  • فتح منفذ المعالج 20080 للعالم: وهو يحمل مقبس Docker.
  • مكتبة الويب في Node.js: الجلسة Cookie، فاستخدم مكتبة السيرفر بمفتاح API أو توكن JWT.
  • InputFile من المسار القديم: فيفشل السكربت قبل أن يبدأ.

وخلاصة هذا الجدول أن Appwrite يناسب الفريق الذي يريد أن يشتري الوقت بالسيرفر، أي أن يدفع ذاكرة وقرصاً أكبر مقابل ميزات جاهزة ولوحة واحدة، ولا يناسب الفريق الذي يريد أن يوفر السيرفر بوقته.

تدريب عملي

  • أنشئ فريقاً لمشروع، وأضف إليه مستخدمين بدورين مختلفين، ثم اجعل صلاحية الصف read(team:<id>) وصلاحية التعديل update(team:<id>/editor)، واختبر بالمستخدمين في متصفحين كما فعلنا.
  • أزل صلاحية create عن جدول المهام، وانقل الإنشاء إلى دالة تضع الصلاحيات بنفسها بمفتاحها المؤقت، ثم حاول من المتصفح أن تنشئ صفاً عاماً، ولاحظ الفرق.
  • اربط دالة بالحدث databases.todo.tables.todos.rows.*.create، واجعلها تكتب في السجل عنوان كل مهمة جديدة، ثم اقرأ السجل من صفحة التنفيذات.
  • غير _APP_FUNCTIONS_RUNTIMES إلى بيئة واحدة، وأعد تشغيل المنفذ، وتأكد من قائمة ال Images أنه لم ينزل غيرها.

والهدف من التدريب الثاني خصوصاً أن ترى بنفسك الفرق بين صلاحيات يقررها العميل وصلاحيات يقررها السيرفر، فهو القرار الأهم في أي تطبيق مبني على Appwrite، وكلما اتخذته مبكراً قل ما تحتاج أن تصلحه لاحقاً في آلاف الصفوف الموجودة، لأن تغيير الصلاحيات بعد الإطلاق يعني سكربتاً يمر على كل صف ويعيد كتابة قائمة أدواره.

حذف المختبر

docker rm -f sc5-aw-web $(docker ps -aq --filter name=exc1-)
docker compose -p sc5-aw down -v
docker network rm runtimes

ولاحظ أن الشبكات في ملف Compose الذي يولده المعالج لها أسماء ثابتة، أي appwrite وgateway وbrowser وruntimes، وأن Containers الدوال وشبكة runtimes ينشئها المنفذ وليس Compose، فلا يحذفها down. ثم حذفنا ال Images التي نزلناها بأسمائها، ولا تقم بتشغيل docker system prune على سيرفر عليه خدمات أخرى.

ولا تقم بتشغيل أوامر الحذف هذه على سيرفر إنتاج فيه تثبيت Appwrite حقيقي، والسبب أن الخيار -v يحذف Volume قاعدة البيانات والملفات معاً، فالأمر الذي ينظف المختبر في ثوان يحذف كل بيانات مستخدميك في الثواني نفسها، ولا رجوع عنه إلا من نسخة احتياطية.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • Appwrite 2.7.4 منصة كاملة بترخيص BSD-3-Clause: مصادقة وجداول وتخزين ودوال وتحديث فوري ورسائل، ويثبت بمعالج من المتصفح يولد ثماني عشرة خدمة.
  • الثمن حقيقي: قرابة 11.6 جيجابايت من ال Images و2.8 جيجابايت من الذاكرة دون ضغط في المختبر، فاضبط _APP_FUNCTIONS_RUNTIMES قبل التشغيل، ولا تحذف خدمة مساعدة قبل أن تعرف دورها.
  • الصلاحيات على الجدول وعلى الصف تجمع، والإنشاء يحتاج صلاحية الجدول، والعميل يستطيع أن يجعل صفه عاماً، فقرر ذلك على السيرفر.
  • الدالة تعمل بتوكن المستخدم فتبقى الصلاحيات مطبقة، وتحتاج عنواناً حقيقياً للواجهة البرمجية، والتشغيل البارد أخذ 7.3 ثانية والدافئ أجزاء من الثانية.
  • النسخ الاحتياطي والتحديث عليك، والتحديث يمر بإصدارات وسيطة مع أداة الترحيل.
دليلما هو Backend as a Service؟ وما بديل كل خدمة في Firebaseما الذي يقدمه ال Backend الجاهز لتطبيقك، ولماذا تصبح قواعد الوصول هي الحارس الوحيد لبياناتك، وما البديل المفتوح لكل خدمة في Firebase.دليلSupabase على سيرفرك: بديل Firebase فوق PostgreSQLكيف تثبت Supabase على سيرفرك وتبني عليه تطبيقاً صغيراً بمستخدمين وصلاحيات وملفات، وما الذي ينقص النسخة المستضافة عن السحابية.دليلPocketBase: Backend كامل في ملف واحد على سيرفرككيف تشغل PocketBase على سيرفرك وتبني عليه تطبيقاً بمستخدمين وقواعد وصول وملفات وتحديث فوري، وما الذي يكفيه سيرفر واحد وما الذي لا يكفيه.دليلSupabase أم Appwrite أم PocketBase؟ مقارنة بالأرقامبنينا التطبيق نفسه على الأدوات الثلاث وقسنا الذاكرة والقرص والزمن والصلاحيات، لتختار الخلفية التي تناسب سيرفرك وفريقك.دليلالانتقال من Firebase: البيانات والمستخدمون وكلمات المروركيف تنقل بيانات Firestore والمستخدمين بكلمات مرورهم القديمة من Firebase إلى Supabase وAppwrite وPocketBase، وتعيد كتابة القواعد دون أن تفتح بياناتك.

سجل التحديثات

  • 20 نوفمبر 2026: كتابة الدليل، وتنفيذ المختبر على Appwrite 2.7.4 مع PostgreSQL ومكتبتي node-appwrite 32.0.0 وappwrite 29.3.1 وبيئة Node.js 22 للدوال، على Docker Engine 29.8.0 وGoogle Chrome 157.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.