diff --git a/docs/config/advanced/AGENTS.md b/docs/config/advanced/AGENTS.md new file mode 100644 index 0000000..aac78ac --- /dev/null +++ b/docs/config/advanced/AGENTS.md @@ -0,0 +1,44 @@ + + + +# advanced + +## Purpose +高级功能配置示例目录，包含 WebSocket、gRPC、HTTP/2、HTTP/3、Stream 代理等高级协议配置。 + +## Key Files + +| File | Description | +|------|-------------| +| `websocket.conf` | WebSocket 代理配置：Upgrade 头处理、长连接支持 | +| `grpc.conf` | gRPC 代理配置：HTTP/2 透传、超时设置 | +| `http2.conf` | HTTP/2 配置：多路复用、服务器推送、流控制 | +| `http3.conf` | HTTP/3 (QUIC) 配置：UDP 传输、0-RTT 连接 | +| `stream-tcp.conf` | TCP Stream 代理：四层负载均衡、连接复用 | +| `stream-udp.conf` | UDP Stream 代理：DNS 负载均衡、无状态转发 | + +## For AI Agents + +### Working In This Directory +- HTTP/2 需要 HTTPS，HTTP/3 需要 QUIC 支持 +- Stream 代理工作在四层（TCP/UDP），不解析 HTTP +- WebSocket 需要正确处理 Upgrade 和 Connection 头 + +### Testing Requirements +- 高级协议通过集成测试验证 +- HTTP/3 测试需要 QUIC 客户端支持 + +### Common Patterns +- WebSocket：`proxy_set_header Upgrade $http_upgrade` +- gRPC：`grpc_pass grpc://upstream` +- Stream：`listen 12345` 在 stream 块中 + +## Dependencies + +### Internal +- `../../../internal/http2/` - HTTP/2 实现 +- `../../../internal/http3/` - HTTP/3 (QUIC) 实现 +- `../../../internal/stream/` - Stream 代理实现 +- `../../../internal/proxy/websocket.go` - WebSocket 代理 + + diff --git a/docs/config/basic/AGENTS.md b/docs/config/basic/AGENTS.md new file mode 100644 index 0000000..c53016d --- /dev/null +++ b/docs/config/basic/AGENTS.md @@ -0,0 +1,38 @@ + + + +# basic + +## Purpose +基础配置示例目录，包含静态文件服务器、反向代理、虚拟主机等核心功能的 nginx 配置示例。 + +## Key Files + +| File | Description | +|------|-------------| +| `static-server.conf` | 静态文件服务器配置：sendfile、try_files、缓存策略 | +| `reverse-proxy.conf` | 反向代理配置：proxy_pass、超时设置、缓冲配置 | +| `virtual-host.conf` | 虚拟主机配置：多域名、server_name 匹配 | + +## For AI Agents + +### Working In This Directory +- 每个配置文件包含 Lolly YAML 对照注释 +- 修改基础功能时应参考这些配置了解 nginx 兼容需求 +- 配置文件使用 nginx 指令风格，注释说明 Lolly 对应项 + +### Testing Requirements +- 配置示例通过集成测试验证功能兼容性 +- 运行测试：`go test ./internal/integration/...` + +### Common Patterns +- 配置对照格式：nginx 指令 ↔ Lolly YAML 配置项 +- 注释使用 `# Lolly 对应:` 标记映射关系 + +## Dependencies + +### Internal +- `../../../internal/config/` - Lolly 配置解析实现 +- `../../../internal/handler/` - 静态文件处理器 + + diff --git a/docs/config/caching/AGENTS.md b/docs/config/caching/AGENTS.md new file mode 100644 index 0000000..4a7b9d0 --- /dev/null +++ b/docs/config/caching/AGENTS.md @@ -0,0 +1,40 @@ + + + +# caching + +## Purpose +缓存配置示例目录，包含代理缓存、Gzip 压缩、Brotli 压缩等性能优化配置。 + +## Key Files + +| File | Description | +|------|-------------| +| `proxy-cache.conf` | 代理缓存：响应缓存、缓存键、过期策略 | +| `gzip.conf` | Gzip 压缩：文本压缩、压缩级别、MIME 类型 | +| `brotli.conf` | Brotli 压缩：更高压缩率、现代浏览器支持 | + +## For AI Agents + +### Working In This Directory +- 代理缓存适用于后端响应不频繁变化的场景 +- Gzip 是通用压缩方案，所有浏览器支持 +- Brotli 压缩率更高，但需要浏览器支持 +- 压缩级别建议 4-6，平衡 CPU 和压缩率 + +### Testing Requirements +- 缓存配置通过集成测试验证 +- 压缩测试验证 Content-Encoding 头 + +### Common Patterns +- 缓存键：`$scheme$host$request_uri` +- 缓存控制：`X-Cache-Status` 头 +- 压缩条件：`gzip_types text/plain text/css application/json` + +## Dependencies + +### Internal +- `../../../internal/cache/` - 文件缓存实现 +- `../../../internal/middleware/compression/` - 压缩中间件 + + diff --git a/docs/config/load-balancing/AGENTS.md b/docs/config/load-balancing/AGENTS.md new file mode 100644 index 0000000..186f6d0 --- /dev/null +++ b/docs/config/load-balancing/AGENTS.md @@ -0,0 +1,43 @@ + + + +# load-balancing + +## Purpose +负载均衡配置示例目录，包含轮询、加权、最少连接、IP 哈希、一致性哈希等负载均衡策略配置。 + +## Key Files + +| File | Description | +|------|-------------| +| `round-robin.conf` | 轮询负载均衡：默认策略、均匀分配 | +| `weighted.conf` | 加权轮询：按权重分配流量、服务器能力差异 | +| `least-conn.conf` | 最少连接：动态分配到连接最少的服务器 | +| `ip-hash.conf` | IP 哈希：会话保持、同一客户端固定后端 | +| `consistent-hash.conf` | 一致性哈希：分布式缓存、节点增减影响最小化 | + +## For AI Agents + +### Working In This Directory +- 默认策略是轮询（round-robin） +- 加权适用于服务器性能差异场景 +- 最少连接适用于长连接场景 +- IP 哈希适用于需要会话保持的场景 +- 一致性哈希适用于分布式缓存场景 + +### Testing Requirements +- 负载均衡策略通过单元测试和集成测试验证 +- 运行测试：`go test ./internal/loadbalance/...` + +### Common Patterns +- 权重配置：`weight=N` 参数 +- 健康检查：`max_fails`, `fail_timeout` +- 备用服务器：`backup` 标记 + +## Dependencies + +### Internal +- `../../../internal/loadbalance/` - 负载均衡策略实现 +- `../../../internal/resolver/` - 动态 DNS 解析 + + diff --git a/docs/config/lua/AGENTS.md b/docs/config/lua/AGENTS.md new file mode 100644 index 0000000..6180ad7 --- /dev/null +++ b/docs/config/lua/AGENTS.md @@ -0,0 +1,45 @@ + + + +# lua + +## Purpose +Lua 配置示例目录，包含 Lua 脚本集成、各阶段钩子、共享字典等 Lua 功能配置。 + +## Key Files + +| File | Description | +|------|-------------| +| `basic-lua.conf` | 基础 Lua 配置：脚本加载、基本语法 | +| `access-by-lua.conf` | access 阶段 Lua：访问控制、认证检查 | +| `content-by-lua.conf` | content 阶段 Lua：动态内容生成 | +| `balancer-by-lua.conf` | 负载均衡 Lua：动态上游选择 | +| `shared-dict.conf` | 共享字典：进程间数据共享、缓存 | + +## For AI Agents + +### Working In This Directory +- Lua 钩子按 nginx 处理阶段执行：rewrite → access → content +- 共享字典用于进程间数据共享，适合缓存场景 +- Lua 代码在沙箱中执行，有安全限制 +- 参考 OpenResty 风格的 ngx API + +### Testing Requirements +- Lua 脚本通过集成测试验证 +- 运行测试：`go test ./internal/lua/...` + +### Common Patterns +- 访问控制：`access_by_lua_block { ... }` +- 动态内容：`content_by_lua_block { ngx.say(...) }` +- 共享字典：`lua_shared_dict cache 10m` + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎实现 +- `../../../docs/lua-nginx-module/` - lua-nginx-module 文档参考 + +### External +- `github.com/yuin/gopher-lua` - Go Lua 解释器 + + diff --git a/docs/config/rewriting/AGENTS.md b/docs/config/rewriting/AGENTS.md new file mode 100644 index 0000000..29049c5 --- /dev/null +++ b/docs/config/rewriting/AGENTS.md @@ -0,0 +1,39 @@ + + + +# rewriting + +## Purpose +URL 重写配置示例目录，包含 rewrite 规则、重定向等 URL 处理配置。 + +## Key Files + +| File | Description | +|------|-------------| +| `rewrite-rules.conf` | URL 重写规则：正则匹配、变量替换、内部重定向 | +| `redirect.conf` | 重定向配置：301/302 跳转、域名迁移 | + +## For AI Agents + +### Working In This Directory +- rewrite 使用正则表达式匹配 URL +- last 表示重写后重新匹配 location +- break 表示重写后直接处理，不再匹配 +- redirect 返回 302，permanent 返回 301 + +### Testing Requirements +- 重写规则通过单元测试验证 +- 测试正则匹配和变量替换正确性 + +### Common Patterns +- 正则捕获：`rewrite ^/user/(\d+)$ /profile?id=$1 last` +- 域名迁移：`return 301 https://new.domain.com$request_uri` +- HTTP 转 HTTPS：`return 301 https://$host$request_uri` + +## Dependencies + +### Internal +- `../../../internal/middleware/rewrite/` - 重写中间件实现 +- `../../../internal/handler/` - 请求处理器 + + diff --git a/docs/config/security/AGENTS.md b/docs/config/security/AGENTS.md new file mode 100644 index 0000000..7b9ae30 --- /dev/null +++ b/docs/config/security/AGENTS.md @@ -0,0 +1,43 @@ + + + +# security + +## Purpose +安全配置示例目录，包含访问控制、认证、限流、连接限制、安全头部等安全防护配置。 + +## Key Files + +| File | Description | +|------|-------------| +| `access-control.conf` | 访问控制：IP 白名单/黑名单、allow/deny 规则 | +| `basic-auth.conf` | Basic 认证：用户名密码保护、htpasswd 文件 | +| `auth-request.conf` | 子请求认证：外部认证服务集成 | +| `rate-limit.conf` | 请求限流：令牌桶、漏桶、请求速率控制 | +| `conn-limit.conf` | 连接限制：并发连接数、单 IP 连接限制 | +| `security-headers.conf` | 安全头部：X-Frame-Options、CSP、HSTS | + +## For AI Agents + +### Working In This Directory +- 访问控制按顺序匹配：先检查黑名单，再检查白名单 +- Basic Auth 使用 bcrypt 密码哈希 +- 限流使用令牌桶算法，支持按 IP/全局限流 +- 安全头部建议全部启用 + +### Testing Requirements +- 安全配置通过单元测试验证 +- 运行测试：`go test ./internal/middleware/security/...` + +### Common Patterns +- 认证失败返回 401 Unauthorized +- 限流触发返回 429 Too Many Requests +- 访问拒绝返回 403 Forbidden + +## Dependencies + +### Internal +- `../../../internal/middleware/security/` - 安全中间件实现 +- `../../../internal/config/` - 安全配置解析 + + diff --git a/docs/config/ssl/AGENTS.md b/docs/config/ssl/AGENTS.md new file mode 100644 index 0000000..1294f0c --- /dev/null +++ b/docs/config/ssl/AGENTS.md @@ -0,0 +1,40 @@ + + + +# ssl + +## Purpose +SSL/TLS 配置示例目录，包含 HTTPS、mTLS、OCSP Stapling、HSTS 等安全传输配置示例。 + +## Key Files + +| File | Description | +|------|-------------| +| `basic-ssl.conf` | 基础 HTTPS 配置：证书、TLS 协议、加密套件、HTTP/2 | +| `hsts.conf` | HSTS 配置：Strict-Transport-Security、预加载 | +| `mtls.conf` | 双向 TLS 认证：客户端证书验证、CA 配置 | +| `ocsp-stapling.conf` | OCSP Stapling：在线证书状态验证、缓存配置 | + +## For AI Agents + +### Working In This Directory +- TLS 1.0/1.1 已弃用，推荐使用 TLS 1.2/1.3 +- 加密套件推荐使用 AEAD（AES-GCM、CHACHA20-POLY1305） +- Session Tickets 禁用更安全，但会影响会话恢复性能 + +### Testing Requirements +- SSL 配置通过集成测试验证 +- 测试证书位于 `internal/ssl/testdata/` + +### Common Patterns +- 证书路径：`ssl.cert`, `ssl.key`, `ssl.cert_chain` +- 协议配置：`ssl.protocols: ["TLSv1.2", "TLSv1.3"]` +- HTTP/2 启用：`ssl.http2.enabled: true` + +## Dependencies + +### Internal +- `../../../internal/ssl/` - SSL 证书加载和管理 +- `../../../internal/sslutil/` - SSL 工具函数 + + diff --git a/docs/lua/api-gateway/AGENTS.md b/docs/lua/api-gateway/AGENTS.md new file mode 100644 index 0000000..6e0bd79 --- /dev/null +++ b/docs/lua/api-gateway/AGENTS.md @@ -0,0 +1,44 @@ + + + +# api-gateway + +## Purpose +API 网关示例项目，演示如何使用 Lua 脚本实现动态路由、认证、限流、健康检查等网关核心功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 项目说明：功能特性、快速开始、配置示例 | +| `gateway.lua` | 网关主逻辑：路由、认证、限流、错误处理 | +| `upstream.lua` | 上游服务管理：健康检查、故障剔除、动态负载均衡 | +| `nginx.conf` | NGINX 配置示例：Lua 脚本集成方式 | + +## For AI Agents + +### Working In This Directory +- 基于 OpenResty / lua-nginx-module 风格 +- 路由规则在 `gateway.lua` 的 `routes` 表中定义 +- 上游节点在 `upstream.lua` 的 `upstreams` 表中配置 +- 生产环境建议使用 Redis 替代共享字典存储 + +### Testing Requirements +- Lua 脚本通过集成测试验证 +- 测试框架：`internal/lua/` 模块测试 + +### Common Patterns +- 路由匹配：路径 + 方法 + Header 组合 +- 限流算法：令牌桶滑动窗口 +- 健康检查：被动探测 + 故障剔除 + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎实现 +- `../../../internal/loadbalance/` - 负载均衡策略 + +### External +- OpenResty / lua-nginx-module - Lua 运行环境 + + diff --git a/docs/lua/authentication/AGENTS.md b/docs/lua/authentication/AGENTS.md new file mode 100644 index 0000000..0b1a64e --- /dev/null +++ b/docs/lua/authentication/AGENTS.md @@ -0,0 +1,41 @@ + + + +# authentication + +## Purpose +认证示例目录，演示如何使用 Lua 实现 Basic Auth、JWT 验证等认证功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 功能说明和使用指南 | +| `basic_auth.lua` | Basic Auth 认证：用户名密码验证、bcrypt 哈希 | +| `jwt_validate.lua` | JWT 验证：令牌解析、签名验证、过期检查 | +| `nginx.conf` | NGINX 配置示例：认证钩子集成 | + +## For AI Agents + +### Working In This Directory +- Basic Auth 使用 bcrypt 密码哈希存储 +- JWT 验证支持 HS256、RS256 算法 +- 认证失败返回 401 Unauthorized +- 可与外部认证服务集成 + +### Testing Requirements +- 认证逻辑通过单元测试验证 +- 测试密码验证、令牌解析正确性 + +### Common Patterns +- Basic Auth：解析 Authorization 头，验证用户名密码 +- JWT：解析 Bearer 令牌，验证签名和有效期 +- 错误响应：`ngx.exit(401)` + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/middleware/security/auth.go` - 认证中间件 + + diff --git a/docs/lua/caching/AGENTS.md b/docs/lua/caching/AGENTS.md new file mode 100644 index 0000000..ff19902 --- /dev/null +++ b/docs/lua/caching/AGENTS.md @@ -0,0 +1,40 @@ + + + +# caching + +## Purpose +缓存示例目录，演示如何使用 Lua 实现响应缓存、缓存失效等缓存功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 功能说明和使用指南 | +| `cache_handler.lua` | 缓存处理器：缓存键生成、存储/读取、过期管理 | +| `nginx.conf` | NGINX 配置示例：共享字典缓存配置 | + +## For AI Agents + +### Working In This Directory +- 使用共享字典（shared dict）存储缓存数据 +- 缓存键通常基于 URL、请求头、参数组合 +- 支持缓存过期时间配置 +- 缓存失效策略：TTL、主动清除 + +### Testing Requirements +- 缓存逻辑通过单元测试验证 +- 测试缓存命中/未命中、过期清理 + +### Common Patterns +- 缓存键：`local key = ngx.md5(ngx.var.uri .. ngx.var.args)` +- 缓存读取：`local data = shared_dict:get(key)` +- 缓存写入：`shared_dict:set(key, data, ttl)` + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/cache/` - 文件缓存实现 + + diff --git a/docs/lua/dynamic-routing/AGENTS.md b/docs/lua/dynamic-routing/AGENTS.md new file mode 100644 index 0000000..2243273 --- /dev/null +++ b/docs/lua/dynamic-routing/AGENTS.md @@ -0,0 +1,40 @@ + + + +# dynamic-routing + +## Purpose +动态路由示例目录，演示如何使用 Lua 实现基于路径、方法、Header 的动态路由。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 功能说明和使用指南 | +| `router.lua` | 路由器实现：路由规则匹配、上游选择 | +| `nginx.conf` | NGINX 配置示例：动态路由集成 | + +## For AI Agents + +### Working In This Directory +- 路由规则支持正则表达式匹配 +- 支持按路径、方法、Header 组合匹配 +- 动态上游选择支持负载均衡 +- 路由规则可热更新 + +### Testing Requirements +- 路由逻辑通过单元测试验证 +- 测试路由匹配、上游选择正确性 + +### Common Patterns +- 路由表：`local routes = { ["/api/*"] = "api_upstream" }` +- 匹配逻辑：遍历路由表，正则匹配请求路径 +- 上游设置：`ngx.var.upstream = matched_upstream` + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/loadbalance/` - 负载均衡实现 + + diff --git a/docs/lua/logging-monitoring/AGENTS.md b/docs/lua/logging-monitoring/AGENTS.md new file mode 100644 index 0000000..e67e90c --- /dev/null +++ b/docs/lua/logging-monitoring/AGENTS.md @@ -0,0 +1,41 @@ + + + +# logging-monitoring + +## Purpose +日志和监控示例目录，演示如何使用 Lua 实现自定义日志格式、指标收集等监控功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 功能说明和使用指南 | +| `log_formatter.lua` | 日志格式化器：自定义日志格式、字段提取 | +| `metrics.lua` | 指标收集：请求计数、延迟统计、Prometheus 格式 | +| `nginx.conf` | NGINX 配置示例：日志钩子集成 | + +## For AI Agents + +### Working In This Directory +- 日志格式支持 JSON、文本格式 +- 指标可导出为 Prometheus 格式 +- 支持请求级别的详细日志 +- 监控数据可存储到共享字典 + +### Testing Requirements +- 日志和指标逻辑通过单元测试验证 +- 测试日志格式、指标计算正确性 + +### Common Patterns +- 日志字段：`ngx.log(ngx.INFO, json.encode(log_entry))` +- 指标计数：`metrics_dict:incr("request_count")` +- Prometheus 格式：`# TYPE http_requests_total counter` + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/logging/` - 日志系统实现 + + diff --git a/docs/lua/middleware/AGENTS.md b/docs/lua/middleware/AGENTS.md new file mode 100644 index 0000000..138e043 --- /dev/null +++ b/docs/lua/middleware/AGENTS.md @@ -0,0 +1,38 @@ + + + +# middleware + +## Purpose +中间件示例目录，演示 Lua 中间件的概念和用法。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 中间件概念说明和使用指南 | + +## For AI Agents + +### Working In This Directory +- 中间件按处理阶段执行：rewrite → access → content → log +- 中间件可链式组合 +- 支持请求修改和响应拦截 +- 参考 OpenResty 风格的中间件模式 + +### Testing Requirements +- 中间件逻辑通过集成测试验证 +- 测试中间件链执行顺序 + +### Common Patterns +- 链式调用：按注册顺序执行 +- 请求修改：`ngx.req.set_header()` +- 响应拦截：`ngx.exit()` 提前返回 + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/middleware/` - 中间件框架实现 + + diff --git a/docs/lua/rate-limiting/AGENTS.md b/docs/lua/rate-limiting/AGENTS.md new file mode 100644 index 0000000..ccffbc4 --- /dev/null +++ b/docs/lua/rate-limiting/AGENTS.md @@ -0,0 +1,40 @@ + + + +# rate-limiting + +## Purpose +限流示例目录，演示如何使用 Lua 实现请求限流、令牌桶算法等限流功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 功能说明和使用指南 | +| `access.lua` | 限流实现：令牌桶、滑动窗口、请求计数 | +| `nginx.conf` | NGINX 配置示例：限流钩子集成 | + +## For AI Agents + +### Working In This Directory +- 令牌桶算法：固定速率生成令牌，请求消耗令牌 +- 滑动窗口：统计时间窗口内请求数 +- 支持按 IP、全局限流 +- 限流触发返回 429 Too Many Requests + +### Testing Requirements +- 限流逻辑通过单元测试验证 +- 测试令牌桶、滑动窗口算法正确性 + +### Common Patterns +- 令牌桶：`local tokens = min(max_tokens, tokens + rate * elapsed)` +- 限流检查：`if tokens < 1 then ngx.exit(429) end` +- 滑动窗口：使用共享字典存储请求时间戳 + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/middleware/security/ratelimit.go` - 限流中间件 + + diff --git a/docs/lua/websocket/AGENTS.md b/docs/lua/websocket/AGENTS.md new file mode 100644 index 0000000..05475fc --- /dev/null +++ b/docs/lua/websocket/AGENTS.md @@ -0,0 +1,40 @@ + + + +# websocket + +## Purpose +WebSocket 示例目录，演示如何使用 Lua 实现 WebSocket 服务器和客户端功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `README.md` | 功能说明和使用指南 | +| `ws_handler.lua` | WebSocket 处理器：握手、消息收发、连接管理 | +| `nginx.conf` | NGINX 配置示例：WebSocket 代理配置 | + +## For AI Agents + +### Working In This Directory +- WebSocket 需要正确处理 Upgrade 和 Connection 头 +- 支持双向消息传递 +- 需要处理连接保活（ping/pong） +- 错误处理：连接断开、协议错误 + +### Testing Requirements +- WebSocket 逻辑通过集成测试验证 +- 测试握手、消息收发、连接关闭 + +### Common Patterns +- 握手验证：检查 `Upgrade: websocket` 头 +- 消息循环：`while true do local data = ws:recv() end` +- 心跳：定期发送 ping 帧 + +## Dependencies + +### Internal +- `../../../internal/lua/` - Lua 脚本引擎 +- `../../../internal/proxy/websocket.go` - WebSocket 代理实现 + +