iiEsaywebUI/README.md

# iiEasy AI-платформа

Корпоративная AI-платформа на базе Open WebUI с интеграцией Ollama, Qdrant, SearXNG и синхронизацией Nextcloud.

## Архитектура

```
┌─────────────────────────────────────────────────────────────┐
│                    Reverse Proxy (Nginx)                     │
│              *.iieasy.ru (odo.iieasy.ru)                     │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌───────▼────────┐  ┌───────▼────────┐
│  Open WebUI    │  │   Authentik     │  │   Nextcloud    │
│  odo.iieasy.ru │  │ auth.iieasy.ru  │  │next.iieasy.ru  │
└───────┬────────┘  └─────────────────┘  └───────┬────────┘
        │                                         │
        │  ┌──────────────────────────────────────┘
        │  │
        ▼  ▼
┌─────────────────────────────────────────────────────────────┐
│              Docker Network (iieasy-ai)                     │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                │
│  │  Ollama  │  │  Qdrant  │  │ SearXNG  │                │
│  │ (GPU)    │  │ (Vector) │  │ (Search) │                │
│  └──────────┘  └──────────┘  └──────────┘                │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │ Python Worker │
                    │ (Nextcloud →  │
                    │  Qdrant Sync) │
                    └───────────────┘
```

## Компоненты

- **Open WebUI** - Веб-интерфейс для работы с AI моделями
- **Ollama** - Локальный запуск LLM моделей (Gemma 3)
- **Qdrant** - Векторная база данных для RAG
- **SearXNG** - Метапоисковая система для веб-поиска
- **Authentik** - Централизованный SSO (OIDC)
- **Nextcloud Sync Worker** - Автоматическая синхронизация документов из Nextcloud

## Быстрый старт

### Предварительные требования

- Docker и Docker Compose
- NVIDIA GPU с драйверами (для Ollama)
- Reverse proxy (Nginx) настроенный для доменов *.iieasy.ru
- Authentik настроенный и доступный на auth.iieasy.ru

### 1. Клонирование и настройка

```bash
cd /home/its/iiEasyWeb
cp .env.example .env
# Отредактируйте .env и заполните все необходимые переменные
```

### 2. Генерация API ключей

```bash
# Генерация QDRANT_API_KEY
openssl rand -hex 32
# Добавьте результат в .env
```

### 3. Запуск инфраструктуры

```bash
# Запуск всех сервисов
docker-compose up -d

# Проверка статуса
docker-compose ps

# Просмотр логов
docker-compose logs -f
```

### 4. Загрузка модели Ollama

```bash
# Загрузка модели Gemma 3
docker exec ollama ollama pull gemma3n:e4b-it-fp16

# Проверка загруженных моделей
docker exec ollama ollama list
```

### 5. Настройка Authentik

1. Войдите в Authentik (https://auth.iieasy.ru)
2. Создайте OIDC Provider:
   - Redirect URI: `https://odo.iieasy.ru/oauth/oidc/callback`
   - Client ID и Client Secret скопируйте в `.env`
3. Обновите `OPENID_CONNECT_ISSUER` в `.env`

### 6. Ребрендинг Open WebUI

После первого запуска Open WebUI выполните:

```bash
./scripts/rebrand.sh
```

Скрипт заменит:
- Логотипы и favicon
- Текстовые упоминания "Open WebUI" → "iiEasyWeb"
- Отключит проверку обновлений
- Удалит аналитику и телеметрию

### 7. Настройка API ключа Open WebUI

1. Откройте https://odo.iieasy.ru
2. Войдите через Authentik SSO
3. Перейдите в Settings → Account → API Keys
4. Создайте новый API ключ
5. Добавьте ключ в `.env` как `OPENWEBUI_API_KEY`

### 8. Запуск воркера синхронизации Nextcloud

```bash
cd worker

# Установка зависимостей
pip install -r requirements.txt

# Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env

# Запуск однократной синхронизации
python nextcloud_sync.py --once

# Или запуск в режиме daemon
python nextcloud_sync.py --daemon
```

Для production рекомендуется использовать systemd:

```bash
# Создайте /etc/systemd/system/iieasy-sync.service
sudo nano /etc/systemd/system/iieasy-sync.service
```

```ini
[Unit]
Description=iiEasy Nextcloud Sync Worker
After=network.target

[Service]
Type=simple
User=its
WorkingDirectory=/home/its/iiEasyWeb/worker
ExecStart=/usr/bin/python3 /home/its/iiEasyWeb/worker/nextcloud_sync.py --daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable iieasy-sync
sudo systemctl start iieasy-sync
```

## Переменные окружения

### Основной .env

См. `.env.example` для полного списка переменных. Основные:

- `DOMAIN_OPENWEBUI` - URL Open WebUI
- `DOMAIN_NEXTCLOUD` - URL Nextcloud
- `DOMAIN_AUTHENTIK` - URL Authentik
- `OAUTH_CLIENT_ID` - Client ID из Authentik
- `OAUTH_CLIENT_SECRET` - Client Secret из Authentik
- `OPENID_CONNECT_ISSUER` - Issuer URL Authentik
- `QDRANT_API_KEY` - API ключ Qdrant (сгенерировать)
- `OPENWEBUI_API_KEY` - API ключ Open WebUI (создать после первого запуска)

### worker/.env

- `NC_USER` - Пользователь Nextcloud
- `NC_APP_PASSWORD` - App Password (не основной пароль!)
- `NC_SCAN_PATHS` - Пути для сканирования
- `OPENWEBUI_API_KEY` - API ключ Open WebUI

## Структура проекта

```
iiEasyWeb/
├── docker-compose.yml          # Основной compose файл
├── .env                         # Переменные окружения
├── .env.example                 # Шаблон переменных
├── .gitignore                   # Игнорируемые файлы
│
├── scripts/
│   └── rebrand_safe_final.sh   # ✅ Рекомендуемый скрипт ребрендинга (безопасный)
│   ├── rebrand.sh              # ⚠️ Старый скрипт (может ломать OAuth)
│   └── rebrand_fast.sh         # ⚠️ Быстрый скрипт (может ломать функциональность)
│
├── media/
│   ├── logo-light.svg          # Логотип светлая тема
│   ├── logo-dark.svg           # Логотип темная тема
│   └── favicon.svg             # Favicon
│
├── worker/
│   ├── nextcloud_sync.py       # Главный скрипт воркера
│   ├── config.py               # Конфигурация
│   ├── nextcloud_client.py     # WebDAV клиент
│   ├── openwebui_client.py     # Open WebUI API клиент
│   ├── document_processor.py   # Обработка документов
│   ├── requirements.txt        # Python зависимости
│   └── .env.example            # Шаблон для воркера
│
└── README.md                    # Эта документация
```

## Сетевая архитектура

Все сервисы работают в Docker сети `iieasy-ai` и доступны только внутри сети, кроме Open WebUI, который доступен через reverse proxy.

### Порты

- **Open WebUI**: 3001 (внутренний) → Nginx → 443 (HTTPS)
- **Qdrant**: 6333 (gRPC), 6334 (HTTP) - только внутри сети
- **SearXNG**: 8080 - только внутри сети
- **Ollama**: 11434 - только внутри сети

### Безопасность

- Все сервисы изолированы в Docker сети
- Доступ к Qdrant только через API ключ
- Open WebUI использует Authentik SSO для аутентификации
- Воркер использует App Password для Nextcloud (не основной пароль)
- CrowdSec и OPNsense фильтруют трафик на уровне reverse proxy

## Поддерживаемые форматы файлов

Воркер синхронизации поддерживает:

- **PDF** (.pdf) - извлечение текста через pypdf
- **DOCX** (.docx, .doc) - извлечение текста через python-docx
- **Текстовые** (.txt, .md, .markdown) - прямое чтение
- **CSV** (.csv) - конвертация в текстовый формат

Файлы больше 100MB обрабатываются потоково с ограничением количества страниц.

## Устранение неполадок

### Open WebUI не подключается к Qdrant

1. Проверьте, что Qdrant запущен: `docker-compose ps qdrant`
2. Проверьте логи: `docker-compose logs qdrant`
3. Убедитесь, что `QDRANT_API_KEY` установлен в `.env`
4. Проверьте переменную `QDRANT_URI=http://qdrant:6333`

### Ошибки аутентификации через Authentik

1. Проверьте redirect URI в Authentik: `https://odo.iieasy.ru/oauth/oidc/callback`
2. Убедитесь, что `OPENID_CONNECT_ISSUER` правильный
3. Проверьте логи Open WebUI: `docker-compose logs open-webui`

### Воркер не синхронизирует файлы

1. Проверьте логи: `tail -f worker/sync.log`
2. Убедитесь, что `OPENWEBUI_API_KEY` правильный
3. Проверьте доступность Nextcloud: `curl https://next.iieasy.ru`
4. Проверьте права доступа к путям в `NC_SCAN_PATHS`

### Ollama не использует GPU

1. Проверьте драйверы NVIDIA: `nvidia-smi`
2. Установите nvidia-container-toolkit
3. Перезапустите Docker: `sudo systemctl restart docker`
4. Проверьте переменную `NVIDIA_VISIBLE_DEVICES` в `.env`

## Лицензия

Внутренний проект iiEasy Research Center.

## Поддержка

Для вопросов и проблем обращайтесь к команде разработки iiEasy.