RuleGo-Server 提供灵活的用户认证与权限体系，支持 JWT 令牌和 API Key 两种认证方式，并可通过接口自定义认证器和授权器。

用户管理

在 config.conf 的 [users] 段配置用户：

[users]
# 格式：username = password[,apiKey]
# apiKey 可选
admin = admin,ak-2af255ea5618467d914c67a8beeca31d
user01 = user01
user02 = user02,ak-another-key

每个用户拥有独立的工作空间，规则链、组件、配置等数据按用户隔离。

除配置文件外，运行时也可通过用户管理 API 增删改查用户（仅 admin 角色可用），参见下文用户管理 API。

角色体系

每个用户可分配一个或多个角色，决定该账号能做什么：

角色	说明
admin	全权，含用户管理
editor	自己工作空间内全部读写，不能管理用户
viewer	只读

匿名访问（require_auth = false 且未携带凭证）和未分配角色的用户，默认授权器视为 admin，保持开箱体验。生产环境建议开启认证并为用户分配明确角色。

认证方式

匿名模式（默认）

当 require_auth = false 且请求未携带认证信息时，以 default_username（默认 admin）身份访问：

require_auth = false
default_username = admin

JWT 认证

开启认证：

require_auth = true
jwt_secret_key = your-secret-key
jwt_expire_time = 43200000
jwt_issuer = rulego.cc

登录获取令牌

POST /api/v1/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin"
}

响应：

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": 1719360000
}

expiresAt 为 Unix 时间戳（秒）。登录接口有速率限制：同一 IP 每分钟最多 10 次，超限返回 429。

使用令牌

在后续请求中通过 Authorization 头携带令牌：

GET /api/v1/rules
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key 认证

为用户配置 apiKey 后，可直接使用 API Key 代替 JWT：

方式一：Authorization 头

GET /api/v1/rules
Authorization: Bearer ak-2af255ea5618467d914c67a8beeca31d

方式二：X-API-Key 头

GET /api/v1/rules
X-API-Key: ak-2af255ea5618467d914c67a8beeca31d

API Key 常用于 MCP 客户端接入、第三方系统集成等场景，无需登录流程。

权限体系

权限动作

资源	动作	说明
rule	read / write / delete / execute / operate	规则链管理
component	read / write / delete	组件管理
skill	read / write / delete	技能管理
user	read / write / delete	用户管理（仅 admin）
config	read / write	系统配置
log	read / delete	运行日志
locale	read / write	国际化
marketplace	read	组件市场

默认授权器

DefaultAuthorizer 按角色判权：

• 匿名用户和未分配角色的用户：放行所有操作（开箱体验）
• admin：放行所有操作
• user 资源：仅 admin 可操作
• read / list 等只读动作：所有角色放行
• 其余写操作：editor 放行，viewer 拒绝

数据隔离由各用户的独立存储保证（每个请求只能看到自己 username 下的数据），授权器只管「能做什么动作」。

自定义认证器/授权器

RuleGo-Server 的认证和授权是可替换的，通过服务容器注入自定义实现：

服务键	接口	说明
module.user.authenticator	Authenticator	自定义认证逻辑（OAuth2、LDAP 等）
module.user.authorizer	Authorizer	自定义授权逻辑（RBAC、ABAC 等）
module.user.admin	UserAdmin	自定义用户存储与管理

二次开发参见 二次开发。

用户管理 API

以下接口需认证后访问，除查询自身信息外仅 admin 角色可用：

方法	路径	说明
GET	/api/v1/users/me	获取当前登录用户信息（用户名、角色、apiKey 等）
PATCH	/api/v1/users/me	修改当前用户信息（如密码）
GET	/api/v1/users	列出所有用户（admin）
POST	/api/v1/users	创建或更新用户（admin），可指定角色、apiKey、停用状态
DELETE	/api/v1/users/:targetUsername	删除用户（admin），加 ?purge=true 同时清除该用户数据目录

限制：不能删除当前登录用户自己，也不能删除 default_username 配置的默认用户。配置文件 [users] 段的内置账号不在运行时用户存储中，需通过修改配置文件管理。