giip

服务器 API 参考指南

用于查询 GIIP 平台管理的服务器资产详细信息并发送控制指令的 API 详细规范。

🔌 前往服务器列表功能页 →

📋 概述

利用服务器 API，您可以检查库存中注册的服务器物理/逻辑状态，并能通过代理远程执行指令或重启服务。

🔍 核心端点

1. 查询服务器列表

获取按项目或客户维度注册的所有服务器信息。

  • URL: 
    GET /server/list
  • 主要参数: 
    • prj_isn
      (Integer): 仅查询特定项目所属的服务器
    • status
      (String): 按 
      Running
      , 
      Stop
      , 
      Unknown
      等状态进行过滤
  • 响应数据: 主机名、IP 地址、操作系统类型、CPU/内存规格等

2. 查询心跳与实时状态

确认安装在服务器上的代理的存活信号及实时负载信息。

  • URL: 
    GET /server/heartbeat
  • 必填参数: 
    server_isn
    (服务器唯一编号)
  • 响应数据: 最后接收时间、当前 CPU 使用率、可用内存等

3. 远程执行指令 (execCommand)

向特定服务器发送 Shell 指令并异步接收结果。

  • URL: 
    POST /server/command
  • 负载 (Payload): 
    • server_isn
      : 目标服务器编号
    • command
      : 要执行的指令（如 
      systemctl restart nginx
      ）
  • 响应: 返回指令接收 ID (
    cmd_isn
    )（执行结果请在 
    /server/command/result
    中查询）

🛠️ 代码示例 (Shell 脚本)

# 查看特定服务器当前的 CPU 使用率
curl -X GET "https://api.giip.io/v3/server/heartbeat?server_isn=123" \
     -H "x-giip-ak: YOUR_AK"

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

在进行新增服务器注册 (

LSvrPut
) 或变更详细信息 (
LSVRDetail
校验) 等基础设施资产管理的核心操作时，为了确保操作的一致性并获取详细的审计日志 (Audit Log)，建议使用 
giipApiSk3
端点。

  • 端点: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 优势: 若服务器注册失败，系统会立即记录调用者的详细环境信息 (IP, UA) 和堆栈追踪 (StackTrace)，助力快速分析助理对接问题或配置错误。
  • 使用技巧: 灵活运用 
    text
    命令和 
    jsondata
    的参数替换功能，确保服务器用途 (
    lsUsage
    ) 或复杂的配置值能完整、稳定地反映到平台中。

故障排除

症状原因解决
查询服务器列表/心跳时发生认证错误缺少或无效的 
x-giip-ak
请求头		确认请求头中包含有效的 AK。
GET /server/list
返回空列表
prj_isn
过滤条件有误或 
status
过滤过于严格		核对 
prj_isn
值并放宽 
status
过滤（如去掉 
Running
）。
GET /server/heartbeat
未返回数据
server_isn
有误或代理尚未上报		使用有效的 
server_isn
并确认目标服务器上的代理正在运行。
远程执行指令后未立即获得结果
execCommand
为异步，仅返回接收 ID（
cmd_isn
）		使用返回的 
cmd_isn
查询 
/server/command/result
获取结果。

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

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

相关文档:

← Previous
Sk3 高性能日志 API
Next →
数据库管理API