OIDC

docs/design/architecture.md

@@ -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

@@ -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,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`。