架构概览¶

KanjiIQ采用多容器Pod架构，部署在Kubernetes上。前端和后端作为同一Pod内的独立容器运行，通过localhost通信。

系统架构图¶

graph TB
    subgraph Internet
        U[User Browser]
    end

    subgraph Hetzner["Hetzner k3s Cluster"]
        subgraph NS["Namespace: jlpt-kanji"]
            T[Traefik Ingress Controller]

            subgraph Pod["Application Pod (x2 replicas)"]
                FE[Flutter Web<br/>Nginx :80]
                BE[Dart Frog API<br/>:8080]
            end

            PG[(PostgreSQL 15<br/>PVC)]

            subgraph Middleware["Traefik Middlewares"]
                RL[Rate Limiting]
                SH[Security Headers]
            end
        end

        CM[cert-manager<br/>Let's Encrypt]
    end

    U -->|HTTPS| T
    T --> Middleware
    Middleware -->|kanjiiq.com| FE
    Middleware -->|api.kanjiiq.com| BE
    FE -->|/api/ proxy| BE
    BE --> PG
    CM -->|TLS Certificates| T

域名架构¶

域名	服务	用途
`kanjiiq.com`	前端 (Nginx)	Flutter Web应用
`www.kanjiiq.com`	前端 (Nginx)	重定向到主域名
`api.kanjiiq.com`	后端 (Dart Frog)	REST API
`admin.kanjiiq.com`	后端 (Dart Frog)	管理后台API
`docs.kanjiiq.app`	文档 (Nginx)	本文档站点

多容器Pod设计¶

应用以单个Kubernetes Deployment运行，包含2个副本，每个副本包含两个容器：

# Simplified view of k8s/05-deployment.yaml
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: backend    # Dart Frog API on :8080
        - name: frontend   # Nginx serving Flutter Web on :80

为什么采用多容器Pod？

前端Nginx将/api/请求代理到localhost:8080（后端），避免跨域问题
两个容器一起扩缩容——每个副本都是完整的、自包含的单元
简化网络：前端到后端的通信在Pod内部完成

组件摘要¶

前端¶

框架: Flutter Web，采用Material Design 3
服务: Nginx Alpine（非root用户，UID 1000）
状态管理: Provider
路由: GoRouter
离线支持: 本地SQLite缓存，支持后台同步

后端¶

框架: Dart Frog 1.1.0
认证: JWT（用于管理端点）
安全: 多层中间件栈（IP封锁、路径检测、速率限制）
翻译: OpenAI API，用于动态内容翻译

数据库¶

引擎: PostgreSQL 15
存储: Kubernetes PersistentVolumeClaim (10Gi)
模式: JSONB列，用于多语言内容存储
主键: UUID

基础设施¶

集群: k3s，运行在Hetzner专用服务器上
Ingress: Traefik，支持自动HTTPS
TLS: cert-manager + Let's Encrypt
CI/CD: Forgejo Actions（自托管）
镜像仓库: Forgejo Container Registry

安全层级¶

KanjiIQ通过多层安全机制实现纵深防御：

graph LR
    R[Request] --> L1[Traefik<br/>Rate Limiting]
    L1 --> L2[Traefik<br/>Security Headers]
    L2 --> L3[App: IP<br/>Blocklist Check]
    L3 --> L4[App: Malicious<br/>Path Detection]
    L4 --> L5[App: SQL Injection<br/>Detection]
    L5 --> L6[App: Regional<br/>Analytics]
    L6 --> H[Request Handler]

基础设施层（Traefik）：速率限制（公共100请求/分钟，管理50请求/分钟）和安全头（HSTS、X-Frame-Options、CSP）
应用层（Dart Frog中间件）：IP封锁列表、恶意路径检测（.env、.php、配置文件）、SQL注入模式、路径遍历防护
分析层：区域请求跟踪，24小时内3次可疑请求后自动封锁

详见后端架构了解中间件栈详情。