huawei-cloud-ecs-passwordless-login

华为云 ECS 免密登录

概述

使用 COC（Cloud Operations Center）配置华为云 ECS 免密 SSH 登录，通过 7 步自动化工作流完成：

1. IAM 授权 — 为 COC 服务创建 ServiceAgencyForCOC 委托并绑定 4 个必需角色；如果委托已存在（HTTP 409），则完全跳过
2. 生成密钥 — 在本地生成 Ed25519 SSH 密钥对
3. 创建脚本 — 创建或复用一个参数化 COC 脚本，用于部署公钥
4. 执行脚本 — 通过 COC 在一个或多个目标 ECS 实例上执行脚本（批量处理；通过 COC CLI ListResources 解析每个目标的区域和 resource_id）
5. SSH 测试 — 验证与每个目标 ECS 的 SSH 免密连接
6. 持久连接 — 建立 SSH ControlMaster，使 Agent 在清理密钥后仍能继续通过 SSH 访问
7. 安全清理 — 60 秒后自动从远程 authorized_keys 中移除密钥、删除本地密钥对，并清理 COC 脚本

工具链： hcloud CLI（KooCLI）+ 本地 SSH 工具。部署仅通过执行 COC 脚本完成。

区域模型：COC 是一项全球级服务，仅支持 cn-north-4（中国站点）和 ap-southeast-3（国际站点）。目标 ECS 实例可以位于不同区域（批量处理）。所有 COC/IAM API 调用以及通过 COC ListResources 解析目标时都使用 coc_region — 解析目标时无需预先知道 ECS 区域；每个目标的实际区域由 ListResources 响应返回。详情请参阅注意事项。

前置条件

• 已安装 hcloud CLI（KooCLI）并使用 AK/SK 完成认证 — 请参阅CLI 安装指南
• IAM 用户具有创建委托和操作 COC 的足够权限 — 请参阅IAM 策略
• 本地可使用 SSH 客户端和 ssh-keygen
• 目标 ECS 实例 ID 或弹性 IP，以逗号分隔的列表形式提供（每台 ECS 都必须处于 ACTIVE 状态）
• ECS 预装 uniagent — COC 脚本执行依赖 ECS 上预装的 uniagent Agent。通过 hcloud COC ListResources 命令检查 uniagent 状态，查看 agent_state 字段以确认 Agent 正常运行

安全

• 切勿在对话或输出中泄露私钥内容
• 切勿在 60 秒窗口之外记录或持久保存私钥
• 必须执行清理 — 如果 SSH 测试成功，必须在 cleanup_delay 秒内移除密钥
• 从 authorized_keys 中移除公钥只会阻止新的 SSH 连接；不会中断现有会话
• 如果 SSH 测试失败，请保留密钥以便调试，且不要触发清理

工作流

按顺序执行以下编号步骤。每一步使用的确切命令语法请参阅核心命令部分。

1. IAM 授权

每个账户仅需设置一次。 授权 COC 操作你的 ECS 实例。

此步骤中的所有 IAM 调用都针对 COC 支持的区域（coc_region）：cn-north-4（中国）或 ap-southeast-3（国际）。

1. 获取域 ID — 调用 KeystoneListAuthDomains 并提取 id。
2. 创建委托 — 使用名称 ServiceAgencyForCOC 和信任域 op_svc_coc 调用 CreateAgency。
   • HTTP 200 — 已创建新委托。记录 agency.id。继续步骤 3。
   • HTTP 409 — 委托已存在。跳过整个 IAM 阶段（步骤 3–4），并跳转至步骤 2（生成密钥）。
3. 查找角色 ID — 分别为以下 4 个角色调用 KeystoneListPermissions：IAM ReadOnlyAccess、RMS ReadOnlyAccess、DCS UserAccess、COCServiceAgencyPolicy。如果找不到任何角色，请停止 — 该账户可能没有访问权限。
4. 绑定角色 — 对 4 个角色 ID 分别调用 AssociateAgencyWithAllProjectsPermission。
   • HTTP 200 — 绑定成功。
   • HTTP 409 — 已绑定，跳过并继续。

2. 生成本地 SSH 密钥对

生成 Ed25519 密钥对。注释 coc-temp-key 是清理标记。仅支持 Ed25519 密钥——不支持 RSA、ECDSA 和 DSA 密钥类型；请勿尝试生成或部署这些密钥，因为它们与此技能不兼容。

记录密钥指纹。绝不显示私钥内容。

3. 创建或复用 COC 脚本

1. 检查现有脚本 — 调用 ListScripts --cli-region=<coc_region>，并使用 --name_like="coc_ssh_key_setup"。如果找到，记录 script_uuid 并跳过步骤 2。
2. 创建新脚本 — 编写一个包含脚本内容的 JSON 文件，然后调用 CreateScript --cli-region=<coc_region> --cli-jsonInput=<file>。使用 --cli-jsonInput（而不是内联 --content），以避免脚本正文中的特殊字符引发 shell 引号问题。记录返回的 script_uuid。

4. 在目标 ECS 上执行脚本

在一批目标 ECS 实例上执行部署脚本。COC 每次执行最多支持 200 台主机，每批最多 10 台主机（batch_index/rotation_strategy）；相应地，将目标拆分为每批 ≤10 台。

1. 解析目标并确认区域 — 对于 ecs_instance_id / ecs_ip 中的每个条目，调用 COC ListResources --cli-region=<coc_region> --provider=ecs --type=cloudservers，将条目解析为 ECS 资源。ListResources 只需要 coc_region——不需要预先知道 ECS 的区域；响应会返回每个资源的 region_id 和 resource_id（以及 properties.addresses 中的 IP）。为每个目标记录一个 (region_id, resource_id) 对。目标可以分布在多个 ECS 区域。

   • 按资源 ID 查询 — 对 ID 条目传入 --resource_id_list.N="<instance_id>"。返回的精确匹配 resource_id 是 COC 执行负载中要使用的值。
   • 按 IP 查询 — 对 IP 条目始终传入 --ip_list.N="<EIP>"。--ip_list 会进行精确匹配。对于每个返回的资源，在记录目标前，验证 properties.addresses[].addr 是否与查询的 <EIP> 匹配：
     • 精确匹配 — 记录 (region_id, resource_id) 对并继续。
     • 不匹配 / 未返回资源 — 报告不匹配并对该条目跳过 / 停止。请勿悄悄回退到其他 IP，否则脚本会在错误的实例上运行。

2. 执行 — 编写一个 JSON 文件，其中嵌入公钥，并将所有已解析的目标对分组到各批次中，然后调用 ExecuteScript --cli-region=<coc_region> --cli-jsonInput=<file>。按照步骤 3 的相同方式操作，以避免公钥内容引发 shell 引号问题。记录 execute_uuid。

3. 轮询 — 每 5 秒调用一次 GetScriptJobInfo --cli-region=<coc_region>，直到状态结束。注意：出于安全考虑，API 会在响应中隐藏 param_value；请在步骤 5 中通过测试 SSH 来验证部署。

   状态	操作
   RUNNING	等待 5 秒后再次轮询
   SUCCESS	继续步骤 5
   FAILED / TIMEOUT	报告各目标的错误并停止

   最多 2 分钟（轮询 24 次）。

5. 测试 SSH 连接

使用生成的密钥测试免密 SSH——针对每个目标 ECS：

• 所有目标均返回 SSH_OK — 继续步骤 6。
• 任一目标失败 — 报告失败的目标。在此处停止。 保留密钥以供调试。请勿触发清理。

6. 建立持久 SSH 连接

设置 SSH ControlMaster，以便在步骤 7 移除密钥后，Agent 仍能访问每台目标 ECS。

1. 追加 SSH 配置 — 对每个目标，在 ~/.ssh/config 中添加一个 Host <EIP> 块，其中包含 ControlMaster auto、ControlPath /tmp/coc_ssh_%r@%h:%p、ControlPersist <persist_timeout>、ServerAliveInterval <server_alive_interval> 和 ServerAliveCountMax <server_alive_count_max>。
2. 启动主连接 — 对每个目标，运行 ssh -N -f <ssh_user>@<EIP> -i <key>，在后台启动持久主连接。
3. 验证 — 对每个目标，不使用密钥文件运行 ssh <ssh_user>@<EIP> "echo SSH_MUX_OK"。如果返回 SSH_MUX_OK，则多路复用正常。

SSH 配置和套接字无需清理——配置条目不会造成影响，套接字会随 ControlPersist 自动过期。

7. 安全清理

必须执行。 启动一个后台计时器，在 cleanup_delay 秒后触发（默认：60）：

1. 从每台目标服务器上的远程 ~<ssh_user>/.ssh/authorized_keys 中移除 coc-temp-key 行
2. 通过 DeleteScript --cli-region=<coc_region> 删除 COC 脚本
3. 删除 <temp_dir>/ 中的本地密钥文件

清理完成后，Agent 仍可通过 ssh <EIP> 连接任何目标——ControlMaster 会绕过密钥认证。

回退方案：如果通过 SSH 无法从任何目标移除远程密钥，则创建并执行一次性 COC 脚本（批量执行，仅针对失败的主机）：

#!/bin/bash
set -e
HOME_DIR=$(eval echo ~$SSH_USER)
sed -i '/coc-temp-key/d' "$HOME_DIR/.ssh/authorized_keys"
echo "KEY_REMOVED"

将此脚本作为批次创建并执行（仅包含失败的主机，并使用各主机解析出的区域），同时将 SSH_USER 参数设为 <ssh_user>。执行完成后立即删除脚本。

核心命令

占位符值（每种操作系统对应的解析方式见“参数”）：

占位符	Linux / macOS	Windows
<temp_dir>	/tmp	$env:TEMP

# 1. Check/setup COC IAM authorization
# IAM is regional in hcloud; the agency must be created in the COC-supported region (coc_region)
hcloud IAM KeystoneListAuthDomains/v3 --cli-region=<coc_region>
hcloud IAM CreateAgency/v3 \
  --cli-region=<coc_region> \
  --agency.domain_id="<domain_id>" \
  --agency.name="ServiceAgencyForCOC" \
  --agency.trust_domain_name="op_svc_coc" \
  --agency.duration="FOREVER"
hcloud IAM KeystoneListPermissions/v3 \
  --cli-region=<coc_region> \
  --display_name="<role_name>"
hcloud IAM AssociateAgencyWithAllProjectsPermission/v3 \
  --cli-region=<coc_region> \
  --agency_id="<agency_id>" --domain_id="<domain_id>" --role_id="<role_id>"

# 2. Generate local SSH key pair (Ed25519 only)
ssh-keygen -t ed25519 -f <temp_dir>/coc_ssh_key -N "" -C "coc-temp-key"
ssh-keygen -lf <temp_dir>/coc_ssh_key  # record fingerprint

# 3. Check for existing COC script
# COC API calls always target the COC-supported region (coc_region)
hcloud COC ListScripts --cli-region=<coc_region> --limit=100 --name_like="coc_ssh_key_setup"
# If not found, create a JSON file and use --cli-jsonInput:
cat > <temp_dir>/coc_create.json << 'JSONEOF'
{
  "body": {
    "name": "coc_ssh_key_setup",
    "type": "SHELL",
    "description": "Deploy SSH public key for passwordless login",
    "content": "#!/bin/bash\nset -e\nHOME_DIR=$(eval echo ~$SSH_USER)\nmkdir -p \"$HOME_DIR/.ssh\" && chmod 700 \"$HOME_DIR/.ssh\"\necho $PUBLIC_KEY >> \"$HOME_DIR/.ssh/authorized_keys\"\nchmod 600 \"$HOME_DIR/.ssh/authorized_keys\"\necho KEY_DEPLOYED_SUCCESSFULLY",
    "properties": {
      "risk_level": "LOW",
      "version": "1.0.0"
    },
    "script_params": [
      {
        "param_name": "PUBLIC_KEY",
        "param_description": "SSH public key to deploy",
        "param_value": "",
        "sensitive": true
      },
      {
        "param_name": "SSH_USER",
        "param_description": "Target SSH username on the ECS",
        "param_value": "",
        "sensitive": false
      }
    ]
  }
}
JSONEOF
hcloud COC CreateScript --cli-region=<coc_region> --cli-jsonInput=<temp_dir>/coc_create.json

# 4. Resolve batch targets & confirm each region, then execute script
# ecs_instance_id / ecs_ip are comma-separated lists. Do NOT assume a single region;
# COC ListResources resolves each entry (IP or ID) WITHOUT needing the ECS region in advance,
# and returns each resource's region_id and resource_id. Always target the coc_region endpoint.
hcloud COC ListResources --cli-region=<coc_region> --provider=ecs --type=cloudservers --limit=100 \
  --resource_id_list.1="<instance_id>"                       # for an ID entry (exact match)
hcloud COC ListResources --cli-region=<coc_region> --provider=ecs --type=cloudservers --limit=100 \
  --ip_list.1="<EIP>"                                        # for an IP entry (exact list match)

# Always verify the returned resource's properties.addresses[].addr exactly equals <EIP>
# before recording the target; otherwise the script may run against the wrong instance.
# Extract per resource: region_id, resource_id, and properties.addresses[].addr
#   RESULT=$(hcloud COC ListResources ... --cli-json-filter="data[]")
# Record (region_id, resource_id) pair per target; group into batches of <=10 hosts each.
cat > <temp_dir>/coc_execute.json << 'JSONEOF'
{
  "path": {"script_uuid": "<script_uuid>"},
  "body": {
    "execute_batches": [
      {
        "batch_index": 1,
        "rotation_strategy": "CONTINUE",
        "target_instances": [
          {"region_id": "<target1_region>", "resource_id": "<target1_id>"},
          {"region_id": "<target2_region>", "resource_id": "<target2_id>"}
        ]
      },
      {
        "batch_index": 2,
        "rotation_strategy": "CONTINUE",
        "target_instances": [
          {"region_id": "<target3_region>", "resource_id": "<target3_id>"}
        ]
      }
    ],
    "execute_param": {
      "execute_user": "root",
      "success_rate": 100,
      "timeout": 120,
      "script_params": [{
        "param_name": "PUBLIC_KEY",
        "param_value": pubkey
      },
      {
        "param_name": "SSH_USER",
        "param_value": "<ssh_user>"
      }]
    }
  }
}
JSONEOF
hcloud COC ExecuteScript --cli-region=<coc_region> --cli-jsonInput=<temp_dir>/coc_execute.json

# Poll execution status (note: GetScriptJobInfo redacts param_value for security; check SSH directly to verify)
hcloud COC GetScriptJobInfo --cli-region=<coc_region> --execute_uuid=<execute_uuid>

# 5. Test SSH connection (repeat for every target EIP)
for eip in <EIP1> <EIP2> <EIP3>; do
  ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    -o ConnectTimeout=10 -i <temp_dir>/coc_ssh_key <ssh_user>@$eip "echo SSH_OK"
done

# 6. Establish persistent SSH connection (ControlMaster multiplexing, one per target)
for eip in <EIP1> <EIP2> <EIP3>; do
  cat >> ~/.ssh/config << EOF

Host $eip
  User <ssh_user>
  ControlMaster auto
  ControlPath /tmp/coc_ssh_%r@%h:%p
  ControlPersist <persist_timeout>
  ServerAliveInterval <server_alive_interval>
  ServerAliveCountMax <server_alive_count_max>
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
EOF
  ssh -N -f <ssh_user>@$eip -i <temp_dir>/coc_ssh_key && echo "MASTER_CONNECTED $eip"
  ssh <ssh_user>@$eip "echo SSH_MUX_OK"  # verify multiplexing works
done

# 7. Security cleanup (background, survives parent shell exit via nohup + disown)
nohup bash -c '
sleep <cleanup_delay>
# Remove public key from every remote target
for eip in <EIP1> <EIP2> <EIP3>; do
  ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    -o ConnectTimeout=5 -i <temp_dir>/coc_ssh_key <ssh_user>@$eip \
    "sed -i \"/coc-temp-key/d\" \$(eval echo ~<ssh_user>)/.ssh/authorized_keys" 2>/dev/null || true
done
# Delete COC script
hcloud COC DeleteScript --cli-region=<coc_region> --script_uuid="<script_uuid>" 2>/dev/null || true
# Delete local keys
rm -f <temp_dir>/coc_ssh_key <temp_dir>/coc_ssh_key.pub
echo "COC SSH keys cleaned up. Existing SSH sessions remain unaffected."
' > <temp_dir>/coc_cleanup.log 2>&1 &
disown
echo "Cleanup scheduled in <cleanup_delay>s (PID: $!, log: <temp_dir>/coc_cleanup.log)"

参数

参数	必填	默认值	约束
ecs_instance_id	有条件必填	None	以逗号分隔的 ECS 实例 UUID 列表。如果未提供 ecs_ip，则必填。可与 ecs_ip 条目混合使用 — 完整集合将作为批次处理
ecs_ip	有条件必填	None	以逗号分隔的 ECS 弹性 IPv4 地址列表。如果未提供 ecs_instance_id，则必填。可与 ecs_instance_id 条目混合使用
ecs_region	否	None	已从目标解析中移除。 通过 COC ListResources 发现目标 ECS 区域（该接口会返回每个资源的 region_id，无需提前提供）；此参数仅作为可选提示保留，并非必填
coc_region	否	cn-north-4	COC 服务区域。COC 是一项全球级服务 — 仅支持 cn-north-4（中国站点）和 ap-southeast-3（国际站点）。所有 COC/IAM API 调用都必须指向此区域；该区域独立于 ECS 区域
ssh_user	否	root	目标 ECS 上的 SSH 用户名。支持 root 或非 root 用户；密钥会部署到该用户的 ~/.ssh/authorized_keys
cleanup_delay	否	60	自动清理密钥前的等待秒数（最小值 10，最大值 300）
persist_timeout	否	3600	所有会话关闭后，保持 ControlMaster 运行的秒数（最小值 60，最大值 86400）
server_alive_interval	否	30	向远程主机发送 keepalive 数据包以维持活动 TCP 连接的间隔秒数（最小值 5，最大值 300）
server_alive_count_max	否	3	客户端断开连接前，未收到响应的 keepalive 探测次数（最小值 1，最大值 10）

输出格式

在每个步骤中，以结构化方式报告进度：

步骤	输出
1. 授权	机构状态（已创建 / 已存在）、已绑定角色数（4/4）
2. 密钥生成	密钥指纹、密钥文件路径
3. 脚本	脚本名称、操作（已创建 / 已复用）、script_uuid
4. 执行	execute_uuid、目标数量及每批状态、每个目标的最终结果
5. SSH 测试	每个目标的连接结果、SSH 命令字符串
6. 持久连接	ControlMaster 状态、多路复用验证、SSH 别名（每个 <EIP> 一个）
7. 清理	计时器 PID、倒计时通知、清理确认

验证

逐步验证工作流：

1. 授权 — CreateAgency 返回 200 → 绑定全部 4 个角色（每个返回 200 或 409）；返回 409 → 跳过整个 IAM 阶段（该机构已在先前运行中获得授权）
2. 密钥生成 — 密钥对文件存在于 <temp_dir>/ 中，且权限正确
3. 脚本 — coc_ssh_key_setup 已存在，包含 PUBLIC_KEY 参数，且 script_uuid 有效
4. 执行 — GetScriptJobInfo 显示该批次在 2 分钟内 SUCCESS
5. SSH 测试 — 每个目标均可无密码提示地连接；所有测试命令均返回 SSH_OK
6. 持久连接 — 已追加 SSH 配置（包含 ControlMaster、ControlPersist 和 ServerAliveInterval），ssh -N -f <ssh_user>@<EIP> 启动主连接，且每个目标上的 ssh <ssh_user>@<EIP> "echo SSH_MUX_OK" 均成功
7. 清理 — 每个目标上的远程密钥均已删除，COC 脚本已删除，本地密钥文件已删除；ssh <ssh_user>@<EIP> 仍可通过 ControlMaster 连接

详细检查清单请参阅验证方法和验收标准。

最佳实践

• IAM 授权是每个账号仅需执行一次的设置 — 如果 CreateAgency 返回 409，则整个 IAM 阶段（机构 + 角色绑定）已完成，应完全跳过
• 在 ListScripts 中使用 --name_like 筛选条件，避免创建重复脚本
• 启动清理计时器前，务必测试 SSH 连接
• 如果 SSH 失败，请将密钥保留在磁盘上以便调试 — 不要自动清理
• 清理计时器在后台子 Shell 中运行；若在清理完成前终止进程，密钥会保留
• 清理密钥后，Agent 仍可通过 ssh <EIP> 使用 SSH — ControlMaster 会绕过密钥认证
• 使用 -o UserKnownHostsFile=/dev/null，避免污染本地 known_hosts 文件
• SSH 密钥注释 coc-temp-key 是 sed 用于清理的标记 — 不要更改
• COC 脚本每次执行最多处理 200 台主机，每批最多处理 10 台主机 — 将目标拆分为多个批次，每个 batch_index 最多 10 台主机
• 每批目标可能分布在多个 ECS 区域 — 在第 4 步中，务必通过 COC ListResources 确认每个目标所在的区域（无需提前提供区域即可返回 region_id）；切勿假定所有目标都属于同一个 ecs_region
• 对批次中的每个目标测试 SSH 并运行清理；任何一个目标失败都会中止运行，并保留密钥以便调试
• 清理后，SSH 配置条目会继续保留，但成为无害的失效条目；如有需要，可稍后删除
• 在 ~/.ssh/config 中配置 ServerAliveInterval（默认 30s）和 ServerAliveCountMax（默认 3），防止 NAT 网关和有状态防火墙静默断开空闲的 ControlMaster 连接

参考文档

文档	描述
CLI 安装指南	安装并配置 hcloud CLI 和 SSH 工具
IAM 策略	所需的 IAM 权限、委托设置和错误处理
验证方法	各工作流步骤的分步验证
验收标准	完整的端到端验收清单

注意事项

• COC 脚本依赖 uniagent — COC 脚本执行依赖 ECS 上预先安装的 uniagent Agent。如果未安装 uniagent，或其状态异常，COC 脚本执行将失败。使用以下命令检查 uniagent 状态：

  hcloud COC ListResources --cli-region=<coc_region> --provider=ecs --type=cloudservers --limit=100
  

  检查响应中的 agent_state 字段，确保 Agent 处于运行状态。如果 Agent 状态异常，请先修复 uniagent 问题，再执行 COC 脚本。
• 区域模型 — COC 和 ECS 使用不同的区域：
  • COC 是全局级服务：仅支持 cn-north-4（中国站）和 ap-southeast-3（国际站）。所有 COC/IAM API 调用都必须指向 coc_region。
  • ECS 按区域划分：每个目标 ECS 都位于自己的区域中，同一批次中的区域可能各不相同。第 4 步通过 ECS CLI 确认每个目标的区域，然后在 COC 执行负载中，将其作为 region_id 传入对应的 target_instance；COC 会从全局端点路由到相应区域。
  • COC/IAM/ECS 调用通过 --cli-region 明确指定区域，避免 CLI 配置文件的默认区域导致路由错误：
    • COC 和 IAM 调用 → --cli-region=<coc_region>
    • ECS 目标解析（COC ListResources）→ --cli-region=<coc_region>（全局 COC 端点；无需预先知道 ECS 所在区域 — 响应会返回每个资源的 region_id）
    • SSH 命令 → 直接使用 <EIP> 和 <ssh_user>（SSH 无区域概念）
• COC 脚本通过带有 JSON 文件的 --cli-jsonInput 创建，而非内联使用 --content="..." — 内联引号会导致脚本正文中的 shell 特殊字符引发解析错误
• COC 脚本使用 PUBLIC_KEY 进行参数化 — 脚本会持久保留，可在不同调用中部署不同的密钥
• 如果之前的运行已创建 COC 脚本，则会复用该脚本，而不是重新创建
• 清理操作使用 nohup bash -c '...' & + disown，确保父 shell 退出后清理进程仍可继续运行；输出会记录到 <temp_dir>/coc_cleanup.log 以供验证。在非交互模式下，父 shell 退出时，旧的 (sleep N && ...) & 模式会丢失标准输出
• 私钥存储在 <temp_dir> 中，绝不能提交到 VCS
• SSH 密钥类型固定为 Ed25519（ssh-keygen -t ed25519）。此技能不支持 RSA、ECDSA 和 DSA 密钥 — 请勿生成或部署这些密钥。如果检测到已有的不兼容密钥，请重新生成 Ed25519 密钥
• sed 清理目标 coc-temp-key 与 ssh-keygen 设置的密钥注释相匹配
• 清理后，使用 ssh <EIP>（无需密钥文件）— ControlMaster 套接字会处理身份验证