Сборка и публикация документации

Портал документации — отдельный статический пакет docs-portal. Он использует VitePress 1.6.4 и Vue 3.5.22; сборка не добавляет runtime-зависимости в приложение NGENSIA. Для воспроизводимой установки используйте pnpm 11.25.0 и зафиксированный lockfile.

Локальная проверка

Используйте Node.js 24 и pnpm 11.25.0. Из корня исходного проекта перейдите в пакет документации:

cd docs-portal
pnpm install --frozen-lockfile
pnpm build
pnpm dev

Локальный просмотр открывается по адресу http://127.0.0.1:4380/docs/. Это интерфейс разработки на компьютере оператора. Для проверки уже собранного результата используйте pnpm preview вместо pnpm dev; обе команды используют тот же локальный порт.

Готовые статические файлы находятся в content/.vitepress/dist. Перед публикацией проверьте ссылки, изображения, поиск, мобильное меню, светлую и тёмную темы. Откройте несколько вложенных страниц напрямую, а не только с главной: это выявляет неверные правила обработки URL на хостинге.

Что передавать на сервер

Публикуйте только содержимое content/.vitepress/dist. Исходные аудиты, рабочие отчёты, исходники приложения, конфигурация .env, секреты и резервные копии не входят в публичный сайт. Поиск индексирует опубликованные материалы, поэтому приватные сведения нужно исключить до сборки.

Есть два режима сборки. По умолчанию используется путь /docs/ рядом с приложением — он остаётся для локальных стендов. Для публичного адреса https://docs.ngensia.com используется режим standalone, описанный ниже: страницы и ресурсы открываются от корня сайта. Не размещайте исходники проекта в публичном каталоге.

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

Пример размещения рядом с приложением

Совместимость с обновлением приложения

Добавление /docs/ меняет Caddyfile. Новый механизм release-add / update требует точного совпадения этого файла с файлом внутри образа: образ с прежней конфигурацией будет отклонён. До следующего обновления согласуйте инфраструктурный комплект с этим маршрутом. Не удаляйте документацию и не исправляйте контрольные суммы для обхода проверки. Порядок обновления и статус механизма.

Передайте содержимое dist в новый каталог, например /srv/ngensia-docs/releases/2026-10-13. Пользователь сервиса Caddy должен иметь право читать файлы и проходить по родительским каталогам, но не изменять сборку. Если Caddy работает в контейнере, используйте доступный ему постоянный каталог и внутренний путь контейнера.

Ниже показана схема маршрутизации, не замена полного рабочего Caddyfile. Сохраните существующие защитные заголовки, лимиты, запреты внутренних URL и параметры TLS. Блок общего reverse proxy переведите в последний handle:

helpdesk.example.com {
    encode zstd gzip
    @internal path /health /health/* /version
    handle @internal {
        respond 404
    }
    redir /docs /docs/ 308
    handle_path /docs/* {
        root * /srv/ngensia-docs/releases/2026-10-13
        try_files {path} {path}.html {path}/index.html =404
        file_server
    }
    handle {
        reverse_proxy app:8080
    }
    handle_errors 404 {
        root * /srv/ngensia-docs/releases/2026-10-13
        rewrite * /404.html
        file_server
    }
}

Правило .html нужно для прямого открытия адресов без расширения. Не перенаправляйте любой неизвестный URL на главную с кодом 200: опечатка должна отдавать страницу 404. Поведение правил описано в официальной документации try_files и handle_errors.

До применения выполните caddy validate --config /etc/caddy/Caddyfile в том окружении, где работает сервис. При ошибке остановитесь. Перезагрузите конфигурацию штатным способом вашей установки Caddy; не запускайте второй экземпляр на занятых портах. Необходимы доступность DNS и согласованные TCP 80/443 для сертификата и HTTPS.

После публикации проверьте /docs/, прямой адрес /docs/operations/backup, поиск «резервная копия», увеличение скриншота и отсутствующий путь внутри /docs/ с HTTP 404. Для возврата документации укажите предыдущий сохранённый каталог в обоих root, проверьте и перезагрузите конфигурацию. Данные приложения при этом не меняются. Изменение Caddyfile учитывайте в инфраструктурном контракте следующих выпусков серверного комплекта.

Сохраните запрет служебных адресов

При добавлении handle нельзя оставлять прежний respond @internal 404 отдельной директивой вне этих блоков: порядок обработки Caddy может направить запрос в общий reverse proxy раньше запрета. Используйте отдельный handle @internal, как в примере, и после перезагрузки проверьте снаружи HTTP 404 для /health, /health/ready и /version. Доступность самой документации не заменяет эту проверку.

Публикация на docs.ngensia.com

Этот режим отделяет общедоступную справку от рабочего интерфейса NGENSIA. В DNS домена создайте запись A с именем docs и адресом сервера документации. IP берите из согласованной схемы размещения, а не из старого примера. Для сертификата должны быть доступны необходимые порты и корректно настроен DNS; если существует запись AAAA, она тоже должна вести на обслуживающий этот сайт сервер.

В каталоге docs-portal соберите отдельный пакет для корня домена:

NGENSIA_DOCS_SITE=standalone pnpm build

Это синтаксис Linux shell. В PowerShell сначала выполните $env:NGENSIA_DOCS_SITE='standalone', затем pnpm build. Настройка меняет пути ресурсов, favicon и sitemap; проверка ссылок и поиска использует тот же режим. Перед обычной локальной сборкой удалите переменную: unset NGENSIA_DOCS_SITE в Linux или Remove-Item Env:NGENSIA_DOCS_SITE в PowerShell. Не публикуйте /docs/-сборку в корень без пересборки.

Разместите готовые файлы в новом каталоге выпуска. Отдельный сайт Caddy должен раздавать только эту статику, без перенаправления запросов в API приложения. Настройте прямое открытие .html-страниц без расширения, страницу 404 и защитные заголовки. Если используется Content-Security-Policy, разрешите встроенные скрипты по SHA-256 конкретной сборки; не отключайте политику целиком ради работы поиска или темы.

Старые ссылки https://esm.ngensia.com/docs/… должны вести на ту же статью на новом домене. Пример блока внутри старого сайта Caddy:

@legacyDocs path /docs /docs/*
handle @legacyDocs {
    route {
        uri strip_prefix /docs
        redir https://docs.ngensia.com{uri} 308
    }
}

route сохраняет порядок: сначала убирается /docs, затем формируется адрес. Проверьте сохранение параметров запроса и переход к разделу статьи по #…. Общий обработчик приложения и запрет /health, /health/*, /version должны остаться на месте. Не заменяйте весь рабочий Caddyfile этим фрагментом. Правила перенаправления описаны в документации Caddy redir и uri.

До переключения сохраните прежнюю конфигурацию и сборку вне сервера. Проверьте новый Caddyfile командой caddy validate в окружении сервиса, затем примените его через штатный caddy reload. Это не требует перезапуска приложения или PostgreSQL. При ошибке верните сохранённую конфигурацию и повторите проверку; не удаляйте прежние файлы до подтверждения успешной публикации.

После переключения откройте главную, вложенную статью, поиск, скриншот и несуществующую страницу на новом домене. Проверьте действительный HTTPS-сертификат, старую ссылку со сложным путём и доступность самого приложения. Sitemap должен содержать https://docs.ngensia.com/…, а не адреса старого размещения.

Граница готовности

Успешный pnpm build подтверждает создание статического сайта. Он не подтверждает DNS, доступность внешнего сервера или фактическую публикацию. После размещения проверьте HTTPS, прямой вход на вложенную страницу, поиск, изображения и ответ для отсутствующей страницы с внешнего подключения. До этих проверок статус следует считать «сборка подготовлена», а не «сайт опубликован».

Домен и HTTPS приложения · Релизы и окружения