---
title: "Миграция документации Look Scanned How-To на VitePress с улучшенной безопасностью"
description: "Узнайте, как Look Scanned обновил инфраструктуру документации, мигрировав с Vue + Vite на VitePress, одновременно внедрив npm Trusted Publishers с OIDC для безопасной публикации пакетов без токенов."
date: 2025-12-19T07:55:33.000Z
lang: ru
source: https://lookscanned.io/ru/blog/migrating-look-scanned-how-to-to-vitepress
tags: ["vitepress", "документация", "безопасность", "cicd", "npm"]
---

# Миграция документации Look Scanned How-To на VitePress с улучшенной безопасностью

В [Look Scanned](https://lookscanned.io) мы постоянно совершенствуем нашу инфраструктуру, чтобы обеспечить лучшую документацию и более безопасные методы разработки. Сегодня мы рады поделиться подробностями о значительном обновлении нашего сайта документации How-To: миграция с пользовательского приложения Vue + Vite на VitePress, одновременно улучшая нашу безопасность CI/CD с помощью npm Trusted Publishers.

## 📚 Почему мы мигрировали на VitePress

Наш сайт документации How-To ([github.com/lookscanned/how-to](https://github.com/lookscanned/how-to)) служит комплексным руководством по использованию Look Scanned. Хотя наша предыдущая настройка Vue + Vite работала хорошо, мы признали, что VitePress будет лучшим выбором для сайта документации, ориентированного на контент.

### Что такое VitePress?

VitePress — это генератор статических сайтов, специально разработанный для документации. Построенный на основе Vite и Vue 3, он сочетает в себе лучшее из обоих миров: молниеносный опыт разработки с мощными функциями документации из коробки.

### Ключевые преимущества миграции

**🎯 Лучшая архитектура для документации**
- **Маршрутизация на основе файлов**: Каждый файл markdown автоматически становится страницей, делая организацию контента интуитивной
- **Встроенные функции документации**: Оглавление, поиск, интернационализация и многое другое предварительно настроены
- **Генерация статических сайтов**: Предварительно отрендеренный HTML обеспечивает отличное SEO и мгновенную загрузку страниц

**⚡ Улучшенный опыт разработчика**
- **Мгновенная горячая перезагрузка**: Изменения появляются немедленно во время разработки
- **Markdown в первую очередь**: Сосредоточьтесь на контенте, а не на создании компонентов
- **Поддержка компонентов Vue**: При необходимости мы все еще можем использовать пользовательские компоненты Vue внутри markdown

**🔧 Упрощенное обслуживание**
- **Более четкая структура**: Документация следует соглашениям, снижая когнитивную нагрузку для участников
- **Более стабильные сборки**: Принципиальная структура VitePress приводит к более воспроизводимым сборкам
- **Лучшее сотрудничество**: Члены команды могут вносить вклад в документацию без глубоких знаний Vue

## 🔒 Улучшенная безопасность с npm Trusted Publishers

Наряду с миграцией VitePress мы внедрили критическое улучшение безопасности: **npm Trusted Publishers с использованием аутентификации OIDC**.

### Проблема с традиционными токенами npm

Ранее для публикации пакетов в npm требовалось хранить долгоживущий `NPM_TOKEN` в секретах репозитория. У этого подхода есть несколько недостатков:

- **Риск безопасности**: Токены могут быть случайно раскрыты или скомпрометированы
- **Накладные расходы на управление**: Токены требуют ручной ротации и обновлений
- **Проблемы аудита**: Трудно отследить, кто что и когда опубликовал

### Решение: Доверенная публикация на основе OIDC

[npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers/) использует OpenID Connect (OIDC) для обеспечения безопасной публикации без токенов напрямую из GitHub Actions. Вот как это работает:

1. **Нет сохраненных секретов**: Вместо сохранения токенов GitHub Actions запрашивает краткосрочные учетные данные у npm
2. **Проверка личности**: npm проверяет, что запрос на публикацию пришел из авторизованного репозитория GitHub
3. **Автоматическое управление учетными данными**: Учетные данные автоматически выдаются и быстро истекают

### Реальные преимущества

Это изменение приносит немедленные улучшения в наш рабочий процесс разработки:

- ✅ **Больше никакого управления токенами**: Нет необходимости создавать, хранить или ротировать токены npm
- ✅ **Уменьшенная поверхность атаки**: Краткосрочные учетные данные минимизируют риск раскрытия
- ✅ **Лучшая аудитируемость**: Каждое действие публикации привязано к конкретному запуску GitHub Actions
- ✅ **Современные лучшие практики**: Соответствует принципам безопасности нулевого доверия

**Техническая заметка**: Для поддержки npm Trusted Publishers мы обновили нашу конфигурацию CI для использования Node.js `lts/*`, гарантируя, что у нас есть последняя версия npm, необходимая для аутентификации OIDC.

## 📦 График выпусков

Миграция была завершена через три релиза 19 декабря 2025 года:

- **v2.0.0**: Основная миграция с Vue + Vite на VitePress (критическое изменение)
- **v2.0.1**: Исправление CI для поддержки npm Trusted Publishers с соответствующей версией Node.js
- **v2.0.2**: Улучшение производительности путем перемещения `@fontsource/noto-mono` в devDependencies

## 🌍 Продолжение многоязычной поддержки

Важное примечание: наша документация How-To генерирует многоязычные PDF-файлы, которые всегда использовались в качестве примеров файлов в основном приложении Look Scanned (доступно на [lookscanned.io/en/scan](https://lookscanned.io/en/scan)). Эта миграция VitePress не меняет эту функциональность — она просто обеспечивает лучшую основу для поддержки и улучшения нашей инфраструктуры документации.

## 💡 Что это значит для пользователей

Если вы используете документацию Look Scanned:

- **Тот же доступ, лучший опыт**: Документация остается по тому же URL с улучшенной загрузкой и навигацией
- **Более надежно**: Генерация статических сайтов означает более быструю загрузку и лучшую стабильность
- **Лучший поиск и обнаружение**: Встроенный поиск VitePress помогает быстрее найти ответы
- **Продолжение поддержки PDF**: Генерация многоязычных PDF продолжается как прежде

## 🚀 Что дальше

С завершением обновления инфраструктуры мы сосредоточились на улучшении контента:

- **Расширенные примеры использования**: Больше практических примеров и пошаговых руководств
- **Улучшения согласованности**: Уточнение многоязычной терминологии для ясности
- **Улучшенный экспорт PDF**: Улучшение опыта генерации PDF в разных браузерах

## Попробуйте Look Scanned сегодня

Look Scanned предоставляет браузерные эффекты сканирования PDF с приоритетом конфиденциальности без загрузки ваших файлов куда-либо. Улучшенная документация делает начало работы проще, чем когда-либо.

👉 **Посетите [lookscanned.io](https://lookscanned.io), чтобы испытать быстрое, безопасное сканирование документов в вашем браузере.**