نشر موقع Hugo على AWS S3 باستخدام AWS CLI

نشر موقع Hugo الثابت إلى AWS S3 باستخدام AWS CLI يوفر حلًا قويًا وقابلًا للتوسع لاستضافة موقعك. يغطي هذا الدليل عملية النشر الكاملة، من الإعداد الأولي إلى التحكم المتقدم في التخزين المؤقت.

يصبح استخدام AWS CLI طريقة مفضلة لنشر المواقع المبنية بواسطة Hugo، نظرًا لإزالة أمر deploy من حزمة Hugo القياسية. راجع extended و withdeploy في كيفية تثبيت Ubuntu 24.04 و الأدوات المفيدة إذا كنت تستخدمه محليًا وترغب لا تزال في استخدام hugo deploy.

المتطلبات الأساسية

قبل نشر موقعك المبني على Hugo إلى AWS S3، تأكد من أنك تمتلك:

• موقع Hugo جاهز للنشر (إذا كنت بحاجة إلى مساعدة في إنشاء واحد، راجع دليل البدء السريع لـ Hugo)
• حساب AWS مع الأذونات المناسبة
• AWS CLI مثبت ومُكوّن
• معرفة أساسية بالعمليات عبر سطر الأوامر

بناء موقعك المبني على Hugo

الخطوة الأولى في نشر موقعك المبني على Hugo هي إنشاء الملفات الثابتة. استخدم ورقة الحيل لـ Hugo كمرجع للحصول على أوامر وخيارات متاحة.

ابن موقعك مع العلميات المحسنة:

hugo --gc --minify

العلم --gc يزيل الملفات المؤقتة غير المستخدمة، بينما العلم --minify يضغط HTML وCSS وJavaScript لتحقيق الأداء الأمثل. يقوم هذا بإنشاء موقعك الثابت في الدليل public/، وهو ما سننشره إلى S3.

إعداد AWS CLI

إذا لم تكن قد قمت بتكوين AWS CLI بالفعل، ابدأ بتشغيل:

aws configure

سيتم طلبك إدخال:

• AWS Access Key ID: مفتاح الوصول الخاص بك في AWS
• AWS Secret Access Key: مفتاح الوصول السري الخاص بك
• المنطقة الافتراضية: المنطقة المفضلة لديك في AWS (مثل us-east-1, ap-southeast-2)
• تنسيق الإخراج الافتراضي: json (الموصى به)

للحصول على الوصول البرمجي، تأكد من أن مستخدم IAM الخاص بك لديه أذونات لـ:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket
• cloudfront:CreateInvalidation (إذا كنت تستخدم CloudFront)

إنشاء وتكوين وعاء S3

إنشاء الوعاء

أنشئ وعاء S3 باستخدام AWS CLI:

aws s3 mb s3://اسم-الوعاء-الذي-تريده --region us-east-1

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

تكوين الوعاء لاستضافة المواقع الثابتة

تفعيل استضافة المواقع الثابتة:

aws s3 website s3://اسم-الوعاء-الذي-تريده \
  --index-document index.html \
  --error-document 404.html

تعيين سياسة الوعاء

للحصول على الوصول العام (إذا كنت لا تستخدم CloudFront)، أنشئ سياسة وعاء:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::اسم-الوعاء-الذي-تريده/*"
    }
  ]
}

تطبيق السياسة:

aws s3api put-bucket-policy \
  --bucket اسم-الوعاء-الذي-تريده \
  --policy file://policy.json

ملاحظة أمنية: إذا كنت تستخدم CloudFront (المُوصى به)، يمكنك تقييد الوصول إلى وعاء S3 فقط إلى CloudFront، مما يلغي الحاجة إلى الوصول العام.

نشر المحتوى إلى S3 باستخدام AWS CLI

النطاق الرئيسي للنشر يستخدم aws s3 sync لرفع موقعك:

aws s3 sync public/ s3://اسم-الوعاء-الذي-تريده/ \
  --delete \
  --cache-control max-age=60

شرح المعلمات المهمة

• public/: الدليل المحلي لخرج موقعك المبني على Hugo
• s3://اسم-الوعاء-الذي-تريده/: الوجهة في وعاء S3
• --delete: يحذف الملفات في S3 التي لا توجد محليًا، مما يضمن أن وعاءك يعكس بناءك
• --cache-control max-age=60: يحدد رؤوس التخزين المؤقت (60 ثانية في هذا المثال)

خيارات النسخ المتقدمة

للحصول على سيطرة أكبر على نشرك:

aws s3 sync public/ s3://اسم-الوعاء-الذي-تريده/ \
  --delete \
  --cache-control "public, max-age=31536000, immutable" \
  --exclude "*.html" \
  --cache-control "public, max-age=60" \
  --include "*.html" \
  --exclude "*.js" \
  --cache-control "public, max-age=31536000, immutable" \
  --include "*.js"

هذا المثال يحدد فترات تخزين مؤقت مختلفة للملفات HTML (60 ثانية) مقارنة بموارد ثابتة مثل JavaScript (سنة واحدة)، وهو استراتيجية تحسين شائعة.

إعداد توزيع CloudFront

بينما يمكن لـ S3 استضافة المواقع الثابتة مباشرة، فإن استخدام Amazon CloudFront كـ CDN يوفر أداءً أفضل وأمانًا وانتشارًا عالميًا.

إنشاء توزيع CloudFront

aws cloudfront create-distribution \
  --distribution-config file://cloudfront-config.json

تتضمن تكوين CloudFront الأساسي:

• وعاء S3 كمصدر
• سلوك التخزين المؤقت الافتراضي
• شهادة SSL/TLS (من AWS Certificate Manager)
• تكوين اسم نطاق مخصص (اختياري)

استراتيجيات إدارة التخزين المؤقت

عند النشر عبر CloudFront، تأكد من النظر في هذه الاستراتيجيات:

1. تحديد فترة التخزين المؤقت القصوى: تكوين فترة التخزين المؤقت القصوى في CloudFront للتحكم في مدى تخزين المحتوى في مواقع الحواف
2. نسخ المحتوى: استخدام معرفات الإصدار في أسماء الملفات (مثل style-v2.css) لفرض تحديثات التخزين المؤقت
3. رؤوس التخزين المؤقت: تعيين رؤوس مناسبة أثناء نسخ S3 (كما تم إظهاره أعلاه)
4. إبطال التخزين المؤقت انتقائيًا: إبطال فقط المسارات المُحدثة بدلًا من التخزين المؤقت بالكامل

إبطال التخزين المؤقت

بعد نشر التحديثات، أبطل التخزين المؤقت في CloudFront لعرض المحتوى الجديد:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

لإبطال التخزين المؤقت المحدد:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/index.html" "/blog/*"

ملاحظة التكلفة: أول 1000 مسار لبطال التخزين المؤقت في الشهر مجانًا. بعد ذلك، يكلف كل مسار 0.005 دولار. استخدم إبطال التخزين المؤقت الانتقائي لتقليل التكاليف.

التلقائية مع CI/CD

يعمل النشر اليدوي على مشاريع صغيرة، لكن التلقائية ضروري لتدفق العمل الإنتاجي. يمكنك دمج هذا عملية النشر مع Gitea Actions لنشر موقع Hugo إلى AWS S3 أو أنظمة CI/CD المماثلة.

نموذج بسيط لنص النشر

أنشئ نموذجًا بسيطًا للنشر:

#!/bin/bash
set -e

# بناء موقع Hugo
echo "بناء موقع Hugo..."
hugo --gc --minify

# نشر إلى S3
echo "نشر إلى S3..."
aws s3 sync public/ s3://اسم-الوعاء-الذي-تريده/ \
  --delete \
  --cache-control max-age=60

# إبطال التخزين المؤقت في CloudFront
echo "إبطال التخزين المؤقت في CloudFront..."
aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

echo "تم الانتهاء من النشر!"

اجعله قابلًا للتنفيذ وتشغيله:

chmod +x deploy.sh
./deploy.sh

مثال على GitHub Actions

للمشاريع الموجودة على GitHub، أنشئ ملفًا .github/workflows/deploy.yml:

name: Deploy to AWS S3

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      
      - name: Build
        run: hugo --gc --minify
      
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
      
      - name: Deploy to S3
        run: |
          aws s3 sync public/ s3://اسم-الوعاء-الذي-تريده/ \
            --delete \
            --cache-control max-age=60          
      
      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"          

المراقبة والتحسين

تفعيل السجلات

كوّن سجلات S3 و CloudFront لمراقبة الأنماط:

# تفعيل سجلات الوصول إلى S3
aws s3api put-bucket-logging \
  --bucket اسم-الوعاء-الذي-تريده \
  --bucket-logging-status file://logging.json

إعداد إنذارات CloudWatch

راقب نشرك باستخدام CloudWatch:

aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate \
  --alarm-description "تنبيه عند حدوث معدل أخطاء مرتفع" \
  --metric-name 4xxError \
  --namespace AWS/CloudFront \
  --statistic Sum \
  --period 300 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold

حل المشكلات الشائعة

الملفات لا تتحديث

إذا لم تظهر التحديثات:

1. تحقق من حالة إبطال التخزين المؤقت في CloudFront
2. تأكد من استخدام علم --delete في أمر النسخ
3. نظف ذاكرة التخزين المؤقت للمتصفح أو اختبر في وضع المتصفح المجهول
4. تحقق من أذونات وعاء S3

النشر بطيء

تحسين أداء النسخ:

• استخدم --exclude و --include لتجاوز الملفات غير الضرورية
• فكّر في استخدام --size-only للمقارنات السريعة
• استخدم التحميل المتزامن مع --cli-read-timeout و --cli-write-timeout

أخطاء الأذونات

تأكد من أن مستخدم IAM الخاص بك لديه:

• أذونات الوصول إلى وعاء S3
• أذونات إبطال التخزين المؤقت في CloudFront (إذا كان مناسبًا)
• سياسات وعاء مناسبة مكوّنة

ملخص الممارسات المثلى

1. استخدم دائمًا --delete للحفاظ على توافق S3 مع بناءك المحلي
2. حدد رؤوس التخزين المؤقت المناسبة بناءً على أنواع الملفات
3. استخدم CloudFront لتدفق العمل الإنتاجي
4. تلقائي النشر مع أنظمة CI/CD
5. راقب التكاليف - كن مدركًا لتكاليف إبطال التخزين المؤقت في CloudFront
6. نسخ إصداراتك - أضف إصدارات لسهولة التراجع
7. اختبر محليًا أولًا - تحقق من بناء موقعك قبل النشر

الموارد ذات الصلة

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

عند كتابة محتواك، تأكد من استخدام كتل الكود في Markdown لل أمثلة الكودية، وراجع ورقة الحيل الشاملة لـ Markdown للحصول على إرشادات التنسيق.

روابط مفيدة

• نشر الموقع المُنشأ بواسطة Hugo إلى AWS S3
• استخدام Gitea Actions لنشر موقع Hugo إلى AWS S3
• ورقة الحيل لـ Hugo
• ورقة الحيل الشاملة لـ Markdown
• استخدام كتل الكود في Markdown

المراجع الخارجية

• مستندات استضافة المواقع الثابتة في AWS S3
• مراجع أوامر AWS CLI لـ S3
• أفضل الممارسات لتحكم التخزين المؤقت في CloudFront
• مستندات Hugo الرسمية
• دليل إبطال التخزين المؤقت في CloudFront