host/proxmox-mcp-setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
host
2026-08-05 20:11:43 +03:00
parent 0a9e3c9193
commit 165b0f8f52
1 changed files with 94 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
proxmox-mcp-open-webui-setup.md
+93 -80
View File
@@ -1,34 +1,31 @@
# Установка Proxmox MCP-сервера и подключение к Open WebUI # Установка 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-узле ## Шаг 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`; - User: `root@pam`;
- Token ID: `openwebui-token`; - Token ID: например `openwebui-token`;
- отключи **Privilege Separation**, если используешь права пользователя напрямую. - сохрани Secret, который показывается только один раз;
4. Сохрани **Token ID** и **Secret**. Secret показывается только один раз. - Token ID должен точно совпадать со значением `auth.token_name` в конфигурации.
Повтори для `kybinka` и `pve1`. В конфигурацию нужно подставить секрет токена соответствующего узла. Повтори операцию для `kybinka` и `pve1`.
--- ---
## Шаг 2. Подготовить конфиги на TrueNAS ## Шаг 2. Подготовить конфиги на TrueNAS
Файлы конфигурации должны находиться в следующих каталогах: Файлы должны находиться здесь:
```text ```text
/mnt/ssd/apps/mcp/pve/config.json /mnt/ssd/apps/mcp/pve/config.json
@@ -36,22 +33,18 @@
/mnt/ssd/apps/mcp/pve1/config.json /mnt/ssd/apps/mcp/pve1/config.json
``` ```
Если каталоги ещё не созданы, выполни на TrueNAS через SSH или Shell: Создай каталоги:
```bash ```bash
mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1} 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`: ```json
```bash
cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF'
{ {
"dev_mode": true,
"proxmox": { "proxmox": {
"host": "192.168.31.2", "host": "192.168.31.2",
"port": 8006, "port": 8006,
@@ -60,23 +53,23 @@ cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF'
"auth": { "auth": {
"user": "root@pam", "user": "root@pam",
"token_name": "openwebui-token", "token_name": "openwebui-token",
"token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE" "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE"
}, },
"logging": { "logging": {
"level": "INFO" "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 ```json
cat > /mnt/ssd/apps/mcp/kybinka/config.json << 'EOF'
{ {
"dev_mode": true,
"proxmox": { "proxmox": {
"host": "192.168.1.10", "host": "192.168.1.10",
"port": 8006, "port": 8006,
@@ -84,24 +77,24 @@ cat > /mnt/ssd/apps/mcp/kybinka/config.json << 'EOF'
}, },
"auth": { "auth": {
"user": "root@pam", "user": "root@pam",
"token_name": "openwebui-token", "token_name": "open-webui",
"token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_KYBINKA" "token_value": "СЕКРЕТНЫЙ_ТОКЕН_KYBINKA"
}, },
"logging": { "logging": {
"level": "INFO" "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 ```json
cat > /mnt/ssd/apps/mcp/pve1/config.json << 'EOF'
{ {
"dev_mode": true,
"proxmox": { "proxmox": {
"host": "192.168.31.4", "host": "192.168.31.4",
"port": 8006, "port": 8006,
@@ -109,17 +102,21 @@ cat > /mnt/ssd/apps/mcp/pve1/config.json << 'EOF'
}, },
"auth": { "auth": {
"user": "root@pam", "user": "root@pam",
"token_name": "openwebui-token", "token_name": "open-webui",
"token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE1" "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE1"
}, },
"logging": { "logging": {
"level": "INFO" "level": "INFO"
},
"security": {
"dev_mode": true
} }
} }
EOF
``` ```
Проверь корректность всех JSON-файлов до запуска контейнеров: Сохрани этот JSON в `/mnt/ssd/apps/mcp/pve1/config.json`.
Проверь файлы:
```bash ```bash
python3 -m json.tool /mnt/ssd/apps/mcp/pve/config.json 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 python3 -m json.tool /mnt/ssd/apps/mcp/pve1/config.json
``` ```
Если ошибок нет, команды выведут отформатированное содержимое JSON. При необходимости ограничь права доступа к файлам с токенами: Ограничь доступ к файлам с токенами:
```bash ```bash
chmod 600 /mnt/ssd/apps/mcp/{pve,kybinka,pve1}/config.json 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 ## Шаг 3. Запустить три контейнера через Dockge
В Dockge создай один Stack с именем `proxmox-mcp`. В Dockge создай один Stack с именем `proxmox-mcp`, рабочая директория:
1. Открой Dockge. ```text
2. Нажми **Create Stack** или **+**. /mnt/ssd/apps/mcp
3. Укажи имя `proxmox-mcp`. ```
4. Укажи рабочую директорию стека:
`/mnt/ssd/apps/mcp` Вставь в редактор Dockge **один** compose-файл:
5. Вставь в compose-редактор:
```yaml ```yaml
services: services:
@@ -159,7 +153,7 @@ services:
ports: ports:
- "8811:8811" - "8811:8811"
environment: environment:
PROXMOX_API_KEY: ключ-для-pve-придумай-любой-длинный PROXMOX_API_KEY: "ЗАМЕНИТЬ_КЛЮЧ_PVE"
volumes: volumes:
- /mnt/ssd/apps/mcp/pve/config.json:/app/proxmox-config/config.json:ro - /mnt/ssd/apps/mcp/pve/config.json:/app/proxmox-config/config.json:ro
@@ -170,7 +164,7 @@ services:
ports: ports:
- "8812:8811" - "8812:8811"
environment: environment:
PROXMOX_API_KEY: ключ-для-kybinka-придумай-любой-длинный PROXMOX_API_KEY: "ЗАМЕНИТЬ_КЛЮЧ_KYBINKA"
volumes: volumes:
- /mnt/ssd/apps/mcp/kybinka/config.json:/app/proxmox-config/config.json:ro - /mnt/ssd/apps/mcp/kybinka/config.json:/app/proxmox-config/config.json:ro
@@ -181,62 +175,81 @@ services:
ports: ports:
- "8813:8811" - "8813:8811"
environment: environment:
PROXMOX_API_KEY: ключ-для-pve1-придумай-любой-длинный PROXMOX_API_KEY: "ЗАМЕНИТЬ_КЛЮЧ_PVE1"
volumes: volumes:
- /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro - /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro
``` ```
6. Замени значения `ключ-для-*` на свои ключи. Не добавляй несколько блоков `services:` подряд. `networks: {}` не требуется — Compose создаст сеть автоматически.
7. Нажми **Save**, затем **Deploy** / **Up** / **Start**.
В результате должны запуститься контейнеры `proxmox-mcp-pve`, `proxmox-mcp-kybinka` и `proxmox-mcp-pve1` на портах `8811`, `8812` и `8813` соответственно. Замени `ЗАМЕНИТЬ_КЛЮЧ_*` на отдельные ключи для OpenAPI-доступа, нажми **Save**, затем **Down** и **Deploy/Up**. После изменения JSON-файлов контейнеры нужно перезапустить или пересоздать.
--- ---
## Шаг 4. Проверить, что контейнеры работают ## Шаг 4. Проверить контейнеры
```bash ```bash
curl -f http://192.168.31.100:8811/livez # pve curl -f http://192.168.31.100:8811/livez
curl -f http://192.168.31.100:8812/livez # kybinka curl -f http://192.168.31.100:8812/livez
curl -f http://192.168.31.100:8813/livez # pve1 curl -f http://192.168.31.100:8813/livez
``` ```
Авторизованный запрос: Проверка авторизации OpenAPI:
```bash ```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 ## Шаг 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:8811/openapi.json` — `Proxmox pve`;
- `http://192.168.31.100:8812/openapi.json` — `Proxmox kybinka`; - `http://192.168.31.100:8812/openapi.json` — `Proxmox kybinka`;
- `http://192.168.31.100:8813/openapi.json` — `Proxmox pve1`. - `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-маунты: ```text
Insecure TLS configuration blocked
```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
``` ```
проверь, что внутри контейнера присутствует именно такая структура:
```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`. Если ключи уже были опубликованы, их следует заменить.