规则链部署与调用

可视化编辑器（RuleGo-Editor）是可选的。规则链可以通过文件放置或 REST API 完成部署和执行，方便与第三方系统和 CI/CD 流水线集成。

# 工作原理

RuleGo-Server 启动时会扫描数据目录加载规则链：

data/
├── workflows/                          # 用户工作区
│   └── admin/                          # 用户名（config.conf 中的 default_username）
│       ├── rules/                      # 规则链文件
│       │   ├── index                   # 索引文件（自动生成）
│       │   ├── iot-router.json         # 每个 .json 文件 = 一条规则链
│       │   └── data-pipeline.json
│       ├── components/                 # 自定义组件配置
│       └── runs/                       # 运行日志
└── system/
    └── agents/                         # 系统智能体
        └── _assistant/
            ├── _assistant.json
            └── AGENTS.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14

文件名（去掉 .json 后缀）即为规则链 ID
每个用户有独立的 workflows/{用户名}/rules/ 目录
索引文件（index）自动生成，用于加速列表查询

如果在服务器运行期间手动添加或删除了 .json 文件，需要重启 RuleGo-Server 才能生效。也可以通过 API 热部署，无需重启。

# 方式一：手动文件部署

直接将规则链 JSON 文件放入 rules 目录，文件名即为规则链 ID。

# 第一步：创建规则链 JSON 文件

例如，创建 data/workflows/admin/rules/iot-router.json——一条物联网温度过滤规则链：

{
  "ruleChain": {
    "id": "iot-router",
    "name": "温度过滤推送",
    "root": false,
    "debugMode": false,
    "disabled": false,
    "additionalInfo": {
      "description": "过滤指定设备，温度转换后推送至后端API"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "s1",
        "type": "jsFilter",
        "name": "设备过滤",
        "configuration": {
          "jsScript": "return msg.deviceId=='sensor-001' || msg.deviceId=='sensor-002';"
        }
      },
      {
        "id": "s2",
        "type": "jsTransform",
        "name": "温度转换",
        "configuration": {
          "jsScript": "msg.temperature = msg.temperature / 10;\nreturn {'msg':msg,'metadata':metadata,'msgType':msgType};"
        }
      },
      {
        "id": "s3",
        "type": "restApiCall",
        "name": "推送数据",
        "configuration": {
          "restEndpointUrlPattern": "http://backend-service:9099/api/iot/data",
          "requestMethod": "POST"
        }
      },
      {
        "id": "node_end",
        "type": "end",
        "name": "结束"
      }
    ],
    "connections": [
      {"fromId": "s1", "toId": "s2", "type": "True"},
      {"fromId": "s2", "toId": "s3", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Failure"},
      {"fromId": "s1", "toId": "node_end", "type": "False"}
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

文件名 iot-router.json 决定了规则链 ID 为 iot-router。

# 第二步：删除索引文件

如果索引文件存在，删除它以便 RuleGo-Server 启动时重建索引：

rm data/workflows/admin/rules/index

# 第三步：启动（或重启）RuleGo-Server

./server -c="./config.conf"

启动后日志中会显示加载的规则链数量：

[rule] admin number of rule chains loaded: 1

# 第四步：通过 API 执行规则链

curl -X POST http://localhost:9090/api/v1/rules/iot-router/execute/msgData \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"sensor-001","temperature":265}'

1
2
3

同步执行会等待规则链完成并返回结果。

# 方式二：REST API 部署

通过 REST API 部署规则链，无需直接操作文件系统。修改即时生效，无需重启。

# 部署规则链

curl -X POST http://localhost:9090/api/v1/rules/iot-router \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" \
  -d '{
  "ruleChain": {
    "id": "iot-router",
    "name": "温度过滤推送",
    "root": false,
    "disabled": false,
    "additionalInfo": {
      "description": "过滤指定设备，温度转换后推送至后端API"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "s1",
        "type": "jsFilter",
        "name": "设备过滤",
        "configuration": {
          "jsScript": "return msg.deviceId==\"sensor-001\" || msg.deviceId==\"sensor-002\";"
        }
      },
      {
        "id": "s2",
        "type": "jsTransform",
        "name": "温度转换",
        "configuration": {
          "jsScript": "msg.temperature = msg.temperature / 10;\nreturn {\"msg\":msg,\"metadata\":metadata,\"msgType\":msgType};"
        }
      },
      {
        "id": "s3",
        "type": "restApiCall",
        "name": "推送数据",
        "configuration": {
          "restEndpointUrlPattern": "http://backend-service:9099/api/iot/data",
          "requestMethod": "POST"
        }
      },
      {
        "id": "node_end",
        "type": "end",
        "name": "结束"
      }
    ],
    "connections": [
      {"fromId": "s1", "toId": "s2", "type": "True"},
      {"fromId": "s2", "toId": "s3", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Failure"},
      {"fromId": "s1", "toId": "node_end", "type": "False"}
    ]
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

规则链会保存到文件系统并立即加载到引擎中。

# 查询规则链列表

curl http://localhost:9090/api/v1/rules \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2

# 获取规则链

curl http://localhost:9090/api/v1/rules/iot-router \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2

# 部署 / 下线规则链

# 部署（启动）
curl -X POST http://localhost:9090/api/v1/rules/iot-router/operate/start \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

# 下线（停止）
curl -X POST http://localhost:9090/api/v1/rules/iot-router/operate/stop \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2
3
4
5
6
7

# 删除规则链

curl -X DELETE http://localhost:9090/api/v1/rules/iot-router \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2

# 执行规则链

规则链部署后，可以通过多种 API 端点执行：

# 同步执行

等待规则链执行完成后返回结果：

curl -X POST http://localhost:9090/api/v1/rules/iot-router/execute/msgData \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" \
  -d '{"deviceId":"sensor-001","temperature":265,"humidity":60}'

1
2
3
4

# 异步执行

发送后不等待结果（fire-and-forget），适合高吞吐场景：

curl -X POST http://localhost:9090/api/v1/rules/iot-router/notify/msgData \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" \
  -d '{"deviceId":"sensor-001","temperature":265,"humidity":60}'

1
2
3
4

# OpenAI 兼容对话接口

对于包含 ai/agent 节点的智能体规则链，自动获得 OpenAI 兼容端点：

POST /api/v1/rules/{规则链ID}/v1/chat/completions

智能体相关的 API 调用示例参见创建智能体教程。

# 认证方式

当 config.conf 中 require_auth = true 时，API 请求需要认证。有两种方式：

# API Key 认证

在 config.conf 中为用户配置 API Key：

[users]
admin = admin,2af255ea5618467d914c67a8beeca31d

1
2

请求时携带：

# 通过 X-API-Key 请求头
curl -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" ...

# 或通过 Authorization 请求头
curl -H "Authorization: Bearer 2af255ea5618467d914c67a8beeca31d" ...

1
2
3
4
5

# JWT Token 认证

# 登录获取 JWT Token
TOKEN=$(curl -s -X POST http://localhost:9090/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')

# 使用 JWT Token
curl -H "Authorization: Bearer $TOKEN" ...

1
2
3
4
5
6
7

当 require_auth = false（默认）时，所有请求使用默认用户身份，无需认证。

详细的认证和权限说明参见用户认证与权限。

# CI/CD 集成示例

通过 CI/CD 流水线自动部署规则链：

#!/bin/bash
# deploy-rule-chain.sh
RULE_CHAIN_ID=$1
JSON_FILE=$2
SERVER_URL="http://localhost:9090"
API_KEY="2af255ea5618467d914c67a8beeca31d"

# 通过 API 部署规则链（热更新，无需重启）
curl -X POST "${SERVER_URL}/api/v1/rules/${RULE_CHAIN_ID}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -d @"${JSON_FILE}"

if [ $? -eq 0 ]; then
  echo "规则链 ${RULE_CHAIN_ID} 部署成功"
else
  echo "规则链 ${RULE_CHAIN_ID} 部署失败"
  exit 1
fi

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

使用方式：

./deploy-rule-chain.sh iot-router ./rule-chains/iot-router.json

# 目录结构参考

data/                                  # config.conf 中的 data_dir
├── workflows/                         # 用户工作区
│   └── {用户名}/                      # 每个用户独立目录
│       ├── rules/                     # 规则链 JSON 文件
│       │   ├── index                  # 自动生成的索引文件
│       │   ├── chain-a.json           # 规则链，ID = "chain-a"
│       │   └── chain-b.json           # 规则链，ID = "chain-b"
│       ├── components/                # 自定义组件配置
│       └── runs/                      # 执行运行日志
├── system/
│   └── agents/                        # 系统智能体（启动时自动部署）
│       └── {智能体ID}/
│           ├── {智能体ID}.json        # 智能体规则链 JSON
│           └── AGENTS.md              # 系统提示词（可选）
├── skills/                            # 全局技能（config.conf 中的 skill_path）
├── js/                                # 全局 JS 脚本（作为 UDF 加载）
└── plugins/                           # 全局插件（.so 文件）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# API 汇总

方法	路径	说明
GET	`/api/v1/rules`	获取规则链列表
GET	`/api/v1/rules/{id}`	获取规则链 JSON
POST	`/api/v1/rules/{id}`	保存并部署规则链
DELETE	`/api/v1/rules/{id}`	删除规则链
POST	`/api/v1/rules/{id}/operate/start`	部署（启动）
POST	`/api/v1/rules/{id}/operate/stop`	下线（停止）
POST	`/api/v1/rules/{id}/execute/{msgType}`	同步执行
POST	`/api/v1/rules/{id}/notify/{msgType}`	异步执行
POST	`/api/v1/rules/{id}/v1/chat/completions`	OpenAI 兼容对话接口（仅 AI 智能体）

完整的 API 文档参见 REST API 参考。

# 相关文档

概述与快速开始 — 服务器概述与快速开始
REST API 参考 — 完整 API 文档
用户认证与权限 — JWT、API Key、权限体系
创建智能体教程 — 可视化创建智能体及 OpenAI API 集成
智能体框架概述 — 规则链即智能体概念
快速开始 — 规则引擎核心概念入门

在 GitHub 上编辑此页

上次更新: 2026/05/30, 11:18:53

← 二次开发可视化编辑器→