OpsAny 运维平台

OpsAny 是「PaaS + SaaS」架构的智能运维平台。本 Skill 通过 opsany-mcp-server 暴露的 MCP 工具
操作平台数据：只调工具、不碰平台内部接口。

覆盖模块（括号内为工具名前缀）：CMDB 资源平台（opsany_cmdb_）、管控平台（opsany_control_）、
作业平台（opsany_job_）、ITSM 工作台（opsany_workbench_）、统一权限（opsany_rbac_）、
基础监控（opsany_monitor_）、应用监控（opsany_prom_）、事件中心（opsany_event_）、
知识库（opsany_kbase_）。

> 本期不含堡垒机、云管平台、容器平台、日志平台的 MCP 工具（服务端字典已预留但为空），
> 用户问这些请直接说明暂不支持，不要猜测工具名。

1. 接入前检查（先做这一步）

客户端配置（DOMAIN_NAME 换成平台地址，内网用 IP 即可）：

{
  "mcpServers": {
    "opsany-mcp-server": {
      "url": "http://${DOMAIN_NAME}:8020/sse",
      "headers": {
        "username": "${OPSANY_USERNAME}",
        "user-api-token": "${USER_ACCESS_TOKEN}",
        "mcp-auth-token": "${MCP_AUTH_TOKEN}"
      }
    }
  }
}

🔴 首次使用必须先探活：调 opsany_rbac_get_my_user_info。

• 返回当前用户信息 → 链路正常，继续后续操作；
• 工具列表里根本没有 opsany_*，或返回鉴权/连接错误 → 不要换工具重试，
  直接告诉用户检查：① 用户名的拼写与账号；② user-api-token 是否过期；
  ③ mcp-auth-token 与服务端 auth_token 是否一致；④ 8020 端口是否可达。

安全提示：SSE 走 http:// 时三个 header 是明文传输。仅限内网使用，
不要把 8020 暴露到公网；跨网段请在前面加 HTTPS 反向代理。

2. 工具地图

完整参数、枚举、返回说明见 references/mcp-tools.md（按工具名索引）。

约束要点：

• CMDB 写数据前必须先 opsany_cmdb_get_resource_fields 拿字段定义；字段 code 会被写成 {model_code}_{code}。
• IP 地址管理仅支持 C 类网段（掩码 24~31），传 B 类掩码会被服务端拒绝；这是双层校验，不要尝试绕过。
• 资源授权策略中 auth_bind_user 是全量覆盖，auth_user_bind 是增量绑定，别用错。
• opsany_workbench_work_order_folder 与 opsany_job_run_script_by_script 未注册，不要调用；
  要执行一次性脚本，先用 opsany_job_create_script_library 入库再 opsany_job_run_script_by_id。

3. 高频参数速查（这些地方最容易错）

分页参数每个模块都不一样，照抄会报参数无效：

opsany_control_create_host 只接受一个数组参数 host_info_list，监控/堡垒机相关字段都写在
数组元素里。元素必填 9 项：name（唯一标识，执行脚本要用）、show_name、ip、system_type
（Linux/Windows）、controller_id、control_type（1 SSH / 2 Agent / 3 SSH|Agent / 4 Agent|SSH）、
username、group_id（取 code）、host_type（SERVER 物理机 / VIRTUAL_SERVER 虚拟机）。
可选：ssh_port、password、privilege*（sudo/su）、monitor_type（Zabbix/Prometheus）+
controller_zabbix/controller_prom、template_list（Zabbix 模板）、reinstall_zabbix_agent、
is_bastion。

opsany_job_run_script_by_id：script_id + server（主机唯一标识 name，字符串，不是 IP 也不是对象）
+ 可选 parameter、time_out（脚本超时，不是 tool_timeout）。

opsany_workbench_work_order_submit：submit_from、work_order_id、field_dict
（键取自 opsany_workbench_work_order_temp 的 field_list），可加 follow。

枚举是后端原始拼写，不要"纠正"：IP 状态 Userd / Avacliable / Notcsan；
扫描状态 not_scan / scanning / scanned / scan_fail；添加方式 custom / csv。

所有工具都支持 tool_timeout（秒，默认 10~120）。扫描类操作建议显式调大。

枚举速查（"人话 → 取值"）——以下取值均取自服务端实现，不要自行改写或翻译：

工单类（opsany_workbench_work_order_inst）的 data_type 默认 page、data 默认 will（待办）；
其它取值以服务端返回为准，不要凭猜。

4. 典型链路

4.1 从告警到处置（最常用主线）

1. 取告警：opsany_event_alert_info（alert_type=all_alert，status=1 待处理），
   或 opsany_monitor_alert_info / opsany_prom_alert_info 按 severity 过滤；记下 host_ip。
2. 定位主机：opsany_control_get_managed_host_list，用 ip_search 传该 IP，拿到 id、name
   （name 是后续执行脚本的主机唯一标识）。
3. 查资产详情：opsany_cmdb_api_resources 找到主机模型 model_code →
   opsany_cmdb_get_resource（search 传 IP）拿到资源明细与所属业务。
4. 处置：opsany_job_get_script_list 找对应处置脚本 → opsany_job_run_script_by_id
   （server=name）→ opsany_job_get_run_result_by_log_id 轮询结果。
5. 查处置方案：opsany_kbase_read_kbase_article（search_data 传故障关键词）。
6. 留痕提单：opsany_workbench_work_order_temp 取服务目录与 field_list →
   opsany_workbench_work_order_submit。

4.2 资产盘点

1. opsany_cmdb_api_resources（可传 output=extend 带实例数/字段数、resource_type=zc,zz,yw,gl 过滤）。
2. opsany_cmdb_get_resource（model_code + search + 分页）拿明细。
3. 关心关联关系（网络设备/业务）：opsany_cmdb_get_resource_fields 找 is_relationship_field
   字段 → opsany_cmdb_get_resource_link_inst_list。

4.3 批量纳管主机

1. opsany_control_get_controller_list → controller_id；
   opsany_control_get_host_group_list → group_id（取 code）；
   需要监控时 opsany_control_get_zabbix_list + opsany_control_get_zabbix_temp_list。
2. opsany_control_create_host，一次传多台（host_info_list），按 3 节的必填项构造。
3. 回读核对：opsany_control_get_managed_host_list 按 IP 查，确认状态；部分失败时逐条重试，
   不要整批重跑（会造成重复纳管）。

4.4 创建自定义资源模型

opsany_cmdb_get_model_group（取 model_group）→ opsany_cmdb_create_model
（code/name/model_type，可 clone_model 克隆已有模型）→ opsany_cmdb_get_resource_fields
取 field_group_code → opsany_cmdb_create_model_fields（仅普通字段，不支持关联关系字段）→
opsany_cmdb_create_resource 写数据。

4.5 IP 盘点与扫描

1. 定位子网：opsany_control_get_ip_manager_subnet（search_type=subnet_addr + search_data）；
   不确定分组先 opsany_control_get_ip_manager_group（flat=true）。
2. opsany_control_scan_ip_manager_subnet（scan_type=ip），大网段调大 tool_timeout。
3. 轮询 opsany_control_get_ip_manager_subnet_scan（id 或 cache_key）直到 scanned；
   卡住则用 scan_type=ip_stop 停止。
4. 取明细：opsany_control_get_ip_manager_address（ip_manager=子网 ID，state=Avacliable 查可用）。
5. 新建子网：name 全局唯一、subnet_addr 必须是网络地址、掩码仅 C 类；
   opsany_control_delete_ip_manager_subnet 会连带删除子网下所有 IP 记录，删前必须与用户确认。

5. 返回结构与分页规则

统一返回 JSON 文本：{"success": ..., "error": ..., "data": ...}。

列表类 data 有两种形态（取决于服务端 config.yaml 的 realDataType）：

嵌套对象会被拍平成点号键（controller.id、agent_info.ip），与 columns 键一致。

🔴 分页硬规则：列表类工具默认只返回 20 条（部分 10/50/100）。先读 total：

• total > 本次返回条数 → 必须继续翻页，或明确告诉用户"以下是前 N 条，共 M 条"；
• 不要拿第一页直接汇总成"一共就这些"。

空结果 ≠ 调用失败：

{"success": false, "error": "获取当前资源数据为空", "data": {"total": 0, "data": []}}

表示查询成功但没命中。不要用同样参数重试，应放宽条件或确认平台侧确实没数据
（例如子网未扫描时 IP 列表就是空的）。

6. 操作安全

• 默认只读：查询类工具可放心调用；写操作没有明确指令时不要做。
• 破坏性操作必须先确认：opsany_cmdb_delete_model（仅空模型可删）、
  opsany_cmdb_delete_model_field（连带字段数据）、opsany_cmdb_delete_resource、
  opsany_cmdb_resource_auth_delete、opsany_control_delete_ip_manager_subnet、
  opsany_rbac_delete_user。
• 批量操作先小样本验证 1 条，再放量。
• 返回里出现 无操作权限 时，说明是 RSS/权限问题，不是参数问题——换参数重试没有意义。

7. 工具可见性（按授权版本）

服务启动时探测平台授权版本并据此裁剪工具，看不到某个工具通常是被授权版本挡住了：

容器平台、LLMOps、智能巡检、日志、应用监控（APM）的工具字典目前为空，即使企业版也不会出现。

8. 参考资料

references/ 下为背景资料，与本文冲突时以本文为准：

9. 相关资源

• 官网：https://www.opsany.com/
• 文档：https://docs.opsany.com/
• 在线演示：https://demo.opsany.com/
• 更新记录：CHANGELOG.md
• 问题反馈：见平台「建议反馈」入口，或通过官网「联系我们」获取技术支持