homelab/GEMINI.md

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 并同步至 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
• Agent 协同编排工作台 (Codeg Base + 自研大盘): https://nav.961504.xyz/agents & https://codeg.961504.xyz -> 100.108.205.40:3080 (SSO 免密 Proxy Auth)
• Gitea 私有代码托管与冷备中枢: https://git.961504.xyz -> 100.108.205.40:3005 (Mac SSD 热层 + 极空间 20TB 冷层)
• Storybook 设计系统工作台: https://nav.961504.xyz/storybook -> 100.108.205.40:3002/storybook
• AGY 云端编程工作台 (ttyd + tmux): https://agy.961504.xyz -> 100.108.205.40:7681 (受 HomeLab SSO 2.0 保护)
• 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://codeg.home.961504.xyz:10443 (Codeg 多智能体协同工作台)
  • https://git.home.961504.xyz:10443 (Gitea 私有代码托管中枢)
  • 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 组件变体。
• 构建与发布命令:

  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/agents/overview、/api/clawbot/* 与 /api/action/*)
• ~/Library/LaunchAgents/com.homelab.codeg.plist: Codeg 多智能体协同工作台底座 (scripts/start-codeg.sh，监听 3080，内置 4 大分工角色与 20+ CLI 协议适配)
• ~/Library/LaunchAgents/com.homelab.gitea.plist: Gitea 私有代码托管中枢 (scripts/start-gitea.sh，监听 3005/SSH 2222，Mac SSD 热层 + scripts/sync-git-to-nas.sh 极空间 20TB 冷层归档)
• ~/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、Gitea 冷备与基础设施配置至极空间 ~/nas/个人空间/MacMini_Backups/