Сопровождение и передача проекта Индекс

В «Индексе» готовы корпус, схема, импортёр, запрос и локальный gateway. Теперь посмотрим на проект глазами человека, которому предстоит сопровождать его после автора. Результат урока — порядок диагностики, восстановления и передачи, связанный с конкретными файлами и ограничениями. Готовность исходников отделим от успешного исполнения в выбранной среде.

Автор не запускал учебный кластер, приложения, команды импорта, тесты и замеры. Архив содержит один полный итоговый проект с фиксированными версиями и картой уроков. Для будущего наблюдения предусмотрена команда health, которая обращается к официальному Cluster Health API.

Цвет кластера и состояние библиотеки

Health показывает состояние распределения шардов. Green означает, что нужные primary и replicas назначены, yellow — что первичные копии доступны, но часть реплик не назначена, red — что есть недоступная первичная копия. Эти цвета полезны, но не показывают, насколько свежий Markdown попал в индекс и правильно ли настроен публичный запрос.

В учебной схеме один primary и ноль replicas. Поэтому green возможен при наличии только одной копии поисковых данных. Нельзя прочитать цвет как подтверждение устойчивости к потере узла. Отсутствие реплик выбрано для маленького локального примера; при рабочем развёртывании число копий и поведение при отказах требуют самостоятельного решения.

Команда для будущего выполнения читателем:

python manage.py health

Она спрашивает состояние library-read. Если alias ещё не создан или указывает не на ожидаемую версию, диагностируем метаданные назначения отдельно. Успешный ответ о состоянии существующего индекса не доказывает, что gateway использует именно его. Сначала установите цепочку имён: приложение, alias, физический индекс, версия mapping.

Свежесть проекции измеряется предметными данными

Редактор сообщает, что заголовок article-107 изменён, а поиск показывает прежний. Health при этом может быть green. Начните с исходного файла: изменена ли редакция и подготовленная проекция? Затем посмотрите манифест именно текущего физического индекса и результат последнего импорта. После этого проверьте поисковую видимость и назначение read-alias.

Поле revision помогает сопоставить карточку с исходником. Но номер сам по себе не проверяет содержимое: редактор может забыть увеличить его или случайно повторно использовать номер. content_hash помогает импортёру обнаружить техническое изменение проекции. Вместе поля дают полезные наблюдения, но не заменяют договор редактирования и единый владелец записи.

Задержку можно описывать как время от изменения подтверждённого исходника до видимости соответствующей редакции в поиске. В нашем проекте такого измерителя нет. Поэтому не приводим придуманный показатель «индекс обновляется за секунду». Период refresh движка и общий путь доставки изменения являются разными величинами: чтение файлов и запуск импортёра тоже занимают место в этом пути.

Если сервис доступен, но релевантная статья отсутствует, состояние кластера — только начало. Возможны неверная видимость, лишний фильтр, устаревший alias, несовпадение токенов и другое условие допуска. Диагностика должна двигаться по этим причинам последовательно, иначе проблему данных легко ошибочно назвать проблемой производительности.

Отказы записи имеют разные причины

Отказ parsing или mapping обычно требует исправления документа либо схемы. Повторить тот же пакет без изменений бесполезно. Перегрузка или потеря соединения допускают другой сценарий, где исход мог быть частично успешным. Тогда стабильные _id и сохранённый старый манифест позволяют безопасно повторить проекции в рамках одного импортёра.

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

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

Сетевое ожидание ограничено, но это не универсальная защита от любых расходов. Много коротких запросов или тяжёлые агрегации тоже способны загрузить движок. В рабочем окружении понадобятся наблюдение за CPU, памятью, диском, задержками и отказами, а также ограничения входного потока. Мы не выбираем их значения по отсутствующему нагрузочному измерению.

Восстановление начинается с выбора источника

Если потерян поисковый индекс, Markdown остаётся основным источником. Создайте новый физический индекс с сохранённой схемой, импортируйте полный корпус и проверьте известные документы до переключения read-alias. Не используйте старый манифест пустого назначения: он содержит знание о прежнем месте, которое больше не соответствует действительности.

Если нужна быстрая копия существующего индекса, механизм snapshots решает отдельную задачу резервирования. Но snapshot не заменяет хранение Markdown, версии кода подготовки и схемы. Восстановленная поисковая проекция может быть корректной технически и всё же отставать от последней редакционной версии. План восстановления должен объяснять, какую свежесть ожидает читатель.

Локальное состояние импортёра также нужно понимать. Утеря манифеста приводит к полному повтору index, что допустимо при одном владельце записи, но перестаёт давать сведения об удалённых ранее идентификаторах. Для восстановления из загрязнённого индекса предпочтительнее новое пустое назначение. Попытка «досинхронизировать» неизвестный индекс по пустому манифесту не найдёт все лишние записи.

Ожидаемая схема восстановления:

Markdown + версия corpus.py + index.json
→ новое пустое library-vN
→ полный импорт без старого манифеста назначения
→ проверка идентификаторов, видимости и контрольных запросов
→ осознанное переключение aliases

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

Что передаём следующему сопровождающему

В README фиксируем версии Python и OpenSearch, формат собственного корпуса, команды, ограничения и статус not_run. Файл versions.json позволяет увидеть эти сведения без чтения всей серии. Карта уроков показывает, где введён каждый компонент; она не выдаёт общий архив за набор самостоятельных снимков этапов. Один итоговый проект развивается в объяснении постепенно.

Передаваемые границы конкретны: Unix-блокировка импортёра, один владелец записи, один shard без реплики, публичный фильтр без входа сотрудников, последовательный локальный HTTPServer и ограниченный Markdown-формат. Каждая граница связана с будущим изменением архитектуры. Не следует убирать эти сведения ради впечатления законченного production-сервиса.

Последнее упражнение — объясните два случая: green при старой редакции article-107 и отказ импорта после частично принятого пакета. Укажите наблюдения, которые различают их причины. После четырнадцати уроков у вас есть исходник поискового сервиса и понимание операций движка. Для общего устройства поиска доступен курс поиска по сайту, а для векторного маршрута — RAG и pgvector; они развивают другие задачи библиотеки.

Оглавление серии