docs: 更新 AGENTS.md 文档，添加新模块说明

- 更新所有 AGENTS.md 时间戳至 2026-04-24 - 添加 converter、e2e、testutil 模块文档 - 更新 README.md：nginx 配置导入、stale 缓存功能说明 - 更新项目统计：132 Go 文件，157 测试文件 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-24 18:24:31 +08:00 · 2026-04-24 18:24:31 +08:00 · 2122067efb
commit 2122067efb
parent f507fe0951
10 changed files with 287 additions and 14 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -1,4 +1,4 @@
-<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->

 # lolly

--- a/README.md
+++ b/README.md
@ -11,7 +11,7 @@

 ### 核心功能

- **静态文件服务** - 零拷贝传输（sendfile）、文件缓存、预压缩支持、try_files 配置、符号链接安全检查
+- **静态文件服务** - 零拷贝传输（sendfile）、文件缓存、预压缩支持、try_files 配置、符号链接安全检查、ETag 和 304 Not Modified 支持
 - **反向代理** - 完整的代理功能，支持请求头/响应头修改、超时控制、故障转移（next_upstream）、Location/Refresh 头改写
 - **HTTP/3 (QUIC)** - 基于 quic-go，支持 0-RTT 连接
 - **WebSocket** - 完整的 WebSocket 代理支持
@ -24,6 +24,7 @@
 - **Lua 脚本** - 基于 gopher-lua 的可编程扩展，支持 nginx-lua 兼容 API（ngx.var/ngx.ctx/ngx.req/ngx.resp/ngx.timer/ngx.location.capture/ngx.shared.DICT）
 - **GeoIP 过滤** - 基于 MaxMind GeoIP2 的国家/地区访问控制
 - **自定义错误页面** - 支持为特定状态码配置自定义错误页面
+- **nginx 配置导入** - 支持将 nginx 配置文件转换为 lolly YAML 配置

 ### 负载均衡

@ -116,10 +117,33 @@ make build-all
 # 生成默认配置
 ./bin/lolly --generate-config -o lolly.yaml

+# 导入 nginx 配置
+./bin/lolly --import /etc/nginx/nginx.conf -o lolly.yaml
+./bin/lolly -i nginx.conf  # 简写形式
+
 # 显示版本
 ./bin/lolly -v
 ```

+### nginx 配置导入
+
+lolly 支持将 nginx 配置文件转换为 YAML 格式：
+
+```bash
+# 导入 nginx 配置并输出到文件
+./bin/lolly --import nginx.conf -o lolly.yaml
+
+# 导入后会显示转换警告（不支持的指令）
+```
+
+支持的 nginx 指令：
+- `server` 块：listen、server_name、ssl_certificate、ssl_certificate_key
+- `location` 块：proxy_pass、root、alias、index、try_files
+- `upstream` 块：server（含 weight、max_fails、fail_timeout、backup、down）、least_conn、ip_hash、hash、random
+- 其他：gzip、gzip_types、gzip_min_length、client_max_body_size、access_log、error_log、rewrite、return（301/302）、error_page、auth_basic
+
+不支持的指令会在转换时显示警告，需要手动处理。
+
 ## 配置

 配置文件使用 YAML 格式。以下是完整配置示例：
@ -441,6 +465,8 @@ type Balancer interface {
 - **缓存锁**（cache_lock）- 防止缓存击穿，同一缓存键只允许一个请求访问后端
 - **过期复用**（stale-while-revalidate）- 允许在后台刷新时返回过期缓存
 - **后台刷新** - 异步更新缓存，不影响请求响应时间
+- **错误回退**（stale-if-error）- 后端错误时返回过期缓存
+- **超时回退**（stale-if-timeout）- 后端超时时返回过期缓存

 ## Lua 脚本

@ -968,8 +994,8 @@ make lint

 ### 项目统计

- Go 文件：110
- 测试文件：113
+- Go 文件：132
+- 测试文件：157
 - 核心模块均有完整测试和性能基准测试
 - 中文代码注释

--- a/internal/AGENTS.md
+++ b/internal/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->

 # internal

@ -10,26 +10,30 @@

 | Directory | Purpose |
 |-----------|---------|
-| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息） |
+| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息、nginx 配置导入） |
 | `benchmark/` | 基准测试基础设施（Mock 后端、负载生成器、回归检测） |
-| `cache/` | 文件缓存模块（缓存存储、过期管理） |
+| `cache/` | 文件缓存模块（缓存存储、过期管理、stale 回退） |
 | `config/` | 配置解析、验证和默认值生成 |
-| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） |
+| `converter/` | 配置转换器（nginx 配置导入） |
+| `e2e/` | 端到端测试（完整功能验证、容器化测试） |
+| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile、ETag） |
 | `http2/` | HTTP/2 协议支持（ALPN 协商、fasthttp 适配） |
 | `http3/` | HTTP/3 (QUIC) 协议支持（fasthttp 适配、0-RTT） |
 | `integration/` | 集成测试（多模块端到端协作验证） |
 | `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） |
 | `logging/` | 日志系统（zerolog 初始化、访问日志） |
 | `lua/` | Lua 脚本引擎（OpenResty 风格沙箱、ngx API） |
+| `matcher/` | 路径匹配器（精确、前缀、正则匹配） |
 | `middleware/` | 中间件框架（接口定义、链式组合） |
 | `mimeutil/` | MIME 类型检测（扩展名映射、类型推断） |
 | `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） |
-| `proxy/` | 反向代理模块（HTTP/WebSocket 代理） |
+| `proxy/` | 反向代理模块（HTTP/WebSocket 代理、DNS 解析） |
 | `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） |
 | `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 |
-| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） |
+| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling、Session Tickets） |
 | `sslutil/` | SSL 工具函数（证书池加载、CA 信任链） |
 | `stream/` | TCP/UDP Stream 代理模块 |
+| `testutil/` | 测试工具函数（Mock、断言助手） |
 | `utils/` | HTTP 错误处理（统一错误响应助手） |
 | `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） |

--- a/internal/app/AGENTS.md
+++ b/internal/app/AGENTS.md
@ -1,16 +1,17 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->

 # app

 ## Purpose
-应用程序入口包，提供启动逻辑、信号处理、版本信息显示和配置生成功能。
+应用程序入口包，提供启动逻辑、信号处理、版本信息显示、配置生成和 nginx 配置导入功能。

 ## Key Files

 | File | Description |
 |------|-------------|
 | `app.go` | 核心逻辑：Run 入口、startServer、printVersion、generateConfig |
+| `import.go` | nginx 配置导入：ImportNginxConfig、转换警告处理 |
 | `app_test.go` | 单元测试：版本显示、配置生成、服务器启动测试 |

 ## For AI Agents
@ -20,6 +21,7 @@
 - `Run()` 是程序入口函数，返回退出码
 - 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止（等待 30s）
 - `generateConfig()` 生成默认 YAML 配置，调用 `config.DefaultConfig()`
+- `ImportNginxConfig()` 将 nginx 配置转换为 lolly YAML 格式

 ### Testing Requirements
 - 测试文件 `app_test.go` 包含启动逻辑测试
@ -36,5 +38,6 @@
 ### Internal
 - `../config/` - 配置加载和验证
 - `../server/` - HTTP 服务器创建和启动
+- `../converter/nginx/` - nginx 配置转换器

 <!-- MANUAL: -->
--- a/internal/converter/AGENTS.md
+++ b/internal/converter/AGENTS.md
@ -0,0 +1,35 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
+
+# converter
+
+## Purpose
+配置转换器模块，提供外部配置格式到 lolly YAML 配置的转换能力。
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `nginx/` | nginx 配置转换器（nginx.conf → lolly.yaml） |
+
+## For AI Agents
+
+### Working In This Directory
+- 转换器将外部配置格式解析为 `config.Config` 结构体
+- 转换过程中可能产生警告（不支持的指令），需要收集并展示给用户
+- 每种外部格式有独立的子包实现
+
+### Testing Requirements
+- 运行测试：`go test ./internal/converter/...`
+- 测试应覆盖各种配置场景和边界情况
+
+### Common Patterns
+- 转换器返回 `(*config.Config, []Warning, error)` 三元组
+- 警告信息包含文件名、行号和描述
+
+## Dependencies
+
+### Internal
+- `../config/` - 配置结构体定义
+
+<!-- MANUAL: -->
--- a/internal/converter/nginx/AGENTS.md
+++ b/internal/converter/nginx/AGENTS.md
@ -0,0 +1,70 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
+
+# nginx
+
+## Purpose
+nginx 配置转换器，将 nginx.conf 格式转换为 lolly YAML 配置。支持 server、location、upstream、proxy_pass 等核心指令。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `parser.go` | nginx 配置解析器：词法分析、语法树构建 |
+| `converter.go` | 配置转换器：nginx AST → lolly Config |
+| `parser_test.go` | 解析器测试：各种 nginx 配置格式 |
+| `converter_test.go` | 转换器测试：指令映射、警告生成 |
+
+## For AI Agents
+
+### Working In This Directory
+- 解析器将 nginx 配置文本解析为 `NginxConfig` AST
+- 转换器遍历 AST 生成 `config.Config` 结构体
+- 不支持的指令会生成 `Warning` 而非错误，允许部分转换
+- location 匹配类型映射：`=` → `exact`，`^~` → `prefix_priority`，`~` → `regex`，`~*` → `regex_caseless`
+
+### Testing Requirements
+- 运行测试：`go test ./internal/converter/nginx/...`
+- 测试覆盖：完整配置、部分配置、错误处理
+
+### Common Patterns
+```go
+// 解析 nginx 配置
+parser := nginx.NewParser(content)
+cfg, err := parser.Parse()
+
+// 转换为 lolly 配置
+result, err := nginx.Convert(cfg)
+// result.Config - 转换后的配置
+// result.Warnings - 转换警告
+```
+
+### 支持的 nginx 指令
+
+| 指令 | 转换说明 |
+|------|----------|
+| `server` | 转换为 `ServerConfig` |
+| `listen` | 转换为 `listen` 字段 |
+| `server_name` | 转换为 `name`/`server_names` |
+| `location` | 转换为 `ProxyConfig` 或 `StaticConfig` |
+| `proxy_pass` | 转换为代理目标 |
+| `root`/`alias` | 转换为静态文件根目录 |
+| `upstream` | 转换为负载均衡目标列表 |
+| `gzip` | 转换为压缩配置 |
+| `ssl_certificate` | 转换为 SSL 证书配置 |
+| `rewrite` | 转换为 URL 重写规则 |
+| `return 301/302` | 转换为重定向规则 |
+
+### 不支持的指令（生成警告）
+
+- `if`、`map`、`set` - 条件逻辑不支持
+- `limit_req`、`limit_conn` - 使用 `rate_limit` 配置替代
+- `add_header` - 使用 `security.headers` 配置替代
+- `auth_request` - 使用 `security.auth_request` 配置替代
+
+## Dependencies
+
+### Internal
+- `../../config/` - 配置结构体定义
+
+<!-- MANUAL: -->
--- a/internal/e2e/AGENTS.md
+++ b/internal/e2e/AGENTS.md
@ -0,0 +1,72 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
+
+# e2e
+
+## Purpose
+端到端测试模块，验证完整功能的集成测试。使用 testcontainers 启动真实后端服务进行测试。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `e2e_test.go` | 测试入口和通用测试辅助函数 |
+| `cache_e2e_test.go` | 代理缓存端到端测试 |
+| `healthcheck_e2e_test.go` | 健康检查端到端测试 |
+| `http2_e2e_test.go` | HTTP/2 端到端测试 |
+| `loadbalance_e2e_test.go` | 负载均衡端到端测试 |
+| `proxy_e2e_test.go` | 反向代理端到端测试 |
+| `ssl_e2e_test.go` | SSL/TLS 端到端测试 |
+| `static_e2e_test.go` | 静态文件服务端到端测试 |
+| `websocket_e2e_test.go` | WebSocket 代理端到端测试 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `testutil/` | 测试工具函数（容器、配置、证书） |
+| `certs/` | 测试用 TLS 证书 |
+| `configs/` | 测试用配置文件 |
+
+## For AI Agents
+
+### Working In This Directory
+- 端到端测试需要 Docker 环境运行 testcontainers
+- 测试启动真实 lolly 服务器和 mock 后端
+- 使用 `testutil` 包提供的辅助函数创建测试环境
+- 测试名称遵循 `TestE2E_<功能>_<场景>` 格式
+
+### Testing Requirements
+- 运行测试：`go test ./internal/e2e/... -tags=e2e`
+- 需要 Docker 运行
+- 测试可能需要较长时间（启动容器）
+
+### Common Patterns
+```go
+// 创建测试环境
+env := testutil.NewTestEnv(t)
+defer env.Cleanup()
+
+// 启动 lolly 服务器
+env.StartServer(config)
+defer env.StopServer()
+
+// 启动 mock 后端
+backend := env.StartMockBackend()
+defer backend.Close()
+
+// 发送测试请求
+resp := env.Request("GET", "/api/test", nil)
+```
+
+## Dependencies
+
+### Internal
+- `./testutil/` - 测试工具函数
+- `../server/` - HTTP 服务器
+- `../config/` - 配置加载
+
+### External
+- `github.com/testcontainers/testcontainers-go` - 容器化测试
+
+<!-- MANUAL: -->
--- a/internal/e2e/testutil/AGENTS.md
+++ b/internal/e2e/testutil/AGENTS.md
@ -0,0 +1,60 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
+
+# testutil
+
+## Purpose
+端到端测试工具包，提供测试环境搭建、容器管理、证书生成、配置辅助等功能。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `setup.go` | 测试环境初始化：NewTestEnv、Cleanup |
+| `config.go` | 配置辅助：创建测试配置、临时文件 |
+| `constants.go` | 测试常量：默认端口、超时时间 |
+| `container.go` | 容器管理：启动 mock 后端、清理容器 |
+| `container_test.go` | 容器管理测试 |
+| `certs.go` | 证书生成：自签名证书、CA 证书 |
+| `ssl.go` | SSL 辅助：TLS 配置、证书验证 |
+| `websocket.go` | WebSocket 辅助：WS 客户端、消息收发 |
+| `concurrent.go` | 并发测试辅助：并发请求、结果收集 |
+
+## For AI Agents
+
+### Working In This Directory
+- `NewTestEnv(t)` 创建测试环境，返回清理函数
+- 测试环境自动管理临时文件和端口分配
+- 容器化测试需要 Docker 运行
+- 证书生成用于 TLS 测试
+
+### Testing Requirements
+- 运行测试：`go test ./internal/e2e/testutil/...`
+- 部分测试需要 Docker
+
+### Common Patterns
+```go
+// 创建测试环境
+env := testutil.NewTestEnv(t)
+defer env.Cleanup()
+
+// 创建临时配置文件
+cfgPath := env.CreateConfig(serverConfig)
+
+// 启动容器化后端
+container := env.StartContainer(containerConfig)
+defer container.Terminate()
+
+// 生成测试证书
+cert, key := env.GenerateCertificate()
+```
+
+## Dependencies
+
+### Internal
+- `../../config/` - 配置结构体
+
+### External
+- `github.com/testcontainers/testcontainers-go` - 容器管理
+
+<!-- MANUAL: -->
--- a/internal/http2/AGENTS.md
+++ b/internal/http2/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
+<!-- Generated: 2026-04-09 | Updated: 2026-04-24 -->

 # http2

@ -15,6 +15,7 @@ HTTP/2 协议支持模块，基于 golang.org/x/net/http2 实现，提供 ALPN
 | `server_test.go` | 服务器测试：创建、启动、关闭测试 |
 | `adapter_test.go` | 适配器测试：头部转换、请求体处理测试 |
 | `integration_test.go` | 集成测试：端到端 HTTP/2 请求处理 |
+| `integration_tls_test.go` | TLS 集成测试：HTTPS 连接测试 |

 ## For AI Agents

--- a/internal/lua/AGENTS.md
+++ b/internal/lua/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
+<!-- Generated: 2026-04-13 | Updated: 2026-04-24 -->

 # lua

@ -22,6 +22,8 @@ Lua 脚本嵌入引擎，提供类似 OpenResty 的 Lua 沙箱环境，支持请
 | `cache.go` | 字节码缓存：预编译脚本缓存 |
 | `register.go` | API 注册：ngx 表初始化 |
 | `filter_writer.go` | 响应过滤器：body_filter_by_lua |
+| `boundary_test.go` | 边界条件测试：错误处理、资源限制 |
+| `scheduler_test.go` | 调度器测试：定时器、协程调度 |
 | `api_*.go` | ngx API 实现：req、resp、ctx、var、log、timer、socket、location、shared_dict |

 ## For AI Agents