docs: 核查并润色文档，对齐项目实际实现

- 删除未经验证的环境要求（Docker 版本号、浏览器条目）与括号废话
- 故障排查改为真实处理路径（升级→重新发布→强制同步→重建 Agent→提交 issue），删除仅开发时用的排障章节
- 删除设计文档中的测试与验收、实现检查清单、贡献者阅读建议等开发内容
- 修正与代码不符的事实：reset-passwd 命令名、证书续签窗口 7 天、Pages 检查间隔 1440 分钟、Relay vhost 端口 8080、SSO 仅支持 OIDC 等
- 去除口语化表述与无意义括号，改写「不是…而是…」句式
- 同步修正文档站链接锚点，构建验证通过

docs/guide/certificates.md

@@ -12,35 +12,35 @@
 2. 点击右上角的 **「导入证书」**。
 3. 填写配置信息：
    * **证书名称**：输入一个易于识别的别名（如 `my-domain-cert`）。
-   * **证书内容 (PEM)**：复制并粘贴 PEM 格式 of 证书公钥内容（通常以 `-----BEGIN CERTIFICATE-----` 开头）。
-   * **证书私钥 (KEY)**：复制并粘贴证书的私钥内容（通常以 `-----BEGIN PRIVATE KEY-----` 或 `-----BEGIN RSA PRIVATE KEY-----` 开头）。
+   * **证书内容（PEM）**：复制并粘贴 PEM 格式的证书公钥内容（通常以 `-----BEGIN CERTIFICATE-----` 开头）。
+   * **证书私钥（KEY）**：复制并粘贴证书的私钥内容（通常以 `-----BEGIN PRIVATE KEY-----` 或 `-----BEGIN RSA PRIVATE KEY-----` 开头）。
 4. 点击 **「保存」**。导入成功后，该证书即可在配置域名时直接绑定使用。
 
 ---
 
-## 方式二：自动申请与到期自动续签 (ACME)
+## 方式二：自动申请与到期自动续签（ACME）
 
-OpenFlare 内置了 ACME 客户端并对接了 **Asynq 异步任务队列**。通过配合云解析服务商的 DNS API，系统能自动完成 DNS-01 挑战（Challenge）校验，并向 CA（默认 Let's Encrypt）申请通配符/单域名证书，并在**到期前 30 天自动触发后台秒级续签**。
+OpenFlare 内置了 ACME 客户端并对接了 **Asynq 异步任务队列**。通过配合云解析服务商的 DNS API，系统能自动完成 DNS-01 挑战（Challenge）校验，并向 CA（默认 Let's Encrypt）申请通配符/单域名证书，并在**到期前 7 天自动触发续签**。
 
 ### 第一步：在 Cloudflare 申请 DNS API Token
 
 为了使 OpenFlare 能够自动在你的域名下添加 TXT 记录以完成 DNS 校验，你需要准备一个具有特定权限的 Cloudflare API Token。
 
 > [!IMPORTANT]
-> 安全起见，**强烈建议使用限定权限的 API Token**，而非全局 API Key (Global API Key)。
+> 安全起见，**强烈建议使用限定权限的 API Token**，而非全局 API Key（Global API Key）。
 
 1. 登录 [Cloudflare 控制台](https://dash.cloudflare.com/)。
-2. 点击右上角的用户头像，选择 **「我的个人资料 (My Profile)」**。
-3. 在左侧菜单中选择 **「API 令牌 (API Tokens)」**，然后点击 **「创建令牌 (Create Token)」**。
-4. 找到 **「编辑区域 DNS (Edit Zone DNS)」** 模板，点击 **「使用模板 (Use template)」**。
+2. 点击右上角的用户头像，选择 **「我的个人资料（My Profile）」**。
+3. 在左侧菜单中选择 **「API 令牌（API Tokens）」**，然后点击 **「创建令牌（Create Token）」**。
+4. 找到 **「编辑区域 DNS（Edit Zone DNS）」** 模板，点击 **「使用模板（Use template）」**。
 5. 配置令牌权限与范围（保持默认或根据实际情况限定）：
-   * **权限 (Permissions)**：
-     * `区域 (Zone)` - `DNS` - `编辑 (Edit)` (必须，ACME 写入 TXT 记录用)
-     * `区域 (Zone)` - `区域 (Zone)` - `读取 (Read)` (必须，用于列出和检索区域 ID)
-   * **区域资源 (Zone Resources)**：
-     * 选择 **「包括 (Include)」** -> **「所有区域 (All zones)」**，或者选择 **「特定区域 (Specific zone)」** 并指向你托管的特定域名。
-6. 点击 **「继续以转到摘要 (Continue to summary)」**，确认无误后点击 **「创建令牌 (Create Token)」**。
-7. 复制生成的 **API 令牌 (Token)** 字符串。*注意：该令牌仅展示一次，请妥善保存*。
+   * **权限（Permissions）**：
+     * `区域（Zone）` - `DNS` - `编辑（Edit）`（必须，ACME 写入 TXT 记录用）
+     * `区域（Zone）` - `区域（Zone）` - `读取（Read）`（必须，用于列出和检索区域 ID）
+   * **区域资源（Zone Resources）**：
+     * 选择 **「包括（Include）」** -> **「所有区域（All zones）」**，或者选择 **「特定区域（Specific zone）」** 并指向你托管的特定域名。
+6. 点击 **「继续以转到摘要（Continue to summary）」**，确认无误后点击 **「创建令牌（Create Token）」**。
+7. 复制生成的 **API 令牌（Token）** 字符串。该令牌仅展示一次，请妥善保存。
 
 ### 第二步：在控制端添加 DNS 账号
 
@@ -49,7 +49,7 @@ OpenFlare 内置了 ACME 客户端并对接了 **Asynq 异步任务队列**。
 3. 填写配置信息：
    * **账号名称**：如 `cloudflare-main`。
    * **DNS 服务商**：选择 `Cloudflare`。
-   * **API Token**：填入刚刚在 Cloudflare 复制的 API 令牌（该值在入库时会自动加密存储，保障安全）。
+   * **API Token**：填入刚刚在 Cloudflare 复制的 API 令牌（该值在入库时会自动加密存储）。
 4. 点击 **「保存」**。
 
 ### 第三步：提交证书申请任务
@@ -65,4 +65,4 @@ OpenFlare 内置了 ACME 客户端并对接了 **Asynq 异步任务队列**。
 ### 第四步：查看申请进度与续期状态
 
 - **查看实时进度**：保存后，系统会向 Asynq 队列投递单证书续期/申请任务（`of_ssl_single_renew`）。你可以进入管理后台的任务或节点日志页面，实时查看每一步（添加 TXT 记录、DNS 记录全球生效探测、ACME 验证、证书颁发落地等）的详细日志。
-- **自动续期**：所有通过 ACME 申请的证书都会被系统自动托管。后台的 Scheduler 每日会自动扫描证书有效期，在到期前 30 天自动通过异步任务触发续签，无需任何手动维护。
+- **自动续期**：所有通过 ACME 申请的证书都会被系统自动托管。后台的 Scheduler 每日会自动扫描证书有效期，在到期前 7 天自动通过异步任务触发续签，无需任何手动维护。

docs/guide/credits.md

@@ -1,6 +1,6 @@
 # 引用与致谢
 
-OpenFlare 本质上是一个方案整合项目, 在设计与实现过程中借鉴了众多开源项目的优秀理念、架构设计和技术实现。以下是 OpenFlare 在核心底层引擎、安全防护机制以及前后端系统框架等方面所引用的关键开源项目，以及对这些项目及其社区的感谢。
+OpenFlare 在设计与实现过程中借鉴了众多开源项目的优秀理念、架构设计和技术实现。以下是 OpenFlare 在核心底层引擎、安全防护机制以及前后端系统框架等方面所引用的关键开源项目，在此对这些项目及其社区表示感谢。
 
 ---
 
@@ -9,14 +9,14 @@ OpenFlare 本质上是一个方案整合项目, 在设计与实现过程中借
 *   **在 OpenFlare 中的作用**：作为全局数据面（Data Plane）的边缘网关。所有的公网 Web 流量均首先由 OpenResty 接收，在此处进行高并发的 HTTPS 握手、WAF 安全规则比对、防 CC 人机验证，并最终执行反向代理转发。
 *   **项目链接**：[OpenResty 官网](https://openresty.org/)
 
-### 2. FRP (Fast Reverse Proxy)
+### 2. FRP（Fast Reverse Proxy）
 *   **项目定位**：高性能的反向代理应用，专注于内网穿透。
 *   **在 OpenFlare 中的作用**：作为内网穿透子系统的底层隧道引擎。中继端管理器 `openflare-relay` 负责守护和调度 `frps` 引擎，而内网客户端 `openflared` 则负责在本地自动生成 TOML 配置并守护多路复用 `frpc` 子进程。
 *   **项目链接**：[fatedier/frp (GitHub)](https://github.com/fatedier/frp)
 
 ---
 
-### 3. Anubis (PoW 方案)
+### 3. Anubis（PoW 方案）
 *   **项目定位**：基于工作量证明（Proof of Work）的轻量级人机验证防护方案。
 *   **在 OpenFlare 中的作用**：为网关 WAF 提供了核心的**无感防 CC 人机挑战**能力。
 

docs/guide/first-site.md

@@ -23,15 +23,15 @@ OpenFlare 的发布链路以“不可变配置版本”为核心。你在管理
 
 为了快速验证，我们首先部署一个最基础的 HTTP 反代站点：
 
-1. 登录控制面板，进入左侧导航 **「网站管理」->「域名列表」**，点击 **「新增网站」**。
+1. 登录控制面板，进入左侧导航 **「网站管理」->「域名列表」**，点击 **「新增 Zone」**。
 2. 填写域名配置：
    * **域名**：输入用于测试的域名（如 `first.example.com`）。
    * **绑定证书**：选择不绑定证书（作为 HTTP 快速验证）。
-   * 点击保存，完成网站登记。
-3. 进入左侧导航 **「规则管理」**，点击 **「新增规则」**：
+   * 点击保存，完成域名登记。
+3. 进入左侧导航 **「规则管理」**，点击 **「新建规则」**：
    * **规则名称**：输入简易标识（如 `first-app-route`）。
    * **域名匹配**：填入你的测试域名（如 `first.example.com`）。
-   * 在下方 **「反向代理」** 选项卡中，配置 **源站类型** 为「标准反代」 (Direct)。
+   * 在下方 **「反向代理」** 选项卡中，配置 **回源方式** 为「直连上游」。
    * **上游地址**：填写后端服务地址（如测试专用的 `http://httpbin.org`）。
    * 点击保存创建规则。
 
@@ -45,8 +45,8 @@ OpenFlare 的发布链路以“不可变配置版本”为核心。你在管理
 
 新增的网站配置仍保存在 Server 的数据库中，处于草稿状态，需要通过发布版本分发到数据面：
 
-1. 点击控制面板右上角的 **「配置预览」** 按钮，系统会展示本次新增路由的物理配置文件 Diff 差异。
-2. 确认渲染出的配置内容正确无误后，点击 **「发布并激活」**。
+1. 点击控制面板右上角的 **「预览并发布」** 按钮，系统会展示本次新增路由的物理配置文件 Diff 差异。
+2. 确认渲染出的配置内容正确无误后，点击 **「确认发布」**。
 3. 控制面将生成一个唯一的配置版本号（格式为 `YYYYMMDD-NNN`）。
 
 ---

docs/guide/index.md

@@ -1,6 +1,6 @@
 # 指南
 
-你会学到：OpenFlare 文档如何组织、首次运行应该读哪些页面，以及部署、使用、排查和开发分别从哪里开始。
+你会学到：OpenFlare 文档如何组织、首次运行应该读哪些页面，以及部署、使用、排查分别从哪里开始。
 
 OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站配置、配置版本发布、Agent 节点同步、TLS 证书和基础观测放到一个管理端中，适合单团队或单组织管理多台代理节点。
 
@@ -17,8 +17,8 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
 7. [WAF 安全防护使用](./waf-usage.md)：配置 WAF 规则组，掌握 IP 黑白名单、自动/订阅 IP 组、地域限制与 PoW CC 防护。
 8. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
 9. [Uptime Kuma 监控同步](./uptime-kuma.md)：配置并使用 Uptime Kuma 自动差分同步和监控范围控制。
-10. [SSO 登录配置](./sso.md)：配置 GitHub 或 OIDC 实现第三方单点登录 (SSO) 接入。
-11. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty、边缘缓存命中与前端构建问题。
+10. [SSO 登录配置](./sso.md)：配置 OIDC 实现第三方单点登录（SSO）接入。
+11. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 与边缘缓存命中问题。
 12. [引用与致谢](./credits.md)：查看系统依赖的优秀开源项目与社区致谢清单。
 
 ## 按角色查找
@@ -36,7 +36,7 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
 | 自动同步监测站点状态 | [Uptime Kuma 监控同步](./uptime-kuma.md) |
 | 接入或重装节点 Agent | [接入 Agent](../deployment/agent.md) |
 | 从源码启动 Server | [启动 Server](../deployment/server.md) |
-| 配置 GitHub 或 OIDC 登录 | [SSO 登录配置](./sso.md) |
+| 配置 OIDC 登录 | [SSO 登录配置](./sso.md) |
 | 升级 Server 或 Agent | [升级与维护](../deployment/upgrade.md) |
 | 理解架构和发布模型 | [系统架构](../design/architecture.md) 与 [Agent 与发布模型](../design/agent-design.md) |
 | 查看开源引用与致谢 | [引用与致谢](./credits.md) |

docs/guide/pages-usage.md

@@ -59,12 +59,12 @@ GitHub 来源仅支持公开 `github.com` 仓库。填写：
 
 两种选择都可手动 **「检查更新」** 和 **「同步并发布」**。区别如下：
 
-* **latest**：可设置 5～1440 分钟检查间隔，默认 60 分钟；自动更新默认关闭。开启后，scanner 发现新 revision 才会异步同步并发布。
+* **latest**：可设置 5～1440 分钟检查间隔，默认 1440 分钟（24 小时）；自动更新默认关闭。开启后，scanner 发现新 revision 才会异步同步并发布。
 * **tag**：只支持管理员手动检查和同步，不参与定时 scanner。
 
 “检查更新”只解析 Release/asset 并更新版本游标，不下载部署包；“同步并发布”才会下载、校验、创建或复用 deployment 并激活。如果同一个 Release 下的 asset 被替换，来源会进入 **「需要确认」**，必须确认页面显示的精确 revision 后才能发布，避免静默覆盖。
 
-GitHub Release 在这里是预构建产物源，不等同于连接代码仓库自动构建。未来仓库集成会使用独立的 `git_repository` 来源和 Server build executor，再把构建产物送入同一部署管线。
+GitHub Release 来源只导入预构建产物，不执行仓库源码构建。
 
 ### 4. 切换或删除来源
 

docs/guide/proxy-config.md

@@ -9,7 +9,7 @@
 在网关控制面中，建议遵循以下步骤新增反代规则：
 
 ```text
-  [ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义 (可选) ] ──► [ 步骤 3. 新增网站配置 ]
+  [ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义（可选） ] ──► [ 步骤 3. 新增网站配置 ]
                                                                    │
   [ 步骤 5. 验证访问 ] ◄── [ 步骤 4. 发布与激活版本 ] ◄───────────────┘
 ```
@@ -28,7 +28,7 @@
 
 源站（Origin）代表被代理的后端真实服务地址。虽然在新建网站时可以直接填写 IP，但推荐先在源站库中进行注册，以便后续复用与维护：
 
-1. 进入左侧导航 **「网站管理」->「源站地址」**，点击 **「创建源站」**。
+1. 进入左侧导航 **「网站管理」->「源站地址」**，点击 **「新增源站」**。
 2. 填写源站名称（如 `production-api`）。
 3. 填入合法的上游地址（如 `http://10.0.0.10:8080`），点击保存。
 
@@ -38,13 +38,13 @@
 
 证书和源站就绪后，即可创建核心网站代理路由：
 
-1. 进入左侧导航 **「网站管理」->「域名列表」**，点击 **「新增网站」**：
+1. 进入左侧导航 **「网站管理」->「域名列表」**，点击 **「新增 Zone」**：
    * **域名**：输入该站点绑定的域名。
    * **绑定证书**：选择第一步准备或申请好的证书。
-2. 配置请求路由规则：进入 **「规则管理」** 页面，点击 **「新增规则」** 或编辑已有规则：
+2. 配置请求路由规则：进入 **「规则管理」** 页面，点击 **「新建规则」** 或编辑已有规则：
    * **规则名称**：输入规则的唯一简易标识（如 `app-portal-route`）。
    * **域名匹配**：填入对应的域名（支持通配符或精确域名，需与上面登记的域名一致）。
-   * 在下方 **「反向代理」** 选项卡下，选择源站类型为 **「标准反代」**。
+   * 在下方 **「反向代理」** 选项卡下，选择 **回源方式** 为「直连上游」。
    * **源站选择**：从下拉框中选择第二步创建的源站；或者选择手动输入并填入 `http://10.0.0.20:9000`。
 3. 点击保存创建配置。
 
@@ -54,13 +54,13 @@
 
 你在管理端新增的网站配置仅保存在 Server 数据库中，**不会立即生效**。必须生成配置版本快照并分发到 Agent 边缘节点：
 
-1. 点击控制面板右上角的 **「配置预览」** 按钮。
+1. 点击控制面板右上角的 **「预览并发布」** 按钮。
 2. 检查配置文件的 Diff 差异，确认你刚刚新增的 `server` 块以及证书绑定规则无误。
-3. 点击 **「发布并激活」** 按钮。
+3. 点击 **「确认发布」** 按钮。
 4. **Agent 落地机制**：
    * 数据面的 Agent 节点在心跳中发现激活的版本 Checksum 变更，会自动拉取完整的 OpenResty 配置文件和证书包到本地。
    * 自动在本地执行配置校验（类似于 `openresty -t`），确认无语法错误后，执行平滑重载（`reload`）。
-   * *如果重载或校验失败，Agent 会安全阻断并回滚至上一稳定版本，保证节点高可用。*
+   * 如果重载或校验失败，Agent 会安全阻断并回滚至上一稳定版本，保证节点高可用。
 
 ---
 
@@ -80,9 +80,9 @@
 
 ### 2. 一键秒级回滚
 如果发布的新配置导致了线上业务异常：
-1. 导航至左侧 **「配置版本」** 菜单。
+1. 导航至左侧 **「版本发布」** 菜单。
 2. 在历史列表中找到发布前的上一个稳定版本。
-3. 点击 **「激活此版本」**。
+3. 点击 **「激活」**。
 4. 所有在线 Agent 节点将在秒级自动重载回历史配置，实现秒级避险。
 
 ---

docs/guide/quick-start.md

@@ -19,16 +19,12 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点
 | Docker / Docker Compose | 用于启动 Server 及其依赖的 PostgreSQL、Valkey；如采用 Docker Agent，也用于运行 Agent |
 | OpenResty | 本地安装 Agent 时需要可执行 `openresty`，或在安装脚本中指定路径                        |
 | 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址                       |
-| 浏览器 | 用于访问管理端                                                          |
-
-- **Docker**：`20.10.0+`
-- **Docker Compose**：`2.0.0+`
 
 ---
 
 ## 1. 启动 Server
 
-快速开始推荐采用 **PostgreSQL + Redis ** 标准部署方案。
+快速开始推荐采用 **PostgreSQL + Valkey** 标准部署方案。
 
 在空目录中创建 `docker-compose.yaml`：
 
@@ -123,12 +119,14 @@ http://localhost:3000
 > [!WARNING]
 > 为了你的系统安全，首次登录后请立即修改默认密码。
 
-如果忘记密码并且没有配置找回密码渠道, 可以使用命令进行重置
+如果忘记密码并且没有配置找回密码渠道，可以使用命令重置：
 
 ```bash
-go run main.go reset-paswd     # 重置管理员密码
+go run main.go reset-passwd --user admin
 ```
 
+未指定 `--password` 时命令会自动生成随机密码并输出到终端；也可以使用 `--password` 显式指定新密码。
+
 ---
 
 ## 2. 准备 Agent Token
@@ -142,14 +140,14 @@ Agent 可以用两类凭证接入：
 
 在管理端准备其中一种凭证后，进入下一步。
 
-- **`discovery_token`** 获取菜单路径：「系统设置」 (Settings) -> 「OpenFlare」选项卡 -> 「自动注册」凭证
+- **`discovery_token`** 获取菜单路径：「系统设置」->「OpenFlare」选项卡 ->「Discovery Token 与部署」中的 Discovery Token
 - **`agent_token`** 获取菜单路径：在「节点管理」中创建节点后，点击进入节点详情页即可查看到对应的专属 Token。
 
 ---
 
 ## 3. 安装/运行 Agent
 
-Agent 部署方式推荐使用 Docker 部署（即直接运行内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本将 Agent 部署在本地宿主机上。
+推荐使用 Docker 镜像部署 Agent；也可以通过安装脚本部署到本地宿主机。
 
 ### 方式 A：Docker 运行 Agent（推荐）
 
@@ -217,17 +215,17 @@ journalctl -u openflare-agent -f
 
 ---
 
-## 常见失败原因
+## 遇到问题时
 
-| 现象 | 排查方向 |
-| --- | --- |
-| 浏览器打不开管理端 | 确认 `docker compose ps` 中 Server 正在运行，宿主机 `3000` 端口没有被占用 |
-| 登录后数据无法保存/提示报错 | 检查 PostgreSQL 容器健康状态，以及 `DB_PASSWORD` / 密码等连接参数是否一致 |
-| Agent 无法注册 | 确认 Agent 节点能访问 `--server-url`，并检查 Token 是否填错或已失效 |
-| Agent 在线但没有应用配置 | 确认网站配置已启用，并且已经发布并激活版本 |
-| OpenResty 应用失败 | 查看节点应用记录和 `journalctl -u openflare-agent`，重点检查域名、证书、上游地址和端口占用 |
+按以下顺序处理：
 
-更多排查路径见 [故障排查](./troubleshooting.md)。
+1. 将 Server 与 Agent 升级到最新版本，确认问题是否仍然存在。
+2. 重新发布并激活配置版本，等待节点应用。
+3. 在节点详情页对目标节点执行「强制同步」，推动节点立即拉取最新配置。
+4. 重建或重装 Agent（重新执行安装脚本）。
+5. 上述步骤均无效时，携带 Server 日志与节点应用记录提交 [GitHub Issue](https://github.com/Rain-kl/OpenFlare/issues)。
+
+更多排查思路见 [故障排查](./troubleshooting.md)。
 
 ---
 

docs/guide/sso.md

@@ -1,72 +1,51 @@
 # SSO 登录配置
 
-你会学到：如何为 OpenFlare 配置 GitHub OAuth 或标准 OIDC 登录入口，如何填写回调地址，以及第三方账号如何绑定本地用户。
+你会学到：如何为 OpenFlare 配置 OIDC 第三方登录入口、填写回调地址，以及第三方账号如何绑定本地用户。
 
-OpenFlare 支持通过认证源配置第三方登录入口。当前支持 GitHub OAuth 与标准 OIDC Provider，例如 Logto、authentik、Keycloak、Casdoor 等。
+OpenFlare 通过 OIDC 认证源接入第三方登录。任意提供标准 OIDC Discovery 的服务（如 Google、Keycloak、authentik、Logto、Casdoor 等）都可以接入。
 
 认证源配置完成并启用后，会显示在登录页的第三方账号登录区域。用户可以通过第三方账号登录，也可以在已登录状态下把第三方账号绑定到当前本地账号。
 
 ## 使用前准备
 
-你需要先准备：
-
 | 项目 | 说明 |
 | --- | --- |
-| OpenFlare 访问地址 | 用户浏览器实际访问的地址，例如 `https://openflare.example.com` |
-| 认证源名称 | OpenFlare 内部唯一标识，例如 `github`、`company-oidc` |
+| 服务器访问地址 | 在管理端「系统设置」->「系统设置」选项卡 ->「通用设置」中配置，须与用户浏览器实际访问的地址一致（协议、域名、端口） |
+| 认证源名称 | OpenFlare 内部唯一标识，例如 `company-oidc` |
 | Client ID | 第三方平台创建应用后提供 |
 | Client Secret | 第三方平台创建应用后提供 |
-| OIDC Discovery URL | 仅 OIDC 需要，例如 `https://idp.example.com/.well-known/openid-configuration` |
+| OIDC Discovery URL | 例如 `https://idp.example.com/.well-known/openid-configuration` |
 
-**确认系统设置->通用设置->服务器地址能正确和域名匹配**
-
-认证源名称只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。认证源名称会出现在回调地址中，保存后如需修改名称，也必须同步修改第三方平台中的回调地址。
+认证源名称只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。
 
 ## 回调地址
 
-第三方平台中的 Redirect URI / Callback URL 填写格式为：
+第三方平台中的 Redirect URI / Callback URL 固定填写：
 
 ```text
-<OpenFlare 访问地址>/oauth/<认证源名称>
+<服务器访问地址>/login
 ```
 
-示例：
+例如服务器访问地址为 `https://openflare.example.com` 时：
 
 ```text
-https://openflare.example.com/oauth/github
-https://openflare.example.com/oauth/company-oidc
+https://openflare.example.com/login
 ```
 
-在管理端新增或修改认证源时，表单会根据当前浏览器访问地址和你输入的认证源名称自动显示应填写的回调地址。
-
-## 配置 GitHub 登录
-
-1. 在 GitHub 创建 OAuth App。
-2. `Homepage URL` 填写 OpenFlare 访问地址。
-3. `Authorization callback URL` 填写 OpenFlare 显示的回调地址，例如 `https://openflare.example.com/oauth/github`。
-4. 复制 GitHub 提供的 Client ID 和 Client Secret。
-5. 登录 OpenFlare 管理端，进入左侧导航 **「系统设置」** (Settings)，选择 **「安全设置」** 选项卡，在 **「认证源管理」** 栏目中进行配置。
-6. 新增认证源，类型选择 `GitHub`。
-7. 填写认证源名称、展示名称、Client ID、Client Secret。
-8. Scope 默认使用 `user:email`，通常无需修改。
-9. 保存并启用认证源。
-
-启用后，登录页会显示对应的 GitHub 登录按钮。
+回调地址只与「服务器访问地址」相关，不包含认证源名称。第三方平台授权完成后会跳转到该地址，OpenFlare 登录页携带授权码完成登录或绑定。
 
 ## 配置 OIDC 登录
 
-1. 在 OIDC Provider 中创建应用或客户端。
-2. 应用类型选择 Web / Confidential Client。
-3. Redirect URI / Callback URL 填写 OpenFlare 显示的回调地址，例如 `https://openflare.example.com/oauth/company-oidc`。
-4. 复制 Client ID 和 Client Secret。
-5. 获取 Provider 的 Discovery URL，通常以 `/.well-known/openid-configuration` 结尾。
-6. 登录 OpenFlare 管理端，进入左侧导航 **「系统设置」** (Settings)，选择 **「安全设置」** 选项卡，在 **「认证源管理」** 栏目中进行配置。
-7. 新增认证源，类型选择 `OIDC`。
-8. 填写认证源名称、展示名称、Client ID、Client Secret、OIDC Discovery URL。
-9. Scope 默认使用 `openid profile email`。如果 Provider 限制了 scope，请按 Provider 允许的值调整。
-10. 保存并启用认证源。
+1. 在 OIDC Provider 中创建应用或客户端，应用类型选择 Web / Confidential Client。
+2. Redirect URI / Callback URL 填写 `<服务器访问地址>/login`。
+3. 复制 Client ID 和 Client Secret。
+4. 获取 Provider 的 Discovery URL，通常以 `/.well-known/openid-configuration` 结尾。
+5. 登录 OpenFlare 管理端，进入左侧导航 **「系统设置」**，选择 **「安全设置」** 选项卡，在 **「认证源管理」** 栏目中新增认证源。
+6. 类型选择 `OIDC`，填写认证源名称、展示名称、Client ID、Client Secret、OIDC Discovery URL。
+7. Scope 默认使用 `openid profile email`。如果 Provider 限制了 scope，请按 Provider 允许的值调整。
+8. 保存并启用认证源。
 
-启用后，登录页会显示对应的 OIDC 登录按钮。
+启用后，登录页会显示对应的第三方登录按钮。
 
 ## 登录与绑定行为
 
@@ -85,17 +64,17 @@ https://openflare.example.com/oauth/company-oidc
 
 修改认证源时，Client Secret 输入框留空表示保留已有密钥；填写新值则会覆盖保存。
 
-如果修改了认证源名称，回调地址也会随之变化。你必须到第三方平台同步修改 Redirect URI / Callback URL，否则第三方平台会拒绝回调或返回错误。
+修改认证源名称不会影响回调地址，无需同步修改第三方平台配置。
 
 ## 常见问题
 
 ### 返回 `invalid_scope`
 
-说明第三方平台不允许当前配置的 Scope。OIDC 默认 Scope 是 `openid profile email`，GitHub 默认 Scope 是 `user:email`。请到认证源编辑页调整 Scope，或在第三方平台放行对应 Scope。
+说明第三方平台不允许当前配置的 Scope。OIDC 默认 Scope 是 `openid profile email`。请到认证源编辑页调整 Scope，或在第三方平台放行对应 Scope。
 
 ### 提示回调地址不匹配
 
-检查第三方平台中配置的 Redirect URI / Callback URL 是否与 OpenFlare 表单提示完全一致。协议、域名、端口和路径都必须一致。
+检查第三方平台中配置的 Redirect URI / Callback URL 是否与 `<服务器访问地址>/login` 完全一致。协议、域名、端口和路径都必须一致。
 
 ### 登录页没有显示第三方登录按钮
 

docs/guide/troubleshooting.md

@@ -1,6 +1,6 @@
 # 故障排查
 
-你会学到：如何按症状排查 OpenFlare Server、数据库、登录、Agent、OpenResty、配置发布和前端构建问题。
+你会学到：如何按症状排查 OpenFlare Server、数据库、登录、Agent、OpenResty 和配置发布问题。
 
 排查时先确认问题发生在哪一层：浏览器、Server、数据库、Agent、OpenResty、源站或 DNS。OpenFlare 的配置不会直接在线写入所有节点，只有激活版本变化后，Agent 才会在 heartbeat 中发现并应用。
 
@@ -9,7 +9,7 @@
 | 现象 | 先看哪里 |
 | --- | --- |
 | 管理端打不开 | Server 容器或进程日志、端口监听 |
-| 登录异常 | 默认账号、OPENFLARE_TOKEN、浏览器请求、Server 日志 |
+| 登录异常 | 默认账号、Session Cookie、Server 日志 |
 | 数据无法保存 | 数据库连接、SQLite 文件权限、PostgreSQL 健康状态 |
 | Agent 离线 | Agent 日志、Token、Server 地址、网络连通性 |
 | 发布后节点未更新 | 激活版本、节点 heartbeat、应用记录 |
@@ -50,7 +50,7 @@ ls -ld "$(dirname /path/to/openflare.db)"
 
 | 日志或现象 | 处理 |
 | --- | --- |
-| 数据库连接失败 | 检查 `DSN` 中用户名、密码、主机、端口、库名和 `sslmode` |
+| 数据库连接失败 | 检查 `DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD`、`DB_NAME`、`DB_SSL_MODE` 是否一致 |
 | SQLite 无法创建文件 | 检查 `SQLITE_PATH` 所在目录是否存在且可写 |
 | 端口被占用 | 修改 `PORT` 或 `--port`，或停止占用端口的进程 |
 
@@ -62,21 +62,7 @@ ls -ld "$(dirname /path/to/openflare.db)"
 curl -I http://127.0.0.1:3000
 ```
 
-2. 如果是源码运行，确认已经构建前端静态产物：
-
-```bash
-cd frontend
-pnpm build
-```
-
-3. 检查浏览器访问地址是否与反向代理配置一致。
-
-4. 如果通过前端开发服务器访问，确认后端代理地址：
-
-```bash
-cd frontend
-NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
-```
+2. 检查浏览器访问地址是否与反向代理配置一致。
 
 ## 默认账号无法登录
 
@@ -84,32 +70,20 @@ NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
 
 排查步骤：
 
-1. 确认连接的是预期数据库，避免 `SQLITE_PATH` 或 `DSN` 指向了另一个环境。
+1. 确认连接的是预期数据库，避免 `SQLITE_PATH` 或 `DB_HOST` / `DB_NAME` 指向了另一个环境。
 2. 查看 Server 日志中使用的是 `sqlite` 还是 `postgres`。
 3. 在浏览器开发者工具中确认管理端 API 请求已正确携带 Session Cookie。
 4. 清理浏览器缓存及 Cookie 后重新登录。
 
 ### 应急重置管理员密码
 
-如果忘记了 `admin` 账户的密码，可以通过直接更新数据库中的密码哈希值将其重置为 `12345678`（登录后请务必立即修改）：
+忘记 `admin` 账户密码时，使用 `reset-passwd` 命令重置（支持 SQLite 与 PostgreSQL）：
 
-#### 1. 若使用 SQLite 数据库
-停止 Server 运行，使用 sqlite3 客户端打开数据库文件：
 ```bash
-sqlite3 /path/to/openflare.db
+go run main.go reset-passwd --user admin --password your-new-password
 ```
-执行以下 SQL 语句：
-```sql
-UPDATE users SET password = '$2a$10$eXpE9i/6S3gPT94/G0mu0.B8ser66ARETFz5NWYSYcrQ4JmtSrMXu' WHERE username = 'admin';
-```
-输入 `.exit` 退出并重新启动 Server。
 
-#### 2. 若使用 PostgreSQL 数据库
-通过您的数据库连接工具（如 psql、pgAdmin 或 DBeaver）连接到 PostgreSQL 实例，选择对应的 `openflare` 数据库，执行以下 SQL 语句：
-```sql
-UPDATE users SET password = '$2a$10$eXpE9i/6S3gPT94/G0mu0.B8ser66ARETFz5NWYSYcrQ4JmtSrMXu' WHERE username = 'admin';
-```
-执行成功后即可使用默认密码 `12345678` 重新登录管理后台。
+若使用 SQLite，建议先停止 Server 进程再执行，避免数据库文件锁冲突。未指定 `--password` 时命令会生成随机密码并输出到终端。重置成功后请立即登录并修改密码。
 
 ## Agent 无法注册或一直离线
 
@@ -216,29 +190,6 @@ curl -Iv https://your-domain
 4. 检查 `openresty_observability_port` 是否被占用，默认是 `18081`。
 5. 确认 Server 侧没有因数据库清理策略删除对应时间窗口数据。
 
-## 前端构建失败
-
-执行：
-
-```bash
-cd frontend
-corepack enable
-pnpm install
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm build
-```
-
-常见原因：
-
-| 现象 | 处理 |
-| --- | --- |
-| pnpm 版本不一致 | 使用 `corepack enable` 后重新安装 |
-| 类型错误 | 先运行 `pnpm typecheck` 定位具体文件 |
-| API 类型不一致 | 检查 `lib/api/` 和 `types/` 中的响应结构 |
-| E2E 失败 | 确认 Server 和前端开发服务器都已启动 |
-
 ## 边缘缓存命中率异常
 
 访问日志中缓存三态：**命中**（HIT/STALE/REVALIDATED/UPDATING）、**回源**（MISS/EXPIRED）、**未缓存**（BYPASS 或空，请求时未进入可缓存路径或响应未入库）。设计说明见 [边缘缓存策略设计](../design/edge-cache-design.md)。
@@ -269,12 +220,3 @@ pnpm build
 * 响应带 `Set-Cookie` 或 `private`：**不入库**。  
 * 无源站缓存头的可缓存状态码：使用默认 Edge TTL（如 200 约 120 分钟）。
 
-## 文档站构建失败
-
-```bash
-cd docs
-pnpm install
-pnpm build
-```
-
-如果是链接错误，检查新增页面是否已经加入 `docs/config.ts` 侧边栏，或者相对链接是否指向存在的 Markdown 文件。

docs/guide/tunnel-usage.md

@@ -2,9 +2,9 @@
 
 你会学到：OpenFlare 内网穿透隧道的设计原理、核心概念（中继节点与隧道客户端），以及如何从零开始将内网开发环境或私有云服务一步步安全、稳定地发布到公网域名上。
 
-在许多实际开发和运维场景中，我们的源站服务部署在局域网、本地开发机或防范严密的私有 VPC 内部，没有公网 IP，亦无法在边界防火墙或路由器上配置端口映射。
+在许多实际开发和运维场景中，源站服务部署在局域网、本地开发机或私有 VPC 内部，没有公网 IP，也无法在边界防火墙或路由器上配置端口映射。
 
-OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你只需在内网环境发起向公网中继节点的出向安全连接，无需配置任何入方向端口，即可将公网的 Web 访问流量平滑引入内网源站，同时享有网关提供的 TLS 证书自动托管与 WAF 安全防护。
+OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你只需在内网环境发起向公网中继节点的出向安全连接，无需配置任何入方向端口，即可将公网的 Web 访问流量引入内网源站，同时享有网关提供的 TLS 证书自动托管与 WAF 安全防护。
 
 ---
 
@@ -12,10 +12,12 @@ OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你
 
 在使用内网穿透功能前，你需要熟悉以下组件与核心概念：
 
-| **中继节点 (Relay)** | 部署在公网边缘的流量中继服务，负责监听内网客户端的长连接，并作为网关 Agent (OpenResty) 与内网流量的中转桥梁。 | 运行 `openflare-relay` 守护的 `tunnel_relay` 节点 |
-| **穿透隧道 (Tunnel)** | 逻辑上的穿透客户端实例，拥有全局唯一 ID 与安全认证令牌，用以标识一个具体的内网环境。 | 在「节点管理」中创建的 `tunnel_client` 节点，分配专属 Tunnel Token |
-| **隧道客户端 (Client)** | 运行在内网环境下的轻量控制器，根据 Server 下发的配置自动管理底层的 frpc 隧道子进程。 | 内网部署的 `openflared` 容器或独立二进制进程 |
-| **隧道上游 (Tunnel Upstream)** | 路由规则中的特殊反代类型。选择此类型后，网关会将公网流量转发至本地中继端的 Vhost 端口，最终送达内网源站。 | 在「规则管理」详情页中配置的反向代理类型，选择源站类型为「内网穿透」并绑定对应 Tunnel 节点 |
+| 组件 | 说明 | 对应实体 |
+| --- | --- | --- |
+| **中继节点（Relay）** | 部署在公网边缘的流量中继服务，负责监听内网客户端的长连接，并作为网关 Agent（OpenResty）与内网流量的中转桥梁 | 运行 `openflare-relay` 守护的 `tunnel_relay` 节点 |
+| **穿透隧道（Tunnel）** | 逻辑上的穿透客户端实例，拥有全局唯一 ID 与安全认证令牌，用以标识一个具体的内网环境 | 在「节点管理」中创建的 `tunnel_client` 节点，分配专属 Tunnel Token |
+| **隧道客户端（Client）** | 运行在内网环境下的轻量控制器，根据 Server 下发的配置自动管理底层的 frpc 隧道子进程 | 内网部署的 `openflared` 容器或独立二进制进程 |
+| **隧道上游（Tunnel Upstream）** | 路由规则中的特殊反代类型。选择此类型后，网关会将公网流量转发至本地中继端的 Vhost 端口，最终送达内网源站 | 在「规则管理」详情页中配置的反向代理类型，选择回源方式为「内网穿透（Tunnel）」并绑定对应 Tunnel 节点 |
 
 ---
 
@@ -23,11 +25,11 @@ OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你
 
 将一个内网服务发布到公网，推荐按这个顺序进行：
 
-1. 注册并部署至少一个公网 **中继节点 (Relay)** 并保持在线。
-2. 进入 **「节点管理」**，新建一个类型为 **Tunnel 节点 (tunnel_client)** 的节点，获取专属 Token。
-3. 在内网服务器中部署并启动 **隧道客户端 (OpenFlared)**。
+1. 注册并部署至少一个公网 **中继节点（Relay）** 并保持在线。
+2. 进入 **「节点管理」**，新建一个类型为 **Tunnel 节点（tunnel_client）** 的节点，获取专属 Token。
+3. 在内网服务器中部署并启动 **隧道客户端（OpenFlared）**。
 4. 确认管理端中该 Tunnel 节点的状态显示为「在线」。
-5. 在 **「规则管理」** 页面新增或编辑规则，在「反向代理」选项卡中选择源站类型为 **「内网穿透」**，绑定对应 Tunnel 节点并填写内网服务端口（如 `127.0.0.1:8080`）。
+5. 在 **「规则管理」** 页面新增或编辑规则，在「反向代理」选项卡中选择回源方式为 **「内网穿透（Tunnel）」**，绑定对应 Tunnel 节点并填写内网服务端口（如 `127.0.0.1:8080`）。
 6. 发布并激活新版本。
 7. 通过公网域名访问，验证内网穿透链路是否打通。
 
@@ -35,12 +37,12 @@ OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你
 
 ## 详细配置步骤
 
-### 第一步：准备中继节点 (Relay)
+### 第一步：准备中继节点（Relay）
 
 内网流量需要通过公网的中继节点进行中转。在开始前，你需要确保公网有一台可用的中继服务器。
 
 1. 登录管理端，进入 **「节点管理」**。
-2. 添加一个新节点，并将 **节点类型** 选择为 **中继节点 (tunnel_relay)**。
+2. 添加一个新节点，并将 **节点类型** 选择为 **中继节点（tunnel_relay）**。
 3. 保存后，复制该节点专属的 `agent_token`。
 4. 在你的公网服务器上启动 `openflare-relay`。你可以直接使用 Docker 快速运行：
 
@@ -54,20 +56,20 @@ OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你
    ```
 
    > [!IMPORTANT]
-   > 请务必在云服务器安全组中放行 `7000` 端口（frpc 客户端连接控制端口）。如果你的 Server 与中继节点部署在同一台机器，这里的 `OPENFLARE_SERVER_URL` 应指向 Server 的公网或内网通信 IP。
+   > 请务必在云服务器安全组中放行 `7000` 端口（frpc 客户端连接控制端口，默认 `relay_bind_port`）。如果你的 Server 与中继节点部署在同一台机器，这里的 `OPENFLARE_SERVER_URL` 应指向 Server 的公网或内网通信 IP。
 
 ### 第二步：在管理端创建 Tunnel 节点
 
 1. 导航至管理侧边栏的 **「节点管理」** 页面。
-2. 点击 **「新增节点」** 按钮，在弹窗中选择节点类型为 **「Tunnel 节点 (tunnel_client)」**。
+2. 点击 **「新增节点」** 按钮，在弹窗中选择节点类型为 **「Tunnel 节点（tunnel_client）」**。
 3. 填入节点名称与描述，点击保存。
 4. 在节点列表中点击进入刚才创建的 Tunnel 节点详情页，你可以找到专属的 **Tunnel Token** 及相应的客户端一键部署命令。
 
-### 第三步：部署内网客户端 (OpenFlared)
+### 第三步：部署内网客户端（OpenFlared）
 
 回到你的内网服务器中，根据刚才复制的部署命令运行客户端。
 
-#### 方案 A：使用 Docker 部署（强烈推荐）
+#### 方案 A：使用 Docker 部署（推荐）
 
 官方提供的 `openflared` 镜像已经内置了主控守护进程与 `frpc` 运行时，开箱即用，无需配置额外依赖：
 
@@ -108,8 +110,8 @@ docker run -d --name openflared --restart unless-stopped \
 现在你可以为你的内网服务配置公网反向代理和域名访问了。
 
 1. 首先进入 **「网站管理」->「域名列表」** 录入你想要公开访问的域名。
-2. 进入 **「规则管理」** 页面，点击 **「新增规则」** 或编辑已有规则。
-3. 在下方 **「反向代理」** 选项卡下，将 **源站类型** 切换为 **「内网穿透」**。
+2. 进入 **「规则管理」** 页面，点击 **「新建规则」** 或编辑已有规则。
+3. 在下方 **「反向代理」** 选项卡下，将 **回源方式** 切换为 **「内网穿透（Tunnel）」**。
 4. 从下拉列表中选择刚才部署在线的 **Tunnel 节点**。
 5. 填写 **内网目标地址**（对于内网客户端来说可访问的本地地址与端口，例如 `127.0.0.1:8080`）与 **内网协议**（通常为 `http`）。
 6. 配置其他站点常规项，并点击保存。
@@ -118,35 +120,35 @@ docker run -d --name openflared --restart unless-stopped \
 
 为了让网关的 OpenResty 能够正确匹配并路由域名流量，我们需要发布新的配置版本。
 
-1. 点击导航栏右上角的 **「配置预览」**，确认生成的站点配置无误。
-2. 在弹出窗口中，点击 **「发布并激活」**。
-3. 此时，公网边缘的 Agent 会拉取到最新路由：它会将 `nas.example.com` 的请求转发至同机部署的 `openflare-relay (frps)` 的虚拟主机端口下。
-4. 内网客户端 `openflared (frpc)` 会接收到被中继的封包，并安全地透传给内网的 `127.0.0.1:8080` 服务，最后原路返回响应。
-5. 在你的公网浏览器中访问 `nas.example.com`，确认内网服务成功展示！
+1. 点击导航栏右上角的 **「预览并发布」**，确认生成的站点配置无误。
+2. 在弹出窗口中，点击 **「确认发布」**。
+3. 此时，公网边缘的 Agent 会拉取到最新路由：它会将请求转发至同机部署的 `openflare-relay（frps）` 的虚拟主机端口下。
+4. 内网客户端 `openflared（frpc）` 会接收到被中继的封包，并安全地透传给内网的 `127.0.0.1:8080` 服务，最后原路返回响应。
+5. 在你的公网浏览器中访问对应域名，确认内网服务成功展示。
 
 ---
 
 ## 高级应用场景
 
-### 1. 单隧道多服务复用 (多端口映射)
+### 1. 单隧道多服务复用（多端口映射）
 
 你并不需要为内网的每一个服务都部署一个 `openflared` 容器。
 
 如果你想在一个内网环境映射多个不同的服务（例如：`127.0.0.1:80` 是博客，`127.0.0.1:8080` 是 API，`192.168.1.120:9000` 是内网网盘）：
 1. 保持这一个 `openflared` 客户端在线。
 2. 在管理端创建三个独立的网站配置（绑定各自对应的公网域名）。
-3. 这三个网站配置都将 **上游类型** 选为 **同一个穿透隧道**。
-4. 分别在各自的“内网目标地址”中填入对应不同的端口或局域网 IP（例如 `127.0.0.1:80`、`127.0.0.1:8080`、`192.168.1.120:9000`）。
+3. 这三个网站配置都将 **回源方式** 选为 **同一个穿透隧道**。
+4. 分别在各自的内网目标地址中填入对应不同的端口或局域网 IP（例如 `127.0.0.1:80`、`127.0.0.1:8080`、`192.168.1.120:9000`）。
 5. 发布并激活新版本，即可实现一隧多用。
 
 ### 2. 网关安全功能无缝叠加
 
 因为所有公网流量均首先进入公网的 Agent 节点，在此处完成了 HTTPS/TLS 握手与 WAF 引擎拦截，然后再通过安全隧道送达内网。
 
-因此，你的内网服务**天然且无需做任何改造**即可享受以下高级特性：
-*   **一键启用 HTTPS**：直接在管理端为域名选择或申请 SSL 证书，数据传输全程加密。
-*   **全局/自定义 WAF 防护**：开启 SQL 注入拦截、XSS 注入防御与恶意地域 IP 屏蔽。
-*   **人机挑战 (CC PoW)**：一键抵御针对内网服务的恶意 CC 刷接口攻击。
+因此，你的内网服务**无需做任何改造**即可享受以下特性：
+* **一键启用 HTTPS**：直接在管理端为域名选择或申请 SSL 证书，数据传输全程加密。
+* **全局/自定义 WAF 防护**：开启 SQL 注入拦截、XSS 注入防御与恶意地域 IP 屏蔽。
+* **人机挑战（CC PoW）**：一键抵御针对内网服务的恶意 CC 刷接口攻击。
 
 ---
 
@@ -154,17 +156,17 @@ docker run -d --name openflared --restart unless-stopped \
 
 ### 1. 隧道在管理端显示为「离线」
 
-*   **检查 Token 是否正确**：查看 `flared` 日志或环境变量中配置的 `tunnel_token` 是否与管理端生成的一致。
-*   **检查网络连通性**：内网服务器需能通过出向网络正常请求 Server 地址。确保控制面没有启用防火墙限制客户端的 HTTP 请求。
-*   **中继节点防火墙未开**：检查对应中继节点的公网 `7000` 端口（或你自定义的 bindPort）是否已经在安全组中对公网放行。
+* **检查 Token 是否正确**：查看 `flared` 日志或环境变量中配置的 `tunnel_token` 是否与管理端生成的一致。
+* **检查网络连通性**：内网服务器需能通过出向网络正常请求 Server 地址。
+* **中继节点防火墙未开**：检查对应中继节点的公网 `7000` 端口（或自定义的 `relay_bind_port`）是否已经在安全组中对公网放行。
 
 ### 2. 访问公网域名返回 502 Bad Gateway / 504 Gateway Timeout
 
-*   **内网服务未运行**：确认内网目标地址对应的服务已在内网服务器上成功启动并处于监听状态。
-*   **目标地址不可达**：如果内网地址填的是 `127.0.0.1:8080`，确保服务确实在运行着 `openflared` 的同一台主机上；如果填的是局域网 IP `192.168.x.x`，请在 `openflared` 容器内测试该局域网 IP 的连通性。
-*   **检查客户端应用日志**：在管理端查看「应用记录」或在内网查看 `flared` 运行日志，排查是否有 `LastError` 产生。frpc 在连不上内网端口时，会将连接失败报错原样上报至 Server 方便管理员定位。
+* **内网服务未运行**：确认内网目标地址对应的服务已在内网服务器上成功启动并处于监听状态。
+* **目标地址不可达**：如果内网地址填的是 `127.0.0.1:8080`，确保服务确实在运行着 `openflared` 的同一台主机上；如果填的是局域网 IP `192.168.x.x`，请在 `openflared` 容器内测试该局域网 IP 的连通性。
+* **检查节点状态与日志**：在管理端查看 Tunnel 节点详情与「应用记录」，排查是否有异常状态；frpc 进程异常时会在内网宿主机 `flared` 日志中记录详细报错。
 
 ### 3. 多中继网络动荡或重试失败
 
-*   当控制面关联了多个 Relay 中继节点时，`openflared` 会为每个 Relay 独立派生 frpc 守护进程，并在 `flared.json` 中配置的 `sync_interval`（默认 30s）内定时向控制面拉取拓扑状态。
-*   若发现某一中继节点频繁由于网络抖动离线，系统会自动触发退避重试机制。你可以在宿主机日志中看到 `frpc process missing, starting` 的日志，这属于正常的进程自愈逻辑，通常在网络恢复后 5~10 秒内即可自动恢复建连。
+* 当控制面关联了多个 Relay 中继节点时，`openflared` 会为每个 Relay 独立派生 frpc 守护进程，并在 `flared.json` 中配置的 `sync_interval`（默认 30s）内定时向控制面拉取拓扑状态。
+* 若某一中继节点频繁由于网络抖动离线，系统会自动触发指数退避重试（初始 1 秒，上限 60 秒）。你可以在宿主机日志中看到 `frpc process missing, starting` 的日志，这属于正常的进程自愈逻辑，网络恢复后会自动重新建连。

docs/guide/uptime-kuma.md

@@ -14,11 +14,11 @@
 
 ## 第一步：在系统设置中配置集成
 
-1. 登录管理端控制面板，进入左侧导航 **「系统设置」** (Settings)，选择 **「OpenFlare」** 选项卡，在 **「Uptime Kuma 集成」** 区域进行配置。
+1. 登录管理端控制面板，进入左侧导航 **「系统设置」**，选择 **「OpenFlare」** 选项卡，在 **「Uptime Kuma 集成」** 区域进行配置。
 2. 配置以下核心连接参数：
-   * **启用状态 (Enabled)**：开启集成开关。
-   * **实例地址 (Instance URL)**：你的 Uptime Kuma 服务地址。例如 `http://192.168.1.100:3001` 或 `https://kuma.example.com`（必须包含协议前缀 `http://` 或 `https://`）。
-   * **用户名 (Username)** 与 **密码 (Password)**：具有管理权限的 Uptime Kuma 账户凭证，用于 API 鉴权。
+   * **启用状态（Enabled）**：开启集成开关。
+   * **实例地址（Instance URL）**：你的 Uptime Kuma 服务地址。例如 `http://192.168.1.100:3001` 或 `https://kuma.example.com`（必须包含协议前缀 `http://` 或 `https://`）。
+   * **用户名（Username）** 与 **密码（Password）**：具有管理权限的 Uptime Kuma 账户凭证，用于 API 鉴权。
 
 ---
 
@@ -26,24 +26,24 @@
 
 在集成面板中，你可以对监控范围和具体探测行为进行细粒度控制：
 
-### 1. 监控范围 (Monitor Scope)
-*   **全部站点 (All)**：默认选项。OpenFlare 将自动同步所有**已启用**的代理路由站点。当新站点被创建且启用，或者旧站点被停用时，监控列表将自动增删。
-*   **选择站点 (Selected)**：仅监控指定站点。选择此模式后，可以点击 **「选择监控站点」** 弹出框。在弹出框内可以通过搜索过滤站点并进行勾选。被取消勾选或未勾选的站点将不会被同步（若已存在则会被自动清理）。
+### 1. 监控范围（Monitor Scope）
+* **全部站点（All）**：默认选项。OpenFlare 将自动同步所有**已启用**的代理路由站点。当新站点被创建且启用，或者旧站点被停用时，监控列表将自动增删。
+* **选择站点（Selected）**：仅监控指定站点。选择此模式后，可以点击 **「选择监控站点」** 弹出框。在弹出框内可以通过搜索过滤站点并进行勾选。被取消勾选或未勾选的站点将不会被同步（若已存在则会被自动清理）。
 
 ### 2. 监测频率与心跳设置
 你可以为自动生成的监控项指定统一的探测参数：
-*   **同步间隔 (Sync Interval)**：自动差分同步的频率（分钟），默认为 `5` 分钟。即控制面每 5 分钟与 Uptime Kuma 进行一次状态比对。
-*   **心跳检测频率 (Interval)**：Uptime Kuma 探测站点的频率（秒），默认为 `60` 秒。
-*   **最大重试次数 (Retry)**：探测失败后，判定为 Down 之前的最大重试次数，默认为 `0`。
-*   **重试间隔时间 (Retry Interval)**：重试之间的等待秒数，默认为 `60` 秒。
-*   **请求超时时间 (Timeout)**：探测请求判定为超时的秒数，默认为 `48` 秒。
+* **同步间隔（Sync Interval）**：自动差分同步的频率（分钟），默认为 `5` 分钟。即控制面每 5 分钟与 Uptime Kuma 进行一次状态比对。
+* **心跳检测频率（Interval）**：Uptime Kuma 探测站点的频率（秒），默认为 `60` 秒。
+* **最大重试次数（Retry）**：探测失败后，判定为 Down 之前的最大重试次数，默认为 `0`。
+* **重试间隔时间（Retry Interval）**：重试之间的等待秒数，默认为 `60` 秒。
+* **请求超时时间（Timeout）**：探测请求判定为超时的秒数，默认为 `48` 秒。
 
 ---
 
 ## 同步与清理机制
 
-*   **专属标签隔离**：所有自动创建的监控项均会绑定 `OpenFlare` 专属标签（紫蓝色）。同步和清理程序仅操作带有该标签的监控任务，**绝不干扰或破坏你在 Uptime Kuma 中手动创建的其他监控项**。
-*   **差分增量同步**：同步程序会周期性对比监控元数据。当检测到域名或心跳配置变更时，仅执行差分更新，避免中断历史统计数据；当站点停用或移出范围时，会自动执行监控下线清理。
+* **专属标签隔离**：所有自动创建的监控项均会绑定 `OpenFlare` 专属标签（紫蓝色）。同步和清理程序仅操作带有该标签的监控任务，不会干扰或破坏你在 Uptime Kuma 中手动创建的其他监控项。
+* **差分增量同步**：同步程序会周期性对比监控元数据。当检测到域名或心跳配置变更时，仅执行差分更新，避免中断历史统计数据；当站点停用或移出范围时，会自动执行监控下线清理。
 
 > [!TIP]
 > 关于 Uptime Kuma 监控同步的 Socket.IO 控制流、防污染标签模型及差分比对算法细节，请参阅 [Uptime Kuma 监控同步设计](../design/kuma-design.md)。

docs/guide/waf-ip-group-expr.md

@@ -29,7 +29,7 @@
 
 ## 执行口径
 
-自动规则不是逐条请求判断，而是先按单个客户端 IP 聚合：
+自动 IP 组先按单个客户端 IP 聚合指标，再对每个 IP 执行规则表达式：
 
 1. Server 读取最近 `lookback` 时长内的请求日志。
 2. 按 `remote_addr` 归一化后的 IP 分组。