MoonShade 是一台自组 Mini-ITX 一体机，不是买来的成品 NAS。立项动机是三件事叠在一起：数据主权（照片「真身」握在自己盘里）、省掉云订阅（一次性硬件投入换长期不按月付费）、完全掌控（自己攒、自己定架构）。核心诉求写成一句话——桌面级性能 × 服务器级静音功耗 × 卧室可接受噪音。

选择自己攒而不是买成品，代价很清楚：要自己选料、自己装、自己维护。换回来的，是这几样成品机不容易同时给到的东西——核显硬件加速、跑得动完整 Docker 服务栈加机器学习负载、系统盘与数据盘物理分离、以及 ZFS 的完全自主。这台机器还兼一个身份：它自己托管着一个 AI agent 运行时（OpenClaw），由那个 agent 实例充当「NAS 管家」，日常看护这台机器的运维。

这张网有几条让它「省心」的性质：节点之间点对点直连（打洞成功后走公网直连而非中转），每台设备拿一个固定的私有地址（100.x 段，换 Wi-Fi 也不变），可以用主机名代替 IP 访问，不需要任何公网端口转发，而且「设备连进这张网」本身就等于完成了一次设备级身份认证。最后一条尤其关键——它让后面第 6 段的「透明单点登录」几乎零成本。

内存给了 16GB（系统可见 14GiB）加 4GiB swap。轻载常态下 used 约 3.6GiB、大量空闲页拿去做文件系统缓存——8 容器加照片库机器学习并发时到底够不够，留到第 10 段用实测峰值正面回答。

ZFS 在这台机器上解决三件普通文件系统解决不了的事。一是端到端校验和：机械盘长期存放会有静默位翻转，普通文件系统读到坏数据照样返回给你，ZFS 每次读都验校验、有冗余就自动修，还能主动 scrub 全盘扫一遍。二是软件 RAID：tank 用 4 盘 RAID-Z1，拿一块盘的空间换奇偶校验，任意单盘挂掉数据仍在、换盘可重建。三是秒级快照：copy-on-write，创建瞬间完成、初始不占空间，之后只按变化量长——tank/backup 上保着最近约 30 天的每日时间点（数据库 dump 另按 14 天滚动）；每个增量只有几百 K，却能把整库还原到任意一天。采集时两池都是 ONLINE、0 读错 / 0 写错 / 0 校验错。

贯穿这一栈的是两条取向：私有优先——所有服务 tailnet-only、不开公网端口、统一走受信 HTTPS 门户；数据主权 + 能自己造就自己造——照片真身都落在自家 ZFS 盘，能自研的门面坚持无框架零依赖手写，现成方案只作兜底。下一段说清「不开公网」到底怎么做到的。

接入层——不可从公网访问。它只加入一张私有 mesh VPN（Tailscale / WireGuard）。主机防火墙（ufw，active）入站收得极紧：只放行回环口、mesh 虚拟网卡、WireGuard 握手端口，普通局域网入站一律拒绝——即便某个服务在进程层监听 0.0.0.0，ufw 在网络层也会把 LAN 来源的包直接丢掉（容器发布端口是例外：docker 会自行改写 iptables 绕过 ufw，这层由另一条自建守卫链兜底、把发布端口重新锁回 tailnet-only，详见第 9 章「网络收口」）。受信 HTTPS 层——绿锁、无 IP、无警告。入口用 mesh VPN 自带的反向代理，跑在已存在的 VPN 守护进程里，不新增进程、容器或内存开销；tailnet 给节点 FQDN 自动申请并续期 Let's Encrypt 受信证书。因为浏览器不按端口区分信任，同一域名下每个高端口都是绿锁——门户、两套照片库、文件管理、SSO 各占一个受信入口。

有一处工程细节值得记：docker 容器本身不是 tailnet 节点，够不到 tailnet-only 的入口端口；而 OIDC 的 issuer（签发者 URL）只能是一个值，浏览器跳转和后端换 token 都得用它。解法是让身份提供方自持一张对 FQDN 有效的受信证书，再用 docker 网络别名把它挂进照片库所在的容器网络——这样容器内和浏览器侧都够到同一个受信 URL，issuer 保持一致。另外，文件管理器特意不接自动 SSO（它挂了整盘，自动登录一旦被滥用等于「任何设备自动拿到全盘管理员」），并被改成只绑 127.0.0.1。

那个在途守卫本身还踩过一个很典型的坑：同步任务是 oneshot 类型，跑的时候状态是 activating 而不是 active；早期版本只认 active，导致「正在跑」反而被当成空闲、照样重启。修复后把中间态也显式算作「在跑」——这正是 fail-closed 该有的样子。

第二条监控流走的是另一套思路：每台主机各跑一个零依赖的 Python /status 端点，经 tailnet 反代出受信 HTTPS，读路径免 token、零成本。架构上没有中心聚合器——门户前端在浏览器里并行 fetch 各端点、自己拼装渲染，用 Promise.allSettled 包全队，一台失败不拖累其它。第三条是门户本体，分四层：

这三条流共享一套设计哲学：凭据永不进前端；重活在后台各自定时跑，一条流慢或挂不拖累另一条；强容错优先——字段可缺、值可为 null、一台/一源失败不拖垮整页。这不是可选项，是家用异构系统现实约束下的必须项。整站无框架、无构建，纯静态加一个零依赖 Node 服务器，图的就是长期低维护、不吃 npm 生态的版本腐坏。

起点：寄居在 Windows 里。NAS 那个 agent 实例最早只是跑在一台 Windows PC 的 WSL2 里的运行时——记忆和会话历史与宿主环境深度耦合在半虚拟层，这台机器既不专职存储、也不适合长期无人值守。决策：整机重装成裸机 NAS，但只要记忆能留下。关键的范围决策是「只保留 agent 的纯记忆核心（约 134MB / 1400 个文件），其余环境性的东西全丢、新机重设」。迁移不做整盘镜像，而是冷快照：停机、narrow-rsync 只抓记忆目录、打包压到 19MB、生成逐文件 sha256 清单，快照留一周观察期后才准删。

重装后，三层物理隔离。系统盘（装 OS + agent 记忆）、快取池、数据池分开，第一性原则是「池炸了 ≠ agent 失忆」。存储最初选了零冗余的 RAID 0，一轮复核标出「任何一块盘坏就全没」的风险后改成 RAID-Z1，牺牲一块盘容量换单盘容错；组池用 /dev/disk/by-id/ 全名而非会变的 /dev/sdX，避免重启后 degraded。一个诚实的已知取舍：那 4 块是 SMR 盘，换盘重建会慢，于是约定未来「4 盘一起换」绕开单盘 resilver。网络收口时还发现 Docker 会绕过系统防火墙自己改 iptables 把容器端口暴露到 0.0.0.0，于是加了一条自建守卫链把所有发布端口重新锁回 tailnet-only——这条守卫是后面所有服务能安心用 0.0.0.0 端口的前提。

服务也是一层层长出来的，不是一次铺开：先是照片主库（自托管相册 + 从手机云端自动归档），发现主库缩略图引擎读不了 RAW 全是裂图，才加了专读 RAW 的第二套；有了照片要管文件，才有网页文件管理器；服务多到记不住 IP，才有统一门户；门户想要能自己改，才把它逆向重写成无框架的自研 v2；多台机器要一屏看状态，才有了那套零成本监控。中途还插进一轮多 agent 并行的大 code review——几十条 finding 分批修（存储型 XSS 收口、监控不再把真宕机伪装成 LIVE、大视频拷贝原子化、在途守卫的 oneshot 漏检改成 fail-closed），修完达到「零 failed 单元、open PR 清零」的干净状态。月度 ZFS scrub 也是在一次评估发现两个池疑似从未 scrub 过之后才补上的。