[优化] 文档更新

docs/guide/first-site.md

@@ -1,100 +1,69 @@
 # 发布第一份配置
 
-你会学到：如何创建第一条网站配置、绑定源站与证书、发布配置版本，并确认 Agent 已经应用。
+你会学到：如何以最简单的方式创建第一条反向代理规则、发布配置版本，并确认 Agent 已经拉取并应用配置。
 
-OpenFlare 的发布链路以完整配置版本为中心。你在管理端修改网站配置后，需要发布并激活新版本，Agent 才会在后续 heartbeat 中拉取并应用。
+OpenFlare 的发布链路以“不可变配置版本”为核心。你在管理端修改规则后，需要发布并激活新版本，在线的 Agent 才会自动同步并应用。
+
+---
 
 ## 发布前检查
 
-确认以下条件已经满足：
+在开始发布前，请确保以下条件已满足：
 
-| 项目 | 期望 |
+| 检查项 | 状态要求 |
 | --- | --- |
-| Server | 可以登录管理端 |
-| Agent | 至少一个节点在线 |
-| 源站 | Agent 节点可以访问源站地址 |
-| 域名 | 域名已经解析到 OpenResty 节点，或准备通过本地 hosts / curl Host 头验证 |
-| HTTPS | 如需 HTTPS，证书已上传或托管 |
+| **Server** | 控制面板已正常启动，且能顺利登录管理端 |
+| **Agent** | 至少有一个 Agent 节点处于在线状态（可在「节点管理」中确认） |
+| **源站** | 确认你的后端源站服务可从 Agent 宿主机正常访问 |
+| **域名/测试** | 域名已完成 DNS 解析，或者准备好在客户端使用本地 hosts / curl 命令行 Host 头进行测试 |
 
-## 创建网站配置
+---
 
-在管理端新增网站配置时至少需要：
+## 步骤一：创建首个网站配置
 
-| 字段 | 说明 |
-| --- | --- |
-| 网站名称 | 业务唯一标识；未显式填写时可使用主域名 |
-| 域名 | 至少一个域名，第一项视为主域名 |
-| 源站地址 | 合法的 `http://` 或 `https://` 上游地址 |
-| 启用状态 | 只有启用的网站配置会参与发布渲染 |
+为了快速验证，我们首先部署一个最基础的 HTTP 反代站点：
 
-示例：
+1. 登录控制面板，进入 **「网站配置」**，点击 **「创建网站」**。
+2. 填写最基础的站点配置：
+   * **网站名称**：输入简易标识（如 `first-app`）。
+   * **域名 (Domains)**：输入用于测试的域名（如 `first.example.com`）。**第一项默认作为主域名**。
+3. 配置上游源站（Upstream）：
+   * **源站类型**：选择「标准反代」。
+   * **源站地址**：勾选手动输入并填入后端服务地址（如 `http://10.0.0.10:8080` 或测试专用的 `http://httpbin.org`）。
+4. 点击保存，完成网站创建。
 
-| 字段 | 示例 |
-| --- | --- |
-| 网站名称 | `app` |
-| 域名 | `app.example.com` |
-| 源站地址 | `http://10.0.0.20:8080` |
+> [!TIP]
+> **关于 HTTPS 与证书准备**
+> 本节仅引导快速部署基础 HTTP 规则。若你需要导入已有的 SSL 证书或通过 ACME 协议向 Let's Encrypt 自动申请证书并开启 443 端口 HTTPS 代理，请前往 [新建反代配置](./proxy-config.md) 查阅详细步骤。
 
-同一个域名只能属于一个网站配置。同一网站内的流量限制、反向代理和缓存配置按站点共享。
+---
 
-## 绑定证书
+## 步骤二：预览并发布配置版本
 
-HTTPS 证书按域名绑定。没有绑定证书的域名不会被自动放入 `443 ssl` server 块。
+新增的网站配置仍保存在 Server 的数据库中，处于草稿状态，需要通过发布版本分发到数据面：
 
-如果一个网站包含多个域名，发布渲染会按证书分组生成 HTTPS 配置，并确保所有域名仍属于同一站点快照。
+1. 点击控制面板右上角的 **「配置预览」** 按钮，系统会展示本次新增路由的物理配置文件 Diff 差异。
+2. 确认渲染出的配置内容正确无误后，点击 **「发布并激活」**。
+3. 控制面将生成一个唯一的配置版本号（格式为 `YYYYMMDD-NNN`）。
 
-## 发布与激活
+---
 
-标准链路：
+## 步骤三：验证 Agent 生效状态
 
-```text
-修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
-```
+发布成功后，控制面会立即通过 WebSocket 通知在线 Agent（若 WebSocket 离线，则会在 Agent 的心跳中作为差分感知）：
 
-发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数与缓存参数，渲染完整 OpenResty 配置，计算 `checksum`，写入 `config_versions`，再切换激活版本。
-
-## 验证结果
-
-发布后在管理端确认：
-
-| 位置 | 期望结果 |
-| --- | --- |
-| 节点列表 | 节点在线 |
-| 节点详情 | 当前版本与激活版本一致 |
-| 应用记录 | 最近一次应用成功 |
-| 版本页面 | 新版本处于激活状态 |
-
-在节点上确认 Agent 日志：
-
-```bash
-journalctl -u openflare-agent -n 100 --no-pager
-```
-
-用域名访问：
-
-```bash
-curl -I http://app.example.com
-```
-
-如果域名还没有正式解析，可以临时指定 Host 头访问节点 IP：
-
-```bash
-curl -I -H 'Host: app.example.com' http://NODE_IP
-```
-
-HTTPS 验证：
-
-```bash
-curl -I https://app.example.com
-```
-
-## 回滚
-
-如果目标版本应用失败并回滚，Agent 会在本地阻断同一 `version + checksum` 的重复应用，直到控制面激活版本或 checksum 发生变化。
-
-回滚到旧版本：
-
-1. 打开配置版本页面。
-2. 找到上一个确认可用的历史版本。
-3. 重新激活该版本。
-4. 查看节点应用记录，确认 Agent 应用成功。
+1. **管理端验证**：进入「节点管理」-> 点击节点进入详情，检查**当前版本号**是否已成功变为刚刚发布的最新激活版本，且「应用记录」显示为成功。
+2. **边缘节点验证**：你可以在 Agent 节点宿主机上通过日志检查应用情况：
+   ```bash
+   # 如果是 Docker 部署的 Agent
+   docker logs openflare-agent
+   
+   # 如果是本地 systemd 部署的 Agent
+   journalctl -u openflare-agent -n 50 --no-pager
+   ```
+3. **连通性测试**：
+   在客户端电脑上，使用 `curl` 携带测试 Host 请求 Agent 节点的 IP 地址进行最终验证：
+   ```bash
+   curl -I -H "Host: first.example.com" http://AGENT_NODE_IP
+   ```
+   若返回的状态码与后端源站响应一致，即代表你的第一条反代规则已成功在边缘节点落地生效！