homelab/README.md

# Homelab

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

## 架构

```
公网用户
  │
  ├─ 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 | `*.xiteng.site` | Cloudflare Tunnel (HTTP/2) → Traefik | ~50ms |
| Git SSH | `git.xiteng.site` | 阿里云 VPS → frp → Gitea | ~5ms |

## 服务一览

| 服务 | 地址 | 认证 | 说明 |
|------|------|------|------|
| Homepage | [home.xiteng.site](https://home.xiteng.site) | Authentik OIDC | 导航面板 |
| Authentik | [auth.xiteng.site](https://auth.xiteng.site) | 自身 | 统一 SSO (v2026.5.0) |
| 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) |
| 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 | 服务监控 |
| Remark42 | [remark.xiteng.site](https://remark.xiteng.site) | Authentik OAuth2 | 评论系统 |
| Traefik | 内网 | — | 反向代理 |

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

## 认证架构

```
用户请求 → Cloudflare → cloudflared → Traefik
                                        │
                          ┌─────────────┤
                          ▼             ▼
                    ForwardAuth     OAuth2/OIDC
                    (中间件子请求)    (应用层重定向)
                          │             │
                          ▼             ▼
                   Authentik Outpost  Authentik Server
                   (proxy container)  (Django)
```

- **OAuth2/OIDC**: Gitea、HedgeDoc、Homepage、OpenWebUI 各自持有 client_id/secret，用户从应用发起登录
- **ForwardAuth**: SeaweedFS、Uptime Kuma 由 Traefik 中间件在请求到达前拦截验证
- **独立 Outpost**: SeaweedFS 和 Uptime Kuma 各用独立 proxy outpost 容器（避免 cookie domain 冲突）

## 目录结构

```
homelab/
├── compose.yml              # 共享网络定义 (homelab_net)
├── .env                     # 统一环境变量（敏感，gitignore）
├── authentik/
│   ├── compose.yml
│   └── data/
├── cloudflared/
│   ├── compose.yml
│   └── config.yml
├── frpc/
│   ├── compose.yml
│   └── frpc.toml            # 敏感，gitignore
├── gitea/
│   ├── compose.yml
│   └── data/
├── hedgedoc/
│   ├── compose.yml
│   └── data/
├── homepage/
│   ├── compose.yml
│   └── config/
├── openwebui/
│   ├── compose.yml
│   ├── .env                 # OPENWEBUI_SECRET_KEY
│   └── data/                # gitignore
├── outpost/
│   ├── compose.yml          # Uptime Kuma 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
└── uptime-kuma/
    ├── compose.yml
    └── data/
```

## 网络

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

## 快速启动

```bash
# 按依赖顺序启动
docker compose -f 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
docker compose -f remark42/compose.yml up -d
docker compose -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
```

## 所需外部资源

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

## 备案说明

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