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

- 删除未经验证的环境要求（Docker 版本号、浏览器条目）与括号废话 - 故障排查改为真实处理路径（升级→重新发布→强制同步→重建 Agent→提交 issue），删除仅开发时用的排障章节 - 删除设计文档中的测试与验收、实现检查清单、贡献者阅读建议等开发内容 - 修正与代码不符的事实：reset-passwd 命令名、证书续签窗口 7 天、Pages 检查间隔 1440 分钟、Relay vhost 端口 8080、SSO 仅支持 OIDC 等 - 去除口语化表述与无意义括号，改写「不是…而是…」句式 - 同步修正文档站链接锚点，构建验证通过
2026-09-30 14:26:36 +08:00 · 2026-08-16 17:49:57 +08:00
parent 4e3d79c001
commit 600a7acdfb
37 changed files with 275 additions and 517 deletions
@@ -20,7 +20,7 @@ OpenFlare Agent 运行在代理节点侧。它不会接收远程 shell 指令，

 ## 一键安装

-### 交互式安装 (推荐)
+### 交互式安装（推荐）

 如果在不传递任何参数的情况下运行安装脚本，脚本将进入交互模式。您将可以通过向导选择安装方式（本地运行 / Docker 容器运行），并配置 Server 地址与认证 Token（若选择 Docker 方式且本地没有 Docker，脚本还会询问并智能安装 Docker）：

@@ -28,7 +28,7 @@ OpenFlare Agent 运行在代理节点侧。它不会接收远程 shell 指令，
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash
 ```

-### 自动化 (非交互式) 安装
+### 自动化（非交互式）安装

 如果在执行脚本时附加了任何参数，脚本将进入自动化安装模式，不需要任何交互。

@@ -115,7 +115,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
 }
 ```

-如果不配置 `openresty_path`，Agent 默认调用 `openresty`。完整字段见 [配置项参考](../reference/configuration.md#agent-配置字段)。
+如果不配置 `openresty_path`，Agent 默认调用 `openresty`。完整字段见 [配置项参考](../reference/configuration.md#agent-命令行参数与配置字段)。

 ## Docker 运行

@@ -138,7 +138,7 @@ docker run -d --name openflare-agent --restart unless-stopped \

 ## 卸载

-### 交互式卸载 (推荐)
+### 交互式卸载（推荐）

 如果在不传递任何参数的情况下运行卸载脚本，脚本将进入交互模式。您可以通过提示菜单选择卸载方式（本地卸载 / Docker 容器卸载）：

@@ -146,7 +146,7 @@ docker run -d --name openflare-agent --restart unless-stopped \
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
 ```

-### 卸载
+### Docker 容器卸载

 停止并删除 `openflare-agent` 容器即可

@@ -156,4 +156,4 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
 | --- |---------------------------------------------------------------------------------------------------------|
 | `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token                                                                           |
 | 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达                                           |
-| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；在节点尝试强制同步,或者重新发布版本                                |
+| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；在节点详情页点击「强制同步」，或重新发布新版本 |
@@ -2,7 +2,7 @@

 你会学到：OpenFlare 的推荐部署方式、Server 与 Agent 的运行要求、源码启动方式、联调步骤、升级与卸载入口。

-生产环境建议使用 PostgreSQL 作为 Server 数据库，并通过 `config.yaml` 或环境变量配置 `APP_SESSION_SECRET` 等参数。完整 Docker Compose 部署需要 Redis；ClickHouse 可选，用于海量访问日志与观测时序（见仓库根目录 `docker-compose.yaml`）。Agent 部署方式推荐为 Docker 部署（即直接使用内置 OpenResty 的 Agent 镜像）；亦支持通过安装脚本或手动本地运行。日志库判定与切换见 [日志存储解耦](../design/logstore.md)。
+生产环境建议使用 PostgreSQL 作为 Server 数据库，并通过 `config.yaml` 或环境变量配置 `APP_SESSION_SECRET` 等参数。完整 Docker Compose 部署需要 Redis；ClickHouse 可选，用于海量访问日志与观测时序（见仓库根目录 `docker-compose.yaml`）。Agent 支持 Docker 部署与本地安装脚本两种方式，Docker 镜像已内置 OpenResty 二进制。日志库判定与切换见 [日志存储解耦](../design/logstore.md)。

 ## 部署拓扑

@@ -49,7 +49,7 @@ Internal Service (192.168.x.x)

 ### 硬件配置推荐

-| 组件 | 最低硬件配额                        | 推荐硬件配额 | 说明 |
+| 组件 | 参考配置（入门）                    | 参考配置（生产） | 说明 |
 | --- |-------------------------------| --- | --- |
 | **Server 控制面** | 1 核 CPU / 2 GB 内存 / 20 GB 磁盘  | 2 核 CPU / 4 GB 内存 / 50 GB+ 磁盘 | 磁盘用量需根据访问日志留存时长与并发流量合理扩容 |
 | **Agent 数据面** | 1 核 CPU / 512 MB 内存 / 2 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 10 GB+ 磁盘 | 根据 OpenResty 的并发代理连接量与 WAF 拦截处理扩容 |
@@ -8,10 +8,10 @@

 ## 前置条件

-1. **获取 Tunnel Token**：在 OpenFlare 管理端的「内网穿透」或「隧道管理」页面中，创建一个新的隧道实例，系统会自动生成唯一的 `tunnel_id` 与 `tunnel_token`（形如 `tun-<32hex>`）。
+1. **获取 Tunnel Token**：在管理端「节点管理」中新增一个类型为 **Tunnel** 的节点，保存后进入节点详情页即可查看该节点专属的接入 Token。
 2. **网络出方向权限**：内网服务器无需任何公网入方向 IP 或端口映射，但必须能够通过网络访问公网上的 **OpenFlare Server 地址** 以及对应的 **TunnelRelay 节点中继端口 (默认 7000)**。
 3. **软件依赖**（仅限宿主机直接部署）：
-   - 本地需有可执行的 `frpc` 二进制文件（建议版本为 `v0.61.0+` 或最新稳定版 `v0.69.0`），或通过参数显式指定路径。
+   - 本地需有可执行的 `frpc` 二进制文件，或通过参数显式指定路径。

 ---

@@ -58,8 +58,8 @@ docker run -d --name openflared --restart unless-stopped \
 启动成功后，OpenFlared 将执行以下工作流：
 - **心跳与配置获取**：周期性向 Server 的 `/api/v1/tunnel/heartbeat` 和 `/api/v1/tunnel/config/active` 接口发起同步，验证 Token 并检测配置版本。
 - **文件渲染**：当检测到配置版本（或校验和 Checksum）变化时，会自动拉取该隧道的完整路由规则。如果绑定了多个中继 Relay，将为每个 Relay 分别在 `data_dir` 下渲染出 `frpc_{relayNodeID}.toml`。
- **热重载或重启**：拉起对应的 `frpc` 子进程，或在配置文件发生改变时执行 `frpc reload` / 重启动作，以确保流量映射保持最新。
- **异常自恢复**：如果本地 `frpc` 隧道进程异常退出，主控程序会在 5 秒的退避惩罚后自动尝试重新启动。
+- **配置变更重启**：当配置或校验和变化时，重新拉起对应的 `frpc` 子进程，以确保流量映射保持最新。
+- **异常自恢复**：如果本地 `frpc` 隧道进程异常退出，主控程序会按指数退避（初始 1 秒，上限 60 秒）自动重启。

 ### 2. 查看日志与连接状态

@@ -79,6 +79,6 @@ frpc process missing, starting {"relay_id": "..."}

 ### 3. 管理端确认

-打开管理后台的 **「内网穿透」** 页面：
- 查看对应隧道的在线状态，此时应当绿灯显示 **「在线」**。
- 您可以清晰地看到该隧道目前连接了哪些中继节点，以及各内网服务的穿透路由详情。
+打开管理后台的 **「节点管理」**，进入对应 Tunnel 节点的详情页：
+- 查看节点在线状态与 flared 运行状态（WebSocket 已连接 / 运行中 / 离线）。
+- 查看当前应用版本与最近一次应用记录。
@@ -1,4 +1,4 @@
-# 部署 Relay (Tunnel 中继)
+# 部署 Relay（Tunnel 中继）

 你会学到：TunnelRelay 节点的职责、`openflare-relay` 的配置项与环境变量、使用 Docker 运行 Relay 的方法，以及如何通过源码手动构建并部署 Relay。

@@ -40,7 +40,7 @@

 ---

-## Docker 运行）
+## Docker 运行

 Docker 运行是 TunnelRelay 节点最便捷的部署方案。官方镜像内置了 `openflare-relay` 控制器与 `frps` 运行时，开箱即用。

@@ -84,7 +84,7 @@ docker logs -f openflare-relay
 - 从控制面获取最新的 frps 基础配置（包括 `bindPort`、`vhostHTTPPort` 与自动生成的隧道认证凭证 `auth_token`）。
 - 在本地自动渲染出 `data/frps.toml` 配置文件。
 - 自动拉起子进程 `frps -c data/frps.toml`。
- 如果进程意外崩溃，Relay 将在 2 秒后自动拉起它。
+- 如果进程意外退出，Relay 会按指数退避（初始 1 秒，上限 60 秒）自动重启 frps。

 ### 3. 管理端确认

@@ -7,7 +7,7 @@ OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 AP
 > [!IMPORTANT]
 > **关于外部依赖**：
 > OpenFlare 系统内建了对后台异步任务（Asynq 框架）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。
-> 若业务流量过大, 建议使用 ClickHouse 存储日志。
+> 若业务流量过大，建议使用 ClickHouse 存储日志。

 > [!TIP]
 > **ClickHouse 服务端性能配置（推荐挂载）**  
@@ -34,11 +34,11 @@ volumes:

 ---

-## 方式一：Docker 部署 (推荐)
+## 方式一：Docker 部署（推荐）

 使用 Docker 部署可以免去本地配置 Go 与 Node.js 前端构建环境的麻烦。根据你的服务器硬件配置及业务需求，你可以选择以下三种方案之一：

-### 1. 快速启动 (SQLite + Redis)
+### 1. 快速启动（SQLite + Redis）

 > **适用场景**：测试体验、轻量化单机部署。
 >
@@ -66,8 +66,6 @@ services:
      SQLITE_PATH: "/data/openflare.db"
      REDIS_ENABLED: "true"
      REDIS_ADDR: "redis:6379"
-      CLICKHOUSE_ENABLED: "true"
-      CLICKHOUSE_HOST: "clickhouse:9000"
    depends_on:
      redis:
        condition: service_healthy
@@ -87,9 +85,9 @@ services:

 ---

-### 2. 小流量业务场景 (PostgreSQL + Redis)
+### 2. 小流量业务场景（PostgreSQL + Redis）

-> **适用场景**：生产环境、业务流量中小, PostgreSQL 不会成为日志记录的瓶颈。
+> **适用场景**：生产环境、业务流量中小，PostgreSQL 不会成为日志记录的瓶颈。

 创建 `docker-compose.yaml` 文件：

@@ -157,11 +155,11 @@ docker compose up -d

 ---

-### 3. 进阶版 (含 Jaeger 链路追踪的完整编排)
+### 3. 进阶版（含 Jaeger 链路追踪的完整编排）

-> **适用场景**：大流量场景, 需要进行链路性能指标追踪。
+> **适用场景**：大流量场景，需要进行链路性能指标追踪。
 >
-> **特点**：在“生产推荐”全家桶的基础上，使用 ClickHouse 存储日志, 联动 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端。
+> **特点**：在“生产推荐”全家桶的基础上，使用 ClickHouse 存储日志，联动 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端。

 创建 `docker-compose.yaml` 文件：

@@ -177,7 +175,7 @@ services:
      TZ: ${TZ:-Asia/Shanghai}
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://jaeger:4317"
      OTEL_EXPORTER_OTLP_INSECURE: "true"
-      OTEL_SAMPLING_RATE: "1.0" # 本地调试建议设为 1.0 以采样所有 Trace
+      OTEL_SAMPLING_RATE: "1.0" # 采样率，1.0 表示采样全部 Trace
    ports:
      - "3000:3000"
    volumes:
@@ -17,4 +17,4 @@ docker compose up

 ## Agent 升级

-Agent 是完全无状态的，升级时直接拉取最新镜像重建容器即可。具体部署命令与安装方式请参考 **[接入 Agent](./agent.md)**。
+Agent 本地仅缓存运行配置与状态文件，不保存业务数据；升级时直接拉取最新镜像重建容器即可。具体部署命令与安装方式请参考 **[接入 Agent](./agent.md)**。