lolly/docs/config-reference.md

配置参考文档

目录

• 变量系统
• DNS 解析器
• 访问日志格式

---

变量系统

Lolly 支持 nginx 风格的变量系统，可用于访问日志格式、代理请求头和 URL 重写规则。

内置变量

变量名	说明	示例值
$host	请求的主机名（Host 头）	example.com
$remote_addr	客户端 IP 地址	192.168.1.1
$remote_port	客户端端口	54321
$request_uri	原始请求 URI（包含查询参数）	/api/users?page=1
$uri	解码后的 URI 路径	/api/users
$args	查询参数字符串	page=1&limit=10
$request_method	HTTP 请求方法	GET, POST
$scheme	协议	http, https
$server_name	服务器名称	localhost
$server_port	服务器端口	8080
$status	HTTP 响应状态码	200, 404
$body_bytes_sent	发送的响应体字节数	1024
$request_time	请求处理时间（秒）	0.050
$time_local	本地时间	08/Apr/2026:11:04:58 +0800
$time_iso8601	ISO8601 格式时间	2026-04-08T11:04:58+08:00
$request_id	唯一请求标识符	uuid

动态 HTTP 头变量

以 $http_ 开头的变量用于获取 HTTP 请求头值：

• $http_user_agent - User-Agent 头
• $http_referer - Referer 头
• $http_x_forwarded_for - X-Forwarded-For 头
• 其他任意请求头：$http_header_name

变量格式

支持两种格式：

1. 简单格式: $var

   $host $uri
   

2. 花括号格式: ${var}

   ${host}:8080
   ${scheme}://${host}${uri}
   

在代理请求头中使用变量

proxy:
  - path: /api
    targets:
      - url: http://backend:8080
    headers:
      set_request:
        X-Real-IP: "$remote_addr"
        X-Forwarded-Host: "$host"
        X-Request-ID: "$request_id"

在访问日志中使用变量

logging:
  access:
    format: '$remote_addr - $remote_user [$time_local] "$request_method $uri $scheme" $status $body_bytes_sent'

自定义变量

variables:
  set:
    app_name: "lolly"
    version: "1.0.0"

注意:

• $request_id 为内置变量，自动为每个请求生成唯一 UUID，无需配置
• 自定义变量名不能与内置变量冲突
• 变量名只允许字母、数字、下划线

---

DNS 解析器

Lolly 内置 DNS 解析器，支持动态解析后端服务域名。

配置选项

resolver:
  enabled: true              # 是否启用
  addresses:                 # DNS 服务器地址列表
    - "8.8.8.8:53"
    - "8.8.4.4:53"
  valid: 30s                 # 缓存有效期（TTL）
  timeout: 5s                # DNS 查询超时
  ipv4: true                 # 查询 IPv4 地址
  ipv6: false                # 查询 IPv6 地址
  cache_size: 1024           # 缓存最大条目数

功能特性

• DNS 缓存: 按 TTL 缓存解析结果，减少 DNS 查询延迟
• 后台刷新: 自动在 TTL/2 时刷新缓存，避免过期
• 故障转移: 解析失败时使用缓存 IP 继续服务
• 健康检查: 首次解析失败标记目标不健康

使用场景

当后端目标使用域名时，DNS 解析器自动生效：

proxy:
  - path: /api
    targets:
      - url: http://backend.example.com:8080  # 使用域名
        weight: 1

监控指标

通过状态端点获取 DNS 解析统计：

• CacheHits - 缓存命中次数
• CacheMisses - 缓存未命中次数
• CacheEntries - 当前缓存条目数
• ResolveErrors - 解析错误次数
• AverageLatency - 平均解析延迟

---

访问日志格式

nginx 兼容格式

Lolly 默认提供 nginx 兼容的访问日志格式：

logging:
  access:
    format: '$remote_addr - $remote_user [$time] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'

示例输出：

192.168.1.1 - - [08/Apr/2026:11:04:58 +0800] "GET /api/users HTTP/1.1" 200 1024 "-" "Mozilla/5.0"

JSON 格式

设置格式为 json 输出结构化日志：

logging:
  access:
    format: 'json'

示例输出：

{
  "remote_addr": "192.168.1.1",
  "request": "GET /api/users HTTP/1.1",
  "status": 200,
  "body_bytes_sent": 1024,
  "http_user_agent": "Mozilla/5.0"
}

自定义格式

使用变量创建自定义格式：

logging:
  access:
    format: '$remote_addr $request_method $uri $status $request_time'

---

完整配置示例

server:
  listen: ":8080"
  name: "localhost"

  proxy:
    - path: /api
      targets:
        - url: http://backend.example.com:8080
      headers:
        set_request:
          X-Real-IP: "$remote_addr"
          X-Forwarded-Host: "$host"
          X-Request-ID: "$request_id"

resolver:
  enabled: true
  addresses:
    - "8.8.8.8:53"
  valid: 30s
  timeout: 5s

variables:
  set:
    app_name: "lolly"

logging:
  access:
    format: '$remote_addr - $remote_user [$time_local] "$request_method $uri $scheme" $status $body_bytes_sent'
    path: "/var/log/lolly/access.log"
  error:
    level: "info"
    path: "/var/log/lolly/error.log"