host/proxmox-mcp-setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
80a9eab258ff460a196cdd241905367a72e29e32
proxmox-mcp-setup/DEPLOYMENT.md
T

9.6 KiB
Raw Blame History

Развёртывание Proxmox MCP и TrueNAS MCP

Инструкция предназначена для развёртывания стека Docker Compose на TrueNAS-хосте 192.168.31.100, где также работает Open WebUI.

Состав стека:

  • proxmox-mcp-pve — Proxmox MCP для сервера pve, порт 8811;
  • proxmox-mcp-kybinka — Proxmox MCP для сервера kybinka, порт 8812;
  • proxmox-mcp-pve1 — Proxmox MCP для сервера pve1, порт 8813;
  • truenas-mcp — TrueNAS MCP, порт 8814.

1. Предварительные требования

На хосте TrueNAS должны быть доступны:

  • Docker Engine и Docker Compose plugin;
  • рабочий каталог /mnt/ssd/apps/mcp;
  • исходники TrueNAS MCP в каталоге /mnt/ssd/apps/mcp/truenas;
  • файл /mnt/ssd/apps/mcp/truenas/Dockerfile;
  • сетевой доступ от Docker-хоста к Proxmox API и TrueNAS API.

Проверьте версии:

docker --version
docker compose version

Перейдите в каталог, где находятся compose.yaml и .env:

cd /mnt/ssd/apps/mcp

2. Подготовка конфигурационных каталогов

mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}

Каждый Proxmox MCP получает собственный config.json. Пример для pve:

{
  "proxmox": {
    "host": "192.168.31.2",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "openwebui-token",
    "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE"
  },
  "logging": {
    "level": "INFO"
  },
  "security": {
    "dev_mode": true
  }
}

Для kybinka и pve1 измените proxmox.host, token_name и token_value.

Права доступа к конфигурациям:

chmod 700 /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}
chmod 600 /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}/config.json

Проверьте JSON до запуска:

for file in /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}/config.json; do
  [ -f "$file" ] && python3 -m json.tool "$file" >/dev/null && echo "OK: $file"
done

auth.token_value — секрет подключения MCP к Proxmox. Он не используется в Open WebUI.

3. Подготовка переменных окружения

Скопируйте шаблон:

cp .env.example .env
chmod 600 .env

Сгенерируйте отдельные Bearer-ключи для OpenAPI:

openssl rand -hex 32

Внесите разные значения в:

PROXMOX_PVE_API_KEY=...
PROXMOX_KYBINKA_API_KEY=...
PROXMOX_PVE1_API_KEY=...
TRUENAS_API_KEY=...

Не добавляйте .env в Git. Файл уже включён в .gitignore.

Адрес публикации портов

В .env:

MCP_BIND_ADDRESS=192.168.31.100

Это позволяет Open WebUI обращаться к сервисам по LAN-адресу. Если Open WebUI и MCP доступны только локально, используйте 127.0.0.1. При публикации на LAN-адрес ограничьте входящие соединения firewall-правилом только для хоста Open WebUI.

4. Проверка Compose-файла

До запуска выполните:

docker compose --env-file .env config >/tmp/proxmox-mcp-compose-rendered.yaml
docker compose --env-file .env config --quiet

Проверьте, что отрендеренный файл не содержит неожиданных путей или настроек. Не публикуйте его, если в нём присутствуют раскрытые секреты.

Если truenas/Dockerfile отсутствует, сборка truenas-mcp завершится ошибкой. В этом случае сначала разместите исходники TrueNAS MCP в каталоге ./truenas.

5. Первый запуск

Соберите TrueNAS MCP и запустите весь стек:

docker compose --env-file .env up -d --build

Проверьте состояние:

docker compose ps
docker compose logs --tail=100 proxmox-mcp-pve
docker compose logs --tail=100 proxmox-mcp-kybinka
docker compose logs --tail=100 proxmox-mcp-pve1
docker compose logs --tail=100 truenas-mcp

6. Проверка HTTP API

Проверка жизнеспособности Proxmox MCP:

curl -f http://192.168.31.100:8811/livez
curl -f http://192.168.31.100:8812/livez
curl -f http://192.168.31.100:8813/livez

Проверка спецификации OpenAPI:

curl -f http://192.168.31.100:8811/openapi.json >/tmp/pve-openapi.json
curl -f http://192.168.31.100:8812/openapi.json >/tmp/kybinka-openapi.json
curl -f http://192.168.31.100:8813/openapi.json >/tmp/pve1-openapi.json

Проверка Bearer-ключа:

curl -f \
  -H "Authorization: Bearer ${PROXMOX_PVE_API_KEY}" \
  http://192.168.31.100:8811/health

Если endpoint /health в используемой версии образа отсутствует, ориентируйтесь на /livez и ответ /openapi.json.

7. Подключение к Open WebUI

Для каждого сервера создайте отдельный External Tool Server:

Сервис Базовый URL OpenAPI
Proxmox pve http://192.168.31.100:8811 openapi.json
Proxmox kybinka http://192.168.31.100:8812 openapi.json
Proxmox pve1 http://192.168.31.100:8813 openapi.json
TrueNAS MCP http://192.168.31.100:8814 openapi.json

Используйте авторизацию Bearer и соответствующий ключ из .env.

Важно:

  • в URL указывайте только базовый адрес;
  • не добавляйте /openapi.json в базовый URL;
  • не используйте auth.token_value из Proxmox config.json как Bearer-ключ Open WebUI;
  • для каждого сервиса используйте собственный ключ.

8. Обновление

Перед обновлением сохраните текущую конфигурацию:

cp .env .env.backup.$(date +%Y%m%d-%H%M%S)
docker compose config > compose.rendered.backup.yaml

Обновите образы и пересоберите TrueNAS MCP:

docker compose pull
docker compose up -d --build

Проверьте состояние после обновления:

docker compose ps
docker compose logs --since=10m

В production рекомендуется заменить :latest в compose.yaml на конкретный tag или digest образа.

9. Откат

Если новая версия работает некорректно:

docker compose down
docker compose up -d

Для полноценного отката необходимо вернуть предыдущую версию image в compose.yaml, затем выполнить:

docker compose pull
docker compose up -d --build

10. Диагностика

Invalid API key

Проверьте, что Bearer-ключ Open WebUI точно совпадает с переменной соответствующего сервиса:

docker compose config | grep -E 'PROXMOX_API_KEY|TRUENAS_API_KEY'

Не вставляйте вывод этой команды в публичный чат или issue.

Connection closed

Проверьте первичную ошибку в логах:

docker compose logs --tail=200 proxmox-mcp-pve

Затем проверьте:

  • доступность Proxmox API с Docker-хоста;
  • правильность host, port, token_name и token_value;
  • существование смонтированного config.json;
  • соответствие версии OpenAPI-интерфейса и конфигурации Open WebUI.

Ошибка bind на порт

Проверьте занятые порты:

ss -ltnp | grep -E ':8811|:8812|:8813|:8814'

Измените MCP_BIND_ADDRESS или внешние порты в compose.yaml.

Контейнер завершается при включённом hardening

В Compose включены read_only, no-new-privileges и cap_drop: ALL. Если конкретная версия образа требует запись в каталог или capability, проверьте ошибку в логах и ослабляйте только проблемную настройку. Не удаляйте весь hardening без необходимости.

11. Безопасность

  • Не коммитьте .env, реальные config.json, API-ключи и пароли.
  • Используйте отдельные токены для каждого Proxmox-сервера.
  • Минимизируйте ACL токенов Proxmox.
  • Для TrueNAS предпочтительно использовать HTTPS и TRUENAS_VERIFY_SSL=true.
  • TRUENAS_ENABLE_DESTRUCTIVE_OPS=false оставляйте включённым, пока destructive-операции не потребуются явно.
  • Не публикуйте MCP-порты в Интернет.
  • Зафиксируйте версии образов вместо latest.
  • Регулярно проверяйте логи и свободное место Docker-хранилища.
Reference in New Issue View Git Blame Copy Permalink