跳至主要內容

Agent 服务

Agent 服务 (GA)

Agent 服务（简称 GA 服务）是部署在用户服务器上的核心组件，负责处理应用管理、命令执行和进程通信等功能。

服务概述

服务特点

  • 部署位置：用户服务器本地
  • 通信协议：HTTP API + JSON-RPC 2.0
  • 安全性：本地文件套接字通信
  • 性能：低延迟、高效率的进程间通信

API 接口规范

响应格式

所有 API 接口遵循统一的响应格式：

字段类型说明
codenumber状态码，成功为 200000，失败为非 200000
dataany响应数据
metaobject元数据信息
msgstring响应消息（英文）

API 接口详情

1. 执行命令

接口地址：/api/command/exec_shell

SDK 支持

该方法已封装在前端 SDK 中，可直接调用。

请求参数：

{
    "cmd_string": "cat .bashrc",
    "timeout": "1",
    "cwd": "/root",
    "username": "root"
}

参数说明：

参数类型必填说明
cmd_stringstring是要执行的命令字符串，支持原始命令或 base64 编码后的命令
timeoutstring是命令执行超时时间（秒）
cwdstring否命令执行的工作目录，默认为 /.__gmssh/bin
usernamestring是命令执行的用户名

响应示例：

{
    "code": 200000,
    "data": "# .bashrc content here...",
    "meta": {
        "close": 0,
        "endpoint": "/api/command/exec_shell"
    },
    "msg": "Successful operation"
}

2. 获取进程端口号

接口地址：/api/command/get_process_port

请求参数：

{
    "process_name": "test"
}

参数说明：

参数类型必填说明
process_namestring是进程名称

响应示例：

{
    "code": 200000,
    "data": {
        "port": 17766,
        "pid": 17764
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/command/get_process_port"
    },
    "msg": "Successful operation"
}

3. 执行脚本内容

接口地址：/api/command/exec_script

请求参数：

{
    "script": "ZWNobyBoZWxsbw==",
    "timeout": "5"
}

参数说明：

参数类型必填说明
scriptstring是Base64 编码的脚本内容
timeoutstring是脚本执行超时时间（秒）

响应示例：

{
    "code": 200000,
    "data": "hello",
    "meta": {
        "close": 0,
        "endpoint": "/api/command/exec_script"
    },
    "msg": "Successful operation"
}

执行方式区别

  • 执行命令：相当于在终端中执行命令
  • 执行脚本：直接执行脚本文件内容

4. 应用状态检查

接口地址：/api/center/check_status

SDK 支持

该方法已封装在前端 SDK 中，可直接调用。

请求参数：

{
    "app_name": "official/omc",
    "version": "1.0.0",
    "communication_type": "http"
}

参数说明：

参数类型必填说明
app_namestring是应用名称，格式：{组织名}/{应用名}
versionstring是应用版本号
communication_typestring是通信类型：http 或 socket

5. 外置应用访问接口

接口地址：/api/call/{组织名}/{应用名}/{接口名}

请求参数：

{
    "version": "1.0.0",
    "transport": "http",
    "params": {
        "lang": "zh-CN"
    }
}

参数说明：

参数类型必填说明
versionstring是外置应用版本号
transportstring是通信类型：http 或 socket
paramsobject否传递给外置应用的参数

响应示例：

{
    "code": 200000,
    "data": {
        "code": 200,
        "data": "hello world!",
        "msg": "操作成功"
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/call/*"
    },
    "msg": "Successful operation"
}

6.获取文件和目录

接口地址：api/files/get_dir

请求参数：

{
    "path": "/",
    "search": "",
    "all": "",
    "reverse": "False",
    "sort": "name",
    "showRow": 9999,
    "window_id": ""
}

参数说明：

参数类型必填说明
pathstring是目录路径，如 "/" 表示根目录
searchstring否搜索关键词，用于过滤文件名
allstring否是否显示所有文件
reversestring否是否倒序排列，"True" 或 "False"
sortstring否排序方式："name"（按名称）、"size"（按大小）、"time"（按时间）
showRownumber否显示行数限制，默认 9999表示最多的（该参数只在桌面生效）
window_idstring否窗口ID标识

响应示例：

{
    "code": 200000,
    "data": {
        "LIST": [
            {
                "name": "/.__gmssh",
                "filename": ".__gmssh",
                "cwd": "/",
                "fullname": "/.__gmssh",
                "filesize": 4096,
                "size": 4096,
                "mtime": 1751468646,
                "accept": "755",
                "user": "root",
                "link": "",
                "download_id": "0",
                "is_composer_json": "0",
                "favorite": "0",
                "share": "0",
                "ps": "",
                "top": "0",
                "recycle_raw": -1,
                "gmk": {
                    "name": "",
                    "title": "",
                    "icon": "",
                    "type": 0,
                    "type_des": "",
                    "key": "",
                    "v": "",
                    "sort": 0,
                    "only_one": 0,
                    "run_status": 0,
                    "installed": 0,
                    "target_exists": 0,
                    "version": "",
                    "min_width": "",
                    "min_height": "",
                    "index": null
                },
                "type": 1
            },
        ],
        "PATH": "/",
        "desktop": "/.__gmssh/desktop",
        "recycle": {
            "rec_has_file": false
        },
        "size": 0
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/get_dir"
    },
    "msg": "Successful operation"
}

7.创建文件

接口地址:/api/files/create_file

请求参数：

{
    "path": "/demo.txt"
}

参数说明：

参数类型必填说明
pathstring是文件绝对路径

响应示例：

{
    "code": 200000,
    "data": {
        "name": "/demo.txt",
        "filename": "demo.txt",
        "cwd": "/",
        "fullname": "/demo.txt",
        "filesize": 0,
        "size": 0,
        "mtime": 1753061249,
        "accept": "644",
        "user": "root",
        "link": "",
        "download_id": "0",
        "is_composer_json": "0",
        "favorite": "0",
        "share": "0",
        "ps": "",
        "top": "0",
        "recycle_raw": -1,
        "gmk": {
            "name": "",
            "title": "",
            "icon": "",
            "type": 0,
            "type_des": "",
            "key": "",
            "v": "",
            "sort": 0,
            "only_one": 0,
            "run_status": 0,
            "installed": 0,
            "target_exists": 0,
            "version": "",
            "min_width": "",
            "min_height": "",
            "index": null
        },
        "type": 2
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/create_file"
    },
    "msg": "Successful operation"
}

8.删除文件

接口地址:/api/files/delete_file

请求参数：

{
    "path": "/demo.txt"
}

参数说明：

参数类型必填说明
pathstring是文件绝对路径

响应示例：

{
    "code": 200000,
    "data": {
        "refresh_store": false
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/delete_file"
    },
    "msg": "Successful operation"
}

9.创建目录

接口地址:/api/files/create_dir

请求参数：

{
    "path": "/demo"
}

参数说明：

参数类型必填说明
pathstring是目录绝对路径

响应示例：

{
    "code": 200000,
    "data": {
        "name": "/demo",
        "filename": "demo",
        "cwd": "/",
        "fullname": "/demo",
        "filesize": 4096,
        "size": 4096,
        "mtime": 1753061569,
        "accept": "755",
        "user": "root",
        "link": "",
        "download_id": "0",
        "is_composer_json": "0",
        "favorite": "0",
        "share": "0",
        "ps": "",
        "top": "0",
        "recycle_raw": -1,
        "gmk": {
            "name": "",
            "title": "",
            "icon": "",
            "type": 0,
            "type_des": "",
            "key": "",
            "v": "",
            "sort": 0,
            "only_one": 0,
            "run_status": 0,
            "installed": 0,
            "target_exists": 0,
            "version": "",
            "min_width": "",
            "min_height": "",
            "index": null
        },
        "type": 1
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/create_dir"
    },
    "msg": "Successful operation"
}

10.删除目录

接口地址:/api/files/delete_dir

请求参数：

{
    "path": "/demo"
}

参数说明：

参数类型必填说明
pathstring是目录绝对路径

响应示例：

{
    "code": 200000,
    "data": {
        "refresh_store": false
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/delete_dir"
    },
    "msg": "Successful operation"
}

11.编辑文件内容

接口地址:/api/files/read_file_body

请求参数：

{
    "path": "/demo.txt",
    "auto_create": "0"
}

参数说明：

参数类型必填说明
pathstring是文件绝对路径
auto_createstring是是否自动创建文件，0 表示不自动创建，1 表示自动创建

响应示例：

{
    "code": 200000,
    "data": {
        "path": "",
        "encoding": "utf-8",
        "data": "",
        "only_read": false,
        "size": 0,
        "st_mtime": "1753061659"
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/read_file_body"
    },
    "msg": "Successful operation"
}

12.重命名文件/目录

接口地址:/api/files/mv_file

请求参数：

{
    "sfile": "/demo.txt",
    "dfile": "/example.txt",
    "rename": true
}

参数说明：

参数类型必填说明
sfilestring是旧文件绝对路径
dfilestring是新文件绝对路径
renamebool是值为 false就去强制移动（新文件存在就删除）

响应示例：

{
    "code": 200000,
    "data": {
        "name": "/example",
        "filename": "example",
        "cwd": "/",
        "fullname": "/example",
        "filesize": 0,
        "size": 0,
        "mtime": 1753061659,
        "accept": "644",
        "user": "root",
        "link": "",
        "download_id": "0",
        "is_composer_json": "0",
        "favorite": "0",
        "share": "0",
        "ps": "",
        "top": "0",
        "recycle_raw": -1,
        "gmk": {
            "name": "",
            "title": "",
            "icon": "",
            "type": 0,
            "type_des": "",
            "key": "",
            "v": "",
            "sort": 0,
            "only_one": 0,
            "run_status": 0,
            "installed": 0,
            "target_exists": 0,
            "version": "",
            "min_width": "",
            "min_height": "",
            "index": null
        },
        "type": 2
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/files/mv_file"
    },
    "msg": "Successful operation"
}

13.复制粘贴文件/目录

接口地址:/api/files/copy_file

请求参数：

{
    "sfile": "/demo",
    "dfile": "/example"
}

参数说明：

参数类型必填说明
sfilestring是旧文件绝对路径
dfilestring是新文件绝对路径

响应示例：

{
    "code": 200000,
    "data": true,
    "meta": {
        "close": 0,
        "endpoint": "/api/files/copy_file"
    },
    "msg": "Successful operation"
}

JSON-RPC 接口规范

GA 服务也提供基于 Unix Domain Socket 的 JSON-RPC 2.0 接口，支持高性能本地进程间通信。

连接方式

Unix Socket 文件路径：

/.__gmssh/tmp/rpc.sock

协议规范

  • 协议版本：JSON-RPC 2.0
  • 传输协议：Unix Domain Socket
  • 数据格式：JSON
  • 字符编码：UTF-8

请求格式

{
    "jsonrpc": "2.0",
    "method": "method_name",
    "params": {
        "param1": "value1",
        "param2": "value2"
    },
    "id": 1
}

字段说明：

字段类型必填说明
jsonrpcstring是协议版本，固定为 "2.0"
methodstring是调用的方法名
paramsobject/array否方法参数
idnumber/string是请求标识符，用于匹配响应

JSON-RPC 接口详情

1. 日志上报接口(重点)

方法名称:log_report

请求参数：

{
    "plugin_name": "user",
    "plugin_name_des": "用户模块",
    "fn_name": "add_user",
    "fn_name_des": "添加用户",
    "data": data,
    "o_name": "新增用户：xxx",
}

参数说明：

参数类型必填说明
plugin_namestring是插件名称
plugin_name_desstring是插件名称描述
fn_namestring是函数名称
fn_name_desstring是函数名称描述
datastring是请求数据
o_namestring是操作详情

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "code": 200,
    "meta": {"endpoint": null, "close": 1},
    "data": null,
    "msg": "Successful operation"
  },
  "id": 1
}

环境变量

IsClean

作用域：仅在应用的 uninstall.sh 脚本中可获取

取值说明：

  • true：用户选择清除应用数据
  • false：用户选择保留应用数据

使用示例：

#!/bin/bash

if [ "$IsClean" = "true" ]; then
    echo "清除应用数据..."
    rm -rf ./data/
    rm -rf ./config/
else
    echo "保留应用数据"
fi

最佳实践

  • 始终在卸载脚本中检查 IsClean 环境变量
  • 根据用户选择合理处理数据清理逻辑
  • 添加适当的日志输出便于问题排查
最近更新
贡献者: xiaozheng
Copyright © 2025 xiaozheng