ryan
7.9 KiB
产品边界
你会学到：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_routesoriginsconfig_versionsnodesauth_sourcesexternal_accountsnode_system_profilesapply_logstls_certificatesmanaged_domainsnode_request_reportsnode_access_logsnode_metric_snapshotstraffic_analytics_rollupsnode_health_eventswaf_rule_groupswaf_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 sslserver块。 - 未绑定证书的域名不得被自动带入 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只承载控制面状态与低频摘要，不承载高频观测事实。- 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计。
- 访问明细只保留受控时间窗口，不演变成通用日志平台。