客户端接入总览

本文作为 AgentMeshOS 全平台客户端与节点接入的统一入口页。当前文档站继续沿用既有 docs/*.md + MkDocs Material + GitHub Actions + GHCR + 主节点受控 deploy 架构，不引入新的客户端子站或平行文档体系。

页面定位

本次继续沿用现有文档站栈的原因如下：

方案	可维护性	部署复杂度	性能	团队学习成本	后续扩展
沿用当前 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
• 当前 Tailnet 关键节点：
• 主节点：agentmeshos-main / 100.64.0.1
• 中继 / 公网出口候选：agentmeshos-worker-mm / 100.64.0.6
• 当前公网 Nomad 入口：https://nomad.yohan.fun/ui/
• 当前网络环境重点：已验证中国网络环境下可能同时遇到 DNS 污染、UDP 打洞不稳定、控制面不可达、国际站点访问异常和系统网络策略差异。

平台拆分原则

• 每个平台保留独立页面、独立导航入口和独立正文，避免把 Linux、Windows、移动端和桌面端混在一篇长文中。
• 平台接入不等同于资源授权。节点角色、稳定计算池、移动边缘能力和任务限制统一以 节点角色与能力矩阵 为准。
• 已有稳定方案的平台先写成正式操作文档；尚未完整验证的平台先保留架构、边界、风险和待补项。
• 后续若需要新增 iPadOS、Windows Worker、特定品牌 Android 或企业受管 macOS，可继续在本分类下扩展，不改整体导航结构。

当前统一归类口径

后续所有设备接入后，不再只问“有没有在线”，而是统一先判定它属于哪一类：

类别	通俗解释	典型平台
完整节点	这台设备已经能被系统稳定使用，不只是在线，而且能提供正式遥测或正式运行时	Linux Worker
半节点	这台设备已经接进来了，能看见、能识别，但还不能当成正式算力或正式遥测节点	Windows、macOS、iOS 客户端
边缘节点	这台设备有现场能力，但只能按需执行短任务，不能当长期稳定 Worker	Android 手机

这三类的细分标准、升级门槛和长期边界统一以 节点角色与能力矩阵 为准。

当前项目的直接结论

截至 2026-07-16，当前项目应这样理解：

• Linux Worker：属于完整节点，继续扩稳定计算池时优先增加这类节点。
• Windows 管理终端：属于半节点，重点是管理、排障、受控测试，不作为生产 Worker。
• macOS：当前按半节点规划，后续主要承接 Apple 构建与测试，不直接混入 Linux 生产池。
• iOS：当前按半节点规划，主要做移动观察、审批和控制入口。
• Android：当前按边缘节点规划，重点做网络探测、定位、相机、传感器等短任务，不把 Android 系统本身当稳定通用 Worker。

当前推荐推进顺序

为了避免同时开太多线，后续建议按这个顺序推进：

1. 先把所有非 Linux 平台的“在线但未接入遥测”状态解释清楚，并在状态页保持清晰呈现。
2. 再决定 Windows 与 macOS 是否值得补跨平台资源遥测。
3. Android 继续走边缘节点路线，优先做短任务闭环和授权边界，而不是继续折腾 Android 本体 Linux 化。
4. iOS 补正式接入与观察终端说明。
5. 真要扩稳定计算池时，优先新增标准 Linux Worker；手机硬件改 Linux 只做单机试点，不作为当前主线。

当前状态矩阵

平台	页面状态	当前内容状态	后续补充方向
Linux	已拆分	已有稳定接入说明；默认生产 Worker 候选	继续补充节点角色差异、Nomad Client 衔接和脚本边界
Windows	已拆分	已有稳定管理终端说明与正式接入命令；不作为生产 Worker	继续补充遥测、长期 SSH 跳板和更细化故障排查
macOS	已拆分	架构占位；后续定位为受控构建与测试节点	补充客户端安装、权限、路由与验证步骤
iOS	已拆分	架构占位；后续定位为移动控制与观察终端	补充 App 接入、蜂窝网络行为、DNS 与 Exit Node 说明
Android	已拆分	最小接入已验证；默认是按需移动边缘能力节点	继续逐台评估硬件、后台行为与完整 Linux 可行性，补充边缘能力与故障排查步骤

使用原则

• 浏览器和普通客户端访问公网入口时不追加内部 39xxx 端口。
• MM 只负责公网 TLS、域名路由和必要的反代深度配置；主节点继续承载全部后端服务。
• Linux、Exit Node、DNS、代理、系统路由和本地办公软件冲突，应在各平台页面单独说明，不混写成一套统一命令。
• 新平台接入前，先确认当前页面架构、导航入口和计划状态，再补充真实验收后的操作步骤。