homelab/PLAN.md

🗺️ 家庭 All-in-One 实施计划与进度追踪 (PLAN)

更新时间：2026-11-06

---

阶段一：Mac mini 服务器底座初始化 (Base Infrastructure)

• 1.1 局域网设备发现与体检：确认 Mac mini (192.168.31.164)、极空间 Z4 (192.168.31.185)、小米路由 (192.168.31.1) 状态。
• 1.2 开启 Mac mini SSH 与免密登录：配置公钥免密认证，并在本机配置 ssh mini 快捷别名。
• 1.3 建立本地基础设施仓库 (~/homelab)：固化架构文档、实施计划与变更日志。
• 1.4 Mac mini 电源与无头模式（Headless）调优：
  • 已配置 sudo 免密权限 (/etc/sudoers.d/ixvii0iv)。
  • 已关闭系统休眠 (sleep 0)、关闭磁盘休眠 (disksleep 0)、开启断电恢复自动开机 (autorestart 1)、开启网络唤醒 (womp 1)。
• 1.5 安装核心包管理与容器底座：
  • 已安装 Xcode Command Line Tools 27.2 与 Homebrew 7.0.12 (/opt/homebrew)。
  • 已安装并启动 OrbStack 2.2.5（Docker Engine 29.8.2）与 Tailscale 1.104.5。
• 1.6 远端目录规范化：已在 Mac mini 上创建 ~/homelab 与 ~/workspace 目录，并与本机仓库结构对齐。

---

阶段二：公网网关、异地组网与 Azure 2C4G 云边联动 (Network & Edge)

• 2.1 路由器固定 IP 与端口映射：
  • 已在小米路由器 (192.168.31.1) 中将 Mac mini (c8:80:6d:50:23:b1) 绑定为静态 IP 192.168.31.164。
  • 已配置防火墙 DNAT 端口转发：将联通公网 (124.90.142.21) 的 10443 (TCP/UDP) 转发至 Mac mini (192.168.31.164:10443)。
• 2.2 配置 Cloudflare DDNS 与 *.home.961504.xyz 泛域名 HTTPS 反代网关：
  • 已配置 scripts/cloudflare-ddns.sh 并注册 macOS LaunchAgent (com.homelab.cf-ddns.plist，每 5 分钟自动检测并同步公网 IP 至 home.961504.xyz 与 *.home.961504.xyz)。
  • 已通过 acme.sh + Cloudflare DNS API 自动签发 home.961504.xyz 与 *.home.961504.xyz 免费泛域名 SSL 证书。
  • 已部署明文 Git 管理的 home-gateway (stacks/gateway/Caddyfile)，监听 10443 端口反代极空间 Z4 (https://nas.home.961504.xyz:10443)、Lucky (https://lucky.home.961504.xyz:10443) 与 Clash 面板 (https://clash.home.961504.xyz:10443)。
• 2.3 部署 Tailscale（异地组网与家庭子网路由）：
  • 已在小米路由器配置 *.tailscale.com / *.ts.net 免 Fake-IP 直连与 UDP 41641 端口映射。
  • 已在 Mac mini 启动系统级 tailscaled 守护进程（分配固定虚拟 IP 100.108.205.40），开启 192.168.31.0/24 子网路由并关闭 --accept-dns=false 保护原有分流网络。
• 2.4 配置 Azure SG (104.43.105.243) 联动服务：
  • 已部署 Uptime Kuma 外部监控哨兵（访问地址：https://status.961504.xyz，标准 443 免端口）。
  • 已完成 Azure 节点的 Tailscale 组网绑定（虚拟 IP 100.115.204.51，与家里 Mac mini 100.108.205.40 实现 124.90.142.21 P2P 公网直连）。
  • 已打通 /etc/caddy/sites/homelab.conf 免端口反向代理：https://nav.961504.xyz（标准 443 免端口直达家里 Mac mini 导航页）。

---

阶段三：24 小时远程开发工作站 & 本地 AI 算力环境 (Dev & AI Host)

• 3.1 基础开发工具链安装：
  • 已安装 git, tmux, btop, ripgrep, fd, jq, wget, fnm, uv 与 agy (1.5.2)。
• 3.2 VS Code / AI IDE Remote-SSH 与 agy 流量出口锁定：
  • 已验证本机 MacBook Air 通过 ssh mini 免密直连开发。
  • 已完成底层网络规则固化：在小米路由器 /userdisk/ShellCrash/yamls/config.yaml 中将 antigravity.google、gemini.google.com、googleapis.com、deepmind.com 与 RULE-SET,google 统一路由至 Ai平台，并将 Ai平台 首选默认锁定为 狮城节点（仅含 104.43.105.243 SG Azure 双协议节点），不受其他节点测速波动影响。
• 3.3 部署 24 小时常驻 AGY 云端 Web 工作台 (ttyd + tmux 最佳实践)：
  • 已同步本机 agy 登录凭证与配置至 Mac mini (~/.gemini/antigravity-cli/)。
  • 已配置 ~/.tmux.conf（支持鼠标/触屏滑动与 30 万行长历史回溯）及 agy-work 终端快捷指令。
  • 已部署 ttyd + tmux Web 终端常驻服务 (scripts/start-agy-web.sh)，并暴露免端口入口 https://agy.961504.xyz 与家宽直连入口 https://agy.home.961504.xyz:10443（带密码保护），同步添加至家庭导航页首位卡片。

---

阶段四：家庭核心应用与极空间 Z4 联动（按需扩展）

• 4.1 家庭统一导航总入口 (https://nav.961504.xyz / https://home.961504.xyz:10443) 与反代安全锁：
  • 已部署 Sun-Panel (stacks/sun-panel/docker-compose.yml) 并预置 极空间 Z4、Clash 路由面板、小米路由器后台、Lucky 工具箱、Uptime 外部监控 卡片。
  • 已在 stacks/gateway/Caddyfile 为 clash.home.961504.xyz:10443 与 router.home.961504.xyz:10443 开启 HTTP Basic Auth 密码锁保护。
• 4.2 极空间 Z4 (192.168.31.185) 20TB 存储自动挂载与保活：
  • 已编写 scripts/mount-zspace.sh 并在 Mac mini 注册 com.homelab.mount-zspace.plist 守护任务（每 2 分钟巡检断线自动重连）。
  • 已成功将极空间 20TB 磁盘挂载至 Mac mini 的 ~/nas/共享文件 与 ~/nas/个人空间（可用空间 17TB）。
• 4.3 部署 Vaultwarden 私人密码保险箱与极空间每日自动备份：
  • 已部署 Vaultwarden (stacks/vaultwarden/docker-compose.yml)，提供免端口入口 https://vw.961504.xyz 与家宽直连入口 https://vw.home.961504.xyz:10443，并已添加至家庭导航页。
  • 已编写 scripts/backup-to-nas.sh 并注册 com.homelab.nas-backup.plist 定时任务，每天凌晨 03:30 自动打包备份 Vaultwarden 密码库与配置至极空间 ~/nas/个人空间/MacMini_Backups/（保留最近 30 份）。
• 4.4 配置全屋无线「时间机器 (Time Machine)」手动备份通道（关闭自动后台同步）：
  • 已在 Mac mini 绑定极空间 Z4 专用 smb://18549991015@192.168.31.185/Time%20Machine 备份目标，并执行 sudo tmutil disable 关闭后台自动同步（仅按需手动触发 tmutil startbackup）。
  • 已在本机 MacBook Air 钥匙串预存极空间 SMB 凭证并挂载 Time Machine 共享卷，设为手动按需备份模式。