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 是唯一门户。未登录与已登录用户看到相同的服务、基础设施目录及 CPU/MEM/DISK/GPU 实时设备状态；认证只决定能否读取服务数据或执行操作，不用于隐藏组件的存在。
门户不维护硬编码服务清单。Docker 容器通过 xiteng.site.component.<id>.* Label 自行声明名称、分组、说明、入口、访问方式和可选的 HTTP 探测。Registry 以组件 ID 为唯一键，统一保存生命周期、检查历史与可用率。Label 规范见 site/README.md。
服务可另用 xiteng.site.cache.<id>.* Label 声明公开静态目录。Edge Cache Controller 将其编译为高优先级 Traefik 路由及一条合并的 Cloudflare Cache Rule；规范和安全边界见 edge-cache/README.md。
| 服务 | 地址 | 认证 | 说明 |
|---|---|---|---|
| Xiteng Site | xiteng.site | 无 | 个人主页、服务目录与基础设施目录 |
| Authentik | 内部 | Portal 管理 | 隐藏的 OAuth2/OIDC、ForwardAuth 与身份数据引擎 (v2026.5.0) |
| Key Vault | 内网 | Authentik 身份 | 加密 Backend Credential、Provider Registry 与审计 |
| Gitea | gitea.xiteng.site | Authentik OAuth2 | 代码托管 |
| HedgeDoc | notes.xiteng.site | Authentik OIDC | Markdown 协作 |
| Xiteng Chat | xiteng.site/chat | Authentik ForwardAuth | Vanilla TypeScript + Bun 聊天界面，支持 Backend/Frontend Provider 与跨刷新聊天历史 |
| Code Server | code.xiteng.site | Authentik ForwardAuth | 浏览器中的 VS Code 工作台 |
| ComfyUI | comfy.xiteng.site | Authentik ForwardAuth | 节点式图像生成工作台 |
| InvokeAI | invoke.xiteng.site | Authentik ForwardAuth | 图像生成、画布编辑与模型管理 |
| CAT-BODHI | cat-bodhi.xiteng.site | 无 | 门户中的固定上游版本游戏与 Sprite 模型服务 |
| SeaweedFS | file.xiteng.site | Authentik ForwardAuth | 对象存储 (v4.28) |
| SeaweedFS S3 | s3.xiteng.site | Access Key | S3 API |
| Remark42 | 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 网络，通过容器名互访，不暴露端口到宿主机。
快速启动
# 按依赖顺序启动
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 的恢复能力：
./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 启动：
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 直连，不受备案约束。