# Homelab

部署在 CachyOS 上的全套家庭服务，通过 Cloudflare Tunnel + 阿里云 VPS SSH 中转向公网开放。

## 架构

```
公网用户
  │
  ├─ 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
```

| 入口 | 域名 | 传输 | 延迟 |
|------|------|------|:--:|
| 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)。

| 服务 | 地址 | 认证 | 说明 |
|------|------|------|------|
| 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 协作 |
| Xiteng Chat | [xiteng.site/chat](https://xiteng.site/chat/) | Authentik ForwardAuth | Vanilla TypeScript + Bun 聊天界面，支持 Backend/Frontend 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 | 图像生成、画布编辑与模型管理 |
| CAT-BODHI | [cat-bodhi.xiteng.site](https://cat-bodhi.xiteng.site) | 无 | 门户中的固定上游版本游戏与 Sprite 模型服务 |
| SeaweedFS | [file.xiteng.site](https://file.xiteng.site) | Authentik ForwardAuth | 对象存储 (v4.28) |
| 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 → 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
```

- **Authentik**: 隐藏的身份引擎，负责 OAuth2/OIDC、ForwardAuth、用户与策略存储；日常用户、用户组和应用权限管理统一在 `https://xiteng.site/admin`
- **Key Vault**: 用 Authentik `(issuer, sub)` 关联用户，以 AES-256-GCM 信封加密保存 Backend Credential，并维护 Provider Registry；只有 `xiteng-chat` 服务端解析接口会短暂取得属于当前用户的明文
- **Xiteng Chat**: 基于 Vanilla TypeScript、Bun 与 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。

## 目录结构

```
homelab/
├── compose.yml              # 共享网络定义 (homelab_net)
├── .env                     # 统一环境变量（敏感，gitignore）
├── authentik/
│   ├── compose.yml
│   └── data/
├── 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
├── gitea/
│   ├── compose.yml
│   └── data/
├── hedgedoc/
│   ├── compose.yml
│   └── data/
├── site/
│   ├── compose.yml
│   ├── 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
│   ├── 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          # xiteng.site/chat / 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，模型、配置和生成结果
├── cat-bodhi/
│   ├── compose.yml          # 独立域名部署与门户组件标签
│   ├── Dockerfile           # 固定并校验 CAT-BODHI 上游归档
│   └── data/                # gitignore，生成资源与 Sprite 输出
├── outpost/
│   ├── compose.yml          # Portal Admin / ComfyUI / InvokeAI outpost
│   └── ...
├── outpost-seaweedfs/
│   └── compose.yml          # SeaweedFS 独立 outpost
├── remark42/
│   ├── compose.yml
│   └── var/                 # gitignore
├── seaweedfs/
│   ├── compose.yml
│   ├── security.toml        # JWT 已全部注释（社区版 UI 不支持 OIDC）
│   └── data/
└── traefik/
    ├── compose.yml
    └── letsencrypt/         # gitignore
```

## 网络

所有服务加入 `homelab_net` 自定义 bridge 网络，通过容器名互访，不暴露端口到宿主机。

## 快速启动

```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
./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 cat-bodhi/compose.yml up -d --build
docker compose -f remark42/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 中安装需要的模型。

## 所需外部资源

| 资源 | 用途 |
|------|------|
| Cloudflare DNS | 域名托管 + Tunnel |
| 阿里云 ECS (上海) | Git SSH 中转 (frps) |
| Cloudflare Tunnel | Web 流量入口 |

## 备案说明

所有 Web 流量走 Cloudflare Tunnel（境外边缘终止 TLS），域名未备案。SSH 通过阿里云 IP 直连，不受备案约束。