# Внимание: на сервере работает несколько проектов

## Дата обновления
2026-05-21

## Сервер
81.177.141.34 — единый VPS для независимых проектов.
Пользователь: `angel`
ОС: Ubuntu 24.04, Docker Engine

---

## 1. Проекты на сервере

### Проект A: aegisone — Сервисный портал AegisOne Engineering

| Параметр | Значение |
|----------|----------|
| Тип | Python FastAPI + PHP (публичный сайт) + PostgreSQL |
| Python | FastAPI на Uvicorn (4 workers), порт **8000** |
| PHP | Nginx (порт 8080) + PHP-FPM (порт 9000) |
| PostgreSQL | 16-alpine, порт **5432**, БД: `aegisone` |
| Домены | `service.aegisone.ru` (Python), `aegisone.ru` (PHP) |
| Директории | `/opt/projects/aegisone-py/` (Python), `/opt/projects/aegisone-php/` (PHP) |
| Docker проект | `aegisone` — контейнеры: `aegisone-app`, `aegisone-postgres` |
| Deploy | `py_service/deploy.sh` — версионирование, архив, SCP, docker compose up |

**Nginx-роутинг (service.aegisone.ru → localhost:8000):**
```
/              → localhost:8000 (FastAPI root — страница логина)
/service/*     → localhost:8000 (весь сервис FastAPI)
/service-style.php, /logo.php, /assets/* → localhost:8080 (PHP)
```

**Структура Python-приложения:**
```
py_service/
├── app/
│   ├── main.py                 — точка входа FastAPI, lifespan, статика
│   ├── config.py               — настройки (DB, SECRET_KEY, DOCS_DIR и т.д.)
│   ├── database.py             — подключение к PostgreSQL
│   ├── dependencies.py         — get_current_user, require_role
│   ├── models/
│   │   └── models.py           — SQLAlchemy модели (User, Object, Client, SLA и т.д.)
│   ├── routers/
│   │   └── service_pages.py    — все основные роуты + API бота Max
│   ├── documents_router.py     — роуты документов (/service/documents/)
│   ├── services/
│   │   └── docs_permissions.py — discover_docs(), load_permissions()
│   ├── templates/              — Jinja2 шаблоны
│   │   ├── base.html           — базовый HTML (noindex, favicon, theme switcher)
│   │   ├── login.html          — страница входа
│   │   ├── page.html           — основной layout с сайдбаром
│   │   ├── dashboard.html      — дашборд (дублирует сайдбар из page.html)
│   │   ├── documents/          — шаблоны документов
│   │   ├── pages/              — шаблоны страниц (customers, objects, sla и т.д.)
│   │   └── bot_*.html          — страницы управления ботом Max
│   └── static/
│       ├── css/                — service.css, service-theme.css
│       ├── js/                 — theme.js
│       └── img/                — favicons, svg, logo
├── docs/                       — .md файлы документов (26 шт)
├── scripts/                    — bump_version.py, migrate_mysql_to_pg.py
├── Dockerfile, docker-compose.yml
└── requirements.txt
```

**Роли пользователей:** `owner` (владелец), `engineer` (инженер), `technician` (техник)

**Управление ботом Max (раздел в сайдбаре для owner):**
- `/service/bot-settings` — настройки (имя, телефоны, email, часы работы, YandexGPT)
- `/service/bot-settings/responses` — редактирование шаблонов ответов
- `/service/bot-settings/features` — toggle функций бота
- `/service/bot-settings/categories` — CRUD категорий обращений
- `/service/bot-settings/kb` — база знаний (FAQ)
- `/service/bot-settings/conversations` — просмотр диалогов
- `/service/bot-settings/users` — пользователи бота
- `/service/bot-settings/test-runner` — тестовый прогон диалога
- `/service/bot-settings/analytics` — статистика + рассылки

---

### Проект C: max_bot — Чат-бот «София» для Max Messenger

| Параметр | Значение |
|----------|----------|
| Тип | Python FastAPI (Max Bot API) |
| FastAPI | порт **8001** |
| PostgreSQL | общая БД `aegisone` (порт 5432), таблицы с префиксом `bot_` |
| Домен | `max.aegisone.ru` |
| Директория | `/opt/projects/aegisone-py/max_bot/` |
| Контейнер | `aegisone-max-bot` |
| Webhook | `https://max.aegisone.ru/webhook` → localhost:8001 |
| Токен бота | `id2311381465_bot` (хранится в bot_settings) |

**Структура:**
```
max_bot/
├── app/
│   ├── main.py                 — FastAPI app, webhook, API для портала
│   ├── config.py               — настройки (shared DB URL)
│   ├── database.py             — AsyncSession (общая БД aegisone)
│   ├── max_api.py              — клиент Max API (send_message, subscribe)
│   ├── bot_engine.py           — обработчик webhook событий
│   ├── fsm.py                  — конечный автомат состояний
│   ├── conversation.py         — управление диалогами
│   ├── settings_cache.py       — кэш настроек (5 мин TTL)
│   ├── text_renderer.py        — рендер шаблонов с переменными
│   ├── file_storage.py         — сохранение файлов (local → Yandex Disk future)
│   ├── handlers/               — обработчики состояний
│   │   ├── greeting.py         — /start, приветствие
│   │   ├── consent.py          — ФЗ-152 согласие
│   │   ├── contact.py          — сбор контактов
│   │   ├── inquiry.py          — сбор обращения + авто-категоризация
│   │   ├── handoff.py          — передача оператору
│   │   ├── main_menu.py        — главное меню
│   │   └── features/           — доп. функции (risk_score, sla_status, etc.)
│   ├── integrations/
│   │   ├── _1c_unf.py          — webhook в 1С:УНФ + ответ от 1С
│   │   ├── portal_db.py        — чтение из общей БД
│   │   └── yandex_gpt.py       — YandexGPT для категоризации/эмоций
│   ├── keyboards/
│   │   └── inline.py           — генераторы inline-клавиатур
│   └── models/
│       └── models.py           — SQLAlchemy модели (bot_*)
├── sql/
│   └── bot_schema.sql          — CREATE TABLE + начальные данные
├── nginx/
│   └── max-aegisone.conf       — nginx config
├── Dockerfile, docker-compose.yml
└── requirements.txt
```

**Таблицы бота в общей БД:**
`bot_users`, `bot_conversations`, `bot_messages`, `bot_consent_logs`, `bot_1c_sync_log`,
`bot_knowledge_base`, `bot_categories`, `bot_settings`, `bot_features`, `bot_response_templates`, `bot_broadcasts`

**Nginx-роутинг (max.aegisone.ru → localhost:8001):**
```
/webhook       → localhost:8001/webhook (Max API webhook)
/api/*         → localhost:8001/api/* (API для сервисного портала)
/health        → localhost:8001/health
```

---

### Проект B: VoIdeaAI — AI-платформа

| Параметр | Значение |
|----------|----------|
| Тип | Python FastAPI + React Frontend + PostgreSQL + Redis |
| FastAPI | порт **8020** |
| PostgreSQL | порт **5444**, БД: `voidea` |
| Redis | порт **6380** |
| Gitea | порт **3000**, PostgreSQL **5433** |
| Домены | `voideaai.ru`, `git.voideaai.ru` |
| Директория | `/opt/projects/voidea/` |
| Docker проект | `voidea` |
| Nginx конфиг | `/opt/projects/nginx-proxy/conf.d/voideaai.ru.conf` |

---

## 2. Критические правила

### Порты — НЕ занимать!
```
 8000 — aegisone FastAPI
 8001 — max_bot FastAPI
 8080 — aegisone PHP nginx
 9000 — aegisone PHP-FPM
 5432 — aegisone PostgreSQL
 8020 — VoIdea FastAPI
 5444 — VoIdea PostgreSQL
 6380 — VoIdea Redis
 3000 — Gitea web
 5433 — Gitea PostgreSQL
 9001 — Portainer HTTP
 9443 — Portainer HTTPS
```

### nginx-proxy общий
- Конфиги: `/opt/projects/nginx-proxy/conf.d/`
- Файлы: `aegisone.conf`, `service-aegisone.conf`, `max-aegisone.conf`, `voideaai.ru.conf`, `gitea.conf`
- **Перед рестартом nginx:** `docker compose -p nginx-proxy exec nginx nginx -t`

### Docker
- **Все контейнеры используют `network_mode: host`** (bridge не работает на OpenVZ)
- `docker system prune -af` удалит build cache ВСЕХ проектов
- Префиксы Docker Compose:
  - `docker compose -p aegisone` (или `cd /opt/projects/aegisone-py && docker compose`)
  - `docker compose -p voidea`
  - `docker compose -p gitea`
  - `docker compose -p nginx-proxy`
  - `docker compose -p portainer`

### Диск
- 20GB всего, ~13GB свободно
- Проверка: `df -h /`
- Очистка: `docker builder prune -af`

### Публичная часть (PHP) НЕ ТРОГАТЬ
- PHP сайт (aegisone.ru) — отдельный проект, не связан с Python-сервисом
- Все изменения только в `py_service/` и `max_bot/`

---

## 3. Команды для проверки состояния

### aegisone (Python)
```bash
docker ps --filter name=aegisone
docker logs aegisone-app --tail=50
curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/service/dashboard/
cat /opt/projects/aegisone-py/version.txt
docker exec aegisone-postgres psql -U aegisone -d aegisone -c "\dt"
```

### max_bot (София)
```bash
docker ps --filter name=max-bot
docker logs aegisone-max-bot --tail=50
curl -s http://localhost:8001/health
# Проверить webhook:
curl -s http://localhost:8001/api/bot/settings
```

### VoIdeaAI
```bash
docker compose -p voidea ps
docker compose -p voidea logs --tail=20 app
curl -s http://localhost:8020/health
```

---

## 4. Деплой

### aegisone (py_service)
```bash
# Локально (из py_service/)
./deploy.sh [--bump patch|minor|major]
```

### max_bot
```bash
# SCP на сервер, затем:
cd /opt/projects/aegisone-py/max_bot
docker compose build --no-cache
docker compose up -d
```

---

## 5. Troubleshooting

| Проблема | Действие |
|----------|----------|
| aegisone FastAPI не отвечает | `docker logs aegisone-app --tail=50` |
| max_bot не отвечает | `docker logs aegisone-max-bot --tail=50` |
| Ошибка БД | `docker logs aegisone-postgres --tail=20` |
| Документ не найден | Проверить `discover_docs()` — файл .md есть в `py_service/docs/`? |
| Webhook не работает | Проверить `curl http://localhost:8001/health` и nginx конфиг |
| Portainer не открывается | Проверить `http://81.177.141.34:9001` и `https://81.177.141.34:9443` |
| Не хватает места | `df -h /`, `docker builder prune -af` |
| nginx ошибка | `docker compose -p nginx-proxy exec nginx nginx -t` |

---

*Создан: 2026-05-20*
*Обновлён: 2026-05-21 — добавлен max_bot (София)*
