架构设计

整体架构

科华词元平台采用数据面 + 管理面分离的两层架构：

┌─────────────────────────────────────────────────────────────┐
│                       用户客户端                              │
│           (curl / Python SDK / JavaScript)                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   OpenResty (端口 8180)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  数据面 /v1/  │  │ 管理接口      │  │  静态资源         │   │
│  │  init.lua     │  │  admin.lua   │  │  admin-ui/ docs/ │   │
│  └──────┬───────┘  └──────┬───────┘  └──────────────────┘   │
│         │                 │                                  │
│         │ 代理转发         │ Lua 管理接口                     │
│         ▼                 ▼                                  │
│  ┌────────────────────────────────────────────────────┐      │
│  │          共享内存 (config_dict / usage_queue)       │      │
│  └────────────────────────────────────────────────────┘      │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              PHP-FPM (端口 8181)                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐   │
│  │ Controller│  │ Service  │  │ Library  │  │ Middleware  │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────────┘   │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       ▼
              ┌────────────────┐
              │     MySQL      │
              └────────────────┘

请求流转链路

数据面（用户 API 调用）

用户请求 → OpenResty (/v1/) → 鉴权 → 速率检查 → 余额检查 → 路由 → 转发到上游 AI 供应商 → 返回响应

1. 用户发送 HTTP 请求到 http://ok-link.com:10320/v1/...
2. OpenResty 解析请求路径，匹配 handler（chat、embeddings、models）
3. 验证 API Key 有效性（从 config_dict 读取）
4. 检查速率限制（rate_limit_dict）
5. 检查 Token 余额（从 config_dict 读取）
6. 根据路由规则选择上游供应商
7. 转发请求到上游 AI 服务
8. 记录用量到 usage_queue
9. 返回上游响应给用户

管理面（后台配置同步）

管理员操作 → PHP API (/admin-api/) → 写入 DB → HttpClient → OpenResty admin.lua → config_dict

1. 管理员在后台执行配置操作（新增模型、修改路由等）
2. PHP Controller 处理请求，写入 MySQL
3. PHP Service 调用 HttpClient 推送配置到 OpenResty 节点
4. OpenResty admin.lua 接收配置，写入 config_dict
5. 配置立即生效，无需重启

多节点架构

平台支持多个 OpenResty 节点组成集群，分担负载：

                    ┌──────────────┐
                    │  PHP 管理面   │
                    │  (单点)       │
                    └──────┬───────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │ OpenResty    │ │ OpenResty    │ │ OpenResty    │
   │ 节点 1       │ │ 节点 2       │ │ 节点 N       │
   │ (北京)       │ │ (上海)       │ │ (广州)       │
   └──────────────┘ └──────────────┘ └──────────────┘

• 每个节点独立运行 OpenResty，拥有完整的配置数据
• PHP 管理面统一管理所有节点，通过 HTTP 管理接口同步配置
• 用户可以选择接入任意节点，各节点配置保持一致
• 节点故障时，其他节点继续提供服务

关键技术点

技术	用途
OpenResty	高性能代理层，处理所有用户请求
Lua 共享字典	存储配置、用量队列、速率限制数据
PHP-FPM	管理后台 API 服务
MySQL	持久化存储
HMAC-SHA1	PHP → OpenResty 管理接口签名认证
Cron 同步脚本	定期从 OpenResty 拉取用量数据并同步余额