系统管理 API 参考

引导您如何通过系统级自动化 API 向服务器发送指令或控制代理状态。

📋 概述

此 API 模块提供了一系列端点，用于通过 GIIP 代理直接向各服务器下达指令，或管理服务器的元数据（如标签等）。

🔐 认证与请求头

所有请求必须包含通用的认证请求头。

Header:
```
x-giip-ak: [Your Access Key]
```
Header:
```
x-giip-sk: [Your Secret Key]
```

🚀 核心 API 端点

1. 远程执行命令 (Run Remote Command)

URL:
```
POST /api/system/command/run
```
描述: 在指定的服务器上执行特定的 Shell 脚本或指令。
请求体 (Request Body):

{
  "serverIsn": 456,
  "command": "ls -al /var/log",
  "timeout": 30
}

2. 代理控制 (Agent Control)

URL:
```
POST /api/system/agent/control
```
描述: 远程重启安装在服务器上的 GIIP 代理或同步配置。
请求体 (Request Body):

{
  "serverIsn": 456,
  "action": "restart"
}

3. 管理服务器标签 (Manage Server Tags)

URL:
```
POST /api/system/server/tags
```
描述: 更新用于分类服务器的标签列表。
请求体 (Request Body):

{
  "serverIsn": 456,
  "tags": ["Production", "Web", "Region-KR"]
}

🔍 响应数据示例 (Command Run)

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "jobId": "JOB-10293",
    "output": "total 1024\ndrwxr-xr-x 2 root root ...",
    "exitCode": 0
  }
}

💡 使用场景

自动补丁管理: 针对发现漏洞的软件包，向所有服务器下达批量更新指令。
动态资源分配: 通过标签管理 API 自动指定新创建 VM 的用途并应用相应策略。

🛡️ 巧用 Sk3 (高性能日志)

在进行远程命令执行 (

Run Remote Command

) 或代理控制等敏感的系统管理操作时，为了确保操作的完整性并保留详细的执行历史，建议使用

giipApiSk3

端点。

端点:

https://giipfaw.azurewebsites.net/api/giipApiSk3

优势: 若命令执行失败，系统会立即记录调用者的详细环境信息 (IP, UA) 和堆栈追踪 (StackTrace)，助力快速、清晰地识别非法请求或网络故障状况。
使用技巧: 灵活运用
```
jsondata
```
替换功能，确保在管理复杂的 Shell 命令字符串或包含特殊字符的标签信息时数据不丢失且安全。

🔧 故障排除

症状	原因	解决
请求因认证错误被拒绝	缺少 `x-giip-ak` / `x-giip-sk` 请求头或密钥错误	在两个请求头中均包含有效的 Access Key 和 Secret Key 后重试
远程命令未执行	`serverIsn` 错误，或目标服务器的代理离线	确认服务器标识符，并通过代理控制 API( `action: restart` )重启代理
响应中的 `RstVal` 不为 0	命令执行失败或超过 `timeout`	检查 `RstMsg` 与 `Data.exitCode` ，必要时调高 `timeout` 值
发送含特殊字符的标签时数据丢失	未使用 `jsondata` 替换功能	通过 `giipApiSk3` 端点的 `jsondata` 字段发送以防止数据丢失

版本: 1.1 最后更新: 2026-04-11 源文件:

giipv3/public/help/api-system.zh-CN.md

相关文档:

API 结果代码指南 (RstVal)