---
title: "创建或更新安全用户"
date: 2026-02-06
lastmod: 2026-02-06
description: "介绍如何在 Easysearch 中创建或更新内部用户配置。"
tags: ["安全", "用户", "认证"]
summary: "此 API 用于创建或更新 Easysearch 内部用户。
API #  PUT /_security/user/{name} API 的作用 #  创建新的内部用户或更新已存在的用户配置。此 API 是 Easysearch 安全模块的一部分，用于管理系统用户账户。
API 的参数 #  路由参数 #     参数 类型 是否必需 描述     name string 必需 用户名    查询字符串参数 #     参数 类型 是否必需 默认值 描述     refresh string 可选 wait_downgrade 刷新策略
wait_for：等待刷新完成
false：不刷新    请求体参数 #     参数 类型 是否必需 默认值 描述     password string 条件* - 用户的明文密码"
---


此 API 用于创建或更新 Easysearch 内部用户。

## API

```
PUT /_security/user/{name}
```

## API 的作用

创建新的内部用户或更新已存在的用户配置。此 API 是 Easysearch 安全模块的一部分，用于管理系统用户账户。

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `name` | string | 必需 | 用户名 |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `refresh` | string | 可选 | wait_downgrade | 刷新策略<br>`wait_for`：等待刷新完成<br>`false`：不刷新 |

### 请求体参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `password` | string | 条件* | - | 用户的明文密码<br>创建用户时必需（如果未提供 hash） |
| `hash` | string | 条件* | - | 预哈希的密码值<br>与 password 二选一 |
| `roles` | array | 可选 | [] | 分配给用户的内部角色列表 |
| `external_roles` | array | 可选 | [] | 分配给用户的外部角色列表<br>如 LDAP 角色 |
| `attributes` | object | 可选 | {} | 用户自定义的键值对属性 |
| `description` | string | 可选 | - | 用户描述信息 |
| `reserved` | boolean | 可选 | false | 是否为保留用户<br>仅超级管理员可设置 |
| `hidden` | boolean | 可选 | false | 是否为隐藏用户<br>隐藏用户在列表查询中不显示 |

**注意**：`password` 和 `hash` 必须提供其中一个。

## 请求示例

### 创建基本用户

```json
PUT /_security/user/alice
{
  "password": "alice123",
  "roles": ["viewer"]
}
```

### 创建带完整信息的用户

```json
PUT /_security/user/admin
{
  "password": "admin123",
  "roles": ["security_admin", "system_monitor"],
  "external_roles": ["ldap_admins"],
  "attributes": {
    "department": "IT",
    "location": "Beijing"
  },
  "description": "System administrator"
}
```

### 更新现有用户

```json
PUT /_security/user/alice
{
  "password": "new_password",
  "roles": ["editor", "viewer"]
}
```

### 创建隐藏用户

```json
PUT /_security/user/system_user
{
  "password": "secure_password",
  "roles": ["system_role"],
  "hidden": true,
  "reserved": true
}
```

## 响应示例

### 成功响应 - 创建用户

```json
{
  "status": "CREATED",
  "message": "User alice created"
}
```

### 成功响应 - 更新用户

```json
{
  "status": "OK",
  "message": "User alice updated"
}
```

### 错误响应 - 密码不符合要求

```json
{
  "error": {
    "root_cause": [
      {
        "type": "validation_exception",
        "reason": "Password does not meet complexity requirements"
      }
    ],
    "type": "validation_exception",
    "reason": "Password does not meet complexity requirements"
  },
  "status": 400
}
```

## 密码验证规则

密码需要满足以下规则：

1. **非空检查**：密码不能为空字符串
2. **复杂度要求**：如果配置了密码正则表达式，密码必须匹配
3. **不重复用户名**：密码不能与用户名相同（不区分大小写）

## 用户属性

用户属性（attributes）可以存储任意键值对信息，例如：

```json
{
  "password": "user123",
  "roles": ["viewer"],
  "attributes": {
    "department": "Engineering",
    "team": "Backend",
    "location": "Beijing",
    "employee_id": "12345"
  }
}
```

## 权限要求

- **创建用户**：需要 `manage_security` 权限
- **更新用户**：需要 `manage_security` 权限或修改自己的密码
- **保留用户**：只有超级管理员可以创建/修改保留用户

## 注意事项

1. 此 API 使用 PUT 方法
2. 明文密码会在存储时自动转换为哈希值
3. 指定的角色必须存在，否则会返回错误
4. 保留用户不能被普通用户修改
5. 隐藏用户在列表查询中默认不显示

## 安全建议

1. **强密码**：使用强密码策略
2. **最小权限**：只授予用户必需的角色
3. **定期更换**：定期更换用户密码
4. **审计日志**：记录用户变更操作
5. **禁用不使用**：删除或禁用不再使用的账户

## 相关文档

- [查询安全用户](./get-security-user.md)
- [删除安全用户](./delete-security-user.md)
- [查询安全角色](./get-security-role.md)
- [创建或更新安全角色](./create-or-update-security-role.md)