Skip to content

requirements.md

Latest commit

 

History

History
273 lines (206 loc) · 7.48 KB

requirements.md

File metadata and controls

273 lines (206 loc) · 7.48 KB

NginxGo 需求分析文档

1. 项目概述

1.1 项目背景

NginxGo 是一个使用 Go 语言重新实现的 Nginx 核心功能的高性能 HTTP 服务器和反向代理服务器。项目目标是在保持与 Nginx 高度兼容的同时，利用 Go 语言的并发优势实现更高的性能和更好的可维护性。

1.2 项目愿景

  • 性能目标: 对标 Nginx，支持数万并发连接
  • 兼容性: 高度兼容 Nginx 配置语法
  • 可维护性: 清晰的模块化架构，便于扩展和维护

2. 用户需求

2.1 运维人员需求

需求编号 需求描述 优先级
REQ-001 支持 Nginx 风格的配置文件语法 P0
REQ-002 支持热重载配置，无需重启服务 P0
REQ-003 提供与 Nginx 相似的命令行管理工具 P0
REQ-004 支持日志轮转 P1
REQ-005 提供服务状态监控接口 P2

2.2 开发人员需求

需求编号 需求描述 优先级
REQ-101 支持自定义 HTTP 处理器模块 P1
REQ-102 支持自定义过滤器模块 P1
REQ-103 提供丰富的钩子函数用于扩展 P2

2.3 应用场景需求

需求编号 需求描述 优先级
REQ-201 作为静态文件服务器使用 P0
REQ-202 作为反向代理服务器使用 P0
REQ-203 支持负载均衡 P0
REQ-204 支持 SSL/TLS 终端 P1
REQ-205 支持 WebSocket 代理 P1

3. 功能需求

3.1 核心功能

3.1.1 进程管理

  • Master 进程负责整体协调
  • 支持配置数个 Worker 进程（默认 CPU 核数）
  • 支持信号控制（TERM, INT, QUIT, HUP, USR1, USR2）
  • 支持平滑升级

3.1.2 HTTP 服务

请求处理

  • 支持 HTTP/1.1 协议
  • 支持 HTTP 方法：GET, POST, PUT, DELETE, HEAD, OPTIONS
  • 支持 Keep-Alive 长连接
  • 支持分块传输编码 (Chunked Transfer Encoding)

请求解析

  • 解析请求行（Method, URI, Proto）
  • 解析请求头
  • 解析 URL 参数
  • 解析 Cookie
  • 支持最大请求体大小限制

响应处理

  • 支持响应状态码（200, 301, 302, 404, 500 等）
  • 设置响应头（Content-Type, Content-Length, Cache-Control 等）
  • 支持 gzip 压缩
  • 支持自定义错误页面

3.1.3 静态文件服务

  • 支持目录浏览
  • 支持文件类型映射（MIME types）
  • 支持自定义首页（index.html）
  • 支持 ETag 和 Last-Modified 缓存头
  • 支持自定义 404/403 等错误页面

3.1.4 反向代理

  • 支持 upstream 负载均衡
  • 支持负载均衡策略：轮询、最少连接、IP Hash
  • 支持上游服务器健康检查
  • 支持代理请求头修改
  • 支持连接复用

3.1.5 负载均衡

  • 支持多种负载均衡算法
  • 支持权重配置
  • 支持备份服务器
  • 支持最大失败次数配置

3.2 配置功能

3.2.1 全局配置

指令 说明 默认值
worker_processes Worker 进程数 auto (CPU 核数)
error_log 错误日志路径 logs/error.log
pid PID 文件路径 logs/nginx.pid
user 运行用户 nobody
worker_rlimit_nofile 最大文件描述符数 系统限制

3.2.2 Events 配置

指令 说明 默认值
worker_connections 单 Worker 最大连接数 512
use 事件处理模型 epoll (Linux)
multi_accept 一次 accept 多个连接 on

3.2.3 HTTP 配置

Server 块

  • listen: 监听地址和端口
  • server_name: 服务器名称
  • root: 文档根目录
  • index: 默认首页

Location 块

  • location: URL 匹配规则
  • proxy_pass: 上游服务器地址
  • fastcgi_pass: FastCGI 服务器地址
  • try_files: 文件尝试顺序
  • rewrite: URL 重写

3.3 性能需求

指标 目标值
并发连接数 10,000+
QPS 50,000+
内存占用 < 100MB (空闲)
请求延迟 < 10ms (本地文件)
CPU 利用率 < 50% (满载)

4. 非功能需求

4.1 可用性需求

  • 服务启动时间 < 2 秒
  • 配置热重载时间 < 1 秒
  • 支持优雅关闭（处理完当前请求后再退出）

4.2 可扩展性需求

  • 模块化的模块系统
  • 支持运行时加载模块
  • 清晰的模块接口定义

4.3 兼容性需求

  • 配置文件兼容 Nginx 80% 以上常用指令
  • 命令行参数兼容 Nginx 基本操作
  • 支持 SSL 证书格式兼容现有 Nginx 配置

4.4 安全性需求

  • 支持运行在非 root 用户下
  • 支持连接数限制
  • 支持请求速率限制
  • 支持 IP 黑名单

5. 用例分析

5.1 用例1: 启动服务

参与者: 运维人员 前置条件: 配置文件存在且有效 基本流程:

  1. 解析配置文件
  2. 初始化模块
  3. 启动 Master 进程
  4. Fork Worker 进程
  5. Worker 进入事件循环 后置条件: 服务正常运行，监听指定端口

5.2 用例2: 处理静态文件请求

参与者: 客户端 前置条件: 服务已启动 基本流程:

  1. 客户端发送 HTTP 请求
  2. Worker 接收连接
  3. 解析 HTTP 请求
  4. 匹配 Location 规则
  5. 读取本地文件
  6. 构建并发送响应 后置条件: 客户端收到文件内容

5.3 用例3: 反向代理请求

参与者: 客户端 前置条件: 服务已启动，Upstream 已配置 基本流程:

  1. 客户端发送 HTTP 请求
  2. Worker 接收连接
  3. 解析 HTTP 请求
  4. 匹配代理 Location
  5. 选择上游服务器
  6. 转发请求到上游
  7. 接收上游响应
  8. 返回响应给客户端 后置条件: 客户端收到上游服务器响应

5.4 用例4: 热重载配置

参与者: 运维人员 前置条件: 服务运行中 基本流程:

  1. 运维人员发送 HUP 信号
  2. Master 进程解析新配置
  3. 创建新的 Cycle
  4. 通知 Worker 接收新配置
  5. 新请求使用新配置
  6. 旧连接处理完成后关闭 后置条件: 新配置生效，旧连接自然终止

6. 需求追踪矩阵

需求 ID 来源 设计验证 测试验证
REQ-001 运维人员 架构设计-配置系统 单元测试-配置解析
REQ-002 运维人员 架构设计-进程管理 集成测试-热重载
REQ-003 运维人员 详细设计-CLI 手动测试-命令行
REQ-101 开发人员 详细设计-模块接口 单元测试-模块注册
REQ-201 应用场景 详细设计-静态处理 集成测试-文件服务
REQ-202 应用场景 详细设计-代理处理 集成测试-反向代理
REQ-203 应用场景 详细设计-负载均衡 集成测试-负载均衡

7. 风险分析

风险 ID 风险描述 影响程度 缓解措施
RISK-001 Go 语言 GC 延迟 高 使用对象池，减少内存分配
RISK-002 与 Nginx 配置完全兼容难度大 中 优先实现核心指令，逐步完善
RISK-003 性能可能低于原生 Nginx 中 持续优化，特别是热点路径
RISK-004 第三方模块移植困难 低 提供清晰的扩展接口文档

8. 里程碑计划

里程碑 内容 预计时间
M1 核心框架完成（进程模型、事件循环） 第1周
M2 HTTP 核心功能（解析、路由） 第2周
M3 静态文件服务 第3周
M4 反向代理和负载均衡 第4周
M5 SSL/TLS 支持 第5周
M6 性能优化和测试 第6周
M7 Beta 版本发布 第7周
M8 稳定版发布 第8周