246 lines
11 KiB
Markdown
246 lines
11 KiB
Markdown
# Структура проекта F7cloud Talk Recording Server
|
||
|
||
## Обзор
|
||
|
||
Этот документ описывает структуру проекта и назначение каждого компонента для удобной навигации и использования при развертывании.
|
||
|
||
## Основная структура
|
||
|
||
```
|
||
f7cloud-talk-recording/
|
||
│
|
||
├── src/ # Исходный код приложения
|
||
│ └── f7cloud/
|
||
│ └── talk/
|
||
│ └── recording/ # Основной модуль записи
|
||
│ ├── __init__.py # Инициализация модуля, версия, константы
|
||
│ ├── __main__.py # Точка входа CLI (команда f7cloud-talk-recording)
|
||
│ ├── Server.py # HTTP сервер (Flask), обработка API запросов
|
||
│ ├── Service.py # Сервис записи (управление процессом записи)
|
||
│ ├── Config.py # Управление конфигурацией из server.conf
|
||
│ ├── Participant.py # Управление участником в браузере (Selenium)
|
||
│ ├── BackendNotifier.py # Уведомления бэкенда F7cloud
|
||
│ ├── RecorderArgumentsBuilder.py # Построитель аргументов для FFmpeg
|
||
│ └── Benchmark.py # Утилита для бенчмарков
|
||
│
|
||
├── dependencies/ # Внешние зависимости (не требуют установки из репозиториев)
|
||
│ ├── firefox-esr/ # Firefox ESR - браузер для записи
|
||
│ │ ├── firefox # Исполняемый файл Firefox
|
||
│ │ └── ... # Остальные файлы Firefox
|
||
│ └── geckodriver # Geckodriver - драйвер Selenium для Firefox
|
||
│
|
||
├── tests/ # Тесты
|
||
│ ├── ServerTest.py # Тесты HTTP сервера
|
||
│ └── ConfigTest.py # Тесты конфигурации
|
||
│
|
||
├── server.conf.in # Шаблон конфигурационного файла
|
||
│ # Копируется в /etc/f7cloud-talk-recording/server.conf при установке
|
||
│
|
||
├── pyproject.toml # Конфигурация Python проекта
|
||
│ # Содержит зависимости, метаданные, скрипты
|
||
│
|
||
├── f7recording.sh # Скрипт установки (запуск с .env)
|
||
│ # Устанавливает все зависимости и настраивает систему
|
||
│
|
||
├── INSTALL.md # Подробная инструкция по установке
|
||
├── README.md # Основная документация проекта
|
||
└── PROJECT_STRUCTURE.md # Этот файл
|
||
```
|
||
|
||
## Детальное описание компонентов
|
||
|
||
### src/f7cloud/talk/recording/
|
||
|
||
#### __init__.py
|
||
- Версия пакета (`__version__`)
|
||
- Константы статусов записи (`RECORDING_STATUS_AUDIO_AND_VIDEO`, `RECORDING_STATUS_AUDIO_ONLY`)
|
||
- User-Agent для HTTP запросов
|
||
|
||
#### __main__.py
|
||
- Точка входа для команды `f7cloud-talk-recording`
|
||
- Парсинг аргументов командной строки
|
||
- Загрузка конфигурации и запуск сервера
|
||
|
||
#### Server.py
|
||
- HTTP сервер на Flask
|
||
- Обработка запросов на начало/конец записи
|
||
- Prometheus metrics endpoint
|
||
- Валидация запросов и аутентификация
|
||
|
||
#### Service.py
|
||
- Класс `Service` - основной сервис записи
|
||
- Управление виртуальным дисплеем (Xvfb)
|
||
- Управление аудио sink (PulseAudio)
|
||
- Запуск браузера и FFmpeg
|
||
- Загрузка записи на сервер
|
||
|
||
#### Config.py
|
||
- Класс `Config` - управление конфигурацией
|
||
- Чтение и парсинг `server.conf`
|
||
- Методы для получения настроек бэкенда, signaling, записи
|
||
|
||
#### Participant.py
|
||
- Класс `Participant` - управление участником в браузере
|
||
- Класс `SeleniumHelper` - работа с Selenium WebDriver
|
||
- Открытие страницы записи
|
||
- Подключение к signaling серверу
|
||
- Управление медиа потоками
|
||
|
||
#### BackendNotifier.py
|
||
- Функции для отправки уведомлений бэкенду F7cloud
|
||
- `started()` - уведомление о начале записи
|
||
- `stopped()` - уведомление о конце записи
|
||
- `failed()` - уведомление об ошибке
|
||
- `uploadRecording()` - загрузка записи на сервер
|
||
|
||
#### RecorderArgumentsBuilder.py
|
||
- Построитель аргументов командной строки для FFmpeg
|
||
- Формирование команд для записи аудио и видео
|
||
|
||
#### Benchmark.py
|
||
- Утилита для бенчмарков производительности
|
||
- Тестирование записи с различными параметрами
|
||
|
||
### dependencies/
|
||
|
||
#### firefox-esr/
|
||
Firefox ESR (Extended Support Release) - стабильная версия Firefox для корпоративного использования.
|
||
- Используется для записи видеозвонков
|
||
- Запускается в headless режиме через Selenium
|
||
- Устанавливается в `/opt/firefox-esr` при установке
|
||
|
||
#### geckodriver
|
||
Драйвер Selenium для Firefox.
|
||
- Используется для управления Firefox через Selenium WebDriver
|
||
- Устанавливается в `/usr/local/bin/geckodriver` при установке
|
||
|
||
### Конфигурационные файлы
|
||
|
||
#### server.conf.in
|
||
Шаблон конфигурационного файла. Содержит секции:
|
||
- `[logs]` - уровень логирования
|
||
- `[http]` - настройки HTTP сервера
|
||
- `[app]` - настройки приложения (trusted proxies)
|
||
- `[backend]` - общие настройки бэкенда
|
||
- `[backend-id]` - настройки конкретного бэкенда F7cloud
|
||
- `[signaling]` - настройки signaling сервера
|
||
- `[ffmpeg]` - настройки FFmpeg
|
||
- `[recording]` - настройки записи (браузер, пути)
|
||
- `[stats]` - настройки статистики
|
||
|
||
#### pyproject.toml
|
||
Конфигурация Python проекта:
|
||
- Метаданные проекта (имя, описание, авторы)
|
||
- Зависимости Python
|
||
- Entry points (команды CLI)
|
||
- Настройки инструментов (pylint, pytest)
|
||
|
||
### Скрипты
|
||
|
||
#### f7recording.sh
|
||
Скрипт установки (принимает путь к .env-файлу):
|
||
1. Устанавливает системные зависимости
|
||
2. Устанавливает Firefox ESR и Geckodriver
|
||
3. Создает виртуальное окружение Python
|
||
4. Устанавливает Python-зависимости
|
||
5. Создает пользователя `f7cloud-talk-recording`
|
||
6. Копирует конфигурацию
|
||
7. Создает systemd service
|
||
|
||
## Потоки данных
|
||
|
||
### Процесс записи
|
||
|
||
1. **Запрос на запись** → Server.py получает HTTP запрос
|
||
2. **Валидация** → Server.py проверяет запрос и создает Service
|
||
3. **Инициализация** → Service.py создает виртуальный дисплей и аудио sink
|
||
4. **Браузер** → Participant.py запускает Firefox через Selenium
|
||
5. **Подключение** → Participant.py открывает страницу записи и подключается к signaling
|
||
6. **Запись** → Service.py запускает FFmpeg для записи дисплея и аудио
|
||
7. **Завершение** → Service.py останавливает запись и загружает файл через BackendNotifier.py
|
||
|
||
### Взаимодействие компонентов
|
||
|
||
```
|
||
HTTP Request → Server.py
|
||
↓
|
||
Service.py
|
||
↓
|
||
┌──────┴──────┐
|
||
↓ ↓
|
||
Participant.py FFmpeg
|
||
(Selenium) (запись)
|
||
↓ ↓
|
||
BackendNotifier.py
|
||
↓
|
||
F7cloud Server
|
||
```
|
||
|
||
## Установка и развертывание
|
||
|
||
### Автоматическая установка
|
||
|
||
```bash
|
||
sudo ./f7recording.sh /path/to/f7cloud-install.env
|
||
```
|
||
|
||
### Ручная установка
|
||
|
||
См. `INSTALL.md` для подробных инструкций.
|
||
|
||
### После установки
|
||
|
||
1. Редактировать `/etc/f7cloud-talk-recording/server.conf`
|
||
2. Запустить: `sudo systemctl start f7cloud-talk-recording`
|
||
3. Включить автозапуск: `sudo systemctl enable f7cloud-talk-recording`
|
||
|
||
## Разработка
|
||
|
||
### Структура для разработчиков
|
||
|
||
- `src/` - исходный код
|
||
- `tests/` - тесты
|
||
- `pyproject.toml` - зависимости и настройки
|
||
|
||
### Запуск для разработки
|
||
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install -e ".[dev]"
|
||
f7cloud-talk-recording --config server.conf.in
|
||
```
|
||
|
||
## Полезные команды
|
||
|
||
### Проверка установки
|
||
|
||
```bash
|
||
# Проверка Firefox
|
||
/usr/local/bin/firefox-esr --version
|
||
|
||
# Проверка Geckodriver
|
||
/usr/local/bin/geckodriver --version
|
||
|
||
# Проверка Python пакета
|
||
source venv/bin/activate
|
||
f7cloud-talk-recording --version
|
||
```
|
||
|
||
### Логи и отладка
|
||
|
||
```bash
|
||
# Логи systemd
|
||
sudo journalctl -u f7cloud-talk-recording -f
|
||
|
||
# Ручной запуск с логами
|
||
source venv/bin/activate
|
||
f7cloud-talk-recording --config /etc/f7cloud-talk-recording/server.conf
|
||
```
|
||
|
||
## Дополнительная информация
|
||
|
||
- `INSTALL.md` - подробная инструкция по установке
|
||
- `README.md` - основная документация
|
||
- `server.conf.in` - комментарии в конфигурации содержат описание всех параметров
|