tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-02 06:56:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

OIDC

Browse Source
This commit is contained in:
ryan
2026-05-13 10:53:14 +08:00
parent 856e3f46d2
commit e85df49962
31 changed files with 2504 additions and 645 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vitepress/config.ts
+1 -2
View File
@@ -11,8 +11,7 @@ export default defineConfig({
srcExclude: [
'zh/**',
'components/**',
'snippets/**',
'website-configuration-redesign.md'
'snippets/**'
],
markdown: {
docs/design/architecture.md
+4 -1
View File
@@ -24,10 +24,13 @@ Origin
* GORM
* SQLite / PostgreSQL
* 现有登录与 Session 体系
* 认证源与外部账号绑定
* 托管 `openflare_server/web` 静态构建产物
Server 负责管理端 UI 与 API、Agent API、配置渲染、版本发布、数据存储与聚合查询。
认证源登录由 Server 统一处理。管理端配置 `github` 或 `oidc` 认证源后，登录页从 `/api/status` 获取已启用认证源列表；OAuth/OIDC callback 仍回到管理端前端页面，再由前端调用 Server API 完成 code 交换、账号绑定与 Session 建立。
## Agent
`openflare_agent` 是 Go 单体程序：
@@ -51,4 +54,4 @@ Agent 负责首次注册、周期性心跳、配置同步、文件写入、`open
## 核心对象
当前有效实体包括 `proxy_routes`、`origins`、`config_versions`、`nodes`、`apply_logs`、`tls_certificates`、`managed_domains`、`node_request_reports`、`node_access_logs`、`node_metric_snapshots`、`traffic_analytics_rollups` 与 `node_health_events`。
当前有效实体包括 `proxy_routes`、`origins`、`config_versions`、`nodes`、`auth_sources`、`external_accounts`、`apply_logs`、`tls_certificates`、`managed_domains`、`node_request_reports`、`node_access_logs`、`node_metric_snapshots`、`traffic_analytics_rollups` 与 `node_health_events`。
docs/design/development.md
+7
View File
@@ -135,6 +135,8 @@ tests/
* `origins`
* `config_versions`
* `nodes`
* `auth_sources`
* `external_accounts`
* `node_system_profiles`
* `apply_logs`
* `tls_certificates`
@@ -164,6 +166,8 @@ tests/
* `nodes` 只保留控制面状态与低频摘要。
* 观测数据必须按节点与时间窗口关联，快照与聚合结果采用追加式模型。
* 原始访问明细必须有受控保留策略。
* `auth_sources` 仅保存管理端第三方登录源配置，当前支持 `github` 与 `oidc`。
* `external_accounts` 是第三方账号与本地用户的唯一绑定来源；旧 `users.github_id` 仅用于兼容迁移，不得作为新登录流程的业务输入。
## 数据库迁移
@@ -197,6 +201,9 @@ tests/
* 总览与节点详情优先使用专用聚合接口。
* 管理端变更类接口统一使用 `POST`；只读接口使用 `GET`。
* 管理端继续复用现有登录、角色与 Session。
* 第三方登录统一通过认证源 API 进入，认证源管理接口必须要求 Root Session。
* `/api/status` 只能返回已启用认证源的公开字段，不得返回 Client Secret。
* 第三方账号未绑定且注册关闭时，应提供绑定已有账号流程，不得自动创建用户。
* Agent 正式请求统一使用节点专属 `agent_token`。
* 首次接入可使用全局 `discovery_token`。
* Agent 请求头统一使用 `X-Agent-Token`。
docs/design/index.md
+16
View File
@@ -16,6 +16,7 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
| 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 |
| 节点管理 | 节点状态、令牌体系、部署与更新链路 |
| 管理端前端 | 基于 Next.js 的正式管理端 |
| 认证源登录 | 支持以认证源形式配置 GitHub 与标准 OIDC 登录入口，并允许第三方账号绑定已有本地用户 |
默认工作方式：
@@ -31,6 +32,8 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
* `origins`
* `config_versions`
* `nodes`
* `auth_sources`
* `external_accounts`
* `node_system_profiles`
* `apply_logs`
* `tls_certificates`
@@ -80,6 +83,19 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
* 未绑定证书的域名不得被自动带入 HTTPS。
* 必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。
## 认证源约束
`auth_sources` 是管理端第三方登录入口的配置对象，当前仅支持 `github` 与 `oidc` 两类。启用后的认证源会显示在登录页。
`external_accounts` 保存认证源外部账号与本地用户的绑定关系。第三方账号首次登录时：
* 已绑定本地用户则直接登录。
* 当前已有本地登录 Session 时，绑定到当前用户。
* 未绑定且允许注册时，自动创建普通用户并绑定。
* 未绑定且关闭注册时，只允许用户输入已有本地账号密码完成绑定。
旧 `users.github_id` 仅作为升级迁移来源，新的第三方账号登录与绑定关系必须以 `external_accounts` 为准。
## 版本与观测约束
* `config_versions` 必须保存完整快照、渲染结果与 `checksum`。
docs/guide/deployment.md
+28
View File
@@ -93,6 +93,34 @@ go run .
默认监听 `3000` 端口。
## 认证源登录配置
OpenFlare 支持通过认证源配置 GitHub OAuth 或标准 OIDC 登录入口。认证源保存在数据库中，不通过环境变量配置。
配置步骤：
1. 登录管理端，进入“设置 -> 系统设置 -> 配置认证源”。
2. 新增认证源，选择 `GitHub` 或 `OIDC`。
3. 填写 `Name`、展示名称、Client ID、Client Secret。OIDC 还需要填写 Discovery URL。
4. 在第三方平台配置 Redirect URI / Callback URL。
5. 回到 OpenFlare 启用认证源。
回调地址格式固定为：
```text
<OpenFlare 访问地址>/oauth/<认证源 Name>
```
例如 OpenFlare 访问地址为 `https://openflare.example.com`，认证源 `Name` 为 `github`，则第三方平台中应填写：
```text
https://openflare.example.com/oauth/github
```
`Name` 是认证源唯一标识，只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。修改 `Name` 后，第三方平台中的回调地址也必须同步修改。
启用后的认证源会显示在登录页。第三方账号首次登录时，如果已经绑定本地用户会直接登录；如果未绑定且允许注册，会自动创建普通用户；如果未绑定且关闭注册，需要使用已有本地账号完成绑定。
## Swagger
登录管理端后访问：
docs/reference/configuration.md
+32
View File
@@ -78,6 +78,38 @@ go run . --port 3000 --log-dir ./logs
* `DatabaseAutoCleanupEnabled` 开启后，Server 会在每天凌晨 3 点自动清理 `node_access_logs`、`node_metric_snapshots`、`node_request_reports` 三类观测数据。
* `DatabaseAutoCleanupRetentionDays` 为统一保留天数，必须大于等于 1。
* 管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录。
* 第三方登录不再通过 `GitHubOAuthEnabled`、`GitHubClientId`、`GitHubClientSecret` 作为主配置入口；这些旧 Option 仅用于升级时迁移默认 GitHub 认证源。
* 微信登录旧 Option 保留为兼容字段，但管理端不再提供微信登录配置入口。
* Turnstile 旧 Option 与后端校验能力保留，已有配置仍会生效；本版本移除了旧 `OAuth / WeChat / Turnstile` 集成卡片。
## 认证源配置
认证源配置保存在数据库 `auth_sources` 表，由管理端“设置 -> 系统设置 -> 配置认证源”维护，不通过环境变量或启动参数配置。
当前支持：
| 类型 | 必填配置 | 默认 Scope | 说明 |
| --- | --- | --- | --- |
| `github` | Name、Client ID、Client Secret | `user:email` | 使用 GitHub OAuth 登录 |
| `oidc` | Name、Client ID、Client Secret、OIDC Discovery URL | `openid profile email` | 适用于 Logto、authentik 等标准 OIDC Provider |
启用后的认证源会通过 `/api/status` 暴露公开字段并显示在登录页。`Client Secret` 不会通过 API 回显。
`Name` 是认证源的唯一标识，也会作为 OAuth/OIDC 回调路径的一部分。第三方平台中的 Redirect URI / Callback URL 应配置为：
```text
<OpenFlare 访问地址>/oauth/<认证源 Name>
```
例如 OpenFlare 访问地址为 `https://openflare.example.com`，认证源 `Name` 为 `github` 时，回调地址为：
```text
https://openflare.example.com/oauth/github
```
认证源 `Name` 只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。修改 `Name` 后必须同步更新第三方平台中的回调地址。
外部账号绑定保存在 `external_accounts` 表。第三方账号未绑定时，如果允许注册则自动创建普通用户；如果关闭注册，则只能绑定已有本地账号。
## OpenResty 参数
docs/website-configuration-redesign.md
-266
View File
@@ -1,266 +0,0 @@
# 网站配置改造需求与开发计划
## 1. 背景
当前规则模块以“一个域名对应一条规则”为中心，已经支持单域名绑定一个或多个上游，但无法表达“多个域名共享同一套站点配置”的场景。
现阶段已经出现以下真实需求：
* 多个域名指向同一站点，并共享反向代理、缓存等设置，同时允许按域名分别绑定 HTTPS 证书
* 后续希望围绕“网站”继续叠加更多功能，而不是持续在规则列表中堆积字段
* 现有抽屉式编辑界面已经不适合承载更复杂的配置结构
因此，本轮改造将 `proxy_routes` 从“单域名规则”升级为“网站配置”视角，并引入独立的配置子页面。
## 2. 目标
本轮改造的目标如下：
* 支持一个网站绑定多个域名
* 支持一个网站绑定一个或多个上游
* 引入 `site_name` 作为网站业务唯一标识
* 将原列表页的“编辑”操作替换为“配置”，进入独立子页面管理
* 将网站配置拆分为更清晰的功能分区，为后续扩展预留结构
## 3. 本轮范围
本轮仅覆盖以下站点级配置能力：
* 域名设置
* 流量限制
* 反向代理
* 缓存
## 4. 核心模型要求
### 4.1 网站标识
* `site_name` 为网站业务唯一标识
* 新建网站时，若用户未输入 `site_name`，默认取域名列表第一项
* `site_name` 在首次生成后允许独立编辑，不随域名变更自动同步，避免影响引用、跳转和审计
* 数据库内部主键可以继续使用现有数值 `id`，但业务层必须校验 `site_name` 唯一性
### 4.2 域名列表
* 网站的域名字段改为 `domains` 列表
* `domains` 至少包含一个有效域名
* `domains[0]` 视为主域名，用于列表摘要、默认展示和兼容历史逻辑
* 同一网站内域名不能重复
* 任一域名在全局只能属于一个网站
* 域名列表需要支持新增、删除和调整顺序
### 4.3 历史兼容
* 存量单域名数据迁移后应自动转换为：
`site_name = domain`
`domains = [domain]`
* 若迁移期保留旧 `domain` 字段，该字段仅作为 `domains[0]` 的兼容镜像，不再作为主要业务输入
* 版本渲染、差异预览、接口返回和前端展示都应逐步以 `site_name + domains` 为准
## 5. 功能需求
### 5.1 列表页改造
规则列表改造为“网站列表”视图，要求如下：
* 保留当前列表页入口，但展示对象改为网站
* 原“编辑”按钮替换为“配置”按钮
* 点击“配置”进入网站配置子页面
* 列表项至少展示：
`site_name`
主域名
域名数量
上游摘要
HTTPS/缓存/启用状态摘要
* 删除、发布等现有高风险操作仍保留明确确认
### 5.2 网站配置子页面
网站配置采用左右布局：
* 左侧为菜单栏，用于切换配置分区
* 右侧为当前分区的设置面板
* 默认进入“域名设置”分区
* 建议基于 App Router 子路由或稳定的 tab 路由参数实现，保证可直接访问和刷新恢复
建议左侧菜单项固定为：
1. 域名设置
2. 流量限制
3. 反向代理
4. 缓存
为降低跨分区校验干扰，每个分区应支持独立保存与反馈；若采用统一保存，也必须提供未保存修改提示。
### 5.3 域名设置
域名设置分区负责维护网站身份与域名列表，要求如下：
* 可编辑 `site_name`
* 可维护 `domains` 列表
* 可新增、删除、排序域名
* 明确提示第一项为主域名
* 每个域名可单独选择一张证书，形成与 `domains` 平行的 `domain_cert_ids`
* 若某个域名未选择证书，则该域名不启用 HTTPS
* `HTTP -> HTTPS` 跳转逻辑与域名证书绑定放在同一分区维护
* 保存前校验：
`site_name` 非空且唯一
`domains` 非空
每个域名格式合法
域名在当前站点内不重复
域名在全局不与其他网站冲突
已选择证书的域名必须被对应证书覆盖
### 5.4 流量限制
流量限制分区用于配置站点级限流，第一期要求覆盖以下字段：
* `limit_conn perserver`
* `limit_conn perip`
* `limit_rate`
要求如下：
* 采用结构化字段存储，不允许直接录入原始 Nginx 片段
* `limit_conn perserver` 与 `limit_conn perip` 为整数；空值或 `0` 视为未启用
* `limit_rate` 采用人类可读格式录入，例如 `512k`、`1m`
* 保存前进行格式校验，并在页面中提供示例说明
* 配置发布后渲染为对应的 OpenResty/Nginx 指令
### 5.5 反向代理
反向代理分区负责维护网站回源配置，要求如下：
* 支持一个或多个上游
* 至少保留一个上游
* 支持维护回源主机名 `origin_host`
* 继续兼容当前单上游带 path/query、多上游做负载均衡的模式
* 若复用 `origins` 目录，只作为地址候选来源，不改变网站配置为主的编辑模型
建议继续保留当前兼容约束：
* 单上游可附带 path/query
* 多上游模式下，上游项保持 `scheme://host[:port]` 形式
* 同一网站的多个上游在多上游模式下维持统一协议，降低渲染复杂度
### 5.6 缓存
缓存分区负责维护站点级缓存策略，要求如下：
* 支持开启或关闭缓存
* 支持多种缓存策略
* 第一阶段至少兼容当前已存在的策略：
`url`
`suffix`
`path_prefix`
`path_exact`
* 缓存规则继续采用结构化配置，不直接暴露原始 Nginx 片段
* 保持当前安全绕过逻辑，不因界面改造改变默认缓存边界
## 6. 接口与渲染要求
* 列表接口需要返回 `site_name`、`domains`、主域名、状态摘要等字段
* 详情接口需要按分区所需字段返回完整站点配置
* 更新接口需要支持按分区或按网站整体更新，但服务端必须统一做跨字段校验
* 配置 diff 不再只关注单个域名变更，还要能识别：
网站新增/删除
域名列表变更
站点级配置变更
* 发布渲染时，同一网站的全部域名必须落入同一份站点配置上下文中
* 同一网站内，带证书的域名需按证书分组生成 HTTPS `server`；未配置证书的域名只保留 HTTP
## 7. 前端实现要求
* 列表页负责导航与摘要，不再承载完整编辑表单
* 网站配置子页面中的每个分区表单继续遵循 `React Hook Form + Zod`
* API 请求统一收敛在 `lib/api/`
* 站点级数据查询与缓存继续使用 TanStack Query
* 左侧菜单切换时需要明确处理未保存状态，避免无提示丢失修改
* 页面至少覆盖加载态、空态、错误态和保存成功反馈
## 8. 数据迁移要求
实施前必须准备显式数据库迁移与校验逻辑，至少包含：
1. 新增 `site_name`、`domains` 与 `domain_cert_ids` 存储结构
2. 将旧数据从单域名回填到站点结构，并补齐逐域名证书映射
3. 为 `site_name` 建立唯一约束
4. 为域名唯一性建立可校验约束
5. 对迁移结果做一致性校验
迁移失败时，启动流程必须中止，不允许带半迁移状态继续运行。
## 9. 开发计划
### 阶段一：模型与渲染改造
目标：
* 定义网站级 `proxy_routes` 数据结构
* 完成存量数据迁移
* 调整配置渲染与发布链路，支持多域名同站点输出
交付物：
* 数据库迁移
* model/service 调整
* 配置渲染兼容实现
* 迁移与渲染测试
### 阶段二：接口与校验改造
目标：
* 更新列表、详情、创建、更新接口的数据结构
* 引入 `site_name`、`domains`、流量限制等字段校验
* 调整版本 diff 与发布预览语义
交付物：
* API 契约更新
* 服务端参数校验与错误消息
* diff/preview 适配
* 接口回归测试
### 阶段三：前端网站列表与配置子页面
目标：
* 将规则列表切换为网站列表
* 用“配置”按钮替代“编辑”按钮
* 落地左右布局的网站配置子页面与五个分区
交付物：
* 列表页 UI 改造
* 子页面路由与布局
* 域名设置、流量限制、反向代理、缓存四个分区
* 前端交互与表单测试
### 阶段四：联调、发布验证与文档收口
目标：
* 验证从创建网站到发布配置的全链路
* 验证 Agent 拉取、应用与回滚不受影响
* 收口文档与测试
交付物：
* 联调记录
* 发布/回滚回归验证
* 文档同步更新
## 10. 验收标准
满足以下条件后，本专项可视为完成：
* 可以创建一个网站，并绑定多个域名
* 一个网站可以绑定单个或多个上游
* `site_name` 唯一，且创建时默认取第一个域名
* 原列表页已用“配置”按钮替代“编辑”按钮
* 网站配置子页面已经采用左侧菜单、右侧设置的布局
* 五个分区均可独立完成基本配置与保存
* 发布后的渲染结果可正确覆盖同一网站的全部域名，并只为已绑定证书的域名生成 HTTPS 配置
* Agent 同步、应用、回滚链路不被破坏
* 迁移、接口、渲染与前端关键路径均有对应测试或等效回归验证