客户端接入总览
本文作为 AgentMeshOS 全平台客户端与节点接入的统一入口页。当前文档站继续沿用既有 docs/*.md + MkDocs Material + GitHub Actions + GHCR + 主节点受控 deploy 架构，不引入新的客户端子站或平行文档体系。
📚 目录
📌 结论摘要
截至 2026-10-05，Headscale 共登记 15 台节点，其中 11 台在线、4 台离线。在线节点是 rr、101、102、d02、mm、home、dd、dog-public、nas-sz、little-s20 和 honor-magic2；全部在线 Tailnet 节点当前均有直接路径，Relay=agentmeshos-mm 只保留为 DERP 兜底能力。完整地址、SSH 端口、实时状态和身份回读证据统一以 节点名称与别名 为准，本页只负责说明不同平台应如何接入。
🧩 页面定位
本次继续沿用现有文档站栈的原因如下：
| 方案 | 可维护性 | 部署复杂度 | 性能 | 团队学习成本 | 后续扩展 |
|---|---|---|---|---|---|
沿用当前 docs/*.md + MkDocs |
与现有文档站一致，最容易长期维护 | 最低，只需更新导航并走现有发布链路 | 对说明页面足够 | 最低，团队已在使用 | 可继续扩展 Linux、Windows、macOS、iOS、Android |
| 单独新增客户端站点 | 文档边界更独立，但会增加运维面 | 高，需要新增 Dockerfile、部署脚本、CI 和导航入口 | 性能收益不明显 | 更高，要维护第二套站点 | 内容极多时才值得再评估 |
| 回写首页或脚本库零散段落 | 改动最小，但结构会很快变乱 | 低 | 无差异 | 低 | 扩展性最差，后续平台越多越难找 |
因此当前选择仍然是：在现有文档站内，为每个平台保留单独页面和单独导航入口。
🗂️ 当前拆分结构
- 节点角色与能力矩阵：五类平台共同遵循的角色、资源池、授权层级和任务边界；先确定节点能做什么，再进入对应平台的接入步骤。
- Linux 接入：当前已验证的 Linux Worker / 节点接入路径，包含 Headscale 接入脚本、适用边界与后续 Nomad 衔接说明。
- Windows 接入：当前已验证的稳定路径，包含首次安装与接入 Headscale、PowerShell 恢复命令、Exit Node、验收命令和中国网络环境说明。
- macOS 接入：当前先保留页面结构、接入边界和待补项，后续补齐正式操作步骤。
- iOS 接入：当前先保留页面结构、接入边界和待补项，后续补齐正式操作步骤。
- Android 接入：当前先保留页面结构、接入边界和待补项，后续补齐正式操作步骤。
- Android 节点评估与试点：逐台记录 Android 设备信息、边缘能力、完整 Linux 可行性和低优先级 Worker 试点证据。
- 临时 Support Tailnet 与 SSH 技术支持：明确授权的临时电脑接入、SSH 支持、撤销和清理流程。
🌐 当前统一边界
- 当前控制面：
https://mesh.yohan.fun - 当前代理订阅：
https://proxy.yohan.fun/sub/agentmeshos-main?format=clash - 当前代理 Master：
https://proxy.yohan.fun/app/ - 当前节点面板：
panel-mm、panel-d02、panel-dog、panel-dd的.yohan.fun/app/ - 当前 Tailnet 在线节点：
rr/100.64.0.1、101/100.64.0.2、dog-public/100.64.0.3、102/100.64.0.4、d02/100.64.0.5、mm/100.64.0.6、home/100.64.0.7、little-s20/100.64.0.8、dd/100.64.0.9、nas-sz/100.64.0.10、honor-magic2/100.64.0.13 - 当前离线客户端：Mac mini /
100.64.0.14、Summer /100.64.0.12、benson-nb /100.64.0.15、OfficeSummer /100.64.0.16 - 当前公网 Nomad 入口：
https://nomad.yohan.fun/ui/ - 当前网络环境重点：已验证中国网络环境下可能同时遇到 DNS 污染、UDP 打洞不稳定、控制面不可达、国际站点访问异常和系统网络策略差异。
🧭 平台拆分原则
- 每个平台保留独立页面、独立导航入口和独立正文，避免把 Linux、Windows、移动端和桌面端混在一篇长文中。
- 平台接入不等同于资源授权。节点角色、稳定计算池、移动边缘能力和任务限制统一以 节点角色与能力矩阵 为准。
- 已有稳定方案的平台先写成正式操作文档；尚未完整验证的平台先保留架构、边界、风险和待补项。
- 后续若需要新增 iPadOS、Windows Worker、特定品牌 Android 或企业受管 macOS，可继续在本分类下扩展，不改整体导航结构。
🧪 当前统一归类口径
后续所有设备接入后，不再只问“有没有在线”，而是统一先判定它属于哪一类：
| 类别 | 通俗解释 | 典型平台 |
|---|---|---|
| 完整节点 | 这台设备已经能被系统稳定使用，不只是在线，而且能提供正式遥测或正式运行时 | Linux Worker |
| 半节点 | 这台设备已经接进来了，能看见、能识别，但还不能当成正式算力或正式遥测节点 | Windows、macOS、iOS 客户端 |
| 边缘节点 | 这台设备有现场能力，但只能按需执行短任务，不能当长期稳定 Worker | Android 手机 |
这三类的细分标准、升级门槛和长期边界统一以 节点角色与能力矩阵 为准。
🌐 P17 代理网络客户端
代理网络客户端与 Tailnet 节点接入是两条独立通道。代理客户端消费 Clash/Mihomo 订阅，只负责公网出口选择；Tailscale/Headscale 继续负责节点管理、SSH 和遥测。两者可同时安装，但不得互相冒充为对方的客户端或控制面。
| 平台 | 客户端 | 版本 | 接入方式 | 当前验收状态 |
|---|---|---|---|---|
| Windows x64 | Clash Verge Rev | v2.5.7 |
导入同一 Clash 订阅，选择 Proxy / Auto |
Home 与 OfficeSummer 已刷新五台 Reality profile；新订阅下的逐台故障切换仍需补测 |
| Android | Clash Meta for Android | v2.11.35 |
导入同一 Clash 订阅，选择 Proxy / Auto |
S20 与 Magic2 当前离线，Clash Meta 五台 Reality 订阅刷新与切换待执行 |
| iOS / iPadOS | Stash | 3.4.1 |
App Store 安装后导入同一 Clash 订阅 | 当前无在线真机；商品元数据已归档，五台 Reality 切换验收待执行 |
客户端策略固定为 Auto: fallback，顺序是 MM -> d02 -> dog -> DD -> RR。判断节点是否健康的是客户端自身，不是 VPS 自报在线；切换只影响新连接，已有连接不会迁移。Mihomo fallback 当前实测能按顺序选择健康备用，但不能保证健康备用在 MM 恢复后自动回到 MM；严格自动回切口径以 360T7 的 Xray 主 Balancing + 后备 Balancing 为准。完整安装说明、官方来源和 File-Hub 长期目录备份记录见项目路径 assets/proxy-network-clients/README.md。
✅ 当前项目的直接结论
截至 2026-10-03，当前项目应这样理解：
- Linux 完整节点：
rr、mm、dd、101、102、d02、dog-public和 NAS 已按职责接入；继续扩稳定计算池时优先增加compute-generalLinux Worker。 - 公网边缘：
mm仍是当前edge.yohan.fun的正式实现节点；d02与dog-public已有独立公网入口和edge-gateway能力，但正式接管必须另开切换窗口。 - Windows 管理终端：属于半节点，重点是管理、排障、受控测试，不作为生产 Worker。
- macOS：当前按半节点规划，后续主要承接 Apple 构建与测试，不直接混入 Linux 生产池。
- iOS：当前按半节点规划，主要做移动观察、审批和控制入口。
- Android：当前按边缘节点规划，重点做网络探测、定位、相机、传感器等短任务，不把 Android 系统本身当稳定通用 Worker。
🔜 当前推荐推进顺序
为了避免同时开太多线，后续建议按这个顺序推进：
- 先把所有非 Linux 平台的“在线但未接入遥测”状态解释清楚，并在状态页保持清晰呈现。
- 再决定 Windows 与 macOS 是否值得补跨平台资源遥测。
- Android 继续走边缘节点路线，优先做短任务闭环和授权边界，而不是继续折腾 Android 本体 Linux 化。
- iOS 补正式接入与观察终端说明。
- 真要扩稳定计算池时，优先新增标准 Linux Worker；手机硬件改 Linux 只做单机试点，不作为当前主线。
📊 当前状态矩阵
| 平台 | 页面状态 | 当前内容状态 | 后续补充方向 |
|---|---|---|---|
| Linux | 已拆分 | 已有稳定接入说明；默认生产 Worker 候选 | 继续补充节点角色差异、Nomad Client 衔接和脚本边界 |
| Windows | 已拆分 | 已有稳定管理终端说明与正式接入命令；不作为生产 Worker | 继续补充遥测、长期 SSH 跳板和更细化故障排查 |
| macOS | 已拆分 | 架构占位；后续定位为受控构建与测试节点 | 补充客户端安装、权限、路由与验证步骤 |
| iOS | 已拆分 | 架构占位；后续定位为移动控制与观察终端 | 补充 App 接入、蜂窝网络行为、DNS 与 Exit Node 说明 |
| Android | 已拆分 | 最小接入已验证；默认是按需移动边缘能力节点 | 继续逐台评估硬件、后台行为与完整 Linux 可行性，补充边缘能力与故障排查步骤 |
🧩 使用原则
- 浏览器和普通客户端访问公网入口时不追加内部
39xxx端口。 - MM 负责公网 TLS 和域名路由；
rr承载控制面与多数后端，dd承载 Cloudreve 数据面，102 承载当前生产 OmniRoute。不能继续用“所有后端都在主节点”这一旧口径描述现状。 - Linux、Exit Node、DNS、代理、系统路由和本地办公软件冲突，应在各平台页面单独说明，不混写成一套统一命令。
- 新平台接入前，先确认当前页面架构、导航入口和计划状态，再补充真实验收后的操作步骤。
⚠️ 未决项 / 需要决策
| 未决项 | 当前事实 | 下一步 |
|---|---|---|
| 离线客户端重新接入 | Mac mini、Summer、benson-nb、S20、Magic2 当前离线；OfficeSummer 已重新上线并完成订阅刷新 | 上线后从 节点名称与别名 重新核验身份、地址、SSH 和管理密钥，并执行五台 Reality 订阅刷新 |
| 历史移动节点 | redmi-3s 与旧 office-iphone 已不在当前 Headscale 权威表 |
重新接入时分配新地址，不复用旧地址 |
| 公网边缘切换 | d02、dog-public 可作为候选，但当前没有自动切换 DNS 或 Nginx |
生产接管必须由用户确认窗口并按回退方案执行 |