انتقل إلى المحتوى الرئيسي

mTLS والنشر

كيفية حماية مشروع OneEntry برمز أو بشهادة mTLS، ونشر التطبيق على خادم باستخدام Nginx وDocker وGitLab أو GitHub.

الجزء 1: إعداد mTLS​

حماية واجهة API​

  1. الرمز: أنشئ رمزًا في إعدادات OneEntry وأرسله في ترويسة الطلب x-app-token.
  2. mTLS: فعّل mTLS في لوحة تحكم OneEntry وأنشئ شهادة في إعدادات OneEntry.

إعداد الشهادة​

  1. في لوحة التحكم، افتح علامة التبويب Access وبدّل من الرمز إلى mTLS.
  2. أنشئ شهادة جديدة في OneEntry (Settings → Application Certificates → Create New Certificate).
  3. نزّلها واستخرجها إلى مجلد cert في جذر مشروعك.

إعداد البيئة المحلية (مثال React)​

  1. نزّل setupProxy.js واحفظه في المجلد src.
  2. اضبط المعامل target على عنوان مشروعك.
  3. ثبّت http-proxy-middleware: npm install http-proxy-middleware.
  4. شغّل التطبيق.

تهيئة SDK​

عند تفعيل mTLS لا تتحقق واجهة API من رمز التطبيق. هيّئ SDK بعنوان مشروعك كالمعتاد. لا يزال SDK 1.0.175 يتطلب قيمة token غير فارغة، لذا مرّر أي سلسلة نصية بديلة:

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'mtls', // not checked when mTLS is enabled
});

الجزء 2: إعداد الخادم​

تجهيز الخادم​

  1. حدّث معلومات المستودعات: apt update.
  2. أضف مستودع Docker وثبّت الحزم: apt install nginx certbot docker-ce pwgen.

إعداد UFW​

  1. احظر جميع الاتصالات الواردة: ufw default deny incoming.
  2. اسمح بجميع الاتصالات الصادرة: ufw default allow outgoing.
  3. اسمح باتصالات TCP الواردة على المنافذ 22 و80 و443: ufw allow 22,80,443/tcp.

إعداد SSH​

  1. عدّل إعدادات خادم SSH: nano /etc/ssh/sshd_config.
  2. عيّن PasswordAuthentication no.
  3. أعد تشغيل خادم SSH: systemctl restart ssh.

إعداد Nginx​

  1. احذف ملف الإعدادات الافتراضي: rm /etc/nginx/sites-available/default.
  2. أنشئ ملف إعدادات جديدًا: nano /etc/nginx/sites-available/my_app.
  3. نزّل إعدادات Nginx الخاصة بـ OneEntry واستبدل "your_domain.com" بنطاقك.
  4. نفّذ: ln -s /etc/nginx/sites-available/my_app /etc/nginx/sites-enabled، مع استبدال "my_app" باسم ملف إعداداتك.
  5. أصدر شهادات SSL باستخدام Certbot: certbot certonly --webroot -w /var/www/html -d your_domain.
  6. تحقّق من التجديد التلقائي للشهادات: certbot renew --dry-run.
  7. عدّل مهمة cron الخاصة بـ Certbot ليعيد Nginx تحميل إعداداته بعد إصدار الشهادات: nano /etc/cron.d/certbot، مع استبدال السطر الأخير بـ: echo "0 */12 * * * root certbot -q renew && nginx -s reload" > /etc/cron.d/certbot
  8. أزل التعليق عن الأسطر في ملف الإعدادات nano /etc/nginx/sites-available/my_app (حيث my_app هو اسم ملف إعداداتك).
  9. تحقّق من إعدادات Nginx: nginx -t.
  10. أعد تحميل Nginx بعد كل تغيير: nginx -s reload.

الجزء 3: نشر التطبيق باستخدام GitLab أو GitHub​

صلاحيات المشغّل. ينضم مستخدم مشغّل GitHub إلى المجموعتين docker وsudo، ويعمل مشغّل GitLab في الوضع المميّز (privileged) مع مقبس Docker الخاص بالمضيف. وكلاهما يمنح تحكمًا بمستوى root في المضيف، لذا سجّل المشغّل لمستودعك الخاص فقط ولا تسمح له بتشغيل مهام من التفرعات (forks) أو طلبات الدمج غير الموثوقة. إصدارات الصور هي التي اختُبر عليها هذا الدليل؛ استخدم الإصدارات المدعومة الحالية من gitlab/gitlab-runner وdocker.

GitHub

إنشاء مستخدم لمشغّل GitHub​

  1. أنشئ كلمة مرور: pwgen -s 15 1.
  2. أنشئ مستخدمًا جديدًا: useradd -m github-runner.
  3. عيّن كلمة مرور له: passwd github-runner.
  4. أضف المستخدم الجديد إلى المجموعات: usermod -aG docker github-runner وusermod -aG sudo github-runner.
  5. غيّر الصدفة (shell) لمستخدم الـ runner: chsh -s /bin/bash github-runner.
  6. انتقل إلى المستخدم الجديد: sudo su - github-runner.

إعداد مشغّل GitHub​

  1. أنشئ مشغّلًا: في إعدادات مستودعك، افتح Actions → Runners وانقر New self-hosted runner.
  2. اتبع التعليمات في كتلة Download ونفّذ الأمر الأول في كتلة Configure.
  3. أضف الـ runner إلى التشغيل التلقائي للنظام: sudo ./svc.sh install. أدخل كلمة المرور التي أنشأتها سابقًا.
  4. شغّل الـ runner: sudo ./svc.sh start.
  5. في Actions → Runners، تأكد من أن المشغّل يعمل.
  6. عد إلى المستخدم root.
  7. أنشئ مجلد عمل: mkdir -p /var/apps/frontend.
  8. امنح المستخدم github-runner الصلاحيات: chown -R github-runner:docker /var/apps/frontend.

إعداد متغيرات البيئة في GitHub​

  1. أنشئ المتغيرات DOMAIN وMTLS_USER_CERT وMTLS_USER_KEY في مستودع GitHub الخاص بك (Settings → Secrets and Variables).
  2. أنشئ شهادة في OneEntry وضع الشهادة والمفتاح في المتغيرات. عيّن DOMAIN إلى عنوان مشروعك بدون https.
  3. نزّل الملف docker-compose.yml والأرشيفين .github و.docker.
  4. ضع docker-compose.yml والأرشيفين في المجلد الجذر لمشروعك واستخرجهما (يمكنك حذف الأرشيفين بعد ذلك).
  5. ادفع التغييرات إلى مستودعك.
  6. تابع التشغيل في علامة التبويب Actions.
  7. افتح التطبيق في المتصفح للتحقق من أنه متاح.
GitLab

تجهيز إعدادات مشغّل GitLab (منفّذ Docker)​

  1. أنشئ المجلدات اللازمة: mkdir -p /var/apps/gitlab-runner/volumes/etc/gitlab-runner.

  2. أنشئ docker-compose.yaml:

    cat <<EOT > /var/apps/gitlab-runner/docker-compose.yaml
    version: '3'
    services:
      runner:
        image: 'gitlab/gitlab-runner:v16.2.0'
        restart: always
        container_name: 'gitlab-runner'
        privileged: true
        volumes:
          - './volumes/etc/gitlab-runner:/etc/gitlab-runner'
          - '/var/run/docker.sock:/var/run/docker.sock'
    EOT

تسجيل GitLab runner​

  1. افتح Settings → CI/CD → Runners وانقر New project runner.
  2. عيّن الوسمين docker, frontend وأنشئ الـ runner.
  3. انتقل إلى مجلد الـ runner: cd /var/apps/gitlab-runner.
  4. شغّل الأمر لبدء عملية التسجيل: docker compose run runner register.
  5. أدخل رابط GitLab، مثل https://gitlab.com/.
  6. انسخ رمز التسجيل من قسم Runners في المشروع على GitLab والصقه في الطرفية.
  7. عيّن المنفّذ (executor) إلى docker.
  8. عيّن الصورة الافتراضية إلى docker:20.10.16.

تعيين متغيرات البيئة في GitLab​

  1. أنشئ المتغيرات DOMAIN وMTLS_USER_CERT وMTLS_USER_KEY في مستودع GitLab الخاص بك (Settings → CI/CD → Variables).
  2. أنشئ شهادة في OneEntry، وضع الشهادة والمفتاح في المتغيرات، وعيّن DOMAIN إلى عنوان مشروعك بدون https.
  3. نزّل docker-compose.yml وأرشيف .gitlab-ci.yml وأرشيف .docker، وضعها في جذر مشروعك واستخرج الأرشيفات (يمكنك حذفها بعد ذلك).

إعداد مشغّل GitLab​

  1. عدّل ملف الإعدادات: nano volumes/etc/gitlab-runner/config.toml.
  2. عيّن المعامل privileged إلى true لتفعيل Docker-in-Docker.
  3. غيّر قيمة volumes إلى ['/var/run/docker.sock:/var/run/docker.sock', '/cache'] ليعمل Docker بشكل صحيح.
  4. أضف user = 'gitlab-runner' في بداية الملف لتشغيل الـ runner بصلاحيات هذا المستخدم.
  5. احفظ التغييرات واخرج من المحرر.

تشغيل مشغّل GitLab والتحقق منه​

  1. شغّل الـ runner: docker compose up -d.
  2. في GitLab، تحقق من أن المشغّل نشط؛ تظهر حالته في قسم Runners في المشروع.

إعداد مشغّل إضافي على المضيف (منفّذ shell)​

  1. اتبع التعليمات لتثبيت مشغّل إضافي يعمل مباشرة على المضيف، لا في Docker.
  2. عيّن وسوم الـ runner: shell, frontend.

صلاحيات المشغّل​

  1. أضف المستخدم إلى المجموعة: usermod -aG docker gitlab-runner.
  2. لتغيير مالك ملف أو مجلد ومجموعته: chown -R gitlab-runner:docker /var/apps/frontend.

الفحص النهائي​

  1. تأكد من أن جميع المشغّلات مضبوطة وجاهزة.
  2. ادفع التغييرات إلى مستودعك.
  3. تابع التقدم في Build → Pipelines.
  4. افتح التطبيق في المتصفح للتحقق من أنه متاح.