Практический гайд

Как публиковать и версионировать HTML-дашборды, созданные ИИ

Как публиковать и версионировать HTML-дашборды, созданные ИИ
Temporary fallback cover; replace in editorial pass.
Уровень: с нуля Время чтения: до 12 минут Формат: self-hosted
Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.

ИИ быстро создаёт HTML-отчёт, но почти так же быстро появляются его копии: final.html, final-new.html и архив в мессенджере. В результате непонятно, какая версия опубликована, кто может её открыть и как вернуться к рабочему состоянию. В этой статье соберём простой процесс вокруг OnePage: один каталог для публикации, отдельные версии, проверка доступа и понятный откат.

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

Что получится в конце

Вы развернёте OnePage в Docker, поместите в него статический HTML-дашборд и проверите четыре операции:

В командах ниже имя Docker-образа обозначено переменной ONEPAGE_IMAGE. Подставьте официальное имя образа из документации вашей сборки OnePage. Это сделано намеренно: имя образа и набор переменных окружения зависят от конкретной поставки и не должны угадываться.

1. Подготовьте рабочий каталог

Нужны Docker с Compose, каталог проекта и готовый HTML-файл. Команды выполняйте в отдельной директории, чтобы не смешать отчёт с другими файлами.

mkdir -p onepage-dashboard/site/versions/v1
cd onepage-dashboard

cp /path/to/dashboard.html site/versions/v1/index.html
cp site/versions/v1/index.html site/index.html

Путь /path/to/dashboard.html замените на фактическое расположение файла. Если отчёт использует изображения, таблицы стилей или JavaScript, скопируйте их в site/ и сохраните относительные пути внутри HTML. Так страница не будет зависеть от локального диска автора.

2. Опишите запуск в Docker Compose

Создайте файл compose.yaml. В примере каталог site монтируется в контейнер только для чтения. Это снижает риск случайного изменения опубликованного файла изнутри контейнера.

services:
  onepage:
    image: ${ONEPAGE_IMAGE}
    container_name: onepage-dashboard
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro

Путь назначения /usr/share/nginx/html подходит для сборки OnePage, которая публикует статические файлы через веб-сервер. Если ваша сборка использует другой каталог публикации, замените только правую часть volume-монтирования согласно её документации.

Сохраните имя образа в локальном файле .env. Не добавляйте этот файл в репозиторий, если в нём есть приватные настройки.

printf '%s\n' 'ONEPAGE_IMAGE=официальное-имя-образа-onepage' > .env
docker compose config
docker compose up -d

Команда docker compose config сначала проверяет, что Compose смог подставить переменную и разобрать YAML. Если проверка успешна, docker compose up -d запускает контейнер в фоне.

3. Проверьте первую публикацию

Откройте в браузере http://localhost:8080/. Ожидаемый результат: отображается именно ваш HTML-дашборд, а не список файлов и не страница ошибки.

Для быстрой проверки из терминала используйте:

curl -I http://localhost:8080/
docker compose ps
docker compose logs --tail=50 onepage

В ответе curl ищите успешный HTTP-статус. В docker compose ps контейнер должен иметь состояние, в котором он продолжает работать. Логи нужны, если браузер показывает ошибку или контейнер сразу завершается.

4. Обновляйте отчёт через новые версии

Не перезаписывайте единственную копию HTML. Сохраните новую публикацию в отдельном каталоге, например v2, а затем обновите рабочий файл.

mkdir -p site/versions/v2
cp /path/to/dashboard-v2.html site/versions/v2/index.html
cp site/versions/v2/index.html site/index.html

curl -fsS http://localhost:8080/ -o /tmp/onepage-check.html
cmp site/versions/v2/index.html /tmp/onepage-check.html

Здесь cmp сравнивает опубликованный ответ с локальной версией. Проверка подходит для простого статического отчёта. Если OnePage меняет HTML при отдаче страницы, сравнивайте не весь файл, а видимый заголовок, идентификатор версии или другой стабильный маркер.

Добавьте в сам отчёт небольшой маркер версии. Например:

<meta name="report-version" content="v2">

Такой маркер помогает понять, какую версию вы открыли, когда браузер или промежуточный прокси показывает кэшированный результат.

5. Сделайте откат

Откат выполняется копированием сохранённой версии обратно в точку публикации. Сначала сохраните текущий файл, чтобы откат можно было отменить.

cp site/index.html site/versions/v2/index-before-rollback.html
cp site/versions/v1/index.html site/index.html

curl -fsS http://localhost:8080/ -o /tmp/onepage-rollback-check.html
cmp site/versions/v1/index.html /tmp/onepage-rollback-check.html

Если OnePage кэширует страницы, очистите кэш способом, предусмотренным вашей сборкой, или проверьте результат в приватном окне. Не удаляйте каталоги старых версий до тех пор, пока новая публикация не прошла проверку.

6. Проверьте контроль доступа

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

ports:
  - "127.0.0.1:8080:80"

После изменения перезапустите сервис:

docker compose up -d
curl -I http://127.0.0.1:8080/

Если доступ нужен нескольким пользователям, настройте аутентификацию и HTTPS на прокси перед OnePage. Конкретный способ зависит от вашей инфраструктуры. Не считайте скрытый URL контролем доступа: ссылку можно переслать, а поисковая индексация не заменяет авторизацию.

Проверьте доступ как минимум с двух сторон: авторизованный пользователь должен открыть отчёт, а запрос без учётных данных должен получить отказ или перенаправление на страницу входа. Такой тест нужно выполнять уже на вашем прокси и в вашей сети, потому что Docker Compose сам по себе не описывает политику пользователей.

Безопасный минимальный процесс

  1. Сгенерируйте HTML-отчёт и связанные ресурсы в отдельной папке.
  2. Проверьте файл локально в браузере.
  3. Сохраните его в новом каталоге версии.
  4. Скопируйте выбранную версию в каталог публикации.
  5. Проверьте HTTP-ответ и видимый маркер версии.
  6. Только после проверки открывайте доступ другим пользователям.

Если отчёт содержит персональные данные, токены, внутренние URL или исходные выгрузки, удалите их из HTML и связанных ресурсов до публикации. HTML-страница, доступная браузеру, уже считается раскрытой тому, кто может её открыть.

Типовые ошибки

Контейнер не запускается

Выполните docker compose config и проверьте имя образа, YAML и переменную ONEPAGE_IMAGE. Затем посмотрите последние строки логов: docker compose logs --tail=100 onepage.

Страница открывается, но без стилей или изображений

Проверьте пути в HTML. Для публикации используйте относительные ссылки вроде assets/chart.js, а не путь к файлу на компьютере автора.

Обновление не видно

Сравните содержимое каталога site/ и HTTP-ответ через curl. Если файл обновился, проверьте кэш браузера, прокси и встроенный кэш OnePage.

Старую версию невозможно восстановить

Значит, публикация перезаписывалась без каталога versions/ или резервной копии. Версионный каталог нужно создавать до замены рабочего файла, а не после.

Ограничения подхода

Каталоги версий решают задачу простого локального журнала изменений, но не заменяют полноценную систему контроля версий. Они не фиксируют автора, комментарий к изменению и факт согласования. Для командной работы храните версии в Git или другой системе, а Docker используйте как воспроизводимый способ запуска публикации.

Команды в статье предполагают статический HTML. Если OnePage в вашей поставке использует собственную базу данных, панель пользователей или другой путь хранения, следуйте её инструкции для volume-монтирования, резервного копирования и настройки доступа.

Итог

Надёжная публикация AI-сгенерированного дашборда начинается с простого правила: опубликованный файл должен иметь сохранённую версию, проверяемый маркер и понятную границу доступа. Docker делает запуск повторяемым, каталог версий позволяет быстро откатиться, а отдельная проверка авторизации не даёт принять случайно открытый URL за защищённую публикацию.

Больше практических сценариев смотрите в разделе с гайдами, а термины, включая версионирование, проверяйте в глоссарии.