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

Откат неподтверждённых изменений

Browse Source
This commit is contained in:
host
2026-08-08 20:12:28 +03:00
parent 8db2fcf16b
commit 3da54c6e2a
1 changed files with 0 additions and 289 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEPLOYMENT.md
-289
View File
@@ -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-хранилища.