Prepare containerized dev/prod deployment (inactive)
Add a Docker image and separate Compose projects for development and production, based on the stable main behaviour without the privacy gateway. Nothing is wired into the existing systemd deploy workflow. - One non-root image (api | ui | preflight), base image pinned by digest, dependencies from a hash-locked universal lock without torch and sentence-transformers (MiniLM is not on the runtime path) - Preflight aborts on: VECTOR_DIM != 768 or non-nomic embedding profile, implicit or cross-env collection prefix, cloud keys without explicit egress acknowledgement, missing/empty or writable vault mount - Vault is a read-only NAS bind mount without host-path autocreation; healthcheck turns unhealthy when the vault sentinel disappears - Dev runs its own Qdrant; prod reuses the existing host instance - API published on loopback only; read-only rootfs, cap_drop ALL, no-new-privileges - Dev workflow kept as an inactive template outside .gitea/workflows - Docs: operations guide and migration plan with release gates, test baseline classification, R2/R3 and privacy gateway requirements Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
0d61a9e191
commit
7a225ba2b6
18 files changed
+2864
No files matched your search
@@ -0,0 +1,138 @@
|
||||
---
|
||||
doc_type: operations_manual
|
||||
audience: devops, deployment_engineer
|
||||
scope: docker, compose, container_security, nas_mount
|
||||
status: draft
|
||||
version: 0.1.0
|
||||
context: "Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, noch keine produktive Umschaltung."
|
||||
---
|
||||
|
||||
# Container-Betrieb (Docker Compose)
|
||||
|
||||
Stand: 28.10.2026. **Status: vorbereitet, nicht aktiv.** Produktion läuft unverändert über systemd und `.gitea/workflows/deploy.yml` (siehe [Deployment Guide](04_deployment_guide.md)). Der Containerstand basiert auf dem stabilen `main`-Verhalten **ohne** Privacy Gateway.
|
||||
|
||||
## 1. Überblick
|
||||
|
||||
| | Dev | Prod |
|
||||
| --- | --- | --- |
|
||||
| Compose-Datei | `deploy/compose.dev.yml` | `deploy/compose.prod.yml` |
|
||||
| Projektname | `mindnet-dev` | `mindnet-prod` |
|
||||
| API (nur `127.0.0.1`) | 8012 | 8011 |
|
||||
| UI (Bind-Adresse konfigurierbar) | 8512 | 8511 |
|
||||
| Qdrant | eigener Container `qdrant`, Volume `mindnet-dev_qdrant` | bestehende Host-Instanz, unverändert |
|
||||
| Collection-Präfix | `mindnet_dev` (fest) | `mindnet` (env-Datei, von Preflight geprüft) |
|
||||
| Vault | Testdaten, nur lesend | NAS-Vault, nur lesend |
|
||||
| Ollama | gemeinsamer Host-Dienst | gemeinsamer Host-Dienst |
|
||||
|
||||
Die Ports kollidieren weder untereinander noch mit systemd (8001/8002/8501/8502). Dev und Prod können später parallel zu den systemd-Diensten laufen, was einen Vergleich vor der Umschaltung erlaubt.
|
||||
|
||||
Alle Dateien liegen unter `deploy/`. Dieser Ordner gehört nicht zu `DEPLOY_DIRS` des bestehenden Workflows und wird daher nicht automatisch auf den Server synchronisiert. Der alte Ordner `docker/` (MiniLM-Embed-Dienst, Port 8990) bleibt unverändert, siehe Abschnitt 8.
|
||||
|
||||
## 2. Image
|
||||
|
||||
`deploy/Dockerfile`, Build-Kontext ist das Repository-Root:
|
||||
|
||||
```bash
|
||||
docker build -f deploy/Dockerfile -t mindnet:$(git rev-parse --short HEAD) .
|
||||
```
|
||||
|
||||
- **Ein Image, drei Modi:** `api` (uvicorn, 1 Worker), `ui` (Streamlit), `preflight [--live]`.
|
||||
- **Reproduzierbar:** Basis `python:3.12-slim-bookworm` per Digest; Abhängigkeiten aus `deploy/requirements.lock` mit `--require-hashes`.
|
||||
- **Ohne torch/sentence-transformers:** Der MiniLM-Pfad (`app/embeddings.py`, `embed_router`) ist im Laufzeitcode nicht eingebunden. Embeddings kommen ausschließlich von Ollama.
|
||||
- **Nicht-root:** Nutzer `mindnet` (UID 10001). Code und Config gehören root und sind nur lesbar.
|
||||
- **Build-Kontext als Allowlist** (`/.dockerignore`): Nur `app/`, `config/`, `scripts/`, `tests/` und `deploy/` gelangen in den Build-Kontext. Ausgeschlossen bleiben `.env`-Dateien, `config/*.env`, Vault, Logs und venvs.
|
||||
- **Test-Target:** `docker build --target test …` installiert zusätzlich pytest.
|
||||
|
||||
### Lock neu erzeugen
|
||||
|
||||
Nur bewusst, z. B. bei Sicherheitsupdates, und danach die Testsuite laufen lassen:
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
uv pip compile requirements.in --universal --python-version 3.12 \
|
||||
--exclude-newer <ISO-Datum> --generate-hashes --no-header -o requirements.lock
|
||||
uv pip compile requirements-test.in --universal --python-version 3.12 \
|
||||
--exclude-newer <ISO-Datum> --generate-hashes --no-header -o requirements-test.lock
|
||||
```
|
||||
|
||||
Der aktuelle Lock wurde mit `--exclude-newer 2026-01-22` erzeugt, also dem Stand nach dem letzten `main`-Commit, den das systemd-Deploy damals per `pip install` gezogen haben dürfte. **Offen:** Abgleich mit `pip freeze` der produktiven venv auf llm-node (nur lesend, erfordert Freigabe).
|
||||
|
||||
## 3. Preflight (Abbruch statt stiller Fehler)
|
||||
|
||||
`deploy/entrypoint.py` prüft vor jedem Start und bricht mit Exit-Code 1 ab, wenn:
|
||||
|
||||
| Prüfung | Schützt vor |
|
||||
| --- | --- |
|
||||
| `MINDNET_ENV` ∈ {dev, prod}; `COLLECTION_PREFIX` explizit; Dev nur `*_dev`, Prod nie `*_dev` | Dev schreibt in Prod-Collections; stiller Default `mindnet` |
|
||||
| `VECTOR_DIM == 768`, Profil `embedding_expert` = ollama/`nomic-embed-text`/768, kein abweichendes `MINDNET_EMBEDDING_MODEL` | stiller Rückfall auf 384 (MiniLM) in `qdrant.py` bzw. auf das Chat-Modell als Embedding |
|
||||
| Cloud-Key gesetzt ohne `MINDNET_ALLOW_CLOUD_EGRESS=true` | unmaskierte Vault-Inhalte an OpenRouter/Gemini |
|
||||
| Vault fehlt, Sentinel nicht lesbar, Mount nicht `ro` (`statvfs` `ST_RDONLY`) | Arbeiten auf leerem NAS-Mountpunkt; Schreiben in den Vault (R2) |
|
||||
|
||||
Die Werte für Umgebung, Dimension und Vault stehen in den Compose-Dateien unter `environment` und lassen sich nicht über die env-Datei überschreiben.
|
||||
|
||||
`preflight --live` prüft zusätzlich **nur lesend** die tatsächliche Ollama-Embedding-Länge und die Vektorgröße der Collections `<prefix>_notes` und `<prefix>_chunks`:
|
||||
|
||||
```bash
|
||||
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env run --rm --no-deps api preflight --live
|
||||
```
|
||||
|
||||
## 4. Vault auf dem NAS
|
||||
|
||||
- Der Bind-Mount ist `read_only: true`, mit `create_host_path: false` (kein stilles Anlegen) und `propagation: rslave`. Ein später wieder eingehängtes NAS wird dadurch im Container sichtbar, sofern der Host-Mountpunkt `shared` ist.
|
||||
- **Sentinel:** Standard ist `_system/dictionary/edge_vocabulary.md` relativ zum Vault, einstellbar über `MINDNET_VAULT_SENTINEL`. Die Datei existiert im echten Vault bereits; am NAS muss also nichts angelegt werden. Ein Testdaten-Vault für Dev braucht sie ebenfalls.
|
||||
- **NAS beim Start nicht verfügbar:** Die API startet nicht. `restart: unless-stopped` versucht es mit Backoff weiter. Die UI hängt an der gesunden API.
|
||||
- **NAS fällt im Betrieb aus:** Der Healthcheck meldet die API als `unhealthy`. Lesende Abfragen gegen Qdrant laufen weiter. Speichern ist wegen des schreibgeschützten Mounts ohnehin ausgeschlossen. `/ingest/save` würde ohne `ro` den fehlenden Vault-Ordner per `os.makedirs` neu anlegen; genau das verhindert der Mount.
|
||||
- **Berechtigungen:** Der Container läuft als UID 10001. Der Vault muss für diese UID **lesbar** sein, z. B. über `others: r-x` oder eine passende Gruppe auf dem NAS-Export. Bei CIFS-Mounts gelten `uid`/`gid`/`file_mode` aus den Mount-Optionen des Hosts. Prüfen, ohne am NAS etwas zu ändern:
|
||||
|
||||
```bash
|
||||
mountpoint <vault-pfad>; findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS,PROPAGATION <vault-pfad>
|
||||
sudo -u '#10001' test -r <vault-pfad>/_system/dictionary/edge_vocabulary.md && echo lesbar
|
||||
```
|
||||
|
||||
## 5. Netzwerk und gemeinsame Dienste
|
||||
|
||||
Die Container erreichen Host-Dienste über `host.docker.internal` (`host-gateway`). **Voraussetzung, vor dem ersten Start auf llm-node nur lesend zu prüfen:**
|
||||
|
||||
```bash
|
||||
ss -ltnp | grep -E ':(6333|11434)\b' # Binden Qdrant/Ollama nur an 127.0.0.1?
|
||||
docker inspect qdrant --format '{{json .HostConfig.PortBindings}}'
|
||||
```
|
||||
|
||||
Sind Qdrant oder Ollama nur an `127.0.0.1` gebunden, ist der Host-Gateway nicht erreichbar. Lösungsmöglichkeiten, jede nur mit Freigabe: Ollama an die Bridge-Adresse binden (`OLLAMA_HOST`), den Prod-Container an das bestehende Docker-Netz von `qdrant` anhängen (externes Netz), oder `network_mode: host` für die API. Keine davon ist umgesetzt.
|
||||
|
||||
Die API hat keine Authentisierung und wird daher nur an `127.0.0.1` veröffentlicht. Die UI erreicht sie intern über `http://api:8000`. Für LAN-Zugriff auf die UI wird `MINDNET_UI_BIND` auf die LAN-IP des Hosts gesetzt.
|
||||
|
||||
## 6. Härtung
|
||||
|
||||
Für `api` und `ui`: `read_only`-Rootfs, `tmpfs /tmp`, `cap_drop: ALL`, `no-new-privileges`, `init`, `pids_limit`, `mem_limit`, rotierende json-Logs. Beschreibbar sind nur die Volumes `logs` (`/app/logs`) und `data` (`/app/data`). Die UI bindet `data` nur lesend ein.
|
||||
|
||||
## 7. Bedienung
|
||||
|
||||
```bash
|
||||
cp deploy/env/dev.env.example deploy/env/dev.env # ausfüllen; *.env ist git-ignoriert
|
||||
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env build
|
||||
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env run --rm --no-deps api preflight
|
||||
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env up -d --wait
|
||||
```
|
||||
|
||||
**Dev-Daten aufbauen** (nur Dev-Qdrant, Präfix fest `mindnet_dev`): Der Vault-Mount ist nur lesend; der Import liest die Dateien und schreibt ausschließlich in Qdrant.
|
||||
|
||||
```bash
|
||||
DEV="docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env"
|
||||
$DEV run --rm --no-deps api preflight && \
|
||||
$DEV run --rm --entrypoint python api -m scripts.import_markdown --vault /vault --prefix mindnet_dev --apply
|
||||
```
|
||||
|
||||
Hinweis: Ein Befehl hinter `run` ersetzt nur `CMD`; `entrypoint.py` lehnt unbekannte Modi ab. Für Skripte wird der Entrypoint deshalb mit `--entrypoint python` ersetzt. Der Preflight muss dann vorher separat laufen, wie oben gezeigt. Die übrigen Prüfungen bleiben wirksam: fester Präfix `mindnet_dev`, Dev-Qdrant und schreibgeschützter Vault.
|
||||
|
||||
**Ohne Cloud-Keys** (Prod-Standard) ruft der stabile Code für Cloud-Profile Ollama mit der Cloud-Modell-ID auf. Das scheitert zunächst und endet über `fallback_profile` bei `identity_safe` (phi3:mini). Chat funktioniert damit lokal, aber mit Verzögerung durch Fehlversuche (Review R4).
|
||||
|
||||
## 8. Altbestand `docker/` (MiniLM)
|
||||
|
||||
`docker/docker-compose.yml` und `docker/embeddings.Dockerfile` bauen einen MiniLM-Dienst (384 Dimensionen, Port 8990). Laut [Server-Handbuch](04_server_operation_manual.md) läuft `mindnet-embed` auf llm-node. Im Anwendungscode wird er nicht genutzt; außerdem verweist das Dockerfile auf `app/embed_server.py`, das im Repository nicht mehr existiert. **Nicht entfernen, bevor geprüft ist**, ob der Container auf llm-node noch läuft und von irgendetwas angesprochen wird. Grund: `deploy.yml` synchronisiert `docker/` mit `rsync --delete`; eine Löschung auf `main` entfernt die Dateien auch auf dem Server.
|
||||
|
||||
## 9. Noch nicht verifiziert
|
||||
|
||||
- Kein `docker build` und kein Compose-Start: Auf der Entwicklungsmaschine ist kein Docker installiert. Verifiziert sind die Preflight-Logik, statische Compose-/Dockerfile-Zusagen (`tests/test_container_preflight.py`) und die Testsuite mit exakt den gelockten Versionen (frische venv aus dem Lock, Windows).
|
||||
- Healthcheck von `qdrant/qdrant` nutzt `bash` und `/dev/tcp`; beim ersten Dev-Build prüfen.
|
||||
- Der Abgleich mit den produktiven Paketversionen fehlt (Abschnitt 2).
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
doc_type: development_plan
|
||||
audience: developer, devops
|
||||
scope: docker_migration, release_gates, test_baseline, privacy_gateway
|
||||
status: draft
|
||||
version: 0.1.0
|
||||
context: "Migrationsplan Mindnet → Container (Dev/Prod) mit Freigabe-Gates, Testbaseline und Anforderungen an das Privacy Gateway."
|
||||
---
|
||||
|
||||
# Migrationsplan: Containerisierung
|
||||
|
||||
Stand: 28.10.2026. Betriebsdetails: [Container-Betrieb](../04_Operations/04_docker_deployment.md). Die Review-Befunde R1–R9 stehen in `05_review_2026-09-25.md` auf dem Branch `codex/privacy-gateway`. Der Link funktioniert erst, wenn beide Stände in `develop` zusammengeführt sind.
|
||||
|
||||
## 1. Rahmenbedingungen (entschieden)
|
||||
|
||||
- Ziel-Host bleibt vorerst `llm-node`; nichts ist auf diesen Host oder auf lokale Python-Umgebungen zugeschnitten.
|
||||
- Ollama und GLiNER sind gemeinsame Dienste pro Host. Dev und Prod haben getrennte Konfiguration, Volumes und Compose-Projekte.
|
||||
- Die produktive Qdrant-Instanz bleibt unverändert; Dev hat eine eigene Instanz.
|
||||
- Embeddings: `nomic-embed-text`, 768 Dimensionen. Ein Rückfall auf MiniLM/384 wird technisch verhindert.
|
||||
- Vault vom NAS, nur lesend. Dev bekommt Testdaten. Prod-Schreibzugriff bleibt gesperrt, bis R2 behoben ist.
|
||||
- Containerisierung und Privacy Gateway sind getrennt. Keine echten Vault-Inhalte an Cloud-Anbieter.
|
||||
|
||||
## 2. Befunde aus Phase 0
|
||||
|
||||
| Befund | Auswirkung |
|
||||
| --- | --- |
|
||||
| **Gitea-Repo `Lars/mindnet` ist öffentlich** (`private: false`, anonymes `git ls-remote` möglich) | Push der Gateway-Arbeit **nicht** durchgeführt. Sicherung nur lokal (Commits + Bundle). |
|
||||
| Push auf `main` löst `.gitea/workflows/deploy.yml` aus: `rsync --delete` von `app scripts schemas docker tests config …` nach `/home/llmadmin/mindnet` plus Neustart | Jeder Merge nach `main` ist ein Produktions-Deploy. Container-Dateien liegen deshalb in `deploy/` (nicht synchronisiert). |
|
||||
| `config/prod.env` ist versioniert; Key-Felder enthalten in allen Ständen nur Platzhalter (Länge 9/12) | Kein Leak. Datei bleibt ungenutzt; das Image schließt `config/*.env` aus. |
|
||||
| MiniLM: `app/embeddings.py` und `embed_router` sind nicht eingebunden. `docker/embeddings.Dockerfile` kopiert das nicht mehr existierende `app/embed_server.py`. `mindnet-embed` läuft laut Handbuch auf llm-node | Nicht entfernt. Abschaltung erst nach Prüfung auf llm-node (Gate G2). |
|
||||
| `qdrant.py` fällt ohne `VECTOR_DIM` auf 384 zurück; `IngestionProcessor` legt Collections beim Start an | Preflight erzwingt `VECTOR_DIM=768`. |
|
||||
| Ohne Cloud-Keys ruft der stabile Code Ollama mit Cloud-Modell-IDs auf (R4) | Chat lokal nur über Fallback-Kette; langsamer, aber ohne Egress. |
|
||||
|
||||
## 3. Branches
|
||||
|
||||
| Branch | Basis | Inhalt | Ort |
|
||||
| --- | --- | --- | --- |
|
||||
| `main` | — | Produktion (systemd, Auto-Deploy) | Gitea |
|
||||
| `develop` | `origin/main` (`0d61a9e`) | Integrationszweig nach Kansho-Muster; noch ohne Deploy | **nur lokal** |
|
||||
| `feature/containerization` | `develop` | Phase 1 | **nur lokal** |
|
||||
| `codex/privacy-gateway` | `origin/main` | Gateway (2 Commits), unverändert | **nur lokal** + Bundle |
|
||||
| `origin/SectionType` | `origin/main` | WP-26; R3 offen | Gitea |
|
||||
|
||||
Reihenfolge: `feature/containerization` → `develop`. Das Gateway folgt erst nach der Docker-Anpassung aus Abschnitt 6 und als eigener Merge. Ein Konflikt mit dem Gateway-Branch ist nicht zu erwarten: `deploy/`, `.dockerignore` und die neuen Docs/Tests sind neu, `.gitignore` nur auf dem Gateway-Branch.
|
||||
|
||||
## 4. Testbaseline (17 bestehende Fehler, kategorisiert)
|
||||
|
||||
Gleiches Ergebnis mit lokaler venv und mit einer frischen venv aus `deploy/requirements.lock`: 12 failed, 5 errors. Keiner davon wurde deaktiviert.
|
||||
|
||||
| Kategorie | Tests | Ursache | Empfehlung |
|
||||
| --- | --- | --- | --- |
|
||||
| **A – echter Produktfehler** | `test_query_text_embed_unit::test_query_with_text` | `app/routers/query.py:28` übergibt `log_search(req, res)`; Signatur ist `(query_id, query_text, results, …)`. Das Suchprotokoll für `/query` schlägt im Hintergrund fehl. | Aufruf korrigieren (eigener Fix). |
|
||||
| **A – echter Produktfehler** | `test_query_unit::test_query_hybrid_with_monkeypatch`, `test_retriever_basic::test_hybrid_retrieve_basic` | `retriever.py:401` loggt `req.query[:100]`; bei reiner Vektor-Abfrage ist `query=None` → `TypeError` → HTTP 500. | Logging `None`-sicher machen (eigener Fix). |
|
||||
| **B – veralteter Test (API umgebaut)** | `test_final_wp15_validation`, `test_smart_chunking_integration`, `test_wp15_final` (Collection-Error) | `from app.core import chunker` – Modul existiert nicht mehr (jetzt `app/core/chunking/`). | Auf neue API portieren oder bewusst archivieren. |
|
||||
| B | `test_WP22_intelligence` (4) | `EdgeRegistry(vault_root=…)` – Parameter entfernt. | Portieren. |
|
||||
| B | `test_dialog_full_flow` (2) | `save_note()` verlangt `background_tasks`. | Portieren. |
|
||||
| **C – fachlich klären** | `test_type_registry::test_defaults_when_missing` | Test erwartet `chunk_profile`, Code liefert `chunking_profile`. | Entscheiden, welcher Schlüssel gilt. |
|
||||
| C | `test_retriever_edges::test_hybrid_retrieve_uses_edge_scores` | Erwartetes Ranking (`note:2` vor `note:1`) tritt nicht ein. | Prüfen, ob Edge-Scoring regressiert oder Erwartung veraltet ist. |
|
||||
| **D – braucht Infrastruktur / falsch gepatcht** | `test_graph_unit::test_graph_neighbors` | Patcht nicht mehr die tatsächlich aufgerufene Funktion → echte Qdrant-Verbindung. | Patch korrigieren; danach Unit-Test ohne Qdrant. |
|
||||
| **E – kein pytest-Test** | `test_interview_intent::test_intent`, `test_wp06_decision::test_decision_engine` | Funktionsparameter `message`/`query` werden als Fixture interpretiert; manuelle Skripte gegen laufende Dienste. | Nach `scripts/` verschieben oder als Integrationstest mit Marker. |
|
||||
|
||||
Für eine CI-Pipeline wie bei Kansho: zuerst A beheben, B/D portieren, C entscheiden, E umziehen. Danach ist die Baseline ehrlich grün. Bis dahin sollte eine künftige Test-Pipeline nur prüfen, dass **keine neuen** Fehler gegenüber dieser Liste entstehen.
|
||||
|
||||
## 5. Freigabe-Gates
|
||||
|
||||
| Gate | Inhalt | Wer |
|
||||
| --- | --- | --- |
|
||||
| **G0** | Repo `Lars/mindnet` auf privat stellen (oder anderes privates Ziel benennen); danach Push von `codex/privacy-gateway`, `develop`, `feature/containerization` | Lars |
|
||||
| **G1** | Review dieses Stands; Merge `feature/containerization` → `develop` | Lars |
|
||||
| **G2** | **Nur lesende** Prüfungen auf llm-node: Docker-/Compose-Version, Port-Bindung Qdrant/Ollama (`ss -ltnp`), `docker ps` (läuft `mindnet-embed`?), `pip freeze` der Prod-venv, NAS-Mount (`findmnt`), Lesbarkeit für UID 10001 | Freigabe Lars |
|
||||
| **G3** | Dev-Stack auf llm-node bauen und starten (eigene Qdrant, Testdaten-Vault), `preflight --live`; Aktivierung der Workflow-Vorlage `deploy/gitea-workflows/deploy-dev.yml.example` | Freigabe Lars |
|
||||
| **G4** | Prod-Container parallel zu systemd starten (nur lesend auf Prod-Qdrant, Vault `ro`), Vergleich der Antworten | Freigabe Lars |
|
||||
| **G5** | Umschaltung Prod auf Container; systemd 2–3 Wochen als Rückfallebene; `deploy.yml` anpassen | Freigabe Lars; Voraussetzung R2, falls Schreibzugriff nötig |
|
||||
|
||||
### R2 – Pfadsicherheit beim Speichern (Pflicht vor beschreibbarem Vault)
|
||||
|
||||
`create_from_text` setzt `folder`/`filename` per `os.path.join` zusammen und schreibt ungeprüft. Die Container verhindern das derzeit nur über den schreibgeschützten Mount. Vor jedem beschreibbaren Prod-Vault: aufgelösten Zielpfad gegen den aufgelösten Vault prüfen, absolute Pfade und `..` ablehnen, Symlinks berücksichtigen, Überschreibregeln festlegen, Tests ergänzen. Zusätzlich gehört vor `/ingest/*` eine Zugriffsgrenze (Authentisierung).
|
||||
|
||||
### R3 – Section-Types (Pflichtkorrektur vor Integration von `SectionType`)
|
||||
|
||||
`_propagate_section_type_backwards` gruppiert fest auf H2 und überträgt den ersten Typ auf alle Blöcke. Zwei H3-Abschnitte mit unterschiedlichen Typen erhalten denselben Typ, und der H2-Elterntext wird umtypisiert (Reproduktion im Review). **Gesonderte Korrektur** auf dem `SectionType`-Branch mit verschachteltem Regressionstest. Erst danach Merge nach `develop`. In diesem Arbeitspaket bewusst nicht behoben.
|
||||
|
||||
## 6. Phase 2: Privacy Gateway im Container (Anforderungen)
|
||||
|
||||
Gilt für die spätere Anpassung von `require_local_endpoint` und `LocalDetector`. Grundsatz bleibt fail-closed.
|
||||
|
||||
**Zielverbindungen.** Eine Host-Allowlist mit einmaliger DNS-Auflösung reicht nicht. Zwischen Prüfung und Verbindung kann der Name auf eine andere Adresse zeigen (DNS-Rebinding), und Redirects oder Proxies können das Ziel wechseln. Anforderungen:
|
||||
|
||||
1. Allowlist erlaubter Dienste mit Name, Port und Schema (`ollama:11434`, `gliner:8090`), keine Wildcards.
|
||||
2. Auflösung **pro Verbindung**; alle aufgelösten Adressen müssen in erlaubten Netzen liegen (bevorzugt im Compose-Subnetz statt pauschal RFC1918). Sonst Abbruch.
|
||||
3. **Verbinden auf die geprüfte IP** (Pinning über eigenen httpx-Transport bzw. Resolver), Host-Header bzw. SNI bleibt der Name. Danach die tatsächliche Gegenstelle des Sockets (`getpeername`) gegen die geprüfte IP vergleichen.
|
||||
4. `follow_redirects=False`, `trust_env=False` (keine Proxies), keine URL-Credentials; Antwort-Redirects sind Fehler.
|
||||
5. Netzwerkseitig zusätzlich absichern: Detector und Ollama in einem `internal: true`-Netz ohne Internetzugang. Ausgehender Cloud-Verkehr nur aus dem API-Container und perspektivisch über einen Egress-Proxy mit Provider-Allowlist.
|
||||
6. Tests: Rebinding-Simulation (zweite Auflösung liefert öffentliche IP), Redirect-Antwort, Proxy-Variablen gesetzt, IPv6-mapped-IPv4, Link-Local/Metadaten-IP (`169.254.169.254`).
|
||||
|
||||
**Ausfall der Personenerkennung.** Cloud-Aufrufe werden blockiert (`PrivacyError`, kein Fallback). Das ist im Gateway-Branch bereits so umgesetzt.
|
||||
|
||||
**Wiederholungsmechanismus für die Ingestion (Entwurf).** Bisher bekommt eine Notiz `status: error`, wenn die Kantenvalidierung an einem `PrivacyError` scheitert. Ziel ist eine nachvollziehbare, nicht stille Wiederholung:
|
||||
|
||||
1. **Kein Teil-Commit:** Note, Chunks und explizite Kanten werden geschrieben. Kandidaten-Kanten, deren Validierung nicht möglich war, werden **nicht** verworfen und **nicht** als validiert markiert. Sie bleiben mit `validation_state: pending` und einem Reason-Code (`local_detection_failed`, `local_endpoint_required`, …) erhalten.
|
||||
2. **Persistente Warteschlange** im `data`-Volume (z. B. SQLite `data/ingest_retry.db`), Schlüssel `(note_id, content_hash)`: Versuchszähler, `next_attempt_at` mit exponentiellem Backoff, letzter Reason-Code. Keine Inhalte, nur Referenzen.
|
||||
3. **Idempotenz:** Ändert sich die Notiz, wird der alte Eintrag durch den neuen Hash ersetzt. Wiederholung verarbeitet nur die offenen Kandidaten.
|
||||
4. **Auslösung:** Zunächst **manuell** (CLI-Skript bzw. Admin-Endpoint). Ein automatischer Scheduler erst nach gesonderter Freigabe, weil er gegen Produktivdaten läuft.
|
||||
5. **Sichtbarkeit:** `/admin/stats` und Healthcheck-Details melden Anzahl `pending`/`failed`; nach `max_attempts` Status `failed` mit Reason-Code, nie stilles Verwerfen.
|
||||
6. **Tests:** Detector-Ausfall während der Ingestion → Note vorhanden, Kandidaten `pending`, Queue-Eintrag. Erneuter Lauf mit verfügbarem Detector → validiert, Eintrag entfernt.
|
||||
|
||||
## 7. Nächste Schritte
|
||||
|
||||
1. G0: Repo-Sichtbarkeit klären.
|
||||
2. G1: Review/Merge von `feature/containerization` nach `develop`.
|
||||
3. G2: lesende Prüfungen auf llm-node (Kommandos in [Container-Betrieb §4–5](../04_Operations/04_docker_deployment.md)).
|
||||
4. Fix-Pakete A (query/retriever) und R3 separat; Gateway-Anpassung nach Abschnitt 6.
|
||||
Reference in new issue
Block a user