CLAUDE.md — 家庭网络部署与运维手册
权威声明：本文档是家庭网络的唯一权威（2026-09-12 用户确认）。Obsidian 旧笔记若与本文冲突，以本文为准；冲突清单见 §11。
生成方式：2026-09-12 由 DSH agent 实测（SSH/端口扫描/容器与配置读取）+ 用户答题卡确认生成，版本 v1.0。
维护约定：用户口径是「遇见就更新」——每次改动后同步更新对应表格，并在 §12 变更记录 追加一行。
状态标记：✅ 实测确认 📌 来自用户答复 ⚠️ 待确认（我未证实，不要当事实用）
0. 30 秒速查
| 我想要… |
去哪里 |
| 改路由/宽带/端口/DHCP/DNS 下发 |
iKuai http://10.10.10.253（VM100，凭据位置见 §10.1） |
| 科学上网 / 旁路由 / Samba |
iStoreOS ssh istore → http://10.10.10.252（VM101） |
| 看/重启家庭主服务 |
CentOS 服务机 ssh centos → http://10.10.10.14（VM104） |
| 管虚拟机、备份、看宿主机 |
PVE https://10.10.10.254:8006（ssh pve） |
| 存储/相册/下载/时光机 |
群晖 Princess http://10.10.10.23:5000（ssh nas） |
| 容器可视化管理 |
Portainer 群晖 http://10.10.10.23:9000，服务机 agent 10.10.10.14:9001 |
| 域名反代/内网穿透面板 |
Lucky http://10.10.10.24:16601（VM103） |
| 智能家居 |
Home Assistant http://10.10.10.2:8123（VM105） |
| 在外网进家里 |
ZeroTier（主通道，见 §6）；Cloudflare Tunnel / FRP（备用，见 §6.3） |
| 服务健康监控 |
Uptime Kuma http://10.10.10.14:33001 |
| 定时任务面板 |
青龙 http://10.10.10.14:15700 |
一句话架构：光猫桥接 → iKuai(VM) 双线拨号 → 2.5G 交换机 → PVE 宿主机跑 6 台虚拟机（路由/服务/存储/智能家居）＋群晖 NAS；无公网 IPv4，外网访问靠 ZeroTier（家庭侧网关＝群晖上的 ZT 容器）。
1. 物理与线路
| 项 |
现状 |
| 家庭网段 |
10.10.10.0/24，单网段、无 VLAN 📌 |
| 网关 |
10.10.10.253 = iKuai（PVE 里的 VM100） |
| 宽带 |
电信 + 联通 双线，光猫桥接，iKuai 拨号 📌 |
| 公网 |
无公网 IPv4；有 IPv6（群晖已拿到 240e:338:37:3041::/64）📌 |
| 双线策略 |
iKuai 上做负载均衡 📌 |
| 无线 |
TP-Link TL-7DR7270（10.10.10.11）做有线中继，SSID Sweet_home 📌 实测 |
| 交换机 |
5 口 2.5G 非网管 📌 |
结论性提示：没有公网 IPv4 ⇒ 任何"端口映射到公网"的方案都不成立，远程访问只能是 VPN/隧道（§6）。IPv6 是唯一"理论上可直连"的路径，但当前没有对外暴露服务。
2. 主机清单（实测地址）
| IP |
身份 |
形态 |
管理入口 |
可重启性 |
10.10.10.253 |
iKuai 主路由 |
PVE VM100 |
Web 80/443 |
⛔ 全家断网单点 |
10.10.10.254 |
PVE 宿主（VUModule） |
物理 |
Web 8006 / ssh pve |
⛔ 承载一切 |
10.10.10.252 |
iStoreOS 旁路由 |
PVE VM101 |
Web / ssh istore |
🟡 断科学上网+文件共享 |
10.10.10.16 |
WireGuard |
PVE VM102 |
SSH |
🟡 断 WG 连接 |
10.10.10.24 |
Lucky |
PVE VM103 |
Web 16601 |
🟡 断反代/穿透 |
10.10.10.14 |
CentOS Stream 10 服务机 |
PVE VM104 |
ssh centos / 宝塔 29012 |
🟡 断 14 个容器服务 |
10.10.10.2 |
HAOS / Home Assistant |
PVE VM105 |
Web 8123 |
🟢 断智能家居 |
10.10.10.23 |
群晖 Princess DS716+II |
物理 |
Web 5000/5001 / ssh nas |
🟡 断存储；ZT 入口也在它上面 |
10.10.10.11 |
TP-Link TL-7DR7270 无线中继 |
物理 |
Web 80 |
🟡 断 Wi-Fi |
10.10.10.19 |
未知，只开 53（DNS） |
物理（MAC 78:11:dc:e3:c2:99，非 PVE VM） |
— |
⚠️ 待确认 |
10.10.10.26 |
未知，开 22 + 5000（疑似另一台群晖/NAS） |
物理 |
— |
⚠️ 待确认 |
10.10.10.29 |
Euphony Web（音乐串流，v4.20250205） |
物理 |
Web 80 |
⚠️ 用途待确认 |
10.10.10.21 |
未知，能 ping 通、22 拒绝（ssh mini 别名指向它但连不上） |
物理 |
— |
⚠️ 待确认 |
10.10.10.1 / .9 |
不存在（笔记里的「VUM-HOME 10.10.10.1」和「Mac mini 10.10.10.9」均 ping 不通） |
— |
— |
📌 旧笔记错误 |
10.10.10.3 / .4 / .5 / .6 / .7 |
家庭杂项电子设备，用户不掌握 📌 |
物理 |
— |
⚠️ 待确认 |
本机 Mac（跑 DSH 的这台）当前不在家庭网段（en0 = 192.168.7.90），完全靠 ZeroTier 进家庭网。
3. 虚拟化层：PVE 10.10.10.254
| 项 |
实测 |
| 版本 |
pve-manager 9.2.11（Debian 13），内核 7.0.14，主机名 VUModule |
| 硬件 |
倍控 N355，16G DDR5，Kingston SNV2S500G 单条 NVMe 465.8G |
| 存储 |
LVM-thin 无，local(dir) 457G 用 52%（224G/457G），单盘、无 RAID |
| 网桥 |
vmbr0 = enp1s0，address 10.10.10.254/24，网关 10.10.10.253 |
| 备份 |
每日 01:00，全部 VM，zstd，snapshot 模式，keep-last=2 keep-weekly=1，存 local（/var/lib/vz/dump） |
| 其他 |
核显仅服务宿主机，无直通 |
3.1 虚拟机（全部 onboot=1 开机自启 📌「没有固定谁先起」）
| VM |
名称 |
IP |
MAC |
配置 |
用途 |
| 100 |
iKuai |
.253 |
62:CD:D5:6C:0F:0C |
2C/2G/2G盘 |
主路由；直通 5 个 PCI 设备 02:00.0 03:00.0 04:00.0 05:00.0 07:00.0（4 网卡+1） |
| 101 |
iStoreOS |
.252 |
BC:24:11:69:AC:25 |
1C/1G/2.4G盘 |
旁路由：passwall 已装、openclash 未启用；dnsmasq:53、ttyd:7681、Samba 139/445、NFS 2049；docker 已装无容器 |
| 102 |
WireGuard |
.16 |
BC:24:11:72:55:74 |
2C/1G/5G盘 |
WG 服务端 ⚠️ 客户端数/端口待确认 |
| 103 |
Lucky |
.24 |
BC:24:11:72:55:76 |
2C/1G/5G盘 |
反代/穿透/证书面板（16601） |
| 104 |
Centos10 |
.14 |
BC:24:11:D1:C7:7F |
4C/6G/100G |
家庭服务主力（见 §4） |
| 105 |
HAOS |
.2 |
BC:24:11:8B:1A:74 |
2C/2G/32G盘 |
Home Assistant |
3.2 PVE 红线
- 管理网口
enp1s0/vmbr0 绝不直通（否则宿主机失联）——iKuai 已直通 5 个 PCI 设备，这是它的口粮，别再加进 PVE 管理网。
- 单盘 NVMe：VM 和备份在同一块盘上，磁盘挂 = 全丢。异地备份未做（§11 建议）。
- 改
/etc/network/interfaces 前先 cp 备份；改完用 ifreload -a。
4. 家庭服务主力：CentOS VM104 10.10.10.14
⚠️ 用户答复「除群晖和 PVE 外没有别的机器跑 Docker」，实际这台就是 Docker 主力（14 个容器）；按实测记录为准。
| 容器 |
端口 |
用途 |
pihole |
53(tcp/udp) / 80 |
内网 DNS 之一（标题 Pi-hole 00f787d79a88） |
cloudflared-tunnel |
— |
Cloudflare 隧道出网（外网访问备用通道） |
searxng-core + searxng-valkey |
8080 |
自建搜索 |
alist |
5244 |
网盘聚合 |
clouddrive2 |
19798 |
云盘挂载 |
portainer_agent |
9001 |
供群晖 Portainer 统一管理 |
omni-tools |
8081 |
在线工具箱 |
frpc_mpsf |
— |
FRP 客户端（配置 /www/dk_project/dk_app/frpc/frpc_mpsf/data/frpc.toml） |
panhub |
3067 |
网盘搜索 |
uptime_kuma |
33001 |
服务监控（监控项/告警渠道 ⚠️ 待确认） |
qinglong_bwbz |
15700 |
定时任务（青龙） |
watchtower-updater |
— |
容器自动更新 📌（用户确认走 Watchtower） |
libretv |
8899 |
影视聚合 |
moontv |
2000 |
影视聚合 |
| 宝塔面板 BT-Panel |
29012 |
面板管理（compose 项目根 /www/dk_project/dk_app/…） |
| pure-ftpd |
21 |
FTP |
- 其他 compose 位置：
/opt/searxng/docker-compose.yml、/home/wechat-selkies/docker-compose.yml、/opt/alist、/home/CloudNas、/home/www
- 登录：
ssh centos（专用密钥 ~/.ssh/10.10.10.14_id_ed25519）
- 注意：这是 KVM 虚拟机，Docker 另有
br-* 网段（172.21/172.31/192.168.48）
5. 群晖 Princess 10.10.10.23
| 项 |
实测 |
| 机型 |
DS716+II（synology_braswell_716+II，内核 3.10.108），主机名 Princess |
| 阵列 |
RAID1 ×3：md0 8G(系统) / md1 2G / md2 3.9T；卷 volume1 = 3.5T，用 431G（13%） |
| 网络 |
bond0（双网口聚合），默认路由指向 10.10.10.252（iStoreOS 旁路由） |
| 容器 |
portainer(8000/9000/9443)、zt = ZeroTier(远程入口)、baiduapp(8092)、synology_docviewer×2 |
| 套件 |
ContainerManager、qBittorrent、DownloadStation、SynologyPhotos、AudioStation、WebDAVServer、CloudSync、Komga、NASTool、yt-dlp、rclone、SynoFinder、SMBService、LogCenter、ActiveInsight、ScsiTarget、USBCopy、HybridShare 等 |
| 共享目录 |
docker、Download、homes(admin/zhensolid)、logs、music、roon_server、video、YT-DLP、百度同步盘、Time Machine |
| sudo |
用户 zhensolid，密码已由用户提供并在会话/记忆中（本文档不写明文，见 §10.2） |
6. 外网访问与组网
6.1 主通道：ZeroTier（官方 Central 控制 📌）
| 项 |
值 |
| 网络名 / ID |
SolidSnake / 68bea79acf757b6d，MTU 2800 |
| 本机 Mac |
192.168.192.17（接口 feth4093，ZT 端口 9993） |
| 家庭侧网关 |
群晖上的 zt 容器 → 192.168.192.48（接口 zt6jy5fync） |
| 托管路由 |
10.10.10.0/24 → 本机路由表：via 192.168.192.48 dev feth4093 |
| 群晖侧转发 |
net.ipv4.ip_forward=1；iptables -t nat -A DEFAULT_POSTROUTING -o zt6jy5fyn -j MASQUERADE |
路径：Mac(192.168.192.17) → ZT → 群晖 zt 容器(192.168.192.48) → 家庭 10.10.10.0/24。
- ⚠️ 本机
/Library/Application Support/ZeroTier/One/controller.d/ 目录存在（历史自建控制器的残留痕迹），但用户确认用的是官方 Central——两者关系待确认，动 ZT 前先确认，别误删。
- 实测 192.168.192.0/24 里只有
.17(Mac) 和 .48(群晖) 响应，其他成员要么下线要么禁 ICMP。
6.2 备用通道（在服务机 VM104 上）
- Cloudflare Tunnel：
cloudflared-tunnel 容器在跑（隧道名/绑定域名 ⚠️ 待确认）。
- FRP：
frpc 容器，配置 frpc.toml，服务端 ⚠️ 待确认（VPS 有 king/princess/aliyun/tx6us）。
- WireGuard：VM102(
10.10.10.16) 另有一套 ⚠️ 用途边界待确认。
组网方案有 3～4 套并存（ZT/WG/CF/FRP）。日常用 ZeroTier；排障时先分清是哪条链路，别同时改多套。
6.3 排障：跨网段访问断了
- 本机看 ZT 是否在线（ZeroTier 应用菜单 → 网络状态；
zerotier-one 进程 + 端口 9993）。
- 群晖上确认
zt 容器在跑（ContainerManager / docker ps）。
- 群晖上
ip route 检查是否出现抢路由的 scope link 条目（这是笔记里踩过的坑：10.10.10.0/24 dev zt6jy5fync scope link 这类会顶掉真正的网关路由）→ 用 ip route del 清掉对应条目后 ip neigh flush dev zt6jy5fync。
- 若只是某个服务不通，按 §8.4 的四层法定位。
7. 内网 DNS（三处并存，注意别改错）
| 位置 |
服务 |
端口 |
10.10.10.14 |
Pi-hole（容器） |
53 tcp/udp，Web 80 |
10.10.10.252 |
iStoreOS dnsmasq |
53（含 172.17.0.1:53） |
10.10.10.19 |
未知设备 |
53 ⚠️ |
- ⚠️ iKuai 的 DHCP 到底把哪个 IP 下发给客户端，尚未确认——这是「改了 DNS 没生效」类问题的第一处排查点。
- 旧笔记里有 AdGuard Home + SmartDNS + PassWall 的配置记录，当前未在 .14/.252 上运行（实测无该进程/端口）。
8. 运维流程（步骤式）
8.1 服务更新
- 容器：由 Watchtower 自动拉取更新（服务机 VM104）；异常时看
watchtower-updater 日志。
- 手动更新某个服务：SSH 进
centos → 定位 compose 目录（宝塔项目在 /www/dk_project/dk_app/<应用>/<应用>_<hash>/，其余在 /opt/<应用>、/home/<应用>）→ 拉镜像重建 → 看容器日志确认起来。
- 更新前建议先确认该服务的配置/数据卷挂载路径（都在 compose 文件里），必要时先导出配置。
8.2 系统更新
- PVE 宿主：Web 8006 → 节点 → 更新；内核更新后需重启宿主（会带走全部 VM，先确认家人不用网）。
- VM 内（iStoreOS/服务机/HAOS）：各自面板或包管理器更新。
- 群晖：控制面板 → 更新；ContainerManager 里的容器随 Watchtower/手动更新。
- iKuai：Web → 系统 → 升级；改前先导出配置备份。
8.3 备份与校验
- PVE：每日 01:00 自动（全 VM、zstd、保留 2 份 + 1 周）。校验方式：PVE → 节点 → 备份，确认当天文件存在且大小合理（现网单个 VM 备份 6～17G）。
- 群晖：套件里有 CloudSync / HybridShare（⚠️ 具体备份任务清单待确认）。
- 风险点：PVE 备份宿主盘 = VM 盘，属"同盘备份"，不具备容灾能力。
8.4 服务打不开的四层定位法
- DNS：
nslookup 走的是 Pi-hole(.14) / dnsmasq(.252) / .19 哪个？换公共 DNS 试是否恢复。
- 主机：
ping + ssh 目标 IP 是否在（PVE 里 VM 是否 running，qm list）。
- 容器：SSH 到宿主机看
docker ps 目标容器是否 Up、端口是否监听、看日志。
- 入口：Lucky(.24:16601) 反代规则 → Cloudflare Tunnel → FRP，按域名走哪条链路倒推。
8.5 常见故障处理
| 症状 |
处理顺序 |
| PVE 一长三短报警 / 核显死机 |
用户确认的最高频问题。按既有排障笔记：显卡欺骗器常插 HDMI-A-1；核显仅服务宿主显示输出，未直通；先查 BIOS 报警声含义→检查内存/显卡欺骗器→必要时降级显示设置 |
| ZeroTier 不通 |
§6.3 |
| 群晖被 AutoBlock 封 IP |
SSH 进群晖，清 synology_autoblock 库的 AutoBlockIP 表 |
| iStoreOS 内存 1G 跑满 |
它是 1C/1G，重启它（不影响 iKuai 拨号） |
| 断电恢复 |
来电后先起 PVE 宿主 → VM 自动开机（全 onboot=1）→ 群晖自启 → 等 ZT 起来再远程。无 UPS 自动关机脚本 📌，突然断电会让群晖/VM 非正常关机 |
9. 红线与禁忌
| # |
禁忌 |
原因 |
| 1 |
不要碰公司环境：192.168.8.2（EPR 生产群晖）、192.168.6.23（ZLSH_NAS）、192.168.8.37 |
用户明确「不能」；与家庭网无管理关系 |
| 2 |
不要把 PVE 管理网口直通给虚拟机 |
宿主机失联 |
| 3 |
不要重启 iKuai(VM100) 和 群晖 .23 而不打招呼 |
全网单点 / 远程入口单点 |
| 4 |
不要在群晖乱删 ZT 相关路由与容器 |
远程进来全靠它 |
| 5 |
改 iKuai / PVE / 群晖 配置前先导出/备份配置 |
家庭网没有第二套冗余 |
| 6 |
不要同时改多套组网（ZT/WG/CF/FRP） |
排除故障时无法定位 |
10. 凭据与密钥
10.1 凭据存放位置
| 目标 |
位置 |
| iKuai / iStoreOS / (旧)ESXi 后台账号 |
Obsidian《02-家庭实验室/软路由/软路由首页.md》 |
群晖 zhensolid sudo |
用户会话中提供（同一口令亦用于公司群晖运维流程） |
| SSH 免密 |
~/.ssh/config + ~/.ssh/id_ed25519（个别专用密钥：centos→10.10.10.14_id_ed25519、king、princess） |
| Portainer / Lucky / Pi-hole / 宝塔 / Uptime Kuma |
⚠️ 待确认存放位置 |
10.2 关于明文密码
用户勾选了「可以写密码明文」，但本文档默认仍只记录存放位置，未写入任何明文口令（避免文档在 Mac、Obsidian 同步库、agent 上下文中扩散）。
若确需写入明文，告知一声，我会写进一个独立的本地文件（不进 Obsidian 同步库），并在本节指向它。
11. 已知风险、待补项与旧笔记纠错
11.1 风险（按优先级）
- PVE 单盘、备份同盘 → 盘坏 = VM 全丢 + 备份全丢。建议：加一块盘或把
/var/lib/vz/dump 定期同步到群晖（10.10.10.23，还有 3.1T 空闲）。
- 无 UPS 自动关机 → 建议给 PVE 与群晖配 UPS 联动关机。
- iKuai 与群晖 都是单点（路由 / 远程入口）。
- 三处 DNS 并存（Pi-hole / dnsmasq / .19）→ 建议明确一处为主，其余关掉，减少"解析飘"问题。
- 组网 4 套并存 → 建议明确"ZT 为主、其余留作备用"，并记录各自边界。
- iStoreOS 仅 1C/1G，还兼旁路由+科学+Samba+NFS，负载偏重。
11.2 待补项（⚠️ 我无法自行确认）
- iKuai：DHCP 下发的 DNS、端口映射（大概率无）、系统版本、备份策略导出位置
.19 / .26 / .29 / .21 / .3-.7 的设备身份与用途- Cloudflare Tunnel 的隧道名与绑定域名、FRP 服务端是哪台 VPS、WireGuard 的用途与客户端
- Uptime Kuma 监控了哪些、告警发到哪个渠道
- 群晖 Hybrid/CloudSync 备份任务清单、Hyper Backup 是否存在
- 证书现状：群晖默认证书为自签（
CN=synology，2027-07-31 到期）；其他服务（Lucky/CF）证书与续期方式
- 家庭数据"最不能挂的服务"排序、玩具服务名单
11.3 旧笔记纠错（Obsidian 02-家庭实验室）
| 旧笔记说法 |
实测事实 |
ESXI: 10.10.10.254 |
已是 PVE 9.2.11（ESXi 时代结束） |
VUM-HOME: 10.10.10.1 |
10.10.10.1 不存在；网关是 .253 iKuai |
mini = 10.10.10.9（服务器清单）、ssh mini 指向 10.10.10.21 |
.9 不通；.21 可 ping 但 22 拒绝 —— ssh mini 当前不可用，需重新确认 Mac mini 的真实 IP |
| 「除群晖/PVE 外无其它 Docker 主机」 |
VM104 10.10.10.14 是 14 容器的 Docker 主力 |
| 「软路由 .252 = iStoreOS 物理机」 |
它是 PVE VM101 |
| AdGuard Home + SmartDNS + PassWall 在跑 |
仅 passwall 已装；未见 AdGuard/SmartDNS 进程 |
12. 变更记录
| 日期 |
版本 |
变更 |
执行人 |
| 2026-09-12 |
v1.0 |
首版：实测生成主机/服务/组网全景，用户答题卡确认关键口径 |
DSH agent |
