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

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

Для развертывания HunyuanVideo требуется среда на базе Linux с определенными аппаратными и программными конфигурациями для поддержки генерации видео с ускорением GPU.

Операционная система: Ubuntu 22.04 LTS (или совместимая версия с ядром HWE).
Привилегии: Для установки пакетов на уровне системы и настройки Docker требуются права root или привилегии sudo.
Аппаратное обеспечение: Видеокарта NVIDIA с совместимыми драйверами и поддержкой CUDA.
Сеть: Доступ в интернет для загрузки репозиториев, моделей и сертификатов.
Порты: Порт 443 требуется для внешнего доступа по HTTPS.

FQDN финальной панели¶

Приложение доступно по следующему формату Полного Квалифицированного Доменного Имени (FQDN) в домене hostkey.in:

Формат домена: hvideo<Server ID>.hostkey.in
Порт: 443 (HTTPS)
Путь: /

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

Приложение и его вспомогательные компоненты организованы в следующей структуре каталогов:

Исходный код приложения: /opt/HunyuanVideo
Содержит клонированный репозиторий от Tencent.
Среда Python: /opt/HunyuanVideo/venv
Виртуальная среда для зависимостей Python.
Модели: /opt/HunyuanVideo/models
Место хранения загруженных контрольных точек (checkpoints) HunyuanVideo.
Конфигурация Nginx:
Каталог: /root/nginx
Файл compose: /root/nginx/compose.yml
Конфигурация пользователя: /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf
Docker Secrets: /etc/letsencrypt (монтированный том для SSL-сертификатов).

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

Установка включает клонирование репозитория, настройку виртуальной среды Python, установку зависимостей и загрузку необходимых AI-моделей.

Клонирование репозитория: Репозиторий HunyuanVideo клонируется с GitHub в каталог /opt/HunyuanVideo.
```
git clone https://github.com/Tencent/HunyuanVideo.git /opt/HunyuanVideo
```
Создание виртуальной среды: В каталоге приложения создается виртуальная среда Python 3.
```
python3 -m venv /opt/HunyuanVideo/venv
```
Установка зависимостей: Пакеты Python устанавливаются с помощью pip из файла requirements.txt.
```
source /opt/HunyuanVideo/venv/bin/activate
pip install -r /opt/HunyuanVideo/requirements.txt
```
Установка CLI Hugging Face: Пакет huggingface-hub с поддержкой CLI устанавливается для облегчения загрузки моделей.
```
pip install "huggingface-hub[cli]"
```

Загрузка моделей: Предварительно обученные контрольные точки загружаются напрямую в каталог моделей.

mkdir -p /opt/HunyuanVideo/models
huggingface-cli download tencent/HunyuanVideo \
  --local-dir /opt/HunyuanVideo/models \
  --local-dir-use-symlinks False \
  --include "hunyuan-video-t2v-720p/**"

Права доступа и безопасность¶

Безопасность управляется через установку пакетов на уровне системы и конфигурацию среды выполнения Docker.

Системные пакеты: Необходимые инструменты, такие как git, python3, curl и wget, устанавливаются через apt.
Драйверы NVIDIA: Пакет nvidia-docker2 устанавливается для обеспечения передачи GPU (passthrough) для контейнеров.
Среда выполнения Docker: Среда выполнения Docker по умолчанию настроена на использование среды выполнения NVIDIA.
Межсетевой экран (Firewall): Внешний доступ ограничен портом 443 для HTTPS-трафика, управляемого прокси-сервером Nginx.

Базы данных¶

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

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

Развертывание использует контейнеры Docker для обратного прокси-сервера и управления SSL. Само приложение работает в среде хоста с настроенным доступом к GPU через среду выполнения NVIDIA.

Контейнер Nginx-Certbot:
Образ: jonasal/nginx-certbot:latest
Политика перезапуска: unless-stopped
Режим сети: host
Томы:
- nginx_secrets монтируется в /etc/letsencrypt
- /data/nginx/user_conf.d монтируется в /etc/nginx/user_conf.d
Переменные окружения:
- CERTBOT_EMAIL: hkadm@hostkey.com
- Конфигурация загружается из /data/nginx/nginx-certbot.env
Файл Docker Compose: Оркестрация контейнеров определена в файле /root/nginx/compose.yml.
Конфигурация среды выполнения NVIDIA: Docker настроен на использование среды выполнения NVIDIA по умолчанию через /etc/docker/daemon.json:
```
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
```

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

Nginx выступает в роли обратного прокси-сервера и терминала SSL для приложения.

Конфигурация прокси:
Файл конфигурации Nginx находится по адресу /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf.
Директива proxy_pass пересылает запросы во внутренний сервис приложения:
```
location / {
    proxy_pass http://127.0.0.1:8080;
}
```
SSL/TLS:
Управляется автоматически контейнером nginx-certbot.
Сертификаты хранятся в томе nginx_secrets.
Пользовательский домен:
Домен hvideo<Server ID>.hostkey.in сопоставлен с внутренним сервисом.

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

Права доступа к файлам и каталогам настроены для обеспечения правильного доступа для пользователя root и демона Docker.

Каталог Nginx:
Путь: /root/nginx
Владелец: root:root
Режим: 0755
Файл Compose:
Путь: /root/nginx/compose.yml
Владелец: root:root
Режим: 0644
Каталог приложения:
Путь: /opt/HunyuanVideo
Права доступа управляются пользователем, выполняющим скрипты Python (обычно root или выделенный пользователь сервиса).

Расположение файлов конфигурации и данных¶

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

Файл/Каталог	Путь	Описание
Исходный код приложения	`/opt/HunyuanVideo`	Основной код репозитория
Виртуальная среда Python	`/opt/HunyuanVideo/venv`	Изолированная среда Python
AI-модели	`/opt/HunyuanVideo/models`	Загруженные контрольные точки моделей
Docker Compose	`/root/nginx/compose.yml`	Определение контейнера Nginx
Конфигурация Nginx	`/data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf`	Правила обратного прокси-сервера
Конфигурация демона Docker	`/etc/docker/daemon.json`	Настройки среды выполнения NVIDIA

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

Следующие порты настроены для внешнего и внутреннего взаимодействия:

Порт 443: Внешний доступ по HTTPS через прокси-сервер Nginx.
Порт 8080: Внутренний HTTP-порт, используемый приложением и проксируемый Nginx.

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

Управление службами осуществляется через Docker Compose для прокси-сервера и стандартные команды Python для приложения.

Запуск прокси-сервера Nginx:
```
cd /root/nginx
docker compose up -d
```
Остановка прокси-сервера Nginx:
```
cd /root/nginx
docker compose down
```

Обновление прокси-сервера Nginx:

cd /root/nginx
docker compose pull
docker compose up -d

Запуск тестового сценария приложения: Для проверки установки выполните скрипт образцовой генерации:
```
cd /opt/HunyuanVideo
source venv/bin/activate
python sample_video.py --prompt "A cyberpunk city at night"
```
Перезапуск службы Docker: Требуется после изменения файла /etc/docker/daemon.json:
```
systemctl restart docker
```