ИИ‑агенты > Pastukhov Agent > Документация > SSL-сертификаты

SSL-сертификаты

Когда агент работает по адресу вашего домена, соединение с ним стоит защитить: HTTPS-протокол шифрует трафик, а браузер показывает настоящий адрес сайта и «замочек» вместо предупреждений о небезопасном соединении. Обычно для этого нужны сторонние программы и ручные настройки, но Pastukhov Agent умеет выпускать бесплатные SSL-сертификаты Let’s Encrypt прямо из своего веб-интерфейса — без Docker-контейнеров, дополнительных программ и ручного размещения проверочных файлов. Откройте в приложении страницу /ssl, укажите домен и email — сертификат будет получен автоматически и сохранён в папке конфигурации проекта (.pastukhov/ssl/ или .xedant/ssl/).

Как это работает

Встроенный ACME-клиент. Сертификат выпускается по открытому протоколу ACME — это технология автоматической выдачи сертификатов, по которой работают центры вроде Let’s Encrypt. Приложение само выступает в роли клиента ACME (встроенная библиотека Certes работает прямо в его процессе) — отдельный certbot или Docker-команды не нужны.

Проверка владения доменом (HTTP-01). Центр должен убедиться, что домен действительно ваш: он запрашивает одноразовый код по адресу http://{домен}/.well-known/acme-challenge/{код}. Пока проверка активна, приложение само отвечает на этот запрос — вам ничего размещать не нужно.

Сохранение файлов. Готовые сертификаты сохраняются в подпапке домена внутри папки SSL: fullchain.pem (полная цепочка сертификата) и privkey.pem (закрытый ключ). Ключ ACME-аккаунта (account-key.pem) сохраняется один раз и переиспользуется для последующих запросов.

Прогресс в реальном времени. Каждый шаг процесса отображается в интерфейсе мгновенно (обновления приходят по технологии SignalR) — вы видите текущее состояние: от регистрации аккаунта до сохранения сертификата.

Получение сертификата

  1. Откройте страницу /ssl вашего экземпляра Pastukhov Agent.
  2. Укажите домен (например, agent.example.com) и email для регистрации ACME-аккаунта. Email браузер запоминает и подставляет автоматически при следующих обращениях.
  3. Отметьте «Использовать тестовый сервер» только для экспериментов — тестовые сертификаты браузеры не принимают, для настоящей работы галочку снимать нельзя.
  4. Нажмите «Получить сертификат» — приложение зарегистрирует ACME-аккаунт, создаст заказ, пройдёт проверку владения доменом и сохранит файлы сертификата.
  5. Прогресс отображается пошагово: регистрация аккаунта → создание заказа → настройка проверки → подтверждение домена → генерация сертификата → сохранение файлов.

Повторные запросы для того же домена допустимы — файлы перезаписываются, а существующий ACME-аккаунт переиспользуется.

Проверка текущего сертификата

Кнопка проверки рядом с полем домена показывает, какой сертификат установлен на домен в данный момент: кому он выдан и кем, период действия и сколько дней осталось (подсвечивается жёлтым, если осталось меньше 30 дней). Если сертификата нет — появляется соответствующее предупреждение.

Список сертификатов и удаление

Все выпущенные сертификаты перечислены на странице /ssl: домен, дата выдачи, срок действия и имена сохранённых файлов. Ненужный сертификат можно удалить одной кнопкой.

Что нужно для выпуска

  • Домен (или поддомен) должен указывать на IP-адрес сервера, где запущен Pastukhov Agent;
  • Порт 80 (HTTP) должен быть доступен снаружи — через него Let’s Encrypt проводит проверку;
  • Для настоящих выпусков действуют лимиты Let’s Encrypt (порядка 5 сертификатов на домен в неделю) — для экспериментов используйте тестовый сервер.

Самоподписанный сертификат (без домена)

Если у вас нет домена — например, агент работает на сервере по IP-адресу или в локальной сети, — Let’s Encrypt неприменим: без домена нельзя доказать владение. Для таких случаев есть встроенный режим самоподписанного сертификата: HTTPS включается одним переключателем, без регистрации и внешних сервисов.

Браузер не может проверить, что такой сертификат выпущен доверенным центром, поэтому при первом заходе покажет предупреждение о безопасности — его нужно один раз пропустить (кнопка «Продолжить на сайт»). После этого соединение шифруется полноценно: пароли, токены и содержимое чатов защищены от перехвата в пути.

Как включить. Достаточно задать переменную окружения AGENT_SSL=auto при запуске. Переменные окружения — это параметры запуска: вы задаёте их один раз, и приложение применяет их автоматически. При старте приложение само сгенерирует сертификат (срок действия — 5 лет, продлевать не нужно) и начнёт слушать HTTPS-порт:

  • AGENT_SSL_PORT — порт для HTTPS (по умолчанию — номер HTTP-порта + 1, например, HTTP на 8080 → HTTPS на 8081);
  • сертификат сохраняется в папке .pastukhov/ssl/auto/ (fullchain.pem + privkey.pem) и при последующих запусках переиспользуется, пока действует;
  • в сертификат автоматически включаются все имена хостов и IP-адреса сервера — он подойдёт для обращения и по IP, и по имени в локальной сети;
  • HTTP при этом продолжает работать как раньше — оба протокола доступны одновременно.

Переменная AGENT_SSL_DOMAINS позволяет явно перечислить через запятую домены/IP, которые нужно добавить в сертификат (используется в Docker-контейнерах MultiAgent, где имя хоста и адреса внутри контейнера не совпадают с тем адресом, по которому к агенту обращается браузер).

Какой вариант выбрать: если у вас есть домен и доступный порт 80 — используйте Let’s Encrypt (сертификат доверенный, предупреждений в браузере не будет); если домена нет или доступ только по IP — включите самоподписанный сертификат.

Подключение к nginx

После выпуска подключите сертификат в конфигурации вашего веб-сервера. Пример для nginx (пути — относительно корня проекта, где хранится папка .pastukhov):

server {
    listen 443 ssl;
    server_name agent.example.com;

    ssl_certificate     /srv/pastukhov/.pastukhov/ssl/agent.example.com/fullchain.pem;
    ssl_certificate_key /srv/pastukhov/.pastukhov/ssl/agent.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Автоматического продления (auto-renewal) в приложении пока нет — обновляйте сертификат заново через страницу /ssl до истечения срока. Let’s Encrypt выпускает сертификаты на 90 дней.