feat: rebuild xiteng.site homelab platform

2026-08-12 09:48:25 +08:00
parent 557b0eca33
commit 5b84988789
128 changed files with 14979 additions and 292 deletions
@@ -7,17 +7,21 @@
 ```
 公网用户
  │
-  ├─ Web (443) ──→ Cloudflare Tunnel ──→ cloudflared (Docker, HTTP/2)
-  │                                       │
-  └─ SSH (22)  ──→ 阿里云 VPS (frps) ──→ frpc (Docker) ──→ Gitea
-                                           │
-                              Traefik v3.7.1 (反向代理)
-                                    │
-                    ┌───────────────┼───────────────────┐
-                    ▼               ▼                   ▼
-              (有 Authentik SSO)  (ForwardAuth)      (免认证)
-              Gitea / HedgeDoc    SeaweedFS /        Gitea SSH
-              Homepage / OpenWebUI Uptime Kuma
+  ├─ Web (443) ──→ Cloudflare Tunnel ──→ Traefik
+  │                                           │
+  │                         ┌─────────────────┼─────────────────┐
+  │                         ▼                 ▼                 ▼
+  │                    xiteng.site        OAuth2/OIDC       ForwardAuth
+  │                    唯一公开目录       应用层认证          入口层认证
+  │                         │
+  │                         ├─→ Edge Cache Controller ──→ Traefik + Cloudflare Cache Rule
+  │                         ▼
+  │                  Site Registry ──→ Docker API
+  │                         │          (Label + 容器状态)
+  │                         ├─→ HTTP 探测器
+  │                         └─→ SQLite (生命周期 + 历史 + 可用率)
+  │
+  └─ SSH (22) ──→ 阿里云 VPS (frps) ──→ frpc ──→ Gitea
 ```

 | 入口 | 域名 | 传输 | 延迟 |
@@ -25,41 +29,58 @@
 | Web | `*.xiteng.site` | Cloudflare Tunnel (HTTP/2) → Traefik | ~50ms |
 | Git SSH | `git.xiteng.site` | 阿里云 VPS → frp → Gitea | ~5ms |

-## 服务一览
+## 服务与组件目录
+
+[xiteng.site](https://xiteng.site) 是唯一门户。未登录与已登录用户看到相同的服务、基础设施目录及 CPU/MEM/DISK/GPU 实时设备状态；认证只决定能否读取服务数据或执行操作，不用于隐藏组件的存在。
+
+门户不维护硬编码服务清单。Docker 容器通过 `xiteng.site.component.<id>.*` Label 自行声明名称、分组、说明、入口、访问方式和可选的 HTTP 探测。Registry 以组件 ID 为唯一键，统一保存生命周期、检查历史与可用率。Label 规范见 [`site/README.md`](site/README.md)。
+
+服务可另用 `xiteng.site.cache.<id>.*` Label 声明公开静态目录。Edge Cache Controller 将其编译为高优先级 Traefik 路由及一条合并的 Cloudflare Cache Rule；规范和安全边界见 [`edge-cache/README.md`](edge-cache/README.md)。

 | 服务 | 地址 | 认证 | 说明 |
 |------|------|------|------|
-| Homepage | [home.xiteng.site](https://home.xiteng.site) | Authentik OIDC | 导航面板 |
-| Authentik | [auth.xiteng.site](https://auth.xiteng.site) | 自身 | 统一 SSO (v2026.5.0) |
+| Xiteng Site | [xiteng.site](https://xiteng.site) | 无 | 个人主页、服务目录与基础设施目录 |
+| Authentik | 内部 | Portal 管理 | 隐藏的 OAuth2/OIDC、ForwardAuth 与身份数据引擎 (v2026.5.0) |
+| Key Vault | 内网 | Authentik 身份 | 加密 Backend Credential、Provider Registry 与审计 |
 | Gitea | [gitea.xiteng.site](https://gitea.xiteng.site) | Authentik OAuth2 | 代码托管 |
 | HedgeDoc | [notes.xiteng.site](https://notes.xiteng.site) | Authentik OIDC | Markdown 协作 |
-| OpenWebUI | [ai.xiteng.site](https://ai.xiteng.site) | Authentik OIDC | AI 对话界面 (v0.9.5) |
+| Xiteng Chat | [chat.xiteng.site](https://chat.xiteng.site) | Authentik ForwardAuth | assistant-ui 聊天界面，支持双连接 Provider 与跨刷新聊天历史 |
+| Code Server | [code.xiteng.site](https://code.xiteng.site) | Authentik ForwardAuth | 浏览器中的 VS Code 工作台 |
+| ComfyUI | [comfy.xiteng.site](https://comfy.xiteng.site) | Authentik ForwardAuth | 节点式图像生成工作台 |
+| InvokeAI | [invoke.xiteng.site](https://invoke.xiteng.site) | Authentik ForwardAuth | 图像生成、画布编辑与模型管理 |
 | SeaweedFS | [file.xiteng.site](https://file.xiteng.site) | Authentik ForwardAuth | 对象存储 (v4.28) |
-| SeaweedFS S3 | [minio-api.xiteng.site](https://minio-api.xiteng.site) | Access Key | S3 API |
-| Uptime Kuma | [uptime.xiteng.site](https://uptime.xiteng.site) | Authentik ForwardAuth | 服务监控 |
+| SeaweedFS S3 | [s3.xiteng.site](https://s3.xiteng.site) | Access Key | S3 API |
 | Remark42 | [remark.xiteng.site](https://remark.xiteng.site) | Authentik OAuth2 | 评论系统 |
 | Traefik | 内网 | — | 反向代理 |

 > **注意**: SeaweedFS 已替代原 MinIO。域名于 2026-05-27 从 `s3.xiteng.site` 迁移至 `file.xiteng.site`。

-## 认证架构
+## 认证与 Key Vault 架构

 ```
-用户请求 → Cloudflare → cloudflared → Traefik
-                                        │
-                          ┌─────────────┤
-                          ▼             ▼
-                    ForwardAuth     OAuth2/OIDC
-                    (中间件子请求)    (应用层重定向)
-                          │             │
-                          ▼             ▼
-                   Authentik Outpost  Authentik Server
-                   (proxy container)  (Django)
+用户请求 → Cloudflare → cloudflared → Traefik → Authentik
+                                                  │ issuer + sub
+                       ┌──────────────────────────┴─────────────────────────┐
+                       ▼                                                    ▼
+             xiteng.site/account                                     Xiteng Chat
+       Backend Credential / Provider                         assistant-ui / AI SDK
+                       │                                  ┌───────────┴───────────┐
+                       ▼                                  ▼                       ▼
+                   Key Vault                   Backend Provider          Frontend Provider
+             加密存储 / Registry / Audit       Chat 服务端直连             浏览器直接连接
+                                                       │                 IndexedDB Credential
+                                                       └──────────┬──────────────┘
+                                                                  ▼
+                                                             AI Provider
 ```

- **OAuth2/OIDC**: Gitea、HedgeDoc、Homepage、OpenWebUI 各自持有 client_id/secret，用户从应用发起登录
- **ForwardAuth**: SeaweedFS、Uptime Kuma 由 Traefik 中间件在请求到达前拦截验证
- **独立 Outpost**: SeaweedFS 和 Uptime Kuma 各用独立 proxy outpost 容器（避免 cookie domain 冲突）
+- **Authentik**: 隐藏的身份引擎，负责 OAuth2/OIDC、ForwardAuth、用户与策略存储；日常用户、用户组和应用权限管理统一在 `https://xiteng.site/admin`
+- **Key Vault**: 用 Authentik `(issuer, sub)` 关联用户，以 AES-256-GCM 信封加密保存 Backend Credential，并维护 Provider Registry；只有 `xiteng-chat` 服务端解析接口会短暂取得属于当前用户的明文
+- **Xiteng Chat**: 基于 assistant-ui 与 AI SDK；Backend Provider 由 Chat 服务端使用 Key Vault Credential 直连，Frontend Provider 由浏览器使用 IndexedDB 本地 Credential 直连；聊天记录按 Authentik `(issuer, sub)` 隔离并持久化到 `chat/data/chat.db`，不会保存 Credential 明文
+- **Portal**: Authentik ForwardAuth 保护 `/admin` 与 `/account`；`/admin` 只允许 `liooil`，并提供用户、用户组、密码恢复、会话注销和 `liuhome` 应用权限矩阵
+- **公开目录**: `xiteng.site` 不做登录判断，只展示 Label 明确声明的公开元数据；受控服务在点击后执行 Authentik 或服务自身认证
+
+Authentik 数据库、Key Vault 的 `vault_master_key`、Portal HMAC Key 与 Chat 的 `chat/data/chat.db` 必须分别备份，不能放入 Docker Label 或 Git。

 ## 目录结构

@@ -73,6 +94,10 @@ homelab/
 ├── cloudflared/
 │   ├── compose.yml
 │   └── config.yml
+├── edge-cache/
+│   ├── compose.yml          # Docker Label → Traefik/Cloudflare 缓存控制面
+│   ├── controller.mjs       # 动态路由、TTL 与 Cache Rule 生成器
+│   └── README.md            # 静态路径 Label 规范及安全边界
 ├── frpc/
 │   ├── compose.yml
 │   └── frpc.toml            # 敏感，gitignore
@@ -82,15 +107,48 @@ homelab/
 ├── hedgedoc/
 │   ├── compose.yml
 │   └── data/
-├── homepage/
+├── site/
 │   ├── compose.yml
-│   └── config/
-├── openwebui/
+│   ├── index.html           # 页面结构，不包含服务清单
+│   ├── admin.html           # 用户、权限、Vault 与生命周期管理页
+│   ├── styles.css
+│   ├── app.js               # 动态渲染组件卡片
+│   ├── server.mjs           # 公网站点与同源 API
+│   ├── registry.mjs         # Label 发现、HTTP 探测与生命周期控制面
+│   ├── import-kuma.mjs      # 一次性旧历史迁移工具
+│   ├── metrics.py           # 只读主机与 NVIDIA GPU 指标
+│   ├── data/                # Registry SQLite，gitignore
+│   └── README.md            # 组件 Label 规范
+├── ai-gateway/             # 内部 Key Vault 服务（保留目录名以避免数据路径迁移）
 │   ├── compose.yml
-│   ├── .env                 # OPENWEBUI_SECRET_KEY
-│   └── data/                # gitignore
+│   ├── vault.mjs            # 信封加密、所有权、Provider Registry 与审计
+│   ├── providers.json       # 内置 Provider Catalog
+│   ├── providers.mjs        # Provider 校验与合并
+│   ├── server.mjs
+│   └── data/                # Vault SQLite，gitignore
+├── homelab-emergency        # Authentik 与 Vault 本机恢复入口
+├── chat/
+│   ├── app/                 # Next.js 页面与流式聊天 API
+│   ├── components/          # assistant-ui 线程与页面壳层
+│   ├── data/                # 用户聊天历史 SQLite，gitignore
+│   ├── Dockerfile
+│   └── compose.yml          # chat.xiteng.site / Authentik ForwardAuth
+├── code-server/
+│   ├── compose.yml
+│   ├── .env                 # 本地 UID/GID 等环境变量，gitignore
+│   ├── config/              # VS Code Server 配置，gitignore
+│   └── local/               # 扩展与用户本地数据，gitignore
+├── comfyui/
+│   ├── compose.yml
+│   ├── compose.gpu.yml       # 可选 NVIDIA GPU override
+│   ├── models/              # gitignore
+│   ├── custom_nodes/        # gitignore
+│   └── output/              # gitignore
+├── invokeai/
+│   ├── compose.yml
+│   └── data/                # gitignore，模型、配置和生成结果
 ├── outpost/
-│   ├── compose.yml          # Uptime Kuma outpost
+│   ├── compose.yml          # Portal Admin / ComfyUI / InvokeAI outpost
 │   └── ...
 ├── outpost-seaweedfs/
 │   └── compose.yml          # SeaweedFS 独立 outpost
@@ -101,12 +159,9 @@ homelab/
 │   ├── compose.yml
 │   ├── security.toml        # JWT 已全部注释（社区版 UI 不支持 OIDC）
 │   └── data/
-├── traefik/
-│   ├── compose.yml
-│   └── letsencrypt/         # gitignore
-└── uptime-kuma/
+└── traefik/
    ├── compose.yml
-    └── data/
+    └── letsencrypt/         # gitignore
 ```

 ## 网络
@@ -118,21 +173,71 @@ homelab/
 ```bash
 # 按依赖顺序启动
 docker compose -f compose.yml up -d          # 创建网络
+docker compose -f edge-cache/compose.yml up -d
 docker compose -f traefik/compose.yml up -d
 docker compose -f authentik/compose.yml up -d
 docker compose -f gitea/compose.yml up -d
 docker compose -f hedgedoc/compose.yml up -d
 docker compose -f seaweedfs/compose.yml up -d
-docker compose -f uptime-kuma/compose.yml up -d
-docker compose -f homepage/compose.yml up -d
-docker compose -f openwebui/compose.yml up -d
+./homelab-emergency init-secrets
+./homelab-emergency identity-bootstrap
+docker compose -f ai-gateway/compose.yml up -d
+docker compose -f site/compose.yml up -d
+docker compose -f chat/compose.yml up -d --build
+docker compose --env-file code-server/.env -f code-server/compose.yml up -d
+docker compose -f comfyui/compose.yml up -d
+docker compose -f invokeai/compose.yml up -d
 docker compose -f remark42/compose.yml up -d
-docker compose -f outpost/compose.yml up -d
+docker compose --env-file .env -f outpost/compose.yml up -d
 docker compose -f outpost-seaweedfs/compose.yml up -d
 docker compose -f cloudflared/compose.yml up -d
 docker compose -f frpc/compose.yml up -d
 ```

+
+## 最终恢复入口
+
+日常身份管理位于 `https://xiteng.site/admin`。Authentik 原生管理界面已隐藏；根目录的
+`homelab-emergency` 提供不依赖 Portal 的恢复能力：
+
+```bash
+./homelab-emergency status
+./homelab-emergency identity-recovery liooil
+./homelab-emergency identity-set-password liooil
+./homelab-emergency identity-reset-2fa liooil
+./homelab-emergency identity-reset-passkeys liooil
+./homelab-emergency identity-bootstrap
+./homelab-emergency vault-list
+./homelab-emergency vault-audit 100
+./homelab-emergency vault-delete <credential-id>
+./homelab-emergency vault-backup ai-gateway/data/backups/vault.db
+```
+
+`identity-bootstrap` 保证 `liooil` 是唯一人类管理员、`liooil` 与 `ziyue` 属于 `liuhome`，
+并将当前非开放应用的准入用户组统一为 `liuhome`。`identity-reset-2fa` 与
+`identity-reset-passkeys` 需要交互确认，只删除指定用户的认证器并写入身份审计。应急脚本不输出
+Provider Key、TOTP Secret 或 Passkey 凭据明文。
+
+Homepage、Beszel、Uptime Kuma 和 AutoKuma 已退役。它们不再有活动 Compose 定义；现有 `homepage/config/`、`beszel/data/` 与 `uptime-kuma/data/` 仅作为迁移后的回滚数据保留，不会被 Portal 或启动流程读取。
+
+code-server 将当前仓库挂载到 `/home/coder/homelab`，并持久化 VS Code 配置与扩展到
+`code-server/config/` 和 `code-server/local/`。公网入口必须保持 Authentik ForwardAuth 保护；
+code-server 内置密码认证已关闭，避免重复登录。默认不挂载 Docker socket，如需从浏览器终端管理
+Docker，应改用更窄的专用运维入口。
+
+ComfyUI 默认配置不要求 Docker GPU runtime，模型、Custom Nodes 和生成结果分别持久化到 `comfyui/models/`、`comfyui/custom_nodes/`、`comfyui/output/`。ComfyUI Manager 可安装第三方节点，公网入口必须保持 Authentik ForwardAuth 保护。
+
+启用 NVIDIA GPU 前，先在宿主安装并配置 NVIDIA Container Toolkit，然后用 override 启动：
+
+```bash
+sudo pacman -S --needed nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+docker compose -f comfyui/compose.yml -f comfyui/compose.gpu.yml up -d
+```
+
+InvokeAI 使用 NVIDIA GPU，模型、配置和生成结果统一持久化到 `invokeai/data/`。公网入口必须保持 Authentik ForwardAuth 保护；首次进入后在 Model Manager 中安装需要的模型。
+
 ## 所需外部资源

 | 资源 | 用途 |