diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md deleted file mode 100644 index 1251b29..0000000 --- a/DEPLOYMENT.md +++ /dev/null @@ -1,289 +0,0 @@ -# Развёртывание 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-хранилища.