290 lines
9.6 KiB
Markdown
290 lines
9.6 KiB
Markdown
# Развёртывание 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-хранилища.
|