84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
# Meilisearch in HiveGrid deployen
|
|
|
|
HiveGrid nutzt gemäß `infra/STANDARDS.md` §4 den zentralen Meilisearch im
|
|
Estate. Staging und Production bekommen keinen eigenen Meilisearch-Service in
|
|
Coolify. Der zentrale Dienst ist ausschließlich über das WireGuard-Mesh
|
|
erreichbar und wird von der Estate-Infrastruktur betrieben und gesichert.
|
|
|
|
Lokale Entwicklung kann weiterhin den Service aus `docker-compose.yml`
|
|
verwenden. Der Anwendungs- und Tenant-Vertrag steht in
|
|
`docs/features/search.md`.
|
|
|
|
## Runtime-Vertrag
|
|
|
|
| Variable | Pflicht | Zweck |
|
|
| --------------- | ------- | ------------------------------------------------------------- |
|
|
| `MEILI_URL` | ja | Mesh-Adresse des zentralen Dienstes: `http://10.42.0.4:7700`. |
|
|
| `MEILI_API_KEY` | ja | Auf HiveGrid und `hivegrid-*`-Indizes beschränkter API-Key. |
|
|
|
|
`MEILI_MASTER_KEY` gehört niemals in eine HiveGrid-App, einen HiveGrid-Worker
|
|
oder eine HiveGrid-CI-Variable. Erstellung und Rotation des scoped API-Keys
|
|
erfolgen mit dem Master-Key ausschließlich auf der Estate-Control-Ebene.
|
|
|
|
Die Runtime-Variablen müssen mindestens auf `hivegrid-web`, `hivegrid-api` und
|
|
`worker-general` identisch gesetzt sein. Der Mesh-Endpunkt darf nicht über
|
|
einen öffentlichen Port oder Proxy veröffentlicht werden.
|
|
|
|
## Index-Namespace
|
|
|
|
Registry-Schemas, Outbox-Payloads, CLI-Parameter und Worker-Pager verwenden
|
|
weiterhin logische Namen wie `projects` oder `crm-contacts`. Erst der Adapter
|
|
in `@hivegrid/search` bildet diese zentral auf physische Meilisearch-UIDs ab:
|
|
|
|
```text
|
|
logical: projects
|
|
physical: hivegrid-projects
|
|
```
|
|
|
|
Aufrufer dürfen den Prefix nicht selbst ergänzen. `SearchClient.index()`
|
|
verwirft bereits physisch präfixierte Namen, damit weder doppelte Prefixes noch
|
|
ein zweiter, unpräfixierter Namespace entstehen. Der scoped API-Key muss
|
|
ausschließlich Zugriffe auf `hivegrid-*` erlauben.
|
|
|
|
## Staging-Rollout
|
|
|
|
1. Estate-Operator erstellt oder rotiert einen HiveGrid-scoped API-Key für
|
|
`hivegrid-*`; der Master-Key bleibt außerhalb der Anwendung. Der Key braucht
|
|
zusätzlich zu Index-, Dokument- und Settings-Rechten auch `tasks.get`, weil
|
|
HiveGrid jede asynchrone Mutation bis zum terminalen Status bestätigt.
|
|
2. `MEILI_URL` und `MEILI_API_KEY` auf Web, API und `worker-general` setzen.
|
|
3. Für einen Namespace-Wechsel Web zunächst mit `SEARCH_BACKEND=sql` starten.
|
|
Der Worker schreibt dabei weiter nach Meilisearch, aber kein bestehender
|
|
Tenant liest aus einem unvollständig befüllten Index.
|
|
4. Alle drei Ressourcen mit demselben geprüften Image-SHA deployen. Der
|
|
General-Worker legt alle registrierten `hivegrid-*`-Indizes an und bestätigt
|
|
ihre Settings, bevor er den ersten Search-Job annimmt. Schlägt das fehl,
|
|
beendet er den Start fail-closed.
|
|
5. `/health` beziehungsweise `/readyz` und die Worker-Logs prüfen, ohne Keys
|
|
oder Verbindungs-URLs auszugeben.
|
|
6. Für jeden bestehenden Tenant alle unterstützten Registry-Indizes neu
|
|
aufbauen. Nicht durch Bulk-Pager abgedeckte Indizes müssen über ihre
|
|
jeweiligen Source-of-Truth-Projektionen vollständig replayed werden.
|
|
7. Dokumentanzahl und Tenant-Isolation je Index verifizieren. Erst wenn alle
|
|
acht Indizes vollständig sind, `SEARCH_BACKEND=meilisearch` auf Web setzen
|
|
und erneut deployen. Bis dahin bleibt SQL der explizite Read-Pfad.
|
|
|
|
Der Demo-Pro-Seed verifiziert seinen eigenen Tenant vollständig in allen acht
|
|
Indizes. Das ersetzt keinen Backfill anderer Staging-Tenants und ist daher kein
|
|
Signal, das globale Read-Gate vorzeitig umzuschalten.
|
|
|
|
## Disaster Recovery
|
|
|
|
Postgres bleibt die Source of Truth. Ein Rebuild wird ausschließlich über
|
|
logische Namen und Outbox-Events gestartet:
|
|
|
|
```bash
|
|
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all
|
|
```
|
|
|
|
Der `search-indexer` konsumiert die Events und schreibt über den zentralen
|
|
Adapter in `hivegrid-*`. `--index=all` umfasst nur Indizes mit registriertem
|
|
Bulk-Pager; nicht unterstützte Projektionen werden abgewiesen. Snapshot,
|
|
Restore, Retention und Master-Key-Rotation des zentralen Dienstes gehören in
|
|
die Runbooks des `infra/`-Repos und werden nicht in HiveGrid dupliziert.
|