آموزش نصب و پیکربندی Caddy روی Ubuntu 26.04 (HTTPS خودکار)

دسته بندی: آموزش بازدیدها: 10 بازدید نظرات: 0 نظر زمان مطالعه: 10 دقیقه
آنچه در این مطلب می‌خوانید:

وقتی یک وب‌سایت را منتشر می‌کنید یا یک اپلیکیشن را پشت یک Reverse Proxy قرار می‌دهید، پیکربندی HTTPS اغلب بیشتر از نصب خودِ وب‌سرور زمان می‌برد. Caddy در بیشتر سناریوها، صدور گواهی (certificate)، تمدید آن و ریدایرکت HTTP به HTTPS را به‌صورت کاملاً خودکار انجام می‌دهد.

صدور خودکار گواهی HTTPS توسط Caddy روی سرور

به‌محض اینکه دامنه‌ی شما به سرور اشاره کند، معمولاً یک Caddyfile کوتاه برای سرو کردن سایت روی HTTP/2 و HTTP/3 کافی است. در این راهنما یاد می‌گیرید چطور Caddy را روی Ubuntu 26.04 از مخزن رسمی APT نصب کنید، یک سایت استاتیک سرو کنید، یک Reverse Proxy تنظیم کنید و سرویس را با systemd مدیریت کنید.

مرجع سریع (Quick Reference)

کار دستور (Command)
نصب Caddy sudo apt install caddy
ویرایش پیکربندی sudo nano /etc/caddy/Caddyfile
Reload پیکربندی sudo systemctl reload caddy
Restart کردن Caddy sudo systemctl restart caddy
بررسی وضعیت (status) sudo systemctl status caddy
اعتبارسنجی Caddyfile sudo caddy validate --config /etc/caddy/Caddyfile
فرمت‌کردن Caddyfile sudo caddy fmt --overwrite /etc/caddy/Caddyfile
مشاهده‌ی لاگ‌ها (logs) sudo journalctl -u caddy -f

پیش‌نیازها (Prerequisites)

پیش از شروع، مطمئن شوید که موارد زیر را در اختیار دارید:

  • یک سرور Ubuntu 26.04 با کاربری که دسترسی sudo دارد. (برای تهیه سرور می‌توانید به صفحه‌ی سرور مجازی لینوکس ایران یا سرور مجازی آلمان سر بزنید.)
  • یک نام دامنه (domain) با رکورد A یا AAAA که به سرور اشاره کند، در صورتی که گواهی HTTPS معتبرِ عمومی می‌خواهید. مدیریت رکوردها از طریق سرویس DNS انجام می‌شود.
  • پورت‌های TCP شماره 80 و 443 در فایروال سرور و فایروال سطح ارائه‌دهنده باز باشند.

اگر از UFW استفاده می‌کنید، با دستورهای زیر ترافیک HTTP و HTTPS را مجاز کنید:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Caddy از HTTP/3 روی UDP پشتیبانی می‌کند. اگر می‌خواهید کلاینت‌ها از آن استفاده کنند، پورت UDP شماره 443 را هم باز کنید:

sudo ufw allow 443/udp

نکته: اگر فقط می‌خواهید Caddy را به‌صورت محلی (local) تست کنید، از یک آدرس صریحِ HTTP مثل http://localhost یا یک پورت غیراستاندارد مثل :8080 در Caddyfile استفاده کنید. در این حالت Caddy، HTTPS خودکار را برای آن آدرس فعال نمی‌کند.

نصب Caddy از مخزن رسمی

پروژه‌ی Caddy یک مخزن رسمی APT روی Cloudsmith نگه‌داری می‌کند. از همان برای نصب نسخه‌ی پایدارِ فعلی و دریافت به‌روزرسانی‌های آینده از طریق APT استفاده می‌کنیم.

ابتدا پکیج‌های پیش‌نیاز را نصب کنید:

sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

کلید امضای (signing key) Caddy را اضافه کنید:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

مخزن APT مربوط به Caddy را اضافه کنید:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list

هر دو فایلِ مخزن را برای APT قابل‌خواندن کنید:

sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list

ایندکس پکیج‌ها را به‌روز کرده و Caddy را نصب کنید:

sudo apt update
sudo apt install -y caddy

این پکیج، باینری را در مسیر /usr/bin/caddy نصب می‌کند، کاربر سیستمیِ caddy را می‌سازد، یک پیکربندی پیش‌فرض در /etc/caddy/Caddyfile اضافه می‌کند و یونیت systemd با نام caddy.service را نصب می‌کند.

نسخه‌ی نصب‌شده را نمایش دهید:

caddy version

سپس مطمئن شوید که سرویس در حال اجراست:

sudo systemctl status caddy

خروجی وضعیت باید active (running) را نشان دهد. برای خروج از صفحه‌ی status کلید q را بزنید.

می‌توانید سایت پیش‌فرض را هم مستقیماً از سرور درخواست کنید:

curl -I http://localhost

یک نصب درست، پاسخ HTTP 200 OK برمی‌گرداند و در هدرها Server: Caddy دیده می‌شود. همچنین می‌توانید آدرس IP سرور را در مرورگر باز کنید تا صفحه‌ی پیش‌فرض را ببینید.

سرو کردن یک سایت استاتیک

Caddy پیکربندی خود را از /etc/caddy/Caddyfile می‌خواند. فایل پیش‌فرض، محتوا را از /usr/share/caddy روی پورت 80 سرو می‌کند.

پیش از تغییر آن، یک نسخه‌ی پشتیبان (backup) بگیرید:

sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.backup

سپس Caddyfile را باز کنید:

sudo nano /etc/caddy/Caddyfile

محتوای آن را با بلاکِ سایتِ زیر جایگزین کنید. example.com را به دامنه‌ی خودتان تغییر دهید:

example.com {
    root * /var/www/example.com
    file_server
}

دامنه‌ای که در خط اول است، آدرس سایت (site address) محسوب می‌شود. Caddy از آن برای دریافت گواهی، ریدایرکت درخواست‌های HTTP به HTTPS و سرو امنِ سایت استفاده می‌کند. به یک بلاک certificate جداگانه یا دستور listen نیازی ندارید.

پوشه‌ی ریشه‌ی سند (document root) را بسازید و یک صفحه‌ی تست اضافه کنید:

sudo mkdir -p /var/www/example.com
echo "
Hello from Caddy
" | sudo tee /var/www/example.com/index.html
sudo chmod -R a+rX /var/www/example.com

سرویس Caddy فقط به دسترسی خواندن (read) روی فایل‌های استاتیک نیاز دارد. نگه‌داشتن مالکیت فایل‌ها به‌نام کاربر استقرار (deployment user) یا root، مانع از این می‌شود که فرایند وب‌سرور بتواند آن‌ها را تغییر دهد.

پیش از اعمال پیکربندی جدید، آن را اعتبارسنجی (validate) کنید:

sudo caddy validate --config /etc/caddy/Caddyfile

اگر دستور خطایی گزارش نکرد، Caddy را reload کنید:

sudo systemctl reload caddy

دستور reload، Caddyfile جدید را بدون متوقف‌کردن سرویس اعمال می‌کند. سپس Caddy یک گواهی درخواست می‌کند و ترافیک HTTP را به HTTPS ریدایرکت می‌کند. اگر DNS به سرور اشاره کند و پورت‌های 80 و 443 قابل‌دسترس باشند، صدور گواهی معمولاً ظرف چند ثانیه کامل می‌شود. برای آشنایی بیشتر با گواهی‌ها می‌توانید به صفحه‌ی گواهی SSL مراجعه کنید.

افزودن یک Reverse Proxy

نمودار عملکرد Reverse Proxy در Caddy؛ هدایت ترافیک کاربر به اپلیکیشن backend

Caddy اغلب جلوی یک اپلیکیشن که روی همان سرور اجرا می‌شود قرار می‌گیرد. برای مثال، اگر یک اپلیکیشن Node.js یا Python روی 127.0.0.1:3000 گوش می‌دهد، از این Caddyfile استفاده کنید:

app.example.com {
    reverse_proxy 127.0.0.1:3000
}

با این پیکربندی، Caddy کارِ HTTPS را مدیریت می‌کند و درخواست‌ها را به اپلیکیشن فوروارد می‌کند. همچنین هدرِ Host ورودی را عبور می‌دهد، هدرهای رایج X-Forwarded-* را تنظیم می‌کند و بدون دستور اضافه از اتصال‌های WebSocket پشتیبانی می‌کند.

برای proxy کردن یک مسیر فرعی (subpath)، دستور را محدود (scope) کنید:

example.com {
    root * /var/www/example.com
    file_server
    handle /api/* {
        reverse_proxy 127.0.0.1:3000
    }
}

درخواست‌های زیرِ /api/ با همان پیشوند /api به اپلیکیشن ارسال می‌شوند. سایر درخواست‌ها همچنان از file server استاتیک استفاده می‌کنند. اگر اپلیکیشن به‌جای /api/users انتظار /users را دارد، handle را با handle_path جایگزین کنید تا پیشوند منطبق پیش از proxy حذف شود.

پس از تغییر، پیکربندی را validate و reload کنید:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

میزبانی چند سایت (Multiple Sites)

میزبانی همزمان چند دامنه و ساب‌دامنه از یک سرور با Caddy

می‌توانید چندین دامنه و ساب‌دامنه را از یک Caddyfile میزبانی کنید. برای هر hostname یک بلاک سایت اضافه کنید:

example.com {
    root * /var/www/example.com
    file_server
}

blog.example.com {
    root * /var/www/blog
    file_server
    encode gzip
}

api.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy برای هر hostname واجد شرایط، یک گواهی دریافت و تمدید می‌کند. برخلاف ساختار sites-available در Nginx، این پیکربندی به مرحله‌ی جداگانه‌ی symlink نیاز ندارد.

هر چه تعداد سایت‌ها بیشتر شود، می‌توانید پیکربندی را با دستور import بین چند فایل تقسیم کنید:

import /etc/caddy/sites/*.caddy

پوشه‌ی /etc/caddy/sites را بسازید، سپس برای هر سایت یک فایل .caddy اضافه کنید. پس از افزودن یا حذف هر فایلِ import شده، دستور caddy validate را اجرا کنید.

اعتبارسنجی و فرمت‌کردن Caddyfile

پیش از هر reload، Caddyfile را validate کنید:

sudo caddy validate --config /etc/caddy/Caddyfile

اعتبارسنجی، فایل را parse و ماژول‌های آن را provision می‌کند، بدون اینکه سرور دیگری را اجرا کند. اگر Caddy خطای syntax یا پیکربندی پیدا کند، خط یا دستور مربوطه را گزارش می‌کند.

Caddy یک فرمت‌کننده (formatter) برای تورفتگی و فاصله‌گذاری هم دارد:

sudo caddy fmt --overwrite /etc/caddy/Caddyfile

گزینه‌ی --overwrite فایل را با نسخه‌ی فرمت‌شده جایگزین می‌کند. اگر می‌خواهید تغییرات فرمت را پیش از استقرار بررسی کنید، فایل را مرور کنید یا آن را در version control نگه دارید.

مدیریت Caddy با systemd

مدیریت سرویس Caddy و مشاهده لاگ‌ها با systemd

این پکیج، Caddy را به‌عنوان یک سرویس systemd با نام caddy.service اجرا می‌کند. برای کنترل آن از این دستورها استفاده کنید:

sudo systemctl start caddy
sudo systemctl stop caddy
sudo systemctl restart caddy
sudo systemctl reload caddy
sudo systemctl status caddy

برای تغییرات Caddyfile، به‌جای restart از reload استفاده کنید. reload پیکربندی جدید را از طریق admin API خودِ Caddy و بدون قطع اتصال‌های فعال اعمال می‌کند.

این پکیج معمولاً سرویس را هنگام نصب فعال (enable) می‌کند. اگر غیرفعال شده بود، دوباره با این دستور فعالش کنید:

sudo systemctl enable caddy

مشاهده‌ی لاگ‌های Caddy

Caddy لاگ‌های runtime و سرویس خود را در journal مربوط به systemd می‌نویسد. ورودی‌های جدید را با journalctl دنبال کنید:

sudo journalctl -u caddy -f

لاگ‌گیریِ دسترسی (access logging) جداست و به‌صورت پیش‌فرض فعال نیست. برای نوشتن access log با فرمت JSON در یک فایل، یک دستور log به بلاک سایت اضافه کنید:

example.com {
    root * /var/www/example.com
    file_server
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

پوشه‌ی لاگ را یک‌بار با مالکیت درست بسازید:

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

پس از validate کردن تغییر، Caddy را reload کنید. Caddy به‌صورت پیش‌فرض access log های فایلی را rotate می‌کند و خروجی JSON را می‌توان با ابزارهای جمع‌آوری لاگ مثل Vector، Loki یا Elasticsearch خواند.

به‌روزرسانی Caddy

چون Caddy از یک مخزن APT نصب شده، می‌توانید آن را با جریان عادی پکیج به‌روز کنید:

sudo apt update
sudo apt install --only-upgrade caddy

ارتقای پکیج، Caddyfile و داده‌های Caddy را در /var/lib/caddy حفظ می‌کند. پس از به‌روزرسانی، نسخه‌ی نصب‌شده و وضعیت سرویس را بررسی کنید:

caddy version
sudo systemctl status caddy

رفع اشکال (Troubleshooting)

خطای bind: address already in use روی پورت 80 یا 443

یک وب‌سرور دیگر (اغلب Apache یا نصب قبلیِ Nginx) از قبل روی آن پورت گوش می‌دهد. سرویس متداخل را با sudo systemctl stop apache2 یا sudo systemctl stop nginx متوقف کنید، سپس Caddy را اجرا کنید.

صدور گواهی شکست می‌خورد

Caddy برای چالش HTTP به دسترسی ورودی روی پورت 80، یا برای چالش TLS-ALPN به پورت 443 نیاز دارد. مطمئن شوید فایروال هر دو را مجاز می‌کند، هر رکورد A یا AAAA به همین سرور اشاره می‌کند و هیچ proxy دیگری درخواست اعتبارسنجی را رهگیری نمی‌کند. لاگِ journal (دستور journalctl -u caddy) خطای دقیق ACME را نشان می‌دهد.

خطای permission denied هنگام خواندن ‎/var/www/…

Caddy به‌جای root با کاربر caddy اجرا می‌شود. فایل‌های زیر document root باید قابل‌خواندن و پوشه‌های والد باید قابل‌اجرا (executable) باشند. دستور sudo chmod -R a+rX /var/www/example.com را اجرا کنید و اگر خطا ادامه داشت، هر پوشه‌ی والد را بررسی کنید.

Caddyfile معتبر است اما سایت در دسترس نیست

بررسی کنید که بلاک سایت دقیقاً همان hostname درخواست‌شده توسط مرورگر را استفاده می‌کند. DNS را با getent hosts example.com تست کنید، سپس با curl -v https://example.com اتصال و پاسخ را بررسی کنید.

درخواست‌های HTTP به HTTPS ریدایرکت نمی‌شوند

HTTPS خودکار وقتی غیرفعال می‌شود که آدرس سایت با http:// شروع شود یا فقط شامل یک پورت HTTP باشد. در Caddyfile به‌جای http://example.com از example.com استفاده کنید، پیکربندی را validate کنید و journal را برای خطاهای گواهی بررسی کنید.

جمع‌بندی

به‌محض اینکه Caddy در حال اجرا باشد، بیشتر کارهای روزمره در /etc/caddy/Caddyfile انجام می‌شود. هر تغییر را پیش از reload کردن validate کنید و پورت‌های 80 و 443 را در دسترس نگه دارید تا Caddy بتواند گواهی صادر کند و بازدیدکنندگان را به HTTPS ریدایرکت کند. برای اجرای این آموزش به یک بستر پایدار نیاز دارید؛ مجموعه‌ی سرورهای مجازی پارس آپتایم با منابع اختصاصی، گزینه‌ی مناسبی برای میزبانی Caddy است.

مطالعه این مطالب را هم توصیه میکنیم

خدمات مورد نیاز شما را با کیفیتی که انتظار دارید و قیمتی که انتظار ندارید.

آیا این مطلب برای شما مفید بود؟

ثبت دیدگاه

آدرس ایمیل شما منتشر نخواهد شد. فیلدهای الزامی با * مشخص شده‌اند.

برای جلوگیری از اسپم، حاصل جمع زیر را وارد کنید:

چهار به‌علاوه هشت چند می‌شود؟
پارس آپتایم | ارائه‌دهنده VPS و میزبانی وب