Сообщение «API service not available» в Proxmox VE обычно означает, что веб-интерфейс не может связаться с демоном pveproxy или связанными с ним службами кластера — чаще всего проблема возникает после некорректного обновления, переполнения диска или рассинхронизации узлов в кластере. Доступ к виртуальным машинам при этом может сохраняться, но управление через браузер и API становится невозможным.
Хорошая новость: сам гипервизор и гостевые системы обычно продолжают работать, а ошибка касается именно управляющего слоя. Ниже разберём, как проверить состояние служб, что чаще всего ломается и как восстановить доступ без переустановки системы.
Что означает ошибка и какие службы за неё отвечают
За работу API и веб-интерфейса Proxmox VE отвечает связка из нескольких демонов. Основной — pveproxy, который принимает HTTPS-подключения на порту 8006 и проксирует запросы к остальным компонентам. Рядом работают pvedaemon (обработка API-запросов), pvestatd (сбор статистики) и кластерные службы pmxcfs и corosync, если узел входит в кластер.
Когда браузер показывает «API service not available», это значит, что pveproxy либо не запущен, либо запущен, но не может получить ответ от внутренних сервисов. Вторая ситуация коварнее: служба формально активна, но запросы зависают или возвращают ошибку.
Первичная диагностика через SSH или консоль
Поскольку веб-интерфейс недоступен, вам понадобится доступ к серверу по SSH или через физическую/IPMI-консоль. Первым делом проверьте состояние ключевых служб:
systemctl status pveproxy pvedaemon pvestatd pmxcfsЕсли какая-то из служб в состоянии failed или inactive, это уже указывает направление поиска. Дополнительно посмотрите свежие записи журнала — там часто видна первопричина:
journalctl -u pveproxy -n 100 --no-pager- 🔍 pveproxy failed — проверяйте сертификаты и свободное место на диске;
- 🗄️ pmxcfs не стартует — вероятны проблемы с кластерной файловой системой
/etc/pve; - 🌐 corosync в ошибке — узел потерял связь с кластером или сменился сетевой интерфейс;
- 💾 службы падают без явной причины — проверьте заполнение корневого раздела.
Проверка свободного места на диске
Одна из самых частых и при этом неочевидных причин — переполнение корневого раздела. Когда место заканчивается, pmxcfs не может писать в /etc/pve, службы начинают падать, и API перестаёт отвечать. Проверка занимает секунды:
df -hОбратите внимание на корневой раздел / и раздел с /var. Типичные «пожиратели» места — старые журналы в /var/log, резервные копии, случайно попавшие на локальный диск, и накопленные пакеты после обновлений. Очистить кэш пакетов можно командой apt clean, а старые журналы — через journalctl --vacuum-time=7d.
⚠️ Внимание: не удаляйте файлы из /etc/pve вручную, пока не убедитесь, что понимаете их назначение. Это виртуальная файловая система pmxcfs, и некорректные действия могут нарушить конфигурацию кластера.
Проблемы с SSL-сертификатами
Демон pveproxy при старте загружает SSL-сертификаты узла. Если файлы сертификатов повреждены, удалены или имеют неверные права, служба может не запуститься, и вы получите ту самую ошибку недоступности API. Стандартные пути — /etc/pve/local/pve-ssl.pem и /etc/pve/local/pve-ssl.key.
Проверьте, существуют ли эти файлы и читаются ли они. Если узел входит в кластер, убедитесь, что pmxcfs смонтирована и каталог /etc/pve доступен — без него pveproxy не найдёт сертификаты. При повреждении сертификата его можно пересоздать штатными средствами Proxmox, но точную команду для вашей версии лучше сверить с официальной документацией, так как синтаксис может отличаться между релизами.
Как понять, что виноват именно сертификат
В журнале pveproxy (journalctl -u pveproxy) появляются строки об ошибках загрузки ключа или сертификата — например, упоминания SSL, PEM или невозможности прочитать файл. Если таких записей нет, а служба просто не стартует молча, чаще виноваты диск или pmxcfs.
Сбои кластера: pmxcfs и corosync
Если сервер входит в кластер, ошибка API нередко связана с потерей кворума или конфликтом corosync. Проверьте состояние кластера:
pvecm statusЕсли команда сообщает об отсутствии кворума, файловая система /etc/pve переходит в режим только для чтения, и управляющие службы работают некорректно. Типичный сценарий — выключение части узлов кластера или смена IP-адреса/hostname одного из них без правки конфигурации кластера.
Для временной диагностики на одиночном узле, вышедшем из кластера, существует режим local mode для pmxcfs, однако применять его стоит осознанно: это вмешательство в кластерную конфигурацию, и порядок действий зависит от того, планируете ли вы возвращать узел в кластер. Перед любыми операциями с corosync.conf сделайте резервную копию конфигурации.
| Симптом | Вероятная причина | Первое действие |
|---|---|---|
| pveproxy в статусе failed | Проблема с сертификатами или портом 8006 | Смотреть journalctl -u pveproxy |
| Все службы падают разом | Переполнен корневой раздел | Выполнить df -h, очистить место |
| /etc/pve пуст или read-only | pmxcfs не смонтирована, нет кворума | Проверить pvecm status |
| Ошибка после обновления пакетов | Прерванный apt, битые зависимости | Запустить apt -f install |
| API недоступен только из сети | Файрвол или смена IP узла | Проверить iptables и доступность порта 8006 |
Ошибка после обновления системы
Немало случаев связано с прерванным или неполным обновлением пакетов Proxmox VE. Если обновление оборвалось (перезагрузка, обрыв SSH, переполнение диска в процессе), часть пакетов может остаться в несогласованном состоянии. Проверить и попытаться исправить это можно так:
apt update
apt -f install
dpkg --configure -a
После завершения перезапустите ключевые службы: systemctl restart pveproxy pvedaemon pvestatd. Если apt сообщает о конфликтах репозиториев, убедитесь, что у вас корректно настроены источники пакетов — для установок без подписки должен использоваться репозиторий pve-no-subscription, а enterprise-репозиторий без активной подписки будет выдавать ошибки.
⚠️ Внимание: не выполняйте apt dist-upgrade вслепую на продуктивном сервере с запущенными ВМ. Сначала убедитесь, что у вас есть резервные копии конфигурации и возможность откатиться, а обновления проводите в окно обслуживания.
☑️ Порядок восстановления доступа к API
Когда ничего не помогло
Если службы стартуют, диск свободен, кластер в порядке, а API по-прежнему недоступен, копайте глубже. Проверьте, не занят ли порт 8006 другим процессом (ss -tlnp | grep 8006), посмотрите общий системный журнал journalctl -xe на предмет ошибок сегментации или нехватки памяти — OOM-killer иногда убивает управляющие демоны на серверах с перегруженной памятью.
Полезно также проверить целостность конфигурации узла в /etc/pve/nodes/ и системные лимиты. В сложных случаях имеет смысл изучить журналы за период, предшествующий появлению ошибки: первопричина (например, внезапная перезагрузка или сбой диска) часто видна задолго до того, как пользователь заметил недоступность веб-интерфейса.
⚠️ Внимание: если сервер является частью продуктивного кластера и вы не уверены в последствиях команд, сначала зафиксируйте текущее состояние (выводы диагностических команд, копии конфигов) и сверьтесь с официальной документацией Proxmox VE для вашей версии. Ошибочные действия с кластерными службами могут затронуть соседние узлы.
Частые вопросы
Виртуальные машины продолжают работать при ошибке API service not available?
Да, в подавляющем большинстве случаев гостевые системы работают штатно — страдает только управляющий слой (веб-интерфейс и API). Однако без доступа к API вы не сможете управлять ВМ, поэтому восстанавливать службы нужно оперативно.
Можно ли просто перезагрузить сервер, чтобы исправить ошибку?
Перезагрузка иногда временно помогает, но если причина в переполненном диске, битых пакетах или потере кворума, ошибка вернётся. Лучше сначала провести диагностику через SSH и устранить первопричину.
Ошибка появляется только при входе через браузер, а по SSH всё работает. Что делать?
Проверьте, слушает ли pveproxy порт 8006 командой ss -tlnp | grep 8006, а также не блокирует ли порт файрвол. Попробуйте перезапустить pveproxy и очистить кэш браузера или открыть интерфейс в режиме инкогнито.
Может ли ошибка быть связана с истёкшей подпиской Proxmox?
Нет, отсутствие подписки не отключает API и веб-интерфейс — она влияет только на доступ к enterprise-репозиторию обновлений. Ошибка недоступности API всегда указывает на техническую проблему со службами, диском или кластером.
Как предотвратить повторение ошибки в будущем?
Настройте мониторинг свободного места на диске, проводите обновления в плановые окна с резервными копиями, следите за состоянием кворума в кластере и периодически проверяйте журналы служб pveproxy и pmxcfs на предмет ранних признаков сбоев.