部署指南

本文档涵盖 AuthNexus 的生产环境部署，从硬件选型到系统服务配置。

硬件建议

Control Plane

规模	CPU	内存	磁盘	说明
小型（≤10 节点）	2 核	4 GB	20 GB SSD	SQLite 即可
中型（10-50 节点）	4 核	8 GB	50 GB SSD	建议 PostgreSQL
大型（50+ 节点）	8+ 核	16+ GB	100+ GB SSD	PostgreSQL + 独立 DB 服务器

Server App（业务节点）

并发连接数	CPU	内存	说明
≤1,000	2 核	2 GB	轻量部署
1,000-10,000	4 核	4 GB	中等负载
10,000-50,000	8 核	8 GB	高并发
50,000+	16+ 核	16+ GB	需要多节点负载均衡

业务节点的内存消耗主要来自 TLS 连接上下文（约 50KB/连接）和会话状态。

端口规划

端口	服务	协议	默认绑定	用途
8080	Control Plane Admin	HTTP	`127.0.0.1`	管理后台 API
9091	Control Plane CP	mTLS HTTP	`0.0.0.0`	南向接口 + SSE
9092	Control Plane OCSP	Plain HTTP	`0.0.0.0`	OCSP 响应器
可配置	Server App TCP	mTLS TCP	`0.0.0.0`	SDK 业务连接

Admin 端口安全

Admin HTTP 默认仅监听 127.0.0.1（loopback）。切勿将 Admin 端口直接暴露到公网。生产环境必须通过反向代理访问。

数据库选型与配置

SQLite 部署（单机轻量）

SQLite 为默认数据库后端，无需额外安装：

Control DB 和 Runtime DB 各一个文件
适合单节点或小规模部署
零运维成本
性能足以支撑中小规模业务

数据库文件默认位于可执行文件同目录。建议配置独立的数据目录：

powershell

# Windows
.\control_plane_app.exe --db-path C:\AuthNexus\data\control.db

# Linux
./control_plane_app --db-path /var/lib/authnexus/control.db

PostgreSQL 部署（规模化）

适用于多节点、高可用场景：

powershell

# 设置环境变量
$env:AUTHNEXUS_PG_HOST = "db.example.com"
$env:AUTHNEXUS_PG_PORT = "5432"
$env:AUTHNEXUS_PG_USER = "authnexus"
$env:AUTHNEXUS_PG_PASSWORD = "your-secure-password"
$env:AUTHNEXUS_PG_DBNAME = "authnexus_control"

bash

# Linux
export AUTHNEXUS_PG_HOST=db.example.com
export AUTHNEXUS_PG_PORT=5432
export AUTHNEXUS_PG_USER=authnexus
export AUTHNEXUS_PG_PASSWORD=your-secure-password
export AUTHNEXUS_PG_DBNAME=authnexus_control

PostgreSQL 配置建议：

参数	推荐值	说明
`max_connections`	100+	根据节点数调整
`shared_buffers`	内存的 25%	缓冲池
`work_mem`	4-8 MB	排序/哈希操作内存
`wal_level`	replica	支持复制
`ssl`	on	加密传输

Schema 文件位于 schema/postgres_control_plane_schema.sql，首次启动时自动应用。

反向代理配置

Nginx 示例

Admin HTTP 通过 Nginx 反向代理对外暴露：

nginx

server {
    listen 443 ssl http2;
    server_name admin.example.com;

    ssl_certificate     /etc/nginx/ssl/admin.crt;
    ssl_certificate_key /etc/nginx/ssl/admin.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    # Admin API
    location /admin/v1/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Admin Frontend 静态文件
    location / {
        root /var/www/authnexus-admin/dist;
        try_files $uri $uri/ /index.html;
    }
}

南向接口不需要反向代理

CP 南向接口 (:9091) 和 OCSP (:9092) 由节点直接访问，已有 mTLS / OCSP 签名保护，通常不需要额外的反向代理。

线程调优

自动模式（推荐）

Server App 和 Control Plane 默认使用 --auto 模式，根据 CPU 核数自动分配线程。

Server App 自动线程表

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

SSE 池始终固定 1 线程（每节点只有一条 SSE 长连接）。

Control Plane 自动线程表

CP 通过 apply_cp_auto_threads 按核数分配 admin_threads、cp_threads、bg_threads。CP 的 SSE 相关容量由 event_thread_pool_count 控制（httplib 实际 pool = cp_thread_pool_count + event_thread_pool_count）。

手动覆盖

当自动模式不满足需求时，可手动指定各线程池大小：

powershell

# Server App
.\server_app.exe `
    -i 4 `              # IO 线程
    --logic-threads 4 `  # Logic 线程
    -d 3 `               # DB 线程
    -c 3 `               # Crypto 线程
    --cp-io 2 `          # CP IO 线程
    --bg-threads 2       # 后台线程

# Control Plane
.\control_plane_app.exe `
    --admin-threads 4 `  # Admin HTTP 线程
    --cp-threads 4 `     # CP 南向线程
    --bg-threads 2       # 后台线程

调优建议

IO 线程：通常等于 CPU 核数的一半，上限不超过 4
Logic 线程：与 IO 线程相同或略多
DB 线程：SQLite 下 1-2 个即够（写锁串行）；PostgreSQL 下可增加到 3-4
Crypto 线程：取决于认证 QPS，2-3 个通常足够
云函数线程：取决于云函数调用频率和复杂度
CP IO 线程：短任务池，2-3 个通常足够

TLS 证书准备

生产部署前需要准备以下证书文件：

反向代理 TLS

为 Admin 前端的反向代理准备 HTTPS 证书（可使用 Let's Encrypt）。

PKI 初始化

四类 CA 通过 Web 部署向导初始化，无需预先准备。向导完成后证书存储在 Control DB 中。

节点证书

每个业务节点需要：

由 cp_node_client_ca 签发的客户端证书（连接 CP）
由 tcp_server_ca 签发的服务端证书（接受 SDK 连接）

通过管理后台的节点管理页面完成 enrollment。

日志配置

生产环境

powershell

# 默认 info 级别（推荐）
.\control_plane_app.exe --log-level info
.\server_app.exe --log-level info

避免在生产环境使用 debug/trace 级别

debug 级别日志会让 Server 日志文件达到几十 MB 量级，严重影响性能并污染压测样本。仅在本地排查问题时临时启用。

日志轮转

建议配置日志轮转，避免磁盘空间耗尽：

powershell

# 通过命令行参数控制
.\server_app.exe --log-file C:\AuthNexus\logs\server.log --log-max-size 100MB

Windows 服务部署

使用 NSSM 注册服务

powershell

# 安装 NSSM (Non-Sucking Service Manager)
# 下载: https://nssm.cc/download

# 注册 Control Plane 服务
nssm install AuthNexus-CP "C:\AuthNexus\bin\control_plane_app.exe"
nssm set AuthNexus-CP AppDirectory "C:\AuthNexus\bin"
nssm set AuthNexus-CP DisplayName "AuthNexus Control Plane"
nssm set AuthNexus-CP Description "AuthNexus Control Plane Service"
nssm set AuthNexus-CP Start SERVICE_AUTO_START
nssm set AuthNexus-CP AppStdout "C:\AuthNexus\logs\cp-stdout.log"
nssm set AuthNexus-CP AppStderr "C:\AuthNexus\logs\cp-stderr.log"

# 注册 Server App 服务
nssm install AuthNexus-Server "C:\AuthNexus\bin\server_app.exe"
nssm set AuthNexus-Server AppDirectory "C:\AuthNexus\bin"
nssm set AuthNexus-Server DisplayName "AuthNexus Server"
nssm set AuthNexus-Server Description "AuthNexus Business Server Node"
nssm set AuthNexus-Server Start SERVICE_AUTO_START
nssm set AuthNexus-Server AppStdout "C:\AuthNexus\logs\server-stdout.log"
nssm set AuthNexus-Server AppStderr "C:\AuthNexus\logs\server-stderr.log"

# 启动服务
nssm start AuthNexus-CP
nssm start AuthNexus-Server

客户交付包

项目提供 scripts\start_authnexus_control_plane.bat 脚本用于客户交付场景，仅启动 CP（不创建 demo 数据）。

Linux systemd 服务

Control Plane Unit

ini

# /etc/systemd/system/authnexus-cp.service
[Unit]
Description=AuthNexus Control Plane
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=authnexus
Group=authnexus
WorkingDirectory=/opt/authnexus/bin
ExecStart=/opt/authnexus/bin/control_plane_app --log-level info
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/authnexus/data /opt/authnexus/logs

# 环境变量（PostgreSQL）
Environment=AUTHNEXUS_PG_HOST=localhost
Environment=AUTHNEXUS_PG_PORT=5432
Environment=AUTHNEXUS_PG_USER=authnexus
EnvironmentFile=-/opt/authnexus/env/cp.env

[Install]
WantedBy=multi-user.target

Server App Unit

ini

# /etc/systemd/system/authnexus-server.service
[Unit]
Description=AuthNexus Server Node
After=network.target authnexus-cp.service

[Service]
Type=simple
User=authnexus
Group=authnexus
WorkingDirectory=/opt/authnexus/bin
ExecStart=/opt/authnexus/bin/server_app --log-level info
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/authnexus/data /opt/authnexus/logs

[Install]
WantedBy=multi-user.target

启停管理

bash

# 启动
sudo systemctl start authnexus-cp
sudo systemctl start authnexus-server

# 开机自启
sudo systemctl enable authnexus-cp
sudo systemctl enable authnexus-server

# 查看状态
sudo systemctl status authnexus-cp
sudo systemctl status authnexus-server

# 查看日志
sudo journalctl -u authnexus-cp -f
sudo journalctl -u authnexus-server -f

部署检查清单

生产上线前请确认以下事项：

[ ] 四类 CA 已通过 Web 向导完成初始化
[ ] 所有业务节点已完成证书 enrollment
[ ] Admin HTTP 仅监听 loopback，已配置反向代理
[ ] 反向代理已启用 HTTPS
[ ] PostgreSQL 已配置并测试连接（如使用）
[ ] 日志级别设为 info（非 debug/trace）
[ ] 日志轮转已配置
[ ] 防火墙已开放必要端口（9091、9092、业务 TCP）
[ ] 防火墙已封堵 Admin 端口对外访问（8080）
[ ] 系统服务已注册并设为开机自启
[ ] 数据目录有足够磁盘空间
[ ] 已运行 E2E 测试验证功能正常

下一步

快速开始 — 开发环境搭建
系统架构 — 架构概览
安全模型 — 安全配置详解

部署指南 ​

硬件建议 ​

Control Plane ​

Server App（业务节点） ​

端口规划 ​

数据库选型与配置 ​

SQLite 部署（单机轻量） ​

PostgreSQL 部署（规模化） ​

反向代理配置 ​

Nginx 示例 ​

线程调优 ​

自动模式（推荐） ​

Server App 自动线程表 ​

Control Plane 自动线程表 ​

手动覆盖 ​

调优建议 ​

TLS 证书准备 ​

反向代理 TLS ​

PKI 初始化 ​

节点证书 ​

日志配置 ​

生产环境 ​

日志轮转 ​

Windows 服务部署 ​

使用 NSSM 注册服务 ​

客户交付包 ​

Linux systemd 服务 ​

Control Plane Unit ​

Server App Unit ​

启停管理 ​

部署检查清单 ​

下一步 ​

部署指南

硬件建议

Control Plane

Server App（业务节点）

端口规划

数据库选型与配置

SQLite 部署（单机轻量）

PostgreSQL 部署（规模化）

反向代理配置

Nginx 示例

线程调优

自动模式（推荐）

Server App 自动线程表

Control Plane 自动线程表

手动覆盖

调优建议

TLS 证书准备

反向代理 TLS

PKI 初始化

节点证书

日志配置

生产环境

日志轮转

Windows 服务部署

使用 NSSM 注册服务

客户交付包

Linux systemd 服务

Control Plane Unit

Server App Unit

启停管理

部署检查清单

下一步