---
title: "创建或更新安全角色"
date: 2026-01-15
lastmod: 2026-01-15
description: "创建新角色或更新现有角色"
tags: ["安全", "角色", "权限管理"]
summary: "在 Easysearch 安全系统中创建新角色或更新现有角色的权限配置。
API 格式 #  PUT /_security/role/{name} API 作用 #  该 API 用于创建或更新安全角色：
 创建新角色并定义其权限 完全更新现有角色的配置 定义集群级别和索引级别的权限  API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {name} String 是 - 角色名称    请求体参数 #     参数 类型 是否必填 默认值 描述     cluster String[] 否 [] 集群级别的权限列表   indices Object[] 否 [] 索引级别的权限配置数组   description String 否 - 角色的描述信息   reserved Boolean 否 false 是否为保留角色（仅超级管理员可设置）   hidden Boolean 否 false 是否为隐藏角色   static Boolean 否 false 是否为静态角色（不可修改）    indices 数组元素结构 #     字段 类型 是否必填 描述     names String[] 是 索引模式列表（如 ["*"]、["logs-*"]）   privileges String[] 是 索引权限列表（如 ["ALL"]、["READ_UT"]）   query String 否 文档级安全查询（过滤文档）   field_security String[] 否 可访问的字段列表   field_mask String[] 否 需要隐藏的字段列表    请求示例 #  创建管理员角色 #  PUT /_security/role/admin { "cluster": ["*"], "indices": [ { "names": ["*"], "privileges": ["*"] } ], "description": "拥有所有权限的管理员角色" } 创建只读角色 #  PUT /_security/role/readonly_user { "cluster": ["cluster:monitor/health"], "indices": [ { "names": ["logs-*"], "field_security": ["timestamp", "message", "level"], "privileges": ["indices:data/read/search"] } ], "description": "只读访问日志索引，限制字段访问" } 创建带文档级安全的角色 #  PUT /_security/role/department_manager { "indices": [ { "names": ["employee-*"], "query": "{\"term\": {\"department\": \"engineering\"}}", "privileges": ["READ_UT"] } ], "description": "只能查看工程部门的文档" } 创建数据分析师角色 #  PUT /_security/role/data_analyst { "cluster": ["cluster:monitor/health", "cluster:monitor/nodes/info"], "indices": [ { "names": ["sales-*", "marketing-*"], "privileges": ["READ_UT", "indices:data/read/search"], "field_mask": ["salary", "ssn"] }, { "names": ["reports-*"], "privileges": ["ALL"] } ], "description": "数据分析师角色，可访问销售和营销数据" } 响应示例 #  创建成功（201 Created） #  { "status": "CREATED", "message": "'admin' created."
---


在 Easysearch 安全系统中创建新角色或更新现有角色的权限配置。

## API 格式

```
PUT /_security/role/{name}
```

## API 作用

该 API 用于创建或更新安全角色：
- 创建新角色并定义其权限
- 完全更新现有角色的配置
- 定义集群级别和索引级别的权限

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{name}` | String | **是** | - | 角色名称 |

### 请求体参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `cluster` | String[] | 否 | `[]` | 集群级别的权限列表 |
| `indices` | Object[] | 否 | `[]` | 索引级别的权限配置数组 |
| `description` | String | 否 | - | 角色的描述信息 |
| `reserved` | Boolean | 否 | `false` | 是否为保留角色（仅超级管理员可设置） |
| `hidden` | Boolean | 否 | `false` | 是否为隐藏角色 |
| `static` | Boolean | 否 | `false` | 是否为静态角色（不可修改） |

### indices 数组元素结构

| 字段 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `names` | String[] | **是** | 索引模式列表（如 `["*"]`、`["logs-*"]`） |
| `privileges` | String[] | **是** | 索引权限列表（如 `["ALL"]`、`["READ_UT"]`） |
| `query` | String | 否 | 文档级安全查询（过滤文档） |
| `field_security` | String[] | 否 | 可访问的字段列表 |
| `field_mask` | String[] | 否 | 需要隐藏的字段列表 |

## 请求示例

### 创建管理员角色

```json
PUT /_security/role/admin
{
  "cluster": ["*"],
  "indices": [
    {
      "names": ["*"],
      "privileges": ["*"]
    }
  ],
  "description": "拥有所有权限的管理员角色"
}
```

### 创建只读角色

```json
PUT /_security/role/readonly_user
{
  "cluster": ["cluster:monitor/health"],
  "indices": [
    {
      "names": ["logs-*"],
      "field_security": ["timestamp", "message", "level"],
      "privileges": ["indices:data/read/search"]
    }
  ],
  "description": "只读访问日志索引，限制字段访问"
}
```

### 创建带文档级安全的角色

```json
PUT /_security/role/department_manager
{
  "indices": [
    {
      "names": ["employee-*"],
      "query": "{\"term\": {\"department\": \"engineering\"}}",
      "privileges": ["READ_UT"]
    }
  ],
  "description": "只能查看工程部门的文档"
}
```

### 创建数据分析师角色

```json
PUT /_security/role/data_analyst
{
  "cluster": ["cluster:monitor/health", "cluster:monitor/nodes/info"],
  "indices": [
    {
      "names": ["sales-*", "marketing-*"],
      "privileges": ["READ_UT", "indices:data/read/search"],
      "field_mask": ["salary", "ssn"]
    },
    {
      "names": ["reports-*"],
      "privileges": ["ALL"]
    }
  ],
  "description": "数据分析师角色，可访问销售和营销数据"
}
```

## 响应示例

### 创建成功（201 Created）

```json
{
  "status": "CREATED",
  "message": "'admin' created."
}
```

### 更新成功（200 OK）

```json
{
  "status": "OK",
  "message": "'data_analyst' updated."
}
```

### 错误响应 - 无效参数

```json
{
  "error": {
    "root_causes": [
      {
        "type": "invalid_parameter_exception",
        "reason": "Invalid keys [unknownkey] found"
      }
    ],
    "type": "invalid_parameter_exception",
    "reason": "Invalid keys [unknownkey] found"
  },
  "status": 400
}
```

### 错误响应 - 权限不足

```json
{
  "status": "FORBIDDEN",
  "message": "No permission to access REST API"
}
```

## 常用权限说明

### 集群级别权限

| 权限 | 描述 |
|------|------|
| `"*"` 或 `"cluster:*"` | 所有集群权限 |
| `"cluster:monitor/health"` | 监控集群健康状态 |
| `"cluster:monitor/nodes/info"` | 获取节点信息 |
| `"cluster:all"` | 所有集群监控权限 |

### 索引级别权限

| 权限 | 描述 |
|------|------|
| `"*"` 或 `"ALL"` | 所有索引权限 |
| `"READ_UT"` | 读取、查看和索引映射 |
| `"CRUD_UT"` | 创建、读取、更新、删除 |
| `"indices:data/read/search"` | 搜索权限 |
| `"indices:data/write/index"` | 索引文档权限 |
| `"indices:admin/create"` | 创建索引权限 |
| `"indices:admin/refresh"` | 刷新索引权限 |

## HTTP 状态码

| 状态码 | 描述 |
|--------|------|
| 200 OK | 角色更新成功 |
| 201 Created | 角色创建成功 |
| 400 Bad Request | 无效的请求体验证错误 |
| 401 Unauthorized | 身份验证失败 |
| 403 Forbidden | 权限不足 |
| 404 Not Found | 安全配置未初始化 |

## 注意事项

1. **完全替换**：更新角色时需要提供完整的角色定义（部分更新使用 PATCH）
2. **角色名称**：角色名称在 URL 路径中指定，而非请求体中
3. **权限初始化**：使用此 API 前必须先初始化安全配置
4. **保留角色**：只有超级管理员可以设置 `reserved=true`
5. **字段掩码**：`field_mask` 中的字段将返回为 `null` 值
6. **文档级安全**：`query` 参数使用查询 DSL 语法

## 相关操作

- **GET /_security/role**：查询所有角色
- **GET /_security/role/{name}**：查询指定角色
- **DELETE /_security/role/{name}**：删除角色
- **PATCH /_security/role/{name}**：部分更新角色

## 实现细节

- **处理器**：`RolesApiAction.java`
- **路由**：`PUT /_security/role/{name}`
- **验证**：`RolesValidator.java` 验证请求参数
- **配置存储**：角色配置存储在安全配置索引中
- **集群同步**：配置更改会传播到所有集群节点