# 🏠 家庭 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 监控配置
```