Обзор развертывания HunyuanVideo на сервере¶

Предварительные требования и условия¶

Для развертывания HunyuanVideo требуется сервер Linux с операционной системой Ubuntu 22.04. Перед началом установки должны быть выполнены следующие условия:

Операционная система: Ubuntu 22.04 (рекомендуется поддержка ядра HWE).
Привилегии: Для установки системных пакетов, настройки Docker и изменения сетевых настроек требуются права root или привилегии sudo.
Домен и зона: Приложение настроено для зоны hostkey.in с префиксом hvideo.
Требования к GPU: Обязательно наличие GPU NVIDIA с поддержкой CUDA. В системе должны быть установлены драйверы NVIDIA и среда выполнения nvidia-docker2.
Сетевые порты:
- Порт 8080: Внутренний порт приложения.
- Порт 443: Внешний порт HTTPS для защищенного доступа через прокси.

FQDN конечной панели¶

После развертывания приложение доступно по следующему полностью ограниченному доменному имени (FQDN):

hvideo<Server ID>.hostkey.in:443

Примечание: Замените <Server ID> на конкретный идентификатор, присвоенный вашему экземпляру сервера.

Структура файлов и каталогов¶

Файлы приложения, конфигурация и данные хранятся в следующих местах:

Исходный код приложения: /opt/HunyuanVideo
- Содержит клонированный репозиторий от Tencent.
- Виртуальная среда: /opt/HunyuanVideo/venv
- Модели: /opt/HunyuanVideo/models (Хранит загруженные контрольные точки, такие как hunyuan-video-t2v-720p).
Конфигурация Nginx и прокси:
- Каталог: /root/nginx
- Файл Compose: /root/nginx/compose.yml
- Конфигурация пользователя: /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf
- Файл окружения: /data/nginx/nginx-certbot.env
Конфигурация Docker:
- Настройка среды выполнения: /etc/docker/daemon.json
SSL-сертификаты: Хранятся в Docker-томе nginx_secrets, маппированном в /etc/letsencrypt внутри контейнера.

Процесс установки приложения¶

Приложение HunyuanVideo устанавливается с помощью нативного скрипта, который клонирует исходный код, настраивает среду Python и загружает необходимые модели. Процесс включает следующие шаги:

Подготовка системы: Система обновляется, и если версия ОС соответствует, устанавливается ядро High Availability Kernel для Ubuntu 22.04.
Установка CUDA и драйверов:
- Инструментарий CUDA и драйверы NVIDIA устанавливаются в зависимости от версии релиза Ubuntu.
- Переменные среды (PATH и LD_LIBRARY_PATH) добавляются в ~/.bashrc, чтобы обеспечить доступ к исполняемым файлам CUDA.
- Модуль ядра nouveau удаляется, и инициализируются модули NVIDIA.
Docker и среда выполнения NVIDIA:
- Устанавливается пакет nvidia-docker2.
- Демон Docker настраивается на использование среды выполнения NVIDIA по умолчанию через /etc/docker/daemon.json.
- Сервис Docker перезапускается.
Настройка среды Python:
- Репозиторий клонируется с https://github.com/Tencent/HunyuanVideo.git в /opt/HunyuanVideo.
- Виртуальная среда Python 3 создается в /opt/HunyuanVideo/venv.
- Зависимости, перечисленные в requirements.txt, устанавливаются внутри виртуальной среды.
Загрузка моделей:
- Устанавливается CLI-инструмент huggingface-hub.
- Предварительно обученные контрольные точки (в частности, hunyuan-video-t2v-720p) загружаются в /opt/HunyuanVideo/models с помощью huggingface-cli.
Проверка:
- Запускается тестовая генерация с использованием sample_video.py и тестового промпта для проверки корректности настройки.

Контейнеры Docker и их развертывание¶

Приложение использует Docker для реализации обратного прокси и управления SSL-сертификатами. Развертывание осуществляется с помощью конфигурации Docker Compose, расположенной в /root/nginx.

Конфигурация контейнера¶

Следующая таблица резюмирует конфигурацию контейнера:

Имя сервиса	Образ	Режим сети	Подключенные тома (Volume Mounts)
`nginx`	`jonasal/nginx-certbot:latest`	`host`	`nginx_secrets` (external), маппирован на `/etc/letsencrypt` `/data/nginx/user_conf.d`, маппирован на `/etc/nginx/user_conf.d`

Команда развертывания¶

Контейнер развертывается с помощью следующей команды, выполняемой из каталога /root/nginx:

docker compose up -d

Файл compose.yml определяет сервис с переменной окружения CERTBOT_EMAIL, установленной в hkadm@hostkey.com, и загружает дополнительную конфигурацию из /data/nginx/nginx-certbot.env.

Прокси-серверы¶

Nginx используется в качестве обратного прокси для обработки HTTPS-трафика и управления SSL-сертификатами через Certbot.

Цель проксирования: Входящий трафик на порт 443 перенаправляется на http://127.0.0.1:8080.
Файл конфигурации: Специфичное правило прокси записывается в /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf.
Блок Location: В конфигурацию вставляется следующая строка после директивы location / {:
```
proxy_pass http://127.0.0.1:8080;
```
Управление SSL: Сертификаты управляются автоматически контейнером nginx-certbot, который хранит секреты во внешнем томе nginx_secrets.

Базы данных¶

Согласно предоставленной конфигурации, для этого экземпляра приложения не определены и не развернуты внешние сервисы баз данных (такие как PostgreSQL, MySQL или MongoDB). Приложение опирается на хранение в локальной файловой системе для моделей и результатов генерации.

Настройки прав доступа¶

Права доступа к файлам и каталогам устанавливаются следующим образом в процессе развертывания:

Каталог Nginx:
- Путь: /root/nginx
- Владелец/Группа: root:root
- Режим: 0755
Файл Compose:
- Путь: /root/nginx/compose.yml
- Владелец/Группа: root:root
- Режим: 0644
Конфигурация демона Docker:
- Путь: /etc/docker/daemon.json
- Режим: 0644

Приложение работает в каталоге /opt/HunyuanVideo, где находятся виртуальная среда и файлы моделей. Права на выполнение управляются оболочечными скриптами и интерпретатором Python внутри виртуальной среды.

Доступные порты для подключения¶

Следующие порты используются приложением и инфраструктурой прокси:

Порт 443: HTTPS-трафик для внешнего доступа через FQDN.
Порт 8080: Внутренний HTTP-порт, используемый приложением HunyuanVideo, перенаправляемый через Nginx.
Порт 80: Требуется для начальной валидации SSL-сертификата Certbot (обрабатывается прокси неявно).

Запуск, остановка и обновление¶

Управление компонентами приложения осуществляется с помощью стандартных команд Docker и сервисов Linux.

Управление прокси (Nginx/Certbot)¶

Запуск/Перезапуск:
```
cd /root/nginx
docker compose up -d
```
Остановка:
```
cd /root/nginx
docker compose down
```
Обновление: Получить последний образ и перезапустить:
```
cd /root/nginx
docker compose pull
docker compose up -d
```

Управление демоном Docker¶

Если конфигурация среды выполнения NVIDIA была изменена, перезапустите сервис Docker:

sudo systemctl restart docker

Запуск приложения¶

Для ручного выполнения скрипта генерации видео (после активации виртуальной среды):

source /opt/HunyuanVideo/venv/bin/activate
cd /opt/HunyuanVideo
python sample_video.py --prompt "A cyberpunk city at night"

Примечание: Само приложение в данной конфигурации не работает как постоянный Docker-контейнер, а выполняется через среду Python на хост-системе, при этом веб-доступ обеспечивается исключительно через Nginx-прокси, пересылающий запросы на порт 8080.