Первые шаги#

Это руководство проводит вас через настройку только что установленного Angie — от приветственной страницы пакета до сервера, который раздает файлы, передает запросы приложению, отвечает по HTTPS с сертификатами, которые получает сам, и показывает собственную статистику. Если вы уже используете nginx, перенесите его конфигурацию, а не собирайте заново вручную.

Каждый шаг развивает конфигурацию, собранную на предыдущем, поэтому выполняйте шаги по порядку. Пропустить можно только шаг с HTTPS: это единственный шаг, для которого нужно публичное доменное имя, и от него ничего дальше не зависит.

Понадобятся установленный из пакета Angie на Linux с systemd и учетная запись с правом использовать sudo. Для Alpine и FreeBSD на странице установки приведены команды service, которые заменяют systemctl.

Проверка установки#

Узнайте установленную версию:

$ angie -v
Angie version: Angie/1.12.1

Запустите службу и запросите страницу по умолчанию:

$ sudo systemctl start angie
$ curl -I localhost
HTTP/1.1 200 OK
Server: Angie/1.12.1
...

Ответ пришел от сервера с приветственной страницей, который описан в конфигурации из пакета; где именно — покажет следующий шаг.

Изменения конфигурации применяются перезагрузкой, а не перезапуском: главный процесс перечитывает конфигурацию и запускает новые рабочие процессы, а старые дообрабатывают свои запросы и только потом завершаются. Все команды запуска, остановки, перезагрузки и ротации журналов, стоящие за ними сигналы и параметры командной строки описаны в разделе Управление во время выполнения.

Устройство конфигурации#

Основной файл конфигурации — angie.conf; путь к нему задан при сборке программы:

$ angie -V 2>&1 | tr ' ' '\n' | grep conf-path
--conf-path=/etc/angie/angie.conf

Файл разделен на контексты — блоки, которые группируют директивы, относящиеся к одному виду трафика:

  • events — общая обработка соединений

  • http — трафик HTTP

  • mail — почтовый трафик

  • stream — трафик TCP и UDP

Файлы из /etc/angie/http.d/ подключаются внутрь http, поэтому в них размещают блоки server и директивы уровня http. Блок server описывает один виртуальный сервер, а вложенный в него блок location — обработку одного набора URI запросов.

Приветственную страницу отдает единственный сервер из конфигурации пакета — он задан в /etc/angie/http.d/default.conf. Это руководство заменяет содержимое этого файла, а angie.conf оставляет как есть.

Наследование между контекстами, правила синтаксиса, а также единицы измерения размеров и времени в параметрах директив описаны в разделе Конфигурационные файлы.

Раздача статических файлов#

Начните с файлов на диске. Создайте две директории и положите в каждую по файлу; в каждый файл записано имя его директории, поэтому по ответу видно, откуда он взялся:

$ sudo mkdir -p /data/www /data/images
$ echo 'Hello from /data/www' | sudo tee /data/www/index.html
Hello from /data/www
$ echo 'Hello from /data/images' | sudo tee /data/images/example.png
Hello from /data/images

Второй файл лишь изображает картинку; с настоящим PNG все работает так же.

Замените содержимое /etc/angie/http.d/default.conf на такое:

/etc/angie/http.d/default.conf#
server {
    listen 80;

    location / {
        root /data/www;
    }

    location /images/ {
        root /data;
    }
}

Проверьте конфигурацию и перезагрузите ее:

$ sudo angie -t && sudo systemctl reload angie

Теперь доступны оба файла, а на запрос несуществующего файла сервер отвечает 404:

$ curl localhost/index.html
Hello from /data/www
$ curl localhost/images/example.png
Hello from /data/images
$ curl -o /dev/null -w '%{http_code}\n' localhost/images/missing.png
404

Обе локации — префиксные: им соответствуют URI запросов, начинающиеся с указанной строки, и побеждает самый длинный совпавший префикс. URI /index.html подошел под location / — кратчайший возможный префикс, который принимает все, что не досталось остальным локациям.

Директива root задает не директорию, из которой раздаются файлы, а директорию, к которой добавляется весь URI запроса. Поэтому location /images/ нужен root /data, а не /data/images: URI /images/example.png, добавленный к /data, дает /data/images/example.png.

Примечание

Если запрос обрабатывается не так, как вы ожидаете, причину почти всегда видно в журналах доступа и ошибок, которые пишутся в /var/log/angie/.

Сопоставление запроса с виртуальными серверами и локациями, включая локации с регулярными выражениями и порядок их проверки, описано в разделе Соединения, сессии, запросы, логи. Директивы, которые отображают URI на файлы, — root, alias, index, try_files — собраны в справочнике модулей HTTP.

Проксирование запросов к приложению#

Вторая типичная задача Angie — стоять перед приложением и передавать запросы ему. Здесь роль приложения играет сам Angie: второй сервер, который слушает только петлевой адрес на порту 8080 и раздает файлы из собственной директории. Позже замените его настоящим приложением.

$ sudo mkdir -p /data/app
$ echo 'Hello from the application' | sudo tee /data/app/index.html
Hello from the application

Опишите этот сервер в отдельном файле:

/etc/angie/http.d/app.conf#
server {
    listen 127.0.0.1:8080;

    root /data/app;
}

В default.conf замените root в location / на proxy_pass, а изображения отбирайте не по префиксу, а по расширению:

/etc/angie/http.d/default.conf#
server {
    listen 80;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data;
    }
}

Проверьте конфигурацию и перезагрузите ее:

$ sudo angie -t && sudo systemctl reload angie

Теперь запросы доходят до приложения — кроме запросов изображений:

$ curl localhost/
Hello from the application
$ curl localhost/images/example.png
Hello from /data/images

Вторая локация начинается с ~, что делает ее локацией с регулярным выражением, а не префиксной. Angie сначала проверяет префиксные локации и запоминает самое длинное совпадение, а затем проверяет регулярные выражения в порядке их следования; если одно из них совпало, выигрывает оно. Благодаря этому единственный короткий шаблон забирает запросы изображений из локации, которая принимает все остальное, и Angie отдает их с диска, не обращаясь к приложению.

У proxy_pass есть обширный набор сопутствующих директив — для заголовков запроса, таймаутов, буферизации и кеширования, — описанных в модуле Proxy. Чтобы распределять запросы между несколькими серверами приложения, опишите блок upstream и проксируйте на него по имени.

Автоматический HTTPS#

Для этого шага нужны доменное имя, которое разрешается в публичный адрес этого сервера, и доступный из интернета порт 80: удостоверяющий центр подтверждает владение доменом, забирая файл по HTTP. Если чего-то из этого нет, переходите к следующему шагу — от этого ничего дальше не зависит.

Angie получает и обновляет сертификаты сам, по протоколу ACME, без внешнего клиента и без задания в cron для продления. Добавьте перед блоком сервера acme_client — это директива уровня http — и сошлитесь на клиента из сервера, подставив вместо example.com и www.example.com свои имена:

/etc/angie/http.d/default.conf#
acme_client example https://acme-v02.api.letsencrypt.org/directory;

server {
    listen 80;
    listen 443 ssl;

    server_name example.com www.example.com;
    acme example;

    ssl_certificate     $acme_cert_example;
    ssl_certificate_key $acme_cert_key_example;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data;
    }
}

Имя удостоверяющего центра Angie по умолчанию разрешает через /etc/resolv.conf, поэтому директива resolver не нужна. Если связности по IPv6 нет, добавьте перед блоком сервера resolver conf ipv6=off;, чтобы он не запрашивал записи AAAA, которыми все равно не сможет воспользоваться.

Сертификат выпускается на доменные имена, перечисленные в server_name тех серверов, которые ссылаются на одного и того же клиента; имена, которые не являются доменными, — регулярные выражения, _ — пропускаются с предупреждением в журнале ошибок. В ssl_certificate сертификат попадает через переменную, а не через путь к файлу, так что устанавливать и менять вручную нечего.

Проверьте конфигурацию и перезагрузите ее:

$ sudo angie -t && sudo systemctl reload angie

Порт 443 Angie занимает сразу после применения конфигурации, но до появления сертификата не может завершить рукопожатие TLS, поэтому пока запросы на этот порт обрываются на рукопожатии. Выпуск происходит не мгновенно — он зависит от удостоверяющего центра. Когда сертификат получен:

$ curl -I https://www.example.com/
HTTP/1.1 200 OK
...

Если сертификат так и не появился, посмотрите состояние клиента в /status/http/acme_clients/example через API из следующего шага и сообщения ACME в журнале ошибок; если этого мало, включите отладочный журнал.

Примечание

Пока вы отлаживаете конфигурацию, направьте acme_client в тестовую среду удостоверяющего центра — у Let's Encrypt это https://acme-staging-v02.api.letsencrypt.org/directory, — чтобы неудачные попытки не расходовали лимиты рабочей среды. Когда сертификат появится, переключитесь на рабочий адрес.

Подтверждение через DNS и TLS-ALPN, wildcard-сертификаты, внешняя привязка учетной записи и переход с Certbot описаны в разделе Настройка ACME; директивы и переменные — в модуле ACME.

Статистика сервера#

Angie сообщает собственное состояние через встроенный REST API. Добавьте для него локацию, доступную только с этого сервера, и задайте серверу status_zone, чтобы по нему собирались счетчики:

/etc/angie/http.d/default.conf#
acme_client example https://acme-v02.api.letsencrypt.org/directory;

server {
    listen 80;
    listen 443 ssl;

    server_name example.com www.example.com;
    acme example;

    ssl_certificate     $acme_cert_example;
    ssl_certificate_key $acme_cert_key_example;

    status_zone site;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data;
    }

    location /status/ {
        api /status/;

        allow 127.0.0.1;
        deny all;
    }
}

Если вы пропустили шаг с HTTPS, добавьте только выделенные строки. Ровно такая локация /status/ была в default.conf из пакета; она исчезла, когда вы заменили содержимое этого файла. Верните ее.

Проверьте конфигурацию и перезагрузите ее; после этого API отвечает в формате JSON:

$ sudo angie -t && sudo systemctl reload angie
$ curl localhost/status/angie/
{
    "version": "1.12.1",
    "build_time": "2026-07-17T06:58:49Z",
    "address": "192.0.2.10",
    "generation": 1,
    "load_time": "2026-07-17T10:23:06.011Z"
}

/status/connections сообщает о принятых, отброшенных, активных и простаивающих соединениях. Счетчики по серверам и локациям включаются отдельно: блок server появляется в /status/http/server_zones/, а блок location — в /status/http/location_zones/, и только если у блока есть собственная status_zone. У сервера выше она есть, у его локаций — нет:

$ curl localhost/status/http/server_zones/site
{
    "ssl": {
        "handshaked": 3,
        "reuses": 0,
        "timedout": 0,
        "failed": 0
    },

    "requests": {
        "total": 5,
        "processing": 1,
        "discarded": 0
    },

    "responses": {
        "200": 3,
        "404": 1
    },

    "data": {
        "received": 412,
        "sent": 1418
    }
}

Объект ssl присутствует потому, что сервер слушает порт с параметром ssl; без этого зона начинается с requests.

Полный набор разделов API — группы серверов, кеши, DNS-резолверы, зоны разделяемой памяти, клиенты ACME, а в Angie PRO еще и динамическая настройка — описан в модуле API. Если эти данные удобнее просматривать, а не запрашивать через curl, те же показатели выводит веб-панель Console Light.

Что дальше#

Инструкции

Пошаговые руководства по отдельным задачам: SSL, OIDC, кластеризация, панели мониторинга и пользовательские метрики.

Модули

Справочник по всем директивам и переменным, сгруппированный по модулям.

Быстрый доступ

Короткие ссылки, ведущие прямо к документации директив и переменных.

Миграция с nginx

Если nginx у вас работает где-то еще, перенесите и те конфигурации.