clossers/didi-lot2-backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
didi-lot2-backend/backend/services/gateway-auth-layer/didiKong/INDEX.md
EVOTECH IT SRL 8ecc78e729 livrare lot 2
2026-07-10 03:39:53 -07:00

9.2 KiB
Raw Blame History

didiKong - Index

API Gateway pentru platforma DIDI. Toate requesturile externe trec prin Kong inainte sa ajunga la serviciile backend. Gestioneaza rutare, rate limiting, CORS, SSL si headere.

Imagine: didi-kong:latest (Kong 3.9.1) Container: didi-kong (activ, pe masina de deployment)

Mod: DB-less declarativ (KONG_DATABASE=off) Porturi (doar loopback 127.0.0.1): 18000 (proxy HTTP -> container 8000), 18001 (admin API -> 8001), 18443 (proxy TLS -> 8443 ssl)

Deployment: container local DB-less (activ)

Kong ruleaza ca un singur container didi-kong pe masina de deployment, in mod DB-less (KONG_DATABASE=off). Nu exista Kong Cluster, Control Plane, Data Planes sau HAProxy, si nu exista PostgreSQL pentru Kong.

  • Config declarativa din declarative/kong.yml.didi11-local, montata in container la /kong/declarative/kong.yml.
  • Porturile sunt legate exclusiv pe loopback (127.0.0.1): proxy 18000, admin API 18001, proxy TLS 18443. Kong nu e expus public direct; traficul extern intra prin edge/tunel catre proxy-ul local.
  • Single source of truth = fisierul declarativ kong.yml.didi11-local. Orice modificare de rute/plugin-uri se face in acest fisier + reload.

Mod de operare: DB-less (declarativ)

Configuratia vine integral din fisierul declarative/kong.yml.didi11-local. Kong nu are baza de date proprie.

KONG_DATABASE=off
KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml

Nu exista mod PostgreSQL / productie separata pentru Kong: acelasi fisier declarativ este sursa unica de adevar.

Servicii inregistrate

Kong ruteaza catre 2 servicii backend (conform kong.yml.didi11-local):

Serviciu Target Status
didi-agent-v3 http://didi-agent-v3:24803 activ
didi-framework http://didi-framework:3005 activ

Nota: rutele agent-v3 au timeout mare (660s = 11 min) pentru procesarea video.

Rute definite

Agent service (activ)

Path Metode Destinatie
/agent/health GET agent-api
/agent/status GET agent-api
/api/pipelines GET agent-api
/api/analyze POST agent-api
/api/sessions GET agent-api
/api/upload POST agent-api
/api/abort POST agent-api
/api/v3/* toate agent-api (acopera si /api/v3/moderation/*)

didiFramework (config + HIL moderation)

Path Metode Destinatie
/api/* toate didiFramework (acopera /api/moderation-config, /api/sensitive-topics, /api/moderation-roles)

Nota: rutele de moderatie (HIL) calatoresc pe regulile generale /api/v3/* (agent-v3) si /api/* (didiFramework) — nu sunt necesare reguli Kong dedicate.

Notă: serviciile Python legacy orchestrator-api și analysis-api (rute /api/v1/catalog|pipelines|runs/*, /analysis/*) NU mai există în config-ul local — au fost eliminate odată cu migrarea pe agent-v3. Config-ul kong.yml.didi11-local rutează exclusiv către didi-agent-v3 și didi-framework.

Admin dashboard

Path Metode Destinatie
/admin toate admin-dashboard
/admin/api toate admin-dashboard

Plugin-uri globale

5 plugin-uri active pe toate rutele:

1. CORS

  • Origins: localhost:3000, localhost:3001, localhost:8100, * (wildcard)
  • Metode: GET, POST, PUT, DELETE, OPTIONS, PATCH
  • Headere: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Authorization, X-Request-ID
  • Exposed headers: X-Auth-Token, X-Request-ID
  • Credentials: activat
  • Max age: 3600s
  • Preflight continue: nu

2. Rate Limiting

  • 100 requests/minut per consumer
  • 2000 requests/ora per consumer
  • 10000 requests/zi per consumer
  • Politica: local (fara state distribuit)
  • Fault tolerant: da

3. Correlation ID (Request ID Tracking)

  • Header: X-Request-ID
  • Generator: UUID
  • Echo downstream: da (returnat in raspuns)

4. Request Size Limiting

  • Max payload: 100MB (pentru upload media)
  • Require content-length: nu

5. Response Transformer

  • Adauga: X-Gateway: DIDI-Kong, X-API-Version: 2.0
  • Sterge: Server, Via (ascunde detalii interne)

Upstreams (load balancing)

Config-ul local (kong.yml.didi11-local) NU definește upstream-uri — rutarea se face direct către serviciile didi-agent-v3:24803 și didi-framework:3005. Scalarea orizontală a workerilor se face la nivel de agent-v3 (scale-workers.sh), nu prin upstream-uri Kong.

SSL/TLS

  • Certificat self-signed pentru
  • Locatie: certs/server.crt, certs/server.key
  • Valabil: feb 2026 - feb 2027
  • Emitent: DIDI, Bucharest, RO
  • Servit pe proxy-ul TLS local 127.0.0.1:18443

Integrare Keycloak (LOCAL) + enforcement JWT (Modul 4 Gateway)

Kong valideaza token-urile emise de instanta Keycloak locala (didi-keycloak, port 28080, servita sub /auth). Realm-urile locale sunt didi-clients (useri finali) si didi-admins (operatori). Issuer-ele locale au forma http://localhost:28080/auth/realms/didi-clients si .../didi-admins.

Enforcement-ul se face prin pluginul Kong jwt (nu OIDC/introspection): validare de semnatura RS256 cu chei publice statice, key_claim_name: iss (Kong potriveste tokenul dupa claim-ul iss cu un jwt_secret inregistrat pe consumer).

Consumer: didi-keycloak-users — detine jwt_secrets (RS256, rsa_public_key) pentru toate issuer-ele acceptate, cheia fiind chiar valoarea iss:

  • local: http://localhost:28080/realms/didi-clients, http://localhost:28080/realms/didi-admins
  • plus issuer-ele externe/edge folosite in fata proxy-ului: https://didi365.eu/auth/realms/{didi-clients,didi-admins}, https://<sso-extern>/realms/..., https://<sso-extern>/realms/..., https://<host-local>/auth/realms/..., https://10.11.10.11:{3001,8443}/auth/realms/...

Pluginul jwt este activ pe 16 rute protejate de pe cele doua servicii (didi-agent-v3 si didi-framework), incluzand ruta /framework (route didi-framework-direct, jwt adaugat 2026-07-08). Rutele publice raman fara jwt (health/status, media public, verify-email, waitlist), iar rutele de extensie folosesc autentificare separata prin X-API-Key + rate-limiting.

JWT validation flow:

  1. Clientul (SPA/extensie) obtine token JWT de la Keycloak local (/auth/realms/didi-clients sau /auth/realms/didi-admins).
  2. Trimite request cu Authorization: Bearer {token}.
  3. Kong potriveste iss cu jwt_secret-ul consumer-ului didi-keycloak-users si valideaza semnatura RS256; token invalid/lipsa -> 401.
  4. Daca valid, ruteaza requestul catre serviciul backend local (didi-agent-v3:24803 / didi-framework).
  5. Serviciul backend decodeaza tokenul pentru user_id/email/realm_access.roles (fara re-validare — Kong a validat deja).

Configurare performanta

KONG_NGINX_WORKER_PROCESSES=auto
KONG_MEM_CACHE_SIZE=256m
KONG_NGINX_PROXY_PROXY_BUFFER_SIZE=128k
KONG_NGINX_PROXY_PROXY_BUFFERS=4 256k
KONG_NGINX_PROXY_PROXY_BUSY_BUFFERS_SIZE=256k
KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS=4 64k

Buffer-urile mari sunt necesare pentru headerele JWT de la Keycloak (token-urile pot fi foarte mari).

Fisiere

Dockerfile                       -- Imagine didi-kong (Kong 3.9), instaleaza curl, entrypoint
entrypoint.sh                    -- Pornire Kong DB-less + wait for ready + log servicii
declarative/
  kong.yml.didi11-local          -- Configurare declarativa activa (single source of truth, montata la /kong/declarative/kong.yml)
certs/
  server.crt                     -- Certificat SSL self-signed
  server.key                     -- Cheie privata SSL

Zero cod custom. Zero plugin-uri Lua custom. Doar configurare declarativa si certificat SSL.

Health check

kong health (interval 30s, timeout 10s, retries 3, start period 60s)

Consumers

Configuratia declarativa defineste un singur consumer Kong: didi-keycloak-users (username + custom_id didi-keycloak-users), care detine jwt_secrets-urile RS256 pentru toate issuer-ele Keycloak locale/edge acceptate (vezi sectiunea Integrare Keycloak). Acest consumer este cel pe care pluginul jwt il rezolva la validarea tokenului.

Limitele per-tier (free/paid/enterprise) provin din atributele de grup Keycloak (realm-urile locale didi-clients / didi-admins) si sunt disponibile in claim-urile JWT pentru rate limiting; rutele de extensie au propriul rate-limiting per X-API-Key (30/min).

Recent Changes

  • 2026-07-08 — jwt pe /framework: pluginul jwt (RS256, key_claim_name: iss) adaugat pe ruta didi-framework-direct (path /framework). Enforcement JWT acum activ pe 16 rute protejate pe didi-agent-v3 + didi-framework.
  • jwt_secrets pentru issuer-ele locale pe consumer didi-keycloak-users: http://localhost:28080/realms/didi-clients + .../didi-admins, alaturi de issuer-ele edge (didi365.eu/auth, <sso-extern>, <sso-extern>, <host-local>/auth, 10.11.10.11:{3001,8443}/auth) pentru realm-urile didi-clients si didi-admins.
  • Rute de extensie (didi-agent-extension-analyze, -async, -status, -upload): autentificare X-API-Key + rate-limiting 30/min + request-transformer; CORS extins cu origins chrome-extension://[a-z]+, moz-extension://[a-z0-9-]+ + header X-API-Key.
  • Single source of truth = declarative/kong.yml.didi11-local (DB-less). Fara cluster, fara decK sync.