huawei-cloud-flexus-l-server-scripts-excute

⚠️ 安全执行规则（最高优先级）：

1. 所有脚本都必须通过 skill action=exec 执行，绝不能直接在 shell 中运行
2. 绝不能在对话中打印脚本内容或包含 AK/SK/Token 的命令
3. 绝不能创建临时脚本文件，优先使用内联执行（python -c）
4. 执行失败时，只返回错误信息，不要重写脚本或打印完整命令
5. AK/SK/Token 必须通过环境变量传递，绝不能出现在对话中
6. 绝对不要以任何形式暴露、记录或打印 AK/SK/Token 值——这是关键安全要求
7. 凭据按以下优先级解析：环境变量 (HW_ACCESS_KEY, HW_SECRET_KEY, HW_SECURITY_TOKEN, HW_REGION) -> 命令行参数 -> 交互式提示。优先使用环境变量；不要将 AK/SK 作为命令行参数传递。

Huawei Cloud Flexus L Instance COC Skill

概述

架构图

此 skill 基于 Huawei Cloud COC（Cloud Operations Center）服务构建，涉及以下云服务和组件：

User/Agent    │──────▶│   COC API   │──────▶│   UniAgent    │──────▶│  Flexus L Instance│
(Skill caller)       (Cloud Ops Center)       (Proxy program)              (Target Host) 

组件说明：

• 用户/Agent：通过自然语言或 API 触发脚本管理操作的 skill 调用方
• COC API：Huawei Cloud COC（Cloud Operations Center）提供脚本管理、执行调度和状态查询等核心能力
• UniAgent：部署在目标主机上的 Agent 程序，负责接收脚本并在本地执行
• Flexus L Instance：Huawei Cloud 弹性云服务器，作为脚本执行的目标主机

适用场景

• 批量操作：在多个 Flexus L 实例上执行相同的脚本（例如，软件安装、配置更新）
• 自动化运维：定期执行巡检脚本、日志收集和健康检查
• 紧急响应：快速部署紧急脚本，以处理安全事件或系统故障
• 应用部署：批量部署应用并更新配置文件
• 数据处理：在多个实例上并行执行数据处理任务

典型用例

1. “创建一个用于清理服务器日志的 Shell 脚本”
2. “在所有 L 实例上执行备份脚本”
3. “列出我最近创建的脚本”
4. “在指定的 L 实例上执行 Python 脚本”
5. “创建一个用于批量安装 Nginx 的脚本”

触发关键词

路由关键词：COC 脚本、脚本管理、脚本执行、云运维、自定义脚本、批量执行；COC、脚本管理、脚本执行、云运维。

重要说明

所有脚本和环境检查脚本都位于 skill 软件包中。必须使用 skill action=exec 执行；不要直接在 shell 中运行。

前提条件

CLI 版本要求和验证命令

COC SDK 版本要求：huaweicloudsdkcoc >= 3.1.0

验证命令：

# Check current SDK version
python -c "import huaweicloudsdkcoc; print(huaweicloudsdkcoc.__version__)"

# Verify COC client availability
python -c "from huaweicloudsdkcoc.v1 import CocClient; print('COC SDK version verification passed')"

身份验证配置和安全规则

支持的身份验证方法：

1. 凭证获取方法：

   此技能支持通过以下方法获取 Huawei Cloud 凭证（按优先级从高到低排列）：

   1. 环境变量（优先级最高）

      • HW_ACCESS_KEY：Huawei Cloud Access Key AK
      • HW_SECRET_KEY：Huawei Cloud Access Key SK
      • HW_SECURITY_TOKEN：临时凭证的安全令牌

   2. 命令行参数（未提供环境变量时使用）

      • --ak：Huawei Cloud Access Key AK
      • --sk：Huawei Cloud Access Key SK
      • --security-token：临时凭证的安全令牌（使用临时 AK/SK 时必需）

   3. 交互式输入（未提供上述任一方法时）

   • 程序将提示用户输入凭证信息，例如 AK/SK

# Execute script directly (will automatically use environment variables)
python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script"

2. 环境变量（推荐）：

export HW_ACCESS_KEY="your_access_key"
export HW_SECRET_KEY="***"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"
export HW_REGION="cn-north-4"

# Run without --ak/--sk; credentials are read from environment variables
python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script"

⚠️ 安全提示：通过命令行传递 AK/SK（例如 --ak "..." --sk "..."）会导致凭证暴露在进程列表中（例如 ps aux）。请仅在可信的单用户环境中这样操作；建议优先使用环境变量或 hcloud configure。

3. 交互式输入（测试）：

python {baseDir}/scripts/caller.py create
# Will prompt for AK/SK/region

身份验证参数说明：

参数	说明	必需	默认值	示例
--ak	Huawei Cloud Access Key AK（可以是临时 AK）	是*	提示输入	--ak AXXX...
--sk	Huawei Cloud Access Key SK（可以是临时 SK）	是*	提示输入	--sk SXXX...
--security-token	临时凭证的安全令牌（使用临时 AK/SK 时必需）	否	提示输入	--security-token XXXX...
--region	COC 服务区域	否	cn-north-4	--region cn-north-4

注意：标有 * 的参数可以通过环境变量（HW_ACCESS_KEY、HW_SECRET_KEY、HW_SECURITY_TOKEN、HW_REGION）提供。如果设置了环境变量，其优先级高于命令行参数。

身份验证优先级：

1. 首先检查环境变量：HW_ACCESS_KEY、HW_SECRET_KEY、HW_SECURITY_TOKEN、HW_REGION
2. 如果已设置所有必需的环境变量，则直接使用这些变量
3. 如果未设置环境变量，则使用命令行参数
4. 如果两者均未提供，则提示用户进行交互式输入

安全规则：

• 禁止硬编码凭证：切勿将 AK/SK 直接嵌入代码或配置文件中
• 最小权限原则：仅授予所需的最低权限
• 定期轮换密钥：每 90 天轮换一次 AK/SK
• 启用密钥轮换提醒：在 Huawei Cloud Console 中设置到期提醒

IAM 权限列表

此技能需要以下 IAM 权限。详细信息请参阅 IAM 策略文档：

权限类别	权限名称	说明
脚本管理	coc:script:create	创建脚本
脚本管理	coc:script:list	列出脚本
脚本管理	coc:script:get	获取脚本详情
脚本管理	coc:script:update	更新脚本
脚本管理	coc:script:delete	删除脚本
执行管理	coc:execution:create	创建执行任务
执行管理	coc:execution:list	列出执行任务
执行管理	coc:execution:get	获取执行详情
实例管理	coc:instance:list	列出目标实例

权限失败处理流程

权限不足错误处理：

1. 错误识别：

# Typical error message
error: AccessDenied
message: You do not have permission to perform this action.

2. 故障排查步骤：

   • 验证 AK/SK 配置
   • 确认用户具有所需的 COC 权限
   • 验证区域配置
   • 检查 IAM 策略是否已启用

3. 解决方法：

   • 联系管理员获取所需权限
   • 确认 IAM 策略已正确附加到用户/角色
   • 等待策略生效（通常需要 5-10 分钟）

4. 验证：

# Re-execute to verify permissions
python {baseDir}/scripts/caller.py list

核心命令

脚本管理命令

创建脚本：

# Set credentials via environment variables (recommended)
export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"
export HW_REGION="cn-north-4"

# Run without --ak/--sk; credentials are read from environment variables
python {baseDir}/scripts/caller.py create --name "backup_script" --type SHELL --content "echo 'Backup completed'" --description "Data backup script"

查看脚本详情：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py show --script-uuid "SC202xxxxxxxx13701c4a8a62"

列出脚本：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py list --page 1 --size 10

删除脚本：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py delete --script-uuid "SC202xxxxxxxx13701c4a8a62"

脚本执行命令

执行脚本：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py execute --script-uuid "SC202xxxxxxxx13701c4a8a62" --execute-user root --timeout 300

交互式执行：python {baseDir}/scripts/caller.py execute（从环境变量中读取凭据）

查询执行结果：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py query --execute-uuid "SCT202xxxxxxxx01af694bf"

参数参考

全局参数（所有命令）

参数	描述	必填	默认值	示例
--ak	Huawei Cloud 访问密钥 AK（可以是临时 AK）	是*	提示输入	--ak AXXX...
--sk	Huawei Cloud 访问密钥 SK（可以是临时 SK）	是*	提示输入	--sk SXXX...
--security-token	临时凭据的安全令牌（使用临时 AK/SK 时必填）	否	提示输入	--security-token XXXX...
--region	COC 服务区域	否	cn-north-4	--region cn-north-4

注意：标有 * 的参数可以通过环境变量提供：

• HW_ACCESS_KEY - Huawei Cloud 访问密钥
• HW_SECRET_KEY - Huawei Cloud 密钥
• HW_SECURITY_TOKEN - 临时安全令牌（可选）
• HW_REGION - COC 服务区域

如果设置了环境变量，其优先级高于命令行参数。

create 命令参数

参数	描述	必填	默认值
--name	脚本名称	是	-
--type	脚本类型（SHELL/PYTHON/BAT）	是	-
--content	脚本内容	是	-
--description	脚本描述	是	-
--risk-level	风险等级（LOW/MEDIUM/HIGH）	否	LOW
--version	脚本版本	否	1.0.0

execute 命令参数

参数	描述	必填	默认值
--script-uuid	脚本 UUID	否	最新脚本
--execute-user	执行用户	否	root
--timeout	超时时间（秒，5-1800）	否	300
--success-rate	成功率（0.01-100）	否	1
--rotation-strategy	轮换策略（CONTINUE/PAUSE）	否	CONTINUE

show 命令参数

参数	描述	必填	默认值
--script-uuid	脚本 UUID	是	-

list 命令参数

参数	描述	必填	默认值
--page	页码	否	1
--size	每页条数	否	10

delete 命令参数

参数	描述	必填	默认值
--script-uuid	脚本 UUID	是	-

query 命令参数

参数	描述	必填	默认值
--execute-uuid	执行任务 UUID	是	-

SDK 安装

首次创建或执行脚本前，请确保已安装 Huawei Cloud COC SDK 依赖项。在技能目录（skills/coc）中运行：

pip install -r {baseDir}/requirements.txt

安装说明：

• 安装可能需要几分钟，请耐心等待
• 安装成功后，可以调用 scripts 目录中的 Python 代码来创建和执行脚本
• 使用以下镜像安装 SDK（优先使用第二个 pip 镜像）：

  pip install -r {baseDir}/requirements.txt -i https://pypi.org/project/huaweicloudsdkcoc/
  

  或

  pip install -r {baseDir}/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
  

安装验证：

python -c "from huaweicloudsdkcoc.v1 import CocClient; print('SDK installed successfully!')"

工作流

基本工作流

1. 创建脚本（使用环境变量）：

# Set environment variables first
export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
export HW_SECURITY_TOKEN="your_token"  # Optional

# Execute command (will automatically use environment variables)
python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script"

2. 执行脚本：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
export HW_SECURITY_TOKEN="your_token"  # Optional

python {baseDir}/scripts/caller.py execute --script-uuid "SC202xxxxxxxx13701c4a8a62" --execute-user root --timeout 300 --success-rate 100

⚠️ 切勿通过 --ak "..." --sk "..." 命令行参数传递 AK/SK；它们会显示在进程列表中（例如 ps aux）。请始终优先使用环境变量或 hcloud configure。

提示：完整的参数文档请参阅“参数参考”部分。

交互模式

执行脚本时，系统会交互式请求以下信息（仅限 L-instance）：

必需参数：

• L-instance 资源 ID（resource_id）
• L-instance 区域（region_id）

可选参数（按 Enter 键使用默认值）：

• 脚本 UUID（默认使用最近创建的脚本）
• 执行用户（默认为 root）
• 超时时间（默认 300 秒）
• 成功率（默认 1）
• 轮换策略（默认 CONTINUE）

输出格式

脚本列表输出

Found 25 scripts (Page 1, 10 per page):
--------------------------------------------------------------------------------
No.    Script UUID                    Name                 Type        Risk Level
--------------------------------------------------------------------------------
1       SC202xxxxxxxx13701c4a8a62     backup_script        SHELL       LOW
2       SC202xxxxxxxx10302201d5b9e78     deploy_script        SHELL       HIGH
3       SC202xxxxxxxx13701c4a8a62     monitor_script       PYTHON      MEDIUM
--------------------------------------------------------------------------------

JSON 输出格式

创建脚本成功响应：

{
  "ok": true,
  "text": "Script created successfully: SC202xxxxxxxx13701c4a8a62",
  "result": {
    "data": "SC202xxxxxxxx13701c4a8a62"
  },
  "error": null
}

执行脚本成功响应：

{
  "ok": true,
  "text": "Script execution started: SCT202xxxxxxxx01af694bf",
  "result": {
    "data": "SCT202xxxxxxxx01af694bf"
  },
  "error": null
}

查询执行结果响应：

{
  "data": {
    "batch_index": 1,
    "total_instances": 1,
    "execute_instances": [
      {
        "id": 40304358,
        "cmd_uuid": "2exxxxxxxxxxxxxx6b5",
        "job_sign": null,
        "target_instance": {
          "resource_id": "6axxxxxxxxxxxxxxx9e",
          "agent_sn": "e5xxxxxxxxxxxxxxxxxx77",
          "agent_status": null,
          "agent_version": "1.1.8",
          "region_id": "cn-north-4",
          "project_id": null,
          "properties": {
            "host_name": "dify-test-001",
            "fixed_ip": null,
            "floating_ip": null,
            "region_id": "cn-north-4",
            "zone_id": null,
            "application": null,
            "group": null,
            "project_id": null
          },
          "custom_attributes": null,
          "provider": "hcss",
          "type": "l-instance"
        },
        "gmt_created": 1779934038727,
        "gmt_finished": 1779934107670,
        "execute_costs": 68943,
        "status": "ABNORMAL",
        "message": "Reading package lists...\nWARNING: apt does not have a stable CLI interface. Use with caution in scripts.\n\n\nBuilding dependency tree...\nReading state information...\nexpect is already the newest version (5.45.4-2build1).\n\n[SYSTEM INFO] script job execute timeout."
      }
    ]
  }
}

状态说明：

• FINISHED - 执行成功
• ABNORMAL - 执行失败
• PROCESSING/READY - 正在进行

验证方法

1. SDK 安装验证

python -c "from huaweicloudsdkcoc.v1 import CocClient; print('SDK installed successfully!')"

2. 创建脚本验证

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"

python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script" --non-interactive
# Expected output: Script UUID returned

3. 执行脚本验证

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"

python {baseDir}/scripts/caller.py execute --script-uuid "SC202xxxxxxxx13701c4a8a62" --execute-user root --timeout 300 --non-interactive
# Expected output: Execution task ID returned

4. 冒烟测试

python {baseDir}/scripts/smoke_test.py
# This will test the configuration and optional API connectivity

注意事项

一般注意事项

• 脚本执行必需参数 - 需要提供 L-instance resource_id 和 region_id
• 自动获取脚本 UUID - 如果未指定，将自动使用最近创建的脚本
• 脚本类型必须匹配 - SHELL/PYTHON/BAT
• 必须正确设置风险级别 - LOW/MEDIUM/HIGH
• 需要轮询执行结果 - 执行 API 会返回任务 ID，需要单独查询执行状态

最佳实践

脚本管理最佳实践

1. 脚本复用性：创建可配置参数的通用脚本，以实现最大程度的复用
2. 错误处理：始终在脚本中加入错误处理和日志记录
3. 幂等性：将脚本设计为幂等（可安全地多次运行）
4. 脚本版本管理：为重要脚本维护版本控制
5. 资源标记：为脚本使用统一的命名规范和标签

执行最佳实践

1. 先测试：批量执行前，始终先在单个 L-instance 上测试脚本
2. 风险评估：为脚本设置适当的风险级别（LOW/MEDIUM/HIGH）
3. 计划执行：对周期性任务使用计划执行
4. 监控：监控执行结果，并为失败设置告警

区域概念

COC 涉及两种不同的区域概念：

1. COC 服务区域（API 端点区域）：

• cn-north-4（中国北部-北京-4，默认）
• ap-southeast-3（亚太-新加坡）
• eu-west-101（欧洲-法兰克福）

2. 目标实例区域（L-instance 所在位置）：

• 可以是华为云全球范围内的任意区域
• 交互式输入支持区域 ID 和区域名称

重要：COC 服务区域和目标实例区域可以不同。

错误处理

身份验证失败（403）：

error: Authentication failed

• AK/SK 无效，请使用正确的凭据重新配置

API 配额超限（429）：

error: API quota exceeded

• API 配额已耗尽，请等待或升级

参数错误（400）：

error: Invalid parameter

• 检查请求参数是否正确

安全注意事项

• AK/SK 安全：AK/SK 是访问华为云 API 的重要凭据。请妥善保管，不要与他人分享。
• 获取凭据：登录华为云管理控制台 → 我的凭证 → 访问密钥 → 新建访问密钥

参考文档

• IAM 策略配置
• 验证方法
• 验收标准
• 项目依赖配置