commit 96b899bb6f28697dac2a8373102b0bfe88674a69 Author: Yin Kou Date: Fri Nov 6 21:33:33 2026 +0800 chore: init homelab architecture docs, plan, changelog, and macmini init script diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c33d34e --- /dev/null +++ b/CHANGELOG.md @@ -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)（本变更日志文件） diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..600a4de --- /dev/null +++ b/PLAN.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 安全视频）。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..d922a6d --- /dev/null +++ b/README.md @@ -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)
固定公网 IP / 开放 80 & 443
职责: 免端口HTTPS反代 / 外部监控哨兵 / 企微&TG网关"] + end + + subgraph HomeLAN ["🏠 家庭局域网 (192.168.31.0/24 - 动态公网 IP)"] + Router["📡 小米路由器 (192.168.31.1)
职责: PPPoE拨号 / DHCP / ShellCrash(Mihomo)透明分流 / 端口转发"] + Mini["🖥️ Mac mini M6 (192.168.31.164)
主机名: ixvii0ivdeMac-Mini.local
规格: Apple M6 (12核) / 24GB / 512GB SSD
职责: 公网网关(Lucky) / OrbStack容器中心 / 24h远程开发机 / 本地AI"] + ZSpace["💾 极空间 Z4 (192.168.31.185)
主机名: Z4-R8WA.local
职责: RAID大容量冷存储 / 极影视 / 手机相册备份 / SMB共享"] + MBA["💻 MacBook Air M5 (192.168.31.83)
职责: 日常移动主力开发机 (通过 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 监控配置 +``` diff --git a/scripts/01-macmini-init.sh b/scripts/01-macmini-init.sh new file mode 100755 index 0000000..1efe4fd --- /dev/null +++ b/scripts/01-macmini-init.sh @@ -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 基础底座初始化完成！"