From 165b0f8f52774f776e87e02c2336d477c32988b0 Mon Sep 17 00:00:00 2001 From: host Date: Wed, 5 Aug 2026 20:11:43 +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=D1=80=D0=B0=D1=81=D0=BF=D0=BE=D0=BB=D0=BE=D0=B6=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20dev=5Fmode=20=D0=B2=20=D0=BA=D0=BE=D0=BD?= =?UTF-8?q?=D1=84=D0=B8=D0=B3=D1=83=D1=80=D0=B0=D1=86=D0=B8=D0=B8=20Proxmo?= =?UTF-8?q?x=20MCP?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- proxmox-mcp-open-webui-setup.md | 175 +++++++++++++++++--------------- 1 file changed, 94 insertions(+), 81 deletions(-) diff --git a/proxmox-mcp-open-webui-setup.md b/proxmox-mcp-open-webui-setup.md index 4aa1c0d..d3c9877 100644 --- a/proxmox-mcp-open-webui-setup.md +++ b/proxmox-mcp-open-webui-setup.md @@ -1,34 +1,31 @@ # Установка 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**. Для Open WebUI применяется его OpenAPI-интерфейс. +Используется проект **ProxmoxMCP-Plus** с OpenAPI-интерфейсом для Open WebUI. -## ⚠️ Важный момент про архитектуру +## Архитектура -Узлы `pve`, `kybinka` и `pve1` — независимые Proxmox-серверы. Для каждого узла требуется отдельный контейнер MCP с отдельным портом. +Узлы `pve`, `kybinka` и `pve1` — независимые Proxmox-серверы. Для каждого узла запускается отдельный MCP-контейнер с отдельным портом. --- ## Шаг 1. Создать API-токен на каждом Proxmox-узле -Токен создаётся отдельно на каждом узле. +На каждом Proxmox-сервере отдельно открой **Datacenter → Permissions → API Tokens** и создай токен. -1. Открой веб-интерфейс узла, например `https://192.168.31.2:8006`. -2. Перейди в **Datacenter → Permissions → API Tokens**. -3. Нажми **Add**: - - User: `root@pam`; - - Token ID: `openwebui-token`; - - отключи **Privilege Separation**, если используешь права пользователя напрямую. -4. Сохрани **Token ID** и **Secret**. Secret показывается только один раз. +- User: `root@pam`; +- Token ID: например `openwebui-token`; +- сохрани Secret, который показывается только один раз; +- Token ID должен точно совпадать со значением `auth.token_name` в конфигурации. -Повтори для `kybinka` и `pve1`. В конфигурацию нужно подставить секрет токена соответствующего узла. +Повтори операцию для `kybinka` и `pve1`. --- ## Шаг 2. Подготовить конфиги на TrueNAS -Файлы конфигурации должны находиться в следующих каталогах: +Файлы должны находиться здесь: ```text /mnt/ssd/apps/mcp/pve/config.json @@ -36,22 +33,18 @@ /mnt/ssd/apps/mcp/pve1/config.json ``` -Если каталоги ещё не созданы, выполни на TrueNAS через SSH или Shell: +Создай каталоги: ```bash mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1} ``` -> В каждом файле должен быть секрет API-токена именно соответствующего Proxmox-узла. Не оставляй текст `СЮДА_СЕКРЕТ_ТОКЕНА_*` в рабочем конфиге. +> Важно: `dev_mode` находится внутри блока `security`, а не в корне JSON. Именно такую структуру ожидает ProxmoxMCP-Plus. -### Конфигурация узла `pve` +### Конфигурация `pve` -Создай файл `/mnt/ssd/apps/mcp/pve/config.json`: - -```bash -cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF' +```json { - "dev_mode": true, "proxmox": { "host": "192.168.31.2", "port": 8006, @@ -60,23 +53,23 @@ cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF' "auth": { "user": "root@pam", "token_name": "openwebui-token", - "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE" + "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE" }, "logging": { "level": "INFO" + }, + "security": { + "dev_mode": true } } -EOF ``` -### Конфигурация узла `kybinka` +Сохрани этот JSON в `/mnt/ssd/apps/mcp/pve/config.json`. -Создай файл `/mnt/ssd/apps/mcp/kybinka/config.json`: +### Конфигурация `kybinka` -```bash -cat > /mnt/ssd/apps/mcp/kybinka/config.json << 'EOF' +```json { - "dev_mode": true, "proxmox": { "host": "192.168.1.10", "port": 8006, @@ -84,24 +77,24 @@ cat > /mnt/ssd/apps/mcp/kybinka/config.json << 'EOF' }, "auth": { "user": "root@pam", - "token_name": "openwebui-token", - "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_KYBINKA" + "token_name": "open-webui", + "token_value": "СЕКРЕТНЫЙ_ТОКЕН_KYBINKA" }, "logging": { "level": "INFO" + }, + "security": { + "dev_mode": true } } -EOF ``` -### Конфигурация узла `pve1` +Сохрани этот JSON в `/mnt/ssd/apps/mcp/kybinka/config.json`. -Создай файл `/mnt/ssd/apps/mcp/pve1/config.json`: +### Конфигурация `pve1` -```bash -cat > /mnt/ssd/apps/mcp/pve1/config.json << 'EOF' +```json { - "dev_mode": true, "proxmox": { "host": "192.168.31.4", "port": 8006, @@ -109,17 +102,21 @@ cat > /mnt/ssd/apps/mcp/pve1/config.json << 'EOF' }, "auth": { "user": "root@pam", - "token_name": "openwebui-token", - "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE1" + "token_name": "open-webui", + "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE1" }, "logging": { "level": "INFO" + }, + "security": { + "dev_mode": true } } -EOF ``` -Проверь корректность всех JSON-файлов до запуска контейнеров: +Сохрани этот JSON в `/mnt/ssd/apps/mcp/pve1/config.json`. + +Проверь файлы: ```bash python3 -m json.tool /mnt/ssd/apps/mcp/pve/config.json @@ -127,28 +124,25 @@ 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. Параметр `dev_mode: true` требуется текущей версией ProxmoxMCP-Plus, чтобы разрешить такое подключение с самоподписанным сертификатом. Для production лучше установить доверенный сертификат и использовать `verify_ssl: true` вместе с `dev_mode: false`. +`verify_ssl: false` используется для самоподписанных сертификатов Proxmox. В этом случае требуется `security.dev_mode: true`. Для production следует установить доверенный сертификат и использовать `verify_ssl: true`, `security.dev_mode: false`. --- ## Шаг 3. Запустить три контейнера через Dockge -В Dockge создай один Stack с именем `proxmox-mcp`. +В Dockge создай один Stack с именем `proxmox-mcp`, рабочая директория: -1. Открой Dockge. -2. Нажми **Create Stack** или **+**. -3. Укажи имя `proxmox-mcp`. -4. Укажи рабочую директорию стека: +```text +/mnt/ssd/apps/mcp +``` - `/mnt/ssd/apps/mcp` - -5. Вставь в compose-редактор: +Вставь в редактор Dockge **один** compose-файл: ```yaml services: @@ -159,7 +153,7 @@ services: ports: - "8811:8811" environment: - PROXMOX_API_KEY: ключ-для-pve-придумай-любой-длинный + PROXMOX_API_KEY: "ЗАМЕНИТЬ_КЛЮЧ_PVE" volumes: - /mnt/ssd/apps/mcp/pve/config.json:/app/proxmox-config/config.json:ro @@ -170,7 +164,7 @@ services: ports: - "8812:8811" environment: - PROXMOX_API_KEY: ключ-для-kybinka-придумай-любой-длинный + PROXMOX_API_KEY: "ЗАМЕНИТЬ_КЛЮЧ_KYBINKA" volumes: - /mnt/ssd/apps/mcp/kybinka/config.json:/app/proxmox-config/config.json:ro @@ -181,62 +175,81 @@ services: ports: - "8813:8811" environment: - PROXMOX_API_KEY: ключ-для-pve1-придумай-любой-длинный + PROXMOX_API_KEY: "ЗАМЕНИТЬ_КЛЮЧ_PVE1" volumes: - /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro ``` -6. Замени значения `ключ-для-*` на свои ключи. -7. Нажми **Save**, затем **Deploy** / **Up** / **Start**. +Не добавляй несколько блоков `services:` подряд. `networks: {}` не требуется — Compose создаст сеть автоматически. -В результате должны запуститься контейнеры `proxmox-mcp-pve`, `proxmox-mcp-kybinka` и `proxmox-mcp-pve1` на портах `8811`, `8812` и `8813` соответственно. +Замени `ЗАМЕНИТЬ_КЛЮЧ_*` на отдельные ключи для OpenAPI-доступа, нажми **Save**, затем **Down** и **Deploy/Up**. После изменения JSON-файлов контейнеры нужно перезапустить или пересоздать. --- -## Шаг 4. Проверить, что контейнеры работают +## Шаг 4. Проверить контейнеры ```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 +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: ```bash -curl -H "Authorization: Bearer ключ-для-pve" http://192.168.31.100:8811/health +curl -H "Authorization: Bearer ЗАМЕНИТЬ_КЛЮЧ_PVE" \ + http://192.168.31.100:8811/health ``` --- ## Шаг 5. Подключить к Open WebUI -В Open WebUI добавь три OpenAPI Tool Server: +Добавь три OpenAPI Tool Server: - `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`. -Для каждого сервера укажи свой Bearer-ключ из `PROXMOX_API_KEY` в compose-конфигурации Dockge. +Для каждого сервера укажи соответствующий Bearer-ключ из `PROXMOX_API_KEY`. --- -## Частые проблемы +## Диагностика -| Симптом | Причина | -| --- | --- | -| `logging Field required` | В контейнер попал старый `config.json` без блока `logging` или подключён неправильный файл через volume | -| `Insecure TLS configuration blocked` | В конфигурации отсутствует `dev_mode: true` при использовании `verify_ssl: false` | -| `McpError: Connection closed` | MCP-сервер завершился из-за ошибки конфигурации; исправь первичную ошибку выше по логу | -| Контейнер падает при старте | Невалидный JSON или неверный путь к `config.json` | -| `401 Unauthorized` | Bearer-ключ не совпадает с `PROXMOX_API_KEY` | -| Инструмент не появляется в Open WebUI | Проверь URL `/openapi.json` и доступность соответствующего порта | -| Модель не видит VM | Проверь права API-токена Proxmox и логи контейнера в Dockge | +Если в логе появляется: -Если после изменения конфигурации остаётся ошибка `logging Field required`, останови Stack в Dockge, проверь файлы на TrueNAS и заново выполни **Deploy**. В compose должны использоваться именно эти volume-маунты: - -```yaml -- /mnt/ssd/apps/mcp/pve/config.json:/app/proxmox-config/config.json:ro -- /mnt/ssd/apps/mcp/kybinka/config.json:/app/proxmox-config/config.json:ro -- /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro +```text +Insecure TLS configuration blocked ``` + +проверь, что внутри контейнера присутствует именно такая структура: + +```json +"security": { + "dev_mode": true +} +``` + +Проверка маунта: + +```bash +docker inspect proxmox-mcp-pve \ + --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}' +``` + +Ожидаемый результат: + +```text +/mnt/ssd/apps/mcp/pve/config.json -> /app/proxmox-config/config.json +``` + +Проверка файла внутри контейнера: + +```bash +docker exec proxmox-mcp-pve cat /app/proxmox-config/config.json +``` + +`McpError: Connection closed` является вторичной ошибкой: MCP OpenAPI Proxy закрывается после ошибки валидации конфигурации. + +> Никогда не публикуй в чат или репозиторий реальные значения `PROXMOX_API_KEY` и `auth.token_value`. Если ключи уже были опубликованы, их следует заменить.