252 lines
14 KiB
Markdown
252 lines
14 KiB
Markdown
# 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 | [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 | [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**: 基于 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。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
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 # 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 # 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 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 直连，不受备案约束。
|