Nginx. Locations für einen virtuellen Host konfigurieren
Locations legen fest, wie Nginx Anfragen an verschiedene URL-Pfade eines virtuellen Hosts verarbeitet. Über sie binden Sie PHP ein, richten Proxying an einen anderen Dienst ein, beschränken den Zugriff per IP, überschreiben den Stammordner für einen Unterpfad und setzen weitere Parameter. Dieser Artikel richtet sich an alle, die bereits einen virtuellen Host nach der Anleitung Nginx. Arbeiten mit virtuellen Hosts angelegt haben und nun den Block «Extraoptionen» im Konstruktorformular nutzen möchten. Wenn das Formular Ihr Szenario nicht abdeckt (etwa die Direktiven rewrite, if, map), verwenden Sie den Expertenmodus.
Wo Locations zu finden sind
Auf der Seite zum Erstellen oder Bearbeiten eines virtuellen Hosts klappen Sie unterhalb der Hauptfelder den Block «Extraoptionen» auf und klicken auf «Location hinzufügen» — das Panel bietet eine Vorlage zur Auswahl an und legt eine Karte an. Die Reihenfolge der Karten im Formular entspricht der Reihenfolge der location-Blöcke im server.
Location-Vorlagen
Beim Hinzufügen einer Location wählen Sie eine von vier Vorlagen. Die Vorlage bestimmt, welche speziellen Felder auf der Karte erscheinen und welche Nginx-Direktiven am Ende im location-Block stehen. Die Stamm-Location ist immer im Host vorhanden und wird automatisch erstellt — ihre Vorlage lässt sich nicht ändern; die anderen drei werden manuell ausgewählt.
Stamm-Location
Die Stamm-Location ist der Block location / in der Nginx-Konfiguration. Über sie laufen alle Anfragen, die auf keine spezifischere Location zugetroffen haben. Ihre Karte steht stets an erster Stelle im Formular; der Pfad ist auf / festgelegt, die Vorlagenauswahl ist nicht sichtbar, eine Löschen-Schaltfläche gibt es nicht. Verfügbar sind nur der Schalter Aktiviert / Deaktiviert und die universellen Parameter.
In der Stamm-Location sind standardmäßig bereits zwei Parameter gesetzt:
- Dateien prüfen (try_files) =
$uri $uri/ =404— das Standardschema für die Auslieferung statischer Dateien: Nginx sucht zuerst nach der angeforderten Datei, dann nach einem Verzeichnis und antwortet andernfalls mit 404. - Max. Body-Größe =
10m— Limit für die Größe des Anfrage-Bodys.
Beide Voreinstellungen lassen sich ändern oder entfernen; weitere universelle Parameter werden auf gewohntem Weg hinzugefügt. Auch die Stamm-Location selbst lässt sich über den Schalter abschalten (siehe Eine Location aktivieren und deaktivieren) — etwa wenn die Bearbeitung des Stamms vollständig über separate Locations oder universelle Parameter erfolgen soll.
Einfach
Die Vorlage «Einfach» ist ein leerer location-Block mit beliebigem „Pfad" und einer Reihe universeller Parameter. Sie hat keine speziellen Felder — das Verhalten wird über das Hinzufügen von Parametern konfiguriert. Typische Szenarien:
- Zugriff auf das Verzeichnis
/admin/per IP einschränken; - den Stammordner für
/static/überschreiben; - ein langes
expiresfür Assets festlegen; - den Zugriff auf Dienstdateien wie
.gitsperren.
Ausführliches Beispiel: Regel für ein Verzeichnis mit statischen Inhalten
Angenommen, im Formular der Vorlage „Einfach" ist der Pfad /static/ gesetzt und über «Parameter hinzufügen» wurden «Cache-Zeit (expires)» = 30d, «Max. Body-Größe» = 10m und «Zugriff erlauben (allow)» = all ergänzt. In der resultierenden *.conf-Datei landet etwa folgender Block:
location /static/ {
expires 30d;
client_max_body_size 10m;
allow all;
}Die Vorlage „Einfach" fügt selbst keine Direktiven hinzu — am Ausgang steht nur, was Sie in den Parametern angegeben haben.
PHP (FastCGI)
Die Vorlage PHP (FastCGI) richtet die Weiterleitung von Anfragen an PHP-FPM ein — das übliche Szenario für WordPress, Laravel und andere PHP-Anwendungen. Bei Auswahl der Vorlage wird das Feld Pfad automatisch mit dem regulären Ausdruck ~ \.php$ befüllt — er trifft auf alle Anfragen zu, die auf .php enden. In den meisten Fällen muss dieser Wert nicht geändert werden.
Sobald mindestens eine Location im Host die Vorlage PHP (FastCGI) verwendet, fügt BeAdmin index.php automatisch als ersten Eintrag in die gemeinsame Liste der Index-Dateien des Hosts ein. Beim Entfernen einer solchen Location wird index.php ebenso automatisch wieder aus der Liste genommen.
PHP-Version
Die PHP-Version ist das einzige spezifische Feld dieser Vorlage. Anhand der gewählten Version trägt BeAdmin den Pfad zum passenden FPM-Socket in die Konfiguration ein: unix:/var/run/php/php<X.Y>-fpm.sock. Ist die gewählte Version im System noch nicht vorhanden, lässt sie sich direkt von hier aus installieren — ein separater Aufruf des Bereichs „PHP“ ist nicht nötig.
💡 Was die Panel zusätzlich zu Ihren Parametern einträgt
Zusätzlich zu fastcgi_pass für die gewählte PHP-Version trägt BeAdmin einen Standardsatz an FastCGI-Direktiven in den Block ein: fastcgi_split_path_info, try_files $fastcgi_script_name =404, include fastcgi_params sowie die grundlegenden fastcgi_param-Zeilen. Da try_files festgelegt ist, wird der vom Nutzer gesetzte Parameter Dateien prüfen (try_files) in der PHP-Vorlage ignoriert — es bringt nichts, ihn zu setzen.
Ausführliches Beispiel: eine PHP-Location in der resultierenden Konfiguration
Angenommen, im Formular der PHP-Location ist der Pfad ~ \.php$ gesetzt, PHP 8.3 ausgewählt und über Parameter hinzufügen Max. Body-Größe = 64m sowie Cache-Zeit (expires) = 1h ergänzt. In der resultierenden *.conf-Datei landet etwa folgender Block:
location ~ \.php$ {
# Parameter aus dem Formular
client_max_body_size 64m;
expires 1h;
# PHP-FPM-Socket für die gewählte Version
fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
# Standard-FastCGI-Gerüst von BeAdmin
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
try_files $fastcgi_script_name =404;
set $path_info $fastcgi_path_info;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $path_info;
fastcgi_param PATH_TRANSLATED $document_root$path_info;
fastcgi_param HTTP_PROXY "";
}Die ersten beiden Direktiven sind die Parameter, die Sie im Formular eingetragen haben. Den Rest setzt BeAdmin selbst anhand der gewählten PHP-Version und der Standardvorlage für die FastCGI-Verarbeitung.
Reverse-Proxy
Die Vorlage Reverse-Proxy macht aus dem location-Block einen Reverse-Proxy: Anfragen über den gewählten Pfad gehen an ein internes Backend (ein weiterer Nginx, Apache auf 127.0.0.1:8808, eine Node-Anwendung, ein Docker-Container). Bei Auswahl der Vorlage wird das Feld Pfad geleert — tragen Sie es selbst ein: meist /, /api oder ^~ /api/.
Proxy-Ziel (proxy_pass)
Im Feld Proxy-Ziel (proxy_pass) wird die Backend-URL angegeben — zum Beispiel http://127.0.0.1:8080 oder https://api.internal.example.com/v2. Dieser Wert landet in der Direktive proxy_pass. Das Feld ist Pflicht; ohne es lässt sich die Location nicht speichern.
Header
Im Unterabschnitt Header lassen sich zusätzliche HTTP-Header über proxy_set_header an das Backend weitergeben. Die Schaltfläche Header hinzufügen ergänzt ein Paar „Name — Wert“. Der Name wird aus einer festen Liste gewählt: Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, Connection, Upgrade, Accept-Encoding, Accept-Language, Authorization, Content-Type, Content-Length, User-Agent, Referer, Origin, Cache-Control, Cookie, Set-Cookie. Steht der gewünschte Header nicht in der Liste, bleibt nur der Expertenmodus.
Eine typische Kombination für die Verbindung Nginx + Apache: Host = $host, X-Real-IP = $remote_addr, X-Forwarded-For = $proxy_add_x_forwarded_for, X-Forwarded-Proto = $scheme.
Ausführliches Beispiel: Proxying an eine lokale Node-Anwendung
Angenommen, im Formular der Vorlage „Reverse-Proxy" ist der Pfad / gesetzt, «Proxy-Ziel (proxy_pass)» = http://127.0.0.1:8080, und über «Header hinzufügen» sind die Paare Host = $host und X-Real-IP = $remote_addr ergänzt. In der resultierenden *.conf-Datei landet etwa folgender Block:
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}Die Vorlage „Reverse-Proxy" fügt im Block nur proxy_pass und proxy_set_header für die aufgeführten Header hinzu; alles Übrige wird über universelle Parameter oder den Expertenmodus konfiguriert.
Universelle Parameter
In jeder Vorlage gibt es den Unterabschnitt Parameter und die Schaltfläche Parameter hinzufügen. Darunter befindet sich eine für alle Vorlagen gemeinsame Liste mit sieben Schlüsseln. Jeder Schlüssel lässt sich pro Karte nur einmal hinzufügen; bereits verwendete werden ausgeblendet. Die Tabelle zeigt, was jeder Parameter in der Nginx-Konfiguration bewirkt und wie ihn das Formular prüft.
| Parameter im Formular | In *.conf | Wofür er steht und wie er geprüft wird |
|---|---|---|
| Zugriff erlauben (allow) | allow <Wert>; | Liste der Adressen, denen der Zugriff erlaubt ist. Jeder Wert ist eine IPv4-Adresse (192.168.1.100), ein CIDR-Netz (192.168.1.0/24, Maske von 0 bis 32) oder das Schlüsselwort all. Mehrere Werte werden nacheinander über ein Auswahlfeld eingegeben. |
| Zugriff verweigern (deny) | deny <Wert>; | Wie oben, verweigert aber den Zugriff. Die übliche Kombination sind mehrere allow-Einträge für die eigenen Netze und ein abschließendes deny all. |
| Max. Body-Größe | client_max_body_size <Wert>; | Limit für die Größe des Anfrage-Bodys. Format: eine Zahl mit optionalem Suffix k, m oder g: 100m, 10k, 1g, 0. |
| Cache-Zeit (expires) | expires <Wert>; | Der Expires-Header für das Caching auf Browser-Seite. Im Auswahlfeld stehen die Vorgaben off, 1m, 30m, 1h, 24h, 7d, 30d, 1y; ein eigener Wert wie -1h oder max lässt sich ebenfalls eintragen. |
| 404-Fehler loggen | log_not_found on/off; | Schalter: ob Meldungen über nicht gefundene Dateien in das Nginx-Log geschrieben werden. |
| Root-Ordner (root_dir) | root <Wert>; | Stammordner für diese Location — überschreibt das gemeinsame root des Hosts für einen konkreten Pfad. Das Feld darf nicht leer sein. |
| Dateien prüfen (try_files) | try_files <Wert>; | Die vollständige Argumentzeichenfolge der try_files-Direktive, etwa $uri $uri/ =404 oder $uri /index.php?$query_string. In der Vorlage PHP (FastCGI) wird dieser Parameter ignoriert — try_files ist dort festgelegt. |
⚠️ IPv6 bei „Zugriff erlauben“ und „Zugriff verweigern“
Im Formular werden ausschließlich IPv4-Adressen und IPv4-CIDR-Netze akzeptiert. Für Beschränkungen über IPv6 ist der Expertenmodus erforderlich — dort werden allow und deny direkt in die Konfiguration geschrieben und unterstützen jede Syntax von Nginx.
Eine Location aktivieren und deaktivieren
Jede Location-Karte, einschließlich der Stamm-Location, hat den Schalter Aktiviert / Deaktiviert. Eine deaktivierte Location bleibt im Formular erhalten, landet aber nicht in der resultierenden *.conf für Nginx — eine bequeme Möglichkeit, einen Teil der Konfiguration vorübergehend abzuschalten, ohne die Einstellungen zu verlieren. Gleichzeitig entfällt für eine deaktivierte Location die Prüfung auf einen doppelten Pfad: Sie können eine alte Location mit dem Pfad /api deaktivieren und eine neue mit demselben Pfad anlegen — das Speichern wird durchgehen.