video_socket-server/.qoder/repowiki/zh/content/部署指南/SSL_TLS 配置.md

# 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 的套件，确保会话密钥不被历史泄露影响。

说明：本节为通用概念说明，不直接对应具体源码文件。