# HomeLab & Cloud-Edge Architecture Memory (`GEMINI.md`)

本文件为 `agy` (Antigravity CLI) 的**全局持久上下文记忆文件**。无论在 M5 MacBook Air 还是 M6 Mac mini 网页端 (`https://agy.961504.xyz`) 启动新会话，均自动加载本架构规范。

---

## 1. 交互与工作准则
1. **汇报 + 确认机制**：每次架构变更或较大改动前，先说明方案，再执行；代码与基础设施配置统一维护在 Git 仓库 [`/Users/ixvii0iv/homelab`](file:///Users/ixvii0iv/homelab) 并同步至 `mini:~/homelab`。
2. **代码链接规范**：回答中涉及所有文件路径或代码符号时，必须使用可点击的 Markdown 链接（如 `[TopRibbon.tsx](file:///Users/ixvii0iv/homelab/stacks/portal/web/src/components/TopRibbon.tsx)`）。

---

## 2. 核心硬件与网络拓扑（4 大节点）

| 节点角色 | 设备型号 / 系统 | 局域网 / 公网 IP | Tailscale 专线 IP | SSH 快捷别名 | 核心职责 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **随身开发机** | Apple M5 MacBook Air (macOS) | `192.168.31.83` | `100.89.152.95` | 本机 | 日常主力操作终端、本地 Git 仓库源头 |
| **家庭计算核心** | Apple M6 Mac mini (24GB RAM, 460GB SSD) | `192.168.31.164` | `100.108.205.40` | `ssh mini` / `ssh mini-ts` | 7×24h All-in-One 服务器、OrbStack 容器宿主机、AGY 网页端宿主、Tailscale 子网路由 (`192.168.31.0/24`) |
| **家庭存储中心** | 极空间 Z4 (20TB RAID) | `192.168.31.185` | 经 Mac mini 子网路由可达 | Web `5055` / SMB `445` | 20TB 大容量冷热存储、通过 LaunchAgent 自动 SMB 挂载至 Mac mini `~/nas/{共享文件,个人空间}` |
| **家庭主路由** | 小米路由器 (开启 SSH + ShellCrash/Mihomo) | `192.168.31.1` (联通公网 `124.90.142.21`) | 经 Mac mini 子网路由可达 | `ssh root@192.168.31.1` | PPPoE 拨号、端口转发 (`10443`/`41641` -> `192.168.31.164`)、内网 Split-DNS、锁定 AI 流量走狮城节点 |
| **海外云端前哨** | 新加坡 Azure VM (Ubuntu 24.04) | `104.43.105.243` | `100.115.204.51` | `ssh azure` | 443 免端口公网 HTTPS 反向代理入口、AI 算力固定出口、Uptime Kuma 外部独立监控哨兵 |

---

## 3. 域名与双通道访问矩阵 (`961504.xyz`)

### 通道 A：443 免端口标准 HTTPS（经新加坡 Azure Caddy -> Tailscale P2P 回源）
- **导航中控台 (HomeLab Console V3)**: `https://nav.961504.xyz` -> `100.108.205.40:3002`
- **Storybook 设计系统工作台**: `https://nav.961504.xyz/storybook` -> `100.108.205.40:3002/storybook`
- **AGY 云端编程工作台 (`ttyd` + `tmux`)**: `https://agy.961504.xyz` -> `100.108.205.40:7681` (受 Basic Auth 保护)
- **Vaultwarden 密码保险箱**: `https://vw.961504.xyz` -> `100.108.205.40:8222`
- **Uptime Kuma 外部监控哨兵**: `https://status.961504.xyz` -> `127.0.0.1:3001` (Azure 本地容器)

### 通道 B：10443 家庭宽带公网直连 & 局域网 Split-DNS 秒开（Mac mini Caddy Wildcard TLS）
- 在家连 Wi-Fi 时，小米路由器 Mihomo 将 `home.961504.xyz` 与 `*.home.961504.xyz` 直接解析为 `192.168.31.164`（并在 `fake_ip_filter` 中豁免 Fake-IP），实现 <1ms 局域网直连。
- 在外网时，Cloudflare DNS 将 `*.home.961504.xyz` 动态解析至家庭联通公网 IP (`124.90.142.21`)，通过路由器 `10443` 端口转发直达 Mac mini Caddy：
  - `https://home.961504.xyz:10443` (HomeLab Console V3)
  - `https://agy.home.961504.xyz:10443` (AGY 云端工作台)
  - `https://vw.home.961504.xyz:10443` (Vaultwarden)
  - `https://nas.home.961504.xyz:10443` (极空间 Z4 Web `192.168.31.185:5055`)
  - `https://clash.home.961504.xyz:10443` (路由器 Mihomo 面板 `192.168.31.1:9999`)
  - `https://router.home.961504.xyz:10443` (小米路由器后台 `192.168.31.1:80`)
  - `https://status.home.961504.xyz:10443` (Uptime Kuma `100.115.204.51:3001`)

---

## 4. 前端中控台工程架构 (`stacks/portal/web`)
- **技术栈**: React 19 + Vite 6 + TypeScript + Zustand + Tailwind CSS v4 + Lucide Icons
- **设计语言**:
  - **顶部导航 (`src/components/TopRibbon.tsx`)**: 标准 `shadcn/ui` 双层 AppShell Header。第一层 (`h-14`) 左侧为品牌与 `[中控台 | 📖 Storybook 设计规范]` 视图切换，右侧通过 `ml-auto shrink-0` 严格固定 `[🔍 搜索 ⌘K | >_ AGY 终端 | ☀️/🌙 主题切换]`；第二层 (`h-11`) 左侧为 4 枚硬件/网络微缩仪表胶囊，右侧为四模路由切换器。
  - **双主流主题自动切换 (`src/design-system/tokens.ts`)**: 仅保留 `light` (Shadcn Clean Light) 与 `dark` (Catppuccin/Linear Dark) 两个主流主题，默认监听 `window.matchMedia('(prefers-color-scheme: dark)')` 跟随设备深浅色自动切换，也可在右上角手动切换。
  - **内置 Storybook (`src/components/StorybookWorkbench.tsx`)**: 支持实时切换 3 种主流布局 (`homepage-3col` / `bento-split` / `compact-2col`)、查看双主题设计 Token、交互式调试 `ServiceCard` 组件变体。
- **构建与发布命令**:
  ```bash
  cd /Users/ixvii0iv/homelab/stacks/portal/web && npm run build
  rsync -az --delete /Users/ixvii0iv/homelab/stacks/portal/ ixvii0iv@192.168.31.164:~/homelab/stacks/portal/
  ```

---

## 5. Mac mini 后台常驻服务清单 (`LaunchAgents` & `LaunchDaemons`)
- `/Library/LaunchDaemons/com.homelab.caddy.plist`: 系统级 Caddy 网关（监听 `10443`，提供 `*.home.961504.xyz` Let's Encrypt DNS-01 通配符证书反代）
- `~/Library/LaunchAgents/com.homelab.portal.plist`: HomeLab Console V3 后端与静态资源服务 (`stacks/portal/server.py`，监听 `3002`/`3004`，提供 `/api/telemetry` 与 `/api/action/*`)
- `~/Library/LaunchAgents/com.homelab.agy-web.plist`: AGY 网页终端 (`scripts/start-agy-web.sh`，通过 `ttyd` 暴露 `7681` 端口并附着到 `tmux` 会话 `agy`)
- `~/Library/LaunchAgents/com.homelab.cf-ddns.plist`: 每 5 分钟检测家庭公网 IP 并更新 Cloudflare `home.961504.xyz` / `*.home.961504.xyz`
- `~/Library/LaunchAgents/com.homelab.mount-zspace.plist`: 自动挂载极空间 SMB 至 `~/nas/共享文件` 与 `~/nas/个人空间`
- `~/Library/LaunchAgents/com.homelab.nas-backup.plist`: 每天凌晨 03:30 自动打包备份 Vaultwarden、Caddy 与基础设施配置至极空间 `~/nas/个人空间/MacMini_Backups/`