7.1 KiB
% Ghid de instalare și operare — DiDi Lot 2 (Backend) % PNRR DIGI150 · contract 11.1.i3.c9
1. Precondiții
Software
- Docker ≥ 24 și Docker Compose v2 (
docker compose version). git,curl,bash. Fără dependențe de rețea externă pentru pornirea backend-ului.
Hardware (recomandat, per mașină backend)
- 8 vCPU, 16 GB RAM, 50 GB disc liber (fără modelele AI, care rulează pe Lotul 1).
Rețea
- Backendul rulează self-contained. Pentru analiza AI reală, mașina trebuie să poată accesa
serviciile Lotului 1 (platforma AI) prin URL-urile configurate în
.env(vezi §5).
2. Conținutul arhivei livrate
backend/
├── production/
│ ├── build-local.sh ← scriptul principal de instalare
│ └── .env.example ← șablon variabile (Redis/Keycloak/Kong)
├── services/
│ ├── data-layer/ ← PostgreSQL + Redis + RabbitMQ + MinIO + Keycloak
│ │ └── didiDatabase/DIDI_full_export_2026-07-02.sql ← seed baza de date
│ ├── gateway-auth-layer/ ← Kong + Keycloak (config + realm)
│ └── orchestration-layer/
│ ├── agent-v3/ ← motorul de analiză (+ .env.example)
│ └── didiFramework/ ← CRUD parametri (+ .env.example)
├── admin-dashboard/ ← interfața administrativă React
├── observability/ ← Prometheus/Grafana/Loki/OTel
└── docs/ ← acest ghid + arhitectură + raport testare
Seed-ul bazei de date (
DIDI_full_export_2026-07-02.sql, ~23 MB) trebuie să fie prezent înservices/data-layer/didiDatabase/înainte de instalare. Conține schema completă + datele + toate migrațiile.
3. Pași de instalare
Pasul 1 — Pregătește fișierele .env
Fiecare serviciu are un .env.example. Copiază-l în .env și completează secretele
(valorile marcate CHANGE_ME):
cd backend
cp services/orchestration-layer/agent-v3/.env.example services/orchestration-layer/agent-v3/.env
cp services/orchestration-layer/didiFramework/.env.example services/orchestration-layer/didiFramework/.env
cp admin-dashboard/.env.example admin-dashboard/.env
cp production/.env.example production/.env
Secrete de completat în agent-v3/.env: cheile LLM (OPENROUTER_API_KEY, OPENAI_API_KEY,
GROQ_API_KEY, opțional ANTHROPIC_API_KEY, GOOGLE_API_KEY), tokenul Whisper
(M17_WHISPER_TOKEN), cheile MinIO. URL-urile Lotului 1 se setează tot aici (vezi §5).
Pasul 2 — Rulează scriptul de instalare
cd backend/production
chmod +x build-local.sh
./build-local.sh [hostname] # implicit: hostname-ul mașinii de deployment
Scriptul ridică toată stiva în ordinea corectă:
- rețea Docker
didi-network; - stratul de date (PostgreSQL + import automat al seed-ului la primul boot, Redis, RabbitMQ, MinIO, Keycloak);
- Kong (gateway DBless);
- didiFramework + sincronizarea Redis (încarcă parametrii din PostgreSQL);
- agent-v3 + cei 13 workeri;
- admin dashboard.
Durata tipică: 5–10 minute (majoritatea = build-ul imaginilor Docker + npm install).
Pasul 3 — Verifică
La final, scriptul afișează un rezumat de health checks. Verificare manuală:
docker exec didi-postgres pg_isready -U bos_interface
docker exec didi-framework wget -qO- http://127.0.0.1:3005/health
docker exec didi-agent-v3 wget -qO- http://localhost:24803/api/v3/health
docker exec didi-cache redis-cli -a redis123 --no-auth-warning keys 'didi:framework:*' | wc -l # aștept 8
4. Ce pornește (containere)
| Container | Rol | Port |
|---|---|---|
didi-postgres |
PostgreSQL 17 (baza de date principală) | 5432 |
didi-cache |
Redis 7 | 6379 |
staging-dataLayer-rabbitmq |
RabbitMQ 3.12 | 5672 / 15672 |
staging-dataLayer-minio |
MinIO (S3) | 9000 / 9001 |
didi-keycloak |
Keycloak (OIDC) | 28080 (/auth) |
didi-kong |
API Gateway (DBless) | 18000 / 18001 / 18443 |
didi-framework |
CRUD parametri | 3005 (intern) |
didi-agent-v3 |
motor de analiză | 24803 |
agent-v3-worker-* (×11) |
workeri componente | — |
verdict-aggregator (×2) |
agregare verdict | — |
didi-admin-local |
admin dashboard | 3081 / 3001 |
5. Configurarea Lotului 1 (platforma AI)
Agent V3 apelează serviciile AI prin URL-uri din agent-v3/.env, blocul „Lot 1 — Platforma
AI". Pe mașina unde e instalat și Lotul 1, se ajustează doar host-urile:
LLM_ROUTER_URL=http://<host-lot1>:14011 # modele LLM text + OCR
VISION_LLM_URL=http://<host-lot1>:14011 # analiză imagine
DIDI_BRAIN_URL=http://<host-lot1>:8090 # brain (verification cache + RAG)
VIDEO_ANALYSIS_URL=http://<host-lot1>:54600 # deepfake video
EXTRACTORS_URL=http://<host-lot1>:54400 # EXIF/ELA/NER/YOLO/OCR
FORENSIC_API_URL=http://<host-lot1>:8080 # forensic
M17_WHISPER_URL=http://<host-lot1>:54300/v1/audio/transcriptions # transcriere
M17_WEB_API_URL=http://<host-lot1>:51100 # web search
DOMAIN_CHECK_API_URL=http://<host-lot1>:11000/api/v1/check/check # domain check
Dacă Lotul 1 rulează pe aceeași rețea Docker, se pot folosi numele de container
(ex. http://didiAI-extractors:54400). Dacă e pe alt host, se pune IP-ul.
După modificarea .env, se reconstruiește agent-v3:
cd backend/services/orchestration-layer/agent-v3 && docker compose up -d --build
6. Operare curentă
Resincronizarea parametrilor în Redis (după orice modificare de config)
docker exec didi-framework wget -qO- --post-data='' http://127.0.0.1:3005/api/sync-redis
Reconstruirea unui serviciu
# agent-v3 + workeri
cd backend/services/orchestration-layer/agent-v3 && docker compose up -d --build
# framework
cd backend/services/orchestration-layer/didiFramework && docker compose up -d --build
Scalarea workerilor
cd backend/services/orchestration-layer/agent-v3
./scale-workers.sh status # replici + backlog live
./scale-workers.sh set worker-claims 4 # scalare manuală
./scale-workers.sh auto --apply # scalare pe metrici
Loguri
docker logs -f didi-agent-v3
docker logs -f didi-framework
Rebuild bază de date (alt host / reset)
Vezi rețeta completă în services/data-layer/didiDatabase/REBUILD.md.
7. Depanare
| Simptom | Cauză probabilă | Soluție |
|---|---|---|
| Baza DIDI e goală după build | seed absent înainte de primul boot | pune seed-ul + șterge volumul didi-postgres-data + re-rulează |
| Analize eșuează / fără rezultat LLM | chei API lipsă sau Lot 1 inaccesibil | verifică agent-v3/.env (chei + URL-uri Lot 1) |
401 pe orice cerere prin Kong |
token JWT lipsă/invalid | obține token de la Keycloak; rutele publice (waitlist, verify-email) sunt exceptate |
| Redis fără chei framework | sync-redis neexecutat | rulează comanda de sync (§6) |
| Worker „mort" tăcut | reconectare broker | workerii se re-abonează automat; verifică docker logs |
Documentul-pereche (operațional, cu inventar de scripturi): backend/BUILD_AND_SCRIPTS.md.