From d374796753b7b5ff10d3b3a9108efd72a1dd4288 Mon Sep 17 00:00:00 2001
From: cheney <qian.huang@sunyard.com>
Date: Fri, 10 Jul 2026 10:37:11 +0800
Subject: [PATCH] save

---
 .idea/.gitignore   |   5 +
 .idea/gateway2.iml |   9 +
 .idea/misc.xml     |  13 +
 .idea/modules.xml  |   8 +
 docs/设计.md       | 620 +++++++++++++++++++++++++++++++++++++++++++++
 docs/需求.md       |   8 +
 6 files changed, 663 insertions(+)
 create mode 100644 .idea/.gitignore
 create mode 100644 .idea/gateway2.iml
 create mode 100644 .idea/misc.xml
 create mode 100644 .idea/modules.xml
 create mode 100644 docs/设计.md
 create mode 100644 docs/需求.md

diff --git a/.idea/.gitignore b/.idea/.gitignore
new file mode 100644
index 0000000..10b731c
--- /dev/null
+++ b/.idea/.gitignore
@@ -0,0 +1,5 @@
+# 默认忽略的文件
+/shelf/
+/workspace.xml
+# 基于编辑器的 HTTP 客户端请求
+/httpRequests/
diff --git a/.idea/gateway2.iml b/.idea/gateway2.iml
new file mode 100644
index 0000000..d6ebd48
--- /dev/null
+++ b/.idea/gateway2.iml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>
\ No newline at end of file
diff --git a/.idea/misc.xml b/.idea/misc.xml
new file mode 100644
index 0000000..4b1700d
--- /dev/null
+++ b/.idea/misc.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MavenRunner">
+    <option name="environmentProperties">
+      <map>
+        <entry key="JAVA_TOOL_OPTIONS" value="-Dfile.encoding=UTF-8" />
+      </map>
+    </option>
+  </component>
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_17" default="true" project-jdk-name="ms-17" project-jdk-type="JavaSDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>
\ No newline at end of file
diff --git a/.idea/modules.xml b/.idea/modules.xml
new file mode 100644
index 0000000..aff5070
--- /dev/null
+++ b/.idea/modules.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/gateway2.iml" filepath="$PROJECT_DIR$/.idea/gateway2.iml" />
+    </modules>
+  </component>
+</project>
\ No newline at end of file
diff --git a/docs/设计.md b/docs/设计.md
new file mode 100644
index 0000000..6f4e69e
--- /dev/null
+++ b/docs/设计.md
@@ -0,0 +1,620 @@
+# 基于 Nginx 与 TongsuoSSL 的国密 SSL 网关方案
+
+## 1. 目标与范围
+
+本方案描述一个基于 Nginx 与 TongsuoSSL 的 SSL 网关程序，用于在网关入口侧支持国密算法套件，并将业务流量安全、稳定地转发到后端服务。
+
+网关重点能力如下：
+
+- 支持国密 TLS/SSL 能力，包括 SM2、SM3、SM4 及国密相关密码套件。
+- 支持端口融合，在同一个监听端口上同时兼容国密套件和国际套件。
+- 可选支持 SDF 接口对接海光 CCP，SDF 动态库通过配置外置指定。
+- 复用 Nginx 的高性能网络模型、反向代理能力、负载均衡能力和配置体系。
+- 使用 TongsuoSSL 替换或增强 Nginx 原生 OpenSSL 依赖，为 TLS 握手、证书校验、加解密提供国密能力。
+- 对外提供统一 HTTPS/GMSSL 入口，对内按策略转发 HTTP、HTTPS 或其他上游协议。
+- 将证书、密钥、路由、上游、日志、监控等职责拆分为清晰模块，便于后续实现和运维。
+
+## 2. 总体架构
+
+整体架构采用“增强版 Nginx 网关 + TongsuoSSL 加密底座 + 配置与运维支撑模块”的形式。
+
+
+
+```mermaid
+flowchart LR
+    Client["客户端<br/>浏览器、终端、SDK"] --> Listener["监听接入模块<br/>Nginx listen 与 server"]
+    Listener --> TLS["国密 TLS 处理模块<br/>TongsuoSSL"]
+    TLS --> Router["请求路由模块<br/>Nginx location、map 与 rewrite"]
+    Router --> Proxy["反向代理模块<br/>proxy 与 upstream"]
+    Proxy --> Upstream["后端业务服务"]
+
+    Config["配置管理模块"] --> Listener
+    Config --> TLS
+    Config --> Router
+    Config --> Proxy
+
+    Cert["证书密钥管理模块"] --> TLS
+    SDF["SDF 适配模块<br/>海光 CCP 动态库"] --> TLS
+    SDF --> Cert
+
+    %% 日志模块从各组件收集数据（箭头指向 Log）
+    Listener --> Log["日志审计模块"]
+    TLS --> Log
+    Router --> Log
+    Proxy --> Log
+
+    %% 监控模块从各组件收集数据（箭头指向 Monitor）
+    Listener --> Monitor["监控告警模块"]
+    TLS --> Monitor
+    Proxy --> Monitor
+```
+
+核心关系说明：
+
+- Nginx 是网关主进程与流量调度核心，负责监听端口、解析请求、路由匹配、负载均衡和反向代理。
+- TongsuoSSL 是 TLS/SSL 能力提供方，嵌入 Nginx SSL 模块调用链中，负责国密握手、国际 TLS 握手、密码套件协商、证书链校验和数据加解密。
+- 配置管理模块以 Nginx 配置为主，统一描述监听、端口融合、证书、密码套件、SDF 动态库、路由、上游和日志策略。
+- 证书密钥管理模块向 TLS 处理模块提供签名证书、加密证书、国际证书、私钥、CA 链和吊销信息。
+- 日志审计与监控告警模块不直接参与转发决策，主要消费各模块运行状态和请求结果。
+
+## 3. 模块职责
+
+### 3.1 监听接入模块
+
+职责：
+
+- 基于 Nginx `server` 与 `listen` 配置暴露网关入口端口。
+- 支持普通 HTTPS 入口、国密 SSL 入口以及同端口融合入口。
+- 负责连接接入、连接复用、超时控制、客户端 IP 透传和基础限流。
+- 在端口融合入口中不按端口区分算法体系，由国密 TLS 处理模块根据 ClientHello 能力完成协议和套件协商。
+- 将完成 TCP 接入后的连接交给国密 TLS 处理模块。
+
+输入：
+
+- 客户端 TCP 连接。
+- 监听端口、端口融合开关、协议类型、连接超时、并发限制等配置。
+
+输出：
+
+- 已接入的连接上下文。
+- 连接建立、关闭、异常等基础日志和指标。
+
+与其他模块关系：
+
+- 从配置管理模块读取监听端口和协议参数。
+- 将连接转交给国密 TLS 处理模块。
+- 向日志审计模块和监控告警模块输出连接级事件。
+
+### 3.2 国密 TLS 处理模块
+
+职责：
+
+- 通过 TongsuoSSL 提供国密 TLS/SSL 与标准 TLS 能力。
+- 完成协议版本协商、密码套件协商、密钥交换、证书选择、证书校验和会话密钥生成。
+- 支持 SM2 签名证书、SM2 加密证书、SM3 摘要算法、SM4 对称加密算法。
+- 支持同端口融合，根据客户端 `ClientHello` 中的协议版本、签名算法、密码套件和扩展字段选择国密或国际 TLS 处理路径。
+- 支持国际套件所需的 RSA 或 ECDSA 服务端证书，避免国密和国际客户端互相阻塞。
+- 支持单向认证和可选的双向认证。
+- 根据配置决定是否启用会话复用、会话缓存、OCSP/CRL 校验等能力。
+
+输入：
+
+- 监听接入模块传入的连接上下文。
+- 证书、私钥、CA 链、密码套件、协议版本、端口融合策略、SDF 开关等 TLS 配置。
+
+输出：
+
+- 已完成 TLS 握手的安全连接。
+- 握手失败原因、证书校验结果、协议类型、密码套件协商结果、SDF 使用结果等日志和指标。
+
+与其他模块关系：
+
+- 被 Nginx SSL 模块调用，底层依赖 TongsuoSSL API。
+- 从证书密钥管理模块加载国密证书和私钥。
+- 从配置管理模块读取协议版本、密码套件、端口融合、SDF 和认证策略。
+- 握手完成后将明文 HTTP 请求交给请求路由模块。
+
+### 3.3 国密协议版本与密码套件范围
+
+本方案首版明确支持以下国密协议与密码套件。实际可用范围需要以最终选定的 TongsuoSSL 与 Nginx 编译组合为准，启动前通过 `nginx -t` 和客户端握手测试确认。
+
+| 协议版本      | 密码套件名称                  | 身份认证        | 密钥交换             | 摘要算法 | 对称加密    | 支持级别 | 说明                      |
+| --------- | ----------------------- | ----------- | ---------------- | ---- | ------- | ---- | ----------------------- |
+| GMTLS 1.1 | `ECC-SM2-SM4-CBC-SM3`   | SM2         | ECDHE 或 SM2 协商流程 | SM3  | SM4-CBC | 首版必选 | 常见国密双证书场景，兼容性优先         |
+| GMTLS 1.1 | `ECDHE-SM2-SM4-CBC-SM3` | SM2         | ECDHE            | SM3  | SM4-CBC | 首版必选 | 适合需要前向安全的国密 TLS 场景      |
+| GMTLS 1.1 | `ECDHE-SM2-SM4-GCM-SM3` | SM2         | ECDHE            | SM3  | SM4-GCM | 首版建议 | 优先选择 AEAD 模式，需确认客户端兼容性  |
+| TLS 1.3   | `TLS_SM4_GCM_SM3`       | 证书算法可使用 SM2 | TLS 1.3 密钥协商     | SM3  | SM4-GCM | 兼容增强 | 适用于支持 RFC 8998 的客户端和服务端 |
+| TLS 1.3   | `TLS_SM4_CCM_SM3`       | 证书算法可使用 SM2 | TLS 1.3 密钥协商     | SM3  | SM4-CCM | 兼容增强 | 适用于支持 RFC 8998 的客户端和服务端 |
+
+版本边界：
+
+- 国密专用双证书握手优先按 `GMTLS 1.1` 设计，证书侧使用签名证书和加密证书。
+- 标准 `TLS 1.3` 国密密码套件按 RFC 8998 设计，密码套件名称为 `TLS_SM4_GCM_SM3` 和 `TLS_SM4_CCM_SM3`。
+- 标准 `TLS 1.2` 本身没有 IETF 标准化的 `SM2 + SM3 + SM4` 密码套件；如需兼容，应按 TongsuoSSL 提供的国密扩展能力单独验证。
+- 标准 RSA、ECDSA、AES 类密码套件不属于本方案的国密重点范围，可作为兼容入口另行配置。
+
+配置原则：
+
+- 默认优先启用 `ECDHE-SM2-SM4-GCM-SM3` 或 `TLS_SM4_GCM_SM3`，在客户端不兼容时回退到 CBC 套件。
+- 对公网入口不建议启用弱算法、非国密目标算法或无前向安全的配置。
+- 每个监听入口应明确协议版本和密码套件，避免一个入口同时承担过多兼容逻辑。
+
+### 3.4 SDF 适配模块
+
+职责：
+
+- 可选对接海光 CCP 的 SDF 接口，为 SM2 私钥运算、随机数生成等能力提供硬件或密码卡支撑。
+- SDF 动态库不内置到网关程序中，通过配置指定动态库路径、设备标识、应用标识、密钥索引和访问参数。
+- 网关启动或 reload 时按配置加载 SDF 动态库，并完成设备打开、会话创建和密钥可用性检查。
+- 当 SDF 模块内密钥已生成且可用时，优先使用 SDF 内部密钥完成私钥相关密码运算。
+- 当 SDF 模块内密钥未生成、密钥索引不存在或设备不可用时，按配置退化为使用外部私钥文件和证书。
+- SDF 退化只能影响私钥运算来源，不应改变客户端可见的证书链、路由规则和上游转发行为。
+
+输入：
+
+- SDF 开关、动态库路径、设备参数、密钥索引、超时和回退策略。
+- 外部证书、外部私钥和 CA 链配置。
+
+输出：
+
+- 可供国密 TLS 处理模块调用的私钥运算接口。
+- SDF 初始化状态、密钥命中状态、回退原因和错误信息。
+
+与其他模块关系：
+
+- 被国密 TLS 处理模块调用，用于完成握手中的 SM2 私钥相关运算。
+- 与证书密钥管理模块协作，决定当前入口使用 SDF 内部密钥还是外部私钥文件。
+- 从配置管理模块读取动态库路径、密钥索引和回退策略。
+- 向日志审计模块和监控告警模块输出 SDF 初始化、调用失败和回退事件。
+
+回退规则：
+
+| 场景 | 处理方式 | 日志级别 | 是否允许继续启动 |
+| --- | --- | --- | --- |
+| 未启用 SDF | 使用外部私钥文件和证书 | info | 是 |
+| SDF 动态库路径为空 | 使用外部私钥文件和证书 | warn | 是 |
+| SDF 动态库加载失败 | 使用外部私钥文件和证书 | error | 是，前提是外部私钥可用 |
+| SDF 设备打开失败 | 使用外部私钥文件和证书 | error | 是，前提是外部私钥可用 |
+| SDF 密钥索引不存在 | 使用外部私钥文件和证书 | warn | 是，前提是外部私钥可用 |
+| SDF 内部密钥可用 | 使用 SDF 内部密钥 | info | 是 |
+| SDF 不可用且外部私钥不可用 | 当前入口启动失败 | error | 否 |
+
+### 3.5 证书密钥管理模块
+
+职责：
+
+- 管理国密双证书体系，包括签名证书、加密证书及其私钥。
+- 管理国际 TLS 证书体系，包括 RSA 或 ECDSA 证书及其私钥。
+- 当启用 SDF 时，负责校验外部证书与 SDF 内部密钥的公钥匹配关系。
+- 管理 CA 根证书、中间证书、客户端认证 CA、CRL 文件等信任材料。
+- 支持证书文件加载、权限校验、格式校验和到期时间检查。
+- 为后续热更新或自动轮换预留清晰边界，但首版可采用文件配置方式。
+
+输入：
+
+- PEM 格式证书、私钥、CA 链和吊销列表文件。
+- 证书路径、密钥路径、SDF 密钥索引、客户端认证策略等配置。
+
+输出：
+
+- 可供 TongsuoSSL 使用的证书、私钥、SDF 密钥引用和信任链。
+- 证书加载失败、即将过期、校验失败等告警信息。
+
+与其他模块关系：
+
+- 向国密 TLS 处理模块提供证书、外部密钥材料或 SDF 密钥引用。
+- 从配置管理模块读取证书文件路径和认证策略。
+- 向日志审计模块记录证书加载和校验结果。
+- 向监控告警模块输出证书有效期和加载状态。
+
+### 3.6 请求路由模块
+
+职责：
+
+- 基于 Nginx `server_name`、`location`、`map`、`rewrite` 等能力完成请求匹配。
+- 根据域名、路径、Header、方法等条件选择后端上游。
+- 负责请求头规范化、必要的安全头处理和客户端信息透传。
+- 将路由后的请求交给反向代理模块。
+
+输入：
+
+- 国密 TLS 处理模块解密后的 HTTP 请求。
+- 路由规则、域名规则、Header 处理策略等配置。
+
+输出：
+
+- 已匹配上游的请求上下文。
+- 路由命中、未命中、重写结果等日志和指标。
+
+与其他模块关系：
+
+- 从配置管理模块读取路由规则。
+- 将请求转交给反向代理模块。
+- 向日志审计模块输出访问日志所需字段。
+
+### 3.7 反向代理与上游管理模块
+
+职责：
+
+- 使用 Nginx `proxy_pass` 与 `upstream` 能力转发请求到后端服务。
+- 支持轮询、权重、最少连接、健康检查等上游策略。
+- 支持对内 HTTP、HTTPS 或按需扩展其他协议。
+- 负责连接池、超时、重试、失败切换和响应返回。
+
+输入：
+
+- 请求路由模块传入的请求上下文。
+- 上游服务地址、负载均衡策略、超时、重试等配置。
+
+输出：
+
+- 后端服务响应。
+- 上游连接状态、请求耗时、错误码、重试次数等日志和指标。
+
+与其他模块关系：
+
+- 从配置管理模块读取上游列表和代理策略。
+- 将响应返回给客户端连接。
+- 向日志审计模块和监控告警模块输出转发结果。
+
+### 3.8 配置管理模块
+
+职责：
+
+- 以 Nginx 配置文件为核心，统一管理网关运行参数。
+- 管理监听端口、SSL 参数、证书路径、路由规则、上游服务、日志格式和限流策略。
+- 支持配置语法检查、灰度发布和 reload 生效。
+- 通过模板或配置生成工具降低手工配置错误，但首版可先使用静态配置文件。
+
+输入：
+
+- 运维或部署系统提供的配置文件。
+- 环境变量、模板参数或外部配置中心数据。
+
+输出：
+
+- Nginx 可加载的完整配置。
+- 配置检查结果和 reload 结果。
+
+与其他模块关系：
+
+- 为监听接入、国密 TLS、证书密钥、请求路由、反向代理、日志监控提供配置来源。
+- 不直接处理业务流量，只影响各运行模块的行为。
+
+### 3.9 日志审计模块
+
+职责：
+
+- 记录访问日志、错误日志、TLS 握手日志和安全审计日志。
+- 记录客户端 IP、域名、路径、状态码、响应时间、上游地址、密码套件、证书校验结果等关键信息。
+- 支持与日志采集系统对接，例如 Filebeat、Fluent Bit 或本地日志轮转工具。
+- 为问题排查、合规审计和安全分析提供数据来源。
+
+输入：
+
+- 各模块产生的运行事件、请求结果和异常信息。
+
+输出：
+
+- 标准访问日志、错误日志、安全审计日志。
+- 可被外部采集系统消费的结构化或半结构化日志。
+
+与其他模块关系：
+
+- 被监听接入、国密 TLS、请求路由、反向代理、证书密钥等模块调用或间接写入。
+- 向运维平台、安全平台提供审计数据。
+
+### 3.10 监控告警模块
+
+职责：
+
+- 采集网关运行指标、TLS 握手指标、证书状态和上游服务状态。
+- 关注 QPS、连接数、握手成功率、握手耗时、4xx/5xx、上游耗时、证书剩余有效期等指标。
+- 支持通过 Nginx stub_status、日志采集、Exporter 或外部探针方式接入监控系统。
+- 根据阈值产生告警，辅助定位证书过期、握手失败、后端异常和容量不足等问题。
+
+输入：
+
+- Nginx 运行状态、日志、证书检查结果、上游探测结果。
+
+输出：
+
+- 指标数据、健康状态和告警事件。
+
+与其他模块关系：
+
+- 从监听接入、国密 TLS、反向代理、证书密钥模块获取运行状态。
+- 与日志审计模块互补，日志用于追踪明细，监控用于观察趋势和触发告警。
+
+## 4. 请求处理流程
+
+```mermaid
+sequenceDiagram
+    participant C as 客户端
+    participant N as Nginx监听接入
+    participant T as TongsuoSSL国密TLS
+    participant R as 请求路由
+    participant P as 反向代理
+    participant U as 后端服务
+
+    C->>N: 建立TCP连接
+    N->>T: 发起TLS或国密握手
+    T->>T: 协商协议版本与国密密码套件
+    T->>T: 加载并校验证书链
+    T-->>C: 握手完成
+    C->>T: 发送加密HTTP请求
+    T->>R: 解密后转交HTTP请求
+    R->>R: 匹配server、location与upstream
+    R->>P: 传递路由结果
+    P->>U: 转发请求
+    U-->>P: 返回响应
+    P-->>T: 返回明文响应
+    T-->>C: 加密响应并返回
+```
+
+流程说明：
+
+1. 客户端连接网关监听端口。
+2. Nginx 接收 TCP 连接并进入 SSL 握手流程。
+3. TongsuoSSL 负责国密协议与密码套件协商。
+4. 握手成功后，TongsuoSSL 解密 HTTP 请求。
+5. Nginx 按配置执行域名、路径和请求规则匹配。
+6. 反向代理模块将请求转发到目标上游。
+7. 后端响应经网关返回客户端，出口侧继续由 TLS 模块加密。
+
+## 5. 部署形态
+
+建议首版采用静态编译或明确绑定 TongsuoSSL 的 Nginx 构建方式：
+
+```text
+Nginx 主程序
+├── Nginx core/event/http 模块
+├── Nginx ssl/http_ssl 模块
+├── TongsuoSSL 库
+├── 网关配置文件
+├── 国密证书与私钥文件
+└── 日志与监控采集组件
+```
+
+模块部署关系：
+
+- Nginx 与 TongsuoSSL 位于同一运行实例中，TongsuoSSL 作为 Nginx SSL 能力的底层库。
+- 配置文件、证书文件和日志目录通过部署系统挂载或复制到实例内。
+- 监控采集组件可与网关同机部署，也可由外部监控系统远程采集。
+- 后端服务与网关之间可处于同一内网，是否启用内侧 TLS 根据安全要求决定。
+
+## 6. 端口融合策略
+
+端口融合指同一个 `listen` 端口同时支持国密密码套件和国际密码套件，避免为不同客户端分别暴露不同端口。
+
+设计原则：
+
+- 同一端口同时配置国密套件和国际套件，由 TLS 握手阶段根据客户端能力自动协商。
+- 国密客户端优先协商 `GMTLS 1.1` 或 `TLS 1.3` 国密套件，国际客户端协商标准 RSA、ECDSA、AES 或 CHACHA20 套件。
+- 服务端需要同时准备国密证书和国际证书，TLS 处理模块根据握手上下文选择匹配证书。
+- 对不支持国密的普通客户端，不应因为启用国密套件导致握手失败。
+- 对只支持国密的客户端，不应因为同时配置国际套件导致降级到非国密算法。
+
+同端口融合关系如下：
+
+```mermaid
+flowchart LR
+    ClientHello["ClientHello<br/>协议版本、签名算法、密码套件"] --> Selector["TLS 能力选择<br/>TongsuoSSL"]
+    Selector --> GM["国密路径<br/>GMTLS 1.1 或 TLS 1.3 SM 套件"]
+    Selector --> INTL["国际路径<br/>标准 TLS 套件"]
+    GM --> GMCert["国密证书<br/>SM2 签名证书与加密证书"]
+    INTL --> IntlCert["国际证书<br/>RSA 或 ECDSA 证书"]
+    GMCert --> Router["统一请求路由"]
+    IntlCert --> Router
+```
+
+注意事项：
+
+- 端口融合属于 TLS 握手层能力，路由模块不应依赖“国密或国际”来决定默认业务路由。
+- 如果业务必须区分国密和国际来源，应通过独立 Header、变量或日志字段显式标记，避免隐式依赖端口。
+- 若客户端兼容性复杂，可保留独立国密端口和独立国际端口作为排障入口。
+
+## 7. 配置边界
+
+首版建议将配置划分为以下文件或片段：
+
+```text
+conf/
+├── nginx.conf              # 主配置，定义 worker、日志、全局参数
+├── conf.d/
+│   ├── gateway.conf        # 网关 server、SSL、端口融合和路由配置
+│   ├── sdf.conf            # 可选 SDF 动态库、设备和密钥索引配置
+│   └── upstream.conf       # 后端 upstream 配置
+├── certs/
+│   ├── sign.crt            # 国密签名证书
+│   ├── sign.key            # 国密签名私钥
+│   ├── enc.crt             # 国密加密证书
+│   ├── enc.key             # 国密加密私钥
+│   ├── intl.crt            # 国际 TLS 证书
+│   ├── intl.key            # 国际 TLS 私钥
+│   └── ca.crt              # CA 证书链
+└── logs/
+    ├── access.log
+    ├── error.log
+    └── ssl_audit.log
+```
+
+职责边界：
+
+- `nginx.conf` 只放全局配置，不承载业务路由细节。
+- `gateway.conf` 定义入口、端口融合、SSL 参数、server_name、location 和代理规则。
+- `sdf.conf` 定义 SDF 开关、动态库路径、设备参数、密钥索引和回退策略。
+- `upstream.conf` 定义后端服务池和负载均衡策略。
+- `certs/` 只保存证书和密钥材料，权限应独立控制。
+- `logs/` 只作为本地日志落地点，由外部系统负责采集和归档。
+
+## 8. 安全职责划分
+
+| 安全事项     | 责任模块                 | 说明                       |
+| -------- | -------------------- | ------------------------ |
+| 国密密码套件支持 | 国密 TLS 处理模块          | 由 TongsuoSSL 提供底层算法与协议支持 |
+| 端口融合协商 | 监听接入模块、国密 TLS 处理模块 | 同一端口根据 ClientHello 协商国密或国际套件 |
+| SDF 密钥运算 | SDF 适配模块、证书密钥管理模块 | 可选调用海光 CCP SDF 动态库，失败时按策略回退 |
+| 服务端证书加载  | 证书密钥管理模块             | 提供签名证书、加密证书和私钥           |
+| 客户端证书认证  | 国密 TLS 处理模块、证书密钥管理模块 | 可按入口启用双向认证               |
+| 后端访问控制   | 请求路由模块、反向代理模块        | 通过路由规则和网络策略限制上游访问        |
+| 敏感信息保护   | 配置管理模块、证书密钥管理模块      | 限制私钥文件权限，避免日志泄露密钥        |
+| 安全审计     | 日志审计模块               | 记录握手失败、证书异常和访问异常         |
+| 证书过期告警   | 监控告警模块               | 采集证书剩余有效期并触发告警           |
+
+## 9. 实施阶段建议
+
+### 阶段一：基础可用版本
+
+目标：验证 Nginx 与 TongsuoSSL 能够完成国密 TLS 接入和基础反向代理。
+
+主要工作：
+
+- 构建绑定 TongsuoSSL 的 Nginx。
+- 配置同端口国密与国际套件融合入口。
+- 准备国密服务端证书、国际 TLS 服务端证书和 CA 证书。
+- 配置国密 SSL、国际 TLS 和端口融合所需密码套件。
+- 配置单个后端 upstream 并完成请求转发。
+- 输出访问日志和错误日志。
+
+验收标准：
+
+- 客户端可使用国密 TLS 或国际 TLS 在同一端口成功连接网关。
+- 网关可将请求转发到后端服务并返回响应。
+- 握手失败、证书错误、上游错误可在日志中定位。
+
+### 阶段二：生产增强版本
+
+目标：完善稳定性、安全性和运维能力。
+
+主要工作：
+
+- 增加多 upstream 与负载均衡策略。
+- 增加双向认证配置能力。
+- 增加证书有效期检查、SDF 初始化状态检查和告警。
+- 增加结构化访问日志和 TLS 审计字段。
+- 增加配置检查、reload 和回滚流程。
+
+验收标准：
+
+- 多后端转发策略符合配置预期。
+- 客户端证书校验策略可按入口控制。
+- 证书即将过期、SDF 不可用、上游异常、握手异常可触发监控告警。
+- 配置变更可通过检查后平滑 reload。
+
+### 阶段三：平台化版本
+
+目标：将网关能力沉淀为可持续运维的平台组件。
+
+主要工作：
+
+- 对接配置中心或配置生成工具。
+- 支持证书自动轮换、集中托管或 SDF 内部密钥生命周期管理。
+- 接入统一日志、监控和告警平台。
+- 形成标准部署包、启动脚本和运维手册。
+
+验收标准：
+
+- 网关实例可批量部署和一致化配置。
+- 证书轮换或 SDF 密钥切换流程不影响业务连续性。
+- 运维人员可通过统一平台观察运行状态并定位问题。
+
+## 10. 推荐版本与工作量预估
+
+### 10.1 推荐版本
+
+| 组件 | 推荐版本 | 备选版本 | 推荐理由 | 注意事项 |
+| --- | --- | --- | --- | --- |
+| Nginx | `1.30.3` | `1.31.2` | `1.30.x` 属于稳定分支，适合作为首版工程基线；`1.31.x` 更新但更偏主线验证 | 如需使用更新 HTTP 或 SSL 能力，可在专项测试后切换到 `1.31.2` |
+| TongsuoSSL | `8.4.0` | `8.3.3` | 当前可见稳定标签中 `8.4.0` 较新，适合作为国密、TLS 1.3 SM 套件和后续 SDF 适配基线 | 需要实测与 Nginx SSL 模块、端口融合、SDF 动态库加载的兼容性 |
+
+推荐组合：
+
+- 首选组合：`Nginx 1.30.3 + TongsuoSSL 8.4.0`。
+- 保守组合：`Nginx 1.30.3 + TongsuoSSL 8.3.3`，用于 `8.4.0` 与 SDF 或端口融合存在兼容问题时回退。
+- 验证组合：`Nginx 1.31.2 + TongsuoSSL 8.4.0`，仅建议在需要 Nginx 主线能力时进入兼容性测试。
+
+版本锁定原则：
+
+- 研发、测试和交付环境必须固定具体 tag 或源码提交号，不使用浮动分支。
+- 编译产物需要记录 Nginx 版本、TongsuoSSL 版本、编译参数、SDF 动态库版本和操作系统版本。
+- 升级任一组件时，需要重新执行国密握手、国际 TLS 握手、端口融合、SDF 回退和反向代理回归测试。
+
+### 10.2 开发工作量预估
+
+以下预估按 2 名后端或基础设施开发人员投入计算，默认已有可用的国密证书、国际证书、测试客户端和海光 CCP SDF 测试环境。如果 SDF 设备、证书或客户端环境需要额外准备，工期需要顺延。
+
+| 阶段 | 工作内容 | 预估人日 | 主要产出 |
+| --- | --- | --- | --- |
+| 方案细化 | 明确协议范围、密码套件、端口融合策略、SDF 回退策略和配置格式 | 2-3 | 详细设计、配置样例、测试清单 |
+| 构建集成 | 编译 Nginx 与 TongsuoSSL，固化构建脚本和版本信息 | 3-5 | 可重复构建脚本、二进制包、版本说明 |
+| 国密 TLS 接入 | 配置 GMTLS 1.1、TLS 1.3 SM 套件、国密双证书和基础反向代理 | 4-6 | 国密入口、证书配置、代理配置 |
+| 端口融合 | 同端口支持国密和国际套件，完成证书选择、套件优先级和日志字段 | 5-8 | 融合入口配置、协商日志、兼容性说明 |
+| SDF 适配 | 外置加载海光 CCP SDF 动态库，完成初始化、密钥索引检查、私钥运算调用和回退 | 8-12 | SDF 配置、适配代码或补丁、回退逻辑 |
+| 日志监控 | 增加协议类型、密码套件、SDF 状态、回退原因和上游状态观测 | 3-5 | 日志格式、指标清单、告警建议 |
+| 打包部署 | 启停脚本、配置模板、证书目录、日志目录和部署说明 | 3-4 | 部署包、目录规范、运维说明 |
+| 开发自测 | 开发侧握手、代理、reload、异常回退和基础性能自测 | 4-6 | 自测记录、问题修复 |
+
+开发合计：
+
+- 不含 SDF：约 `24-37` 人日，2 人并行约 `3-4` 周。
+- 含 SDF：约 `32-49` 人日，2 人并行约 `4-6` 周。
+
+### 10.3 测试工作量预估
+
+以下预估按 1-2 名测试人员投入计算，包含功能、兼容性、异常、稳定性和基础性能测试。
+
+| 测试类型 | 测试内容 | 预估人日 | 验证重点 |
+| --- | --- | --- | --- |
+| 构建验证 | 版本号、编译参数、依赖库路径、启动和 reload | 1-2 | 产物可重复、配置检查通过 |
+| 国密功能测试 | GMTLS 1.1、TLS 1.3 SM 套件、国密双证书、单向和双向认证 | 4-6 | 握手成功、证书校验、套件正确 |
+| 国际 TLS 测试 | RSA、ECDSA、标准 TLS 1.2 和 TLS 1.3 客户端接入 | 2-4 | 国际客户端兼容性 |
+| 端口融合测试 | 同端口国密客户端和国际客户端混合接入 | 5-8 | 协商正确、互不影响、日志可区分 |
+| SDF 功能测试 | 动态库加载、设备打开、密钥索引命中、私钥运算 | 5-8 | SDF 路径可用、性能和错误处理正常 |
+| SDF 回退测试 | 未生成密钥、索引不存在、动态库缺失、设备不可用、外部私钥缺失 | 4-6 | 按规则回退或失败，日志清晰 |
+| 代理功能测试 | 路由、Header 透传、负载均衡、超时、重试和上游故障 | 3-5 | 代理行为符合配置 |
+| 安全测试 | 弱套件禁用、证书过期、错误证书、客户端证书异常 | 3-5 | 不接受非法连接，审计可追踪 |
+| 稳定性测试 | 长连接、并发连接、reload、日志轮转和异常恢复 | 5-8 | 长时间运行无明显异常 |
+| 基础性能测试 | 握手吞吐、请求吞吐、SDF 与外部私钥性能对比 | 4-6 | 形成容量基线 |
+
+测试合计：
+
+- 不含 SDF：约 `27-44` 人日，1-2 人约 `3-5` 周。
+- 含 SDF：约 `36-58` 人日，1-2 人约 `4-7` 周。
+
+### 10.4 总体周期建议
+
+| 范围 | 开发周期 | 测试周期 | 总周期建议 |
+| --- | --- | --- | --- |
+| 基础国密网关，不含端口融合和 SDF | 2-3 周 | 2-3 周 | 4-6 周 |
+| 含端口融合，不含 SDF | 3-4 周 | 3-5 周 | 6-8 周 |
+| 含端口融合和海光 CCP SDF | 4-6 周 | 4-7 周 | 8-12 周 |
+
+主要风险：
+
+- 端口融合依赖客户端 `ClientHello` 能力，老旧国密客户端可能存在非标准行为。
+- SDF 适配依赖海光 CCP 动态库、设备驱动、密钥生命周期和接口行为，建议尽早取得真实测试环境。
+- TongsuoSSL 与 Nginx SSL 模块的接口兼容性需要以实际编译和握手测试为准。
+- 国密证书签发、双证书匹配和 SDF 内部密钥公钥匹配会影响联调进度。
+
+## 11. 后续设计重点
+
+后续进入实现前，需要进一步明确以下事项：
+
+- TongsuoSSL 与 Nginx 的具体版本组合。
+- 国密证书格式、双证书配置方式和证书签发来源。
+- 端口融合入口需要支持的客户端范围，以及国密与国际套件的优先级。
+- 海光 CCP SDF 动态库版本、SDF 接口兼容性、密钥索引规划和回退策略。
+- 后端协议是否必须加密，以及是否需要内侧双向认证。
+- 日志字段、审计留存周期和监控接入方式。
+- 部署环境是物理机、虚拟机、容器还是 Kubernetes。
+
+## 12. 成功标准
+
+本方案对应的网关程序实现完成后，应满足以下标准：
+
+- 客户端可通过同一端口使用国密 TLS 或国际 TLS 与网关建立安全连接。
+- 网关可基于域名、路径或 Header 将请求转发到指定后端。
+- 证书、SDF、路由、上游和日志配置边界清晰，便于维护。
+- TLS 握手、端口融合协商、SDF 状态、请求路由、上游代理、证书加载均可观测。
+- 常见异常场景可通过日志和监控定位，包括证书错误、SDF 回退、握手失败、路由未命中、上游不可用。
diff --git a/docs/需求.md b/docs/需求.md
new file mode 100644
index 0000000..96cf0c4
--- /dev/null
+++ b/docs/需求.md
@@ -0,0 +1,8 @@
+- 服务模块（nginx+tongsuossl）
+- 客户端模块
+    - java http+ssl 客户端
+        - 单向认证
+        - 双向认证
+    - java tcp+ssl 客户端
+        - 单向认证
+        - 双向认证
\ No newline at end of file