tg-sd/README.md

# Telegram Bot для генерации изображений через Stable Diffusion (Automatic1111)

Бот для генерации изображений через API Stable Diffusion WebUI (Automatic1111) с поддержкой профилей, управления хранением изображений и удобным интерфейсом.

## Возможности

- 🎨 **Генерация изображений (txt2img)** — создание изображений по текстовому описанию
- ⚙️ **Система профилей** — сохранение настроек (размер, модель, LoRA, сэмплер и т.д.)
- 🗃️ **Управление хранением** — настройка времени хранения изображений (автоочистка)
- 📊 **Мониторинг** — проверка статуса подключения к SD API
- 🐳 **Docker** — простая установка и запуск в контейнере
- 🛡️ **Админ-панель** — управление пользователями, лимитами и доступом

---

## Содержание

1. [Что умеет бот](#что-умеет-бот)
2. [Требования](#требования)
3. [Настройка Stable Diffusion WebUI](#настройка-stable-diffusion-webui)
4. [Создание Telegram бота](#создание-telegram-бота)
5. [Установка бота](#установка-бота)
6. [Настройка конфигурации](#настройка-конфигурации)
7. [Запуск бота](#запуск-бота)
8. [Использование бота](#использование-бота)
9. [Примеры промптов](#примеры-промптов)
10. [Структура проекта](#структура-проекта)
11. [FAQ](#faq)
12. [Устранение неполадок](#устранение-неполадок)

---

## Что умеет бот

### 🎨 Генерация изображений

Бот позволяет создавать изображения двумя способами:

**txt2img (текст → изображение)** — опишите словами, что хотите увидеть, и бот сгенерирует изображение. Вы вводите промпт (описание) и необязательный негативный промпт (чего НЕ должно быть на картинке), а бот передаёт запрос в Stable Diffusion и возвращает готовое изображение.

После генерации бот покажет все параметры: промпт, размер, количество шагов, CFG Scale, сэмплер, шедулер, seed, модель и время хранения изображения.

### ⚙️ Система профилей

Создавайте и сохраняйте профили с предустановленными настройками, чтобы не вводить их каждый раз заново:

| Параметр | Описание |
|----------|----------|
| **Размер изображения** | Предустановленные (512×512, 768×768, 512×768, 768×512, 1024×1024) или произвольный (64–2048 px) |
| **Количество шагов** | От 10 до 150. Больше шагов = выше качество, но дольше генерация |
| **CFG Scale** | От 1.0 до 30.0. Определяет, насколько строго модель следует промпту (стандарт: 7.0) |
| **Сэмплер** | Euler a, Euler, DPM++ 2M Karras, DPM++ SDE Karras, DDIM и другие — загружаются из SD API |
| **Шедулер** | Автоматически подбирается к сэмплеру |
| **Модель** | Выбор из всех доступных моделей в вашем SD WebUI |
| **LoRA** | Подключение LoRA с настраиваемой силой (0.0–1.0) |
| **Негативный промпт** | Описание того, чего НЕ должно быть на изображении |

Вы можете установить один профиль как **профиль по умолчанию** (⭐) — тогда при генерации будут автоматически применяться его настройки.

### 🛡️ Админ-панель

Администратор (указанный в `ADMIN_ID`) имеет доступ к панели управления:

- **Добавление пользователей** — выдача доступа по Telegram User ID
- **Типы доступа:**
  - ♾️ **Без ограничений** — полный доступ навсегда
  - ⏰ **По времени** — доступ на заданное количество дней (1–3650)
  - 🎨 **По количеству генераций** — лимит на число сгенерированных изображений
- **Список пользователей** — просмотр, пагинация, управление
- **Управление пользователями** — блокировка, разблокировка, обновление доступа, удаление
- **Очистка истёкших доступов** — автоматическая деактивация пользователей с истёкшим сроком

> **Как узнать свой User ID?** — Напишите боту [@userinfobot](https://t.me/userinfobot) в Telegram.

### 🗃️ Управление хранением

Каждый пользователь может настроить время хранения своих сгенерированных изображений:

- **Предустановленные варианты:** 12 ч, 24 ч (1 день), 48 ч (2 дня), 72 ч (3 дня), 168 ч (7 дней)
- **Произвольное значение** — от 1 часа до максимума (`MAX_IMAGE_TTL_HOURS`)
- **Автоматическая очистка** — фоновая задача удаляет просроченные изображения с заданным интервалом

### 📊 Мониторинг

Команда `/status` или кнопка «Статус SD API» покажет:

- Статус подключения к SD API
- Адрес API
- Текущую загруженную модель

### 🔐 Система доступа

Бот по умолчанию **не допускает** новых пользователей — только те, кого добавил администратор, могут пользоваться ботом. Это защищает от несанкционированного использования ваших ресурсов.

При попытке использования бота без доступа пользователь получит сообщение об ошибке.

### 📋 Команды бота

| Команда | Описание |
|---------|----------|
| `/start` | Запуск бота, приветствие и главное меню |
| `/menu` | Показать главное меню |
| `/status` | Проверка статуса SD API |
| `/cancel` | Отмена текущей операции |
| `/admin` | Админ-панель (только для администратора) |

---

## Требования

### Для сервера с ботом (Docker)

- **Операционная система:** Linux (Ubuntu 20.04+), Windows 10/11 с WSL2, macOS 12+
- **Docker:** версии 20.10+
- **Docker Compose:** версии 2.0+
- **Свободное место:** ~500 МБ для бота + место для изображений
- **Оперативная память:** минимум 256 МБ для контейнера бота
- **Сеть:** доступ к серверу Stable Diffusion по локальной сети

### Для сервера со Stable Diffusion

- **Stable Diffusion WebUI (Automatic1111)** — запущенный и доступный по сети
- **API режим** — включён флагом `--api`
- **Сетевой доступ** — слушает не только localhost (флаг `--listen`)

---

## Настройка Stable Diffusion WebUI

### 1. Запуск с поддержкой API

На сервере, где установлен Stable Diffusion WebUI, запустите его со следующими флагами:

```bash
# Для Linux
./webui.sh --api --listen

# Для Windows
webui.bat --api --listen
```

**Обязательные флаги:**

| Флаг | Описание |
|------|----------|
| `--api` | Включает программный API для бота |
| `--listen` | Позволяет подключаться не только с localhost |

**Опциональные флаги:**

| Флаг | Описание |
|------|----------|
| `--port 7860` | Указать порт (по умолчанию 7860) |
| `--nowatchdog` | Отключить watchdog (рекомендуется для серверов) |
| `--xformers` | Использовать xformers для ускорения (если поддерживается) |

**Пример полной команды:**

```bash
./webui.sh --api --listen --port 7860 --nowatchdog
```

### 2. Проверка доступности API

После запуска проверьте, что API доступен:

```bash
# С сервера с ботом (замените IP на ваш)
curl http://192.168.1.120:7860/sdapi/v1/options
```

Вы должны получить JSON-ответ с настройками API.

### 3. Настройка firewall (если необходимо)

Убедитесь, что порт 7860 открыт для подключения с сервера бота:

```bash
# Для Ubuntu/Debian (UFW)
sudo ufw allow 7860/tcp

# Для CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=7860/tcp
sudo firewall-cmd --reload
```

---

## Создание Telegram бота

### 1. Получение токена бота

1. Откройте Telegram и найдите бота **@BotFather**
2. Отправьте команду `/newbot`
3. Следуйте инструкциям:
   - Введите **отображаемое имя** бота (например, `SD Generator`)
   - Введите **username** бота (должен заканчиваться на `bot`, например `sd_gen_bot`)
4. BotFather отправит вам **токен** вида `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`

### 2. Настройка описания бота (опционально)

В BotFather:

```
/setdescription — описание, которое видит пользователь до начала общения
/setabouttext — короткое описание для поиска ботов
/setuserpic — аватар бота
```

---

## Установка бота

### Способ 1: С помощью Docker Compose (рекомендуется)

#### 1. Клонирование или копирование файлов

Скопируйте все файлы проекта на сервер, где будет работать бот:

```
tg-sd/
├── main.py
├── config.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env
├── bot/
│   ├── __init__.py
│   ├── handlers_start.py
│   ├── handlers_generation.py
│   ├── handlers_profiles.py
│   └── handlers_settings.py
├── sd/
│   ├── __init__.py
│   └── sd_client.py
├── database/
│   ├── __init__.py
│   └── database.py
└── utils/
    ├── __init__.py
    └── image_manager.py
```

#### 2. Настройка переменных окружения

Откройте файл `.env` и укажите ваши значения:

```bash
nano .env
```

**Обязательные параметры:**

```env
# Токен вашего бота (получите у @BotFather)
BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

# Адрес Stable Diffusion API
SD_API_URL=http://192.168.1.120:7860
```

**Опциональные параметры:**

```env
# Время хранения изображений по умолчанию (часы)
DEFAULT_IMAGE_TTL_HOURS=48

# Максимальное время хранения (часы)
MAX_IMAGE_TTL_HOURS=168

# Период автоматической очистки (минуты)
CLEANUP_INTERVAL_MINUTES=30
```

#### 3. Создание необходимых директорий

```bash
mkdir -p images data
```

#### 4. Запуск бота

```bash
# Сборка и запуск
docker compose up -d --build

# Проверка логов
docker compose logs -f tg-sd-bot
```

#### 5. Остановка бота

```bash
# Остановка
docker compose down

# Остановка с удалением контейнера и volumes
docker compose down -v
```

### Способ 2: Без Docker (прямой запуск)

#### 1. Установка Python

Убедитесь, что установлен Python 3.10+:

```bash
python3 --version
```

#### 2. Создание виртуального окружения

```bash
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# или
venv\Scripts\activate  # Windows
```

#### 3. Установка зависимостей

```bash
pip install -r requirements.txt
```

#### 4. Настройка окружения

```bash
cp .env.example .env
nano .env  # Укажите ваши значения
```

#### 5. Запуск бота

```bash
python main.py
```

---

## Настройка конфигурации

### Файл .env

| Параметр | Описание | По умолчанию | Обязательно |
|----------|----------|--------------|-------------|
| `BOT_TOKEN` | Токен Telegram бота | — | ✅ Да |
| `SD_API_URL` | URL Stable Diffusion API | `http://192.168.1.120:7860` | ✅ Да |
| `IMAGES_DIR` | Путь к папке изображений | `/app/images` | Нет |
| `DEFAULT_IMAGE_TTL_HOURS` | Время хранения по умолчанию | `48` | Нет |
| `MAX_IMAGE_TTL_HOURS` | Максимальное время хранения | `168` | Нет |
| `CLEANUP_INTERVAL_MINUTES` | Интервал очистки | `30` | Нет |
| `DB_PATH` | Путь к базе данных | `/app/data/bot.db` | Нет |

---

## Запуск бота

### Docker Compose

```bash
# Запуск
docker compose up -d

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

# Перезапуск
docker compose restart

# Остановка
docker compose down

# Обновление (после изменений в коде)
docker compose up -d --build
```

### Прямой запуск

```bash
# Активация окружения
source venv/bin/activate

# Запуск
python main.py

# Остановка: Ctrl+C
```

### Запуск как сервис (systemd, Linux)

Создайте файл сервиса:

```bash
sudo nano /etc/systemd/system/tg-sd-bot.service
```

Содержимое:

```ini
[Unit]
Description=Telegram SD Bot
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/tg-sd
ExecStart=/path/to/tg-sd/venv/bin/python main.py
Restart=always
RestartSec=10

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

Активация:

```bash
sudo systemctl daemon-reload
sudo systemctl enable tg-sd-bot
sudo systemctl start tg-sd-bot

# Проверка статуса
sudo systemctl status tg-sd-bot

# Просмотр логов
sudo journalctl -u tg-sd-bot -f
```

---

## Использование бота

### Команды

| Команда | Описание |
|---------|----------|
| `/start` | Запуск бота, главное меню |
| `/menu` | Показать главное меню |
| `/status` | Проверка статуса SD API |
| `/cancel` | Отмена текущей операции |

### Генерация изображения (txt2img)

1. Нажмите **"🎨 Генерация (txt2img)"**
2. Введите описание изображения (промпт)
3. Введите негативный промпт (или `-` для пропуска)
4. Дождитесь результата

**Пример промпта:**

```
a beautiful sunset over mountains, golden hour, dramatic clouds, 4k, highly detailed
```

**Пример негативного промпта:**

```
blurry, low quality, watermark, text, deformed
```

### Генерация на основе изображения (img2img)

1. Нажмите **"🖼️ Генерация (img2img)"**
2. Отправьте изображение
3. Введите промпт
4. Выберите силу изменений

### Управление профилями

1. Нажмите **"⚙️ Профили"**
2. Создайте новый профиль
3. Настройте параметры:
   - Размер изображения (512x512, 768x768, и т.д.)
   - Количество шагов
   - CFG Scale
   - Сэмплер
   - Модель
   - LoRA и его сила
   - Негативный промпт
4. Установите профиль по умолчанию (⭐)

### Настройки хранения

1. Нажмите **"🗑️ Настройки хранения"**
2. Выберите время хранения:
   - 12 часов
   - 24 часа (1 день)
   - 48 часов (2 дня)
   - 72 часа (3 дня)
   - 168 часов (7 дней)
   - Пользовательское значение

---

## Примеры промптов

### 📸 Фотореализм и портреты

```
professional portrait photograph of a young woman, natural lighting, soft focus, shallow depth of field, 85mm lens, film grain, highly detailed skin texture
```

```
elderly fisherman on a wooden boat at dawn, misty lake, warm golden light, cinematic composition, photorealistic, 4k
```

**Негативный промпт:**
```
blurry, low quality, watermark, text, deformed, extra fingers, bad anatomy, cartoon, illustration
```

### 🌄 Пейзажи и природа

```
majestic mountain range at sunset, snow-capped peaks, golden hour lighting, dramatic clouds reflected in a crystal clear alpine lake, wide angle, national geographic style
```

```
enchanted forest with bioluminescent mushrooms, fireflies, moonlight filtering through ancient trees, magical atmosphere, fantasy landscape, highly detailed
```

**Негативный промпт:**
```
urban, buildings, people, watermark, text, blurry, oversaturated
```

### 🏙️ Архитектура и города

```
futuristic cyberpunk city at night, neon lights, flying cars, towering skyscrapers with holographic advertisements, rain-soaked streets, cinematic lighting, blade runner style
```

```
ancient Greek temple ruins at sunrise, marble columns, overgrown with vines, peaceful atmosphere, warm morning light, archaeological photography style
```

**Негативный промпт:**
```
modern cars, people, watermark, text, low quality, distorted perspective
```

### 🐉 Фэнтези и фантастика

```
epic dragon perched on a volcanic cliff, iridescent scales, wings spread wide, stormy sky with lightning bolts, fantasy art, highly detailed, dramatic lighting, artstation trending
```

```
astronaut floating in a nebula, surrounded by cosmic dust and stars, surreal space scene, vivid colors, cinematic composition, digital art
```

**Негативный промпт:**
```
realistic, photograph, blurry, low resolution, watermark, text, bad anatomy
```

### 🎨 Художественные стили

```
oil painting of a Japanese garden in autumn, red maple trees, stone lantern, koi pond, impressionist style, visible brushstrokes, Monet inspired
```

```
watercolor illustration of a cozy cafe on a rainy day, warm interior light visible through windows, soft pastel colors, lo-fi aesthetic
```

```
pixel art of a medieval castle, 16-bit style, game sprite, clean pixels, side view
```

**Негативный промпт:**
```
photorealistic, 3d render, blurry, watermark, text
```

### 🍱 Аниме стили

```
anime girl with silver hair and blue eyes, wearing a school uniform, cherry blossom petals falling, soft lighting, Makoto Shinkai style, highly detailed anime art
```

```
anime scene of a samurai standing on a bridge at sunset, dramatic pose, katana drawn, wind blowing cloak, Studio Ghibli style, beautiful background art
```

**Негативный промпт:**
```
realistic, photograph, 3d, bad anatomy, extra limbs, watermark, text, low quality
```

### 🍔 Предметы и еда

```
professional food photography of a gourmet burger, melted cheese dripping, fresh ingredients, dark background, studio lighting, commercial photography style, 4k
```

```
luxury Swiss watch on a velvet cushion, macro photography, intricate details, dramatic side lighting, product photography, bokeh background
```

**Негативный промпт:**
```
amateur, blurry, watermark, text, bad lighting, distorted
```

### 💡 Советы по составлению промптов

1. **Используйте английский язык** — модели лучше понимают английские описания
2. **Будьте конкретны** — «sunset over mountains» лучше, чем просто «landscape»
3. **Добавляйте стиль** — укажите «oil painting», «photograph», «anime style» и т.д.
4. **Описывайте освещение** — «golden hour», «dramatic lighting», «soft morning light»
5. **Указывайте качество** — «4k», «highly detailed», «professional photography»
6. **Добавляйте композицию** — «close-up», «wide angle», «macro», «portrait»
7. **Используйте негативный промпт** — это убирает нежелательные элементы

### 🔗 Полезные ресурсы для промптов

- [PromptHero](https://prompthero.com/) — база промптов с примерами изображений
- [Lexica](https://lexica.art/) — поиск по Stable Diffusion изображениям и промптам
- [OpenArt](https://openart.ai/) — галерея с промптами
- [Civitai](https://civitai.com/) — модели, LoRA и примеры промптов

---

## FAQ

### Общие вопросы

#### ❓ Что нужно для работы бота?

Вам понадобятся:
1. **Telegram Bot Token** — получите у [@BotFather](https://t.me/BotFather)
2. **Запущенный Stable Diffusion WebUI (Automatic1111)** с флагами `--api --listen`
3. **Сервер** для запуска бота (Docker или Python)

Бот и SD WebUI могут работать на разных машинах — главное, чтобы бот имел сетевой доступ к SD API.

#### ❓ Можно ли использовать бота без своего GPU?

Да! Бот может работать на слабом сервере (даже на VPS с 256 МБ RAM), а Stable Diffusion — на мощной машине с GPU в вашей локальной сети. Бот лишь передаёт запросы и возвращает изображения.

#### ❓ Какие модели поддерживаются?

Любые модели, загруженные в ваш SD WebUI:
- **Stable Diffusion 1.5 / 2.1**
- **SDXL**
- **Кастомные модели** (ckpt/safetensors) — любые, которые вы загрузили

Бот автоматически подтягивает список доступных моделей из API.

#### ❓ Поддерживаются ли LoRA?

Да! При создании профиля вы можете выбрать LoRA из списка доступных и настроить его силу (0.0–1.0). Список LoRA загружается автоматически из SD WebUI.

#### ❓ Бот поддерживает ControlNet?

В текущей версии ControlNet не поддерживается. Если вам нужна эта функция — вы можете реализовать её, расширив `sd_client.py`.

---

### Генерация

#### ❓ Сколько времени занимает генерация?

Зависит от:
- **Количества шагов** — 20 шагов ≈ 5–15 секунд на GPU среднего уровня
- **Размера изображения** — 512×512 быстрее, чем 1024×1024
- **Модели** — SDXL медленнее, чем SD 1.5
- **Нагрузки на GPU** — если кто-то ещё использует GPU

Обычно генерация занимает **от 10 секунд до 2 минут**.

#### ❓ Почему генерация занимает слишком долго?

Возможные причины:
1. Слишком много шагов (попробуйте 20–30 вместо 50+)
2. Большой размер изображения (попробуйте 512×512 вместо 1024×1024)
3. Медленная модель (SDXL тяжелее, чем SD 1.5)
4. GPU загружен другими задачами

#### ❓ Что такое CFG Scale?

**CFG Scale** (Classifier-Free Guidance) определяет, насколько строго модель следует вашему промпту:
- **5.0** — модель более свободна, может добавлять свои детали
- **7.0** — стандарт, хороший баланс
- **9.0+** — модель строго следует промпту, но может стать «перегруженной»

#### ❓ Что такое сэмплер?

**Сэмплер** — алгоритм, который определяет, как модель «шаг за шагом» создаёт изображение из шума:
- **Euler a** — быстрый, хорошие результаты
- **DPM++ 2M Karras** — высокое качество, рекомендуемый
- **DPM++ SDE Karras** — ещё выше качество, но медленнее
- **DDIM** — быстрый, но менее детализированный

#### ❓ Можно ли использовать seed из предыдущей генерации?

После генерации бот показывает использованный seed. Вы можете создать профиль с конкретным seed (в текущей версии seed генерируется автоматически). Для точного воспроизведения используйте SD WebUI напрямую.

---

### Профили

#### ❓ Зачем нужны профили?

Профили сохраняют ваши любимые настройки. Вместо того чтобы каждый раз выбирать размер, модель, сэмплер и т.д., вы создаёте профиль один раз и используете его в один клик.

#### ❓ Сколько профилей можно создать?

Ограничений нет — создавайте столько, сколько нужно.

#### ❓ Что делает «профиль по умолчанию»?

Если профиль установлен как **по умолчанию** (⭐), его настройки будут автоматически применяться при генерации. Вы можете быстро генерировать, вводя только промпт.

---

### Доступ и администрирование

#### ❓ Почему бот не отвечает мне?

Бот работает в **закрытом режиме** — только пользователи, добавленные администратором, могут его использовать. Обратитесь к администратору, чтобы он добавил вас через админ-панель.

#### ❓ Как добавить пользователя?

1. Узнайте Telegram User ID пользователя (через [@userinfobot](https://t.me/userinfobot))
2. В админ-панели нажмите **«➕ Добавить пользователя»**
3. Введите User ID
4. Выберите тип доступа (без ограничений, по времени, по количеству генераций)

#### ❓ Как заблокировать пользователя?

В админ-панели: **Список пользователей** → выберите пользователя → **🚫 Заблокировать**.

#### ❓ Можно ли дать доступ всем?

В текущей версии бот работает только в закрытом режиме. Если вы хотите открыть доступ для всех, необходимо изменить код мидлвари `AccessCheckMiddleware`.

---

### Хранение изображений

#### ❓ Что происходит с изображениями по истечении срока?

Изображения **автоматически удаляются** с диска фоновой задачей. Записи в базе данных также очищаются.

#### ❓ Можно ли увеличить время хранения?

Да! В настройках хранения выберите нужное время или введите своё значение (до `MAX_IMAGE_TTL_HOURS`).

#### ❓ Где хранятся изображения?

В папке `images/` проекта. При использовании Docker эта папка примонтирована как volume: `./images:/app/images`.

#### ❓ Как скачать изображение?

Просто нажмите на изображение в Telegram и сохраните его. Все изображения отправляются как файлы.

---

### Технические вопросы

#### ❓ Можно ли запустить несколько экземпляров бота?

Теоретически да, но они будут использовать одну базу данных и одну папку изображений, что может привести к конфликтам. Рекомендуется запускать **один экземпляр**.

#### ❓ Как обновить бот?

```bash
docker compose down
# Скопируйте новые файлы
docker compose up -d --build
```

#### ❓ Как сделать резервную копию?

```bash
# База данных
cp data/bot.db backup_$(date +%Y%m%d).db

# Изображения
tar -czf images_backup_$(date +%Y%m%d).tar.gz images/
```

#### ❓ Как перенести бота на другой сервер?

1. Скопируйте все файлы проекта
2. Скопируйте `data/bot.db` (база данных)
3. Скопируйте `images/` (если нужны старые изображения)
4. Настройте `.env` на новом сервере
5. Запустите бот

#### ❓ Как ограничить доступ к SD API?

Используйте firewall, чтобы разрешить подключения только с IP сервера бота:

```bash
sudo ufw allow from <BOT_SERVER_IP> to any port 7860
```

---

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

```
tg-sd/
├── main.py                 # Точка входа, запуск бота
├── config.py               # Настройки и конфигурация
├── requirements.txt        # Зависимости Python
├── Dockerfile              # Образ Docker
├── docker-compose.yml      # Docker Compose конфигурация
├── .env                    # Переменные окружения (не в Git!)
├── .env.example            # Пример переменных окружения
├── .gitignore              # Игнорирование файлов Git
│
├── bot/                    # Обработчики команд бота
│   ├── __init__.py
│   ├── handlers_start.py       # /start, главное меню
│   ├── handlers_generation.py  # Генерация изображений
│   ├── handlers_profiles.py    # Управление профилями
│   └── handlers_settings.py    # Настройки хранения
│
├── sd/                     # Модуль Stable Diffusion
│   ├── __init__.py
│   └── sd_client.py        # Клиент для SD API
│
├── database/               # Модуль базы данных
│   ├── __init__.py
│   └── database.py         # SQLite операции
│
├── utils/                  # Утилиты
│   ├── __init__.py
│   └── image_manager.py    # Управление изображениями
│
├── images/                 # Сгенерированные изображения (создаётся автоматически)
└── data/                   # База данных (создаётся автоматически)
```

---

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

### Бот не запускается

**Проблема:** `BOT_TOKEN не установлен`

**Решение:** Убедитесь, что в файле `.env` указан корректный токен:

```env
BOT_TOKEN=ваш_реальный_токен_от_BotFather
```

### Ошибка подключения к SD API

**Проблема:** `SD API недоступно`

**Возможные причины и решения:**

1. **SD WebUI не запущен**
   - Запустите WebUI с флагами `--api --listen`

2. **Неправильный адрес**
   - Проверьте `SD_API_URL` в `.env`
   - Убедитесь, что IP-адрес корректный

3. **Firewall блокирует порт**
   ```bash
   # Проверьте доступность
   curl http://192.168.1.120:7860/sdapi/v1/options
   
   # Откройте порт на сервере SD
   sudo ufw allow 7860/tcp
   ```

4. **WebUI слушает только localhost**
   - Убедитесь, что используется флаг `--listen`

### Таймаут генерации

**Проблема:** Генерация занимает более 10 минут

**Решения:**

1. Уменьшите количество шагов в профиле
2. Уменьшите размер изображения
3. Используйте более быструю модель
4. Увеличьте таймаут в `sd_client.py` (параметр `timeout`)

### Изображения не сохраняются

**Проблема:** Ошибка сохранения файлов

**Решение:** Проверьте права доступа к директории:

```bash
# Для Docker
docker compose exec tg-sd-bot ls -la /app/

# Для прямого запуска
chmod 755 images/
chmod 755 data/
```

### Проблемы с базой данных

**Проблема:** Ошибки записи в БД

**Решение:** Убедитесь, что директория `data/` существует и доступна для записи:

```bash
mkdir -p data
chmod 755 data
```

### Логи бота

**Docker:**

```bash
docker compose logs -f tg-sd-bot
```

**Прямой запуск:**

Логи выводятся в консоль. Для записи в файл:

```bash
python main.py 2>&1 | tee bot.log
```

---

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

1. **Никогда не коммитьте `.env` файл в Git** — он содержит токен бота
2. **Используйте firewall** — ограничьте доступ к порту SD API только для сервера бота
3. **Регулярно обновляйте зависимости** — проверяйте обновления пакетов
4. **Ограничьте доступ к боту** — при необходимости добавьте проверку `user_id` в обработчиках

---

## Обновление бота

```bash
# Остановка
docker compose down

# Копирование новых файлов

# Пересборка и запуск
docker compose up -d --build
```

---

## Резервное копирование

Для резервного копирования сохраните:

```bash
# База данных (профили и настройки)
cp data/bot.db backup_$(date +%Y%m%d).db

# Изображения (если нужно)
tar -czf images_backup_$(date +%Y%m%d).tar.gz images/
```

---

## Лицензия

Этот проект предоставляется "как есть" без каких-либо гарантий.

---

## Поддержка

При возникновении проблем:

1. Проверьте логи бота
2. Убедитесь, что SD API доступен
3. Проверьте корректность `.env` файла
4. Обратитесь к разделу [Устранение неполадок](#устранение-неполадок)