OpenFlare/docs/guide/usage.md

基础使用

你会学到：OpenFlare 中网站配置、源站、证书、版本、节点和观测分别是什么，以及日常使用时应按什么顺序操作。

OpenFlare 不直接在线修改节点上的 Nginx/OpenResty 配置。你在管理端修改的是控制面数据；只有发布并激活新版本后，Agent 才会拉取完整配置并应用到节点。

核心概念

概念	说明
网站配置	反向代理配置的聚合对象，一条网站配置可以绑定一个或多个域名
主域名	domains 列表中的第一个域名，用作该网站的主要展示域名
源站	被反向代理访问的上游地址，例如 http://10.0.0.10:8080
配置版本	一次发布生成的完整 OpenResty 配置快照，历史版本不可变
激活版本	当前全局生效的配置版本，所有节点默认消费同一份激活版本
Agent	节点侧进程，负责注册、心跳、同步、校验、reload 和失败回滚

推荐操作顺序

日常发布一条反向代理配置时，推荐按这个顺序：

1. 确认至少有一个 Agent 节点在线。
2. 新增或选择源站地址。
3. 新增网站配置，填写域名、源站和站点级配置。
4. 如需 HTTPS，上传或选择证书，并按域名绑定。
5. 预览配置或查看变更摘要。
6. 发布并激活新版本。
7. 在节点详情和应用记录中确认应用结果。

创建网站配置

网站配置至少需要：

字段	要求
网站名称	业务唯一标识；未显式填写时通常可使用主域名
域名	至少一个域名，第一项为主域名；任一域名全局只能属于一个网站
源站地址	合法的 http:// 或 https:// 地址
启用状态	只有启用的网站配置会参与发布渲染

示例：

字段	示例
网站名称	docs
域名	docs.example.com
源站地址	http://10.0.0.10:8080
回源 Host	docs.internal.example.com

上游地址规则：

• 单上游可以携带 base path 或 query，例如 https://app.example.com/base?from=openflare。
• 多上游用于负载均衡时，每个上游必须是纯 scheme://host[:port]。
• 多上游在同一规则内应使用一致协议。

管理源站

源站是轻量目录，用来复用常见上游地址。网站配置关联源站后，仍会保存可渲染的 origin_url 快照，确保历史配置版本可以独立回放。

推荐做法：

• 把经常复用的内部服务地址维护为源站。
• 修改源站目录后，检查已发布的网站配置是否需要同步更新源站快照。
• 发布前使用预览或 diff 确认渲染结果。

托管 Pages 静态站点

Pages 用于托管已经构建完成的静态资源包。当前阶段只支持 Direct Upload，不执行 Git 构建、边缘函数或 SSR。

操作顺序：

1. 进入 Pages 页面，点击 新建 Pages 项目。
2. 填写项目名称、标识、描述；如为前端 history 路由应用，启用 SPA fallback 并填写回退路径，默认是 /index.html，也可以设置为 /app.html 等站点内绝对路径。
3. 创建后回到 Pages 项目列表，点击项目进入详情。
4. 在项目详情中上传 zip 静态资源包，并激活某个部署。
5. 新建或编辑网站规则，将回源方式切换为 Pages 静态站点，选择该 Pages 项目。
6. 发布并激活配置版本，Agent 会下载部署包、校验 checksum、解压到本地 Pages 目录，再由 OpenResty 本地服务静态文件。

Pages 项目只有在启用且存在激活部署后，才会出现在网站规则的 Pages 项目选择列表中。

启用 HTTPS

HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。

操作顺序：

1. 在证书管理中上传或托管证书。
2. 进入网站配置，为需要 HTTPS 的域名选择证书。
3. 未绑定证书的域名会保留 HTTP，不会被自动放入 443 ssl server 块。
4. 发布并激活新版本。

如果一个网站包含多个域名，Server 发布时会按证书分组渲染 HTTPS 配置，同时保持这些域名属于同一份网站快照。

配置 WAF 与 PoW

安全防护统一从管理端侧边栏的 WAF 入口进入：

• WAF 页面维护全局规则组和自定义规则组。全局规则组始终应用到全部网站；自定义规则组可以在规则组内一键选择网站，也可以在网站详情的 WAF 分区绑定。
• 点击 WAF 页面中的 管理 IP 组 可以进入独立 IP 组页面。手动 IP 组直接维护 IP/IP 段；自动 IP 组使用 Expr 规则按单个 IP 聚合请求日志并定时更新名单；订阅 IP 组可从远程文本或 JSON 源定时同步。
• 自动 IP 组页面提供两个预设：单个 IP 请求数大于 100 且 404 占比不低于 80%；单个 IP 通过 IP 地址访问次数大于 50 且该访问占比大于 50%。保存前可点击 测试规则 查看当前日志窗口命中的 IP，保存后可点击 立即执行 更新组内名单，语法见 WAF 自动 IP 组规则语法。
• 在 WAF 规则组的黑白名单中，IP 维度既可以直接添加 IP/IP 段，也可以引用已有 IP 组。发布时版本只携带 IP 组引用 ID；Agent 会按 checksum 差异同步 IP 组成员，并在 Server 通过 WebSocket 广播 IP 组更新时实时落地到节点。
• PoW 是规则组内的一个配置 Tab，位于 黑白名单 与 拦截返回 之间，复用站点已有 PoW 执行逻辑，可将当前 PoW 配置应用到全部网站或当前规则组绑定的网站。
• 网站详情页不再单独编辑 PoW 规则，只展示全局 WAF 规则组并绑定自定义 WAF 规则组。PoW 的启用范围和规则内容应回到 WAF 页面统一维护。

WAF 规则组、网站绑定或 PoW 配置修改后，需要重新发布并激活配置版本，Agent 才会拉取并应用到 OpenResty。IP 组成员变化不需要重新发布版本；在线 Agent 会通过 WebSocket 增量更新，离线或未升级 WS 的 Agent 会在下一次心跳中按 checksum 差异补齐。

详细的 WAF 安全配置与拦截判决原理请查阅 WAF 安全防护使用。

发布、激活与回滚

标准链路：

修改配置 -> 预览 / diff -> 发布 -> 生成完整版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果

发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数、缓存参数和证书资源，生成完整配置并计算 checksum。

回滚不是修改历史版本，而是重新激活旧版本。Agent 发现激活版本变化后，会按普通同步流程拉取并应用。

查看节点与观测

节点页面适合回答三个问题：

问题	查看位置
节点是否在线	节点列表或节点详情
当前运行哪个版本	节点详情中的当前版本
最近一次应用是否成功	应用记录

节点 IP 默认由 Agent 注册和后续心跳自动回填。若在管理端填写或修改 IP，节点编辑会默认开启“锁定节点 IP”；开启后 Agent 上报不会覆盖该 IP。关闭锁定后，下一次 Agent 心跳或 WebSocket 状态上报会重新按自动逻辑更新。

访问分析和资源快照用于基础观测。OpenFlare 只保留受控时间窗口内的访问明细，不定位为通用日志平台。如果需要长期日志检索，应接入独立日志系统。

常见场景

新增一个内部服务反代

1. 确认源站服务可从 Agent 节点访问。
2. 在管理端新增网站配置。
3. 填写域名，例如 app.example.com。
4. 填写源站，例如 http://10.0.0.20:8080。
5. 发布并激活版本。
6. 在 Agent 节点或浏览器访问域名验证。

Tip

如果你的源站部署在内网、没有公网 IP 且 Agent 无法直接访问，请使用内网穿透隧道功能将服务映射至公网。详细操作步骤请查阅 内网穿透与隧道使用。

给已有域名启用 HTTPS

1. 准备覆盖该域名的证书。
2. 在证书管理中上传或创建证书记录。
3. 回到网站配置，为对应域名选择证书。
4. 发布并激活版本。
5. 用浏览器或 curl -I https://your-domain 验证证书链和状态码。

回滚一次失败发布

1. 打开配置版本页面。
2. 找到上一个已知可用版本。
3. 重新激活该版本。
4. 查看节点应用记录，确认 Agent 已应用旧版本。
5. 修正配置后再发布新版本。

推荐实践

• 生产环境显式配置 SESSION_SECRET，并优先使用 PostgreSQL。
• 修改网站配置后先看预览或 diff，再发布。
• 每次发布后检查节点详情与应用记录。
• 多节点部署时保持 Agent 到 Server 的网络路径稳定。
• 不在节点上手动修改 OpenFlare 托管的 OpenResty 配置文件；下次发布会覆盖这些文件。