Nginx · فصل ۱Nginx · Chapter 1

نصب و ساختار فایل‌ها

Installation and file layout

Nginx نصب شده، صفحهٔ پیش‌فرضش هم باز می‌شود؛ اما اگر فردا لازم باشد یک تغییر کوچک بدهی، کدام فایل را باید دست بزنی؟ این فصل کمک می‌کند قبل از ویرایش، بفهمی کدام باینری و کدام درخت پیکربندی واقعاً در حال استفاده است.

Nginx is installed, and its default page opens. But if you need to make one small change tomorrow, which file should you edit? This chapter helps you identify the binary and configuration tree actually in use before you touch anything.

۶۵دقیقهٔ مطالعهminutes

۱۸تمرین با پاسخsolved exercises

۱نقشهٔ فایل‌هاfile map

۰پیش‌نیاز NginxNginx prerequisites

یک تغییر کوچک، دو نصب متفاوتOne small change, two different installations

فرض کن روی VPS صفحهٔ خوش‌آمدگویی Nginx دیده می‌شود. راهنمایی را پیدا می‌کنی، فایل /usr/local/nginx/conf/nginx.conf را ویرایش می‌کنی، سرویس را reload می‌کنی و… هیچ تغییری نمی‌بینی. شاید Nginx فرمانت را نادیده گرفته باشد؟ نه لزوماً؛ ممکن است اصلاً فایلِ نصب دیگری را ویرایش کرده باشی.

Suppose the Nginx welcome page appears on your VPS. You find a guide, edit /usr/local/nginx/conf/nginx.conf, reload the service, and… nothing changes. Did Nginx ignore you? Not necessarily. You may have edited a file belonging to a different installation.

Nginx می‌تواند از بستهٔ خود توزیع لینوکس نصب شود، یا از مخزن رسمی nginx.org، یا از سورس ساخته شود. ممکن است هر سه روش باینری را در مسیر متفاوتی بگذارند و فایل اصلی پیکربندی را جای دیگری دنبال کنند. پس قبل از پرسیدن «کدام فایل را تغییر بدهم؟» سؤال دقیق‌تر این است: «این سرویس با کدام باینری و کدام فایل پیکربندی بالا آمده؟»

Nginx may come from the Linux distribution’s package, the official nginx.org repository, or a source build. Those methods can place the binary in different locations and use different configuration paths. So before asking “Which file should I edit?”, ask the more useful question: “Which binary and configuration file did this service actually start with?”

قاعدهٔ این فصلThe rule for this chapter

اسم یک مسیر در یک مقاله، مدرکِ مسیر فعال سرور تو نیست. اول از خود سیستم مدرک می‌گیریم؛ بعد فایل را تغییر می‌دهیم.

A path mentioned in an article is not evidence of your server’s active path. We will ask the system first, then edit a file.

نصب: بستهٔ توزیع یا مخزن رسمی؟Installation: distribution package or official repository?

برای تمرین این فصل یک Ubuntu یا Debian تمیز لازم داریم؛ VM محلی هم کافی است. مسیر اصلی را با بستهٔ خود توزیع جلو می‌بریم، چون ساده و مناسب شروع است. این انتخاب یعنی Nginx از چرخهٔ به‌روزرسانی همان توزیع می‌آید؛ لزوماً به این معنا نیست که همیشه تازه‌ترین نسخهٔ بالادستی را می‌گیری.

You need a clean Ubuntu or Debian machine; a local VM is enough. Our main path uses the distribution package because it is a straightforward place to begin. That means Nginx follows the distribution’s package updates; it does not necessarily mean you get the newest upstream release immediately.

روی ماشین آزمایشی، فهرست بسته‌ها را به‌روز و Nginx را نصب کن. این دو فرمان چیزی را دربارهٔ پیکربندی سفارشی نمی‌کنند؛ فقط بسته و فایل‌های سرویس را فراهم می‌کنند.

On the test machine, refresh the package index and install Nginx. These commands do not create your custom site configuration; they install the package and service files.

Ubuntu / Debian shell

sudo apt update
sudo apt install nginx

اگر نصب بی‌خطا تمام شد، هنوز فقط می‌دانیم بسته نصب شده. برای اینکه ببینیم سرویس واقعاً فعال است، وضعیت systemd را می‌خوانیم:

A successful installation tells us only that the package was installed. To check whether the service is actually active, inspect its systemd state:

check service state

systemctl status nginx --no-pager
● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (.../nginx.service; enabled; preset: enabled)
     Active: active (running) since ...

خط مهم Active: active (running) است: systemd سرویس را در حال اجرا می‌بیند. این خط ثابت نمی‌کند که صفحهٔ درست سرو می‌شود، درخواست از اینترنت می‌رسد یا پیکربندی‌ای که تو در ذهن داری فعال است. برای این‌ها مدرک جدا می‌خواهیم. اگر وضعیت failed بود، همین‌جا خروجی کامل را بخوان؛ هنوز وقت restart تصادفی نیست.

The useful line is Active: active (running): systemd sees the service running. It does not prove that the intended page is being served, that requests can reach it from the internet, or that the configuration you have in mind is active. Each needs separate evidence. If the state is failed, read the full status output before trying a random restart.

حالا خود endpoint محلی را می‌پرسیم. این تست، مسیر شبکهٔ بیرونی یا DNS را دور می‌زند:

Now request the local endpoint. This test avoids external networking and DNS:

local HTTP check

curl -i http://127.0.0.1/
HTTP/1.1 200 OK
Server: nginx
Content-Type: text/html
...
<!DOCTYPE html>...

پاسخ 200 و محتوای HTML می‌گویند روی همین ماشین یک پاسخ HTTP گرفته‌ایم. اگر اتصال رد شد، سرویس، پورت و فرایند گوش‌دهنده را بررسی کن؛ اگر پاسخ 404 بود، Nginx جواب داده ولی فایل یا مسیری که برای درخواست انتخاب شده پیدا نشده است. این‌ها دو نقطهٔ خرابی متفاوت‌اند.

A 200 and HTML body show that this machine returned an HTTP response. If the connection is refused, check the service, port, and listener. If the response is 404, Nginx answered but could not find the file or path selected for the request. Those are different failure points.

بستهٔ توزیع چه فرقی با بستهٔ nginx.org دارد؟How does the distribution package differ from nginx.org’s package?

اگر به نسخه یا ماژولی نیاز داری که بستهٔ توزیع فراهم نمی‌کند، مخزن رسمی Nginx گزینهٔ دیگری است. این انتخاب باید آگاهانه باشد: منبع بسته و روش به‌روزرسانی عوض می‌شود و احتمالاً مسیرها یا جزئیات بسته‌بندی هم فرق می‌کنند. راهنمای رسمی nginx.org برای Debian و Ubuntu، افزودن کلید امضای مخزن و تعریف مخزن را توضیح می‌دهد؛ کلید را کورکورانه از یک آدرس ناشناس نگیری و دستورهای آن راهنما را با نسخهٔ واقعی توزیعت تطبیق بده.

If you need a version or module not supplied by your distribution package, the official Nginx repository is another option. Make that choice deliberately: the package source and update path change, and packaging details or paths may differ. Nginx’s official instructions for Debian and Ubuntu explain how to add the signing key and repository. Do not trust a key fetched from an unknown source, and match the instructions to your actual distribution release.

مسیر نصبInstall path	چه زمانی؟When?	نکتهٔ مهمImportant caveat
بستهٔ توزیعDistribution package	شروع معمول روی سرور Ubuntu/DebianA normal starting point on Ubuntu/Debian	نسخه و زمان به‌روزرسانی را توزیع تعیین می‌کند.The distribution controls package versions and update timing.
مخزن رسمی nginx.orgOfficial nginx.org repository	وقتی نسخه یا بستهٔ رسمی مشخصی لازم داریWhen you need a particular upstream version or package	مخزن و کلید امضا را طبق راهنمای رسمی همان سیستم تنظیم کن.Configure the repository and signing key using its official instructions.
ساخت از سورسBuild from source	نیاز ویژه‌ای داری که بسته برآورده نمی‌کندYou have a specific need packages do not meet	مسئولیت build، نصب، سرویس و به‌روزرسانی بیشتر می‌شود.You take on more responsibility for builds, service setup, and updates.

قبل از ویرایش، نصب فعال را پیدا کنIdentify the active installation before editing

در یک نصب معمول بسته‌ای، ممکن است فرمان nginx در PATH با باینری مورد استفادهٔ systemd یکی باشد؛ اما در سروری که چند نصب یا override دارد، این را حدس نمی‌زنیم. اول مسیر فرمان و مشخصات build را می‌خوانیم.

In a typical package installation, the nginx command found through PATH may be the same binary systemd uses. On a host with multiple installations or service overrides, we should not guess. First inspect the command path and build details.

binary and build details

command -v nginx
/usr/sbin/nginx

nginx -V
nginx version: nginx/1.x.x
built with ...
configure arguments: ... --conf-path=/etc/nginx/nginx.conf ...

در nginx -V، بخش --conf-path سرنخ مسیر پیش‌فرض nginx.conf برای همین باینری است؛ command -v هم می‌گوید shell کدام فایل اجرایی را پیدا کرده. خروجی واقعی نسخه‌ات متفاوت است. هنوز فرمان اجرایی systemd را ندیده‌ایم، پس واحد سرویس را هم بررسی می‌کنیم:

In nginx -V, --conf-path is a clue to this binary’s default nginx.conf; command -v shows which executable the shell found. Your version will differ. We have not yet inspected systemd’s launch command, so check the service unit too:

systemd unit

systemctl cat nginx
# /lib/systemd/system/nginx.service
ExecStartPre=/usr/sbin/nginx -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/sbin/nginx -g 'daemon on; master_process on;' -s reload

این خروجی نمونه است؛ مسیر و گزینه‌های واقعی روی میزبان تو ملاک‌اند. اگر ExecStart گزینهٔ -c داشته باشد، فایل پیکربندی دیگری معرفی شده؛ -p هم prefix را تغییر می‌دهد. اگر واحد drop-in یا override دارد، همان هم بخشی از شواهد است. systemctl cat فایل پایه و overrideهای شناخته‌شده را نشان می‌دهد.

This is representative output; your host’s actual paths and options are what matter. If ExecStart contains -c, it selects another configuration file; -p changes the prefix. A unit drop-in or override is also evidence. systemctl cat shows the base unit and known overrides.

حالا فایل اصلیِ پیدا‌شده را آزمایش و درخت include را چاپ می‌کنیم:

Now test the identified main file and print its include tree:

validate and print configuration

sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

sudo nginx -T
# configuration file /etc/nginx/nginx.conf:
... include /etc/nginx/conf.d/*.conf;
... include /etc/nginx/sites-enabled/*;
# configuration file /etc/nginx/sites-enabled/default:
...

-t نحو پیکربندی را بررسی می‌کند و بازشدن فایل‌های ارجاع‌شده را هم می‌آزماید؛ -T همین آزمون را انجام می‌دهد و متن پیکربندیِ بارشده را هم چاپ می‌کند. دنبال سرآیندهای # configuration file ... و خط‌های include بگرد. -T نمایی از فایل‌هایی است که این اجرای CLI خوانده؛ اگر سرویس با باینری یا گزینه‌های متفاوت بالا آمده باشد، باید اختلاف را حل کنی و صرفاً به خروجی این فرمان تکیه نکنی.

-t checks configuration syntax and attempts to open referenced files. -T does the same test and also prints the loaded configuration text. Look for # configuration file ... headers and include lines. -T shows what this CLI invocation reads; if the service starts with a different binary or options, reconcile that difference instead of trusting this output alone.

حواست به خروجی باشدWatch what the output contains

nginx -T ممکن است بخش بزرگی از تنظیمات را چاپ کند. آن را قبل از اشتراک‌گذاری عمومی بازبینی کن؛ فایل‌های پیکربندی گاهی اطلاعات داخلی یا مقدارهایی دارند که نباید بی‌دلیل منتشر شوند.

nginx -T may print a large configuration dump. Review it before sharing publicly; configuration files can contain internal details or values that should not be exposed casually.

از باینری تا فایلی که پاسخ را می‌سازدFrom the binary to the file that becomes the response

این نقشه نمی‌گوید همهٔ توزیع‌ها همین نام پوشه‌ها را دارند. می‌گوید دنبال چه رابطه‌ای بگردی: باینری، فایل اصلی، فایل‌های include‌شده، یک server block و در نهایت ریشه‌ای که فایل‌های صفحه از آن خوانده می‌شوند.

This map does not claim that every distribution uses these exact directory names. It shows which relationships to look for: binary, main file, included files, a server block, and finally the root from which page files are read.

فلش‌ها رابطهٔ بارگذاری پیکربندی را نشان می‌دهند؛ درخواست HTTP در جهت دیگری از ruleها عبور می‌کند و در فصل‌های بعد سراغش می‌رویم.The arrows mean configuration loading. An HTTP request follows the resulting rules in a different direction; we will study that later.

روی بستهٔ معمول Ubuntu، اغلب /etc/nginx/nginx.conf فایل اصلی و /var/www/html ریشهٔ صفحهٔ پیش‌فرض است؛ بعضی بسته‌های Debian/Ubuntu از sites-available و sites-enabled استفاده می‌کنند. این قرارداد همه‌جایی نیست. درخت واقعی را از خروجی nginx -T بخوان، نه از حافظه یا یک تصویر اینترنتی.

On a typical Ubuntu package, /etc/nginx/nginx.conf is the main file and /var/www/html is the default page root; some Debian/Ubuntu packages use sites-available and sites-enabled. This is not universal. Read the actual tree from nginx -T, not from memory or an internet diagram.

صفحه را عوض کن، بعد همان مسیر را دوباره بسنجChange the page, then verify the same path again

حالا که ریشهٔ فعال را از پیکربندی پیدا کرده‌ای، یک صفحهٔ کوچک دوزبانه می‌گذاریم. در نصب رایج Ubuntu، مقصد /var/www/html/index.html است؛ اگر خروجی تو چیز دیگری می‌گوید، مقصد واقعی را جایگزین کن. فقط در VM آزمایشی یا محیطی که اجازهٔ تغییرش را داری ادامه بده.

Now that you have found the active root, place a tiny bilingual page there. On a typical Ubuntu install, the path is /var/www/html/index.html; if your output shows another root, substitute that path. Continue only on a test VM or a machine you are authorized to change.

write a small test page

sudo tee /var/www/html/index.html >/dev/null <<'HTML'
<!doctype html>
<html lang="fa" dir="rtl">
<meta charset="utf-8">
<title>Nginx آماده است</title>
<h1>Nginx جواب می‌دهد</h1>
<p>صفحهٔ آزمایشی از ریشهٔ فعال سرو می‌شود.</p>
<hr>
<h1 lang="en" dir="ltr">Nginx is responding</h1>
<p lang="en" dir="ltr">A test page from the active document root.</p>
HTML

این فقط یک فایل HTML است و معمولاً نیازی به restart یا حتی reload ندارد؛ Nginx فایل را هنگام درخواست می‌خواند. همان درخواست محلی را دوباره بفرست تا هم status و هم متن صفحه را ببینی:

This is just an HTML file, so it normally needs neither a restart nor a reload; Nginx reads it when the request arrives. Repeat the same local request and check both the status and page text:

verify response body

curl -i http://127.0.0.1/
HTTP/1.1 200 OK
...
<h1>Nginx is responding</h1>

اگر هنوز صفحهٔ پیش‌فرض را می‌بینی، حدس نزن که cache مقصر است. اول بررسی کن فایل را در همان document root نوشته‌ای که server block انتخاب‌شده استفاده می‌کند؛ بعد با nginx -T ببین کدام فایل و بلوک فعال است. یک 200 به‌تنهایی ثابت نمی‌کند صفحهٔ موردنظر تو پاسخ داده شده؛ متن بدنه هم بخشی از آزمون است.

If the default page still appears, do not immediately blame a cache. First confirm that you wrote to the document root used by the selected server block; then use nginx -T to see which file and block are active. A 200 alone does not prove that your intended page was returned; the response body is part of the test.

یک خطای بی‌خطر: قبل از reload، پیکربندی را بیازماA harmless fault: test configuration before reloading

فرض کن بعداً directive تازه‌ای اضافه کرده‌ای و صفحه دیگر درست جواب نمی‌دهد. به‌جای restart، اول سؤال کوچک‌تری می‌پرسیم: آیا همین باینری می‌تواند همین درخت پیکربندی را بخواند؟ nginx -t برای همین بررسی است.

Suppose you later add a directive and the site stops behaving as expected. Instead of restarting, ask a smaller question first: can this binary parse this configuration tree? That is what nginx -t checks.

برای دیدن خطا، فایل موقت و جداگانه می‌سازیم؛ پیکربندی زنده را خراب نمی‌کنیم. این نمونه عمداً ناقص است و فقط برای دیدن تشخیص parser است:

To see the error, create a separate temporary file; do not break the live configuration. This sample is intentionally invalid and exists only to observe the parser’s diagnosis:

isolated syntax-test file

sudo tee /tmp/nginx-codenames-broken.conf >/dev/null <<'NGINX'
events {}
http {
    server {
        listen 8088;
        server_name localhost;
        this_directive_does_not_exist on;
    }
}
NGINX

sudo nginx -t -c /tmp/nginx-codenames-broken.conf
nginx: [emerg] unknown directive "this_directive_does_not_exist" in /tmp/nginx-codenames-broken.conf:6
nginx: configuration file /tmp/nginx-codenames-broken.conf test failed

مدرک، نام directive و شمارهٔ خط است؛ این خطا پیش از reload سرویس پیدا شد. چون از -c استفاده کردیم، فایل فعال را دست نزدیم. حالا همان فایل آزمایشی را کنار می‌گذاریم و سلامت پیکربندی فعال را جداگانه می‌سنجیم:

The evidence is the unknown directive and line number; the error was caught before reloading the service. Because we used -c, the active file was untouched. Set the test file aside and validate the active configuration separately:

back to active configuration

sudo rm /tmp/nginx-codenames-broken.conf
sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

خط دوم باید دوباره مسیر واقعی خودش را نشان بدهد. اگر تست فعال شکست خورد، خروجی کامل را نگه دار و فایل و خط مشخص‌شده را بررسی کن؛ restart کردن، syntax error را درست نمی‌کند.

The second command should report its actual active path again. If the active test fails, keep the full output and inspect the named file and line; restarting does not fix a syntax error.

reload با restart یکی نیستReload is not the same as restart

وقتی فایل‌های پیکربندی را تغییر دادی، اول nginx -t؛ اگر سالم بود، از systemd بخواه تنظیمات را reload کند. reload معمولاً workerهای تازه را با تنظیمات جدید بالا می‌آورد و workerهای قبلی را با فرصت پایان درخواست‌های در حال انجام کنار می‌گذارد. restart سرویس را متوقف و دوباره شروع می‌کند و برای تغییر عادی config معمولاً انتخاب اول نیست.

After changing configuration, run nginx -t first. If it passes, ask systemd to reload the configuration. A reload normally starts new workers with the new configuration and lets old workers finish in-flight requests before exiting. A restart stops and starts the service, so it is usually not the first choice for an ordinary config change.

عملیاتAction	نمونهExample	برای چه کاری؟Use it for
بازخوانی configReload configuration	`sudo systemctl reload nginx`	تغییر معمول تنظیمات؛ پس از `nginx -t`.Ordinary configuration changes, after `nginx -t`.
توقف و شروع دوبارهٔ سرویسStop and start the service	`sudo systemctl restart nginx`	وقتی restart واقعاً لازم است؛ ممکن است وقفهٔ کوتاهی ایجاد کند.When a restart is actually needed; it may cause a brief interruption.

validate, then reload

sudo nginx -t && sudo systemctl reload nginx
... syntax is ok
... test is successful

اگر reload با خطا برگشت، status و journal سرویس را بررسی کن و دوباره curl بزن. پاسخ سالم قبلی ممکن است هنوز با workerهای قبلی تولید شود؛ فقط به پیام «reload موفق» اکتفا نکن. پایان کار یعنی همان درخواست و همان محتوایی که پیش از تغییر سنجیدی، دوباره درست باشد.

If reload returns an error, inspect the service status and journal, then repeat the curl check. A previously working response may still come from old workers; do not stop at a “reload succeeded” message. Completion means the same request and expected content you checked before the change work again.

تمرین‌ها: از حدس به مدرکExercises: replace guesses with evidence

جواب‌ها را قبل از بازکردن پاسخ پیش‌بینی کن. در چند تمرین، یک فرمان درست کافی نیست؛ بگو چه چیزی را ثابت می‌کند و چه چیزی هنوز نامعلوم است.

Predict before opening each solution. In several exercises, one correct command is not enough: say what it proves and what remains unknown.

۱. سرویس بالا هست؛ سایت هم؟1. The service is up; is the site?

خروجی systemctl status nginx می‌گوید active (running). همکارت می‌گوید صفحه باز نمی‌شود. دو بررسی بعدی تو چیست و چرا؟

systemctl status nginx says active (running). A teammate says the page does not open. What two checks would you do next, and why?

پاسخ را ببینShow solution

اول curl -i http://127.0.0.1/ تا پاسخ محلی و status را جدا از مسیر بیرونی بسنجیم؛ بعد اگر محلی جواب داد، پورت و firewall یا مسیر شبکهٔ بیرونی را بررسی می‌کنیم. active بودن فقط وضعیت process تحت مدیریت systemd را می‌گوید، نه دسترسی عمومی را.

First run curl -i http://127.0.0.1/ to separate the local HTTP response from the external path. If local access works, investigate the listener, firewall, and external network path. “Active” describes the systemd-managed process, not public reachability.

۲. کدام روش نصب؟2. Which installation method?

برای یک صفحهٔ ساده روی Ubuntu، بستهٔ توزیع نصب می‌کنی یا سورس را build می‌کنی؟ چه نیاز مشخصی می‌تواند تصمیم را عوض کند؟

For a simple site on Ubuntu, would you install the distribution package or build from source? What concrete need might change your choice?

پاسخ را ببینShow solution

معمولاً بستهٔ توزیع ساده‌تر است و با چرخهٔ نگه‌داری همان سیستم می‌آید. نسخه یا قابلیت خاصی که آن بسته ندارد می‌تواند دلیل بررسی مخزن رسمی Nginx یا build سفارشی باشد؛ صرفاً «حرفه‌ای‌تر به نظر می‌رسد» دلیل فنی نیست.

The distribution package is usually simpler and follows that system’s maintenance cycle. A required version or feature missing from it may justify the official Nginx repository or a custom build; choosing source just because it sounds more advanced is not a technical reason.

۳. مسیر فایل پیکربندی3. Configuration path

nginx -V شامل --conf-path=/etc/nginx/nginx.conf است. این به‌تنهایی ثابت می‌کند systemd همان فایل را استفاده می‌کند؟

nginx -V includes --conf-path=/etc/nginx/nginx.conf. Does that alone prove systemd uses that file?

پاسخ را ببینShow solution

نه. این پیش‌فرض همین باینری را نشان می‌دهد. systemctl cat nginx را بخوان و دنبال مسیر executable و گزینهٔ -c یا -p بگرد؛ بعد همان باینری و گزینه‌ها را با خروجی تست تطبیق بده.

No. It shows this binary’s default. Read systemctl cat nginx, look for the executable path and -c or -p, then reconcile those with the binary and options used for your test.

۴. `-t` یا `-T`؟4. `-t` or `-T`?

می‌خواهی اول فقط بدانی config قابل‌خواندن است یا کل تنظیمات بارشده را برای یافتن include ببینی. کدام گزینه برای هر هدف؟

You first want to know whether the configuration is readable, then inspect all loaded settings to find includes. Which option for each goal?

پاسخ را ببینShow solution

-t برای آزمون؛ -T برای آزمون به‌اضافهٔ چاپ پیکربندی. خروجی -T ممکن است طولانی یا حساس باشد؛ فقط بخش مرتبط را بررسی و پیش از اشتراک‌گذاری بازبینی کن.

-t tests; -T tests and prints the configuration. The -T output can be long or sensitive; inspect the relevant part and review it before sharing.

۵. صفحهٔ پیش‌فرض کجاست؟5. Where is the default page?

روی راهنمایی نوشته /var/www/html، اما پاسخ تو همان صفحهٔ قبلی است. کدام مدرک را جمع می‌کنی؟

A guide says /var/www/html, but your response is still the old page. What evidence do you collect?

پاسخ را ببینShow solution

nginx -T را برای server block بارشده، directive مربوط به root و فایل‌های include‌شده می‌خوانم؛ بعد متن پاسخ را با curl می‌سنجم. مسیر راهنما ممکن است متعلق به بسته یا server block دیگری باشد.

Read nginx -T for the loaded server block, its root, and included files; then compare the response body with curl. The guide’s path may belong to another package or server block.

۶. روی Debian و Ubuntu6. On Debian and Ubuntu

آیا همیشه باید فایل سایت را در sites-available بنویسی؟ دلیل جوابت چیست؟

Must you always create a site file under sites-available? Explain your answer.

پاسخ را ببینShow solution

نه. این الگوی بسته‌بندی/توزیع است، نه قانون خود Nginx. در خروجی nginx -T باید include مربوط را ببینی. اگر وجود ندارد، ساختن فایل در آن پوشه به‌تنهایی چیزی را فعال نمی‌کند.

No. It is a distribution/package convention, not an Nginx requirement. Find the matching include in nginx -T. If it is absent, creating a file there does not make Nginx load it.

۷. آزمون شکست می‌خورد7. The test fails

nginx -t نام یک فایل و شمارهٔ خط را همراه unknown directive نشان می‌دهد. restart قدم بعدی است؟

nginx -t reports a filename, line number, and unknown directive. Is restarting the next step?

پاسخ را ببینShow solution

نه. همان فایل و خط را باز می‌کنم و نام directive یا تایپ را بررسی می‌کنم. آزمون پیش از reload جلوی اعمال config نامعتبر را می‌گیرد؛ restart فقط همان خطا را دوباره با صدای بلندتر اجرا می‌کند.

No. Inspect the named file and line for a typo or invalid directive. Testing before reload prevents applying invalid configuration; a restart merely encounters the same error again.

۸. چرا تغییر صفحه لازم نیست reload شود؟8. Why may a page change need no reload?

فقط محتوای index.html عوض شده، نه فایل config. اول چه چیزی را تکرار می‌کنی؟

Only index.html changed, not the configuration. What do you repeat first?

پاسخ را ببینShow solution

همان curl -i و بررسی بدنه را تکرار می‌کنم. برای محتوای فایل استاتیک معمولاً reload لازم نیست؛ اگر متن قدیمی برگشت، root انتخاب‌شده و مسیر فایل را می‌سنجم.

Repeat the same curl -i check and inspect its body. Static file content normally needs no reload. If old text remains, check the selected root and file path.

۹. ارتباط رد شد9. Connection refused

curl http://127.0.0.1/ می‌گوید connection refused، اما unit نصب است. سه نقطهٔ بررسی؟

curl http://127.0.0.1/ reports connection refused, but the unit is installed. Name three checks.

پاسخ را ببینShow solution

وضعیت سرویس با systemctl status nginx، journal خطا با journalctl -u nginx و پورت/listener واقعی. نصب‌شدن unit به معنی running بودن process یا گوش‌دادن روی port 80 نیست.

Check systemctl status nginx, service errors with journalctl -u nginx, and the actual listener/port. An installed unit does not mean the process is running or listening on port 80.

۱۰. خروجی 40410. A 404 response

از localhost پاسخ HTTP 404 گرفتی. چه چیزی را حالا می‌دانی و بعد چه می‌کنی؟

Localhost returns HTTP 404. What do you know now, and what do you do next?

پاسخ را ببینShow solution

درخواست به یک HTTP server رسیده و پاسخ گرفته؛ پس این با connection refused یکی نیست. server block و مسیر فایل/root انتخاب‌شده را در config بارشده بررسی می‌کنم، سپس فایل و دسترسی خواندن را می‌سنجم.

The request reached an HTTP server and got a response, unlike a refused connection. Inspect the selected server block and file/root path in the loaded configuration, then check the file and read permissions.

۱۱. باینری shell با سرویس یکی نیست؟11. Does the shell binary match the service?

command -v nginx می‌گوید /usr/local/sbin/nginx؛ اما systemctl cat nginx از /usr/sbin/nginx استفاده می‌کند. چرا این مهم است؟

command -v nginx says /usr/local/sbin/nginx, but systemctl cat nginx uses /usr/sbin/nginx. Why does this matter?

پاسخ را ببینShow solution

دو باینری ممکن است نسخه، module و مسیر پیش‌فرض متفاوت داشته باشند. برای تحلیل سرویس، فرمان و گزینه‌های unit را مبنا می‌گیرم و -V را روی همان مسیر اجرا می‌کنم؛ تست باینری دیگر ممکن است config دیگری را بررسی کند.

The binaries may differ in version, modules, and default paths. For the service, use the unit’s executable and options, and run -V on that path. Testing the other binary may inspect another configuration.

۱۲. کدوم‌یکی include شده؟12. Which file is included?

سه فایل در /etc/nginx پیدا کرده‌ای. راه مطمئن برای فهمیدن کدامشان بار می‌شود چیست؟

You found three files under /etc/nginx. How do you determine which one is loaded?

پاسخ را ببینShow solution

از باینری/گزینه‌های سرویس شروع می‌کنم، بعد nginx -T را با همان مسیر و گزینهٔ -c احتمالی اجرا می‌کنم. سرآیندهای filename در خروجی فایل‌های بازشده را نشان می‌دهند؛ صرف حضور فایل روی دیسک یعنی include نشده.

Start with the service’s binary and options, then run nginx -T with the same executable and any relevant -c. Filename headers identify opened files; a file existing on disk does not mean it is included.

۱۳. پس از تغییر config13. After changing configuration

یک تغییر معمولی در server config دادی. ترتیب کم‌ریسک و دلیلش چیست؟

You made an ordinary server configuration change. What is the safer order, and why?

پاسخ را ببینShow solution

اول sudo nginx -t؛ فقط اگر موفق بود sudo systemctl reload nginx؛ سپس همان درخواست را با curl دوباره می‌سنجم. این کار syntax خراب را قبل از reload می‌گیرد و نتیجهٔ واقعی را هم بررسی می‌کند.

Run sudo nginx -t; only if it passes, run sudo systemctl reload nginx; then repeat the same request with curl. This catches invalid syntax before reload and verifies the actual result.

۱۴. reload موفق، صفحه غلط14. Reload succeeded, but the page is wrong

systemd reload را موفق گزارش کرد ولی مرورگر هنوز محتوا را اشتباه نشان می‌دهد. چه چیزی را نباید نتیجه بگیری؟

systemd reports a successful reload, but the browser still shows the wrong content. What must you not conclude?

پاسخ را ببینShow solution

نباید نتیجه بگیرم «پس config حتماً همان سایت را انتخاب می‌کند». reload یعنی سرویس درخواست reload را پذیرفته؛ بررسی می‌کنم درخواست به کدام listener/server block می‌رسد، root کجاست و body واقعی curl چیست.

Do not conclude that the intended site must have been selected. A reload means the service accepted the reload request. Check the listener and selected server block, its root, and the actual curl body.

۱۵. سرویس fail شده15. The service has failed

بعد از نصب وضعیت failed است. پیش از تغییر فایل‌ها، کدام خروجی‌ها را نگه می‌داری؟

After installation the service is failed. Which outputs do you preserve before changing files?

پاسخ را ببینShow solution

systemctl status nginx --no-pager، journalctl -u nginx --no-pager -n 80 و sudo nginx -t. این‌ها می‌توانند خطای parse، permission یا اشغال‌بودن پورت را از هم جدا کنند؛ بعد بر اساس اولین خطای معنادار جلو می‌روم.

Capture systemctl status nginx --no-pager, journalctl -u nginx --no-pager -n 80, and sudo nginx -t. They can distinguish parse errors, permission issues, and port conflicts. Follow the first meaningful failure rather than changing files at random.

۱۶. می‌توانی خروجی `-T` را بفرستی؟16. Can you share `-T` output?

برای کمک گرفتن می‌خواهی کل خروجی را در یک انجمن عمومی بگذاری. قبلش چه می‌کنی؟

You want to post the full output in a public forum to get help. What do you do first?

پاسخ را ببینShow solution

بازبینی و پالایش. -T پیکربندی بارشده را چاپ می‌کند و ممکن است host name داخلی، مسیرها یا مقدارهای حساس را لو بدهد. بخش مرتبط با خطا را با حفظ context کافی جدا می‌کنم و اطلاعات محرمانه را حذف می‌کنم.

Review and redact it. -T prints the loaded configuration and may reveal internal hostnames, paths, or sensitive values. Share only the relevant section with enough context, after removing confidential information.

۱۷. اختلاف بین دو میزبان17. Two hosts disagree

یک config روی لپ‌تاپ جواب می‌دهد و روی VPS نه. به‌جای کپی کورکورانهٔ فایل‌ها، یک مقایسهٔ مرحله‌ای طراحی کن.

A configuration works on your laptop but not on the VPS. Design a step-by-step comparison instead of blindly copying files.

پاسخ را ببینShow solution

روی هر دو، نسخه و مسیر باینری (command -v و -V)، unit فعال (systemctl cat)، آزمون و includeها (-t/-T)، سپس پاسخ محلی و فایل root را مقایسه می‌کنم. اختلاف را پیدا می‌کنم؛ هنوز لازم نیست کل درخت config را جایگزین کنم.

On both hosts, compare binary/version (command -v and -V), the service unit (systemctl cat), test and includes (-t/-T), then the local response and document-root file. Find the difference before replacing an entire configuration tree.

۱۸. بلیت عیب‌یابی18. A troubleshooting ticket

گزارش: «صفحه تغییر نمی‌کند.» systemctl active است و nginx -t موفق. سه مدرک بعدی را به ترتیب بنویس و بگو هر کدام کدام فرض را می‌آزماید.

Ticket: “The page does not change.” systemd is active and nginx -t passes. Name the next three pieces of evidence in order and the hypothesis each tests.

پاسخ را ببینShow solution

۱) systemctl cat nginx و nginx -V: آیا باینری و config درست را می‌آزماییم؟ ۲) بخش مربوط server/root در nginx -T: آیا فایل و بلوک موردنظر بار شده؟ ۳) curl -i و بدنهٔ پاسخ، همراه بررسی فایل روی همان root: آیا درخواست محلی به محتوای موردنظر می‌رسد؟ بعد از هر تغییر همان درخواست را تکرار می‌کنم.

1) systemctl cat nginx and nginx -V: are we testing the right binary and configuration? 2) The relevant server/root section in nginx -T: is the intended file and block loaded? 3) curl -i and its body, plus the file at that root: does the local request return the intended content? Repeat the same request after any fix.

ماموریت: صفحهٔ خودت را از ریشهٔ فعال سرو کنMission: serve your page from the active root

یک VM تمیز داری و باید ثابت کنی صفحه‌ای که ساخته‌ای از نصب فعال Nginx پاسخ داده می‌شود؛ نه از یک فایل تصادفی که فقط روی دیسک افتاده. قبل از شروع، اگر روی VPS واقعی هستی مطمئن شو دسترسی مجاز داری و راه برگشت به سرویس را می‌دانی.

You have a clean VM and must prove your page is served by the active Nginx installation, not merely sitting somewhere on disk. Before starting on a real VPS, make sure you are authorized and know how to restore the service.

نصب کن و مدرک بگیر: نسخه، وضعیت سرویس و پاسخ localhost.Install it and collect evidence: version, service state, and localhost response.
باینری و فایل فعال را با command -v، nginx -V و systemctl cat تطبیق بده.Reconcile the binary and active file using command -v, nginx -V, and systemctl cat.
با nginx -T include و document root را پیدا کن؛ فرض نکن sites-enabled وجود دارد.Use nginx -T to find includes and the document root; do not assume sites-enabled exists.
یک فایل HTML دوزبانه بگذار و با curl -i هم status و هم محتوای بدنه را ثبت کن.Write a bilingual HTML file and record both status and body with curl -i.
پیکربندی موقت خراب را با -c آزمایش کن؛ خطا را بخوان، فایل موقت را پاک کن و تست فعال را دوباره اجرا کن.Test an isolated broken configuration with -c; read the error, remove the temporary file, and test the active config again.
فقط اگر config فعال را تغییر دادی: -t، سپس reload، بعد همان درخواست curl.Only if you changed active config: run -t, then reload, then repeat the same curl request.

اگر جایی گیر کردی، این سرنخ‌ها را یکی‌یکی باز کنOpen these hints one at a time if you get stuck

اگر اتصال رد می‌شود، هنوز سراغ document root نرو؛ اول process و listener. اگر پاسخ 404 است، server block و مسیر فایل را پیدا کن. اگر صفحهٔ قدیمی است، body پاسخ و root فعال را کنار هم بگذار. اگر -t خطا می‌دهد، همان فایل و line را بخوان؛ restart تشخیص نیست.

If the connection is refused, do not start with the document root; check the process and listener. For a 404, inspect the selected server block and file path. For old content, compare the response body with the active root. If -t fails, inspect its file and line; restarting is not a diagnosis.

معیار پایان مأموریتMission acceptance test

یک گزارش کوتاه داشته باش: باینری سرویس، فایل اصلی و include واقعی، وضعیت سرویس، پاسخ curl با متن صفحه، و نتیجهٔ آزمون syntax قبل و بعد از کنارگذاشتن config آزمایشی.

Keep a short report: service binary, actual main file and includes, service state, the curl response and page text, and syntax-test results before and after removing the test configuration.

حالا که فایل را پیدا کردی…Now that you have found the file…

این فصل جواب داد Nginx از کجا آمده و کدام فایل‌ها را می‌خواند. اما هنوز نپرسیده‌ایم چرا یک directive باید داخل http باشد و دیگری در server. فصل بعد config را خط‌به‌خط می‌خواند: contextها، آکولادها و نقطه‌ویرگول‌ها.

This chapter answered where Nginx came from and which files it reads. We have not yet asked why one directive belongs inside http and another inside server. Next, we will read configuration line by line: contexts, braces, and semicolons.

پرسشQuestion	مدرک مناسبUseful evidence	محدودیت مدرکWhat it does not prove
سرویس زنده است؟Is the service running?	`systemctl status nginx`	درستی پاسخ HTTP را ثابت نمی‌کند.Does not prove the HTTP response is correct.
کدام فایل‌ها خوانده می‌شوند؟Which files are loaded?	`nginx -T` با باینری/گزینه‌های درست	به‌تنهایی ثابت نمی‌کند درخواست به کدام server block می‌رسد.Does not alone prove which server block receives a request.
پیکربندی قابل‌قبول است؟Is configuration acceptable?	`nginx -t`	محتوای صفحه یا مسیر بیرونی شبکه را نمی‌سنجد.Does not check page content or external network reachability.
چه پاسخی می‌گیرم؟What response do I get?	`curl -i http://127.0.0.1/`	DNS، فایروال یا دسترسی عمومی را نمی‌آزماید.Does not test DNS, firewall, or public reachability.

منابع رسمی برای ادامه: راهنمای آغاز Nginx، گزینه‌های خط فرمان Nginx و بسته‌های لینوکس nginx.org. تفاوت مسیرها و واحد سرویس را همیشه با خروجی میزبان خودت تطبیق بده.

Official references: the Nginx Beginner’s Guide, Nginx command-line switches, and nginx.org Linux packages. Always reconcile paths and service units with evidence from your own host.

نصب و ساختار فایل‌ها

Installation and file layout

یک تغییر کوچک، دو نصب متفاوتOne small change, two different installations

نصب: بستهٔ توزیع یا مخزن رسمی؟Installation: distribution package or official repository?

بستهٔ توزیع چه فرقی با بستهٔ nginx.org دارد؟How does the distribution package differ from nginx.org’s package?

قبل از ویرایش، نصب فعال را پیدا کنIdentify the active installation before editing

از باینری تا فایلی که پاسخ را می‌سازدFrom the binary to the file that becomes the response

صفحه را عوض کن، بعد همان مسیر را دوباره بسنجChange the page, then verify the same path again

یک خطای بی‌خطر: قبل از reload، پیکربندی را بیازماA harmless fault: test configuration before reloading

reload با restart یکی نیستReload is not the same as restart

تمرین‌ها: از حدس به مدرکExercises: replace guesses with evidence

۱. سرویس بالا هست؛ سایت هم؟1. The service is up; is the site?

۲. کدام روش نصب؟2. Which installation method?

۳. مسیر فایل پیکربندی3. Configuration path

۴. -t یا -T؟4. -t or -T?

۵. صفحهٔ پیش‌فرض کجاست؟5. Where is the default page?

۶. روی Debian و Ubuntu6. On Debian and Ubuntu

۷. آزمون شکست می‌خورد7. The test fails

۸. چرا تغییر صفحه لازم نیست reload شود؟8. Why may a page change need no reload?

۹. ارتباط رد شد9. Connection refused

۱۰. خروجی 40410. A 404 response

۱۱. باینری shell با سرویس یکی نیست؟11. Does the shell binary match the service?

۱۲. کدوم‌یکی include شده؟12. Which file is included?

۱۳. پس از تغییر config13. After changing configuration

۱۴. reload موفق، صفحه غلط14. Reload succeeded, but the page is wrong

۱۵. سرویس fail شده15. The service has failed

۱۶. می‌توانی خروجی -T را بفرستی؟16. Can you share -T output?

۱۷. اختلاف بین دو میزبان17. Two hosts disagree

۱۸. بلیت عیب‌یابی18. A troubleshooting ticket

ماموریت: صفحهٔ خودت را از ریشهٔ فعال سرو کنMission: serve your page from the active root

حالا که فایل را پیدا کردی…Now that you have found the file…

۴. `-t` یا `-T`؟4. `-t` or `-T`?

۱۶. می‌توانی خروجی `-T` را بفرستی؟16. Can you share `-T` output?