# 🏠 家庭 All-in-One & 云边协同架构仓库 (HomeLab IaC)

本目录用于集中保存、追踪家庭 All-in-One 服务器的**架构设计、实施计划、变更日志（Changelog）、自动化脚本与容器编排配置（Docker Compose）**。所有对设备的修改均在此留档，确保随时可查、可回滚、可一键迁移。

---

## 一、 全局设备与网络拓扑清单

```mermaid
flowchart TB
    Internet["🌐 互联网 / 外部访问"]
    
    subgraph Cloud ["☁️ 公有云层 (SG Azure 104.43.105.243)"]
        Azure["Azure SG (coco-sea1)<br/>固定公网 IP: 104.43.105.243 / Tailscale: 100.115.204.51<br/>职责: 443免端口HTTPS反代 / Uptime Kuma外部哨兵 / AGY固定AI出口"]
    end

    subgraph HomeLAN ["🏠 家庭局域网 (192.168.31.0/24 - 联通公网 124.90.142.21)"]
        Router["📡 小米路由器 (192.168.31.1)<br/>职责: PPPoE拨号 / DHCP静态绑定 / ShellCrash(Mihomo)分流 / 10443&41641端口映射"]
        Mini["🖥️ Mac mini M6 (192.168.31.164 / Tailscale: 100.108.205.40)<br/>规格: Apple M6 (12核) / 24GB / 512GB SSD<br/>职责: Caddy网关 / OrbStack容器 / AGY 24h云端工作台 / Vaultwarden密码库"]
        ZSpace["💾 极空间 Z4 (192.168.31.185)<br/>规格: 20TB 存储池 (可用 17TB)<br/>职责: 影视相册存储 / SMB自动挂载至Mac mini / Time Machine & 灾备中心"]
        MBA["💻 MacBook Air M5 (192.168.31.83)<br/>职责: 日常移动主力开发机 (通过 ssh mini / ssh azure 远程管理)"]
    end

    Internet -->|"标准 443 免端口访问 (*.961504.xyz)"| Azure
    Internet -->|"家宽公网直连 (*.home.961504.xyz:10443)"| Router
    Azure <===>|"Tailscale P2P 加密专线"| Mini
    Router --> Mini
    Router --> ZSpace
    Router --> MBA
    Mini <-->|"SMB 20TB 自动挂载 (~/nas)"| ZSpace
```

| 设备角色 | 设备名称 | 局域网 / 公网 / Tailscale IP | 硬件配置 | SSH 快捷连接 | 核心职责 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **核心计算/AIO** | **Mac mini** | 内网 `192.168.31.164`<br/>Tailscale `100.108.205.40` | Apple M6 (12C) / 24GB / 512G | `ssh mini`<br/>`ssh mini-ts` | Caddy 公网网关、Tailscale 子网路由、OrbStack 容器、AGY 云端工作台、Vaultwarden |
| **核心存储/NAS** | **极空间 Z4** | 内网 `192.168.31.185` | 20TB NAS 存储池 | - | 影视/相册/冷备存储，SMB 自动挂载至 Mac mini `~/nas/{共享文件,个人空间}` |
| **主路由/透明网关** | **小米路由器** | 内网 `192.168.31.1`<br/>联通公网 `124.90.142.21` | 已开启 SSH + ShellCrash | `ssh 192.168.31.1` | 宽带拨号、DHCP 绑定、Mihomo 透明分流（锁定 `agy` 走狮城）、端口转发 |
| **云端协同节点** | **Azure SG (`coco-sea1`)** | 公网 `104.43.105.243`<br/>Tailscale `100.115.204.51` | 2C / 8GB RAM | `ssh azure` | 443 免端口反代 (`nav`/`agy`/`vw`/`status`)、Uptime Kuma 监控、`agy` 固定出口 IP |
| **日常控制端** | **MacBook Air** | 内网 `192.168.31.83` | Apple M5 (10C) / 16GB / 512G | 本机 | 日常使用、管理本仓库 (`~/homelab`)、Remote-SSH 远程开发 |

---

## 二、 全部服务访问入口速查表 (`961504.xyz`)

| 服务名称 | 🌐 免端口直达 (走 Azure 443) | ⚡ 家宽公网/内网直达 (10443 端口) | 🏠 局域网原生地址 | 认证说明 |
| :--- | :--- | :--- | :--- | :--- |
| **🏠 家庭统一导航页 (Sun-Panel)** | `https://nav.961504.xyz` | `https://home.961504.xyz:10443`<br/>`https://nav.home.961504.xyz:10443` | `http://192.168.31.164:3002` | 导航主页直接访问 |
| **🤖 AGY 24h 云端工作台 (`ttyd`+`tmux`)** | `https://agy.961504.xyz` | `https://agy.home.961504.xyz:10443` | `http://192.168.31.164:7681` | Basic Auth: `ixvii0iv` / Mac mini 密码 |
| **🔐 Vaultwarden 私人密码库** | `https://vw.961504.xyz` | `https://vw.home.961504.xyz:10443` | `http://192.168.31.164:8222` | Bitwarden 客户端自托管填入 `https://vw.961504.xyz` |
| **💾 极空间 Z4 NAS** | - | `https://z4.home.961504.xyz:10443`<br/>`https://nas.home.961504.xyz:10443` | `http://192.168.31.185:5055` | 极空间账号密码 |
| **🚀 Clash 路由分流面板** | - | `https://clash.home.961504.xyz:10443` | `http://192.168.31.1:9999/ui` | Basic Auth: `ixvii0iv` / Mac mini 密码 |
| **📡 小米路由器管理后台** | - | `https://router.home.961504.xyz:10443` | `http://192.168.31.1` | Basic Auth + 路由器管理密码 |
| **📈 Uptime Kuma 外部监控哨兵** | `https://status.961504.xyz` | - | `http://104.43.105.243:3001` | 首次打开创建管理员账号 |

---

## 三、 目录结构说明

```text
~/homelab/
├── README.md                           # 全局架构、设备资产与服务入口速查表（本文件）
├── PLAN.md                             # 分阶段实施路线图与任务进度 Checklist
├── CHANGELOG.md                        # 详细操作与配置变更日志（含 17 项变更记录与回滚指令）
├── backups/router/config.yaml.bak      # 小米路由器 ShellCrash 原始配置备份
├── configs/
│   └── router-shellcrash-config.yaml   # 小米路由器 Mihomo 生产分流配置（锁定 AGY 狮城出口）
├── scripts/
│   ├── 01-macmini-init.sh              # Mac mini 防休眠、基础环境与目录初始化脚本
│   ├── cloudflare-ddns.sh              # 每 5 分钟自动更新 *.home.961504.xyz 公网 IP
│   ├── mount-zspace.sh                 # 每 2 分钟巡检并自动挂载极空间 20TB SMB 至 ~/nas
│   ├── start-agy-web.sh                # AGY 云端 Web 工作台 (ttyd + tmux) 常驻启动脚本
│   └── backup-to-nas.sh                # 每天 03:30 自动打包备份核心数据至极空间 Z4
└── stacks/
    ├── gateway/                        # Mac mini 10443 泛域名 HTTPS 网关 (Caddyfile + Let's Encrypt 证书)
    ├── azure-edge/                     # SG Azure 443 免端口 HTTPS 边缘网关与 Uptime Kuma 编排
    ├── sun-panel/                      # 家庭统一导航面板 Docker Compose 与 SQLite 数据
    ├── vaultwarden/                    # Vaultwarden 私人密码保险箱 Docker Compose
    └── wechat-bot/                     # 微信双向控制网关代码（已按需暂停保留）
```