docs: 记录 Hydra 人类登录 PoC 部署与验收边界

architecture/constraints.md

@@ -1,6 +1,6 @@
 # 架构约束索引
 
-审阅日期：2026-09-24。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的
+审阅日期：2026-09-25。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的
 已接受设计，其余来源路径相对于 homelab-infra。修改时必须读原文和对应代码，新出现的差异
 先向维护者确认；[首轮状态对齐](../verification.md)已完成。
 
@@ -16,7 +16,7 @@
 | OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` |
 | Terraform 管 API 配置，Ansible 管主机及不能安全纳管的密钥材料 | 不可读回秘密和根密钥不能靠反复重建实现收敛 | `infrastructure/openbao/README.md` |
 | LAN HTTP 入口为 Envoy Gateway；新增服务核对 parentRefs、DNS 和认证 | 不直接套用 archive 中的 Gateway 示例 | `platform/envoy-gateway/README.md`、`AGENTS.md` |
-| 人类身份由 Samba AD / Authelia 提供，Authelia 是 active 的唯一主 OIDC broker；workload 身份由 SPIRE 提供 | 身份签发不等于资源授权；SPIRE 基础设施与最小 PoC 已完成，后续集成以 #34 为准 | [Authelia](../services/authelia.md)、[SPIRE 状态与依据](../services/spire.md) |
+| 人类认证仍由 Samba AD / Authelia 提供；Hydra 作为 Gitea 的实验性签发入口，通过 OIDC 复用 Authelia；workload 身份由 SPIRE 提供 | 2026-09-25 第一轮人类 PoC 扩展了原单 broker 接入边界，未迁移主入口、机器身份或应用权限 | [Authelia](../services/authelia.md)、[Hydra PoC](../services/hydra.md)、[SPIRE](../services/spire.md) |
 | SPIFFE 提供跨基础设施的统一机器身份入口，替代 workload-sts 统一 IAM 平台方案 | 服务信任 SPIFFE 身份、签发自己的 token 并维护自身权限；非 Kubernetes 身份不依赖 Kubernetes ServiceAccount，优先复用服务现有接入机制 | [核心设计与取舍](../services/spire.md#核心设计与取舍)，维护者于 2026-09-16 补充 |
 | 已由 Flux 接管的资源通过 Git 修改；brownfield 不全局开启 prune | 防止漂移回滚与误删；未接管资源不能假定受 Flux 管理 | `clusters/homelab/README.md` |
 | DNS 各视图保留权威边界；只管理明确声明的 RRset | 不清理 Samba 自动维护的域记录；LAN 现状按维护者说明对齐，旧源码文档待同步 | `infrastructure/dns/README.md`、[LAN DNS](../services/lan-dns.md) |
@@ -35,4 +35,5 @@
 
 [独立 IAM 与 agent 身份草案](independent-iam-draft.md)（2026-09-25，draft）提出以 Hydra
 解耦认证与签发，通过 OIDC 接入人类、machine 和 agent，并作为 Ayatori 的独立外部依赖。
-它尚未替代上表的人类身份、SPIFFE 或 DNS 约束；采纳时须显式修订这些边界。
+完整方案仍为草案。2026-09-25 已按维护者要求先实施人类登录 PoC，上表显式记录其有限
+变更；SPIFFE、agent 动态授权、组模型及 DNS 迁移未随之实施。

architecture/independent-iam-draft.md

@@ -9,8 +9,10 @@ sources:
 
 # 独立 IAM 草案：人类、机器与 AI Agent 的统一应用接入
 
-本页记录设计意图，状态为 **draft**；尚未采纳为现役架构，也未部署或完成端到端验证。
-名称、资源模型、接口及具体实现均未定。本次仅整理讨论，不表示已启动迁移。
+本页记录完整 IAM 的设计意图，状态仍为 **draft**。2026-09-25 维护者随后选择先实施
+[Hydra 人类登录 PoC](../services/hydra.md)：通用 OIDC 上游适配器暂用 Authelia，Gitea
+新增 Hydra 登录源；真实人类登录仍待验收。这不表示完整方案已采纳或开始全面迁移。
+长期名称、资源模型及 agent 接口尚未确定。
 
 ## 动机与首要目标
 
@@ -140,7 +142,8 @@ AD 存续期间保留其域记录权威与动态更新边界；普通记录的
 
 现役记录仍以 [架构约束](constraints.md)、[Authelia](../services/authelia.md) 和
 [SPIFFE/SPIRE](../services/spire.md) 为准。当前文档中的 Authelia 主 OIDC 入口、
-服务直接验证 SPIFFE 后签发自身 token 的规则，未因本草案而被替换。
+服务直接验证 SPIFFE 后签发自身 token 的规则，仍是现役基础。第一轮人类 PoC 对
+Gitea 增加实验性 Hydra 签发入口的有限变更已在约束索引中单独记录。
 
 本草案提出的变化是：增加独立的多主体 IAM，通过 Hydra 解耦认证与签发，让尚不支持
 SPIFFE 的下游复用 OIDC；并为 agent 增加区别于传统 service account 的身份授权语义。

guides/task-index.md

@@ -10,7 +10,7 @@ last_reviewed: 2026-09-25
 
 | 要做什么 | 先读 | 需要时再读 |
 |---|---|---|
-| 评估独立 IAM 与 AI agent 身份 | [独立 IAM 草案](../architecture/independent-iam-draft.md) | 草案未替代现役身份架构；下游以 OIDC/OAuth 接入 |
+| 评估独立 IAM 与 AI agent 身份 | [独立 IAM 草案](../architecture/independent-iam-draft.md) | [Hydra 人类登录 PoC](../services/hydra.md)；完整 IAM 仍为草案 |
 | 设计或实现 Ayatori 控制面能力 | [Ayatori 控制面边界](../architecture/ayatori-control-plane.md) | Ayatori 仓库 ADR、对应领域 API 与 adapter 文档 |
 | 发布新的 LAN Web 服务 | [发布新服务](publish-service.md) | [DNS](../services/lan-dns.md)、[Authelia](../services/authelia.md) |
 | 写 CI 或选择 Pod/VM runner | [Gitea / Actions](../services/gitea.md) | [Dynamic Runner](../services/gitea-dynamic-runner.md)、[SPIFFE](../services/spire.md)、[`ci-actions@v1`](https://git.ddupan.top/panxiao81/ci-actions/src/tag/v1) |

services/authelia.md

@@ -2,7 +2,7 @@
 title: Authelia
 lifecycle: active
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-25
 last_verified: null
 sources:
   - 维护者于 2026-09-16 确认当前状态
@@ -10,8 +10,10 @@ sources:
 
 # Authelia
 
-**Authelia 已作为 homelab 唯一的主 OIDC broker 工作，当前状态为 active。**
-此状态由维护者于 2026-09-16 明确，本轮未查询运行环境。
+**Authelia 继续作为 homelab 的主 OIDC 入口与人类认证后端工作，状态为 active。**
+基础状态由维护者于 2026-09-16 明确。2026-09-25 新增 [Hydra 人类登录 PoC](hydra.md)，
+以标准 OIDC client 复用 Authelia；其原有应用客户端、Samba AD 后端及 MFA 策略保留。
+该次仅验证新增配置有效和 Pod 就绪，未更新本页原有功能的整体验收日期。
 
 ## 用途与入口
 

services/gitea.md

@@ -2,7 +2,7 @@
 title: Gitea 与 Actions 使用指南
 lifecycle: active
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-25
 last_verified: null
 ---
 
@@ -23,6 +23,12 @@ Gitea 托管 homelab 的代码、文档、issue 和 PR；Actions 执行仓库声
 登录成功但看不到仓库时，先确认当前账号与仓库权限；OIDC 登录本身不会赋予所有项目的管理权。
 已有账号应沿用原账号关联，遇到关联问题交由管理员处理，不另建同名账号规避。
 
+## Hydra 实验性登录
+
+2026-09-25 按维护者要求新增 [Hydra 人类登录 PoC](hydra.md)，保留旧 Authelia 登录源。
+从 <https://git.ddupan.top/user/oauth2/hydra> 发起，需 LAN/Tailscale 连通 Hydra 内网入口。
+最终认证仍在 Authelia 完成；真实账号返回和权限验收结果见 Hydra 服务页。
+
 ## 创建与修改仓库
 
 通过页面的 New Repository 创建仓库，选择所属用户或组织、名称及可见性。

services/hydra.md

@@ -0,0 +1,76 @@
+---
+title: Hydra 与 OIDC 上游适配器
+lifecycle: experimental
+evidence: live-verified
+last_reviewed: 2026-09-25
+last_verified: 2026-09-25
+sources:
+  - https://git.ddupan.top/panxiao81/homelab-infra/pulls/142
+  - https://git.ddupan.top/panxiao81/homelab-infra/pulls/143
+  - 2026-09-25 部署、discovery、重定向与网络隔离检查
+---
+
+# Hydra 与 OIDC 上游适配器
+
+第一轮人类登录 PoC：Hydra 负责 OIDC 签发，薄的 Login/Consent 服务通过标准 OIDC
+验证上游身份。当前配置的上游是 Authelia，它继续连接 Samba AD 并执行人类 MFA。
+适配器没有直接连接 LDAP，也不与 Authelia 专有认证协议绑定。
+
+本服务独立于 Ayatori。当前代码作为 homelab-infra 中的独立 Go module 保存，未新建
+独立仓库。完整的多主体 IAM 仍是[草案](../architecture/independent-iam-draft.md)；
+本轮不实现 SPIFFE 登录、agent 专用认证、动态授权或统一组迁移。
+
+## 入口与首次使用
+
+| 入口 | 用途 |
+|---|---|
+| <https://hydra.ad.ddupan.top> | Hydra 公共 OAuth2/OIDC API |
+| <https://hydra-login.ad.ddupan.top> | Login/Consent 适配器，仅处理具体流程路径 |
+| <https://git.ddupan.top/user/oauth2/hydra> | 从 Gitea 发起 Hydra 人类登录 |
+
+Hydra 两个域名仅通过 LAN/Tailscale 可达，无公网 tunnel。请从 Gitea 的 `hydra`
+登录源进入，在 Authelia 完成既有认证，然后返回 Gitea；旧 `authelia` 登录源保留。
+Gitea 继续按原有账号关联、仓库权限与 gitea-admins 组映射执行授权。
+
+```text
+Gitea → Hydra → OIDC Login/Consent → Authelia → Samba AD
+      ← OIDC ← 已验证的人类身份 ← OIDC callback
+```
+
+## 验证范围
+
+2026-09-25 已现场验证：Hydra 数据库迁移成功、两个 Deployment 就绪、ESO SecretSynced、
+TLS discovery 的 issuer/endpoints 正确、Flux hydra Kustomization Ready/Healthy；
+HTTP 登录链路可从 Hydra 经适配器到达 Authelia 登录页。
+
+无效 login、callback、consent 请求返回 403。Gitea Pod 能访问公共 discovery，不能
+直连 Hydra admin Service；公共 HTTPS 入口的 admin API 返回 404。
+
+**以上不等于已完成人类端到端登录验收。** Gitea 的新增登录源经 PR #143 接入，Helm revision 19 UpgradeSucceeded、Pod Ready；
+登录页同时显示 hydra/authelia，从真实 Gitea 入口到达 Authelia 的整段跳转已验证。
+人类实际完成 MFA、回到原 Gitea 账号及权限的结果仍待确认。
+`last_verified` 仅覆盖上述明确列出的基础设施与协议入口检查。
+
+## 实现与维护
+
+- Hydra 固定 `v26.2.0` 与镜像 digest，使用独立 hydra PostgreSQL database/role。
+- 源码 `apps/hydra/login-consent`：标准 OIDC 上游适配器。校验 ID token issuer、audience、
+  签名、有效期和 nonce，使用 PKCE S256 与单次、cookie 绑定的 state。
+- 当前只允许 Gitea client 和 openid/profile/email/groups；按请求 scope 释放 claims，
+  不签发 refresh token，不提供通用自动 consent。主体为上游 issuer/sub 的稳定哈希。
+- 单副本短期登录事务保存在内存；重启使正在进行的登录失效，用户重新发起即可。
+- Hydra admin 无 HTTPRoute，NetworkPolicy 仅允许适配器访问；维护时通过受控本地
+  kubectl port-forward，不对外开放 admin。
+- 秘密保存在 OpenBao `kv/k8s/hydra`，ESO 投射给 Hydra/适配器和 Gitea。禁止重建
+  system_secret 来处理普通启动问题。
+- Authelia 的新 hydra-login client 通过现有 Helm release 的增量 values 更新，保留全部
+  已有客户端与 two_factor 策略；Authelia 暂未由 Flux 接管。
+
+源码、构建、claims/client 配置和恢复说明见
+[Hydra README](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/apps/hydra/README.md)。
+Hydra 部署见 [PR #142](https://git.ddupan.top/panxiao81/homelab-infra/pulls/142)，
+Gitea 接入见 [PR #143](https://git.ddupan.top/panxiao81/homelab-infra/pulls/143)。
+
+依赖共享 PostgreSQL、OpenBao/ESO、Authelia、Envoy、Samba DNS 与 zot。独立于 Ayatori
+不等于已完成共享基础设施之外的灾备；恢复需保留 Hydra 数据库和秘密。
+回退时先撤 Gitea 新登录源，沿用旧 Authelia 入口，不删除用户或原有认证配置。

services/index.md

@@ -14,6 +14,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 
 | 组件 | 用途 | 记录入口 | 状态依据 | 来源 | 文档缺口 / 下一步 |
 |---|---|---|---|---|---|
+| [hydra](hydra.md) | OIDC 签发与通用上游适配器，人类登录 PoC | `hydra.ad.ddupan.top / hydra-login.ad.ddupan.top` | experimental；9 月 25 日基础设施与到达 Authelia 的跳转已验证，真实登录待确认 | `apps/hydra/`、PR #142/#143 | 完成人类 Gitea 登录验收 |
 | [authelia](authelia.md) | 唯一主 OIDC broker、统一登录 | `auth.ddupan.top` | active；维护者于 2026-09-16 明确已在工作 | 维护者说明、`apps/authelia/` | 同步源码 README 中过时的 OIDC 阶段说明 |
 | [blocky](lan-dns.md) | LAN 主 DNS、广告过滤、分流 | `192.168.10.127:53` | 维护者说明已作为 DHCP 主 DNS，上游为路由器 | 维护者 2026-09-16 说明、`apps/blocky/README.md` | 无需逐台确认主机；旧源码说明待同步 |
 | [gitea](gitea.md) | 代码托管与 Actions | `git.ddupan.top` | 记录已部署 | `apps/gitea/README.md` | 已有登录、最小 CI 与 runner 选择指南 |