liooil/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
agent/chat-settings-redesign
homelab/README.md
T

14 KiB
Raw Permalink Blame History

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 图像生成、画布编辑与模型管理
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，模型、配置和生成结果
├── 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 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 直连，不受备案约束。

Reference in New Issue View Git Blame Copy Permalink