From b294df740e167bea05f91c97e35d9270943d1e2a Mon Sep 17 00:00:00 2001 From: xfy Date: Tue, 7 Apr 2026 18:28:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E5=B9=B6?= =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20CHANGELOG=20v0.1.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README 添加徽章、完善特性说明、配置示例、项目结构、开发指南 CHANGELOG 记录初始版本 0.1.0 的完整变更历史 Co-Authored-By: Claude --- CHANGELOG.md | 105 ++++++++++++++++++ README.md | 308 +++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 380 insertions(+), 33 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3abaacf --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,105 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/), +and this project adheres to [Semantic Versioning](https://semver.org/). + +## [0.1.0] - 2026-04-07 + +### Added + +#### 核心功能 + +- 反向代理与负载均衡模块，支持轮询/加权/最少连接/一致性哈希算法 +- 故障转移 (next_upstream) 支持，自动切换备用上游 +- 文件缓存模块，支持缓存元数据管理 +- SSL/TLS 支持，强制 TLS 1.2+，支持证书配置 +- HTTP/3 (QUIC) 支持，含 0-RTT 与性能配置验证 +- 静态文件服务，支持多静态目录、路径前缀匹配、try_files 配置 + +#### 中间件系统 + +- URL 重写中间件，含 ReDoS 保护与循环检测 +- gzip/deflate/Brotli 响应压缩中间件 +- 请求体大小限制中间件 +- 自定义错误页面支持 +- 访问日志中间件，支持 nginx combined 格式 +- 安全中间件（访问控制、可信代理配置） + +#### 可观测性 + +- pprof 性能分析端点 +- 访问/错误日志分离，支持全局格式配置 +- 服务器状态 API + +#### 配置与构建 + +- 配置加载模块，支持 YAML/CLI 参数 +- 配置验证功能，多项验证函数 +- Makefile 构建脚本，含基准测试基础设施 +- 程序信号处理（优雅关闭、热升级） + +### Changed + +- 统一错误处理风格，空白标识符忽略明确不关心的返回值 +- 抽取网络工具函数到 netutil 包，移除冗余代码 +- 优化字符串构建方式，使用 fmt.Fprintf 替代冗余写法 +- 增强 FlagLast 语义与循环检测 + +### Fixed + +- 配置与代码实现不一致问题修复 +- Phase 8 问题修复与功能完善 + +### Documentation + +- 添加项目 README 文档 +- 核心模块 GoDoc 文档注释 +- nginx 模块翻译文档 (Lua/安全/API网关/动态配置/ACME 指南) +- 模块上下文文档 (AGENTS.md) +- 开发计划文档 + +### Tests + +- handler/logging/middleware/server/proxy/cache/loadbalance/security 等模块单元测试 +- 核心模块基准测试与回归检测 + +--- + +## Initial Development - 2026-04-02 to 2026-04-03 + +### Project Initialization + +- 项目初始化，添加 nginx 文档作为参考 +- Makefile 构建脚本与程序入口 +- 配置加载模块与 CLI 参数解析 +- 基础 HTTP 服务器核心功能 + +### Core Modules (Phase 1-4) + +- 应用逻辑抽取到 internal/app 包 +- 信号处理与配置结构完善 +- 反向代理与负载均衡实现 +- SSL/TLS 与安全中间件 +- 日志模块增强 +- 文件缓存实现 +- URL 重写与压缩中间件 + +### Performance & Integration (Phase 5-7) + +- 访问日志中间件 +- 性能优化与热升级 +- 访问控制与可信代理配置 +- Phase 6-7 功能完善与测试覆盖 + +### HTTP/3 & Advanced Features (Phase 8-9) + +- HTTP/3 (QUIC) 支持 +- 配置验证增强 +- Brotli 压缩支持 +- pprof 性能分析端点 +- 故障转移支持 +- 自定义错误页面 +- 请求体大小限制 +- try_files 配置支持 diff --git a/README.md b/README.md index 30d3c8c..8cc394f 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,23 @@ # Lolly +[![Go Version](https://img.shields.io/badge/Go-1.26%2B-00ADD8?style=flat&logo=go)](https://golang.org) +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) + 高性能 HTTP 服务器与反向代理，使用 Go 语言编写。 -基于 [fasthttp](https://github.com/valyala/fasthttp) 构建，提供比标准 net/http 更高的性能。支持 HTTP/3、WebSocket、虚拟主机、多种负载均衡算法，以及完整的安全与性能优化特性。 +基于 [fasthttp](https://github.com/valyala/fasthttp) 构建，提供比标准 net/http 更高的性能。支持 HTTP/3 (QUIC)、WebSocket、虚拟主机、多种负载均衡算法、故障转移，以及完整的安全与性能优化特性。 ## 特性 ### 核心功能 -- **静态文件服务** - 零拷贝传输（sendfile）、文件缓存、预压缩支持 -- **反向代理** - 完整的代理功能，支持请求头/响应头修改、超时控制 +- **静态文件服务** - 零拷贝传输（sendfile）、文件缓存、预压缩支持、try_files 配置 +- **反向代理** - 完整的代理功能，支持请求头/响应头修改、超时控制、故障转移（next_upstream） - **HTTP/3 (QUIC)** - 基于 quic-go，支持 0-RTT 连接 - **WebSocket** - 完整的 WebSocket 代理支持 - **虚拟主机** - 单进程支持多域名独立配置 - **TCP/UDP Stream** - 四层代理，支持 MySQL、Redis 等服务 +- **自定义错误页面** - 支持为特定状态码配置自定义错误页面 ### 负载均衡 @@ -25,13 +29,27 @@ | IP Hash | IP 哈希，同一客户端始终路由到同一目标 | | Consistent Hash | 一致性哈希，支持虚拟节点，最小化节点变更影响 | +### 故障转移 + +支持 `next_upstream` 配置，当后端返回特定错误状态码（502/503/504）或连接失败时，自动重试下一个可用后端： + +```yaml +proxy: + - path: "/api" + next_upstream: + tries: 3 + http_codes: [502, 503, 504] +``` + ### 安全 - **访问控制** - IP/CIDR 白名单与黑名单 - **速率限制** - 令牌桶与滑动窗口算法 +- **连接限制** - 单 IP 并发连接数限制 - **认证** - Basic Auth，支持 bcrypt 与 argon2id - **安全头部** - HSTS、X-Frame-Options、CSP、Referrer-Policy - **SSL/TLS** - OCSP Stapling、TLS 1.2/1.3、加密套件配置 +- **请求体限制** - 可配置全局和路径级别的请求体大小限制 ### 性能优化 @@ -39,6 +57,8 @@ - **文件缓存** - LRU 淘汰策略，内存上限控制 - **连接池** - 空闲连接复用，减少连接建立开销 - **零拷贝** - 大文件传输使用 sendfile 系统调用 +- **代理缓存** - 支持缓存后端响应，防止缓存击穿 +- **PGO 优化** - 支持 Profile-Guided Optimization 构建 ### 运维 @@ -47,6 +67,7 @@ - **日志轮转** - USR1 信号触发，重新打开日志文件 - **优雅关闭** - QUIT 信号触发，等待请求完成 - **状态监控** - 内置状态端点，统计连接数、请求数、流量 +- **pprof 端点** - 内置性能分析端点，支持 PGO 优化 ## 安装 @@ -60,9 +81,16 @@ cd lolly # 本地构建 make build -# 生产构建（优化体积） +# 生产构建（体积优化） make build-prod +# 性能构建（最大运行时性能） +make build-perf + +# PGO 构建（需先收集 profile） +make pgo-collect # 查看收集指南 +make build-pgo + # 跨平台构建 make build-all ``` @@ -87,14 +115,28 @@ make build-all ## 配置 -配置文件使用 YAML 格式。以下是基本示例： +配置文件使用 YAML 格式。以下是完整配置示例： ```yaml server: listen: ":8080" + name: "example.com" + read_timeout: 30s + write_timeout: 30s + idle_timeout: 120s + max_conns_per_ip: 100 + max_requests_per_conn: 1000 + client_max_body_size: "10MB" + static: - root: "/var/www/html" - index: ["index.html", "index.htm"] + - path: "/" + root: "/var/www/html" + index: ["index.html", "index.htm"] + try_files: ["$uri", "$uri/", "/index.html"] + try_files_pass: false + - path: "/assets/" + root: "/var/www/assets" + proxy: - path: "/api" targets: @@ -107,27 +149,103 @@ server: interval: 10s path: "/health" timeout: 5s + next_upstream: + tries: 3 + http_codes: [502, 503, 504] + timeout: + connect: 5s + read: 30s + write: 30s + headers: + set_request: + X-Forwarded-For: "$remote_addr" + X-Real-IP: "$remote_addr" + set_response: + X-Proxy-By: "lolly" + cache: + enabled: true + max_age: 5m + cache_lock: true + stale_while_revalidate: 1m + client_max_body_size: "50MB" + ssl: cert: "/etc/ssl/certs/server.crt" key: "/etc/ssl/private/server.key" + cert_chain: "/etc/ssl/certs/chain.crt" + protocols: ["TLSv1.2", "TLSv1.3"] + ocsp_stapling: true + hsts: + max_age: 31536000 + include_sub_domains: true + preload: false + + security: + access: + allow: ["192.168.1.0/24", "10.0.0.0/8"] + deny: [] + default: "deny" + trusted_proxies: ["172.16.0.0/16"] + rate_limit: + request_rate: 100 + burst: 200 + conn_limit: 50 + algorithm: "token_bucket" + auth: + type: "basic" + require_tls: true + algorithm: "bcrypt" + realm: "Secure Area" + users: + - name: "admin" + password: "$2y$10$N9qo8uLOickgx2ZMRZoMy..." + headers: + x_frame_options: "DENY" + x_content_type_options: "nosniff" + content_security_policy: "default-src 'self'" + referrer_policy: "strict-origin-when-cross-origin" + error_page: + pages: + 404: "/var/www/errors/404.html" + 500: "/var/www/errors/500.html" + default: "/var/www/errors/error.html" + + rewrite: + - pattern: "^/old/(.*)$" + replacement: "/new/$1" + flag: "permanent" + compression: type: "gzip" level: 6 min_size: 1024 - security: - rate_limit: - request_rate: 100 - burst: 200 + types: ["text/html", "text/css", "application/javascript", "application/json"] + gzip_static: true + gzip_static_extensions: [".gz", ".br"] http3: enabled: true listen: ":443" - max_streams: 100 + max_streams: 1000 + idle_timeout: 30s + enable_0rtt: true + +stream: + - listen: ":3306" + protocol: "tcp" + upstream: + targets: + - addr: "mysql1:3306" + weight: 3 + - addr: "mysql2:3306" + weight: 1 + load_balance: "round_robin" logging: format: "json" access: path: "/var/log/lolly/access.log" + format: "combined" error: path: "/var/log/lolly/error.log" level: "info" @@ -135,10 +253,27 @@ logging: performance: goroutine_pool: enabled: true - max_workers: 1000 + max_workers: 10000 + min_workers: 100 + idle_timeout: 60s file_cache: - max_entries: 10000 - max_size: 100MB + max_entries: 50000 + max_size: 268435456 # 256MB + inactive: 60s + transport: + max_idle_conns: 1000 + max_idle_conns_per_host: 100 + idle_conn_timeout: 90s + max_conns_per_host: 500 + +monitoring: + status: + path: "/status" + allow: ["127.0.0.1", "10.0.0.0/8"] + pprof: + enabled: false + path: "/debug/pprof" + allow: ["127.0.0.1"] ``` 完整配置说明请参考源码 `internal/config/config.go`。 @@ -147,24 +282,86 @@ performance: ``` internal/ - app/ # 应用入口、信号处理、生命周期 - config/ # 配置加载、验证、默认值 - server/ # HTTP 服务器、虚拟主机、Goroutine 池 - handler/ # 路由器、静态文件处理器 - proxy/ # 反向代理、WebSocket、健康检查 - loadbalance/ # 负载均衡算法 - middleware/ # 中间件链 - compression/ # Gzip/Brotli 压缩 - security/ # 访问控制、限流、认证、安全头部 - rewrite/ # URL 重写 - accesslog/ # 访问日志 - http3/ # HTTP/3 服务器 - stream/ # TCP/UDP Stream 代理 - ssl/ # TLS 配置、OCSP Stapling - cache/ # 文件缓存、代理缓存 - logging/ # 日志系统 +├── app/ # 应用入口、信号处理、生命周期 +│ └── app.go # 主程序逻辑 +├── config/ # 配置加载、验证、默认值 +│ ├── config.go # 配置结构定义 +│ ├── defaults.go # 默认配置 +│ └── validate.go # 配置验证 +├── server/ # HTTP 服务器核心 +│ ├── server.go # 服务器实现 +│ ├── vhost.go # 虚拟主机管理 +│ ├── pool.go # Goroutine 池 +│ ├── status.go # 状态端点 +│ ├── pprof.go # pprof 端点 +│ └── upgrade.go # 热升级管理 +├── handler/ # 请求处理器 +│ ├── router.go # 路由器 +│ ├── static.go # 静态文件处理 +│ ├── sendfile.go # 零拷贝传输 +│ └── errorpage.go # 错误页面管理 +├── proxy/ # 反向代理 +│ ├── proxy.go # 代理核心逻辑 +│ ├── websocket.go # WebSocket 代理 +│ └── health.go # 健康检查 +├── loadbalance/ # 负载均衡算法 +│ ├── balancer.go # 算法实现 +│ └── consistent_hash.go # 一致性哈希 +├── middleware/ # 中间件链 +│ ├── middleware.go # 中间件接口 +│ ├── compression/ # Gzip/Brotli 压缩 +│ ├── security/ # 访问控制、限流、认证、安全头部 +│ ├── rewrite/ # URL 重写 +│ ├── accesslog/ # 访问日志 +│ ├── bodylimit/ # 请求体大小限制 +│ └── errorintercept/ # 错误页面拦截 +├── http3/ # HTTP/3 服务器 +│ ├── server.go # QUIC 服务器 +│ └── adapter.go # HTTP/3 适配器 +├── stream/ # TCP/UDP Stream 代理 +│ └── stream.go # 四层代理实现 +├── ssl/ # TLS 配置 +│ ├── ssl.go # TLS 管理器 +│ └── ocsp.go # OCSP Stapling +├── cache/ # 缓存系统 +│ └── file_cache.go # 文件缓存、代理缓存 +├── logging/ # 日志系统 +│ └── logging.go # 结构化日志 +├── netutil/ # 网络工具 +│ ├── ip.go # IP 解析 +│ └── url.go # URL 处理 +└── benchmark/ # 基准测试工具 + └── tools/ # 测试辅助工具 ``` +### 核心设计 + +#### 中间件链 + +请求处理流程： + +``` +Request → AccessLog → AccessControl → RateLimiter → Auth → BodyLimit → Rewrite → Compression → SecurityHeaders → ErrorIntercept → Handler +``` + +#### 负载均衡 + +所有负载均衡器实现 `Balancer` 接口，支持健康目标过滤和故障转移排除： + +```go +type Balancer interface { + Select(targets []*Target) *Target + SelectExcluding(targets []*Target, excluded []*Target) *Target +} +``` + +#### 代理缓存 + +支持： +- 缓存锁（防止缓存击穿） +- 过期缓存复用（stale-while-revalidate） +- 后台刷新 + ## 信号处理 | 信号 | 行为 | @@ -175,7 +372,14 @@ internal/ | SIGUSR1 | 重新打开日志文件 | | SIGUSR2 | 热升级 | -## 测试 +## 开发 + +### 环境要求 + +- Go 1.26+ +- make + +### 命令 ```bash # 运行测试 @@ -187,10 +391,28 @@ make test-cover # 基准测试 make bench +# 基准测试（统计模式） +make bench-stat + +# 对比基准结果 +make bench-compare + # 代码检查 make check + +# 格式化 +make fmt + +# 静态分析 +make lint ``` +### 项目统计 + +- Go 文件：85+ +- 提交次数：75+ +- 测试覆盖：各核心模块均有完整测试 + ## 性能 基于 fasthttp，相比标准 net/http 有显著性能提升： @@ -199,6 +421,21 @@ make check - 优化的事件循环 - 高效的连接池管理 - 零拷贝传输 +- Goroutine 池复用 + +### PGO 优化 + +支持 Profile-Guided Optimization 构建，可获得额外 5-15% 性能提升： + +```bash +# 1. 启用 pprof 端点 +# 2. 运行代表性工作负载 +# 3. 收集 CPU profile +curl http://localhost:8080/debug/pprof/profile?seconds=30 > default.pgo + +# 4. 使用 PGO 构建 +make build-pgo +``` 建议生产环境配置： @@ -207,9 +444,11 @@ performance: goroutine_pool: enabled: true max_workers: 10000 + min_workers: 100 + idle_timeout: 60s file_cache: max_entries: 50000 - max_size: 256MB + max_size: 268435456 # 256MB transport: max_idle_conns: 1000 max_idle_conns_per_host: 100 @@ -226,6 +465,8 @@ performance: | 扩展方式 | Go 代码 | C 模块/Lua | | 部署 | 单二进制 | 需安装 | | 内存占用 | 较低 | 较低 | +| 故障转移 | 支持 | 支持 | +| 代理缓存 | 支持 | 支持 | ## 依赖 @@ -233,6 +474,7 @@ performance: - [quic-go](https://github.com/quic-go/quic-go) - QUIC/HTTP/3 实现 - [zerolog](https://github.com/rs/zerolog) - 高性能日志库 - [klauspost/compress](https://github.com/klauspost/compress) - 压缩算法 +- [fasthttp/router](https://github.com/fasthttp/router) - 高性能路由器 ## 许可证