remote-access

name	remote-access
description	远程访问工作流。首次访问远端、SSH、跳板机、上传下载或远程部署时，先发现并注册可复用节点，再执行和验证远端操作。
context	inline

远程访问工作流

目标

把一次性 SSH 命令转换为可复用的远端节点能力。节点注册保存连接方式与认证引用；后续任务只使用 alias。

工作流

1. 发现：先调用 remote_list_nodes()，按 alias、description 和 tags 查找适合当前目标的节点。
2. 注册：没有合适节点时，选择一种方式：
   • 已有标准节点清单：调用 remote_import_nodes(manifest_path)。
   • 已知单节点公开连接参数：调用 remote_register_node(...)。
3. 验证：注册后用最小只读命令调用 remote_command(node, command) 验证连通性和目标身份。
4. 执行：
   • 远端命令使用 remote_command；文件上传下载使用 remote_transfer。
   • Kubernetes 通用操作使用 remote_kubectl。
   • Pod 内执行和日志分别使用 remote_pod_exec、remote_pod_logs。
   • 本地客户端必须访问仅远端可见的 API、kubelet 或服务时，使用 remote_tunnel 建立端口转发；用完后 stop。
5. 降级：专用工具不可用、配置不兼容或失败时，可以使用普通命令行方式继续完成任务。

不要为某个项目硬编码 alias。优先使用有意义的 description 和 tags，让后续任务可以重新发现节点。

标准 Manifest

{
  "version": 1,
  "nodes": {
    "prod-api": {
      "description": "production API node",
      "tags": ["prod", "api"],
      "host": "prod-api",
      "backend": "openssh",
      "config_file": "./ssh/config",
      "kubectl_path": "kubectl",
      "kubeconfig_path": "/etc/kubernetes/admin.conf",
      "kube_context": "production",
      "kube_namespace": "default"
    }
  }
}

Manifest 中的 config_file、identity_file 和 auth_env_file 相对路径以 Manifest 所在目录为基准。导入后会转成稳定引用。

单节点注册

常见 OpenSSH profile：

remote_register_node(
  alias="prod-api",
  host="prod-api",
  description="production API node",
  tags=["prod", "api"],
  config_file="/path/to/ssh/config"
)

带密码环境引用的 Paramiko profile：

remote_register_node(
  alias="legacy-node",
  host="gateway.example",
  port=22022,
  user="root",
  backend="paramiko",
  auth_env_file="/path/to/auth.env",
  auth_env_allowlist=["RELAY_SSH_PASSWORD"],
  password_env_key="RELAY_SSH_PASSWORD"
)

完成标准

• 目标节点已有稳定 alias；
• 最小只读命令验证成功，或明确记录专用工具失败并完成合理降级；
• 后续操作使用 Remote 套组，不再重复拼装连接参数。