---
title: "别名（Aliases）"
date: 0001-01-01
description: "索引别名的使用以及安全迁移索引的常见模式。"
summary: "别名（Aliases） #  别名（Alias）是指向一个或多个索引的"虚拟名称"，常用于实现无感迁移、蓝绿切换、按条件路由等功能。合理使用别名，可以让上游客户端几乎不感知底层索引的重建与演进。
最常用的场景：无感重建索引 #  典型需求：你想调整 mapping/设置，只能重建一个新索引，但又不希望业务代码改来改去。
做法示意：
 当前索引为 logs_v1，别名为 logs，所有读写都通过 logs 创建新索引 logs_v2，并将数据迁移过去 将别名 logs 从 logs_v1 原子性切换到 logs_v2 业务只需始终访问 logs，不关心具体版本  好处：
 切换时可以做到"近乎无停机" 可以在后台验证新索引的可用性与正确性，再切换别名  多索引聚合访问 #  别名还可以指向多个索引，例如：
 别名 logs_all → 指向 logs_2024_01、logs_2024_02、logs_2024_03 等  查询 logs_all 即可同时访问多个时间分片索引    这种方式对时间序列/多分片索引的统一查询非常有用。
按条件路由的读写别名 #  别名还可以带有过滤条件或路由信息，例如：
 为某个租户创建只读别名，只能看见自己的数据 为某些写入创建"写别名"，将写入路由到特定索引/分片  这类高级用法可以在多租户、数据分层等场景中减少上游逻辑复杂度，但也需要更严格的管理与规范。
 API 操作 #  创建索引别名 #  使用 actions 方法指定要执行的操作列表："
---


# 别名（Aliases）

别名（Alias）是指向一个或多个索引的"虚拟名称"，常用于实现**无感迁移、蓝绿切换、按条件路由**等功能。合理使用别名，可以让上游客户端几乎不感知底层索引的重建与演进。

## 最常用的场景：无感重建索引

典型需求：你想调整 mapping/设置，只能重建一个新索引，但又不希望业务代码改来改去。

做法示意：

1. 当前索引为 `logs_v1`，别名为 `logs`，所有读写都通过 `logs`
2. 创建新索引 `logs_v2`，并将数据迁移过去
3. 将别名 `logs` 从 `logs_v1` 原子性切换到 `logs_v2`
4. 业务只需始终访问 `logs`，不关心具体版本

好处：

- 切换时可以做到"近乎无停机"
- 可以在后台验证新索引的可用性与正确性，再切换别名

## 多索引聚合访问

别名还可以指向多个索引，例如：

- 别名 `logs_all` → 指向 `logs_2024_01`、`logs_2024_02`、`logs_2024_03` 等
  - 查询 `logs_all` 即可同时访问多个时间分片索引

这种方式对时间序列/多分片索引的统一查询非常有用。

## 按条件路由的读写别名

别名还可以带有过滤条件或路由信息，例如：

- 为某个租户创建只读别名，只能看见自己的数据
- 为某些写入创建"写别名"，将写入路由到特定索引/分片

这类高级用法可以在多租户、数据分层等场景中减少上游逻辑复杂度，但也需要更严格的管理与规范。

---

## API 操作

### 创建索引别名

使用 `actions` 方法指定要执行的操作列表：

```json
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "index-1",
        "alias": "alias1"
      }
    }
  ]
}
```

响应：

```json
{
  "acknowledged": true
}
```

> 如果此请求失败，请确保要添加到别名的索引已存在。

检查别名是否引用了指定索引：

```json
GET alias1
```

### 添加与删除操作

你可以在同一 `_aliases` 操作中执行多个操作。例如，以下命令删除 `index-1` 并将 `index-2` 添加到 `alias1`：

```json
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "index-1",
        "alias": "alias1"
      }
    },
    {
      "add": {
        "index": "index-2",
        "alias": "alias1"
      }
    }
  ]
}
```

`add` 和 `remove` 操作以**原子方式**发生，这意味着 `alias1` 不会同时指向 `index-1` 和 `index-2`。

还可以基于索引模式添加索引：

```json
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "index*",
        "alias": "alias1"
      }
    }
  ]
}
```

### 创建索引时添加别名

```json
PUT index-1
{
  "aliases": {
    "alias1": {}
  }
}
```

### 管理别名

列出别名到索引的映射：

```json
GET _cat/aliases?v
```

检查别名指向的索引：

```json
GET _alias/alias1
```

查找指向特定索引的别名：

```json
GET /index-2/_alias/*
```

检查别名是否存在：

```json
HEAD /alias1/_alias/
```

### 根据筛选条件创建别名

可以创建过滤的别名来访问底层索引中的文档子集：

```json
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "index-1",
        "alias": "alias1",
        "filter": {
          "term": {
            "timestamp": "1574641891142"
          }
        }
      }
    }
  ]
}
```

### 别名选项

| 选项             |  类型  | 描述                                                                    | 必填 |
| ---------------- | :----: | ----------------------------------------------------------------------- | ---- |
| `index`          | String | 别名指向的索引名                                                        | Yes  |
| `alias`          | String | 别名名称                                                                | No   |
| `filter`         | Object | 过滤条件                                                                | No   |
| `routing`        | String | 路由到特定分片，可以分别设置 `search_routing` 或者 `index_routing` 参数 | No   |
| `is_write_index` | String | 别名是否允许接收写入操作，如果不指定则表示不允许                        | No   |

---

## 使用别名时的注意事项

- 保证别名命名规范，与真实索引名有清晰区分（如统一使用 `_vN` 作为真实索引后缀）
- 别名切换应使用原子操作，避免出现短暂的"指向多个不一致索引"的窗口
- 在监控与排障时，注意区分"别名视图"与"真实索引"，避免混淆

## 小结

- 别名是做索引演进与重建时的重要工具，可以极大降低对上游的侵入
- 在设计索引生命周期（建/删/迁移）时，应优先考虑通过别名来隔离"调用方感知的名字"与"实际索引名字"

## 相关文档

- [索引管理]({{< relref "./index-management" >}})：创建/删除索引与零停机切换
- [索引设置]({{< relref "./index-settings" >}})
- [时间序列建模]({{< relref "/docs/best-practices/data-modeling/time-series" >}})
- [多租户建模]({{< relref "/docs/best-practices/data-modeling/multi-tenancy" >}})