Исправил расположение dev_mode в конфигурации Proxmox MCP

2026-08-05 20:11:43 +03:00
parent 0a9e3c9193
commit 165b0f8f52
1 changed files with 94 additions and 81 deletions
@@ -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 показывается только один раз.
+- 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`. Если ключи уже были опубликованы, их следует заменить.