Настройка NPM российские SSL сертификаты: полная установка сертификата Минцифры

Настройка NPM российские SSL сертификаты: полная установка сертификата Минцифры

Настройка NPM российские SSL сертификаты превращается в квест в тот момент, когда ты открываешь раздел SSL Certificates и не находишь ни одной кнопки «загрузить сертификат Минцифры». Встроенного интерфейса под УЦ РФ у Nginx Proxy Manager нет и не появится, потому что подтверждение домена там идёт через Госуслуги или личный кабинет УЦ, а не через DNS-01 challenge. Значит, работаем руками: собираем PEM-цепочку, конвертируем ключ из PKCS#12, кладём файлы в кастомный SSL и проверяем, что браузер видит всю цепочку до корня.

Быстрый ответ
  • Nginx Proxy Manager не имеет встроенной поддержки сертификатов Минцифры. Добавляй их через SSL Certificates → Add SSL Certificate → Custom.
  • Из .pfx/.p12 нужно извлечь ключ и сертификаты в PEM через openssl pkcs12. Отдельно конвертируешь ключ без пароля, отдельно вытаскиваешь цепочку.
  • Собрать один PEM-файл в порядке: конечный сертификат, промежуточный, корневой. Обратный порядок NPM проглотит молча, а браузер потеряет цепочку.
  • Кастомные сертификаты кладутся в volume /data/custom_ssl, иначе при обновлении контейнера они исчезнут. После замены файлов перезапусти контейнер NPM.
  • Проверка: openssl s_client -connect domain:443 -showcerts. Длина цепочки должна совпадать с числом сертификатов, которое выдал УЦ.

Диагноз: сертификат на руках, NPM его не принимает

Поднял NPM, домен в РФ-зоне, сертификат Минцифры выпущен, а в разделе SSL Certificates кнопки «Custom» хватает только на загрузку одного файла сертификата и одного ключа. Ты вставляешь в поле Certificate то, что дал УЦ, получаешь молчаливое сохранение. Идёшь в браузер: замок есть, но на некоторых машинах «не удалось проверить подлинность». На других всё зелёное. Знакомая картина.

Проблема не в NPM и не в сертификате. Проблема в цепочке. Российский УЦ отдаёт тебе набор из нескольких файлов: конечный сертификат домена, промежуточный и корневой. NPM хочет видеть это одним файлом в правильном порядке. Формат ключа тоже не тот: УЦ выдаёт PKCS#12 с паролем, NPM хочет PEM без пароля. Две нестыковки в одном месте, и обе не подсвечиваются в интерфейсе.

Дальше разберём, как собрать корректный PEM, как вытащить ключ из pfx, как положить файлы так, чтобы они пережили обновление контейнера, и как проверить цепочку снаружи.

Что получишь по итогу:

  • собранный PEM-файл с правильным порядком сертификатов
  • приватный ключ в PEM без пароля, привязанный к сертификату
  • сертификат, добавленный в NPM через раздел Custom
  • смонтированный volume, чтобы файлы не теряли при апдейте контейнера
  • команду проверки цепочки снаружи

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

Почему NPM не берёт сертификат Минцифры из коробки

Причин несколько, и они складываются в одну большую.

Формат выдачи: PKCS#12 против PEM

УЦ Минцифры отдаёт закрытый ключ и сертификаты упакованными в контейнер PKCS#12 с расширением .pfx или .p12. Это бинарный архив с паролем. Nginx, а значит и NPM, работает с PEM: это текстовый формат с блоками BEGIN/END. NPM не конвертирует одно в другое на лету.

Сертификат это не один файл, а цепочка

УЦ выдаёт сразу несколько сертификатов: конечный на твой домен, промежуточный УЦ и корневой. Браузеру нужна вся цепочка, чтобы дойти до корня, которому он доверяет. В поле Certificate у NPM нужно вставить все три блока подряд в правильном порядке.

Порядок в PEM критичен и молчалив

Если вставить корневой первым, NPM сохранит файл без ошибки. Nginx тоже запустится. А вот браузер не соберёт цепочку и покажет предупреждение. Порядок должен быть: конечный домен, промежуточный, корневой. Именно так, сверху вниз.

Ключ обёрнут паролем

Приватный ключ внутри pfx защищён паролем, который ты задавал при выпуске. openssl умеет его извлечь, но только с этим паролем. Если пароль потерян, восстановить его нельзя: PKCS#12 не имеет механизма сброса. Единственный выход это перевыпуск сертификата в личном кабинете УЦ.

Встроенный ACME не подходит

NPM умеет выпускать Let’s Encrypt через HTTP-01 и DNS-01 challenge. Российский УЦ работает иначе: подтверждение домена идёт через портал Госуслуг или кабинет удостоверяющего центра, автоматизированного ACME-протокола нет. Значит, NPM никогда не обновит сертификат сам. Раз в двенадцать месяцев ты возвращаешься сюда руками.

Kesh сертификатов внутри контейнера

NPM держит активные сертификаты в своей внутренней базе и на диске. Если ты подменил файлы в /data/custom_ssl руками, контейнер продолжит отдавать старую цепочку, пока его не перезапустишь. Это самая частая причина «я обновил, а браузер всё равно ругается».

Корневой сертификат не установлен в ОС и браузере

Даже отлично собранная цепочка обрывается на клиенте, если корневой сертификат УЦ не добавлен в доверенные хранилища. На сервере тоже стоит его положить в системное хранилище, если из NPM куда-то ходят бэкенды по TLS.

Рецепт: собираем сертификат и грузим в NPM

Подготовка

Собери всё в одну папку на машине, где стоит NPM. Тебе нужны:

  • файл .pfx или .p12, который выдал УЦ
  • пароль от этого контейнера
  • доступ по SSH к хосту с NPM
  • доступ в веб-интерфейс NPM с правами администратора
  • openssl версии не ниже 1.1.1

Работай в отдельной директории, чтобы не перепутать файлы. Создай её и перейди туда.


mkdir -p ~/ru-cert && cd ~/ru-cert

Скопируй сюда .pfx, если он лежит в другом месте. Проверь, что файл читается и не пустой.


ls -la ~/ru-cert

Ожидаемый результат: видишь файл .pfx с нормальным размером, обычно от 3 до 10 килобайт.

Системные требования

Компонент Минимум Рекомендовано
ОС хоста Ubuntu 22.04 Ubuntu 24.04 LTS, Debian 12
Docker Engine 24.x актуальная стабильная ветка, проверь релизы Docker
Docker Compose v2.20 актуальная версия плагина compose
Nginx Proxy Manager 2.10 актуальная на момент написания, проверь релизы NPM
openssl 1.1.1 3.x, актуальная версия
RAM 1 ГБ 2 ГБ и больше
Свободное место 2 ГБ 10 ГБ с запасом под логи и бэкапы

На момент публикации актуальна версия NPM из ветки 2.x. Перед установкой проверь свежие релизы на официальной странице проекта.

Порты

Если NPM уже работает, порты открыты. Таблица нужна, чтобы сверить и не открыть лишнего.

Порт Протокол Назначение Доступен снаружи
80 TCP HTTP, редирект на 443 да
443 TCP HTTPS, отдаёт TLS да
81 TCP админка NPM нет, только LAN или VPN
22 TCP SSH к хосту по политике, лучше через bastion

Как это выглядит по цепочке

Блок-схема: pfx от УЦ, openssl: извлечь ключ, openssl: извлечь сертификаты, key.pem без пароля, cert-chain.pem по порядку, SSL Certificates Custom в…
Как это выглядит по цепочке

Шаг 1. Посмотреть, что внутри pfx

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


openssl pkcs12 -in cert.pfx -info -nokeys -noout

Команда попросит пароль. Введи тот, что задавал при выпуске.

Ожидаемый результат: видишь список сертификатов в цепочке, обычно два или три блока, и подтверждение, что ключа в выводе нет, потому что мы его отключили флагом -nokeys.

Шаг 2. Извлечь ключ в PEM без пароля

Здесь два варианта: с паролем на выходе и без. В NPM ключ должен быть без пароля, потому что при старте nginx некому вводить пароль интерактивно. Если оставишь пароль, nginx не поднимется с ошибкой чтения ключа.


openssl pkcs12 -in cert.pfx -nocerts -nodes -out key.pem

Флаг -nocerts говорит «не трогай сертификаты», -nodes значит «не шифруй ключ на выходе». Пароль запросит только от исходного pfx.

Ожидаемый результат: файл key.pem. Внутри один блок PRIVATE KEY.


grep -c "BEGIN" key.pem

Должно вернуть единицу. Если вернуло больше, значит в контейнере не один ключ, разбирайся отдельно.

Шаг 3. Защитить ключ правами

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


chmod 600 key.pem
ls -la key.pem

Ожидаемый результат: права -rw——- и владелец ты.

Шаг 4. Извлечь сертификаты

Достаём всю цепочку в один файл. Если у тебя три сертификата, получишь три блока CERTIFICATE подряд. Порядок в исходном контейнере обычно правильный: конечный, промежуточный, корневой.


openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert-only.pem
openssl pkcs12 -in cert.pfx -nokeys -cacerts -out ca-chain.pem

Первая команда вытащит только листовой сертификат домена. Вторая вытащит промежуточные и корневой.

Ожидаемый результат: два файла, в первом один блок CERTIFICATE, во втором один или два. Проверь количество блоков.


grep -c "BEGIN CERTIFICATE" cert-only.pem
grep -c "BEGIN CERTIFICATE" ca-chain.pem

Число в сумме должно совпадать с тем, что показала команда из шага 1.

Шаг 5. Собрать итоговую цепочку в правильном порядке

Порядок сборки: сначала листовой, потом промежуточный, потом корневой. Никаких перестановок. Собираем в отдельный файл, чтобы было видно результат.


cat cert-only.pem ca-chain.pem > cert-chain.pem

Проверь результат: число блоков CERTIFICATE в итоговом файле должно быть равно сумме двух предыдущих.


grep -c "BEGIN CERTIFICATE" cert-chain.pem

Ожидаемый результат: то же число, что получилось при сложении.

Дополнительно посмотри, что первым идёт именно сертификат твоего домена, а не корневой.


openssl x509 -in cert-chain.pem -noout -subject -issuer

Первая команда в файле должна вернуть subject с твоим CN. Если вернула корень УЦ, значит порядок перепутан, пересобери по-другому.

Шаг 6. Проверить соответствие ключа и сертификата

Очень типичная ошибка: ключ от одного выпуска, сертификат от другого. NPM примет файлы и сохранит, а nginx не поднимется. Проверяй модуль публичного ключа у обоих файлов, они должны совпадать.


openssl x509 -in cert-only.pem -noout -pubkey | openssl md5
openssl pkey -in key.pem -pubout | openssl md5

Ожидаемый результат: оба хеша одинаковые, до символа.

Шаг 7. Положить файлы в volume NPM

Если NPM работает в Docker, файлы кастомных SSL лежат в /data/custom_ssl внутри контейнера. Чтобы они пережили обновление контейнера, эта директория должна быть смонтирована как volume. Проверь compose-файл.


docker compose config | grep -A3 custom_ssl

Если видишь строку монтирования вида ./data/custom_ssl:/data/custom_ssl, отлично. Если нет, добавь том в docker-compose.yml.


services:
  npm:
    image: jc21/nginx-proxy-manager:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "81:81"
    volumes:
      - ./data:/data
      - ./data/custom_ssl:/data/custom_ssl
      - ./letsencrypt:/etc/letsencrypt

После правки перезапусти сервис.


docker compose up -d

Ожидаемый результат: контейнер перезапущен, volume виден в docker inspect.


docker inspect npm --format '{{ range .Mounts }}{{ .Source }} -> {{ .Destination }}
{{ end }}'

Шаг 8. Добавить сертификат в NPM через Custom

Открой админку NPM в браузере. Дальше по меню:

SSL Certificates → Add SSL Certificate → Custom

В поле Name впиши что-то понятное, например domain.ru-ru-cert-2025, чтобы потом не путаться. В поле Certificate пропиши путь к content внутреннего файла или вставь содержимое целиком. В поле Certificate Key такой же подход для key.pem. Каждый файл начинается с BEGIN и заканчивается END, это важно, иначе nginx ругнётся.

Если ты не хочешь вставлять содержимое руками, просто укажи пути до файлов, лежащих внутри контейнера, например /data/custom_ssl/cert-chain.pem и /data/custom_ssl/key.pem, предварительно положив их туда.


docker cp cert-chain.pem npm:/data/custom_ssl/cert-chain.pem
docker cp key.pem npm:/data/custom_ssl/key.pem

Дальше в интерфейсе заполни пути и сохрани.

Ожидаемый результат: в списке SSL Certificates появилась новая запись с датой окончания действия.

Шаг 9. Привязать сертификат к прокси-хосту

Идёшь в Hosts → Proxy Hosts, открываешь нужный хост, вкладка SSL. В выпадающем списке SSL Certificate выбираешь только что созданный. Сохраняешь.

Ожидаемый результат: NPM сохранил конфиг и переписал конфигурацию nginx. В логах контейнера нет красных строк про ssl_certificate.


docker logs npm --tail 100

Шаг 10. Перезапустить контейнер

Если ты подменял файлы напрямую в /data/custom_ssl, а не через интерфейс, NPM мог закешировать старое. Перезапуск гарантирует, что он подхватит свежую цепочку.


docker restart npm

Ожидаемый результат: контейнер поднялся за пару секунд. nginx отдаёт тот же сайт, но уже с новым сертификатом.

Безопасность на этом этапе

Мелочи, которые часто пропускают.

  • Файл key.pem не должен лежать в публичных местах. Ни в git, ни в /tmp, ни в веб-доступных директориях.
  • Админку NPM на порту 81 закрой файрволом, доступ только с LAN или через VPN. Открытая наружу админка это приглашение.
  • В docker-compose не храни пароли от БД и от админки в открытом виде. Используй .env файл.
  • Проверь, что UFW или аналог открывает только 80/443 снаружи.
  • Сгенерируй отдельного ssh-пользователя для управления NPM. root по SSH это плохая привычка.
  • Храни исходный pfx и пароль в защищённом хранилище. Сгодится при перевыпуске и при аудите.

ufw allow 80/tcp
ufw allow 443/tcp
ufw allow from 10.0.0.0/8 to any port 81 proto tcp
ufw allow from 10.0.0.0/8 to any port 22 proto tcp
ufw enable

Ожидаемый результат: ufw status показывает открытые 80, 443 снаружи и 22/81 только из LAN.

Проверка

Проверяй снаружи, с другой машины, не с того же хоста, где стоит NPM. Иначе половина проблем с DNS и маршрутизацией не видна.

Первое: tls handshake и цепочка.


openssl s_client -connect domain.ru:443 -showcerts < /dev/null

Ожидаемый результат: в выводе видишь блоки BEGIN CERTIFICATE, их количество равно числу сертификатов в цепочке. В конце строка Verify return code: 0 (ok). Если увидел self signed certificate in certificate chain, значит цепочка неполная или порядок неверный.

Второе: срок действия.


echo | openssl s_client -connect domain.ru:443 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Ожидаемый результат: notBefore сегодня или раньше, notAfter ровно через год после выпуска, subject с твоим CN, issuer это промежуточный УЦ, а не корневой.

Третье: проверка из браузера. Открой домен в браузере, нажми на замок, посмотри сертификат. В иерархии должна быть цепочка до корневого УЦ, который система признаёт. Если последний элемент помечен как self-signed и не в хранилище, обрывается как раз на этом шаге.

Четвёртое: проверка на стороннем сервисе. Подойдёт любой онлайн-валидатор TLS-цепочки, где видно количество звеньев и дни до истечения. Из локальных подойдёт утилита testssl.sh.


docker run --rm drwetter/testssl.sh domain.ru

Ожидаемый результат: раздел Certificate Chain содержит все звенья, ни одного WARN про expired или self-signed в цепочке.

Пятое: NPM в логах.


docker logs npm --tail 200 | grep -i error

Ожидаемый результат: пустой вывод. Если видишь строки про ssl_certificate или ssl_certificate_key, значит пути или порядок не подхватились, проверяй заново шаги 5 и 8.

Шестое: подключение с клиента, где корневой установлен, и с клиента, где его нет. Разница в поведении покажет, проблема в серверной цепочке или в клиентском хранилище. Это ключевой тест, когда «у меня работает, у коллеги нет».

Когда openssl ругается, а сертификат вроде бы валидный

Ты собрал PEM, залил в NPM, браузер открыл сайт. Через день звонит коллега из другого офиса и говорит, что у него красный замочек. Или того хуже: всё работает в Chrome, но ломается в старом корпоративном IE на терминальном сервере, который никто не обновлял со времён Windows 7. По факту это самая частая история с российскими сертификатами: сам файл корректный, а вот окружение вокруг него кто-то собрал на коленке.

Ниже типовые ошибки, которые я ловил лично или разбирал по логам коллег. Формат простой: что видно, почему так, что делать.

openssl pkcs12: mac verify error

Извлекаешь ключ из .pfx и получаешь вместо ключа простыню с ошибкой. Причина в 99% случаев: неверный пароль. Либо ты вводишь пароль от контейнера, а нужен пароль, который задавали при выпуске в личном кабинете УЦ. Либо в УЦ пароль сгенерировали автоматически и он закопан в письме, которое улетело в спам три месяца назад. Проверь пароль отдельной командой, чтобы не гадать.


openssl pkcs12 -in cert.pfx -nokeys -passin pass:'ТВОЙ_ПАРОЛЬ' -info

Если вывод есть и в нём видно subject с твоим доменом, пароль верный. Если mac verify error, пароль битый. Восстановить его нельзя, только перевыпускать сертификат в личном кабинете УЦ. Запомни это правило и держи пароль в менеджере секретов, а не в переписке.

unable to load certificate: expect PEM

Такое сообщение появляется, когда в файл попал DER вместо PEM, либо когда ты перепутал порядок с именем расширения. Открой файл глазами.


head -3 fullchain.pem

В нормальном PEM первая строка это -----BEGIN CERTIFICATE-----. Если видишь бинарный мусор, значит у тебя DER. Тогда в конвертации нужен флаг -inform DER.


openssl x509 -in cert.der -inform DER -out cert.pem -outform PEM

Второй сценарий: файл склеен из кусков, но между блоками попали лишние строки от Windows. Проверь кодировку и окончания строк.


file fullchain.pem
grep -c "BEGIN CERTIFICATE" fullchain.pem

Если file говорит CRLF, а grep показывает меньше блоков, чем должно быть, прогони через dos2unix и пересобери.

Цепочка обрывается, хотя PEM собран

Самый коварный сценарий. NPM стартует без ошибок, отдаёт сертификат. Но в браузере появляется предупреждение о неполной цепочке. Причина обычно одна из трёх: неверный порядок файлов внутри PEM, отсутствие корневого сертификата в хранилище клиента или лишний промежуточный сертификат от другого УЦ. Проверить просто.


openssl s_client -connect example.ru:443 -showcerts -servername example.ru /dev/null | grep -E "^ [0-9] s:|^ [0-9] i:"

Сравни количество строк s c ожидаемым. Должно быть три: конечный, промежуточный, корневой. Если сервер отдаёт один только конечный, значит в fullchain.pem попал лишь он один, остальные блоки потерялись при копипасте. Пересобери по правилу: сначала конечный, потом промежуточный, потом корневой, без пустых строк внутри блоков.

Сертификат не отображается в NPM после замены файлов

Заменил файлы руками в /data/custom_ssl/npm-XX/, а вебморда показывает старые данные. NPM кэширует метаданные сертификата при старте. Перезапусти контейнер.


docker restart npm-app-1
docker logs --tail 50 npm-app-1

В логах должно быть чисто, без nginx: [emerg]. Если контейнер перезапустился, а дата выпуска та же, ты залил файлы мимо каталога. У NPM каталог кастомного сертификата называется по его числовому ID внутри вебморды, а не по имени домена.

OCSP stapling warning в старых браузерах

Часть российских УЦ не публикует OCSP-ответ для своих конечных сертификатов. NPM в конфиге nginx всё равно пытается сделать ревалидацию, и в браузере или в curl появляется предупреждение вида no OCSP response. Решать это на стороне сервера бессмысленно, потому что проблема на стороне клиента и его политики. Но можно убрать лишний шум в конфиге NPM.

Открой /data/nginx/custom/http.conf внутри контейнера и добавь явное отключение запросов OCSP, чтобы не ждать таймаутов.


ssl_stapling off;
ssl_stapling_verify off;

После этого перезапусти контейнер. Это не починит клиент, но уберёт задержку на первом handshake.

Если NPM не подходит: альтернативы

Бывает, что NPM в проекте уже не первый месяц и его менять никто не хочет. Тогда фикс делается на уровне обратного прокси. А бывает наоборот: NPM только внедряют, и вопрос выбора открыт. Пробегусь по трём вариантам, которые реально работают с российскими сертификатами.

HAProxy

HAProxy не занимается управлением сертификатами вообще. Он берёт один PEM-файл в директиве crt и отдаёт его как есть. Плюс в том, что формат ровно тот же, что мы собирали для NPM. Минус в том, что автоматизировать выпуск и обновление придётся самому, руками или скриптами, а кэш обновляется только через reload HAProxy.


frontend https-in
    bind *:443 ssl crt /etc/haproxy/certs/example.ru.pem
    default_backend app_servers

Если сертификат обновили, HAProxy нужно перезагрузить сигналом SIGHUP или через systemd reload. Живую сессию не порвёт, старые коннекты доживут, новые пойдут на новую цепочку. Проверить без перезапуска можно через тот же openssl s_client.

Traefik

Traefik подходит, если ты уже используешь Docker-стек с лейблами. Он умеет принимать статический сертификат через файл провайдер. Но у него есть засада: динамическая перезагрузка сертификатов работает только для ACME-режима. Для статических файлов нужно либо перезапускать, либо использовать Traefik в режиме с file provider, где watch включён.


tls:
  certificates:
    - certFile: /certs/fullchain.pem
      keyFile: /certs/privkey.pem

При изменении файла Traefik подхватит его без перезапуска, если file provider указан с watch: true. Это чуть удобнее HAProxy, но требует культурного docker-compose и общей шины конфигов.

Ручной nginx

Самый предсказуемый вариант. Никаких промежуточных слоёв, весь конфиг у тебя на руках, в конфиге прямо прописан путь к PEM. Тюнинг, оптимизация TLS, OCSP, HSTS, всё делается строчкой.


server {
    listen 443 ssl http2;
    server_name example.ru;

    ssl_certificate     /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_stapling        off;
    ssl_stapling_verify off;
}

Минус только один: вся логика управления сертификатом на тебе. Никакой вебморды и никакого автообновления. Если у тебя десять сайтов и обновление раз в год, это ок. Если сто, ставь NPM.

Я остаюсь на NPM по одной причине: разделение обязанностей. Вебморду отдаёт отдельный сервис, команда разработки может сама прицепить новый домен, а я вижу только двухнедельные изменения в git. На продакшене это экономит часы.

Решение Формат сертификата Перезагрузка после замены Вебморда
NPM PEM, цепочка restart контейнера Да
HAProxy PEM, цепочка reload через SIGHUP Нет
Traefik PEM через file provider watch без перезапуска Да, dashboard
nginx вручную PEM, цепочка nginx -s reload Нет

Что делать, чтобы не повторить через год

Сертификат Минцифры живёт двенадцать месяцев. Двенадцать месяцев это как раз тот срок, за который ты успеваешь забыть, где лежит пароль от .pfx. Ниже набор действий, который я делаю сразу после успешной установки, чтобы через год всё прошло за двадцать минут, а не за два дня.

Бэкап: что, куда и как часто

Бэкапить нужно три вещи: каталог custom_ssl со всеми сертификатами и ключами, файл docker-compose.yml NPM вместе с volumes, и, отдельно, исходный .pfx вместе с паролем. Без пароля .pfx бесполезен, но и без .pfx перевыпуск потребует похода в личный кабинет УЦ.

Схема простая: локальный бэкап раз в неделю, вынос в отдельное хранилище раз в месяц, прямая проверка восстановления раз в квартал.


tar czf npm-custom-ssl-$(date +%F).tar.gz /var/lib/docker/volumes/npm_data/_data/custom_ssl
age -r age1... -o npm-custom-ssl-$(date +%F).tar.gz.age npm-custom-ssl-$(date +%F).tar.gz
rm npm-custom-ssl-$(date +%F).tar.gz

Использую age, а не gpg, потому что возраст зашифровать проще: одна строка, один ключ, одна команда. Ключ расшифровки держи отдельно от бэкапа, иначе вся затея бессмысленна. .pfx кладу в vault или в защищённый репозиторий с двухфакторкой, пароль от .pfx в password manager с шарингом на двух инженеров.

Мониторинг срока действия

Раз в год ты вспомнишь о сертификате, когда браузер уже орёт. Не жди этого момента. Ставь проверку через чёрный ящик. Простейший вариант: скрипт на хосте, который раз в день дёргает порт и смотрит дни до истечения.


#!/bin/bash
DOMAIN="example.ru"
WARN_DAYS=30
END=$(echo | openssl s_client -connect "$DOMAIN":443 -servername "$DOMAIN" 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
END_EPOCH=$(date -d "$END" +%s)
NOW=$(date +%s)
LEFT=$(( (END_EPOCH - NOW) / 86400 ))
if [ "$LEFT" -lt "$WARN_DAYS" ]; then
    echo "WARN: $DOMAIN expires in $LEFT days" | mail -s "SSL $DOMAIN" ops@example.ru
fi

Если у тебя есть Zabbix, там это делается штатной проверкой web.certificate.get. Если Prometheus, ставь blackbox_exporter с метрикой probe_ssl_earliest_cert_expiry. Любой из вариантов закрывает задачу и даёт порог предупреждения за тридцать дней.

Автозапуск контейнера и volumes

Проверь docker-compose на предмет рестарт-политики. Если её нет, контейнер умрёт после ребута хоста, и сайт ляжет вместе с ним.


services:
  npm-app:
    image: jc21/nginx-proxy-manager:latest
    restart: unless-stopped
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

Использую bind-mount, а не именованный volume. Причина: бэкапить и смотреть содержимое на хосте проще. Плюс миграция на другой сервер это копирование двух каталогов, а не возня с docker volume cp и разбирательствами, где он лежит на самом деле.

Безопасность контура

Сертификат это не сама защита, а только её часть. Приватный ключ должен лежать с правами, которые не дают прочитать его никому, кроме root и контейнера.


chmod 600 /path/to/fullchain.pem
chmod 600 /path/to/privkey.pem
chown root:root /path/to/privkey.pem

Обратный прокси я всегда закрываю фаерволом. Открытыми остаются только 80 и 443. SSH на нестандартном порту, вход по ключу, парольная аутентификация выключена, fail2ban висит на SSH и на попытках подбора на 443.


ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Отдельно: не давай NPM доступ к Docker-сокету от чужого контейнера. Если ты используешь его с сетью хоста, держи сервис хотя бы за авторизацией, а не открытым в интернет по HTTP. Вебморда NPM на 81-м порту наружу не должна смотреть никогда.

Обновление контейнера без потери сертификатов

NPM обновляется тегом образа. Перед обновлением проверь, что volumes смонтированы корректно, и сделай бэкап каталогов data и letsencrypt. Обновление делается так.


docker compose pull
docker compose up -d
docker compose logs --tail 100 npm-app

Если новая версия сломала что-то, откат делается принудительным тегом предыдущей версии в docker-compose.yml и повторным docker compose up -d. Не используй latest в продакшне, закрепи конкретный мажорный тег, иначе получишь сюрприз в час ночи.

Перед обновлением обязательно
Проверь, что бэкап каталогов data и letsencrypt свежий. Проверь, что исходный .pfx и пароль к нему доступны. Проверь, что тег образа в docker-compose сменён с latest на конкретную версию. Без этих трёх условий обновление это лотерея.

FAQ: вопросы, которые задают чаще всего

Почему российский сертификат не работает после настройки NPM?

В девяти случаях из десяти причина в одном из трёх: клиент не видит корневой сертификат Минцифры в своём хранилище, PEM собран в неверном порядке, или NPM не перезапущен после замены файлов. Проверь все три по порядку: установи корневой сертификат в браузер, пересобери PEM с конечного к промежуточному к корневому, перезапусти контейнер. В 90% случаев этого достаточно.

Как проверить, что сертификат установился корректно?

Командой openssl s_client -connect domain:443 -showcerts -servername domain. В выводе должно быть три сертификата: конечный, промежуточный, корневой. Если их меньше, цепочка неполная. Дополнительно проверь срок действия: openssl x509 -noout -dates покажет notBefore и notAfter. Ну и открой сайт в браузере, где установлен корневой Минцифры, там замочек должен быть зелёный.

Что делать, если openssl pkcs12 выдаёт mac verify error?

Пароль неверный. Восстановить его нельзя ни через openssl, ни через какой-либо другой инструмент. Вариант один: зайти в личный кабинет УЦ и перевыпустить сертификат, сохранив новый пароль сразу в менеджер секретов. На будущее: при выпуске всегда фиксируй пароль в защищённом хранилище в тот же день, когда получил .pfx.

Чем NPM отличается от ручного nginx для российских сертификатов?

NPM даёт вебморду и volume-монтирование, но перезапускается только целиком и хранит сертификаты в своей внутренней структуре каталогов. Ручной nginx удобнее тем, что весь конфиг у тебя на руках и сертификат лежит по одному известному пути. По функциям они эквивалентны, разница в удобстве управления и в том, сколько у тебя доменов. На десяти доменах выигрывает nginx, на ста и больше выигрывает NPM.

Нужно ли ставить корневой сертификат в саму ОС и в каждый браузер?

Да, и в ОС, и в браузеры. Chrome и Firefox используют разные хранилища: Chrome берёт системное из ОС, Firefox держит своё. Если у тебя Firefox на сотрудниках, корневой сертификат нужно загрузить и туда, иначе получишь плавающие ошибки доверия, которые невозможно повторить стабильно. Для домена без публичного корня эта настройка обязательна на всех клиентских машинах.

Как автоматизировать продление, если его нет в NPM?

Автоматического продления российских сертификатов через NPM не существует, потому что подтверждение проходит через личный кабинет УЦ или Госуслуги, а не через ACME. Единственная посильная автоматизация: заранее подготовить скрипт, который пересоберёт PEM из нового .pfx одним запуском, и напоминание за тридцать дней до истечения. Дальше процедура всё равно ручная: получить новый .pfx, запустить конвертацию, залить в каталог, перезапустить контейнер.

Что в итоге получилось

У тебя на руках рабочая цепочка: конечный плюс промежуточный плюс корневой, конвертированный ключ без пароля, PEM-файлы в каталоге custom_ssl с монтированием через volume. NPM отдаёт этот сертификат клиентам, браузеры с установленным корневым сертификатом Минцифры видят зелёный замочек, openssl s_client показывает тройку сертификатов без обрывов. Через год ты пересоберёшь всё за двадцать минут, потому что конвертация это одна команда, а процедура уже отработана.

Если что-то из этого не сошлось, посмотри в первую очередь цепочку и перезапуск контейнера. В восьмидесяти процентах случаев проблема сидит ровно там.

Не заработало?
Открой комментарии и напиши, что видишь: вывод openssl s_client, вывод docker logs NPM, какой браузер ругается. С этой тройкой данных я разберу твой случай быстрее, чем читать всю переписку с УЦ. Если заработало, тоже напиши, интересно, что было узким местом на твоей стороне.
[/su_box>

Оставайтесь на связи

Рецепты от IT-боли. Без воды, без рекламы, без маркетинговой шелухи.

Подписаться на IT-Аптеку →
Поделитесь:

4 комментария к “Настройка NPM российские SSL сертификаты: полная установка сертификата Минцифры”

  1. Дмитрий К.

    NPM у меня работает в докер-сваpме за Traefik, домен рвётся на внутренний nginx в другом контейнере, потому что стейджинг и прод за одним IP. УЦ выдал .pfx на четыре сертификата, а не три: в цепочке оказался два промежуточных (старый и новый корень). В статье такой кейс не разобран. Проблема в том, что Traefik видит только сертификат, который я положил в NPM, а второй уровень терминейта у него свой. Как правильно собрать PEM, чтобы промежуточные шли в правильном порядке, если один из них уже не актуален, но УЦ его всё ещё отдаёт, и не сломает ли это обновление, когда старый истечёт?

    1. Четыре сертификата в pfx обычно означают, что УЦ отдаёт обе ветки доверия: старый и новый промежуточный. Собрать можно двумя способами. Первый: оставить полную цепочку как есть, порядок листовой, новые промежуточные, корень, и в конце старый промежуточный. Nginx и Traefik спокойно обрабатывают дополнительные неиспользуемые сертификаты в цепочке, главное чтобы первый был листовой. Проверь через openssl s_client -connect domain:443 -showcerts, что браузерная цепочка строится до корня, который в клиентском хранилище. Второй вариант чище: оставить только актуальную ветку. Вытащить её можно из pfx через openssl pkcs12 -in file.pfx -nokeys -clcerts для листового, а остальные взять из вывода openssl pkcs12 -in file.pfx -nokeys -cacerts. Когда старый промежуточный истечёт, ничего не сломается: клиент его просто не выберет, если в хранилище есть новый корень. Traefik при этом терминейтит свой TLS, и до NPM трафик идёт уже расшифрованный, поэтому цепочка NPM влияет только на внешний контур. Проверь ещё, что файлы в /data/custom_ssl пережили перезапуск: сделай docker restart nginx-proxy-manager и сразу openssl s_client, чтобы увидеть, подхватился ли новый порядок, иначе просто отдаётся старая цепочка из внутренней базы.

  2. Дмитрий К.

    У меня NPM живёт не на голом хосте, а внутри Synology в Docker, и папки /data/custom_ssl на диске просто нет, потому что всё зашито в btrfs-том самого пакета. Пробовал цеплять через File Station: файлы вижу, но после перезапуска контейнера они откатываются к прежнему состоянию, будто их и не было. Подскажи, как в таком закрытом окружении закрепить PEM и ключ так, чтобы они пережили не только рестарт, но и обновление самого пакета NPM, и куда смотреть в логах, если сертификат подхватился, а nginx всё равно отдаёт старую цепочку?

    1. На Synology есть рабочий обход. Контейнер NPM из пакета хранит данные не в томе, который ты видишь через File Station, а в отдельном разделе Docker. Сначала найди реальный путь: docker inspect nginx-proxy-manager и в блоке Mounts посмотри поле Source для тома /data. Дальше два варианта. Первый: переопредели маппинг через переменную окружения в настройках пакета, если версия пакета это позволяет. Второй, более надёжный: не трогай внутренние папки, а примонтируй свою папку с сертификатами отдельным volume и укажи на неё путь в конфиге кастомного SSL. Проверить, что подхватилось, можно так: docker exec -it nginx-proxy-manager ls -la /data/custom_ssl. Если файлов нет, значит маппинг не сработал. И отдельно проверь логи: docker logs nginx-proxy-manager 2>&1 | grep -i ssl, там будет видно, какой именно файл nginx пытается открыть при старте. Если в логах ошибка вида cannot load certificate, значит путь в конфиге не совпадает с тем, где реально лежит PEM.

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Прокрутить вверх