[文档] 文档更新

2026-10-03 07:06:36 +08:00 · 2026-03-15 17:11:17 +08:00
parent 5858e30af6
commit b2eb4befba
11 changed files with 769 additions and 2232 deletions
@@ -1,387 +1,151 @@
-# OpenFlare 配置项说明
-
-本文档汇总当前 OpenFlare Server 与 Agent 在启动、部署和运行时支持的参数、环境变量与配置文件字段，并说明其作用、默认值和示例。
-
---
-
-## 1. Server 配置
-
-Server 当前支持两类启动配置：
-
-1. 命令行参数
-2. 环境变量
-
-此外，部分运行时参数已迁入数据库 `Option` 表，可在管理端设置页中热更新，例如 Agent 运行参数与限流阈值。
-
-第五版（0.5.x）继续复用 `Option` 表承载 OpenResty 性能优化参数与缓存参数，不单独引入新的配置中心。
-
-### 1.1 Server 命令行参数
-
-启动示例：
-
-```bash
-cd openflare_server
-go run . --port 3000 --log-dir ./logs
-```
-
-或在编译后二进制中使用：
-
-```bash
-./openflare --port 3000 --log-dir ./logs
-```
-
-支持的命令行参数：
-
-| 参数 | 作用 | 默认值 | 示例 |
-| --- | --- | --- | --- |
-| `--port` | 指定 Server 监听端口 | `3000` | `--port 3000` |
-| `--log-dir` | 指定日志目录；设置后会自动创建目录并写入日志 | 空，默认输出到 stdout | `--log-dir ./logs` |
-| `--version` | 输出当前版本后退出 | `false` | `./openflare --version` |
-| `--help` | 输出帮助信息后退出 | `false` | `./openflare --help` |
-
-说明：
-
-* 当同时设置 `PORT` 环境变量与 `--port` 时，运行时优先使用 `PORT`
-* `--log-dir` 当前没有对应环境变量，适合源码运行或 systemd 方式部署时使用
-
-### 1.2 Server 环境变量
-
-源码启动示例：
-
-```bash
-cd openflare_server
-export SESSION_SECRET='replace-with-random-string'
-export SQLITE_PATH='./openflare.db'
-export GIN_MODE='release'
-export LOG_LEVEL='info'
-export PORT='3000'
-go run .
-```
-
-Docker Compose 示例：
-
-```yaml
-services:
-	openflare:
-		image: ghcr.io/rain-kl/openflare:latest
-		restart: unless-stopped
-		ports:
-			- "3000:3000"
-		environment:
-			SESSION_SECRET: replace-with-random-string
-			SQLITE_PATH: /data/openflare.db
-			GIN_MODE: release
-			LOG_LEVEL: info
-			PORT: "3000"
-		volumes:
-			- openflare-data:/data
-
-volumes:
-	openflare-data:
-```
-
-支持的环境变量：
-
-| 环境变量 | 作用 | 默认值 | 示例 |
-| --- | --- | --- | --- |
-| `PORT` | 指定 Server 实际监听端口 | `3000` | `PORT=3000` |
-| `GIN_MODE` | 指定 Gin 运行模式；仅当值为 `debug` 时启用 debug，其余情况按 release 运行 | 非 `debug` 默认按 release 运行 | `GIN_MODE=release` |
-| `LOG_LEVEL` | 指定系统日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=warn` |
-| `SESSION_SECRET` | Session 签名密钥；生产环境必须显式设置，避免重启后会话失效 | 启动时随机生成 UUID | `SESSION_SECRET=replace-with-random-string` |
-| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` | `SQLITE_PATH=/data/openflare.db` |
-| `SQL_DSN` | MySQL DSN；设置后优先使用 MySQL，而不是 SQLite | 未设置时使用 SQLite | `SQL_DSN=user:pass@tcp(127.0.0.1:3306)/openflare` |
-| `REDIS_CONN_STRING` | Redis 连接串；设置后启用 Redis，用于 Session/限流相关能力 | 未设置时关闭 Redis | `REDIS_CONN_STRING=redis://default:pass@127.0.0.1:6379/0` |
-| `UPLOAD_PATH` | 上传文件目录 | `upload` | `UPLOAD_PATH=/data/upload` |
-| `AGENT_TOKEN` | 全局 Agent Token 兼容配置；当前默认部署不依赖该变量 | 空 | `AGENT_TOKEN=legacy-shared-token` |
-
-说明：
-
-* `SQL_DSN` 与 `SQLITE_PATH` 同时存在时，优先使用 `SQL_DSN`
-* `SESSION_SECRET` 未固定时，每次重启都会生成新的随机值，已登录用户的 Cookie 会失效
-* `LOG_LEVEL` 未设置或设置为不支持的值时，将回退为 `info`
-* `REDIS_CONN_STRING` 未配置时，相关能力将回退为进程内实现
-* `UPLOAD_PATH` 目录在启动时若不存在会自动创建
-
-### 1.2.1 设置页可热更新的运行时配置
-
-以下配置不依赖环境变量，保存在数据库 `Option` 表中，可在管理端设置页的「运维设置」中调整，并在保存后立即生效：
-
-| 配置项 | 作用 | 默认值 |
-| --- | --- | --- |
+# OpenFlare 配置项说明
+
+本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。
+
+## 1. Server 配置
+
+Server 支持三类配置来源：
+
+1. 命令行参数
+2. 环境变量
+3. 数据库 `Option` 表中的运行时配置
+
+### 1.1 命令行参数
+
+```bash
+cd openflare_server
+go run . --port 3000 --log-dir ./logs
+```
+
+| 参数 | 作用 | 默认值 |
+| --- | --- | --- |
+| `--port` | 指定 Server 监听端口 | `3000` |
+| `--log-dir` | 指定日志目录 | 空 |
+| `--version` | 输出当前版本后退出 | `false` |
+| `--help` | 输出帮助信息后退出 | `false` |
+
+### 1.2 环境变量
+
+| 环境变量 | 作用 | 默认值 |
+| --- | --- | --- |
+| `PORT` | Server 监听端口 | `3000` |
+| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release |
+| `LOG_LEVEL` | 日志等级 | `info` |
+| `SESSION_SECRET` | Session 签名密钥 | 启动时随机生成 |
+| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` |
+| `SQL_DSN` | MySQL DSN，设置后优先于 SQLite | 空 |
+| `REDIS_CONN_STRING` | Redis 连接串 | 空 |
+| `UPLOAD_PATH` | 上传目录 | `upload` |
+| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 |
+
+说明：
+
+* `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 `SQL_DSN`
+* `SESSION_SECRET` 生产环境必须显式配置
+* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现
+
+### 1.3 `Option` 表中的运行时配置
+
+以下配置由管理端设置页维护，可热更新：
+
+| 配置项 | 作用 | 默认值 |
+| --- | --- | --- |
 | `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
-| `NodeOfflineThreshold` | 节点离线判定阈值（毫秒） | `120000` |
+| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` |
 | `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
-| `GeoIPProvider` | 节点/IP 归属解析方式；支持 `disabled`、`mmdb`、`ip-api`、`geojs`、`ipinfo` | `ipinfo` |
-| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口（秒） | `300` / `180` |
-| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口（秒） | `300` / `180` |
-| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口（秒） | `50` / `60` |
-| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口（秒） | `50` / `60` |
-| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 登录、注册、验证码等敏感接口限流次数 / 时间窗口（秒） | `100` / `1200` |
-
-说明：
-
-* 限流窗口上限不能超过 `RateLimitKeyExpirationDuration`，当前为 20 分钟
-* 限流按来源 IP 统计，若前置了 Nginx/CDN/LB，应正确透传真实客户端 IP
-* `GeoIPProvider=mmdb` 时，Server 会按需下载并使用本地 MaxMind Country 数据库；其余非 `disabled` 选项会直接请求对应外部 GeoIP 服务
-* 管理端“日志 -> 访问记录”中的访客 IP 归属地入库固定使用 MaxMind mmdb，不跟随 `GeoIPProvider` 切换
-
-### 1.2.2 第五版当前支持的 OpenResty 优化配置项
-
-以下配置项当前已接入管理端「运维设置」，并统一保存在 `Option` 表中。它们会参与第五版后续的配置渲染与发布链路；当前阶段优先完成参数录入、默认值和校验能力。
-
-| 配置项 | 作用 | 计划默认值 |
-| --- | --- | --- |
-| `OpenRestyWorkerProcesses` | `worker_processes` 配置；支持 `auto` 或正整数 | `auto` |
-| `OpenRestyWorkerConnections` | `events { worker_connections }` 上限 | `4096` |
-| `OpenRestyWorkerRlimitNofile` | `worker_rlimit_nofile` 上限 | `65535` |
-| `OpenRestyEventsUse` | `events { use ... }` 指令；为空表示不显式渲染 | 空 |
-| `OpenRestyEventsMultiAcceptEnabled` | 是否启用 `multi_accept on` | `false` |
-| `OpenRestyKeepaliveTimeout` | `keepalive_timeout` 秒数 | `65` |
-| `OpenRestyKeepaliveRequests` | `keepalive_requests` 上限 | `1000` |
-| `OpenRestyClientHeaderTimeout` | `client_header_timeout` 秒数 | `15` |
-| `OpenRestyClientBodyTimeout` | `client_body_timeout` 秒数 | `15` |
-| `OpenRestySendTimeout` | `send_timeout` 秒数 | `30` |
-| `OpenRestyProxyConnectTimeout` | `proxy_connect_timeout` 秒数 | `5` |
-| `OpenRestyProxySendTimeout` | `proxy_send_timeout` 秒数 | `60` |
-| `OpenRestyProxyReadTimeout` | `proxy_read_timeout` 秒数 | `60` |
-| `OpenRestyWebsocketEnabled` | 是否自动注入 WebSocket 升级所需代理头 | `true` |
-| `OpenRestyProxyRequestBufferingEnabled` | 是否启用 `proxy_request_buffering` | `false` |
-| `OpenRestyProxyBufferingEnabled` | 是否启用 `proxy_buffering` | `true` |
-| `OpenRestyProxyBuffers` | `proxy_buffers` 组合值，例如 `16 16k` | `16 16k` |
-| `OpenRestyProxyBufferSize` | `proxy_buffer_size` | `8k` |
-| `OpenRestyProxyBusyBuffersSize` | `proxy_busy_buffers_size` | `64k` |
-| `OpenRestyGzipEnabled` | 是否启用 `gzip on` | `true` |
-| `OpenRestyGzipMinLength` | `gzip_min_length` 字节数 | `1024` |
-| `OpenRestyGzipCompLevel` | `gzip_comp_level` | `5` |
-| `OpenRestyCacheEnabled` | 是否启用代理缓存 | `false` |
-| `OpenRestyCachePath` | `proxy_cache_path` 目录 | 空 |
-| `OpenRestyCacheLevels` | `proxy_cache_path levels=` 值 | `1:2` |
-| `OpenRestyCacheInactive` | `proxy_cache_path inactive=` 时长 | `30m` |
-| `OpenRestyCacheMaxSize` | `proxy_cache_path max_size=` 大小 | `1g` |
-| `OpenRestyCacheKeyTemplate` | 缓存 Key 模板 | `$scheme$proxy_host$request_uri` |
-| `OpenRestyCacheLockEnabled` | 是否启用 `proxy_cache_lock` | `true` |
-| `OpenRestyCacheLockTimeout` | `proxy_cache_lock_timeout` 时长 | `5s` |
-| `OpenRestyCacheUseStale` | `proxy_cache_use_stale` 场景列表 | `error timeout updating http_500 http_502 http_503 http_504` |
-
-说明：
-
-* 第五版第一批当前仅开放稳定、可校验、可回滚的常用性能项；更多指令后续按相同模式扩展
-* 所有大小、时长、布尔和整数参数都应在 Server 保存前完成校验
-* `OpenRestyCacheEnabled=false` 时，缓存目录与缓存参数应允许留空或回退到默认值
-* 任何包含路径的配置项都必须在 Agent 落盘前再次校验可写性与安全边界
-
-### 1.3 前端构建环境变量
+| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` |
+| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` |
+| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` |
+| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` |
+| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` |
+| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` |

-新版管理端位于 `openflare_server/web`，构建时支持以下公开环境变量：
-
-| 环境变量 | 作用 | 默认值 | 示例 |
-| --- | --- | --- | --- |
-| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` |
-| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` |
-| `NEXT_DEV_BACKEND_URL` | 前端开发服务器通过反向代理转发 `/api/*` 时使用的后端地址；仅开发模式使用 | `http://127.0.0.1:3000` | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3300` |
+### 1.4 OpenResty 参数

-说明：
+OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括：

-* `NEXT_PUBLIC_*` 变量会在前端构建阶段读取，并打包进静态资源
-* `NEXT_DEV_BACKEND_URL` 仅在本地开发服务器模式下使用，不会进入静态导出产物
-* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api`
-* `pnpm start` 会以开发模式启动前端，默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 将 `/api/*` 代理到后端
-
---
-
-## 2. Agent 配置
-
-Agent 当前支持两类启动配置：
-
-1. 命令行参数
-2. `agent.json` 配置文件
-
-当前 Agent 仅支持少量环境变量用于日志输出控制；核心启动行为仍由 `-config` 参数和配置文件字段决定。
+* `OpenRestyWorkerProcesses`
+* `OpenRestyWorkerConnections`
+* `OpenRestyWorkerRlimitNofile`
+* `OpenRestyKeepaliveTimeout`
+* `OpenRestyProxyConnectTimeout`
+* `OpenRestyProxySendTimeout`
+* `OpenRestyProxyReadTimeout`
+* `OpenRestyProxyBufferingEnabled`
+* `OpenRestyGzipEnabled`
+* `OpenRestyCacheEnabled`
+* `OpenRestyCachePath`
+* `OpenRestyCacheMaxSize`

-### 2.1.1 Agent 环境变量
+这类参数必须以结构化方式校验、保存并参与版本渲染。

-支持的环境变量：
+### 1.5 前端构建环境变量

-| 环境变量 | 作用 | 默认值 | 示例 |
+| 环境变量 | 作用 | 默认值 |
+| --- | --- | --- |
+| `NEXT_PUBLIC_API_BASE_URL` | 前端请求 API 的基础路径 | `/api` |
+| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` |
+| `NEXT_DEV_BACKEND_URL` | 本地开发服务器代理的后端地址 | `http://127.0.0.1:3000` |
+
+## 2. Agent 配置
+
+Agent 当前支持：
+
+1. `-config` 命令行参数
+2. `agent.json` 配置文件
+3. 少量日志相关环境变量
+
+### 2.1 Agent 环境变量
+
+| 环境变量 | 作用 | 默认值 |
+| --- | --- | --- |
+| `LOG_LEVEL` | Agent 日志等级 | `info` |
+
+### 2.2 Agent 命令行参数
+
+| 参数 | 作用 | 默认值 |
+| --- | --- | --- |
+| `-config` | 指定 Agent 配置文件路径 | `./agent.json` |
+
+### 2.3 Agent 配置字段
+
+| 字段 | 作用 | 是否必填 | 默认值/行为 |
 | --- | --- | --- | --- |
-| `LOG_LEVEL` | 指定 Agent 的 `slog` 日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=debug` |
+| `server_url` | 控制面地址 | 是 | 无 |
+| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 |
+| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
+| `node_name` | 节点名称 | 否 | 自动使用主机名 |
+| `node_ip` | 节点 IP | 否 | 自动探测 |
+| `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 |
+| `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` |
+| `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` |
+| `openresty_observability_port` | 本地观测端口 | 否 | `18081` |
+| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` |
+| `data_dir` | Agent 数据目录 | 否 | 配置文件所在目录下的 `data` |
+| `main_config_path` | OpenResty 主配置写入路径 | 否 | 本机模式建议显式配置 |
+| `route_config_path` | 路由配置写入路径 | 否 | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
+| `cert_dir` | 本机证书写入目录 | 否 | `data_dir/etc/nginx/certs` |
+| `openresty_cert_dir` | OpenResty 读取证书目录 | 否 | 随运行模式变化 |
+| `lua_dir` | 本机 Lua 脚本写入目录 | 否 | `data_dir/etc/nginx/lua` |
+| `openresty_lua_dir` | OpenResty 读取 Lua 目录 | 否 | 随运行模式变化 |
+| `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` |
+| `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `15` |
+| `state_path` | Agent 本地状态文件路径 | 否 | `data_dir/var/lib/openflare/agent-state.json` |
+| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 |
+| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒 |

 说明：

-* `LOG_LEVEL` 只影响 Agent 本地日志输出，不改变心跳、同步或配置行为
-* 未设置或设置为不支持的值时，将回退为 `info`
+* `agent_token` 与 `discovery_token` 不能同时为空
+* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串
+* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式

-### 2.1 Agent 命令行参数
-
-启动示例：
-
-```bash
-cd openflare_agent
-go run ./cmd/agent -config ./agent.json
-```
-
-或编译后二进制：
-
-```bash
-./openflare-agent -config /path/to/agent.json
-```
-
-支持的命令行参数：
-
-| 参数 | 作用 | 默认值 | 示例 |
-| --- | --- | --- | --- |
-| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | `-config /etc/openflare/agent.json` |
-
-### 2.2 Agent 配置文件示例
-
-推荐最小配置：
-
-```json
-{
-	"server_url": "http://127.0.0.1:3000",
-	"discovery_token": "replace-with-global-discovery-token",
-	"data_dir": "./data",
-	"openresty_container_name": "openflare-openresty",
-	"openresty_docker_image": "openresty/openresty:alpine",
-	"openresty_observability_port": 18081,
-	"observability_replay_minutes": 15,
-	"heartbeat_interval": 10000,
-	"request_timeout": 10000
-}
-```
-
-使用节点专属 Token 的示例：
-
-```json
-{
-	"server_url": "http://127.0.0.1:3000",
-	"agent_token": "replace-with-node-auth-token",
-	"node_name": "node-01",
-	"node_ip": "192.168.1.20",
-	"data_dir": "./data",
-	"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
-	"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
-	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
-	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"lua_dir": "/usr/local/openresty/nginx/conf/lua",
-	"openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua",
-	"openresty_observability_port": 18081,
-	"observability_buffer_path": "./data/observability-buffer.json",
-	"observability_replay_minutes": 15,
-	"state_path": "./data/agent-state.json",
-	"heartbeat_interval": 10000,
-	"request_timeout": 10000
-}
-```
-
-### 2.3 Agent 配置字段
-
-| 字段 | 作用 | 是否必填 | 默认值/行为 | 示例 |
-| --- | --- | --- | --- | --- |
-| `server_url` | 控制面地址，Agent 所有注册、心跳、同步请求都会发往这里 | 是 | 无 | `http://127.0.0.1:3000` |
-| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 | `node-token-xxx` |
-| `discovery_token` | 全局发现 Token，用于节点首次自动注册 | 与 `agent_token` 二选一 | 空 | `discovery-token-xxx` |
-| `node_name` | 节点名称 | 否 | 自动使用主机名 | `node-01` |
-| `node_ip` | 节点 IP | 否 | 自动探测第一个可用 IPv4 | `192.168.1.20` |
-| `openresty_path` | 本机 OpenResty 可执行文件路径；设置后按本机 OpenResty 模式运行 | 否 | 空；未设置时按 Docker OpenResty 模式处理 | `/usr/local/openresty/nginx/sbin/openresty` |
-| `openresty_container_name` | Docker 模式下的 OpenResty 容器名 | 否 | `openflare-openresty` | `openflare-openresty` |
-| `openresty_docker_image` | Docker 模式下用于初始化/管理的 OpenResty 镜像 | 否 | `openresty/openresty:alpine` | `openresty/openresty:alpine` |
-| `openresty_observability_port` | Agent 注入的 OpenResty 本地观测端口；用于 heartbeat 前读取 Lua 窗口指标和 `stub_status`，默认仅监听 `127.0.0.1` | 否 | `18081` | `18081` |
-| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | `/usr/bin/docker` |
-| `data_dir` | Agent 数据目录，用于存储托管配置、证书和状态文件 | 否 | 配置文件所在目录下的 `data` 子目录 | `./data` |
-| `main_config_path` | 第五版主配置接管时 OpenResty 主配置文件写入路径 | 第五版本机模式建议必填 | Docker 模式可使用受管默认路径；本机模式建议显式设置 | `/usr/local/openresty/nginx/conf/nginx.conf` |
-| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/openflare_routes.conf` |
-| `cert_dir` | Agent 在本机写入受管证书文件的目录 | 否 | 默认为 `data_dir` 下托管 certs 目录 | `./data/etc/nginx/certs` |
-| `openresty_cert_dir` | OpenResty 实际读取受管证书文件的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/openflare-certs` | `/usr/local/openresty/nginx/conf/certs` |
-| `lua_dir` | Agent 在本机写入受管 Lua 观测脚本的目录；每次启动都会覆盖释放 | 否 | 默认为 `data_dir` 下托管 lua 目录 | `./data/etc/nginx/lua` |
-| `openresty_lua_dir` | OpenResty 实际读取受管 Lua 观测脚本的目录 | 否 | 本机模式默认等于 `lua_dir`；Docker 模式默认 `/etc/nginx/openflare-lua` | `/usr/local/openresty/nginx/conf/lua` |
-| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径；用于在 server 短暂离线时按时间窗口落盘待补传数据 | 否 | 默认为 `data_dir` 下托管观测缓冲文件 | `./data/var/lib/openflare/observability-buffer.json` |
-| `observability_replay_minutes` | Agent 恢复心跳后允许批量补传的最近观测窗口时长（分钟） | 否 | `15` | `30` |
-| `state_path` | Agent 本地状态文件路径 | 否 | 默认为 `data_dir` 下托管状态文件 | `./data/agent-state.json` |
-| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 | `10000` |
-| `request_timeout` | HTTP 请求超时时间 | 否 | `10000` 毫秒 | `10000` |
-
-说明：
-
-* `agent_token` 与 `discovery_token` 不能同时为空
-* `heartbeat_interval`、`request_timeout` 支持两种写法：
-	* 毫秒整数，例如 `10000`
-	* Go duration 字符串，例如 `"30s"`
-* `node_name` 与 `node_ip` 未填写时会自动探测；若自动探测失败，配置校验会报错
-* 未配置 `openresty_path` 时，默认为 Docker OpenResty 模式
-* `openresty_observability_port` 默认仅绑定本地回环地址；若节点本机已有端口冲突，可改为其他未占用端口
-* `observability_replay_minutes` 只控制“允许补传最近多少分钟的窗口”；超出该窗口的历史观测会在本地自动裁剪
-* 配置保存时，`agent_version`、`nginx_version` 由程序运行时维护，不需要写入 JSON
-* 第五版主配置接管完成后，本机模式下应优先通过 `main_config_path` 由 Agent 写入受管主配置，而不是依赖节点手工维护 include 规则
-
-### 2.4 Agent 托管路径默认值
-
-当未显式设置以下字段时，Agent 会根据 `data_dir` 自动生成托管路径：
-
-| 字段 | 默认值 |
-| --- | --- |
-| `main_config_path` | 第五版 Docker 模式默认可落在 `data_dir/etc/nginx/nginx.conf`；本机模式建议显式配置 |
-| `route_config_path` | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
-| `cert_dir` | `data_dir/etc/nginx/certs` |
-| `lua_dir` | `data_dir/etc/nginx/lua` |
-| `observability_buffer_path` | `data_dir/var/lib/openflare/observability-buffer.json` |
-| `state_path` | `data_dir/var/lib/openflare/agent-state.json` |
-
-Docker OpenResty 模式下：
-
-| 字段 | 默认值 |
-| --- | --- |
-| `openresty_cert_dir` | `/etc/nginx/openflare-certs` |
-| `openresty_lua_dir` | `/etc/nginx/openflare-lua` |
+## 3. 维护要求

-补充说明：
+以下内容变化时，必须同步更新本文档：

-* Agent 会在每次启动时把受管 Lua 观测脚本覆盖释放到 `lua_dir`，不再由 Server 随配置版本下发
-* OpenResty 通过 `openresty_lua_dir` 读取这些本地脚本，并在每次 heartbeat 前通过 `http://127.0.0.1:<openresty_observability_port>/openflare/observability` 读取最近窗口请求指标
-* 若 server 短暂离线，Agent 会把最近窗口观测先写入 `observability_buffer_path`，待 heartbeat 恢复后按时间窗口批量补传最近 `observability_replay_minutes` 分钟的数据
-* 同一端口还会暴露仅本机可访问的 `stub_status`，用于采集 OpenResty 活动连接数
-
-### 2.5 Agent 启动示例
-
-#### Docker OpenResty 模式
-
-适用于节点本机不直接管理宿主机 OpenResty，而是通过 Docker 容器运行 OpenResty。
-
-```json
-{
-	"server_url": "http://127.0.0.1:3000",
-	"discovery_token": "replace-with-global-discovery-token",
-	"data_dir": "./data"
-}
-```
-
-#### 本机 OpenResty 模式
-
-适用于节点已经安装了宿主机 OpenResty，且 Agent 直接执行 `openresty -t` 与 `openresty -s reload`。
-
-```json
-{
-	"server_url": "http://127.0.0.1:3000",
-	"agent_token": "replace-with-node-auth-token",
-	"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
-	"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
-	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
-	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"lua_dir": "/usr/local/openresty/nginx/conf/lua",
-	"openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua"
-}
-```
-
---
-
-## 3. 配置维护要求
-
-当以下内容发生变化时，应同步更新本文档：
-
-* Server 新增/删除命令行参数
-* Server 新增/删除环境变量
-* Agent 新增/删除命令行参数
-* Agent 新增/删除配置文件字段
-* 任一配置项的默认值、示例或用途发生变化
+* Server 命令行参数
+* Server 环境变量
+* Agent 命令行参数
+* Agent 配置字段
+* 任一配置项的默认值、用途或示例