后端架构¶

KanjiIQ后端是一个Dart Frog REST API，提供闪卡内容服务、管理区域配置，并提供管理分析功能。

API结构¶

/api/v1/
├── config/
│   └── locale/[locale]              # GET - Locale configuration
├── kanji/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single kanji
│   └── random/index                 # GET - Random batch
├── vocabulary/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single vocabulary
│   └── random/index                 # GET - Random batch
└── admin/                           # Protected routes (API key required)

中间件栈¶

每个请求都经过_middleware.dart中定义的分层中间件管道处理：

graph TD
    R[Incoming Request] --> M1[ipBlocklistCheck]
    M1 -->|Blocked IP| R404[404 Response]
    M1 -->|Allowed| M2[securityMiddleware]
    M2 -->|Malicious Path| R404
    M2 -->|Clean| M3[corsHeaders]
    M3 --> M4[regionalAnalytics]
    M4 --> M5[requestLogger]
    M5 --> M6[databaseProvider]
    M6 --> H[Route Handler]

中间件详情¶

中间件	用途
`ipBlocklistCheck`	拒绝来自被封锁IP地址的请求（手动封锁 + 自动封锁）
`securityMiddleware`	封锁恶意文件扩展名探测，检测SQL注入模式，防止路径遍历
`corsHeaders`	为跨域请求添加CORS头
`regionalAnalytics`	跟踪请求来源（国家、设备类型、IP哈希），标记可疑活动，自动封锁重复违规者
`requestLogger`	记录所有请求及计时信息
`databaseProvider`	初始化PostgreSQL连接池

管理中间件¶

管理路由（/api/v1/admin/*）有额外保护：

通过X-API-Key头进行API密钥认证
更严格的速率限制（通过Traefik限制50请求/分钟）
免于自动封锁（防止将管理员锁定在外）

数据库连接¶

后端按优先级顺序解析数据库凭据：

DATABASE_URL环境变量（生产环境——从Kubernetes Secret注入）
单独的环境变量：DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASSWORD
默认值：localhost:5432

安全特性¶

恶意路径检测¶

对探测此技术栈中不存在的服务端脚本、敏感配置文件和常见框架端点的请求返回404。

自动封锁¶

分析中间件实现自动IP封锁：

每个可疑请求在regional_analytics表中被标记
当一个IP累积的可疑请求超过可配置的阈值时，自动添加到封锁列表
自动封锁在可配置的时间后过期
管理路径免于封锁，防止自我锁定

隐私合规¶

分析数据遵循GDPR/CCPA要求：

原始IP地址仅保留7天
7天后，IP被SHA-256哈希替换
国家级地理定位使用Cloudflare的CF-IPCountry头（不使用IP地理定位数据库）
用户可通过管理API请求删除数据