安装与部署

# 下载

从 Github Releases (opens new window) 下载对应平台的二进制文件。

# 启动

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

后台启动：

nohup ./server -c="./config.conf" >> console.log &

# 安装可视化编辑器（RuleGo-Editor）

RuleGo-Editor 是 RuleGo-Server 的可视化 UI 界面，用于可视化管理、调试和部署规则链。

# 方式一：使用预编译包（推荐）

从 Github Releases (opens new window) 下载 editor.zip
解压到 server 二进制文件相同目录下，会生成 editor 文件夹：

your-app/
├── server          # 服务端二进制
├── config.conf     # 配置文件
└── editor/         # 解压后的编辑器前端
    ├── index.html
    ├── config/
    │   └── config.js
    └── ...

1
2
3
4
5
6
7
8

确保 config.conf 中 resource_mapping 配置正确（默认已配置）：

resource_mapping = /editor/*filepath=./editor,/images/*filepath=./editor/images

启动 server 后，访问 http://localhost:9090/ 即可打开编辑器

如果 editor 放在其他路径，修改 resource_mapping 中的 ./editor 为实际路径。

# 方式二：从源码编译

克隆 rulego-editor (opens new window) 仓库
重要：确保 vite.config.js (opens new window) 中 base 配置为 /editor/：

export default defineConfig({
  base: '/editor/',
  // ...
})

1
2
3
4

安装依赖并构建：

npm install
npm run build

1
2

将构建产物（dist 目录内容）复制到 server 同目录下的 editor 文件夹

# 修改后端 API 地址

如果 server 不在本地或端口不同，编辑 editor/config/config.js 中的 baseUrl：

window.baseUrl = 'http://your-server:9090'

# 配置文件详解

配置文件采用 INI 格式，支持环境变量替换（${VAR} 或 ${VAR:-default}）。以下是完整配置项说明：

# 基础配置

参数	默认值	说明
`data_dir`	`./data`	数据目录，存放规则链、组件等运行时数据
`server`	`:9090`	HTTP 服务监听地址
`base_path`	（空）	API 路由前缀，用于嵌入模式
`default_username`	`admin`	未开启认证时的默认用户名
`skill_path`	`./skills`	全局 Skill 存储路径（内置 config.conf 中配置为 `./data/skills`）

# 运行时配置

参数	默认值	说明
`debug`	`true`	是否把节点调试日志打印到日志文件
`max_node_log_size`	`40`	单个节点日志最大条数
`script_max_execution_time`	`5000`	脚本执行超时时间（毫秒）
`run_log_mode`	`off`	运行记录级别：`off`（不记录）/ `summary`（摘要）/ `detail`（完整节点日志）。替代原 `save_run_log`，链级 `additionalInfo.runLogMode` 可覆盖此全局配置
`run_log_store_type`	`bbolt`	执行日志存储后端：`bbolt`、`file`（JSON Lines）
`run_log_retention_count`	`500`	每条规则链保留最近 N 条日志，0 表示不限制
`run_log_retention_days`	`7`	保留最近 N 天日志，0 表示不限制
`share_http_server`	`false`	将主 HTTP 服务器注入每个用户节点池作为共享节点，业务链可通过 `server: "ref://<server>"` 复用。多租户环境慎用（路由冲突与链 Restart 会波及共享该端口的所有租户）
`endpoint_enabled`	`false`	是否启用 endpoint 框架（MQTT、Kafka 等外部集成）
`event_bus_chain_id`	（空）	处理核心事件总线事件的规则链 ID
`category_folder_enabled`	`false`	是否按分类文件夹组织规则链
`load_lua_libs`	`true`	是否加载 Lua 第三方库

# HTTP 服务配置

参数	默认值	说明
`allow_cors`	`true`	是否允许跨域请求
`read_timeout`	`30`	HTTP 读超时（秒）
`write_timeout`	`300`	HTTP 写超时（秒），AI 流式输出需要较大值
`max_body_size`	`10`	最大请求体大小（MB）

# 日志配置

参数	默认值	说明
`log_file`	（空）	日志文件路径，为空则输出到控制台
`log_level`	`info`	日志级别：`debug`、`info`、`warn`、`error`
`log_max_size`	`100`	单个日志文件最大大小（MB）
`log_max_backups`	`30`	保留的旧日志文件数量
`log_max_age`	`7`	日志文件保留天数

# 安全配置

参数	默认值	说明
`require_auth`	`false`	是否开启 JWT 认证
`jwt_secret_key`	（内置默认值）	JWT 签名密钥，建议通过环境变量 `JWT_SECRET_KEY` 设置
`jwt_expire_time`	`43200000`	JWT 过期时间（毫秒），默认 12 小时
`jwt_issuer`	`rulego.cc`	JWT 签发者
`cmd_mode`	`allow`	Shell 命令安全模式：`allow`（白名单）、`deny`（黑名单）
`cmd_white_list`	（内置列表）	允许执行的 Shell 命令列表
`cmd_deny_list`	（空）	禁止执行的 Shell 命令列表
`cmd_deny_args`	（空）	禁止的命令参数模式
`file_path_white_list`	`/tmp`	文件节点的路径白名单

# AI 工具安全配置

[ai_security] 段提供 AI 工具调用的全局预检策略（例如演示环境限制工具能力），需要 with_ai 或 with_all 构建标签，不影响每个智能体节点自身的工具安全设置。

参数	默认值	说明
`enable`	`false`	是否启用工具安全拦截
`mode`	`deny`	拦截模式：`deny`（黑名单，命中则拦截）或 `allow`（白名单，不在列表则拦截）
`deny_tools`	（空）	黑名单模式下拦截的工具名称，逗号分隔，支持 `*` 通配符
`allow_tools`	（空）	白名单模式下允许的工具名称，逗号分隔，支持 `*` 通配符
`denied_types`	（空）	拦截的工具类型：`builtin`、`mcp`、`rulechain`、`subagent`
`cmd_deny_extra`	（空）	bash 工具额外命令黑名单，在工具自身安全检查之上追加
`allow_paths`	（空）	文件路径白名单，read/write/edit 工具只能访问这些路径，为空则不限制
`deny_paths`	（空）	文件路径黑名单，优先级高于 `allow_paths`，支持通配符（如 `./config*`）

# 资源映射

# 格式：/url/*filepath=/path/to/file，多个映射用逗号分隔
resource_mapping = /editor/*filepath=./editor,/images/*filepath=./editor/images

1
2

# 共享节点池

# 节点池文件，规则链 JSON 格式
node_pool_file = ./node_pool.json

1
2

# MCP 配置

[mcp]
enable = true

1
2

详细说明参见 MCP 服务。

# MCP 分组配置

[mcp.groups]
# 格式：组名 = 工具列表（逗号分隔）
# 支持语法：* 表示全部工具，-prefix* 表示按前缀排除，
#          rules/components/chains 表示工具类别（管理 API 工具/组件工具/规则链工具）
readonly = rules,list_components,get_component_doc
full = *
no-delete = *,-delete_rule_chain
iot = rules,components,chains,-_assistant

1
2
3
4
5
6
7
8

# 全局自定义配置

[global]
# 组件可通过 ${global.xxx} 取值
sqlDriver = mysql
sqlDsn = root:root@tcp(127.0.0.1:3306)/test
# AI Agent LLM 配置
llm_url = https://api.openai.com/v1
llm_api_key = sk-xxx
llm_model = gpt-4o

1
2
3
4
5
6
7
8

# 用户配置

[users]
# 格式：username = password[,apiKey]
# apiKey 可选，配置后可通过 apiKey 直接访问接口，无需登录
admin = admin,ak-your-secret-key
user01 = user01

1
2
3
4
5

# pprof 配置

[pprof]
enable = false
addr = 0.0.0.0:6060

1
2
3

# Docker 部署

FROM alpine:latest
COPY server /app/server
COPY config.conf /app/config.conf
COPY editor /app/editor
WORKDIR /app
RUN chmod +x server
EXPOSE 9090
CMD ["./server", "-c=./config.conf"]

1
2
3
4
5
6
7
8

docker build -t rulego-server .
docker run -d -p 9090:9090 -v ./data:/app/data rulego-server

1
2

# 从源码构建

# 标准构建
go build -o server ./cmd/server/

# 带 AI 组件
go build -tags "with_ai" -o server ./cmd/server/

# 带所有可选组件
go build -tags "with_all" -o server ./cmd/server/

# 或逐个指定
go build -tags "with_ai,with_iot,with_etl,with_ci,with_extend" -o server ./cmd/server/

1
2
3
4
5
6
7
8
9
10
11

可用构建标签：

标签	说明
`with_all`	所有可选组件（等同于同时启用下面全部标签）
`with_ai`	AI 相关组件（ai/agent 节点、LLM 工具等）
`with_iot`	IoT 相关组件
`with_etl`	ETL 数据处理组件
`with_ci`	CI/CD 相关组件
`with_extend`	扩展组件

# 完整配置文件示例

# =============================================================================
# 基础配置
# =============================================================================
# 数据目录
data_dir = ./data
# 全局 Skill 存储路径
skill_path = ./data/skills
# HTTP 服务监听地址
server = :9090
# API 路由前缀（用于嵌入模式）
#base_path = /rulego
# 默认用户名（未开启认证时使用）
default_username = admin

# =============================================================================
# 安全配置
# =============================================================================
# Shell 命令安全模式：allow（白名单）或 deny（黑名单）
cmd_mode = allow
# Shell 命令白名单
cmd_white_list = cp,scp,mvn,npm,yarn,git,make,cmake,docker,kubectl,helm,ansible,puppet,pytest,python,python3,pip,go,java,dotnet,gcc,g++,ctest
# Shell 命令黑名单
cmd_deny_list =
# 禁止的命令参数模式
cmd_deny_args =
# 文件节点路径白名单
file_path_white_list = /tmp
# 是否加载 Lua 第三方库
load_lua_libs = true

# =============================================================================
# 认证配置
# =============================================================================
# 是否开启 JWT 认证
require_auth = false
# JWT 签名密钥（建议通过环境变量 JWT_SECRET_KEY 设置）
jwt_secret_key = r6G7qZ8xk9P0y1Q2w3E4r5T6y7U8i9O0pL7z8x9CvBnM3k2l1
# JWT 过期时间（毫秒），默认 12 小时
jwt_expire_time = 43200000
# JWT 签发者
jwt_issuer = rulego.cc
# 全局加密密钥
#secret_key =

# =============================================================================
# 日志配置
# =============================================================================
# 是否记录节点调试数据
debug = true
# 单个节点日志最大条数
max_node_log_size = 40
# 日志文件路径，为空则输出到控制台
#log_file =
# 日志级别
#log_level = info
# 单个日志文件最大大小（MB）
#log_max_size = 100
# 保留的旧日志文件数量
#log_max_backups = 30
# 日志文件保留天数
#log_max_age = 7

# =============================================================================
# 运行时配置
# =============================================================================
# 资源映射（格式：/url/*filepath=/path/to/file，多个用逗号分隔）
resource_mapping = /editor/*filepath=./editor,/images/*filepath=./editor/images
# 节点池文件
node_pool_file = ./node_pool.json
# 运行记录级别：off（不记录）/ summary（摘要）/ detail（完整节点日志）
# 链级 additionalInfo.runLogMode 可覆盖此全局配置
run_log_mode = off
# 执行日志存储后端：bbolt（默认）或 file（JSON Lines）
#run_log_store_type = bbolt
# 每条规则链保留最近 N 条日志，0 表示不限制
#run_log_retention_count = 500
# 保留最近 N 天日志，0 表示不限制
#run_log_retention_days = 7
# 脚本执行超时时间（毫秒）
script_max_execution_time = 5000
# 组件市场基础 URL
#marketplace_base_url =
# 将主 HTTP 服务器注入每个用户节点池作为共享节点（多租户慎用）
share_http_server = false
# 是否启用 endpoint 框架（MQTT、Kafka 等外部集成）
#endpoint_enabled = true
# 处理核心事件总线事件的规则链 ID
#event_bus_chain_id =
# 是否按分类文件夹组织规则链
#category_folder_enabled = false

# =============================================================================
# HTTP 服务配置
# =============================================================================
# 是否允许跨域请求
allow_cors = true
# HTTP 读超时（秒）
read_timeout = 30
# HTTP 写超时（秒），AI 流式输出需要较大值
write_timeout = 300
# 最大请求体大小（MB）
max_body_size = 10

# =============================================================================
# AI 工具安全配置（需 with_ai / with_all 构建标签，否则忽略）
# =============================================================================
[ai_security]
# 是否启用工具安全拦截
enable = false
# 拦截模式：deny（黑名单）或 allow（白名单）
mode = deny
# 黑名单模式下拦截的工具（逗号分隔，支持 * 通配）
#deny_tools = bash,write,edit
# 白名单模式下允许的工具
#allow_tools = read,plan,skill
# 拦截的工具类型：builtin, mcp, rulechain, subagent
#denied_types =
# bash 工具额外命令黑名单
#cmd_deny_extra = curl,wget
# 文件路径黑名单，优先级高于 allow_paths，支持通配符
#deny_paths = ./config*
# 文件路径白名单，为空则不限制
#allow_paths = /tmp

# =============================================================================
# MCP 配置
# =============================================================================
[mcp]
enable = true

# MCP 分组配置（支持 * 通配、- 排除、rules/components/chains 类别关键字）
[mcp.groups]
manager = preview_rule_chain,save_rule_chain,list_rule_chains,get_rule_chain,delete_rule_chain,operate_rule_chain,execute_rule_chain,list_components,get_component_doc
# readonly = rules,list_components,get_component_doc
# full = *

# =============================================================================
# pprof 配置
# =============================================================================
[pprof]
enable = false
addr = 0.0.0.0:6060

# =============================================================================
# 全局自定义配置（组件可通过 ${global.xxx} 取值）
# =============================================================================
[global]
#sqlDriver = mysql
#sqlDsn = root:root@tcp(127.0.0.1:3306)/test
# AI Agent LLM 配置
#llm_url = https://api.openai.com/v1
#llm_api_key = sk-xxx
#llm_model = gpt-4o

# =============================================================================
# 用户配置（格式：username = password[,apiKey]）
# =============================================================================
[users]
admin = admin
user01 = user01

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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

在 GitHub 上编辑此页

上次更新: 2026/08/13, 09:22:24

← 概述与快速开始用户认证与权限→