# Lolly 项目需求文档 > 本文档用于指导 AI 实现一个高性能 HTTP 服务器项目。 ## 一、项目定位 创建一个类似 nginx 的高性能 HTTP 服务器，项目名称为 **lolly**。 ### 核心目标 - 实现与 nginx 相同的核心功能，但**不是 1:1 复刻** - 比 nginx 更加现代、更加易用 - 充分利用 Go 语言特性（goroutine、channel、标准库等） - 保持高性能（高并发、低内存消耗） ### 技术约束 | 约束项 | 要求 | |--------|------| | 语言 | 纯 Go 实现，不依赖 C 库 | | 部署 | 静态链接，单二进制文件即可运行 | | 配置 | YAML 格式（比 nginx 的 nginx.conf 更简单易用） | | 兼容性 | 跨平台支持（Linux、macOS、Windows） | --- ## 二、功能需求 ### 必须实现的核心功能（参考 docs/ 目录详细文档） #### 2.1 HTTP 核心模块（优先级：最高） 参考：`docs/03-nginx-http-core.md` - **Server/Location 配置**：虚拟主机、请求路由 - **静态文件服务**：高效 serving 静态资源 - **请求处理**：请求头、请求体、超时控制 - **keep-alive**：长连接支持 - **MIME 类型**：自动识别内容类型 #### 2.2 反向代理与负载均衡（优先级：高） 参考：`docs/04-nginx-proxy-loadbalancing.md` - **反向代理**：proxy_pass 功能 - **负载均衡算法**：轮询、权重、最少连接、IP 哈希 - **健康检查**：主动/被动健康检测 - **WebSocket 支持**：Upgrade 协议处理 - **代理缓存**：响应缓存机制 #### 2.3 SSL/TLS 与 HTTPS（优先级：高） 参考：`docs/05-nginx-ssl-https.md` - **HTTPS 服务**：证书配置 - **SSL 会话缓存**：减少握手开销 - **HTTP/2 支持**：现代化协议 - **自动证书管理**：可选 ACME/Let's Encrypt 集成 #### 2.4 URL 重写与请求处理（优先级：中） 参考：`docs/06-nginx-rewrite.md` - **URL 重写**：灵活的路由规则 - **重定向**：301/302 等状态码 - **请求修改**：添加/修改请求头 #### 2.5 压缩与缓存（优先级：中） 参考：`docs/07-nginx-compression-caching.md` - **Gzip/Brotli 压缩**：响应压缩 - **静态文件缓存**：文件描述符缓存 - **代理响应缓存**：缓存代理请求结果 #### 2.6 日志与监控（优先级：中） 参考：`docs/08-nginx-logging-monitoring.md` - **访问日志**：可定制日志格式 - **错误日志**：分级日志 - **状态监控**：实时状态端点（类似 stub_status） - **日志轮转**：内置支持 #### 2.7 安全与访问控制（优先级：高） 参考：`docs/09-nginx-security.md` - **IP 访问控制**：白名单/黑名单 - **请求限制**：速率限制、连接限制 - **安全头部**：自动添加安全相关 HTTP 头 - **基础认证**：Basic Auth 支持 #### 2.8 TCP/UDP Stream 代理（优先级：低） 参考：`docs/10-nginx-stream-tcp-udp.md` - **TCP 代理**：四层代理支持 - **UDP 代理**：UDP 流处理 - **Stream 负载均衡**：四层负载均衡 #### 2.9 邮件代理（优先级：最低，可选） 参考：`docs/11-nginx-mail-proxy.md` - IMAP/POP3/SMTP 代理（可后期实现或不实现） --- ## 三、配置文件设计 ### 设计原则 配置文件采用 YAML 格式，设计原则： 1. **简洁易用**：比 nginx.conf 更直观 2. **结构清晰**：层级明确，易于理解 3. **类型安全**：配置值有明确类型 4. **默认合理**：开箱即用，最小配置即可运行 ### 配置文件示例（仅供参考） ```yaml # lolly.yaml - 最简配置示例 server: listen: 8080 name: example.com # 静态文件服务 static: root: /var/www/html index: [index.html, index.htm] # 反向代理 proxy: - path: /api target: http://backend:8080 load_balance: round_robin # SSL/HTTPS ssl: cert: /etc/ssl/cert.pem key: /etc/ssl/key.pem # 日志配置 logging: access: /var/log/lolly/access.log error: /var/log/lolly/error.log level: info # 性能配置 performance: workers: auto # 自动匹配 CPU 核心数 max_connections: 10000 keepalive_timeout: 60s ``` ### 配置与 nginx 的对比 | nginx 配置 | lolly 配置（预期） | |------------|-------------------| | `worker_processes auto;` | `performance.workers: auto` | | `listen 80;` | `server.listen: 80` | | `root /var/www;` | `server.static.root: /var/www` | | `proxy_pass http://backend;` | `server.proxy.target: http://backend` | | `ssl_certificate cert.pem;` | `server.ssl.cert: cert.pem` | --- ## 四、架构设计要求 ### 4.1 Go 特性利用 充分利用 Go 语言特性： - **Goroutine**：每个连接一个 goroutine，天然高并发 - **Channel**：进程内通信、信号处理 - **标准库**：`net/http`、`net`、`io`、`sync` 等 - **Context**：请求超时控制、取消传播 - **接口**：模块化设计，接口抽象 ### 4.2 模块化设计 ``` lolly/ ├── cmd/ │ └── lolly/ │ └── main.go # 入口 ├── internal/ │ ├── config/ # 配置解析 │ ├── server/ # HTTP 服务器核心 │ ├── proxy/ # 反向代理 │ ├── loadbalance/ # 负载均衡算法 │ ├── ssl/ # SSL/TLS 支持 │ ├── rewrite/ # URL 重写 │ ├── cache/ # 缓存模块 │ ├── compression/ # 压缩模块 │ ├── logging/ # 日志模块 │ ├── security/ # 安全模块 │ ├── stream/ # TCP/UDP 代理 │ └── middleware/ # 中间件系统 ├── pkg/ │ └── utils/ # 公共工具 └── configs/ └── lolly.yaml # 默认配置 ``` ### 4.3 性能要求 - 单机支持数万并发连接 - 低内存消耗（相比 nginx 同等功能） - 静态文件高效传输（利用 `sendfile` 等优化） - 连接复用、缓冲池 --- ## 五、开发规范 ### 5.1 提交规范 每完成一个功能点提交一次，提交格式遵循最佳实践： ``` ():