快速开始

本文档引导你从零开始构建并运行 AuthNexus 系统，包括后端服务、管理前端和 SDK Demo。

环境要求

操作系统

平台	最低版本
Windows	Windows 11 / Windows Server 2022
Linux	Ubuntu 22.04 LTS+ / Debian 12+ / RHEL 9+

编译工具链

工具	最低版本	说明
MSVC	Visual Studio 2022 17.6+	Windows 平台，需启用 C++23
GCC	13.0+	Linux 平台
CMake	3.26+	构建系统
OpenSSL	3.0+	TLS / PKI / 密码学基础
Node.js	18+	管理前端构建
npm	9+	前端包管理

数据库（可选）

• SQLite：内置，无需额外安装，适合单机与轻量部署
• PostgreSQL 15+：规模化部署时使用，需提前安装并准备连接信息

获取源码

git clone https://github.com/AuroraEchos/AuthNexus.git
cd AuthNexus

构建后端

配置（首次或 CMakeLists.txt 变更后）

cmake -B build -S .

编译

推荐使用 --parallel 并行编译以加速构建：

# Release 构建（推荐）
cmake --build build --config Release --parallel

# Debug 构建（开发调试用）
cmake --build build --config Debug --parallel

# 仅构建特定目标
cmake --build build --config Release --target control_plane_app --parallel
cmake --build build --config Release --target server_app --parallel
cmake --build build --config Release --target unit_tests --parallel
cmake --build build --config Release --target sdk_demo --parallel

构建产物输出到 build/bin/<Config>/ 目录。schema/ 目录会由 POST_BUILD 步骤自动复制到可执行文件同目录。

验证构建

# 运行全量单元测试
ctest --test-dir build -C Release --output-on-failure

# 按名称筛选测试
ctest --test-dir build -C Release --output-on-failure -R "PasswordHasher|CloudFunction"

首次启动

第一步：启动 Control Plane

cd build/bin/Release
.\control_plane_app.exe

Control Plane 默认监听：

端口	用途	默认绑定
8080	Admin HTTP API (/admin/v1/*)	127.0.0.1（仅本地）
9091	CP 南向接口 (/cp/v2/*，mTLS）	0.0.0.0
9092	OCSP 响应器（Plain HTTP）	0.0.0.0

首次启动时，系统进入 setup-only 状态，不会开放 /cp/* 端口，必须先完成 PKI 初始化。

第二步：PKI 初始化（Web 部署向导）

打开浏览器访问 http://localhost:8080，系统自动跳转到部署向导页面。

向导引导你完成四类 CA 的初始化：

1. CP Server CA (cp_server_ca) — Control Plane 服务端证书
2. CP Node Client CA (cp_node_client_ca) — 业务节点访问 CP 的客户端证书
3. TCP Server CA (tcp_server_ca) — 业务 Server TCP 服务端证书
4. App Client CA (app_client_ca) — SDK/App 客户端证书

每个 CA 需设置基本参数（有效期、密钥算法等）。向导完成后系统自动签发必要证书并进入正常运行状态。

注意

四类 CA 全部初始化完成前，CP 不开放南向接口 (/cp/*)，业务节点无法接入。请务必一次性完成向导。

第三步：首次登录

PKI 初始化完成后，向导会要求创建首个 平台管理员（Platform Admin）账户。设置用户名和密码后，使用该账户登录管理后台。

登录后你可以：

• 创建应用（Application）
• 配置应用策略
• 创建代理（Agent）层级
• 管理卡类型与卡密
• 配置云函数与云变量

第四步：启动 Server App

在另一个终端启动业务节点：

cd build/bin/Release
.\server_app.exe

Server App 启动后会通过 mTLS 连接到 Control Plane 进行注册。首次启动时需要节点证书（由 PKI 系统签发，通过管理后台的节点管理页面完成 enrollment）。

Server App 使用 StageRunner 分阶段初始化，关键阶段包括：日志 -> Token -> 数据库 -> 安全模块 -> 缓存 -> TCP 服务器 -> CP Agent。任何阶段失败会按逆序安全清理。

CP Agent Ready

Server App 的 CP Agent 必须成功连接 CP 并应用关键配置后，才会开放业务 TLS 端口。这是 fail-closed 设计。

管理前端

开发模式

cd src/admin_frontend
npm install
npm run dev

开发服务器默认监听 http://localhost:3000，/admin/v1 和 /cp 请求自动代理到 :9090（可在 vite.config.ts 中调整）。

Demo 模式（无需后端）

npm run dev:demo

Demo 模式使用 MSW (Mock Service Worker) 在浏览器内拦截 API 请求，无需任何后端服务即可体验完整管理功能。

生产构建

npm run build      # 输出到 dist/
npm run build:demo # 输出到 dist-demo/，可嵌入 website

SDK Demo 连接

构建完成后可以运行 SDK Demo 验证端到端连接：

cd build/bin/Release
.\sdk_demo.exe

SDK Demo 演示基本的认证流程：

1. 连接到 Server App（TLS 1.3 + mTLS）
2. 执行登录认证
3. 维持心跳
4. 查询卡密信息
5. 调用云函数

SDK 内部自动管理三个后台线程：reader（读取服务端消息）、notify（通知回调）、heartbeat（心跳保活）。

线程自动规划

Server App 和 Control Plane App 均支持 --auto 模式（默认启用），根据 CPU 核数自动分配线程：

CPU 核数	IO	Logic	DB	Crypto	CP IO
≤2	1	1	1	1	1
≤4	2	2	1	1	1
≤8	3	3	2	2	2
>8	4	4	3	3	3

手动覆盖使用 -i/--logic-threads/-d/-c/--cp-io/--bg-threads 等参数。

下一步

• 系统架构 — 了解三进程边界与数据流
• 四通道通讯 — 深入 CP 与 Server 的通讯协议
• TLS 与 PKI — 证书体系与 mTLS 握手细节
• 部署指南 — 生产环境部署与运维