# 产品边界

OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。

当前稳定能力包括：

| 能力 | 说明 |
| --- | --- |
| 反代规则管理 | 以网站配置为聚合边界，支持多域名与源站配置 |
| 网站级配置 | 一条规则对应一个网站，可绑定一个或多个域名，并共享站点级配置 |
| 源站管理 | 维护轻量源站目录，并允许网站保存可渲染的源站快照 |
| 配置版本 | 支持预览、发布、激活、不可变历史与回滚 |
| Agent 同步 | 支持注册、心跳、同步、应用结果上报与自更新 |
| OpenResty 托管 | 管理主配置模板、性能参数、缓存参数与 Lua 资源 |
| HTTPS/TLS | 托管证书与域名资产，并按域名绑定证书 |
| 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 |
| 节点管理 | 节点状态、令牌体系、部署与更新链路 |
| 管理端前端 | 基于 Next.js 的正式管理端 |
| 认证源登录 | 支持以认证源形式配置 GitHub 与标准 OIDC 登录入口，并允许第三方账号绑定已有本地用户 |

默认工作方式：

* 所有节点消费同一份全局激活版本。
* Server 保存配置与状态，不直接 SSH 管理节点。
* Agent 是节点侧唯一受控落地入口。

## 核心对象

当前有效实体：

* `proxy_routes`
* `origins`
* `config_versions`
* `nodes`
* `auth_sources`
* `external_accounts`
* `node_system_profiles`
* `apply_logs`
* `tls_certificates`
* `managed_domains`
* `node_request_reports`
* `node_access_logs`
* `node_metric_snapshots`
* `traffic_analytics_rollups`
* `node_health_events`

## 网站配置约束

`proxy_routes` 从“单域名规则”升级为“网站配置”聚合对象。一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置。

约束：

* `proxy_routes.site_name` 是网站的业务唯一标识。
* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名。
* 任一域名全局只能属于一个 `proxy_routes`。
* 迁移期可保留 `proxy_routes.domain` 作为 `domains[0]` 的镜像字段，但业务读写与后续扩展必须以 `site_name` + `domains` 为准。
* 网站级流量限制、反向代理与缓存配置当前按站点共享，不在同一网站内做域名级差异化配置。
* HTTPS 允许在同一站点内按域名绑定证书。

## 源站约束

`origins` 只保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略。

`proxy_routes` 可选关联一个 `origins` 记录，用于复用源站地址；规则仍保存完整 `origin_url` 快照以参与渲染与版本快照。

上游约束：

* `proxy_routes` 至少包含一个上游地址。
* 为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡。
* 上游统一渲染为带 keepalive 的 named `upstream`。
* 单上游可附带 base path 或 query 并在 `proxy_pass` 中追加。
* 多上游限定为纯 `scheme://host[:port]`。
* `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头。
* 所有上游地址都必须为合法 `http://` 或 `https://`。

## HTTPS 约束

`proxy_routes.domain_cert_ids` 用于记录与 `domains` 平行的域名证书绑定；值为 `0` 表示该域名不启用 HTTPS，仅保留 HTTP。

发布渲染时：

* 带证书的域名按证书分组输出独立 `443 ssl` `server` 块。
* 未绑定证书的域名不得被自动带入 HTTPS。
* 必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。

## 认证源约束

`auth_sources` 是管理端第三方登录入口的配置对象，当前仅支持 `github` 与 `oidc` 两类。启用后的认证源会显示在登录页。

`external_accounts` 保存认证源外部账号与本地用户的绑定关系。第三方账号首次登录时：

* 已绑定本地用户则直接登录。
* 当前已有本地登录 Session 时，绑定到当前用户。
* 未绑定且允许注册时，自动创建普通用户并绑定。
* 未绑定且关闭注册时，只允许用户输入已有本地账号密码完成绑定。

旧 `users.github_id` 仅作为升级迁移来源，新的第三方账号登录与绑定关系必须以 `external_accounts` 为准。

## 版本与观测约束

* `config_versions` 必须保存完整快照、渲染结果与 `checksum`。
* 全局同时只能有一个激活版本。
* 回滚通过重新激活旧版本实现。
* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实。
* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计。
* 访问明细只保留受控时间窗口，不演变成通用日志平台。

## 文档维护原则

* 产品范围或系统边界变化时更新本文档。
* 开发约束、代码规范、接口约定变化时更新 [开发约束](./development.md)。
* 部署方式变化时更新 [部署说明](../guide/deployment.md) 与 README。
* 配置项变化时更新 [配置项参考](../reference/configuration.md)。
* 已完成阶段不再以“版本计划”形式回填。
* 新阶段开始前，先补设计，再进入实现。