6.1 KiB
6.1 KiB
HomeLab & Cloud-Edge Architecture Memory (GEMINI.md)
本文件为 agy (Antigravity CLI) 的全局持久上下文记忆文件。无论在 M5 MacBook Air 还是 M6 Mac mini 网页端 (https://agy.961504.xyz) 启动新会话，均自动加载本架构规范。
1. 交互与工作准则
- 汇报 + 确认机制：每次架构变更或较大改动前，先说明方案，再执行；代码与基础设施配置统一维护在 Git 仓库
/Users/ixvii0iv/homelab并同步至mini:~/homelab。 - 代码链接规范：回答中涉及所有文件路径或代码符号时，必须使用可点击的 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 Web192.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 Kuma100.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组件变体。
- 顶部导航 (
- 构建与发布命令:
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.xyzLet'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 并更新 Cloudflarehome.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/