Portainer на сервере: частые ошибки и решения

MAATRIX

Portainer ставится одной командой — и ровно поэтому ломается у всех одинаково: панель встречает сообщением «timed out for security purposes», окружение показывает ноль контейнеров при живом Docker, стек из веб-редактора падает на build path ... does not exist. Ниже — частые ошибки Portainer по схеме «точный текст → причина → команда».

Куда смотреть в первую очередь

Portainer — один контейнер, и сломаться в нём может три вещи: процесс, доступ к Docker API и доступ к панели по сети. Первые тридцать секунд отладки всегда такие:

docker ps -a --filter name=portainer --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
docker inspect -f '{{range .Mounts}}{{.Name}}{{.Source}} -> {{.Destination}}{{println}}{{end}}' portainer
docker logs --tail 100 portainer

Здоровая машина отвечает:

portainer   Up 19 days    8000/tcp, 0.0.0.0:9443->9443/tcp
portainer_data -> /data
/var/run/docker.sock -> /var/run/docker.sock

Дальше по статусу. Restarting (1) 5 seconds ago — процесс падает на старте, ответ в логах. Exited (137) — убит по памяти. Up с пустой панелью — сломан доступ к Docker. Up, а браузер не открывается — сеть и публикация порта.

Второе — почти всё состояние Portainer лежит в одном файле:

Порты: 9443 — HTTPS-панель, 8000 — туннель Edge-агентов, 9001 — порт агента на нодах. Грабля старых инструкций: в свежих сборках 2.x чистый HTTP выключен по умолчанию, контейнер слушает только 9443, и скопированное откуда-то -p 9000:9000 даёт ERR_EMPTY_RESPONSE.

«Timed out for security purposes»: не создаётся администратор

Первый контакт с Portainer выглядит как поломка, хотя это защита. Вместо формы создания пользователя:

Your Portainer instance timed out for security purposes.
To re-enable your Portainer instance, you will need to restart Portainer.

Свежий Portainer без администратора — открытая дверь к Docker, поэтому на создание первого пользователя даётся окно около пяти минут после старта контейнера. Лечится одним docker restart portainer, после чего сразу открываете https://IP:9443. Пароль — минимум 12 символов, короче форма не примет.

Если сервер разворачивается скриптом или Ansible, ловить окно бессмысленно: задайте пароль заранее. Хеш даёт htpasswd из пакета apache2-utils (на AlmaLinux — httpd-tools):

htpasswd -nbB admin 'VashSilnyjParol2026' | cut -d ':' -f 2
docker run -d --name portainer ... portainer/portainer-ce:latest \
  --admin-password '$2y$05$q1Kx8Zt0nR7pV3sYc1LmEeJ9hB6wA4uT2dN5fG8kX0oQ'

Тонкость, на которой спотыкаются: в docker-compose.yml или в стеке каждый $ надо удвоить до $$, иначе Compose примет хеш за переменные и подставит пустоту. Проще без хеша — --admin-password-file /run/secrets/portainer_pass, где в файле обычный пароль текстом.

Permission denied на docker.sock: панель есть, контейнеров нет

Второй по частоте симптом: авторизация проходит, а окружение local показывает нули. В логе:

Got permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock

Сокет не смонтирован. Вывод docker inspect из первого раздела должен содержать /var/run/docker.sock -> /var/run/docker.sock. Нет строки — пересоздайте контейнер с правильным -v: том portainer_data это переживёт.

SELinux. На AlmaLinux, Rocky и Fedora getenforce отвечает Enforcing: монтирование проходит, а обращение блокируется политикой. Подтверждение — ausearch -m avc -ts recent | grep -i docker.sock. Штатное решение из документации Portainer — добавить --privileged. Грубо, но доступ к docker.sock и без того равносилен root на хосте, так что безопасность здесь не падает.

Rootless Docker или Podman. Сокет лежит не там, где привыкли: -v /run/user/1000/docker.sock:/var/run/docker.sock для rootless, /run/podman/podman.sock для Podman (его надо поднять через systemctl enable --now podman.socket).

Отсюда правило: у кого админка Portainer, у того root на сервере, поэтому 9443 не отдают наружу голым портом. Как публиковать панель — в статье про установку Portainer на VPS, а грабли с портами — в материале Portainer не создаёт порты.

Окружение недоступно: агент, удалённые ноды и версия API

Когда контейнеров нет на удалённом окружении, источников два: версия Docker API и агент.

Слишком старый движок. Portainer говорит с Docker по фиксированной версии API, и с docker.io из репозитория дистрибутива вы получите:

Error response from daemon: client version 1.44 is too new.
Maximum supported API version is 1.41

Смотрите docker version --format '{{.Server.APIVersion}}' и обновляйте движок через curl -fsSL https://get.docker.com | sh.

Агент на удалённой ноде запускается так:

docker run -d --name portainer_agent --restart=always \
  -p 10.8.0.2:9001:9001 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -e AGENT_SECRET='obshchij-sekret' \
  portainer/agent:latest

Три вещи ломают связку чаще всего:

• AGENT_SECRET задан только на агенте. Он должен совпадать с переменной на контейнере панели, иначе UI отвечает невнятным «unable to connect to the environment».
• Разъехались версии. Не смешивайте portainer/portainer-ce:latest на панели и portainer/agent:2.19 на ноде: агент отвечает, но снапшот не собирается и данные тихо устаревают.
• Забыт монтаж /var/lib/docker/volumes. Работает всё, кроме кнопки Browse на томе.

Порт 9001 — полный контроль над Docker на ноде, и ufw allow from 203.0.113.10 to any port 9001 его не закроет: опубликованный контейнером порт обходит UFW. Надёжнее привязать агента к приватной сети или WireGuard, как в команде выше.

Стек не деплоится: ошибки Compose в веб-редакторе

Стеки Portainer — обычный docker compose, который панель запускает из /data/compose/<id> внутри своего контейнера. Отсюда все специфические ошибки.

Сборка из веб-редактора. Секция build: в стеке, набранном руками в браузере, обречена — контекста сборки на диске нет:

failed to deploy a stack: build path /data/compose/17/app either does not exist,
is not accessible, or is not a valid URL

Варианта два: готовый образ из реестра либо стек типа Repository — тогда Portainer сам клонирует Git в /data/compose/<id>.

Относительные пути в bind-mount. Строка ./data:/var/lib/postgresql/data не сломается — она сработает не так, как вы ждёте: путь резолвится относительно каталога проекта, то есть в /data/compose/17/data, и создаётся демоном на хосте, а не внутри тома Portainer. При пересоздании стека с другим id вы получите пустую базу. Правило: только именованные тома или абсолютные пути.

Переменные окружения. Файл .env рядом с текстом в редакторе не подхватывается, потому что его там нет:

WARN[0000] The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string.

Переменные задаются в блоке Environment variables формы стека — только оттуда они идут в подстановку.

Табуляции. Редактор пропускает табуляцию, а YAML — нет: yaml: line 12: did not find expected key. Ищите их через grep -Pn '\t' docker-compose.yml.

Конфликт имён и «осиротевшие» стеки. Если контейнер с таким именем уже поднят руками, деплой упадёт на Conflict. The container name "/app" is already in use. А если удалить контейнеры стека через CLI, Portainer пометит стек как orphaned — панель ориентируется на метку com.docker.compose.project. Разворачивайте заново из той же карточки, файл в /data/compose/<id> на месте.

Забытый пароль, потерянный том и обновление без отката

Сброс пароля работает только с остановленной панелью: база — BoltDB-файл с блокировкой, на живом контейнере утилита его не откроет.

docker stop portainer
docker run --rm -v portainer_data:/data portainer/helper-reset-password
docker start portainer

2026/08/28 09:14:02 Password successfully updated for user: admin
2026/08/28 09:14:02 Use the following password to login: %H2r]8Ub<Kf!

Забудете остановить контейнер — получите Failed opening the database: timeout.

А если тома нет. Проверьте docker inspect -f '{{range .Mounts}}{{.Name}} {{end}}' portainer. Ответ вида 9f3c1a... длиной 64 символа вместо portainer_data — анонимный том: контейнер запускали без -v portainer_data:/data. Данные живы, но при первом невнимательном docker rm вы теряете всё.

Бэкап — через Settings → Backup Portainer либо руками: tar czf /root/pt-$(date +%F).tar.gz -C /var/lib/docker/volumes/portainer_data/_data . Стоп контейнера обязателен, иначе база копируется в середине записи.

Обновление — это docker rm и запуск той же команды с новым тегом, том переносит всё. Но отката нет: новая версия мигрирует portainer.db вперёд, а старый бинарник её открыть отказывается и падает с жалобой, что версия базы новее поддерживаемой. Путь назад один — копия тома, снятая до обновления. Поэтому latest опасен не при перезапуске, а при пересоздании: после docker rm вы получите ту версию, что сегодня в Hub. Закрепляйте тег вида portainer/portainer-ce:2.31.3. И не чистите тома кнопкой «удалить неиспользуемые»: для Docker это всё, что не подключено к запущенному контейнеру, включая том остановленного на ночь стека с базой.

Какой сервер под Portainer взять в MAATRIX

Сама панель почти ничего не стоит. docker stats --no-stream на узле 2 vCPU / 4 ГБ:

NAME        CPU %   MEM USAGE / LIMIT     MEM %
portainer   0.31%   78.4MiB / 3.842GiB    1.99%

С пятью-шестью окружениями — 200–300 МБ. Конфигурацию определяет не панель, а то, чем вы через неё управляете.

Честно про нижнюю границу: на 1 ГБ RAM Portainer поднимется — ему хватит. Кончится всё на первой сборке образа или на Postgres по соседству: в docker ps -a появится Exited (137) сразу у нескольких контейнеров, включая панель. Два гигабайта и swap на 2 ГБ — реальный минимум. И 30 ГБ диска уходят быстро: каждый пересобранный образ на Node оставляет 400–900 МБ (почему Docker занимает всё место).

Локация — Лондон, и причина техническая. Portainer постоянно ходит в Docker Hub: тянет образы, проверяет теги, разворачивает стеки. С российских адресов Hub с середины 2024 года отвечает отказом, и первое, что вы увидите на RU-узле, — не ошибку панели, а 403 Forbidden при docker pull. Лечится зеркалами в registry-mirrors внутри /etc/docker/daemon.json, но публичные зеркала появляются и исчезают. Лондон тянет образы напрямую, пинг из Москвы — 45–60 мс. Франция равноценна для континентальной Европы, США берут под американский IP, Россия оправдана при 152-ФЗ — но тогда зеркала закладывайте сразу.

При заказе Portainer можно не ставить руками: он есть в каталоге приложений MAATRIX и ставится вместе с сервером на Ubuntu и Debian, включая 24.04 LTS. Панель поднимается на 9443 с томом portainer_data и политикой unless-stopped, доступы приходят в личный кабинет — таймаут создания администратора вас не касается. Сертификат по умолчанию самоподписанный, как заменить — в материале про самоподписанные сертификаты. Оплата — картами российских банков, по СБП, криптой или токеном MAAT: зарубежная карта для Лондона не нужна. Сомневаетесь — вот разбор Portainer или Docker CLI.

Частые вопросы