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 确认渲染结果。

启用 HTTPS

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

操作顺序：

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

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

发布、激活与回滚

标准链路：

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

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

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

查看节点与观测

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

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

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

常见场景

新增一个内部服务反代

1. 确认源站服务可从 Agent 节点访问。
2. 在管理端新增网站配置。
3. 填写域名，例如 app.example.com。
4. 填写源站，例如 http://10.0.0.20:8080。
5. 发布并激活版本。
6. 在 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 配置文件；下次发布会覆盖这些文件。