From e9fd8de0801506083db45b3e29789f1e964b868e Mon Sep 17 00:00:00 2001 From: host Date: Wed, 5 Aug 2026 19:36:48 +0300 Subject: [PATCH] =?UTF-8?q?=D0=98=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D0=BB=20=D0=A8=D0=B0=D0=B3=202:=20=D0=B4=D0=BE=D0=B1=D0=B0?= =?UTF-8?q?=D0=B2=D0=B8=D0=BB=20=D0=BA=D0=BE=D1=80=D1=80=D0=B5=D0=BA=D1=82?= =?UTF-8?q?=D0=BD=D1=8B=D0=B5=20=D0=BA=D0=BE=D0=BD=D1=84=D0=B8=D0=B3=D0=B8?= =?UTF-8?q?=20Proxmox=20=D1=81=20logging?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- proxmox-mcp-open-webui-setup.md | 184 +++++++++++++++++++------------- 1 file changed, 108 insertions(+), 76 deletions(-) diff --git a/proxmox-mcp-open-webui-setup.md b/proxmox-mcp-open-webui-setup.md index a50ee89..6b04b1a 100644 --- a/proxmox-mcp-open-webui-setup.md +++ b/proxmox-mcp-open-webui-setup.md @@ -1,48 +1,52 @@ # Установка Proxmox MCP-сервера и подключение к Open WebUI -Инструкция под твою инфраструктуру: **pve** (192.168.31.2), **kybinka** (192.168.1.10), **pve1** (192.168.31.4), **TrueNAS** (192.168.31.100, там же крутится Open WebUI). +Инструкция под твою инфраструктуру: **pve** (192.168.31.2), **kybinka** (192.168.1.10), **pve1** (192.168.31.4), **TrueNAS** (192.168.31.100, там же работает Open WebUI). -Используем проект **ProxmoxMCP-Plus** — он умеет работать сразу в двух режимах: -- родной MCP (для Claude Desktop, Cursor и т.д.) -- **OpenAPI-мост** — именно он нужен для Open WebUI, потому что Open WebUI не умеет подключаться к MCP напрямую, а понимает только обычный HTTP/OpenAPI. +Используем проект **ProxmoxMCP-Plus**. Для Open WebUI применяется его OpenAPI-интерфейс. ## ⚠️ Важный момент про архитектуру -Твои три Proxmox-узла (`pve`, `kybinka`, `pve1`) — это **не один кластер**, а три независимых сервера в разных подсетях. Один MCP-контейнер умеет говорить только с **одним** Proxmox API за раз. Значит, чтобы управлять всеми тремя из чата, нужно поднять **три отдельных контейнера** (по одному на узел), каждый на своём порту, и подключить их к Open WebUI как три отдельных инструмента. - -TrueNAS отдельно — это **не Proxmox**, и ProxmoxMCP-Plus с ним не работает. Управлять TrueNAS через тот же чат — отдельная задача (нужен другой MCP-сервер, для TrueNAS API). Ниже — только про Proxmox-узлы, но покажу, где ты потом можешь добавить TrueNAS-инструмент рядом. - -Разворачивать контейнеры удобнее всего **на TrueNAS** — там уже крутится Open WebUI, сервер работает постоянно, и можно поднимать Docker-контейнеры через Dockge. +Узлы `pve`, `kybinka` и `pve1` — независимые Proxmox-серверы. Для каждого узла требуется отдельный контейнер MCP с отдельным портом. --- ## Шаг 1. Создать API-токен на каждом Proxmox-узле -Токен создаётся отдельно на **каждом** из трёх узлов (pve, kybinka, pve1), заходишь в веб-интерфейс каждого по отдельности. +Токен создаётся отдельно на каждом узле. 1. Открой веб-интерфейс узла, например `https://192.168.31.2:8006`. -2. Слева: **Datacenter → Permissions → API Tokens**. +2. Перейди в **Datacenter → Permissions → API Tokens**. 3. Нажми **Add**: - - User: `root@pam` (для учёбы ок, в проде лучше завести отдельного пользователя с ограниченными правами) - - Token ID: `mcp-token` - - **сними галку** "Privilege Separation" (иначе токену нужно отдельно назначать права) -4. Нажми **Add**, скопируй **Token ID** и **Secret** — секрет показывается один раз, сохрани его сразу в текстовый файл. + - User: `root@pam`; + - Token ID: `openwebui-token`; + - отключи **Privilege Separation**, если используешь права пользователя напрямую. +4. Сохрани **Token ID** и **Secret**. Secret показывается только один раз. -Повтори для `kybinka` и `pve1`. В итоге у тебя будет 3 пары `user@realm!token-name` + `secret`. +Повтори для `kybinka` и `pve1`. В конфигурацию нужно подставить секрет токена соответствующего узла. --- ## Шаг 2. Подготовить конфиги на TrueNAS -Зайди на TrueNAS по SSH (или через Shell в веб-интерфейсе), создай папку для конфигов: +Файлы конфигурации должны находиться в следующих каталогах: + +```text +/mnt/ssd/apps/mcp/pve/config.json +/mnt/ssd/apps/mcp/kybinka/config.json +/mnt/ssd/apps/mcp/pve1/config.json +``` + +Если каталоги ещё не созданы, выполни на TrueNAS через SSH или Shell: ```bash mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1} ``` -(используется пул `ssd`; если у тебя он смонтирован по другому пути или ты хочешь другой пул — замени `/mnt/ssd` на свой). +> В каждом файле должен быть секрет API-токена именно соответствующего Proxmox-узла. Не оставляй текст `СЮДА_СЕКРЕТ_ТОКЕНА_*` в рабочем конфиге. -Создай конфиг для узла **pve**: +### Конфигурация узла `pve` + +Создай файл `/mnt/ssd/apps/mcp/pve/config.json`: ```bash cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF' @@ -54,32 +58,94 @@ cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF' }, "auth": { "user": "root@pam", - "token_name": "mcp-token", + "token_name": "openwebui-token", "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE" + }, + "logging": { + "level": "INFO" } } EOF ``` -Аналогично создай `config.json` в папках `kybinka` (host `192.168.1.10`) и `pve1` (host `192.168.31.4`), с соответствующими токенами. +### Конфигурация узла `kybinka` -> `verify_ssl: false` — потому что у Proxmox самоподписанный сертификат по умолчанию. Для учебного стенда это нормально. +Создай файл `/mnt/ssd/apps/mcp/kybinka/config.json`: + +```bash +cat > /mnt/ssd/apps/mcp/kybinka/config.json << 'EOF' +{ + "proxmox": { + "host": "192.168.1.10", + "port": 8006, + "verify_ssl": false + }, + "auth": { + "user": "root@pam", + "token_name": "openwebui-token", + "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_KYBINKA" + }, + "logging": { + "level": "INFO" + } +} +EOF +``` + +### Конфигурация узла `pve1` + +Создай файл `/mnt/ssd/apps/mcp/pve1/config.json`: + +```bash +cat > /mnt/ssd/apps/mcp/pve1/config.json << 'EOF' +{ + "proxmox": { + "host": "192.168.31.4", + "port": 8006, + "verify_ssl": false + }, + "auth": { + "user": "root@pam", + "token_name": "openwebui-token", + "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE1" + }, + "logging": { + "level": "INFO" + } +} +EOF +``` + +Проверь корректность всех JSON-файлов до запуска контейнеров: + +```bash +python3 -m json.tool /mnt/ssd/apps/mcp/pve/config.json +python3 -m json.tool /mnt/ssd/apps/mcp/kybinka/config.json +python3 -m json.tool /mnt/ssd/apps/mcp/pve1/config.json +``` + +Если ошибок нет, команды выведут отформатированное содержимое JSON. При необходимости ограничь права доступа к файлам с токенами: + +```bash +chmod 600 /mnt/ssd/apps/mcp/{pve,kybinka,pve1}/config.json +``` + +> `verify_ssl: false` отключает проверку TLS-сертификата Proxmox. Это обычно требуется для самоподписанного сертификата в локальной сети. Для production лучше установить доверенный сертификат и включить проверку. --- ## Шаг 3. Запустить три контейнера через Dockge -Вместо запуска через Shell создай один Stack (стек) в веб-интерфейсе **Dockge**. Все три контейнера будут управляться из одного стека. +В Dockge создай один Stack с именем `proxmox-mcp`. -1. Открой Dockge в браузере. -2. Нажми **Create Stack** (или **+**). -3. Введи имя стека, например `proxmox-mcp`. -4. В качестве рабочей директории стека укажи: +1. Открой Dockge. +2. Нажми **Create Stack** или **+**. +3. Укажи имя `proxmox-mcp`. +4. Укажи рабочую директорию стека: `/mnt/ssd/apps/mcp` - Если Dockge уже использует собственную корневую директорию для стеков, выбери или создай каталог, соответствующий этому пути. Важно, чтобы каталоги `pve`, `kybinka` и `pve1` с файлами `config.json` находились внутри рабочей директории стека. -5. В редакторе compose-файла вставь следующий конфиг: +5. Вставь в compose-редактор: ```yaml services: @@ -117,67 +183,38 @@ services: - /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro ``` -6. Замени значения `ключ-для-*` на собственные длинные ключи. Ключи можно сгенерировать заранее командой: +6. Замени значения `ключ-для-*` на свои ключи. +7. Нажми **Save**, затем **Deploy** / **Up** / **Start**. -```bash -openssl rand -hex 32 -``` - -Команду можно выполнить на любом компьютере, где установлен OpenSSL. Для каждого контейнера используй отдельный ключ. -7. Нажми **Save**. -8. Нажми **Deploy** / **Up** / **Start** — название кнопки зависит от версии Dockge. - -После запуска в Dockge должны появиться три контейнера: - -- `proxmox-mcp-pve` — порт `8811`; -- `proxmox-mcp-kybinka` — порт `8812`; -- `proxmox-mcp-pve1` — порт `8813`. - -> Если Dockge не может найти `config.json`, проверь, что рабочая директория стека действительно `/mnt/ssd/apps/mcp`, а файлы находятся по адресам `/mnt/ssd/apps/mcp/pve/config.json`, `/mnt/ssd/apps/mcp/kybinka/config.json` и `/mnt/ssd/apps/mcp/pve1/config.json`. +В результате должны запуститься контейнеры `proxmox-mcp-pve`, `proxmox-mcp-kybinka` и `proxmox-mcp-pve1` на портах `8811`, `8812` и `8813` соответственно. --- ## Шаг 4. Проверить, что контейнеры работают -Проверку можно выполнить через встроенный Terminal/Shell TrueNAS или другим компьютером в сети: - ```bash curl -f http://192.168.31.100:8811/livez # pve curl -f http://192.168.31.100:8812/livez # kybinka curl -f http://192.168.31.100:8813/livez # pve1 ``` -Каждый должен ответить `200 OK`. Дальше проверь авторизованный доступ (подставь свой ключ и порт): +Авторизованный запрос: ```bash curl -H "Authorization: Bearer ключ-для-pve" http://192.168.31.100:8811/health ``` -Если видишь `{"status":"ok"}` (или похожее) — контейнер видит Proxmox API. - --- ## Шаг 5. Подключить к Open WebUI -Раз Open WebUI и MCP-контейнеры теперь на одной машине (TrueNAS), обращаться можно либо по `localhost`, либо по IP TrueNAS — зависит от того, в одной ли они Docker-сети. Проще всего указывать IP: `192.168.31.100`. +В Open WebUI добавь три OpenAPI Tool Server: -1. Зайди в Open WebUI → **Settings (шестерёнка) → Admin Settings → Tools** (в некоторых версиях — **Workspace → Tools**, а сами инструменты подключаются как "OpenAPI Tool Server"). -2. Нажми **Add Tool Server** (или "+"): - - **URL**: `http://192.168.31.100:8811/openapi.json` - - **Auth**: Bearer, вставь ключ `ключ-для-pve` - - Имя — например `Proxmox pve` -3. Повтори для kybinka (`http://192.168.31.100:8812/openapi.json`) и pve1 (`http://192.168.31.100:8813/openapi.json`), каждый со своим ключом и понятным именем. -4. Сохрани. В списке моделей/чата должна появиться возможность включить эти инструменты (обычно — иконка инструментов рядом с полем ввода сообщения, там выбираешь, какие серверы разрешить в конкретном чате). +- `http://192.168.31.100:8811/openapi.json` — `Proxmox pve`; +- `http://192.168.31.100:8812/openapi.json` — `Proxmox kybinka`; +- `http://192.168.31.100:8813/openapi.json` — `Proxmox pve1`. ---- - -## Шаг 6. Проверка в чате - -Открой новый чат в Open WebUI, включи инструмент `Proxmox pve`, и напиши что-то вроде: - -> Покажи список нод и виртуальных машин на pve - -Если всё настроено верно, модель вызовет `get_nodes` / `get_vms` и покажет актуальные данные (например, VM `haos-16.1` и LXC `mariadb`, `Panel` — как в твоей инвентаризации). +Для каждого сервера укажи свой Bearer-ключ из `PROXMOX_API_KEY` в compose-конфигурации Dockge. --- @@ -185,12 +222,7 @@ curl -H "Authorization: Bearer ключ-для-pve" http://192.168.31.100:8811/h | Симптом | Причина | | --- | --- | -| Инструмент не появляется в Open WebUI | Проверь, что URL заканчивается на `/openapi.json`, а не просто на `/docs` | -| 401 Unauthorized | Ключ Bearer в Open WebUI не совпадает с `PROXMOX_API_KEY` в compose-файле Dockge | -| Контейнер падает при старте | Опечатка в `config.json` (проверь логи контейнера в Dockge) | -| Модель "не видит" VM | Токен Proxmox создан с "Privilege Separation" — права токена ограничены, пересоздай без этой галки или явно выдай права в Datacenter → Permissions | - -## Что дальше - -- Если захочешь и **изменять** серверы (создавать/удалять VM), а не только смотреть — это уже доступно из коробки, но советую сначала потренироваться на `pve1` (он у тебя простаивает и ничего важного там нет). -- Для управления **TrueNAS** из того же чата понадобится отдельный MCP/OpenAPI-сервер под TrueNAS API — если нужно, могу подобрать и расписать так же подробно. \ No newline at end of file +| Контейнер падает при старте | Невалидный JSON или неверный путь к `config.json` | +| `401 Unauthorized` | Bearer-ключ не совпадает с `PROXMOX_API_KEY` | +| Инструмент не появляется в Open WebUI | Проверь URL `/openapi.json` и доступность соответствующего порта | +| Модель не видит VM | Проверь права API-токена Proxmox и логи контейнера в Dockge |