From 80a9eab258ff460a196cdd241905367a72e29e32 Mon Sep 17 00:00:00 2001 From: host Date: Sat, 8 Aug 2026 19:58:49 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D0=BF=D0=BE=D0=B4=D1=80=D0=BE=D0=B1=D0=BD=D0=B0?= =?UTF-8?q?=D1=8F=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=86=D0=B8?= =?UTF-8?q?=D1=8F=20=D0=B2=D0=BD=D0=B5=D0=B4=D1=80=D0=B5=D0=BD=D0=B8=D1=8F?= =?UTF-8?q?=20=D0=B8=20=D1=8D=D0=BA=D1=81=D0=BF=D0=BB=D1=83=D0=B0=D1=82?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEPLOYMENT.md | 289 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 DEPLOYMENT.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..1251b29 --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,289 @@ +# Развёртывание 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. + +Проверьте версии: + +```bash +docker --version +docker compose version +``` + +Перейдите в каталог, где находятся `compose.yaml` и `.env`: + +```bash +cd /mnt/ssd/apps/mcp +``` + +## 2. Подготовка конфигурационных каталогов + +```bash +mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas} +``` + +Каждый Proxmox MCP получает собственный `config.json`. Пример для `pve`: + +```json +{ + "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`. + +Права доступа к конфигурациям: + +```bash +chmod 700 /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas} +chmod 600 /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}/config.json +``` + +Проверьте JSON до запуска: + +```bash +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. Подготовка переменных окружения + +Скопируйте шаблон: + +```bash +cp .env.example .env +chmod 600 .env +``` + +Сгенерируйте отдельные Bearer-ключи для OpenAPI: + +```bash +openssl rand -hex 32 +``` + +Внесите разные значения в: + +```dotenv +PROXMOX_PVE_API_KEY=... +PROXMOX_KYBINKA_API_KEY=... +PROXMOX_PVE1_API_KEY=... +TRUENAS_API_KEY=... +``` + +Не добавляйте `.env` в Git. Файл уже включён в `.gitignore`. + +### Адрес публикации портов + +В `.env`: + +```dotenv +MCP_BIND_ADDRESS=192.168.31.100 +``` + +Это позволяет Open WebUI обращаться к сервисам по LAN-адресу. Если Open WebUI и MCP доступны только локально, используйте `127.0.0.1`. При публикации на LAN-адрес ограничьте входящие соединения firewall-правилом только для хоста Open WebUI. + +## 4. Проверка Compose-файла + +До запуска выполните: + +```bash +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 и запустите весь стек: + +```bash +docker compose --env-file .env up -d --build +``` + +Проверьте состояние: + +```bash +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: + +```bash +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 -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-ключа: + +```bash +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. Обновление + +Перед обновлением сохраните текущую конфигурацию: + +```bash +cp .env .env.backup.$(date +%Y%m%d-%H%M%S) +docker compose config > compose.rendered.backup.yaml +``` + +Обновите образы и пересоберите TrueNAS MCP: + +```bash +docker compose pull +docker compose up -d --build +``` + +Проверьте состояние после обновления: + +```bash +docker compose ps +docker compose logs --since=10m +``` + +В production рекомендуется заменить `:latest` в `compose.yaml` на конкретный tag или digest образа. + +## 9. Откат + +Если новая версия работает некорректно: + +```bash +docker compose down +docker compose up -d +``` + +Для полноценного отката необходимо вернуть предыдущую версию image в `compose.yaml`, затем выполнить: + +```bash +docker compose pull +docker compose up -d --build +``` + +## 10. Диагностика + +### `Invalid API key` + +Проверьте, что Bearer-ключ Open WebUI точно совпадает с переменной соответствующего сервиса: + +```bash +docker compose config | grep -E 'PROXMOX_API_KEY|TRUENAS_API_KEY' +``` + +Не вставляйте вывод этой команды в публичный чат или issue. + +### `Connection closed` + +Проверьте первичную ошибку в логах: + +```bash +docker compose logs --tail=200 proxmox-mcp-pve +``` + +Затем проверьте: + +- доступность Proxmox API с Docker-хоста; +- правильность `host`, `port`, `token_name` и `token_value`; +- существование смонтированного `config.json`; +- соответствие версии OpenAPI-интерфейса и конфигурации Open WebUI. + +### Ошибка bind на порт + +Проверьте занятые порты: + +```bash +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-хранилища.