188 lines
7.1 KiB
Markdown
188 lines
7.1 KiB
Markdown
% 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
|
||
> în `services/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`):
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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ă:
|
||
1. rețea Docker `didi-network`;
|
||
2. stratul de date (PostgreSQL + **import automat al seed-ului** la primul boot, Redis,
|
||
RabbitMQ, MinIO, Keycloak);
|
||
3. Kong (gateway DBless);
|
||
4. didiFramework + **sincronizarea Redis** (încarcă parametrii din PostgreSQL);
|
||
5. agent-v3 + cei 13 workeri;
|
||
6. 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ă:
|
||
|
||
```bash
|
||
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:
|
||
```bash
|
||
cd backend/services/orchestration-layer/agent-v3 && docker compose up -d --build
|
||
```
|
||
|
||
---
|
||
|
||
# 6. Operare curentă
|
||
|
||
## Resincronizarea parametrilor în Redis (după orice modificare de config)
|
||
```bash
|
||
docker exec didi-framework wget -qO- --post-data='' http://127.0.0.1:3005/api/sync-redis
|
||
```
|
||
|
||
## Reconstruirea unui serviciu
|
||
```bash
|
||
# 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
|
||
```bash
|
||
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
|
||
```bash
|
||
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`.*
|