chore: init homelab architecture docs, plan, changelog, and macmini init script

2026-11-06 21:33:33 +08:00
commit 96b899bb6f
@@ -0,0 +1,27 @@
+# 📝 变更日志 (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)（本变更日志文件）
@@ -0,0 +1,55 @@
+# 🗺️ 家庭 All-in-One 实施计划与进度追踪 (PLAN)
+
+> 更新时间：2026-11-06
+
+---
+
+## 阶段一：Mac mini 服务器底座初始化 (Base Infrastructure)
+
+- [x] **1.1 局域网设备发现与体检**：确认 Mac mini (`192.168.31.164`)、极空间 Z4 (`192.168.31.185`)、小米路由 (`192.168.31.1`) 状态。
+- [x] **1.2 开启 Mac mini SSH 与免密登录**：配置公钥免密认证，并在本机配置 `ssh mini` 快捷别名。
+- [x] **1.3 建立本地基础设施仓库 (`~/homelab`)**：固化架构文档、实施计划与变更日志。
+- [ ] **1.4 Mac mini 电源与无头模式（Headless）调优**：
+  - 关闭系统休眠 (`sleep 0`)、关闭磁盘休眠 (`disksleep 0`)、开启断电恢复自动开机 (`autorestart 1`)、开启网络唤醒 (`womp 1`)。
+  - 开启屏幕共享（VNC）备选通道，评估虚拟显示器（BetterDisplay / HDMI 欺骗器）。
+- [ ] **1.5 安装核心包管理与容器底座**：
+  - 安装 Xcode Command Line Tools 与 Homebrew (`/opt/homebrew`)。
+  - 安装 **OrbStack**（轻量高性能 Docker 引擎与 Linux 运行时）。
+- [ ] **1.6 远端目录规范化**：在 Mac mini 上创建 `~/homelab` 与 `~/workspace` 目录，与本机仓库结构对齐。
+
+---
+
+## 阶段二：公网网关、异地组网与 Azure 2C4G 云边联动 (Network & Edge)
+
+- [ ] **2.1 路由器固定 IP 与端口映射**：
+  - 在小米路由器 (`192.168.31.1`) 中将 Mac mini 固定为静态 IP（建议插网线固定有线 IP）。
+  - 转发 1 个高位 HTTPS 端口（如 `10443`）和组网端口到 Mac mini。
+- [ ] **2.2 部署 Lucky（家庭公网瑞士军刀）**：
+  - 配置域名 DNS API（Cloudflare / 阿里云 / 腾讯云），开启公网 IPv4/IPv6 DDNS 动态解析。
+  - 自动申请并续签 `*.home.<你的域名>` 泛域名免费 SSL/TLS 证书。
+  - 配置反向代理规则（统一通过 HTTPS 安全访问极空间、路由器后台与内部容器）。
+- [ ] **2.3 部署 Tailscale（打通 MacBook + Mac mini + Azure 2C4G）**：
+  - 三端登录同一 Tailnet，开启 Mac mini 的 Subnet Router（子网路由：`192.168.31.0/24`），实现在外网免配置直接用 `192.168.31.x` 访问家里极空间与路由器。
+- [ ] **2.4 配置 Azure 2C4G 联动服务**：
+  - 部署 **Uptime Kuma**：从公网外部监控家里公网 IP 与核心服务，断网/掉线立即推送告警。
+  - 部署 **Caddy / Nginx 443 免端口反代**：通过 Tailscale/WireGuard 隧道将轻量 Web 服务免端口（标准 `443`）暴露。
+
+---
+
+## 阶段三：24 小时远程开发工作站 & 本地 AI 算力环境 (Dev & AI Host)
+
+- [ ] **3.1 基础开发工具链安装**：
+  - 安装 `git`, `tmux`, `btop`, `ripgrep`, `fd`, `jq`, `gh` 等命令行效率工具。
+  - 配置 Node.js (fnm/nvm)、Python (uv/miniconda) 等多版本隔离环境。
+- [ ] **3.2 VS Code / AI IDE Remote-SSH 联调**：
+  - 验证本机 MacBook Air 通过 `ssh mini` 免密直连开发、后台 `tmux` 任务保活。
+- [ ] **3.3 本地 AI 算力服务（可选）**：
+  - 利用 M6 24GB 统一内存部署 **Ollama + Open WebUI**，向内网与本机提供私有大模型 API。
+
+---
+
+## 阶段四：家庭核心应用与极空间 Z4 联动（按需扩展）
+
+- [ ] **4.1 统一导航页与密码管理**：部署 **Sun-Panel / Homepage** + **Vaultwarden**。
+- [ ] **4.2 极空间 SMB 自动挂载与影视自动化**：挂载 `192.168.31.185` 共享目录，部署 **MoviePilot + qBittorrent**。
+- [ ] **4.3 智能家居中枢**：部署 **Home Assistant + Scrypted**（摄像头接入 Apple HomeKit 安全视频）。
@@ -0,0 +1,56 @@
+# 🏠 家庭 All-in-One & 云边协同架构仓库 (HomeLab IaC)
+
+本目录用于集中保存、追踪家庭 All-in-One 服务器的**架构设计、实施计划、变更日志（Changelog）、自动化脚本与容器编排配置（Docker Compose）**。所有对设备的修改均在此留档，确保随时可查、可回滚、可一键迁移。
+
+---
+
+## 一、 全局设备与网络拓扑清单
+
+```mermaid
+flowchart TB
+    Internet["🌐 互联网 / 外部访问"]
+    
+    subgraph Cloud ["☁️ 公有云层 (Azure)"]
+        Azure["Azure VM (2C4G)<br/>固定公网 IP / 开放 80 & 443<br/>职责: 免端口HTTPS反代 / 外部监控哨兵 / 企微&TG网关"]
+    end
+
+    subgraph HomeLAN ["🏠 家庭局域网 (192.168.31.0/24 - 动态公网 IP)"]
+        Router["📡 小米路由器 (192.168.31.1)<br/>职责: PPPoE拨号 / DHCP / ShellCrash(Mihomo)透明分流 / 端口转发"]
+        Mini["🖥️ Mac mini M6 (192.168.31.164)<br/>主机名: ixvii0ivdeMac-Mini.local<br/>规格: Apple M6 (12核) / 24GB / 512GB SSD<br/>职责: 公网网关(Lucky) / OrbStack容器中心 / 24h远程开发机 / 本地AI"]
+        ZSpace["💾 极空间 Z4 (192.168.31.185)<br/>主机名: Z4-R8WA.local<br/>职责: RAID大容量冷存储 / 极影视 / 手机相册备份 / SMB共享"]
+        MBA["💻 MacBook Air M5 (192.168.31.83)<br/>职责: 日常移动主力开发机 (通过 ssh mini 远程连接)"]
+    end
+
+    Internet -->|"标准 443 免端口访问"| Azure
+    Internet -->|"高带宽直连 (Lucky HTTPS / WireGuard)"| Router
+    Azure <===>|"Tailscale / WireGuard 加密专线"| Mini
+    Router --> Mini
+    Router --> ZSpace
+    Router --> MBA
+    Mini <-->|"SMB/NFS 局域网高速挂载"| ZSpace
+```
+
+| 设备角色 | 设备名称 | 局域网/公网 IP | 硬件配置 | SSH 快捷连接 | 核心职责 |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **核心计算/AIO** | **Mac mini** | `192.168.31.164` | Apple M6 (12C) / 24GB / 512G | `ssh mini` | Lucky 公网反代、Tailscale 节点、OrbStack 容器、24h 远程开发与 AI 算力 |
+| **核心存储/NAS** | **极空间 Z4** | `192.168.31.185` | 磁盘阵列 NAS | - | 大容量影视/相册/冷备份存储，通过 SMB 挂载给 Mac mini |
+| **主路由/透明网关** | **小米路由器** | `192.168.31.1` | 已解锁 SSH + ShellCrash | `ssh 192.168.31.1` | 宽带拨号、全屋 DHCP、ShellCrash (Mihomo) 科学上网分流、端口映射 |
+| **云端协同节点** | **Azure 2C4G** | 待填入固定 IP | 2 vCPU / 4 GB RAM | `ssh azure` | 443 免端口反向代理、Uptime Kuma 外部断网告警、企微固定白名单 IP 转发 |
+| **日常控制端** | **MacBook Air** | `192.168.31.83` | Apple M5 (10C) / 16GB / 512G | 本机 | 日常使用、管理本仓库 (`~/homelab`)、Remote-SSH 远程开发 |
+
+---
+
+## 二、 目录结构说明
+
+```text
+~/homelab/
+├── README.md                 # 全局架构、设备资产与端口规划总览（本文件）
+├── PLAN.md                   # 分阶段实施路线图与任务进度 Checklist
+├── CHANGELOG.md              # 详细操作与配置变更日志（含回滚指令）
+├── scripts/                  # 宿主机初始化与运维脚本
+│   └── 01-macmini-init.sh    # Mac mini 防休眠、基础环境与目录初始化脚本
+└── stacks/                   # Docker Compose 容器编排目录（与 Mac mini 同步）
+    ├── lucky/                # DDNS 动态域名 + HTTPS 证书 + 反向代理
+    ├── tailscale/            # 异地组网与内网穿透配置
+    └── azure-edge/           # Azure 2C4G 端 Caddy 反代与 Uptime Kuma 监控配置
+```
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# 01-macmini-init.sh
+# 用途：Mac mini (M6) 家庭 All-in-One 服务器底座初始化脚本
+# 包含：电源防休眠配置、标准目录初始化、Homebrew + OrbStack + 常用开发工具安装
+# ==============================================================================
+set -euo pipefail
+
+echo ">>> [1/4] 创建标准服务器目录结构 (~/homelab & ~/workspace)..."
+mkdir -p "$HOME/homelab/stacks/{lucky,tailscale,monitoring}"
+mkdir -p "$HOME/homelab/scripts"
+mkdir -p "$HOME/homelab/backups"
+mkdir -p "$HOME/workspace"
+
+echo ">>> [2/4] 配置 macOS 服务器电源管理策略 (pmset: 永不休眠 + 断电自启 + 网络唤醒)..."
+sudo pmset -a \
+  sleep 0 \
+  disksleep 0 \
+  displaysleep 10 \
+  standby 0 \
+  autorestart 1 \
+  womp 1 \
+  tcpkeepalive 1 \
+  powernap 1
+pmset -g
+
+echo ">>> [3/4] 检查并安装 Homebrew..."
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+if ! command -v brew >/dev/null 2>&1; then
+  echo "正在安装 Homebrew..."
+  NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  if ! grep -q '/opt/homebrew/bin/brew' "$HOME/.zprofile" 2>/dev/null; then
+    echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> "$HOME/.zprofile"
+  fi
+  eval "$(/opt/homebrew/bin/brew shellenv)"
+else
+  echo "Homebrew 已安装: $(brew --version | head -n 1)"
+fi
+
+echo ">>> [4/4] 安装容器底座 (OrbStack)、组网工具 (Tailscale) 与远程开发工具链..."
+brew install --cask orbstack tailscale-app
+brew install git tmux btop ripgrep fd jq wget fnm uv
+
+echo "✅ Mac mini 基础底座初始化完成！"