OpenFlare/docs/design/index.md

产品边界

你会学到：OpenFlare 是什么、解决什么问题、目标用户是谁、当前稳定能力有哪些，以及哪些设计边界在实现时不能被绕过。

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

项目定位

OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队：

• 希望用管理端维护反向代理网站配置。
• 希望每次配置变更都有完整版本、预览、激活与回滚。
• 希望节点主动同步配置，而不是由控制面 SSH 到节点执行命令。
• 希望在同一系统中管理 TLS 证书、域名资产、节点状态和基础访问分析。

OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingress Controller 或多租户云平台。

目标用户

用户	需求
自托管用户	快速部署一个可视化 OpenResty 控制面
内部运维团队	管理多个反向代理节点、证书和配置版本
开发团队	为内部服务提供统一入口和基础访问分析
贡献者	在明确边界内修复缺陷、补强测试和改进文档

当前稳定能力

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

默认工作方式：

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

典型使用场景

场景	说明
内部服务统一入口	把多个内部 HTTP 服务通过统一域名和证书暴露
多节点反代配置同步	多台 OpenResty 节点消费同一份激活配置
配置变更审查	发布前查看预览或 diff，发布后保留不可变历史
快速回滚	重新激活旧版本，让 Agent 拉取并应用
证书托管	为不同域名绑定 TLS 证书
基础观测	查看节点状态、请求聚合、访问分析和健康事件

核心对象

当前有效实体：

• 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
• waf_rule_groups
• waf_rule_group_bindings

网站配置约束

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 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。

WAF 约束

WAF 以规则组为配置边界。系统固定一个全局规则组，默认应用到所有网站；网站可叠加多个自定义规则组。

一期支持：

• IP / IP 段白名单与黑名单。
• 国家级地域白名单与黑名单。
• 规则组级拦截状态码与响应页面，默认 418 与空页面。

判定顺序：

• 白名单是放行例外，任意启用规则组命中白名单即放行。
• 未命中白名单时继续判断黑名单。
• 多个黑名单命中时，全局规则组优先，其后按自定义规则组 ID 升序。

地域识别由 Agent 维护节点本地 MaxMind mmdb，OpenResty Lua 在请求路径中读取本地库。GeoIP 依赖不可用时只能跳过地域规则，不得影响 IP 规则与反向代理主链路。

认证源约束

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

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

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

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

版本与观测约束

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

文档维护原则

• 产品范围或系统边界变化时更新本文档。
• 系统结构或模块职责变化时更新 系统架构。
• 发布、同步、回滚模型变化时更新 发布模型。
• 开发约束、代码规范、接口约定变化时更新 开发约束。
• 部署方式变化时更新 部署说明 与 README。
• 配置项变化时更新 配置项参考。
• 已完成阶段不再以“版本计划”形式回填。
• 新阶段开始前，先补设计，再进入实现。