-[//]: # (
)
-
# OpenFlare
轻量、自托管的 OpenResty 控制面，用于管理反向代理规则、配置发布、节点同步、TLS 证书与基础可观测能力。
@@ -24,66 +18,28 @@
-> [!NOTE]
-> 当前项目处于快速迭代期，设计与实现均不稳定，请确保使用最新版本并关注更新日志。
-
> [!WARNING]
-> 使用 root 用户初次登录系统后，务必修改默认密码 `123456`，并且确保关闭新用户注册功能。
+> 使用 `root` 用户初次登录系统后，务必修改默认密码 `123456`，并按需关闭新用户注册功能。
-## 为什么存在
+## 文档
-OpenFlare 解决的是一类朴素但高频的运维问题：
+**https://open-flare.pages.dev**
-* 在一个管理端里维护域名到源站的反向代理规则
-* 生成完整 OpenResty 配置并以不可变版本发布
-* 让节点侧 Agent 自动拉取、校验、reload 与失败回滚
-* 统一托管证书、域名、节点凭证与版本状态
-* 提供足够实用的总览、节点详情与访问分析能力
+常用入口：
+
+* [快速开始](https://open-flare.pages.dev/guide/quick-start)
+* [部署说明](https://open-flare.pages.dev/guide/deployment)
+* [配置项参考](https://open-flare.pages.dev/reference/configuration)
+* [系统设计](https://open-flare.pages.dev/design/)
## 核心能力
-* 配置版本化：支持预览、发布、激活、历史回滚
-* Agent 自动应用：周期性同步、落盘、`openresty -t`、`openresty -s reload`、失败自动回滚
-* OpenResty 托管：统一管理主配置模板、性能参数、缓存参数与受管路由
-* TLS 与域名管理：支持证书托管、域名资产维护、精确匹配与通配符匹配
-* 访问与节点观测：支持请求窗口聚合、状态码分布、来源分布、节点资源与健康事件展示
-* 网站防护: 支持 POW, 限流功能
-
-## 系统架构
-
-```text
-OpenFlare Server (Gin + GORM + SQLite/PostgreSQL + Web UI)
- |
- | HTTP API / Config Pull
- v
-OpenFlare Agent (register / heartbeat / sync / apply / update)
- |
- v
-Local OpenResty or Docker OpenResty
- |
- v
-Origin
-```
-
-职责划分：
-
-* `openflare_server`：管理端 UI、管理 API、Agent API、配置渲染、版本发布与状态存储
-* `openflare_agent`：节点注册、心跳、同步、本地写入、校验、reload、回滚、自更新
-* `openflare_server/web`：新版管理端前端，静态导出后由 Go Server 托管
-
-## 界面预览
-
-### 仪表盘总览
-
-
-
-### 节点详情
-
-
-
-### 配置新增
-
-
+* 反向代理网站配置与多域名绑定
+* 配置预览、发布、激活与历史回滚
+* Agent 自动注册、心跳、同步、校验、reload 与失败回滚
+* OpenResty 主配置、性能参数、缓存参数与 Lua 资源托管
+* TLS 证书、域名资产、节点凭证与版本状态管理
+* 请求聚合、访问分析、资源快照、健康事件与节点详情
## 快速开始
@@ -179,42 +135,20 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本完成。
-## 仓库结构
-* `openflare_server`：Gin + GORM + SQLite/PostgreSQL 单体控制面
-* `openflare_server/web`：Next.js 15 App Router 管理端前端
-* `openflare_agent`：Go 单体 Agent
-* `scripts`：安装脚本与辅助脚本
-* `docs`：设计、规范、部署与配置文档
+## 界面预览
-## 本地开发
+### 仪表盘总览
-### Server
+
-```bash
-cd openflare_server
-export SESSION_SECRET='replace-with-random-string'
-export SQLITE_PATH='./openflare.db'
-# 可选：设置 DSN 或 SQL_DSN 后切换到 PostgreSQL。
-# 如果 PostgreSQL 为空且 ./openflare.db 存在，启动时会自动迁移 SQLite 数据。
-# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
-go run .
-```
+### 节点详情
-### Frontend
+
-```bash
-cd openflare_server/web
-pnpm install
-pnpm dev
-```
+### 配置新增
-### Agent
-
-```bash
-cd openflare_agent
-go run ./cmd/agent -config /path/to/agent.json
-```
+
## 管理端与接口
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index f110161a..418ff3e7 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -12,13 +12,7 @@ export default defineConfig({
'zh/**',
'components/**',
'snippets/**',
- 'design.md',
- 'website-configuration-redesign.md',
- 'development-plan.md',
- 'development-guidelines.md',
- 'frontend-development-guidelines.md',
- 'deployment.md',
- 'app-config.md'
+ 'website-configuration-redesign.md'
],
markdown: {
diff --git a/docs/app-config.md b/docs/app-config.md
deleted file mode 100644
index c84b0bdf..00000000
--- a/docs/app-config.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# 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` |
-| `DSN` | PostgreSQL DSN，设置后优先于 SQLite | 空 |
-| `SQL_DSN` | 兼容旧命名的 PostgreSQL DSN，优先级低于 `DSN` | 空 |
-| `REDIS_CONN_STRING` | Redis 连接串 | 空 |
-| `UPLOAD_PATH` | 上传目录 | `upload` |
-| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 |
-
-说明：
-
-* `DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN`
-* `DSN` 或 `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 PostgreSQL
-* 当目标 PostgreSQL 数据库为空且本地 `SQLITE_PATH` 文件存在时，Server 启动阶段会自动迁移 SQLite 数据，并在日志中输出按表迁移进度
-* `SESSION_SECRET` 生产环境必须显式配置
-* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现
-
-### 1.3 `Option` 表中的运行时配置
-
-以下配置由管理端设置页维护，可热更新：
-
-| 配置项 | 作用 | 默认值 |
-| --- | --- | --- |
-| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
-| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` |
-| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
-| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` |
-| `RegisterEnabled` | 是否允许新用户注册 | `false` |
-| `PasswordRegisterEnabled` | 是否允许通过密码方式注册 | `true` |
-| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` |
-| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数（至少 1 天） | `30` |
-| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` |
-| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` |
-| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` |
-| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` |
-| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` |
-
-说明：
-
-* `DatabaseAutoCleanupEnabled` 开启后，Server 会在每天凌晨 3 点自动清理 `node_access_logs`、`node_metric_snapshots`、`node_request_reports` 三类观测数据
-* `DatabaseAutoCleanupRetentionDays` 为统一保留天数，必须大于等于 1；管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录
-
-### 1.4 OpenResty 参数
-
-OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括：
-
-* `OpenRestyWorkerProcesses`
-* `OpenRestyWorkerConnections`
-* `OpenRestyWorkerRlimitNofile`
-* `OpenRestyKeepaliveTimeout`
-* `OpenRestyProxyConnectTimeout`
-* `OpenRestyProxySendTimeout`
-* `OpenRestyProxyReadTimeout`
-* `OpenRestyProxyBufferingEnabled`
-* `OpenRestyGzipEnabled`
-* `OpenRestyCacheEnabled`
-* `OpenRestyCachePath`
-* `OpenRestyCacheMaxSize`
-
-这类参数必须以结构化方式校验、保存并参与版本渲染。
-
-* 管理端不再暴露 `resolver` 配置；规则上游统一渲染为 named `upstream` 并启用 keepalive，单上游如带 base path 或 query，会在 `proxy_pass` 中补回原始 URI。
-* 多上游仍要求每个上游都为纯 `scheme://host[:port]`，且同一规则内协议一致，避免在负载均衡模式下引入不可预测的 URI 差异。
-* `OpenRestyCacheEnabled` 用于启用缓存基础设施与全局默认参数；实际是否缓存、按 URL / 后缀 / 路径等命中策略由各条 `proxy_routes` 单独决定，不再默认对所有规则开启缓存。
-* 默认缓存 Key 为 `$scheme$host$request_uri`，更贴近代理域名维度；如需按其他维度命中，可在性能页显式覆盖。
-* 默认 `keepalive_timeout` 为 `20` 秒，默认 `proxy_connect_timeout` 为 `3` 秒，优先兼顾资源占用与回源失败切换速度。
-* 默认事件模型为 `epoll`，并默认开启 `multi_accept`；HTTPS 监听默认使用独立 `http2 on;` 指令，避免新版 Nginx/OpenResty 对 `listen ... http2` 的弃用告警。
-### 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 配置字段
-
-| 字段 | 作用 | 是否必填 | 默认值/行为 |
-| --- | --- | --- | --- |
-| `server_url` | 控制面地址 | 是 | 无 |
-| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 |
-| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
-| `node_name` | 节点名称 | 否 | 自动使用主机名 |
-| `node_ip` | 节点 IP | 否 | 自动探测，优先选择公网 IPv4；仅无公网地址时退回可用内网地址 |
-| `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` 毫秒 |
-
-说明：
-
-* `agent_token` 与 `discovery_token` 不能同时为空
-* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串
-* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式
-* Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址
-
-## 3. 维护要求
-
-以下内容变化时，必须同步更新本文档：
-
-* Server 命令行参数
-* Server 环境变量
-* Agent 命令行参数
-* Agent 配置字段
-* 任一配置项的默认值、用途或示例
diff --git a/docs/config.ts b/docs/config.ts
index acc09154..fcafd177 100644
--- a/docs/config.ts
+++ b/docs/config.ts
@@ -68,6 +68,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
items: [
{ text: '概览', link: '' },
{ text: '快速开始', link: 'quick-start' },
+ { text: '部署说明', link: 'deployment' },
{ text: '启动 Server', link: 'server' },
{ text: '接入 Agent', link: 'agent' },
{ text: '发布第一份配置', link: 'first-site' },
diff --git a/docs/design.md b/docs/design.md
deleted file mode 100644
index 173b9b38..00000000
--- a/docs/design.md
+++ /dev/null
@@ -1,181 +0,0 @@
-# OpenFlare 设计基线
-
-本文档定义 OpenFlare `1.0.0` 之后仍然有效的产品边界、系统结构与长期约束。第六版已经完成并并入正式版；过程性设计不再在这里维护。
-
-## 1. 产品定位
-
-OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。
-
-当前稳定能力包括：
-
-* 反代规则管理
-* 网站级配置与多域名绑定
-* 源站管理与复用
-* 配置预览、发布、激活与回滚
-* Agent 注册、心跳、同步、应用结果上报
-* OpenResty 主配置模板、性能参数与缓存参数托管
-* HTTPS/TLS 与域名资产管理
-* 节点请求聚合、资源快照、健康事件与看板展示
-* 节点管理、令牌体系、部署与更新链路
-* 基于 Next.js 的正式管理端前端
-
-默认工作方式：
-
-* 所有节点消费同一份全局激活版本
-* Server 保存配置与状态，不直接 SSH 管理节点
-* Agent 是节点侧唯一受控落地入口
-
-## 3. 技术基线
-
-### 3.1 Server
-
-`openflare_server` 继续作为单体控制面：
-
-* Gin
-* GORM
-* SQLite / PostgreSQL
-* 现有登录与 Session 体系
-* 托管 `openflare_server/web` 静态构建产物
-
-### 3.2 Agent
-
-`openflare_agent` 继续作为 Go 单体程序：
-
-* 单二进制
-* 节点本地执行
-* `openresty_path` 优先
-* 未配置 `openresty_path` 时默认使用 Docker OpenResty
-
-### 3.3 Frontend
-
-`openflare_server/web` 是正式前端基线：
-
-* Next.js App Router
-* React 19
-* TypeScript
-* Tailwind CSS
-* 静态导出后由 Go Server 托管
-
-## 4. 总体架构
-
-```text
-OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
- |
- | HTTP API / Config Pull
- v
-OpenFlare Agent (register / heartbeat / sync / apply / update)
- |
- v
-Local OpenResty or Docker OpenResty
- |
- v
-Origin
-```
-
-职责分工：
-
-* Server 负责配置、版本、节点、设置、证书、管理端 UI 与聚合查询
-* Agent 负责本地写入、校验、reload、回滚、自更新与轻量采集
-* 发布通过“生成完整版本并激活”完成
-* 历史版本不可变
-* heartbeat 响应返回激活版本摘要，Agent 仅在不一致时拉取完整配置
-
-## 5. 核心对象
-
-当前有效实体：
-
-* `proxy_routes`
-* `origins`
-* `config_versions`
-* `nodes`
-* `node_system_profiles`
-* `apply_logs`
-* `tls_certificates`
-* `managed_domains`
-* `node_request_reports`
-* `node_access_logs`
-* `node_metric_snapshots`
-* `traffic_analytics_rollups`
-* `node_health_events`
-
-稳定约束：
-
-* `proxy_routes` 从“单域名规则”升级为“网站配置”聚合对象；一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置
-* `proxy_routes.site_name` 是网站的业务唯一标识；新建时默认取 `domains[0]`，后续允许独立维护，不随域名改动自动重写
-* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名；任一域名全局只能属于一个 `proxy_routes`
-* 为兼容历史数据，迁移期可保留 `proxy_routes.domain` 作为 `domains[0]` 的镜像字段，但业务读写与后续扩展必须以 `site_name` + `domains` 为准
-* `origins` 只保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略
-* `proxy_routes` 可选关联一个 `origins` 记录，用于复用源站地址；规则仍保存完整 `origin_url` 快照以参与渲染与版本快照
-* `proxy_routes` 至少包含一个上游地址；为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡
-* `proxy_routes` 上游统一渲染为带 keepalive 的 named `upstream`；单上游可附带 base path 或 query 并在 `proxy_pass` 中追加，多上游仍限定为纯 `scheme://host[:port]`
-* `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头；未设置时默认透传访问域名
-* 网站级流量限制、反向代理与缓存配置当前按站点共享，不在同一网站内做域名级差异化配置；但 HTTPS 允许在同一站点内按域名绑定证书
-* `proxy_routes.domain_cert_ids` 用于记录与 `domains` 平行的域名证书绑定；值为 `0` 表示该域名不启用 HTTPS，仅保留 HTTP
-* 发布渲染时，带证书的域名按证书分组输出独立 `443 ssl` `server` 块；未绑定证书的域名不得被自动带入 HTTPS
-* 发布渲染时必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散
-* 所有上游地址都必须为合法 `http://` 或 `https://`
-* `config_versions` 必须保存完整快照、渲染结果与 `checksum`
-* 全局同时只能有一个激活版本
-* 回滚通过重新激活旧版本实现
-* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实
-* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计
-* 访问明细只保留受控时间窗口，不演变成通用日志平台
-
-## 6. 发布模型
-
-标准链路：
-
-```text
-修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
-```
-
-发布规则：
-
-1. 读取全部启用的 `proxy_routes`
-2. 读取 Server 侧 OpenResty 主配置与结构化参数
-3. 渲染完整 OpenResty 配置
-4. 计算 `checksum`
-5. 写入 `config_versions`
-6. 切换激活版本
-7. Agent 在后续 heartbeat 中发现并应用
-
-版本号格式固定为 `YYYYMMDD-NNN`。
-
-## 7. 模块边界
-
-### 7.1 `openflare_server`
-
-负责：
-
-* 管理端 UI 与 API
-* Agent API
-* 配置渲染与版本发布
-* 数据存储与聚合查询
-* OpenResty 主配置模板、性能参数与缓存参数管理
-
-### 7.2 `openflare_agent`
-
-负责：
-
-* 首次注册与凭证置换
-* 周期性心跳与同步
-* 主配置、路由配置、证书与 Lua 资源写入
-* 执行 `openresty -t` / `openresty -s reload`
-* 失败回滚
-* 对已失败并回退的目标版本做本地熔断，直到控制面出现新的激活版本
-* 节点观测采集与结果上报
-
-### 7.3 `openflare_server/web`
-
-负责：
-
-* 管理端页面、布局、交互与主题
-* 总览、节点详情、规则、版本、节点、证书、域名、用户与设置页面
-* 统一请求层与前端状态管理
-
-## 8. 文档维护原则
-
-* 产品范围或系统边界变化时更新本文档
-* 已完成阶段不再以“版本计划”形式回填
-* 新阶段开始前，先补设计，再进入实现
-* 涉及网站级规则改造的详细需求与实施顺序，见 [docs/website-configuration-redesign.md](./website-configuration-redesign.md)
diff --git a/docs/design/development.md b/docs/design/development.md
index 265190f1..164ac22f 100644
--- a/docs/design/development.md
+++ b/docs/design/development.md
@@ -1,35 +1,287 @@
# 开发约束
-OpenFlare `1.0.0` 之后的开发优先关注稳定性、升级与回滚链路可靠性、文档准确性、测试覆盖补强，以及既有边界内的小步迭代。
+本文档融合原开发规范、前端规范与开发计划，是 OpenFlare `1.0.0` 之后的工程约束入口。
+
+## 当前结论
+
+* 第一版至第六版的主线能力已经全部完成。
+* `1.0.0` 是当前正式基线。
+* 已完成阶段的过程性任务以代码、测试与 Git 历史为准。
+* 新工作优先以缺陷修复、可维护性改进、文档与测试补强为主。
+
+当前开发优先级：
+
+1. 稳定性。
+2. 升级与回滚链路可靠性。
+3. 文档准确性。
+4. 测试覆盖补强。
+5. 在既有边界内的小步迭代。
## 变更准入
新需求进入实现前，按以下顺序判断：
-1. 是否符合产品边界。
-2. 是否符合后端、Agent 与前端开发规范。
-3. 是否会破坏发布、同步、回滚或升级主链路。
-4. 是否需要同步更新部署、配置或 README 文档。
+1. 是否符合 [产品边界](./)。
+2. 是否符合本文档的后端、Agent 与前端约束。
+3. 是否会破坏现有发布、同步、回滚或升级主链路。
+4. 是否需要同步更新部署、配置、README 或文档站页面。
如果需求超出边界或引入新基础设施，应先更新设计文档，再开始实现。
+任何合入正式基线的改动，至少应满足：
+
+* 不破坏 Agent 心跳、同步、发布与回滚主链路。
+* 不破坏现有 OpenResty 主配置托管模型。
+* 不降低总览、节点详情与访问分析的既有可用性。
+* 有与风险相称的测试或联调验证。
+* 文档与代码保持一致。
+
+## 技术基线
+
+Server：
+
+* Go 1.24+
+* Gin
+* GORM
+* SQLite / PostgreSQL
+* 现有登录体系
+
+Agent：
+
+* Go 1.24+
+* 单二进制
+* 节点本地执行
+* `openresty_path` 优先
+* 无 `openresty_path` 时默认 Docker OpenResty
+
+Frontend：
+
+* Next.js 15 App Router
+* React 19
+* TypeScript 5
+* Tailwind CSS 4
+* TanStack Query
+* React Hook Form + Zod
+* Zustand 仅用于轻量客户端状态
+* ESLint + Prettier
+* Vitest + Testing Library + Playwright
+* pnpm
+
+## Server 分层
+
+| 目录 | 职责 |
+| --- | --- |
+| `controller/` | 参数解析、调用 service、返回响应 |
+| `service/` | 业务逻辑、校验、事务编排、渲染 |
+| `model/` | 模型定义与持久化 |
+| `router/` | 路由注册 |
+| `middleware/` | 认证、鉴权、限流等横切逻辑 |
+| `common/` | 配置、全局状态与初始化入口 |
+| `utils/` | 纯工具函数与通用 helper |
+
+禁止在 `controller/` 堆积业务逻辑，禁止在 `middleware/` 实现业务流程，禁止为简单需求新增平台层抽象。
+
+## Agent 分层
+
+Agent 保持现有模块边界：
+
+* `config`
+* `heartbeat`
+* `sync`
+* `openresty` / `nginx`
+* `state`
+* `httpclient`
+* `protocol`
+* `internal/updater`
+
+要求：
+
+* 每个模块职责单一。
+* 外部命令调用集中封装。
+* 状态落盘与配置落盘分离。
+
+## Frontend 分层
+
+推荐目录：
+
+```text
+app/
+components/
+features/
+lib/
+hooks/
+store/
+types/
+styles/
+tests/
+```
+
+职责约束：
+
+* `app/`：路由、布局、页面组装。
+* `features/`：按业务域组织模块。
+* `components/`：跨 feature 复用组件。
+* `lib/`：请求客户端、环境变量、工具函数、常量。
+* `store/`：少量跨页面 UI 状态。
+* `types/`：共享类型定义。
+
+页面文件只负责获取路由参数、组织页面结构、调用 feature 组件；不应手写复杂 API 细节、复杂表单校验逻辑或维护大量彼此耦合的局部状态。
+
+## 数据模型规范
+
+当前有效实体：
+
+* `proxy_routes`
+* `origins`
+* `config_versions`
+* `nodes`
+* `node_system_profiles`
+* `apply_logs`
+* `tls_certificates`
+* `managed_domains`
+* `node_request_reports`
+* `node_access_logs`
+* `node_metric_snapshots`
+* `traffic_analytics_rollups`
+* `node_health_events`
+* `options`
+
+通用约束：
+
+* 不新增平台化对象，除非设计文档明确要求。
+* `origins` 仅作为可复用源站地址目录，字段保持轻量。
+* `proxy_routes` 以“网站配置”作为聚合边界，必须包含唯一 `site_name` 与非空 `domains` 列表。
+* `proxy_routes.domains` 中的每个域名都必须全局唯一，列表第一项视为主域名。
+* `proxy_routes` 继续允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool`。
+* 遗留 `domain` 字段只能作为 `domains[0]` 的兼容镜像；新代码不得继续以该字段作为唯一业务输入。
+* `proxy_routes` 如关联 `origins`，必须同时保存可直接渲染的 `origin_url`。
+* 上游统一使用 named `upstream` + keepalive；单上游如带 base path 或 query，应在 `proxy_pass` 上补回 URI，多上游仅允许纯 `scheme://host[:port]`。
+* 流量限制、反向代理与缓存配置当前都归属站点级 `proxy_routes`。
+* HTTPS 证书绑定必须通过与 `domains` 平行的 `domain_cert_ids` 逐域名保存；未绑定证书的域名不得参与 HTTPS 渲染。
+* `config_versions` 必须保存完整快照与渲染结果。
+* 全局同时只能有一个激活版本。
+* 回滚通过重新激活旧版本实现。
+* `nodes` 只保留控制面状态与低频摘要。
+* 观测数据必须按节点与时间窗口关联，快照与聚合结果采用追加式模型。
+* 原始访问明细必须有受控保留策略。
+
## 数据库迁移
-任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号，并补充从上一版本升级到新版本的显式迁移方法。
+任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号。
-迁移必须包含升级后的校验逻辑。迁移失败或校验失败时，启动流程必须中止，且不得提升数据库版本记录。
+数据库版本号定义在 `openflare_server/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库。
-## 前端约束
+每次提升数据库版本号时，必须补充从上一版本升级到新版本的显式迁移方法。迁移方法必须包含升级后的校验逻辑；只有校验通过，才能写入新的数据库版本记录。
-前端以 `openflare_server/web` 为准：
+新包启动后必须先检查数据库当前版本，再按顺序逐步升级到目标版本；禁止跳过中间升级步骤直接写目标版本。
-* 页面路由与布局放在 `app/`。
-* API 请求统一收敛到 `lib/api/`。
-* 业务逻辑优先放在 `features/`。
-* 服务端状态使用 TanStack Query。
-* 表单使用 React Hook Form 与 Zod。
-* 主题必须支持 `light`、`dark`、`system`。
+空库初始化可以直接建立当前版本结构，但初始化完成后仍必须执行同版本校验，并落库当前数据库版本。
+
+如果迁移失败或校验失败，启动流程必须中止，且不得提升数据库版本记录。涉及数据库版本变更的提交，必须补充对应的迁移测试或等效回归测试。
+
+## API 与鉴权
+
+管理端与 Agent API 统一使用 JSON。成功与失败都必须返回清晰 `message`：
+
+```json
+{
+ "success": true,
+ "message": "",
+ "data": {}
+}
+```
+
+约定：
+
+* Agent API 固定放在 `/api/agent/*`。
+* 总览与节点详情优先使用专用聚合接口。
+* 管理端变更类接口统一使用 `POST`；只读接口使用 `GET`。
+* 管理端继续复用现有登录、角色与 Session。
+* Agent 正式请求统一使用节点专属 `agent_token`。
+* 首次接入可使用全局 `discovery_token`。
+* Agent 请求头统一使用 `X-Agent-Token`。
+
+禁止暴露远程 shell 或任意命令执行入口，禁止在日志中打印完整 Token，禁止绕过占位符约束保存不可渲染的主配置模板。
+
+## 发布与运行
+
+发布逻辑必须保持：
+
+* 发布时读取全部启用的 `proxy_routes`。
+* 同时读取 OpenResty 主配置参数、反代性能参数与缓存参数。
+* 生成完整 OpenResty 配置。
+* 计算 `checksum`。
+* 写入 `config_versions`。
+* 通过切换 `is_active` 激活版本。
+
+版本约束：
+
+* 版本号格式固定为 `YYYYMMDD-NNN`。
+* 不在线修改历史版本。
+* 不做按节点分组的差异化版本。
+* 预览与 diff 是只读能力，不产生发布记录。
+
+Agent 必须满足：
+
+* 启动后读取或生成本地 `node_id`。
+* 周期性心跳与同步。
+* 常规同步优先依据 heartbeat 返回的版本摘要判断。
+* 发现新版本时先备份旧文件。
+* 写入主配置、路由配置与必要证书文件。
+* 写入新配置后以运行态恢复为目标执行激活，Docker 模式优先重建容器并确认容器保持运行。
+* 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty。
+* 回滚后 OpenResty 恢复正常时上报警告；回滚后仍无法恢复运行时上报失败。
+* 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用。
+
+## 前端请求、状态与类型
+
+所有 API 请求必须统一经过 `lib/api/`：
+
+* 统一处理 `success/message/data` 响应结构。
+* 统一处理鉴权失效、网络异常和通用错误消息。
+* 统一维护资源接口与请求路径。
+
+状态分层：
+
+* 服务端状态：TanStack Query。
+* 页面临时状态：组件内部 `useState`。
+* 跨页面 UI 状态：Zustand。
+
+要求开启 TypeScript 严格模式，禁止滥用 `any`，API 响应、表单输入、业务实体必须有明确类型。
+
+## 表单、交互、样式与主题
+
+表单统一使用 React Hook Form 与 Zod。
+
+高风险操作必须二次确认、展示操作对象名称，并明确成功与失败反馈。
+
+样式原则：
+
+* 统一使用 Tailwind CSS 与现有 token 体系。
+* 优先复用已有基础组件与布局组件。
+* 保持视觉层级、留白与语义颜色一致。
+
+主题要求：
+
+* 同时支持 `light`、`dark`、`system`。
+* 用户选择必须持久化。
+* 首屏尽量避免主题闪烁。
## 测试与交付
-关键业务逻辑必须有单元测试或等效回归测试。任何正式基线改动至少应保证不破坏 Agent 心跳、同步、发布与回滚主链路。
+* 关键业务逻辑必须有单元测试或等效回归测试。
+* Agent 主链路修改必须验证同步、应用与回滚。
+* 前端页面至少覆盖加载态、空态、错误态与成功反馈。
+* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流。
+
+## 后续维护方式
+
+后续规划不再按“大版本阶段文档”维护，而采用以下方式：
+
+* 产品边界变动：更新 [产品边界](./)。
+* 工程约束变动：更新本文档。
+* 部署与配置变动：更新 [部署说明](../guide/deployment.md)、[配置项](../reference/configuration.md) 与 README。
+
+如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文档。
+
+当前专项“网站级规则与配置界面改造”的模型边界已纳入 [产品边界](./)，执行时仍按数据模型、接口、前端页面、迁移测试与文档联动的顺序推进。
diff --git a/docs/design/index.md b/docs/design/index.md
index 4e88e009..125eaee3 100644
--- a/docs/design/index.md
+++ b/docs/design/index.md
@@ -7,15 +7,93 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
| 能力 | 说明 |
| --- | --- |
| 反代规则管理 | 以网站配置为聚合边界，支持多域名与源站配置 |
-| 配置版本 | 支持预览、发布、激活、历史回滚 |
-| Agent 同步 | 支持注册、心跳、同步、应用结果上报 |
+| 网站级配置 | 一条规则对应一个网站，可绑定一个或多个域名，并共享站点级配置 |
+| 源站管理 | 维护轻量源站目录，并允许网站保存可渲染的源站快照 |
+| 配置版本 | 支持预览、发布、激活、不可变历史与回滚 |
+| Agent 同步 | 支持注册、心跳、同步、应用结果上报与自更新 |
| OpenResty 托管 | 管理主配置模板、性能参数、缓存参数与 Lua 资源 |
| HTTPS/TLS | 托管证书与域名资产，并按域名绑定证书 |
| 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 |
| 节点管理 | 节点状态、令牌体系、部署与更新链路 |
+| 管理端前端 | 基于 Next.js 的正式管理端 |
默认工作方式：
* 所有节点消费同一份全局激活版本。
* Server 保存配置与状态，不直接 SSH 管理节点。
* Agent 是节点侧唯一受控落地入口。
+
+## 核心对象
+
+当前有效实体：
+
+* `proxy_routes`
+* `origins`
+* `config_versions`
+* `nodes`
+* `node_system_profiles`
+* `apply_logs`
+* `tls_certificates`
+* `managed_domains`
+* `node_request_reports`
+* `node_access_logs`
+* `node_metric_snapshots`
+* `traffic_analytics_rollups`
+* `node_health_events`
+
+## 网站配置约束
+
+`proxy_routes` 从“单域名规则”升级为“网站配置”聚合对象。一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置。
+
+约束：
+
+* `proxy_routes.site_name` 是网站的业务唯一标识。
+* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名。
+* 任一域名全局只能属于一个 `proxy_routes`。
+* 迁移期可保留 `proxy_routes.domain` 作为 `domains[0]` 的镜像字段，但业务读写与后续扩展必须以 `site_name` + `domains` 为准。
+* 网站级流量限制、反向代理与缓存配置当前按站点共享，不在同一网站内做域名级差异化配置。
+* HTTPS 允许在同一站点内按域名绑定证书。
+
+## 源站约束
+
+`origins` 只保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略。
+
+`proxy_routes` 可选关联一个 `origins` 记录，用于复用源站地址；规则仍保存完整 `origin_url` 快照以参与渲染与版本快照。
+
+上游约束：
+
+* `proxy_routes` 至少包含一个上游地址。
+* 为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡。
+* 上游统一渲染为带 keepalive 的 named `upstream`。
+* 单上游可附带 base path 或 query 并在 `proxy_pass` 中追加。
+* 多上游限定为纯 `scheme://host[:port]`。
+* `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头。
+* 所有上游地址都必须为合法 `http://` 或 `https://`。
+
+## HTTPS 约束
+
+`proxy_routes.domain_cert_ids` 用于记录与 `domains` 平行的域名证书绑定；值为 `0` 表示该域名不启用 HTTPS，仅保留 HTTP。
+
+发布渲染时：
+
+* 带证书的域名按证书分组输出独立 `443 ssl` `server` 块。
+* 未绑定证书的域名不得被自动带入 HTTPS。
+* 必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。
+
+## 版本与观测约束
+
+* `config_versions` 必须保存完整快照、渲染结果与 `checksum`。
+* 全局同时只能有一个激活版本。
+* 回滚通过重新激活旧版本实现。
+* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实。
+* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计。
+* 访问明细只保留受控时间窗口，不演变成通用日志平台。
+
+## 文档维护原则
+
+* 产品范围或系统边界变化时更新本文档。
+* 开发约束、代码规范、接口约定变化时更新 [开发约束](./development.md)。
+* 部署方式变化时更新 [部署说明](../guide/deployment.md) 与 README。
+* 配置项变化时更新 [配置项参考](../reference/configuration.md)。
+* 已完成阶段不再以“版本计划”形式回填。
+* 新阶段开始前，先补设计，再进入实现。
diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md
deleted file mode 100644
index 14f5444d..00000000
--- a/docs/development-guidelines.md
+++ /dev/null
@@ -1,232 +0,0 @@
-# OpenFlare 开发规范
-
-本文档描述 OpenFlare `1.0.0` 正式版之后的开发基线。
-
-超出 [docs/design.md](./design.md) 边界的需求，必须先更新设计文档。
-
-## 1. 技术基线
-
-### 1.1 Server
-
-`openflare_server` 继续作为单体控制面：
-
-* Go 1.24+
-* Gin
-* GORM
-* SQLite / PostgreSQL
-* 现有登录体系
-
-### 1.2 Agent
-
-`openflare_agent` 继续作为 Go 单体程序：
-
-* Go 1.24+
-* 单二进制
-* 节点本地执行
-* `openresty_path` 优先
-* 无 `openresty_path` 时默认 Docker OpenResty
-
-### 1.3 Frontend
-
-前端基线以 `openflare_server/web` 为准：
-
-* Next.js 15 App Router
-* React 19
-* TypeScript
-* Tailwind CSS 4
-* TanStack Query
-* React Hook Form + Zod
-* Zustand 仅用于轻量客户端状态
-
-前端细则见 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)。
-
-## 2. 分层与目录约束
-
-### 2.1 Server
-
-* `controller/`：参数解析、调用 service、返回响应
-* `service/`：业务逻辑、校验、事务编排、渲染
-* `model/`：模型定义与持久化
-* `router/`：路由注册
-* `middleware/`：认证、鉴权、限流等横切逻辑
-* `common/`：配置、全局状态与初始化入口
-* `utils/`：纯工具函数与通用 helper
-
-禁止：
-
-* 在 `controller/` 堆积业务逻辑
-* 在 `middleware/` 实现业务流程
-* 为简单需求新增平台层抽象
-
-### 2.2 Agent
-
-保持现有模块边界：
-
-* `config`
-* `heartbeat`
-* `sync`
-* `openresty`
-* `state`
-* `httpclient`
-* `protocol`
-* `internal/updater`
-
-要求：
-
-* 每个模块职责单一
-* 外部命令调用集中封装
-* 状态落盘与配置落盘分离
-
-### 2.3 Frontend
-
-前端分层保持：
-
-* `app/`
-* `features/`
-* `components/`
-* `lib/`
-* `store/`
-* `types/`
-
-要求：
-
-* 页面路由与布局放在 `app/`
-* API 请求统一收敛到 `lib/api/`
-* 业务逻辑优先放在 `features/`
-
-## 3. 数据模型规范
-
-当前有效实体：
-
-* `proxy_routes`
-* `origins`
-* `config_versions`
-* `nodes`
-* `node_system_profiles`
-* `apply_logs`
-* `tls_certificates`
-* `managed_domains`
-* `node_request_reports`
-* `node_access_logs`
-* `node_metric_snapshots`
-* `traffic_analytics_rollups`
-* `node_health_events`
-* `options`
-
-通用约束：
-
-* 不新增平台化对象，除非设计文档明确要求
-* `origins` 仅作为可复用源站地址目录，字段保持轻量；协议、端口、路径与查询参数继续归属具体 `proxy_routes`
-* `proxy_routes` 以“网站配置”作为聚合边界，必须包含唯一 `site_name` 与非空 `domains` 列表；数据库内部 `id` 可继续作为技术主键，但不能替代 `site_name` 的业务唯一性
-* `proxy_routes.domains` 中的每个域名都必须全局唯一；列表第一项视为主域名，创建时若未显式填写 `site_name`，则默认使用主域名
-* `proxy_routes` 继续允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool`
-* 迁移期如保留遗留 `domain` 字段，只能作为 `domains[0]` 的兼容镜像；新代码不得继续以该字段作为唯一业务输入
-* `proxy_routes` 如关联 `origins`，必须同时保存可直接渲染的 `origin_url`；源站地址变更时，由 service 负责同步更新引用该源站的规则快照
-* `proxy_routes` 的上游统一使用 named `upstream` + keepalive；单上游如带 base path 或 query，应在 `proxy_pass` 上补回 URI，多上游仅允许纯 `scheme://host[:port]`
-* `proxy_routes.origin_host` 为可选字段，仅用于覆盖回源 `Host` 请求头，不引入新的平台化对象
-* 流量限制、反向代理与缓存配置当前都归属站点级 `proxy_routes`，同一网站内不拆分域名级差异配置
-* HTTPS 的启停仍由站点级 `proxy_routes` 控制，但证书绑定必须通过与 `domains` 平行的 `domain_cert_ids` 记录逐域名保存；未绑定证书的域名不得参与 HTTPS 渲染
-* `proxy_routes.cert_ids` 仅作为站点级证书集合与兼容镜像，必须由 `domain_cert_ids` 推导生成；`cert_id` 继续作为首个已使用证书的兼容镜像
-* `config_versions` 必须保存完整快照与渲染结果
-* 全局同时只能有一个激活版本
-* 回滚通过重新激活旧版本实现
-* `nodes` 只保留控制面状态与低频摘要
-* 观测数据必须按节点与时间窗口关联
-* 快照与聚合结果采用追加式模型，不覆盖历史
-* 原始访问明细必须有受控保留策略
-
-### 3.1 数据库版本与迁移
-
-* 任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号
-* 数据库版本号定义在 `openflare_server/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库
-* 每次提升数据库版本号时，必须补充从上一版本升级到新版本的显式迁移方法
-* 迁移方法必须包含升级后的校验逻辑；只有校验通过，才能写入新的数据库版本记录
-* 新包启动后必须先检查数据库当前版本，再按顺序逐步升级到目标版本；禁止跳过中间升级步骤直接写目标版本
-* 空库初始化可以直接建立当前版本结构，但初始化完成后仍必须执行同版本校验，并落库当前数据库版本
-* 数据库版本元数据属于内部控制信息，必须保存在独立内部表中，不能混入业务配置表
-* 如果迁移失败或校验失败，启动流程必须中止，且不得提升数据库版本记录
-* 涉及数据库版本变更的提交，必须补充对应的迁移测试或等效回归测试
-
-## 4. API 与鉴权规范
-
-### 4.1 API
-
-* 管理端与 Agent API 统一使用 JSON
-* 成功与失败都必须返回清晰 `message`
-* Agent API 固定放在 `/api/agent/*`
-* 总览与节点详情优先使用专用聚合接口
-* 管理端变更类接口统一使用 `POST`；只读接口使用 `GET`
-
-统一响应结构：
-
-```json
-{
- "success": true,
- "message": "",
- "data": {}
-}
-```
-
-### 4.2 鉴权
-
-管理端：
-
-* 继续复用现有登录、角色与 Session
-
-Agent：
-
-* 正式请求统一使用节点专属 `agent_token`
-* 首次接入可使用全局 `discovery_token`
-* 请求头统一使用 `X-Agent-Token`
-
-禁止：
-
-* 暴露远程 shell 或任意命令执行入口
-* 在日志中打印完整 Token
-* 允许绕过占位符约束保存不可渲染的主配置模板
-
-## 5. 发布与运行规范
-
-发布逻辑必须保持以下事实：
-
-* 发布时读取全部启用的 `proxy_routes`
-* 同时读取 OpenResty 主配置参数、反代性能参数与缓存参数
-* 生成完整 OpenResty 配置
-* 计算 `checksum`
-* 写入 `config_versions`
-* 通过切换 `is_active` 激活版本
-
-版本约束：
-
-* 版本号格式固定为 `YYYYMMDD-NNN`
-* 不在线修改历史版本
-* 不做按节点分组的差异化版本
-* 预览与 diff 是只读能力，不产生发布记录
-
-Agent 必须满足：
-
-* 启动后读取或生成本地 `node_id`
-* 周期性心跳与同步
-* 常规同步优先依据 heartbeat 返回的版本摘要判断
-* 发现新版本时先备份旧文件
-* 写入主配置、路由配置与必要证书文件
-* 写入新配置后以运行态恢复为目标执行激活，Docker 模式优先重建容器并确认容器保持运行
-* 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty
-* 回滚后 OpenResty 恢复正常时上报警告；回滚后仍无法恢复运行时上报失败
-* 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用；只有远端激活版本或 checksum 发生变化时，才允许再次尝试
-
-## 6. 测试与交付要求
-
-* 关键业务逻辑必须有单元测试或等效回归测试
-* Agent 主链路修改必须验证同步、应用与回滚
-* 前端页面至少覆盖加载态、空态、错误态与成功反馈
-* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流
-
-## 7. 文档维护要求
-
-当以下内容变化时，必须同步更新对应文档：
-
-* 产品范围或系统边界变化：更新 `docs/design.md`
-* 开发约束、接口约定、测试基线变化：更新本文档
-* 前端工程约束变化：更新 `docs/frontend-development-guidelines.md`
-* 配置项或部署方式变化：更新 `docs/app-config.md`、`docs/deployment.md` 与 `README.md`
diff --git a/docs/development-plan.md b/docs/development-plan.md
deleted file mode 100644
index f8d74b41..00000000
--- a/docs/development-plan.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# OpenFlare 开发计划
-
-## 1. 当前结论
-
-* 第一版至第六版的主线能力已经全部完成
-* `1.0.0` 是当前正式基线
-* 已完成阶段的过程性任务以代码、测试与 Git 历史为准
-* 新工作优先以缺陷修复、可维护性改进、文档与测试补强为主
-
-## 2. 当前优先级
-
-当前开发应优先关注：
-
-1. 稳定性
-2. 升级与回滚链路可靠性
-3. 文档准确性
-4. 测试覆盖补强
-5. 在既有边界内的小步迭代
-
-## 3. 变更准入原则
-
-新需求进入实现前，按以下顺序判断：
-
-1. 是否符合 [docs/design.md](./design.md) 的产品边界
-2. 是否符合 [docs/development-guidelines.md](./development-guidelines.md) 与前端规范
-3. 是否会破坏现有发布、同步、回滚或升级主链路
-4. 是否需要同步更新部署、配置或 README 文档
-
-如果答案包含“超出边界”或“引入新基础设施”，先修改设计文档，再开始实现。
-
-## 4. 当前验收标准
-
-任何合入正式基线的改动，至少应满足：
-
-* 不破坏 Agent 心跳、同步、发布与回滚主链路
-* 不破坏现有 OpenResty 主配置托管模型
-* 不降低总览、节点详情与访问分析的既有可用性
-* 有与风险相称的测试或联调验证
-* 文档与代码保持一致
-
-## 5. 后续维护方式
-
-后续规划不再按“大版本阶段文档”维护，而采用以下方式：
-
-* 产品边界变动：更新 `docs/design.md`
-* 工程约束变动：更新 `docs/development-guidelines.md`
-* 前端工程变动：更新前端相关规范文档
-* 部署与配置变动：更新 `README.md`、`docs/deployment.md`、`docs/app-config.md`
-
-如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文件。
-
-## 6. 当前专项计划
-
-已确认需要推进“网站级规则与配置界面改造”专项，详细需求、实施顺序与验收标准见 [docs/website-configuration-redesign.md](./website-configuration-redesign.md)。
-
-本专项的执行顺序固定为：
-
-1. 先完成数据模型与配置渲染兼容方案
-2. 再调整接口、校验与版本 diff 语义
-3. 然后改造规则列表与网站配置子页面
-4. 最后补齐迁移、回归测试与文档联动
diff --git a/docs/en/config.ts b/docs/en/config.ts
index b502726c..9aaf1867 100644
--- a/docs/en/config.ts
+++ b/docs/en/config.ts
@@ -40,6 +40,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
items: [
{ text: 'Overview', link: '' },
{ text: 'Quick Start', link: 'quick-start' },
+ { text: 'Deployment', link: 'deployment' },
{ text: 'Run Server', link: 'server' },
{ text: 'Connect Agent', link: 'agent' },
{ text: 'Publish First Site', link: 'first-site' },
diff --git a/docs/en/guide/deployment.md b/docs/en/guide/deployment.md
new file mode 100644
index 00000000..13d96379
--- /dev/null
+++ b/docs/en/guide/deployment.md
@@ -0,0 +1,102 @@
+# Deployment
+
+This page summarizes the OpenFlare deployment baseline, integration flow, upgrade entry points, and Agent install scripts.
+
+## Requirements
+
+Server:
+
+* Go 1.24+
+* Node.js 18+
+* Writable SQLite directory or reachable PostgreSQL instance
+
+Agent:
+
+* Go 1.24+
+* Writable Agent data directory
+* Local mode requires `openresty -t` and `openresty -s reload`
+* Docker mode requires Docker access
+
+## Docker Compose
+
+PostgreSQL is recommended for production:
+
+```yaml
+services:
+ postgres:
+ image: postgres:17-alpine
+ restart: unless-stopped
+ environment:
+ POSTGRES_DB: openflare
+ POSTGRES_USER: openflare
+ POSTGRES_PASSWORD: replace-with-strong-password
+ volumes:
+ - postgres-data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+
+ openflare:
+ image: ghcr.io/rain-kl/openflare:latest
+ container_name: openflare
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ ports:
+ - "3000:3000"
+ environment:
+ SESSION_SECRET: replace-with-random-string
+ SQLITE_PATH: /data/openflare.db
+ DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
+ GIN_MODE: release
+ LOG_LEVEL: info
+ volumes:
+ - openflare-data:/data
+
+volumes:
+ postgres-data:
+ openflare-data:
+```
+
+```bash
+docker compose up -d
+```
+
+Open `http://localhost:3000`. The default account is `root` / `123456`; change the password immediately.
+
+## Agent Install
+
+Using `discovery_token`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+ --server-url http://your-server:3000 \
+ --discovery-token YOUR_DISCOVERY_TOKEN
+```
+
+Using node-specific `agent_token`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+ --server-url http://your-server:3000 \
+ --agent-token YOUR_AGENT_TOKEN
+```
+
+Supported options include `--server-url`, `--discovery-token`, `--agent-token`, `--install-dir`, `--repo`, and `--no-service`.
+
+## Validation
+
+1. Prepare `agent_token` or `discovery_token` in the console.
+2. Start Agent and confirm the node is online.
+3. Add an enabled reverse proxy site.
+4. Publish and activate a new version.
+5. Confirm Agent pulls, validates, reloads, and reports the result.
+
+## Uninstall Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
+```
diff --git a/docs/en/guide/index.md b/docs/en/guide/index.md
index fbdea93d..81d0bfab 100644
--- a/docs/en/guide/index.md
+++ b/docs/en/guide/index.md
@@ -5,7 +5,8 @@ This section helps operators take OpenFlare from first boot to the first working
Suggested order:
1. [Quick Start](./quick-start.md): run Server with Docker Compose and complete the first login.
-2. [Run Server](./server.md): learn source startup, frontend build, and Swagger access.
-3. [Connect Agent](./agent.md): use `agent_token` or `discovery_token` to bring a node online.
-4. [Publish First Site](./first-site.md): create a site configuration, publish it, and verify node application.
-5. [Upgrade and Maintenance](./upgrade.md): understand upgrade, uninstall, validation, and maintenance entry points.
+2. [Deployment](./deployment.md): review production deployment, Agent install, validation, and upgrade.
+3. [Run Server](./server.md): learn source startup, frontend build, and Swagger access.
+4. [Connect Agent](./agent.md): use `agent_token` or `discovery_token` to bring a node online.
+5. [Publish First Site](./first-site.md): create a site configuration, publish it, and verify node application.
+6. [Upgrade and Maintenance](./upgrade.md): understand upgrade, uninstall, validation, and maintenance entry points.
diff --git a/docs/frontend-development-guidelines.md b/docs/frontend-development-guidelines.md
deleted file mode 100644
index efe125a8..00000000
--- a/docs/frontend-development-guidelines.md
+++ /dev/null
@@ -1,128 +0,0 @@
-# OpenFlare 前端开发规范
-
-本文档约束 `openflare_server/web` 的正式前端工程。它描述的是 `1.0.0` 之后仍然有效的结构、请求层、组件、样式、状态管理与测试基线。
-
-## 1. 技术基线
-
-默认技术栈：
-
-* Next.js 15 App Router
-* React 19
-* TypeScript 5
-* Tailwind CSS 4
-* TanStack Query
-* React Hook Form + Zod
-* Zustand
-* ESLint + Prettier
-* Vitest + Testing Library + Playwright
-* pnpm
-
-要求：
-
-* 默认使用 TypeScript
-* 默认使用函数组件
-* 默认使用 App Router
-* 前端必须支持 `light`、`dark`、`system` 三种主题模式
-
-
-## 2. 目录与分层
-
-推荐目录：
-
-```text
-app/
-components/
-features/
-lib/
-hooks/
-store/
-types/
-styles/
-tests/
-```
-
-职责约束：
-
-* `app/`：路由、布局、页面组装
-* `features/`：按业务域组织模块
-* `components/`：跨 feature 复用组件
-* `lib/`：请求客户端、环境变量、工具函数、常量
-* `store/`：少量跨页面 UI 状态
-* `types/`：共享类型定义
-
-## 3. 路由与页面
-
-页面文件只负责：
-
-* 获取路由参数
-* 组织页面结构
-* 调用 feature 组件
-
-页面不应负责：
-
-* 手写复杂 API 细节
-* 编写复杂表单校验逻辑
-* 维护大量彼此耦合的局部状态
-
-## 4. 数据请求与类型
-
-### 4.1 请求层
-
-所有 API 请求必须统一经过 `lib/api/`。
-
-要求：
-
-* 统一处理 `success/message/data` 响应结构
-* 统一处理鉴权失效、网络异常和通用错误消息
-* 统一维护资源接口与请求路径
-
-禁止：
-
-* 在页面组件中直接调用 `fetch('/api/...')`
-* 在多个组件中重复拼接同一接口路径
-
-### 4.2 状态分层
-
-* 服务端状态：TanStack Query
-* 页面临时状态：组件内部 `useState`
-* 跨页面 UI 状态：Zustand
-
-不推荐：
-
-* 用 Zustand 保存服务端主数据
-* 用 Context 代替完整数据层方案
-
-### 4.3 类型
-
-要求：
-
-* 开启 TypeScript 严格模式
-* 禁止滥用 `any`
-* API 响应、表单输入、业务实体必须有明确类型
-
-## 5. 表单与交互
-
-统一使用：
-
-* React Hook Form
-* Zod
-
-高风险操作必须：
-
-* 二次确认
-* 展示操作对象名称
-* 明确成功与失败反馈
-
-## 6. 样式与主题
-
-样式原则：
-
-* 统一使用 Tailwind CSS 与现有 token 体系
-* 优先复用已有基础组件与布局组件
-* 保持视觉层级、留白与语义颜色一致
-
-主题要求：
-
-* 同时支持 `light`、`dark`、`system`
-* 用户选择必须持久化
-* 首屏尽量避免主题闪烁
diff --git a/docs/deployment.md b/docs/guide/deployment.md
similarity index 64%
rename from docs/deployment.md
rename to docs/guide/deployment.md
index fbcb1256..a4f6cf61 100644
--- a/docs/deployment.md
+++ b/docs/guide/deployment.md
@@ -1,51 +1,25 @@
-# OpenFlare 部署说明
+# 部署说明
-本文档只保留 OpenFlare `1.0.0` 的当前部署基线、联调入口与升级方式。
+本文档说明 OpenFlare `1.0.0` 之后的部署基线、联调入口、升级方式与 Agent 一键部署流程。
-## 1. 前置条件
+## 前置条件
-### 1.1 Server
+Server：
* Go 1.24+
* Node.js 18+
* 可写 SQLite 文件目录，或可访问的 PostgreSQL 实例
-### 1.2 Agent
+Agent：
* Go 1.24+
* 对 Agent 数据目录有写权限
* 本机模式下可执行 `openresty -t` 与 `openresty -s reload`
* Docker 模式下具备 Docker 执行权限
-## 2. 启动 Server
+## Docker Compose 启动 Server
-### 2.1 构建前端
-
-```bash
-cd openflare_server/web
-corepack enable
-pnpm install
-pnpm build
-```
-
-`pnpm build` 会生成供 Go Server 托管的静态产物。
-
-### 2.2 源码启动
-
-```bash
-cd openflare_server
-export SESSION_SECRET='replace-with-random-string'
-export SQLITE_PATH='./openflare.db'
-export LOG_LEVEL='info'
-# 可选：设置后优先使用 PostgreSQL。
-# 如果 PostgreSQL 为空且本地 SQLite 文件存在，启动时会自动迁移数据。
-# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
-go run .
-```
-
-默认监听 `3000` 端口。
-
-### 2.3 Docker Compose 启动
+推荐生产部署使用 PostgreSQL：
```yaml
services:
@@ -91,20 +65,43 @@ volumes:
docker compose up -d
```
-### 2.4 首次登录
+首次访问 `http://localhost:3000`，默认账号为 `root` / `123456`。登录后请立即修改默认密码。
-访问 `http://localhost:3000`
+## 源码启动 Server
-默认账号：
+先构建管理端前端：
-* 用户名：`root`
-* 密码：`123456`
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+pnpm build
+```
-### 2.5 Swagger
+再启动 Server：
-登录管理端后访问：`http://localhost:3000/swagger/index.html`
+```bash
+cd openflare_server
+export SESSION_SECRET='replace-with-random-string'
+export SQLITE_PATH='./openflare.db'
+export LOG_LEVEL='info'
+# 可选：设置后优先使用 PostgreSQL。
+# 如果 PostgreSQL 为空且本地 SQLite 文件存在，启动时会自动迁移数据。
+# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
+go run .
+```
-如需在本地重新生成文档：
+默认监听 `3000` 端口。
+
+## Swagger
+
+登录管理端后访问：
+
+```text
+http://localhost:3000/swagger/index.html
+```
+
+本地重新生成 Swagger：
```bash
go install github.com/swaggo/swag/cmd/swag@v1.16.4
@@ -112,11 +109,11 @@ cd openflare_server
swag init -g main.go -o docs
```
-## 3. Agent 配置
+## Agent 接入模式
-当前支持两种接入模式。
+Agent 支持两种接入模式。
-### 3.1 使用节点专属 `agent_token`
+使用节点专属 `agent_token`：
```json
{
@@ -132,7 +129,7 @@ swag init -g main.go -o docs
}
```
-### 3.2 使用全局 `discovery_token`
+使用全局 `discovery_token`：
```json
{
@@ -150,13 +147,44 @@ swag init -g main.go -o docs
说明：
-* `agent_token` 与 `discovery_token` 至少填写一个
-* 未配置 `openresty_path` 时默认使用 Docker OpenResty
-* Agent 会暴露本机观测端口并在 server 恢复后补传最近窗口数据
+* `agent_token` 与 `discovery_token` 至少填写一个。
+* 未配置 `openresty_path` 时默认使用 Docker OpenResty。
+* Agent 会暴露本机观测端口并在 Server 恢复后补传最近窗口数据。
-## 4. 启动 Agent
+## 一键部署 Agent
-### 4.1 直接运行
+使用 `discovery_token`：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+ --server-url http://your-server:3000 \
+ --discovery-token YOUR_DISCOVERY_TOKEN
+```
+
+使用节点专属 `agent_token`：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+ --server-url http://your-server:3000 \
+ --agent-token YOUR_AGENT_TOKEN
+```
+
+支持参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--server-url` | Server 地址 |
+| `--discovery-token` | 首次自动注册 Token |
+| `--agent-token` | 节点专属 Token |
+| `--install-dir` | 安装目录 |
+| `--repo` | 下载 Agent 的仓库 |
+| `--no-service` | 不创建系统服务 |
+
+安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。
+
+## 手动启动 Agent
+
+源码运行：
```bash
cd openflare_agent
@@ -164,7 +192,7 @@ export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json
```
-### 4.2 编译后二进制运行
+编译后二进制运行：
```bash
cd openflare_agent
@@ -173,71 +201,9 @@ export LOG_LEVEL='info'
./openflare-agent -config /path/to/agent.json
```
-## 5. 最小联调步骤
+## 卸载 Agent
-1. 在管理端准备 `agent_token` 或 `discovery_token`
-2. 启动 Agent 并确认节点上线
-3. 新增一条启用中的反代规则
-4. 生成并激活新版本
-5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果
-
-预期管理端可看到：
-
-* 节点在线状态
-* 节点当前版本
-* 最近一次应用结果
-* 自动注册后的专属 `agent_token`
-
-## 6. 升级说明
-
-* Root 用户可在管理端顶栏检查并升级 Server 正式版
-* 如需尝试 preview 版本，可手动检查对应发布
-* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发
-* 也可通过上传 Server 二进制的方式执行确认升级
-
-## 7. 常用验证命令
-
-### 7.1 Server
-
-```bash
-cd openflare_server
-GOCACHE=/tmp/openflare-go-cache go test ./...
-```
-
-### 7.2 Agent
-
-```bash
-cd openflare_agent
-GOCACHE=/tmp/openflare-go-cache go test ./...
-```
-
-### 7.3 Frontend
-
-```bash
-cd openflare_server/web
-pnpm build
-```
-
-## 8. Agent 一键部署
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
- --server-url http://your-server:3000 \
- --discovery-token YOUR_DISCOVERY_TOKEN
-```
-
-支持参数：
-
-* `--server-url`
-* `--discovery-token`
-* `--agent-token`
-* `--install-dir`
-* `--repo`
-* `--no-service`
-
-安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。
-
-如需彻底卸载 Agent 并清空本地数据，可执行：
+如需彻底卸载 Agent 并清空本地数据：
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
@@ -245,14 +211,52 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
支持参数：
-* `--install-dir`
-* `--service-name`
+| 参数 | 说明 |
+| --- | --- |
+| `--install-dir` | Agent 安装目录 |
+| `--service-name` | systemd 服务名 |
卸载脚本会先停止 Agent、移除 `openflare-agent.service`、删除整个安装目录，再根据卸载前保存的 `agent.json` 判断 OpenResty 安装方式：
-* Docker 模式：删除对应容器，并尝试移除 OpenResty 镜像
-* 本机 `openresty_path` 模式：不改动本机 OpenResty，仅提示用户手动卸载
+* Docker 模式：删除对应容器，并尝试移除 OpenResty 镜像。
+* 本机 `openresty_path` 模式：不改动本机 OpenResty，仅提示用户手动卸载。
-## 9. 文档维护要求
+## 最小联调步骤
-部署方式、升级方式、接入模式或联调流程变化时，同步更新本文档和 `README.md`。
+1. 在管理端准备 `agent_token` 或 `discovery_token`。
+2. 启动 Agent 并确认节点上线。
+3. 新增一条启用中的反代规则。
+4. 生成并激活新版本。
+5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果。
+
+预期管理端可看到节点在线状态、节点当前版本、最近一次应用结果，以及自动注册后的专属 `agent_token`。
+
+## 升级说明
+
+* Root 用户可在管理端顶栏检查并升级 Server 正式版。
+* 如需尝试 preview 版本，可手动检查对应发布。
+* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发。
+* 也可通过上传 Server 二进制的方式执行确认升级。
+
+## 常用验证命令
+
+Server：
+
+```bash
+cd openflare_server
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Agent：
+
+```bash
+cd openflare_agent
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+Frontend：
+
+```bash
+cd openflare_server/web
+pnpm build
+```
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 97f8a97e..ce722b56 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -5,9 +5,10 @@
推荐阅读顺序：
1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，并完成首次登录。
-2. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。
-3. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。
-4. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。
-5. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。
+2. [部署说明](./deployment.md)：查看生产部署、Agent 一键安装、联调与升级。
+3. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。
+4. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。
+5. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。
+6. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。
如果你要参与开发，先阅读 [设计](../design/) 与 [开发约束](../design/development.md)，再进入代码修改。
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index adb448c1..4218c77e 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -1,7 +1,28 @@
# 配置项
+本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。
+
+## 配置来源
+
+Server 支持三类配置来源：
+
+1. 命令行参数。
+2. 环境变量。
+3. 数据库 `Option` 表中的运行时配置。
+
+Agent 支持：
+
+1. `-config` 命令行参数。
+2. `agent.json` 配置文件。
+3. 少量日志相关环境变量。
+
## Server 命令行参数
+```bash
+cd openflare_server
+go run . --port 3000 --log-dir ./logs
+```
+
| 参数 | 作用 | 默认值 |
| --- | --- | --- |
| `--port` | 指定 Server 监听端口 | `3000` |
@@ -24,7 +45,70 @@
| `UPLOAD_PATH` | 上传目录 | `upload` |
| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 |
-`DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN`。配置 PostgreSQL 后，Server 优先使用 PostgreSQL；当目标 PostgreSQL 为空且本地 SQLite 文件存在时，启动阶段会自动迁移 SQLite 数据。
+说明：
+
+* `DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN`。
+* `DSN` 或 `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 PostgreSQL。
+* 当目标 PostgreSQL 数据库为空且本地 `SQLITE_PATH` 文件存在时，Server 启动阶段会自动迁移 SQLite 数据，并在日志中输出按表迁移进度。
+* `SESSION_SECRET` 生产环境必须显式配置。
+* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现。
+
+## 运行时 Option
+
+以下配置由管理端设置页维护，可热更新：
+
+| 配置项 | 作用 | 默认值 |
+| --- | --- | --- |
+| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
+| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` |
+| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
+| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` |
+| `RegisterEnabled` | 是否允许新用户注册 | `false` |
+| `PasswordRegisterEnabled` | 是否允许通过密码方式注册 | `true` |
+| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` |
+| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数，至少 1 天 | `30` |
+| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` |
+| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` |
+| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` |
+| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` |
+| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` |
+
+说明：
+
+* `DatabaseAutoCleanupEnabled` 开启后，Server 会在每天凌晨 3 点自动清理 `node_access_logs`、`node_metric_snapshots`、`node_request_reports` 三类观测数据。
+* `DatabaseAutoCleanupRetentionDays` 为统一保留天数，必须大于等于 1。
+* 管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录。
+
+## OpenResty 参数
+
+OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括：
+
+* `OpenRestyWorkerProcesses`
+* `OpenRestyWorkerConnections`
+* `OpenRestyWorkerRlimitNofile`
+* `OpenRestyKeepaliveTimeout`
+* `OpenRestyProxyConnectTimeout`
+* `OpenRestyProxySendTimeout`
+* `OpenRestyProxyReadTimeout`
+* `OpenRestyProxyBufferingEnabled`
+* `OpenRestyGzipEnabled`
+* `OpenRestyCacheEnabled`
+* `OpenRestyCachePath`
+* `OpenRestyCacheMaxSize`
+
+这类参数必须以结构化方式校验、保存并参与版本渲染。
+
+约束：
+
+* 管理端不再暴露 `resolver` 配置。
+* 规则上游统一渲染为 named `upstream` 并启用 keepalive。
+* 单上游如带 base path 或 query，会在 `proxy_pass` 中补回原始 URI。
+* 多上游仍要求每个上游都为纯 `scheme://host[:port]`，且同一规则内协议一致。
+* `OpenRestyCacheEnabled` 用于启用缓存基础设施与全局默认参数；实际是否缓存、按 URL / 后缀 / 路径等命中策略由各条 `proxy_routes` 单独决定。
+* 默认缓存 Key 为 `$scheme$host$request_uri`。
+* 默认 `keepalive_timeout` 为 `20` 秒，默认 `proxy_connect_timeout` 为 `3` 秒。
+* 默认事件模型为 `epoll`，并默认开启 `multi_accept`。
+* HTTPS 监听默认使用独立 `http2 on;` 指令，避免新版 Nginx/OpenResty 对 `listen ... http2` 的弃用告警。
## 前端构建环境变量
@@ -34,31 +118,19 @@
| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` |
| `NEXT_DEV_BACKEND_URL` | 本地开发服务器代理的后端地址 | `http://127.0.0.1:3000` |
-## 运行时 Option
+## Agent 环境变量
-以下配置由管理端设置页维护，可热更新：
-
-| 配置项 | 作用 | 默认值 |
+| 环境变量 | 作用 | 默认值 |
| --- | --- | --- |
-| `AgentHeartbeatInterval` | Agent 心跳间隔，毫秒 | `10000` |
-| `NodeOfflineThreshold` | 节点离线阈值，毫秒 | `120000` |
-| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
-| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` |
-| `RegisterEnabled` | 是否允许新用户注册 | `false` |
-| `PasswordRegisterEnabled` | 是否允许通过密码方式注册 | `true` |
-| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` |
-| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数 | `30` |
-| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` |
-| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` |
-| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` |
-| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` |
-| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` |
+| `LOG_LEVEL` | Agent 日志等级 | `info` |
-OpenResty 性能参数与缓存参数也保存在 Option 表，常用项包括 `OpenRestyWorkerProcesses`、`OpenRestyWorkerConnections`、`OpenRestyProxyConnectTimeout`、`OpenRestyProxyReadTimeout`、`OpenRestyCacheEnabled`、`OpenRestyCachePath` 与 `OpenRestyCacheMaxSize`。
+## Agent 命令行参数
-## Agent 配置
+| 参数 | 作用 | 默认值 |
+| --- | --- | --- |
+| `-config` | 指定 Agent 配置文件路径 | `./agent.json` |
-Agent 支持 `-config` 命令行参数、`agent.json` 配置文件和 `LOG_LEVEL` 环境变量。
+## Agent 配置字段
| 字段 | 作用 | 是否必填 | 默认值/行为 |
| --- | --- | --- | --- |
@@ -66,7 +138,7 @@ Agent 支持 `-config` 命令行参数、`agent.json` 配置文件和 `LOG_LEVEL
| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 |
| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
| `node_name` | 节点名称 | 否 | 自动使用主机名 |
-| `node_ip` | 节点 IP | 否 | 自动探测 |
+| `node_ip` | 节点 IP | 否 | 自动探测，优先选择公网 IPv4；仅无公网地址时退回可用内网地址 |
| `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 |
| `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` |
| `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` |
@@ -76,11 +148,28 @@ Agent 支持 `-config` 命令行参数、`agent.json` 配置文件和 `LOG_LEVEL
| `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` 毫秒 |
-`heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。
+说明：
+
+* `agent_token` 与 `discovery_token` 不能同时为空。
+* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。
+* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式。
+* Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。
+
+## 维护要求
+
+以下内容变化时，必须同步更新本文档：
+
+* Server 命令行参数。
+* Server 环境变量。
+* Agent 命令行参数。
+* Agent 配置字段。
+* 任一配置项的默认值、用途或示例。