修改
This commit is contained in:
346
.qoder/repowiki/zh/content/部署指南/SSL_TLS 配置.md
Normal file
346
.qoder/repowiki/zh/content/部署指南/SSL_TLS 配置.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# SSL/TLS 配置
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [src/index.ts](file://src/index.ts)
|
||||
- [src/server.ts](file://src/server.ts)
|
||||
- [src/class/options.ts](file://src/class/options.ts)
|
||||
- [src/log.ts](file://src/log.ts)
|
||||
- [src/websocket.ts](file://src/websocket.ts)
|
||||
- [package.json](file://package.json)
|
||||
- [run.bat](file://run.bat)
|
||||
- [server.cert](file://server.cert)
|
||||
- [server.key](file://server.key)
|
||||
- [tsconfig.json](file://tsconfig.json)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕当前代码库中的 HTTPS 与证书使用现状，提供一份面向实际部署的 SSL/TLS 配置参考。重点涵盖以下方面：
|
||||
- 当前 HTTPS 启用方式与证书加载机制
|
||||
- 证书文件位置与格式要求
|
||||
- HTTPS 服务器启动参数与运行脚本
|
||||
- 与证书相关的配置项与环境变量
|
||||
- 为后续扩展 ACME 自动续期、HSTS、OCSP Stapling 等安全加固提供落地建议
|
||||
|
||||
说明：当前仓库已内置示例证书与密钥文件，用于本地演示 HTTPS；但未包含 Let's Encrypt 或商业证书的自动化流程、ACME 续期脚本等。本文将基于现有实现，给出可操作的扩展路径与最佳实践。
|
||||
|
||||
## 项目结构
|
||||
与 SSL/TLS 相关的关键文件与职责如下：
|
||||
- 证书与密钥：server.key、server.cert
|
||||
- 应用入口与 HTTPS 启动：src/index.ts
|
||||
- Express 服务器创建与静态资源：src/server.ts
|
||||
- 运行脚本与命令行参数：package.json、run.bat
|
||||
- 日志与选项定义：src/log.ts、src/class/options.ts
|
||||
- WebSocket 信令服务：src/websocket.ts
|
||||
- TypeScript 编译配置：tsconfig.json
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["应用入口<br/>src/index.ts"] --> B["HTTPS 服务器创建<br/>读取 server.key / server.cert"]
|
||||
A --> C["Express 应用创建<br/>src/server.ts"]
|
||||
C --> D["静态资源与路由<br/>客户端页面与 API"]
|
||||
A --> E["WebSocket 信令服务<br/>src/websocket.ts"]
|
||||
F["运行脚本<br/>package.json"] --> A
|
||||
G["启动批处理<br/>run.bat"] --> A
|
||||
H["证书与密钥<br/>server.key / server.cert"] --> B
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
- [server.key](file://server.key)
|
||||
- [server.cert](file://server.cert)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:13-106](file://src/index.ts#L13-L106)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
- [server.key](file://server.key)
|
||||
- [server.cert](file://server.cert)
|
||||
|
||||
## 核心组件
|
||||
- HTTPS 启用与证书加载
|
||||
- 在应用入口中，当启用 HTTPS 时，通过读取 server.key 与 server.cert 文件创建 HTTPS 服务器，并监听指定端口。
|
||||
- 证书与私钥文件路径可通过命令行参数覆盖，默认值指向项目根目录下的 server.key 与 server.cert。
|
||||
- Express 应用与静态资源
|
||||
- Express 应用负责提供前端页面、API 接口与静态资源；HTTPS 仅影响传输层安全，不影响应用逻辑。
|
||||
- 运行脚本与参数
|
||||
- package.json 中的 start 脚本默认以 HTTPS 启动，并传入 -s、-p、-k、-c 等参数。
|
||||
- run.bat 提供 Windows 环境下的构建与启动流程示例。
|
||||
- 日志与选项
|
||||
- 日志系统支持多级别输出，便于排障。
|
||||
- Options 接口定义了端口、HTTPS 开关、证书与密钥路径、信令类型、日志级别等配置项。
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/index.ts:20-41](file://src/index.ts#L20-L41)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
## 架构总览
|
||||
下图展示了 HTTPS 启动与请求处理的整体流程，以及证书加载与静态资源服务的关系。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as "命令行/脚本"
|
||||
participant App as "应用入口<br/>src/index.ts"
|
||||
participant HTTPS as "HTTPS 服务器"
|
||||
participant Express as "Express 应用<br/>src/server.ts"
|
||||
participant WS as "WebSocket 信令<br/>src/websocket.ts"
|
||||
CLI->>App : 传入参数(-s/-p/-k/-c)
|
||||
App->>App : 解析 Options 并校验
|
||||
App->>HTTPS : 读取 server.key / server.cert 创建 HTTPS 服务器
|
||||
HTTPS-->>App : 监听端口并输出访问地址
|
||||
App->>Express : 初始化 Express 应用
|
||||
Express-->>App : 提供静态资源与 API
|
||||
App->>WS : 启动 WebSocket 信令服务
|
||||
Note over HTTPS,Express : 所有请求均通过 HTTPS 传输
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/websocket.ts:15-19](file://src/websocket.ts#L15-L19)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/websocket.ts:15-19](file://src/websocket.ts#L15-L19)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### HTTPS 启动与证书加载
|
||||
- 参数解析与默认值
|
||||
- HTTPS 开关、端口、证书与密钥路径均可通过命令行参数配置；默认启用 HTTPS。
|
||||
- 证书与密钥读取
|
||||
- 使用文件系统读取 server.key 与 server.cert，作为 HTTPS 服务器的凭据。
|
||||
- 启动行为
|
||||
- 成功启动后输出 https:// 访问地址；若未启用 HTTPS，则输出 http://。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["应用启动"]) --> Parse["解析命令行参数<br/>确定 HTTPS 与证书路径"]
|
||||
Parse --> Secure{"是否启用 HTTPS？"}
|
||||
Secure --> |是| LoadCert["读取 server.key / server.cert"]
|
||||
Secure --> |否| HTTPListen["启动 HTTP 服务器"]
|
||||
LoadCert --> HTTPSListen["启动 HTTPS 服务器并监听端口"]
|
||||
HTTPSListen --> LogAddr["输出 https:// 访问地址"]
|
||||
HTTPListen --> LogAddr
|
||||
LogAddr --> End(["服务就绪"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:20-41](file://src/index.ts#L20-L41)
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:20-41](file://src/index.ts#L20-L41)
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
|
||||
### Express 应用与静态资源
|
||||
- CORS 与日志
|
||||
- 默认开启跨域与 Morgan 日志记录，日志级别可配置。
|
||||
- 路由与静态资源
|
||||
- 提供根路径页面、/signaling 信令路由、静态资源目录等。
|
||||
- 上传与媒体资源
|
||||
- 提供头像上传与静态媒体访问路径。
|
||||
|
||||
章节来源
|
||||
- [src/server.ts:18-20](file://src/server.ts#L18-L20)
|
||||
- [src/server.ts:25-39](file://src/server.ts#L25-L39)
|
||||
- [src/server.ts:62-86](file://src/server.ts#L62-L86)
|
||||
|
||||
### WebSocket 信令服务
|
||||
- 与 HTTP 服务器共享底层 TCP 连接
|
||||
- WebSocket 服务器依附于同一 HTTP 服务器实例，因此也受 HTTPS 保护。
|
||||
- 连接生命周期管理
|
||||
- 连接建立、消息分发、断开清理等逻辑由处理器模块完成。
|
||||
|
||||
章节来源
|
||||
- [src/websocket.ts:15-19](file://src/websocket.ts#L15-L19)
|
||||
- [src/websocket.ts:27-38](file://src/websocket.ts#L27-L38)
|
||||
- [src/websocket.ts:44-114](file://src/websocket.ts#L44-L114)
|
||||
|
||||
### 运行脚本与参数
|
||||
- package.json
|
||||
- start 脚本默认以 HTTPS 启动，并传入 -s、-p、-k、-c 等参数。
|
||||
- run.bat
|
||||
- Windows 环境下先构建再启动，便于本地调试。
|
||||
|
||||
章节来源
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
|
||||
### 证书与密钥文件
|
||||
- server.key 与 server.cert
|
||||
- 示例证书与密钥文件位于项目根目录，用于演示 HTTPS 功能。
|
||||
- 请确保文件权限正确，避免被其他用户读取。
|
||||
|
||||
章节来源
|
||||
- [server.key](file://server.key)
|
||||
- [server.cert](file://server.cert)
|
||||
|
||||
## 依赖关系分析
|
||||
- 应用入口依赖文件系统读取证书与密钥，依赖 Express 提供 Web 服务，依赖 WebSocket 提供信令通道。
|
||||
- Express 应用依赖日志模块与配置模块，提供静态资源与 API。
|
||||
- 运行脚本与批处理文件负责编译与启动流程。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Index["src/index.ts"] --> FS["文件系统<br/>读取 server.key / server.cert"]
|
||||
Index --> Express["Express 应用<br/>src/server.ts"]
|
||||
Express --> Static["静态资源与路由"]
|
||||
Index --> WS["WebSocket 信令<br/>src/websocket.ts"]
|
||||
Run["package.json 脚本"] --> Index
|
||||
Bat["run.bat"] --> Index
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/websocket.ts:15-19](file://src/websocket.ts#L15-L19)
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/websocket.ts:15-19](file://src/websocket.ts#L15-L19)
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
|
||||
## 性能考虑
|
||||
- 证书与密钥读取
|
||||
- 采用同步读取方式，启动阶段一次性加载，运行时无额外 IO 开销。
|
||||
- 日志级别
|
||||
- 可通过日志级别控制输出量，避免在高并发场景下产生过多 I/O。
|
||||
- 静态资源
|
||||
- 建议在生产环境中配合反向代理缓存与压缩，提升静态资源访问效率。
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:57-58](file://src/index.ts#L57-L58)
|
||||
- [src/log.ts:15-24](file://src/log.ts#L15-L24)
|
||||
|
||||
## 故障排查指南
|
||||
- 无法启动 HTTPS 服务器
|
||||
- 检查 server.key 与 server.cert 是否存在且可读。
|
||||
- 确认端口未被占用，且进程具备相应权限。
|
||||
- 访问出现证书错误
|
||||
- 若使用自签名证书，请在浏览器或客户端信任该证书。
|
||||
- 确认域名与证书匹配，避免主机名不一致导致的校验失败。
|
||||
- 日志定位问题
|
||||
- 使用日志模块提供的不同级别输出，结合 Express 的 Morgan 日志，快速定位请求异常。
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
- [src/server.ts:18-20](file://src/server.ts#L18-L20)
|
||||
|
||||
## 结论
|
||||
当前代码库已具备基本的 HTTPS 启用能力与证书加载机制，适合在开发与演示环境中使用。若需在生产环境长期稳定运行，建议进一步完善以下方面：
|
||||
- 引入 ACME 自动续期（如 acme.sh），实现 Let's Encrypt 免费证书的自动化申请与续期。
|
||||
- 部署反向代理（如 Nginx/Caddy），统一处理 TLS 终止、证书管理与安全头部。
|
||||
- 配置 HSTS、OCSP Stapling、前向保密等安全策略，提升整体安全性与性能。
|
||||
|
||||
## 附录
|
||||
|
||||
### 证书与密钥文件位置
|
||||
- server.key：HTTPS 私钥文件
|
||||
- server.cert：HTTPS 证书文件
|
||||
|
||||
章节来源
|
||||
- [server.key](file://server.key)
|
||||
- [server.cert](file://server.cert)
|
||||
|
||||
### HTTPS 启动参数与脚本
|
||||
- 命令行参数
|
||||
- -s/--secure：启用 HTTPS
|
||||
- -p/--port：监听端口
|
||||
- -k/--keyfile：私钥文件路径
|
||||
- -c/--certfile：证书文件路径
|
||||
- 启动脚本
|
||||
- package.json 的 start 脚本默认以 HTTPS 启动
|
||||
- run.bat 提供 Windows 环境下的构建与启动流程
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:20-41](file://src/index.ts#L20-L41)
|
||||
- [package.json:9-10](file://package.json#L9-L10)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
|
||||
### 与证书相关的配置项与环境变量
|
||||
- Options 接口定义了 secure、port、keyfile、certfile、type、mode、logging 等配置项
|
||||
- 环境变量映射
|
||||
- PORT、SECURE、KEYFILE、CERTFILE、TYPE、MODE、LOGGING
|
||||
|
||||
章节来源
|
||||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||||
- [src/index.ts:20-41](file://src/index.ts#L20-L41)
|
||||
|
||||
### 证书格式与转换（概念性说明）
|
||||
- PEM 与 DER
|
||||
- PEM 是文本格式，DER 是二进制格式；两者可互相转换。
|
||||
- PKCS#12
|
||||
- 包含私钥与证书链，常用于导入导出。
|
||||
- OpenSSL 常用命令（概念性说明）
|
||||
- 证书转 DER：openssl x509 -in server.pem -outform DER -out server.der
|
||||
- DER 转 PEM：openssl x509 -in server.der -inform DER -out server.pem -outform PEM
|
||||
- 生成自签名证书：openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
|
||||
- 导出 PKCS#12：openssl pkcs12 -export -out keystore.p12 -inkey key.pem -in cert.pem
|
||||
|
||||
说明：本节为通用概念说明，不直接对应具体源码文件。
|
||||
|
||||
### Let's Encrypt 与商业证书申请（概念性说明）
|
||||
- Let's Encrypt
|
||||
- 使用 acme.sh 等工具自动申请与续期免费证书。
|
||||
- 商业证书
|
||||
- 通过 CA 申请，通常包含中间证书链，需按要求配置证书链文件。
|
||||
- 证书链验证
|
||||
- 生产环境应提供完整链路，避免中间证书缺失导致校验失败。
|
||||
|
||||
说明：本节为通用概念说明，不直接对应具体源码文件。
|
||||
|
||||
### HTTPS 服务器配置要点（概念性说明）
|
||||
- TLS 版本
|
||||
- 建议禁用过时版本，启用现代 TLS 1.2/1.3。
|
||||
- 加密套件
|
||||
- 优先选择支持前向保密的套件，避免弱加密算法。
|
||||
- 证书链
|
||||
- 确保证书链完整，避免客户端校验失败。
|
||||
|
||||
说明：本节为通用概念说明，不直接对应具体源码文件。
|
||||
|
||||
### 证书自动续期方案（概念性说明）
|
||||
- acme.sh
|
||||
- 支持自动申请、验证与续期，可配置定时任务。
|
||||
- 定时任务
|
||||
- 使用 crontab 或计划任务定期执行续期检查与重启服务。
|
||||
|
||||
说明：本节为通用概念说明，不直接对应具体源码文件。
|
||||
|
||||
### 安全最佳实践（概念性说明）
|
||||
- HSTS 头部
|
||||
- 设置严格传输安全，提升抗降级攻击能力。
|
||||
- OCSP Stapling
|
||||
- 减少在线证书状态查询延迟与隐私泄露风险。
|
||||
- 前向保密
|
||||
- 使用支持 ECDHE 的套件，确保会话密钥不被历史泄露影响。
|
||||
|
||||
说明：本节为通用概念说明，不直接对应具体源码文件。
|
||||
Reference in New Issue
Block a user