Коннекторы и переиндексация

Индекс поддерживают в актуальном состоянии две операции: коннекторы приносят документы извне, переиндексация перестраивает коллекцию, когда меняется схема, а не содержимое.

КоннекторыCopy Anchor Link

Коннектор — это сохранённый источник плюс отображение полей. Настраивается в консоли (Search → Connectors) и запускается вручную или по интервалу. Типов четыре:

НастройкиCopy Anchor Link

Каждый импортированный документ получает source_type равный типу коннектора, поэтому неудачный запуск легко откатить:

curl -sS -X DELETE "$AAC_API/indexes/documentation/documents" \
  -H "Authorization: Bearer $AAC_KEY" \
  -G --data-urlencode "filter_by=source_type:=sitemap"

Защитные механизмыCopy Anchor Link

• Защита от SSRF. URL коннектора разрешается до загрузки; loopback, link-local, приватные диапазоны и адреса метаданных отклоняются, в том числе IPv6-формы со встроенным таким IPv4, а соединение идёт именно на проверенный адрес (DNS rebinding не проходит). Каждый редирект проверяется заново; учётные данные (Authorization, cookie, секретные заголовки коннектора) после редиректа на другой origin не отправляются. SEARCH_ALLOW_PRIVATE_URLS=true отключает проверку адреса для локальной разработки; в production флаг игнорируется.
• Секреты привязаны к адресу. Сохранённые секреты показываются как *** и хранятся зашифрованными. При смене URL, домена или хоста коннектора секреты нужно ввести заново (CREDENTIALS_REQUIRED), чтобы сохранённый пароль не ушёл на новый хост. Зашифрованное значение enc:…, вставленное как секрет, отклоняется (INVALID_SECRET_VALUE).
• Контрольные суммы. Содержимое каждого документа хешируется и сравнивается с сохранённым хешем, поэтому ночной запуск переимпортирует только изменившееся — разница между 40 000 записей и 40.
• Отказ по документу. Документ, который движок не принял, попадает в очередь мёртвых писем, а не обрывает запуск.
• Ограничения. maxDocuments ограничивает запуск, лимит 5 МБ — память.

Мёртвые письмаCopy Anchor Link

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

Запуск задачCopy Anchor Link

Планировщик выполняет коннекторы, агрегацию аналитики, ретенцию и снимки. Чтобы запустить цикл немедленно — из CI или из внешнего воркера в развёртывании без внутреннего таймера, — используйте админ-эндпоинт. Это операция оператора платформы: кроме API-ключа нужен заголовок x-platform-admin-token со значением SEARCH_PLATFORM_ADMIN_TOKEN развёртывания (иначе 403):

curl -sS -X POST "$AAC_API/admin/jobs/run?job=connectors" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "x-platform-admin-token: $AAC_PLATFORM_ADMIN_TOKEN"

{
	"job": "connectors",
	"result": { "connectors": "ok" },
	"request_id": "req_5b7d9f1a3c5e7b9d1f3a5c7e"
}

job принимает connectors, rollup, retention, snapshot, graph или all. Любое другое значение — 422 INVALID_QUERY с сообщением job must be connectors|rollup|retention|snapshot|graph|all. Запуск пишется в журнал аудита. В result ключи соответствуют выполненной работе: connectors в том же цикле удаляет документы с истёкшим expires_at, rollup сообщает, сколько строк агрегировал, retention — сколько удалил, snapshot — статус резервной копии движка.

ПереиндексацияCopy Anchor Link

Поисковый сервис не умеет удалять или менять тип поля на месте, а некоторые настройки принимаются только при создании. Такие изменения требуют перестройки. POST /indexes/{slug}/reindex делает это без простоя:

1. Создаётся теневая коллекция <alias>_v<n+1> с текущей схемой и настройками.
2. Документы переливаются из живой коллекции в теневую.
3. Синонимы и курирование воспроизводятся на теневой коллекции.
4. Алиас атомарно переключается.
5. Старая коллекция сохраняется как коллекция отката задачи (планировщик удаляет её через SEARCH_ROLLBACK_RETENTION_DAYS, по умолчанию 7 дней), а строка SearchSchemaMigration фиксирует произошедшее.

Поиск идёт через алиас, поэтому окна, в котором запрос видит полузаполненную коллекцию, не существует: текущие запросы обслуживает старая коллекция до самого переключения.

curl -sS -X POST "$AAC_API/indexes/documentation/reindex" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"index": "documentation",
	"job_id": "job_01HZYC4M",
	"status": "queued",
	"status_url": "/api/v1/jobs/job_01HZYC4M",
	"request_id": "req_2f4a6c8e0b2d4f6a8c0e2b4d"
}

Ответ — 202 Accepted: перестройка идёт фоновой задачей. Опрашивайте GET /jobs/{jobId} (см. Задачи): там phase, progress, а после completed — result.documents и result.duration_ms. Повторный reindex того же индекса, пока активен первый, — 409 JOB_CONFLICT.

Требования и ограниченияCopy Anchor Link

• Право settings:write.
• Функция тарифа reindex: на Free её нет, на Pro и Enterprise есть.
• Операция выполняется задачей планировщика, а не внутри HTTP-запроса. Если воркер упал, задача подхватывается снова после истечения lease. ?sync=true блокирует запрос до конца перестройки и предназначен только для тестов.
• Документы берутся из живой коллекции движка, а не из Postgres, поэтому всё, что проиндексировано в обход платформы, сохраняется.

Когда нужна переиндексацияCopy Anchor Link

Проверка результатаCopy Anchor Link

curl -sS "$AAC_API/indexes/documentation/stats" -H "Authorization: Bearer $AAC_KEY"

Сравните documents с числом до переиндексации и посмотрите на queries_24h и avg_latency_24h_ms на предмет регрессии. Пословный diff доступен в представлении схемы консоли: оно показывает поля живой коллекции так, как их отдаёт движок.