homelab/CHANGELOG.md

# 📝 变更日志 (CHANGELOG)

所有针对 **本机 (MacBook Air)**、**Mac mini (`192.168.31.164`)**、**小米路由器 (`192.168.31.1`)** 及 **Azure 2C4G** 的配置变更均记录在此，包含具体命令与回滚方法。

---

## [2026-11-06] 初始化阶段

### 1. 开启 Mac mini SSH 免密登录与快捷别名
- **操作时间**：2026-11-06 21:29 ~ 21:32
- **目标设备**：
  - Mac mini (`192.168.31.164`)
  - 本机 MacBook Air (`192.168.31.83`)
- **变更内容**：
  1. 在 Mac mini 系统设置中开启了“远程登录 (SSH)”。
  2. 通过 `ssh-copy-id ixvii0iv@192.168.31.164` 将本机公钥写入 Mac mini 的 `~/.ssh/authorized_keys`。
  3. 在本机 [`~/.ssh/config`](file:///Users/ixvii0iv/.ssh/config) 中新增了 `Host mini macmini` 快捷配置，开启心跳保活 (`ServerAliveInterval 60`)。
- **验证方式**：在本机终端直接运行 `ssh mini` 即可免密秒连 Mac mini。
- **回滚方式**：编辑 [`~/.ssh/config`](file:///Users/ixvii0iv/.ssh/config) 删除 `Host mini macmini` 段落。

### 2. 创建本机 HomeLab 基础设施管理目录 (`~/homelab`)
- **操作时间**：2026-11-06 21:32
- **目标设备**：本机 MacBook Air (`/Users/ixvii0iv/homelab`)
- **变更内容**：
  - 创建 [`README.md`](file:///Users/ixvii0iv/homelab/README.md)（全局网络拓扑与设备资产表）
  - 创建 [`PLAN.md`](file:///Users/ixvii0iv/homelab/PLAN.md)（4 阶段实施蓝图与进度表）
  - 创建 [`CHANGELOG.md`](file:///Users/ixvii0iv/homelab/CHANGELOG.md)（本变更日志文件）

### 3. 配置 Mac mini 免密 sudo 与服务器电源防休眠策略 (`pmset`)
- **操作时间**：2026-11-06 21:37
- **目标设备**：Mac mini (`192.168.31.164`)
- **变更内容**：
  1. 创建 `/etc/sudoers.d/ixvii0iv`（权限 `0440`），赋予 `ixvii0iv` 用户免密 `sudo` 权限，便于自动化运维。
  2. 执行 `sudo pmset -a sleep 0 disksleep 0 displaysleep 10 standby 0 autorestart 1 womp 1 tcpkeepalive 1 powernap 1`，彻底关闭系统与磁盘休眠，并开启断电恢复自动启动与网络唤醒。
- **回滚方式**：
  - 删除免密 sudo：`ssh mini "sudo rm -f /etc/sudoers.d/ixvii0iv"`
  - 恢复默认休眠：`ssh mini "sudo pmset -a sleep 1 disksleep 10 autorestart 0"`

### 4. 编写 Lucky 与 Azure 云边协同 Docker Compose 编排文件
- **操作时间**：2026-11-06 21:38
- **目标设备**：本机 MacBook Air (`/Users/ixvii0iv/homelab/stacks/`)
- **变更内容**：
  - 创建 [`stacks/lucky/docker-compose.yml`](file:///Users/ixvii0iv/homelab/stacks/lucky/docker-compose.yml)（用于 Mac mini 部署 Lucky DDNS + HTTPS 反代）
  - 创建 [`stacks/azure-edge/docker-compose.yml`](file:///Users/ixvii0iv/homelab/stacks/azure-edge/docker-compose.yml) 与 [`stacks/azure-edge/Caddyfile`](file:///Users/ixvii0iv/homelab/stacks/azure-edge/Caddyfile)（用于 Azure 2C4G 部署 Uptime Kuma 监控与 443 免端口反代）

### 5. 完成 Mac mini 软件底座、OrbStack、Tailscale、开发工具链及 `agy` 安装
- **操作时间**：2026-11-06 21:38 ~ 21:43
- **目标设备**：Mac mini (`192.168.31.164`)
- **变更内容**：
  1. 安装 Xcode Command Line Tools 27.2 与 Homebrew 7.0.12 (`/opt/homebrew`)。
  2. 通过 Homebrew Cask 安装并启动 **OrbStack 2.2.5** (Docker Engine `29.8.2`) 与 **Tailscale 1.104.5**。
  3. 安装 CLI 开发工具链：`git`, `tmux`, `btop`, `ripgrep`, `fd`, `jq`, `wget`, `fnm`, `uv`。
  4. 安装 **Antigravity CLI (`agy` 1.5.2)** 至 `/Users/ixvii0iv/.local/bin/agy`，并配置 `~/.zshrc` 与 `~/.zprofile` 的 `PATH` 环境变量。
- **回滚方式**：可通过 `brew uninstall` 卸载对应软件包，或删除 `~/.local/bin/agy`。

### 6. 锁定小米路由器 Mihomo 策略组出口至 SG Azure (`233boy-sea` / `104.43.105.243`)
- **操作时间**：2026-11-06 21:43
- **目标设备**：小米路由器 (`192.168.31.1:9999`)
- **变更内容**：
  - 通过 Mihomo REST API 将 `手动切换` 固定为 `233boy-sea`，并将 `Ai平台` 与 `节点选择` 固定指向 `手动切换`（取代原先会随延迟自动切换节点的 `自动选择`），确保 Mac mini 与本机的 `agy` 流量 100% 稳定走 SG Azure (`104.43.105.243`)。
- **回滚方式**：在路由器 Mihomo 面板 (`http://192.168.31.1:9999`) 中将 `节点选择` 切回 `自动选择`。

### 7. 在 Mac mini 上启动 Lucky 容器 (`gdy666/lucky:latest`)
- **操作时间**：2026-11-06 21:45
- **目标设备**：Mac mini (`192.168.31.164`)
- **变更内容**：
  - 同步 `~/homelab/stacks/lucky/docker-compose.yml` 至 Mac mini 并执行 `docker compose up -d`。
  - 容器已启动，Web 管理面板监听 `http://192.168.31.164:16601`（默认初始账号密码：`666` / `666`），公网反代端口监听 `10443` (TCP/UDP)。
- **回滚方式**：`ssh mini "cd ~/homelab/stacks/lucky && docker compose down"`

### 8. 小米路由器底层固化：静态 DHCP 绑定、公网 10443 端口转发与 ShellCrash `agy` 规则锁定
- **操作时间**：2026-11-06 21:49 ~ 21:50
- **目标设备**：小米路由器 (`192.168.31.1`)
- **原始备份**：[`backups/router/config.yaml.bak`](file:///Users/ixvii0iv/homelab/backups/router/config.yaml.bak)（路由器端备份为 `/userdisk/ShellCrash/yamls/config.yaml.bak.20261106`）
- **变更内容**：
  1. **DHCP 静态绑定**：通过 `uci add dhcp host` 将 Mac mini (`c8:80:6d:50:23:b1`) 固定绑定为 `192.168.31.164` (`Mac-mini`)。
  2. **公网端口转发 (`Lucky_HTTPS_10443`)**：通过 `uci add firewall redirect` 将 WAN 口 `10443` (TCP+UDP) 转发至 `192.168.31.164:10443`。
  3. **ShellCrash 规则永久固化**（见 [`configs/router-shellcrash-config.yaml`](file:///Users/ixvii0iv/homelab/configs/router-shellcrash-config.yaml)）：
     - 将 `Ai平台` 的默认首选节点改为 `狮城节点`（该组仅包含 `coco-sea1-reality-sony` 与 `233boy-sea`，两者服务端均为你的 SG Azure `104.43.105.243`）。
     - 在 `rules:` 中新增 `antigravity.google`、`gemini.google.com`、`googleapis.com`、`deepmind.com` 及 `RULE-SET,google` 统一指向 `Ai平台`，彻底隔离其他策略组切换对 `agy` 出口 IP 的影响。
- **回滚方式**：
  - 恢复 ShellCrash 配置：`cat ~/homelab/backups/router/config.yaml.bak | ssh 192.168.31.1 "cat > /userdisk/ShellCrash/yamls/config.yaml && /userdisk/ShellCrash/start.sh bfstart"`
  - 删除端口转发：`ssh 192.168.31.1 "uci delete firewall.@redirect[-1] && uci commit firewall && /etc/init.d/firewall reload"`

### 9. 配置 Cloudflare DDNS 自动守护进程、`*.home.961504.xyz` 泛域名 SSL 证书与 HTTPS 反代网关
- **操作时间**：2026-11-06 21:56 ~ 21:58
- **目标设备**：Mac mini (`192.168.31.164`) & Cloudflare (`961504.xyz`) & 小米路由器 (`192.168.31.1`)
- **变更内容**：
  1. **Cloudflare DDNS**：编写 [`scripts/cloudflare-ddns.sh`](file:///Users/ixvii0iv/homelab/scripts/cloudflare-ddns.sh) 并在 Mac mini 注册 `~/Library/LaunchAgents/com.homelab.cf-ddns.plist`（每 5 分钟自动运行），已将 `home.961504.xyz` 与 `*.home.961504.xyz` 解析至当前联通公网 IP `124.90.142.21`。
  2. **泛域名 HTTPS 证书 (`acme.sh`)**：通过 Cloudflare DNS-01 验证自动签发 `home.961504.xyz` + `*.home.961504.xyz` ECC 泛域名证书，存放于 `~/homelab/stacks/gateway/certs/`。
  3. **明文 HTTPS 反代网关 (`home-gateway`)**：部署 [`stacks/gateway/docker-compose.yml`](file:///Users/ixvii0iv/homelab/stacks/gateway/docker-compose.yml) 与 [`stacks/gateway/Caddyfile`](file:///Users/ixvii0iv/homelab/stacks/gateway/Caddyfile)，监听 `10443` 端口提供：
     - `https://nas.home.961504.xyz:10443` (`z4.home.961504.xyz:10443`) -> 极空间 Z4 (`192.168.31.185:5055`)
     - `https://lucky.home.961504.xyz:10443` -> Lucky (`16601`)
     - `https://clash.home.961504.xyz:10443` -> 路由器 Mihomo 面板 (`192.168.31.1:9999`)
  4. **路由器直连优化**：在 [`configs/router-shellcrash-config.yaml`](file:///Users/ixvii0iv/homelab/configs/router-shellcrash-config.yaml) 中新增 `DOMAIN-SUFFIX,home.961504.xyz,全球直连`，避免内网访问家庭域名时绕行境外代理。
- **回滚方式**：
  - 停止 DDNS：`ssh mini "launchctl unload ~/Library/LaunchAgents/com.homelab.cf-ddns.plist"`
  - 停止反代网关：`ssh mini "sudo brew services stop caddy"`

### 10. 部署家庭统一导航页 Sun-Panel (`https://home.961504.xyz:10443`) 与反代 Basic Auth 安全锁
- **操作时间**：2026-11-06 22:06 ~ 22:08
- **目标设备**：Mac mini (`192.168.31.164`)
- **变更内容**：
  1. 部署 [`stacks/sun-panel/docker-compose.yml`](file:///Users/ixvii0iv/homelab/stacks/sun-panel/docker-compose.yml)（监听 `3002` 端口），并在 SQLite 数据库中预置了 **极空间 Z4、Clash 路由面板、小米路由器后台、Lucky 工具箱** 四张卡片（同时配置了外网 `10443` 链接与内网 `192.168.31.x` 链接，支持一键切换内外网模式）。
  2. 更新 [`stacks/gateway/Caddyfile`](file:///Users/ixvii0iv/homelab/stacks/gateway/Caddyfile) 并同步至 `/opt/homebrew/etc/Caddyfile`：
     - 新增总入口 `https://home.961504.xyz:10443`（及 `https://nav.home.961504.xyz:10443`）反代至 Sun-Panel (`127.0.0.1:3002`)。
     - 为 `clash.home.961504.xyz:10443` 与 `router.home.961504.xyz:10443` 开启 `basic_auth` 密码认证（账号 `ixvii0iv`，密码与 Mac mini 一致）。
- **回滚方式**：`ssh mini "cd ~/homelab/stacks/sun-panel && docker compose down"`

### 11. 部署 Mac mini Tailscale 异地组网与家庭子网路由 (`100.108.205.40`)
- **操作时间**：2026-11-06 22:10 ~ 22:18
- **目标设备**：小米路由器 (`192.168.31.1`) & Mac mini (`192.168.31.164`) & 本机 MacBook Air
- **变更内容**：
  1. **路由器防冲突配置**：在 [`configs/router-shellcrash-config.yaml`](file:///Users/ixvii0iv/homelab/configs/router-shellcrash-config.yaml) 中将 `+.tailscale.com`、`+.tailscale.io`、`+.ts.net` 加入 `fake-ip-filter` 与 `全球直连`，并添加防火墙 `Tailscale_UDP_41641` 端口映射，确保 P2P 直连打洞不被国外代理劫持。
  2. **Mac mini 系统级守护进程**：开启内核 IPv4 转发 (`net.inet.ip.forwarding=1`)，安装并启动 `sudo brew services start tailscale`，执行 `sudo tailscale up --advertise-routes=192.168.31.0/24 --accept-dns=false`。
  3. **组网结果**：Mac mini 获得固定 Tailscale IP `100.108.205.40`，同时实测 Mac mini 海外出口 IP 仍为 `104.43.105.243` (SG Azure)，对家庭原有网络零干扰。
  4. **本机 SSH 别名**：在 [`~/.ssh/config`](file:///Users/ixvii0iv/.ssh/config) 新增 `Host mini-ts` (`100.108.205.40`)。
- **回滚方式**：`ssh mini "sudo /opt/homebrew/bin/tailscale down && sudo brew services stop tailscale"`

### 12. 配置 SG Azure (`104.43.105.243`) 外部监控哨兵 (Uptime Kuma)、443 免端口反代与 Tailscale 联动
- **操作时间**：2026-11-06 22:21 ~ 22:25
- **目标设备**：SG Azure (`104.43.105.243` / `coco-sea1`) & Cloudflare (`961504.xyz`)
- **变更内容**：
  1. **Cloudflare DNS**：新增 `status.961504.xyz` 与 `nav.961504.xyz` 解析指向 `104.43.105.243`。
  2. **Uptime Kuma 容器**：在 Azure Rootless Docker 中启动 `louislam/uptime-kuma:1`（监听 `127.0.0.1:3001`，数据目录 `~/homelab/uptime-kuma-data`）。
  3. **Caddy 443 免端口反代**：将 [`stacks/azure-edge/Caddyfile`](file:///Users/ixvii0iv/homelab/stacks/azure-edge/Caddyfile) 写入 Azure 的 `/etc/caddy/sites/homelab.conf` 并重启 Caddy，使 `https://status.961504.xyz` 与 `https://nav.961504.xyz` 免端口 HTTPS 生效。
  4. **Tailscale 组网**：在 Azure 安装 Tailscale（开启 `--accept-dns=false --accept-routes=false` 确保不影响原有 `233boy` 代理节点），获得虚拟 IP `100.115.204.51` 并与家里 Mac mini (`100.108.205.40`) 建立 P2P 直连。
- **回滚方式**：`ssh azure "sudo rm -f /etc/caddy/sites/homelab.conf && sudo systemctl restart caddy"`

### 13. 部署微信（企业微信自建应用 $\leftrightarrow$ 个人微信）双向控制与通知网关 (`https://wx.961504.xyz`)
- **操作时间**：2026-11-06 22:30 ~ 22:31
- **目标设备**：小米路由器 (`192.168.31.1`) & Mac mini (`192.168.31.164`) & SG Azure (`104.43.105.243`)
- **变更内容**：
  1. **固定企微白名单出口 IP**：在路由器 [`configs/router-shellcrash-config.yaml`](file:///Users/ixvii0iv/homelab/configs/router-shellcrash-config.yaml) 新增 `DOMAIN-SUFFIX,qyapi.weixin.qq.com,Ai平台`，确保主动推送消息出口永远为 `104.43.105.243`。
  2. **微信双向网关服务**：编写 [`stacks/wechat-bot/server.py`](file:///Users/ixvii0iv/homelab/stacks/wechat-bot/server.py) 与 [`stacks/wechat-bot/config.env`](file:///Users/ixvii0iv/homelab/stacks/wechat-bot/config.env)，在 Mac mini 注册 `~/Library/LaunchAgents/com.homelab.wechat-bot.plist`（通过 `uv run` 常驻运行于 `3005` 端口）。
  3. **免端口 HTTPS 回调入口**：在 Cloudflare 添加 `wx.961504.xyz -> 104.43.105.243`，并在 Azure Caddy 配置反代至 `100.108.205.40:3005`（已按要求暂停进程保留配置）。
- **回滚方式**：`ssh mini "launchctl unload ~/Library/LaunchAgents/com.homelab.wechat-bot.plist"`

### 14. 配置 Mac mini 自动挂载极空间 Z4 (`192.168.31.185`) 20TB SMB 存储与断线自动重连
- **操作时间**：2026-11-06 22:40
- **目标设备**：Mac mini (`192.168.31.164`) & 极空间 Z4 (`192.168.31.185`)
- **变更内容**：
  1. 编写 [`scripts/mount-zspace.sh`](file:///Users/ixvii0iv/homelab/scripts/mount-zspace.sh)，将极空间 Z4 的 `共享文件` 与 `185XXXX1015`（个人空间，总计 20TB，剩余可用 17TB）挂载至 Mac mini 的 `/Users/ixvii0iv/nas/共享文件` 与 `/Users/ixvii0iv/nas/个人空间`。
  2. 在 Mac mini 注册 `~/Library/LaunchAgents/com.homelab.mount-zspace.plist`（每 120 秒巡检一次，若极空间或路由器重启后自动重新挂载）。
- **回滚方式**：`ssh mini "launchctl unload ~/Library/LaunchAgents/com.homelab.mount-zspace.plist && umount ~/nas/共享文件 ~/nas/个人空间"`

### 15. 部署 24 小时常驻 AGY 云端 Web 工作台 (`https://agy.961504.xyz` / `ttyd` + `tmux`)
- **操作时间**：2026-11-06 22:46 ~ 22:48
- **目标设备**：Mac mini (`192.168.31.164`) & SG Azure (`104.43.105.243`)
- **变更内容**：
  1. **同步 `agy` 配置**：将本机 `~/.gemini/antigravity-cli/{jetski_state.pbtxt,settings.json}` 同步至 Mac mini。
  2. **安装与调优 `ttyd` + `tmux`**：在 Mac mini 安装 `ttyd` (`1.7.7`)，编写 `~/.tmux.conf`（开启鼠标滚轮、触屏滑动与 30 万行历史缓存），编写 [`scripts/start-agy-web.sh`](file:///Users/ixvii0iv/homelab/scripts/start-agy-web.sh) 并注册 `~/Library/LaunchAgents/com.homelab.agy-web.plist` 常驻守护进程（监听 `7681` 端口，自动附着到名为 `agy` 的 `tmux` 会话并启动 `agy`）。
  3. **配置双通道 HTTPS 密码锁反代与导航页卡片**：
     - 免端口访问：`https://agy.961504.xyz`（走 Azure 443 + Basic Auth 密码锁）
     - 家宽直连访问：`https://agy.home.961504.xyz:10443`（走家里 10443 + Basic Auth 密码锁）
     - 已将 **「AGY 云端工作台」** 添加至 `https://nav.961504.xyz` 导航页第一张卡片。
- **回滚方式**：`ssh mini "launchctl unload ~/Library/LaunchAgents/com.homelab.agy-web.plist"`










### 16. 部署 Vaultwarden 私人密码保险箱 (`https://vw.961504.xyz`) 与极空间每日自动备份
- **操作时间**：2026-11-06 22:57 ~ 22:59
- **目标设备**：Mac mini (`192.168.31.164`) & SG Azure (`104.43.105.243`) & 极空间 Z4 (`192.168.31.185`)
- **变更内容**：
  1. **Vaultwarden 容器**：编写 [`stacks/vaultwarden/docker-compose.yml`](file:///Users/ixvii0iv/homelab/stacks/vaultwarden/docker-compose.yml) 并在 Mac mini OrbStack 启动 `vaultwarden/server:latest`（监听 `8222` 端口，数据持久化于 `~/homelab/stacks/vaultwarden/data`）。
  2. **双通道 HTTPS 反代与导航页卡片**：
     - 免端口访问：`https://vw.961504.xyz`（走 Azure 443 反代至 `100.108.205.40:8222`）
     - 家宽直连访问：`https://vw.home.961504.xyz:10443`（走家里 10443 反代至 `127.0.0.1:8222`）
     - 已将 **「Vaultwarden 密码库」** 添加至 `https://nav.961504.xyz` 导航页。
  3. **极空间 20TB 每日自动备份**：编写 [`scripts/backup-to-nas.sh`](file:///Users/ixvii0iv/homelab/scripts/backup-to-nas.sh) 并注册 `~/Library/LaunchAgents/com.homelab.nas-backup.plist`（每天凌晨 03:30 自动打包备份 Vaultwarden 数据、Sun-Panel 配置与 Homelab 脚本至 `/Users/ixvii0iv/nas/个人空间/MacMini_Backups/`，自动保留最近 30 份）。
- **回滚方式**：`ssh mini "cd ~/homelab/stacks/vaultwarden && docker compose down && launchctl unload ~/Library/LaunchAgents/com.homelab.nas-backup.plist"`