feat: deploy infrastructure + disk/drive, calendar, presentation, workspaces, onboarding, demo user

2026-05-19 16:26:26 +03:00
parent 688d043dad
commit 3529c39b22
304 changed files with 18826 additions and 1176 deletions
@@ -0,0 +1,214 @@
+# VoIdeaAI — Инструкция для AI-разработчика (локальная разработка + деплой)
+
+## Назначение
+Эта инструкция — для AI-агента, который продолжает разработку проекта VoIdeaAI.
+Работа ведётся **локально**, деплой — отправкой на сервер.
+
+---
+
+## 1. Архитектура проекта
+
+```
+voidea/
+├── app/                    # Backend (Python FastAPI)
+│   ├── api/v1/            # HTTP endpoints
+│   ├── agents/            # Системные агенты
+│   ├── core/              # Конфиг, БД, security
+│   ├── integrations/      # AI, OAuth, Telegram, Calendar
+│   ├── models/            # SQLAlchemy модели
+│   ├── schemas/           # Pydantic схемы
+│   ├── services/          # Бизнес-логика
+│   └── tasks/             # Celery задачи
+├── webui/                 # Frontend (React + Vite + Tailwind)
+├── flutter/               # Mobile app (Flutter, отдельная разработка)
+├── deploy/                # Файлы деплоя
+│   ├── gitea/             # Docker Compose для Gitea
+│   ├── images/            # Docker образы (tar)
+│   ├── voideaai.nginx.conf
+│   └── voidea-api.service / voidea-worker.service / voidea-beat.service (systemd — legacy)
+├── docs/instructions/     # Инструкции для AI
+├── Dockerfile             # Multi-stage сборка (frontend + backend)
+├── docker-compose.yml     # 4 сервиса: app, worker, db, redis
+└── .env.production        # Шаблон .env для сервера
+```
+
+## 2. Технологический стек
+
+| Компонент | Технология |
+|-----------|-----------|
+| Backend | Python 3.12, FastAPI, SQLAlchemy async |
+| Frontend | React 18, Vite, Tailwind CSS, TypeScript |
+| Mobile | Flutter (на сервер НЕ деплоится) |
+| Database | PostgreSQL 16 |
+| Queue | Celery + Redis 7 |
+| Auth | JWT (access + refresh) |
+| AI | Yandex GPT, GigaChat (fallback chain) |
+| Server | Ubuntu 24.04, Docker Compose, хост-нетворкинг |
+
+## 3. Локальный запуск для разработки
+
+### 3.1 Backend
+```bash
+# Виртуальное окружение
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+venv\Scripts\activate     # Windows
+
+# Зависимости
+pip install -r requirements.txt
+
+# PostgreSQL (локально или через Docker)
+# БД: voidea, user: voidea, pass: voidea_pass, port: 5432
+
+# Миграции
+alembic upgrade head
+
+# Запуск
+uvicorn app.main:app --reload --port 8020
+```
+
+### 3.2 Frontend
+```bash
+cd webui
+npm ci
+npm run dev
+```
+
+### 3.3 Mobile (Flutter)
+```bash
+cd flutter
+flutter pub get
+flutter run
+```
+
+## 4. Процесс деплоя
+
+**Важно: на сервере НЕ dev-окружение. Все правки — локально, затем деплой.**
+
+### Основной сценарий
+```bash
+# 1. Внести изменения локально
+# 2. Закоммитить
+git add .
+git commit -m "feat: описание изменения"
+
+# 3. Запушить в Gitea
+git push origin master
+
+# 4. На сервере
+ssh angel@81.177.141.34
+cd /opt/projects/voidea
+
+# 4a. Получить изменения
+git pull
+
+# 4b. Пересобрать и перезапустить
+docker compose up -d --build
+
+# 4c. Проверить
+curl -s http://localhost:8020/health
+```
+
+### Миграции БД
+```bash
+# Накатить
+docker compose exec app alembic upgrade head
+
+# Откатить
+docker compose exec app alembic downgrade -1
+```
+
+### Просмотр логов
+```bash
+docker compose logs --tail=50 app
+docker compose logs --tail=50 worker
+```
+
+## 5. Структура .env на сервере
+
+Файл `.env` в `/opt/projects/voidea/.env`.
+Шаблон — `.env.production` в корне репозитория.
+
+**Важные отличия от .env.example:**
+- `DATABASE_URL` использует порт **5444** (а не 5432)
+- `REDIS_URL` использует порт **6380** (а не 6379)
+- Порты изменены, чтобы не конфликтовать с проектом aegisone на том же сервере
+
+## 6. Важные ограничения
+
+### Серверные (VPS)
+- **Bridge-сеть не работает** — только `network_mode: host`
+- **Docker build** всегда с `network: host`
+- **Docker Hub** может таймаутить на больших образах (>100MB) — используйте `docker save`/`docker load`
+- Всего 20GB диска, ~13GB свободно. Следите за `df -h /`
+
+### Кодовые
+- Не трогать `.env` на сервере (секреты)
+- `flutter/` — только локальная разработка, в `.dockerignore`, на сервер не деплоится
+- `webui/node_modules/` — в `.gitignore`, не коммитить
+- Миграции БД — через `alembic`, не вручную
+
+## 7. Docker-образы
+
+Образы хранятся в `deploy/images/` в формате `.tar`.
+Список используемых образов:
+- `postgres:16-alpine` — voidea + gitea
+- `redis:7-alpine` — voidea
+- `gitea/gitea:latest-rootless` — Gitea
+- Образ самого приложения собирается из `Dockerfile`
+
+Для обновления образов на сервере:
+```bash
+# Локально: скачать и запаковать
+docker pull postgres:16-alpine
+docker save postgres:16-alpine -o deploy/images/postgres.tar
+scp deploy/images/postgres.tar angel@81.177.141.34:/home/angel/
+
+# На сервере:
+docker load -i /home/angel/postgres.tar
+```
+
+## 8. Полезные команды на сервере
+
+```bash
+# Статус проектов
+docker compose -p voidea ps
+docker compose -p gitea ps
+docker compose -p nginx-proxy ps
+
+# Логи VoIdea
+docker compose -p voidea logs --tail=100 -f app
+
+# Перезапуск конкретного сервиса
+docker compose -p voidea restart app
+
+# Полная пересборка
+docker compose -p voidea up -d --build
+
+# Очистка кеша Docker
+docker builder prune -af
+docker system prune -af
+
+# Проверка nginx
+docker compose -p nginx-proxy exec nginx nginx -t
+docker compose -p nginx-proxy exec nginx nginx -s reload
+```
+
+## 9. Порты на сервере
+
+| Порт | Сервис | Проект |
+|------|--------|--------|
+| 8020 | FastAPI | VoIdea |
+| 5444 | PostgreSQL | VoIdea |
+| 6380 | Redis | VoIdea |
+| 3000 | Gitea | Gitea |
+| 5433 | PostgreSQL | Gitea |
+| 80/443 | nginx-proxy | Общий |
+| 8000 | FastAPI | aegisone (чужой) |
+| 5432 | PostgreSQL | aegisone (чужой) |
+
+Не занимать порты, помеченные как чужие.
+
+---
+
+*Обновлён: 2026-05-19*