Как обновлять и публиковать этот справочник

Эта инструкция фиксирует практический опыт публикации сайта android.rosveb.ru. Она нужна, чтобы человек или Codex могли повторить процесс без догадок и не затронуть другие сайты.

Простая схема

Исходные страницы находятся в docs/. VitePress превращает их в статический сайт. Готовые файлы копируются в отдельную папку production, а Caddy отдаёт их по HTTPS.

docs/*.md
  → npm run verify
  → docs/.vitepress/dist/
  → servers/proxy-nix/sites-static/android/
  → Caddy
  → https://android.rosveb.ru/

Локальная работа

Один раз установите зависимости:

cd ~/projects/android
corepack pnpm@10.12.1 install --frozen-lockfile

Запуск для редактирования:

npm run docs:dev

Сайт доступен только на локальном адресе, который напечатает VitePress. Перед публикацией выполните полную проверку:

npm run verify

Команда проверяет внутренние ссылки, тесты конфигурации, production-сборку, обязательные страницы, карту сайта и интерактивный граф.

Повторяемая проверка в реальном локальном Chromium запускается отдельно, потому что ей нужны свободные локальные порты 4173 и 9222:

npm run browser:smoke

Она проверяет поиск, mobile layout, доступные имена элементов, сохранение прогресса после перезагрузки и загрузку интерактивного графа.

Публикация новой сборки

Production-каталог: ~/projects/servers/proxy-nix/sites-static/android/. Он выделен только этому справочнику. Перед обновлением сохраните краткоживущую rollback-копию, затем точно синхронизируйте готовый артефакт:

mktemp -d /tmp/android-handbook-rollback.XXXXXX
cp -a ~/projects/servers/proxy-nix/sites-static/android \
  /tmp/android-handbook-rollback.<суффикс>/
rsync -a --delete docs/.vitepress/dist/ \
  ~/projects/servers/proxy-nix/sites-static/android/

Подставьте каталог, который напечатал mktemp. --delete здесь допустим только потому, что target заранее проверен, выделен одному сайту и имеет rollback-копию. Он удаляет устаревшие VitePress assets с прежними хешами. Никогда не применяйте такую команду к общему каталогу или к пути, значение которого не проверено. После копирования проверьте локальный TLS и публичные страницы; до этого rollback-копию не удаляйте.

Для уже созданного android.rosveb.ru повторно менять DNS или создавать vhost не нужно. Команда publish используется только при первоначальном создании домена или после осознанного полного отката.

Проверки после публикации

Из каталога ~/projects/servers/proxy-nix:

node cli/isp-dns.cjs get android rosveb.ru
docker compose exec -T caddy caddy validate --config /etc/caddy/Caddyfile
curl -H "Host: android.rosveb.ru" http://127.0.0.1:2000/
curl --resolve android.rosveb.ru:443:127.0.0.1 \
  https://android.rosveb.ru/

Затем с внешней сети проверяются главная, поиск, словарь, одна вложенная страница, интерактивный граф, robots.txt и sitemap.xml. Обычный запрос к публичному IP с той же машины не считается внешней проверкой из-за VPN и особенностей NAT loopback.

Откат

Если новая версия неисправна, точно синхронизируйте сохранённую rollback-копию обратно в sites-static/android/ и повторите HTTP/HTTPS проверки. DNS и Caddy при обычном откате контента не меняются. Временную копию удаляйте только после успешной внешней проверки; после перезагрузки /tmp может быть очищен.

Полностью снять новый домен можно штатной командой:

node cli/isp-dns.cjs unpublish android rosveb.ru

Она сохраняет каталог сайта. Флаг удаления каталога без отдельного точного разрешения не применяется.

Что нельзя публиковать

• keystore, пароли, токены и .env;
• service-account JSON и документы владельца;
• внутренние логи с персональными данными;
• APK/AAB и backup-файлы, если для них не выбран отдельный безопасный канал;
• непроверенные юридические утверждения от имени владельца.

Definition of Done

• corepack pnpm@10.12.1 install --frozen-lockfile воспроизводит зависимости из lock-файла;
• npm run verify проходит полностью;
• desktop и mobile страницы просмотрены в браузере;
• поиск и сохранение прогресса работают с клавиатуры;
• Caddy configuration valid;
• локальный TLS/SNI и внешний HTTPS возвращают ожидаемый контент;
• способ отката известен, чужие vhost и приложения не изменены.