opencode/NSCT---Neutral-Search-Crawler-Tool

Public Access

Files

NSCT Agent e9410be941 Stage 0: Repository und Architekturgrundlage

- Pyproject.toml mit FastAPI, Pydantic v2, SQLAlchemy, httpx, asyncio,
  BeautifulSoup4, selectolax, trafilatura, uvicorn, pytest-asyncio
- Multi-stage Dockerfile (Python 3.12-slim, Non-Root-User nsct)
- docker-compose.yml (nsct-api + postgres + optional searxng)
- .env.example mit allen Config-Parametern
- Config-System: AppSettings mit LLMConfig, VisionConfig, AudioConfig,
  DatabaseConfig — komplett aus Environment, keine Hardcodes
- Strukturiertes Logging mit research_id/llm_request_id Tracking
- Pydantic v2 Schemas: SearchQuery, Source, Claim, EvidenceRelation,
  CitationEdge, ResearchReport
- SQLAlchemy 2.0 Declarative Models + async Engine Factory
- SSRF-Schutz: URL-Validation, IP-Blocklist (RFC1918, Cloud Metadata,
  file://, ftp://)
- Provider-Interfaces: LLMProvider, VisionProvider, AudioProvider,
  SearchProvider, ContentFetcher als ABCs
- Health-Endpoints: /health, /ready (LLM-Connect-Test), /providers
- FastAPI App mit CORS, lifespan (LLM Pre-Flight)
- CLI-Stub mit Entry-Points: nsct, nsct-core, nsct-api
- 6 Test-Cases: /health, /ready, /providers + No-Secrets-Test
- Vollständige Dokumentation: README, ARCHITECTURE, SECURITY,
  METHODOLOGY, API, DEPLOYMENT
- .gitignore (Python, Docker, IDE, .env)

2026-08-23 11:33:45 +00:00

3.7 KiB

Raw Blame History

NSCT — Deployment-Anleitung

1. Voraussetzungen

Docker (≥ 24.0) und Docker Compose (≥ 2.23)
Mindestens 2 GB freier RAM
Zugang zu einem OpenAI-kompatiblen LLM-Endpunkt

2. Konfiguration

2.1 Environment-Datei

cp .env.example .env

Trage folgende Werte ein:

# LLM (verpflichtend)
NSCT_LLM_BASE_URL=http://192.168.80.199:8030/openai/v1
NSCT_LLM_MODEL=Qwen3.6-6-35B
NSCT_LLM_MAX_CONCURRENCY=3
NSCT_LLM_API_KEY=<dein-api-key>

# Vision (optional)
NSCT_VISION_BASE_URL=http://192.168.80.199:8030/openai/visual/v1
NSCT_VISION_MODEL=Qwen2-VL-3B

# Audio (optional)
NSCT_AUDIO_BASE_URL=http://192.168.80.199:8030/hermes-audio
NSCT_AUDIO_MODEL=default

# PostgreSQL
POSTGRES_USER=nsct
POSTGRES_PASSWORD=<starkes-passwort>
POSTGRES_DB=nsct
NSCT_DB_URL=postgresql+asyncpg://nsct:<passwort>@postgres:5432/nsct

# SearXNG (optional)
NSCT_SEARXNG_BASE_URL=http://searxng:8080

# Debug
NSCT_DEBUG=false

3. PostgreSQL Setup

Option A: Docker Compose (empfohlen)

docker compose up postgres

Die Datenbank wird automatisch erstellt. Die Credentials stehen in .env.

Option B: Externe PostgreSQL

Erstelle die Datenbank und den User manuell:

CREATE DATABASE nsct;
CREATE USER nsct WITH ENCRYPTED PASSWORD '<passwort>';
GRANT ALL PRIVILEGES ON DATABASE nsct TO nsct;

Setze NSCT_DB_URL in .env auf den externen Connection String.

4. Deployment-Schritte

4.1 Build und Start

# Vollständiger Stack (API + PostgreSQL + SearXNG)
docker compose up --build

# Nur API und PostgreSQL (kein SearXNG)
docker compose up --build nsct-api postgres

4.2 Gesundheitsprüfung

# Health check
curl http://localhost:8080/health

# Readiness check
curl http://localhost:8080/ready

# Provider-Status
curl http://localhost:8080/providers

4.3 Logs

docker compose logs -f nsct-api

5. Production-Hinweise

5.1 Sicherheit

.env niemals committen — .gitignore behandelt das
Verwende ein Secrets-Management Tool (Hashicorp Vault, AWS Secrets Manager)
API-Authentifizierung wird in Stage 2+ implementiert
Network-Policies für Docker (nur interner Traffic zwischen Services)

5.2 Skalierung

Derzeit: Single-Instance (kein horizontal scaling)
PostgreSQL: Connection Pooling über pool_size=10, max_overflow=20
LLM: Max. NSCT_LLM_MAX_CONCURRENCY parallele Requests (standard: 3)

5.3 Datenpersistenz

# docker-compose.yml
volumes:
  postgres_data:       # PostgreSQL Daten
    driver: local
  nsct_data:           # NSCT Runtime-Daten
    driver: local

Für Production: Verwende ein volumen-Plugin mit Backup-Unterstützung (например, Velero für Kubernetes).

5.4 Monitoring

# Docker Stats
docker stats nsct-api

# Container Logs (letzten 100 Zeilen)
docker compose logs --tail=100 nsct-api

# DB-Größe
docker exec -it nsct-postgres psql -U nsct -d nsct -c "SELECT pg_database_size('nsct');"

6. Troubleshooting

Problem: API startet nicht

# Logs prüfen
docker compose logs nsct-api

# Häufige Ursachen:
# 1. .env-Datei nicht vorhanden
# 2. PostgreSQL nicht erreichbar
# 3. LLM-Endpoint nicht erreichbar

Problem: PostgreSQL-Verbindung schlägt fehl

# Teste die Verbindung
docker compose exec postgres pg_isready -U nsct -d nsct

# Container-Logs prüfen
docker compose logs postgres

Problem: LLM-Provider nicht erreichbar

# Network-Ping zum LLM-Host
docker compose run --rm nsct-api curl -v http://192.168.80.199:8030/openai/v1/models

7. Update / Migration

# Neueste Version holen
git pull

# Container rebuilden
docker compose up --build -d

# Datenbank-Migrationen (wenn benötigt)
# werden in späteren Stages mit Alembic implementiert

3.7 KiB Raw Blame History