--- slug: "node-connect-tool-pro" name: "node-connect-tool-pro" version: "1.0.0" displayName: "节点连接工具(专业版)" summary: "全拓扑节点连接诊断,含尾网/公网/远程网关、批量配对、审计日志与自动修复。。节点连接工具(专业版)面向团队与运维,提供全拓扑节点连接诊断、批量配对、连接审计日志与一键自动修复能力。核心能力:" license: "Proprietary" edition: "pro" description: |- 节点连接工具(专业版)面向团队与运维,提供全拓扑节点连接诊断、批量配对、连接审计日志与一键自动修复能力。核心能力: - 全拓扑支持:同机器/局域网/Tailscale尾网/公网反代/远程网关 - 批量设备配对与状态管理 - 连接审计日志与回溯 - 一键诊断与自动修复脚本 - 远程网关与多网关节点管理 - 高级鉴权配置(Tailscale Serve/Funnel) 适用场景: - 跨网络团队节点协作 - 远程网关与多区域部署 - 大规模设备配对与运维 - 安全合规要求的连接审计 差异化: - ... tags: - Development - 网络 - 诊断 - 企业级 - 运维 - 安全 - 工具 - 效率 - 自动化 - 监控 - 研究 - 分析 - 写作 - skill-platform - tailscale - gateway - config tools: - read - exec - write homepage: "" category: "Automation" --- # 节点连接工具(专业版) ## 概述 节点连接工具(专业版)面向团队与运维,在兼容免费版本地与局域网诊断能力的基础上,扩展了全拓扑支持(含Tailscale尾网、公网反代、远程网关)、批量设备配对、连接审计日志与一键自动修复脚本. 当你在请求中提及 跨网络节点、远程网关、Tailscale、公网反代、批量配对、连接审计 等关键词时,本工具会自动激活,为团队提供结构化的连接诊断与运维方案. 本版本完全兼容 `node-connect-tool-free` 的本地与局域网诊断流程,可平滑升级,已有检查命令与根因映射无需改造. ## 核心能力 | 能力模块 | 说明 | 与免费版差异 | |----|---|------| | 本地/局域网诊断 | 同机器、同Wi-Fi拓扑诊断 | 与免费版一致 | | 尾网诊断 | Tailscale Serve/Funnel 配置与排查 | 免费版无 | | 公网反代 | 公共URL与反向代理配置诊断 | 免费版无 | | 远程网关 | 远程模式与多网关节点管理 | 免费版无 | | 批量配对 | 多设备同时配对与状态管理 | 免费版仅单设备 | | 审计日志 | 连接事件记录与回溯 | 免费版无 | | 自动修复 | 一键诊断并应用修复脚本 | 免费版仅建议 | | 鉴权高级 | Tailscale鉴权、令牌轮换 | 免费版基础鉴权 | ### 核心功能执行 用`input_params`参数进行配置. **输入**: 用户提供核心功能执行所需的指令和必要参数. **处理**: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回核心功能执行的响应数据,包含状态码、结果和日志. - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 参数配置与调用 用`config_options`参数进行配置. **输入**: 用户提供参数配置与调用所需的指令和必要参数. **处理**: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回参数配置与调用的响应数据,包含状态码、结果和日志. - 执行此能力时使用`config_options`参数,支持修改/重置/导入操作 ### 结果处理与输出 用`output_format`参数进行配置. **输入**: 用户提供结果处理与输出所需的指令和必要参数. **处理**: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回结果处理与输出的响应数据,包含状态码、结果和日志. - 执行此能力时使用`output_format`参数,支持导出/保存/转换操作 **能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：全拓扑节点连接诊、含尾网、审计日志与自动修、节点连接工具、专业版、面向团队与运维、提供全拓扑节点连、接诊断、连接审计日志与一、键自动修复能力、核心能力、全拓扑支持、批量设备配对与状、连接审计日志与回、一键诊断与自动修、远程网关与多网关、高级鉴权配置等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持. ## 使用场景 ### 场景一:Tailscale尾网跨网络协作 团队成员分布在不同网络,通过Tailscale尾网连接节点. ```bash # 标准检查 + 尾网检查 skill-platform config get gateway.bind skill-platform config get gateway.tailscale.mode skill-platform config get gateway.auth.allowTailscale skill-platform qr --json tailscale status --json ``` 常见根因: - `gateway.bind=tailnet set, but no tailnet IP was found`:网关主机未实际加入Tailscale - 修复:在网关主机运行 `tailscale up`,确认 `tailscale status` 显示在线 - 应用提示 `unauthorized`:`gateway.auth.allowTailscale` 与预期流程不匹配 - 修复:对Tailscale Serve流程,设置 `gateway.auth.allowTailscale=true` ### 场景二:公网反代部署 团队通过公网URL与反向代理暴露节点网关. ```bash # 检查公共URL配置 skill-platform config get plugins.entries.device-pair.config.publicUrl skill-platform config get gateway.remote.url # ... # 远程模式QR skill-platform qr --remote --json ``` 常见根因: - `qr --remote requires gateway.remote.url`:远程模式配置不完整 - 修复:设置 `gateway.remote.url=https://gateway.example.com` - 公共URL已设但QR仍广播其他地址:检查 `urlSource`,配置并非你以为的那样 - 修复:确认 `publicUrl` 配置项的优先级,或重启网关使配置生效 ### 场景三:批量设备配对与运维 团队一次性接入大量设备,需要批量配对与状态管理. ```bash # 批量查看所有待配对设备 skill-platform devices list --state pending # ... # 批量批准 skill-platform devices approve --all # ... # 按设备类型筛选 skill-platform devices list --type ios skill-platform devices list --type android # ... # 查看节点状态概览 skill-platform nodes status --summary ``` 工具输出设备状态看板: ```text ## 不适用场景 # ... 以下场景节点连接工具(专业版)不适合处理： # ... - 物理硬件维修 - 网络物理布线 - 数据中心选址 # ... ## 触发条件 # ... 需要系统监控、日志分析、运维告警、部署管理时使用。不适用于非本工具能力范围的需求. # ... ## 设备配对看板 (32台设备) # ... | 设备ID | 类型 | 状态 | 最后连接 | 操作 | |:-----|:-----|:-----|:-----|:-----| | dev-001 | android | 已配对 | 2分钟前 | - | | dev-002 | ios | 待配对 | - | 批准 | | dev-003 | android | 已拒绝 | 1小时前 | 重置 | | dev-004 | macos | 离线 | 3天前 | 移除 | ``` ## 快速开始 1. 阅读## 核心能力章节了解skill功能 2. 按## 依赖说明配置环境 3. 执行所需能力对应的命令 4. 参考## 错误处理章节处理异常 5. 查看## FAQ解答常见疑问 ### 1. 全拓扑诊断脚本 ```bash # diagnose.sh 全拓扑一键诊断 #!/usr/bin/env bash set -euo pipefail # ... echo "=== 拓扑识别 ===" echo "gateway.mode: $(skill-platform config get gateway.mode)" echo "gateway.bind: $(skill-platform config get gateway.bind)" echo "tailscale.mode: $(skill-platform config get gateway.tailscale.mode)" echo "remote.url: $(skill-platform config get gateway.remote.url)" echo "publicUrl: $(skill-platform config get plugins.entries.device-pair.config.publicUrl)" # ... echo "" echo "=== QR载荷 ===" skill-platform qr --json # ... echo "" echo "=== 设备列表 ===" skill-platform devices list # ... echo "" echo "=== 节点状态 ===" skill-platform nodes status # ... # 若涉及Tailscale if [ "$(skill-platform config get gateway.tailscale.mode)" != "off" ]; then echo "" echo "=== Tailscale状态 ===" tailscale status --json fi # ... # 若涉及远程 if [ -n "$(skill-platform config get gateway.remote.url)" ]; then echo "" echo "=== 远程QR ===" skill-platform qr --remote --json fi ``` ### 2. 自动修复脚本 ```bash # auto-fix.sh 自动诊断并应用修复 #!/usr/bin/env bash set -euo pipefail # ... DIAGNOSE=$(skill-platform qr --json) URL_SOURCE=$(echo "$DIAGNOSE" | jq -r '.urlSource // empty') # ... case "$URL_SOURCE" in loopback) echo "检测到:网关仅绑定到回环地址" echo "修复:设置 gateway.bind=lan" skill-platform config set gateway.bind lan skill-platform gateway restart skill-platform qr --json ;; tailnet) TS_STATUS=$(tailscale status --json 2>/dev/null || echo '{}') if [ "$(echo "$TS_STATUS" | jq -r '.Self.Online // false')" != "true" ]; then echo "检测到:尾网模式但主机未加入Tailscale" echo "修复:运行 tailscale up" tailscale up fi ;; *) echo "当前urlSource: $URL_SOURCE" echo "请人工审查配置" ;; esac ``` ### 3. 批量配对工作流 ```bash # 批量配对新设备 skill-platform devices list --state pending --format json | jq '.[].id' | while read id; do echo "批准设备: $id" skill-platform devices approve --id "$id" done ``` **响应解析**: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤. ## 示例 ### 全拓扑配置矩阵 | 拓扑 | 关键配置 | QR命令 | |---:|---:|---:| | 同机器 | `gateway.bind=loopback` | `qr --json` | | 同局域网 | `gateway.bind=lan` | `qr --json` | | Tailscale尾网 | `gateway.tailscale.mode=serve` | `qr --json` | | Tailscale公网 | `gateway.tailscale.mode=funnel` | `qr --json` | | 公网反代 | `plugins.entries.device-pair.config.publicUrl` | `qr --json` | | 远程网关 | `gateway.remote.url` | `qr --remote --json` | ### 鉴权配置参考 | 鉴权模式 | 配置 | 适用场景 | |:---:|:---:|:---:| | 令牌 | `gateway.auth.mode=token` | 通用 | | 密码 | `gateway.auth.mode=password` | 简单场景 | | Tailscale | `gateway.auth.allowTailscale=true` | 尾网内信任 | | 混合 | token + allowTailscale | 兼容多场景 | ## 最佳实践 ### 1. 拓扑优先,跨网络不混淆 诊断前必须先确定拓扑类型。跨网络场景常见错误: - 远程网关问题却继续调试 `localhost` 或局域网IP - 尾网场景却广播局域网IP而非MagicDNS/尾网路由 ### 2. 远程模式配置完整性 远程模式涉及多个配置项,任何一项缺失都会失败: ```bash # 完整远程配置检查 skill-platform config get gateway.remote.url # 必须设置 skill-platform config get gateway.auth.mode # 必须与远程一致 skill-platform qr --remote --json # 必须能生成 ``` ### 3. Tailscale鉴权链路 Tailscale Serve/Funnel 的鉴权链路较复杂: ```bash # 确认尾网在线 tailscale status # ... # 确认鉴权模式 skill-platform config get gateway.auth.allowTailscale # ... # 对Serve模式,allowTailscale必须与预期流程匹配 # 对Funnel模式(公网暴露),建议额外启用令牌鉴权 ``` ### 4. 批量配对治理 团队大规模配对时建议: - 配对前按设备类型分组,分批批准 - 每批配对后立即审查 `nodes status`,确认全部在线 - 拒绝的设备记录原因,避免重复尝试 - 定期清理离线超过7天的设备 ### 5. 连接审计 ```bash # 启用审计日志 skill-platform config set audit.enabled true skill-platform config set audit.log-path /var/log/node-connect-audit.log # ... # 查询连接历史 skill-platform audit query --device dev-002 --since 2026-07-01 # ... # 导出审计报告 skill-platform audit export --format csv --since 2026-07-01 --output audit-july.csv ``` ### 6. 多网关节点管理 ```bash # 查看所有网关 skill-platform gateways list # ... # 查看节点与网关映射 skill-platform nodes status --by-gateway # ... # 节点迁移到其他网关 skill-platform nodes migrate --node dev-001 --gateway gw-west ``` ## 常见问题 ### Q1:PRO版与免费版如何共存? 两者本地与局域网诊断流程完全兼容,PRO版包含免费版全部能力。团队升级时直接替换Skill文件,已有诊断脚本与根因映射无需改造. ### Q2:Tailscale Funnel与Serve有何区别? - Serve:仅尾网内可访问(需Tailscale客户端) - Funnel:公网可访问(无需Tailscale客户端),但安全性较低,建议额外启用令牌鉴权 ### Q3:远程网关与公网反代有何区别? - 远程网关:节点连接到独立的远程网关实例,通过 `gateway.remote.url` 配置 - 公网反代:本地网关通过反向代理暴露到公网,通过 `publicUrl` 配置 - 两者可共存,但通常二选一以简化运维 ### Q4:批量配对会触发限流吗? 不会触发API限流,但建议分批进行(每批10-20台),便于观察异常。批量批准后立即运行 `nodes status` 确认全部在线,失败的设备单独处理. ### Q5:审计日志保留多久? 默认保留90天。可在配置中调整: ```bash skill-platform config set audit.retention-days 180 ``` 合规要求更长的场景,建议定期导出到外部归档系统. ### Q6:支持多租户隔离吗? 支持。通过不同网关实例实现租户隔离,各租户的节点、设备、审计日志物理隔离。租户间数据互不影响. ## 依赖说明 ### 运行环境 - **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等) - **操作系统**: Windows / macOS / Linux - **网络环境**: 视拓扑而定,可能需要Tailscale或公网可达 - **Tailscale版本**: 建议 1.50 及以上(用于尾网拓扑) ### 依赖详情 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:------|------:|:------|:------| | LLM API | API | 必需 | 由Agent内置LLM提供 | | skill-platform CLI | 命令行工具 | 必需 | 随技能平台安装 | | Tailscale | VPN工具 | 视拓扑而定 | tailscale.com 下载(尾网场景) | | jq | JSON处理 | 推荐 | 系统包管理器安装 | | 网络诊断工具 | 命令行工具 | 推荐 | ping / traceroute / nc 等 | ### API Key 配置 - 本skill基于Markdown指令规范,无需额外API Key. - `skill-platform` CLI 鉴权由所在平台处理. - Tailscale 通过 `tailscale up` 完成OAuth认证,凭据存储在系统钥匙串. - 远程网关若使用反向代理,需按代理服务文档配置SSL证书与访问控制. ### 可用性分类 - **分类**: MD+EXEC(纯Markdown指令,部分功能需exec命令行执行) - **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作。PRO版面向团队与运维,提供全拓扑诊断、批量配对、审计日志与自动修复能力,完全兼容免费版本地与局域网诊断流程. ## 错误处理 | 错误场景 | 原因 | 处理方式 | |---:|:---|---:| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 | ## 已知限制 - 本地运行，不支持多设备同步 - API调用依赖第三方服务的可用性与稳定性 - 免费版有调用次数限制与并发限制 - 不支持自定义认证与OAuth2.0流程