architecture.md

AI-Guard 架构图

系统架构

graph TB
    subgraph Client["Client / AI Agent"]
        C1["🤖 AI Agent"]
        C2["📱 App"]
    end

    subgraph Gateway["AI-Guard Gateway"]
        AUTH["🔐 Auth Middleware<br/>API Key → SHA256 Hash"]
        QUOTA_PRE["📊 Quota Pre-Check<br/>Redis Lua Atomic"]
        FW_IN["🛡️ Inbound Firewall<br/>KEYWORD / REGEX / MASK / DENY"]
        PROXY["🔄 Proxy Service<br/>Stream + Non-Stream"]
        FW_OUT["🛡️ Outbound Firewall<br/>Response Sanitization"]
        QUOTA_POST["📊 Quota Deduct<br/>Atomic Adjust"]
        AUDIT["📝 Audit Logger<br/>Two-Phase Write"]
    end

    subgraph Upstream["LLM Providers"]
        OAI["OpenAI<br/>GPT-4o"]
        ANT["Anthropic<br/>Claude"]
        ZHIPU["智谱<br/>GLM"]
    end

    subgraph Storage["Data Layer"]
        PG["🐘 PostgreSQL<br/>Tenants / Agents / Policies<br/>Audit Logs / Quotas"]
        RD["⚡ Redis<br/>Quota Counter<br/>Policy Cache"]
        ADMIN["🖥️ Admin Dashboard<br/>Next.js + Shadcn/UI"]
    end

    C1 -->|POST /v1/chat/completions| AUTH
    C2 -->|API Request| AUTH
    AUTH --> QUOTA_PRE
    QUOTA_PRE --> FW_IN
    FW_IN -->|DENY → 403| C1
    FW_IN -->|ALLOW / MASK| PROXY
    PROXY -->|SSRF Check + DNS Verify| OAI
    PROXY -->|SSRF Check + DNS Verify| ANT
    PROXY -->|SSRF Check + DNS Verify| ZHIPU
    PROXY --> FW_OUT
    FW_OUT --> QUOTA_POST
    QUOTA_POST --> AUDIT
    AUDIT --> PG
    QUOTA_PRE -.->|Atomic Deduct| RD
    QUOTA_POST -.->|Adjust| RD
    QUOTA_POST -.->|syncToDb| PG
    ADMIN -->|/api/admin/*| PG
    ADMIN -->|Policy CRUD| PG

    style Gateway fill:#1a1a2e,stroke:#e94560,color:#fff
    style Storage fill:#16213e,stroke:#0f3460,color:#fff
    style Upstream fill:#0f3460,stroke:#533483,color:#fff

Loading

请求生命周期

sequenceDiagram
    participant C as Client
    participant A as Auth
    participant Q as Quota
    participant F as Firewall
    participant P as Proxy
    participant U as Upstream LLM
    participant DB as PostgreSQL
    participant R as Redis

    C->>A: POST /v1/chat/completions
    A->>A: SHA256(apiKey) → lookup Agent
    A-->>C: 401 if invalid
    A->>Q: Pre-check quota
    Q->>R: Lua CHECK_AND_DEDUCT
    Q-->>C: 429 if exceeded
    Q->>F: Inbound firewall check
    F->>F: KEYWORD/REGEX/MASK/DENY
    F-->>C: 403 if DENY
    F->>P: Forward (replace API key)
    P->>P: SSRF validate + DNS resolve
    P->>U: Stream/Non-stream request
    U-->>P: SSE chunks / JSON response
    P->>F: Outbound firewall check
    F->>Q: Adjust quota (actual tokens)
    Q->>R: Lua ADJUST_SCRIPT
    Q->>DB: syncQuotaToDb (async)
    F->>DB: Write audit log (async)
    F-->>C: 200 OK + response

Loading

技术栈

Layer	Technology	Purpose
Gateway	Hono + Node.js	High-perf HTTP proxy
Admin	Next.js 15 + Shadcn/UI	Management dashboard
Database	PostgreSQL 17	Persistent storage
Cache	Redis 7	Quota counters + policy cache
ORM	Prisma	Type-safe DB access
Container	Docker Compose	One-command deployment