系统架构
AuthNexus 采用三进程 + 前端的分层架构，通过 mTLS 和自定义二进制协议实现安全隔离与高效通讯。
进程边界总览
┌─────────────┐ mTLS TCP（自定义二进制协议） ┌──────────────┐
│ SDK 客户端 │ ──────────────────────────────────> │ server_app │
│ (authnexus │ TLS 1.3 + 双向认证 │ (业务节点) │
│ _sdk) │ │ │
└─────────────┘ └──────┬───────┘
│
/cp/v2/* (mTLS HTTP)
│
┌─────────────┐ /admin/v1/* (HTTP) ┌──────▼───────┐
│ Admin │ ──────────────────────────────────> │control_plane │
│ Frontend │ (反向代理 / 直连) │ _app │
│ (Vue 3) │ │ (统一管理面) │
└─────────────┘ └──────────────┘三个核心进程各司其职，通过清晰定义的接口通讯，不存在直接的数据库共享。
Control Plane App（统一管理面）
Control Plane 是系统的中枢，同时承载两大职责：
Admin API (/admin/v1/*)
面向管理后台前端，提供完整的平台管理能力：
- 应用（Application）CRUD 与策略配置
- 代理（Agent）层级管理与权限分配
- 用户管理与在线状态聚合
- 卡类型与卡密管理
- 云函数与云变量管理
- 结算报表与佣金规则
- 节点管理与证书生命周期
- 仪表盘统计与审计日志
Admin HTTP 默认仅监听 127.0.0.1（loopback），生产环境通过反向代理对外暴露。
CP 南向接口 (/cp/v2/*)
面向业务节点，提供配置下发、命令调度、事件推送等管控功能。所有南向通讯均经 mTLS 双向认证保护。详见 四通道通讯。
服务层架构
Control Plane 内部按关注点分层：
| 层级 | 目录 | 职责 |
|---|---|---|
| HTTP 路由 | http/routes/ | 请求解析、参数校验、响应序列化 |
| Admin 路由 | http/admin/ | Admin API 端点实现 |
| CP 路由 | http/cp/ | 南向接口端点实现 |
| Service | service/ | 业务编排逻辑 |
| Cache | cache/ | 热数据缓存层 |
| DB | core/db/ | 数据库访问抽象 |
Server App（业务节点）
Server App 处理所有 SDK 客户端的业务请求，是系统的性能热路径。
自定义二进制协议
SDK 与 Server 之间走 TCP + TLS 1.3 + mTLS 自定义二进制协议，完全不经过 HTTP。协议实现位于 core/protocol/，业务处理位于 server/handler/。
支持的业务类型包括：
- 登录认证（密码 / 卡密）
- 心跳保活
- 卡密查询与操作
- 云函数调用
- 云变量读写
- 服务端推送
线程域模型
Server 严格划分线程域，确保不同类型的工作负载不互相干扰：
| 线程域 | 用途 | 隔离目的 |
|---|---|---|
io_threads | 网络 IO、连接协程调度、per-session strand | 网络吞吐 |
logic_threads | Handler 业务逻辑（解码、JSON、CPU 计算） | 计算密集不阻塞 IO |
db_threads | 阻塞数据库操作 | DB 延迟不影响业务 |
crypto_threads | 密码哈希、证书 CPU 密集任务 | 密码学运算隔离 |
cp_io_threads | CP HTTP 客户端短任务 burst 池 | 管控通讯独立 |
sse_pool | Channel ② SSE 长连接专用（固定 1 线程） | 长连接不占 CP IO |
cloud_function_threads | Lua 云函数执行 | 沙箱运行隔离 |
BackgroundRuntime | TaskScheduler、DeltaPuller 等后台服务 | 后台任务独立调度 |
Handler 业务通过 LogicDispatcher::dispatch() 将处理协程 spawn 到 logic 池，数据库操作通过 runtime.db().run() 派发到 db 池，密码学操作通过 runtime.crypto().run() 派发到 crypto 池。所有跨域派发基于 async::run_on() 原语。
StageRunner 分阶段初始化
Server 使用 StageRunner 模式分阶段启动，每个阶段独立函数、独立日志、独立错误传播：
logging → token_gen → DB → token_mgrs → security → caches
→ dispatcher → push → cloud_function → tcp_server
→ scheduler_tasks → config_manager → runtime_settings
→ app_policies → CP_agent → runtime_security任何阶段失败时按逆序安全清理已初始化的阶段。CP Agent Ready 必须成功绑定关键配置，否则不开放业务 TLS 端口（fail-closed）。
SDK（C++ 静态库）
authnexus_sdk 是面向客户端集成的 C++ 静态库，提供同步 API 封装。
内部线程
SDK 内部维护三个后台线程：
| 线程 | 职责 |
|---|---|
| reader | 持续读取服务端消息并分发 |
| notify | 异步通知回调（推送、状态变更等） |
| heartbeat | 定时发送心跳保活 |
TLS 验证
SDK 在 TLS 握手阶段执行严格的安全校验：
- 验证服务端证书链（
tcp_server_ca信任锚） - 验证 OCSP Stapling 响应（must-staple 策略下无 staple 直接拒绝握手）
- 校验 OCSP 时间窗（maxsec=1800s）
- 检查证书吊销状态
Admin Frontend（管理后台）
基于 Vue 3 + TypeScript + Naive UI 构建的 SPA 应用。
技术栈
- Vue 3 — Composition API
- TypeScript — 全量类型覆盖
- Naive UI — 组件库
- Vite — 构建工具
- MSW — Demo 模式的 Mock Service Worker
Demo 模式
管理后台支持完全离线的 Demo 模式，通过 MSW 在浏览器内拦截 /admin/v1 请求。Demo 模式不污染生产构建——MSW、mocks 和 seed 数据仅在 VITE_DEMO_MODE=true 时动态导入。
数据库分离
AuthNexus 使用两套完全独立的数据库：
Control DB（管控库）
由 Control Plane 独占，存储所有管理数据：
- 应用配置与策略
- 代理层级与权限
- 卡类型与卡密
- 云函数与云变量定义
- 节点注册信息
- 审计日志
- 结算数据
Schema 文件：schema/sqlite_control_plane_schema.sql 和 schema/postgres_control_plane_schema.sql。
Runtime DB（运行时库）
由 Server App 独占，存储运行时数据：
- 用户会话
- 认证令牌
- 运行时黑名单
- 认证 epoch
- 运行时安全数据
两套 DB 即使都使用 SQLite 也是两个独立的文件。数据库后端支持 SQLite（单机轻量）和 PostgreSQL（规模化部署），通过 core/db/ 的抽象层统一访问。
配置下发体系
Control Plane 通过 config_type 注册表管理配置下发，Server 通过 Channel ① 拉取并应用：
| config_type | 用途 |
|---|---|
server_runtime_settings | Server 运行时参数 |
app_policy | 应用级策略（登录限制、功能开关等） |
app_variables | 应用级云变量 |
app_client_ca_bundle | 应用客户端 CA 证书包 |
app_mtls_trust_bundle | 应用 mTLS 信任包 |
cp_agent_runtime | 节点 CP Agent 运行参数 |
配置下发流程：
- Admin 通过管理后台修改配置
- CP 记录配置变更并通过 Channel ② SSE 推送
config.pending事件 - Server 收到事件后通过 Channel ①
configs/pull拉取新配置 - Server 应用配置并通过
configs/acks批量确认 - 应用失败时通过
configs/errors上报错误
节点启动配置
节点启动时的 bootstrap 配置仍走本地 node_agent.json 文件，cp_agent_runtime 仅用于运行时参数的远程下发。