# Apache Doris 开发、运维与使用 Wiki 手册

> 本手册依据 [Apache Doris 官方文档](https://doris.apache.org/docs/) 汇总，覆盖使用、开发、数据建模、数据导入、查询优化、集群运维与故障排查。
>
> **版本说明：** 官方文档的 `dev` 页面会随版本演进；生产环境请将本文命令、参数和特性与实际 Doris 版本的官方文档交叉确认。本文不替代版本发布说明和安全公告。

---

## 目录

- [1. 快速认知](#1-快速认知)
- [2. 架构与核心概念](#2-架构与核心概念)
- [3. 部署与连接](#3-部署与连接)
- [4. 数据库与表设计](#4-数据库与表设计)
- [5. SQL 使用](#5-sql-使用)
- [6. 数据导入](#6-数据导入)
- [7. 数据导出、更新与事务](#7-数据导出更新与事务)
- [8. 查询、索引与性能优化](#8-查询索引与性能优化)
- [9. 外部数据源与湖仓分析](#9-外部数据源与湖仓分析)
- [10. 应用开发与生态集成](#10-应用开发与生态集成)
- [11. 集群运维](#11-集群运维)
- [12. 监控、审计与安全](#12-监控审计与安全)
- [13. 备份、恢复与灾备](#13-备份恢复与灾备)
- [14. 故障排查](#14-故障排查)
- [15. 生产检查清单](#15-生产检查清单)
- [16. 官方文档索引](#16-官方文档索引)

---

## 1. 快速认知

### 1.1 Apache Doris 是什么

Apache Doris 是面向实时分析的分布式 MPP 数据库，兼容 MySQL 协议和较丰富的标准 SQL，适合：

- 实时数仓、报表和 BI 分析；
- 日志、行为、IoT 等明细数据分析；
- 高并发低延迟查询；
- 湖仓数据联邦查询；
- 半结构化数据和全文/向量相关场景（具体能力取决于版本）。

官方入口：[What is Apache Doris](https://doris.apache.org/docs/dev/getting-started/what-is-apache-doris/)。

### 1.2 最短上手路径

1. 选择 [快速开始](https://doris.apache.org/docs/4.x/getting-started/quick-start/) 或 Docker/Kubernetes 部署方式。
2. 通过 MySQL 客户端连接 FE 的 Query Port，默认 `9030`。
3. 创建数据库、表和分区/分桶。
4. 使用 `INSERT`、Stream Load、Routine Load 或 Broker Load 导入数据。
5. 用 `SELECT`、`EXPLAIN` 和 Profile 验证结果和性能。
6. 生产环境补齐副本、权限、监控、备份和升级方案。

### 1.3 关键设计原则

- **先选表模型，再设计 Key、分区和分桶**；表模型创建后不能直接切换。
- **先解决数据分布，再调 SQL**；错误的分桶和数据倾斜会限制所有查询。
- **优先批量写入**；避免频繁单行写入造成大量小 Rowset 和 Compaction 压力。
- **用 `EXPLAIN` 看计划、用 Profile 看实际执行**；不要仅凭 SQL 文本猜性能问题。
- **Label 用于导入幂等**；重试时使用稳定且唯一的业务 Label。
- **所有生产操作先在目标版本的官方文档中确认**；FE/BE 配置、SQL 和特性可能随版本变化。

### 1.4 Apache Doris 与传统数据库对比

本文所说的“传统数据库”主要指 MySQL、PostgreSQL、Oracle 等以单机/主从、行存储和 OLTP 为主的关系数据库。Doris 是面向分布式分析的 MPP 数据库，两者不是简单的高低替代关系，应该按业务工作负载选型。

#### 1.4.1 核心差异

| 对比项 | 传统关系数据库（典型 OLTP） | Apache Doris（典型 OLAP） |
|---|---|---|
| 首要目标 | 单行读写、事务、并发短请求 | 大规模扫描、聚合、Join、报表和实时分析 |
| 典型数据组织 | 行存储，按主键快速定位 | 列式存储，按列裁剪和向量化执行 |
| 架构 | 单机扩展或主从读扩展 | FE + BE 的分布式 MPP，查询并行跨节点执行 |
| 扩展方式 | 纵向扩展、读副本、分库分表 | 横向增加 BE/计算组，数据按 Tablet 分布 |
| 写入模式 | 高频单行 INSERT/UPDATE/DELETE | 批量导入、流式导入、CDC 和 Group Commit |
| 事务 | 通常支持完整 OLTP 事务、行锁和更细粒度隔离 | 支持导入事务和部分显式事务，但不等同于 OLTP 行锁模型 |
| 索引 | B-Tree、Hash 等通用二级索引 | 排序 Key、前缀索引、Bloom Filter、倒排索引、物化视图等 |
| 表设计重点 | 主键、外键、范式、锁竞争 | 表模型、Key、分区、分桶、Tablet、副本和数据倾斜 |
| 查询特点 | 小结果集、点查、短事务 | 大结果集、聚合、窗口函数、复杂 Join、扫描分析 |
| 高可用 | 主从、故障切换、读写分离 | FE 元数据高可用、BE 多副本、Tablet 自动修复 |
| 一致性重点 | 单行/多行事务一致性 | 导入原子性、Label 幂等、可见性和副本一致性 |
| 适合的数据量 | 中小规模在线业务库，也可通过分片扩展 | TB/PB 级分析数据，具体上限取决于硬件和架构 |
| 接入方式 | JDBC/ODBC、应用事务 | MySQL 协议、JDBC/ODBC、HTTP Stream Load、Connector |

#### 1.4.2 何时继续使用传统数据库

以下场景通常应继续使用 MySQL/PostgreSQL/Oracle 等 OLTP 数据库：

- 订单、支付、账户、库存等核心交易链路；
- 大量单行点查和短事务写入；
- 强依赖行锁、外键、触发器、存储过程或完整事务语义；
- 单表数据量和分析压力尚未达到需要分布式 MPP 的程度；
- 业务要求极低延迟写入，而不是大批量分析吞吐。

#### 1.4.3 何时选择 Doris

Doris 更适合：

- 实时数仓、明细日志、用户行为和 IoT 分析；
- BI 报表、聚合指标和多维查询；
- 需要较高并发的分析查询；
- Kafka/Flink/CDC 持续写入并实时查询；
- 跨 Hive、Iceberg、Paimon、JDBC 等外部数据源查询；
- 需要通过分区、分桶、物化视图和列式存储降低扫描成本。

#### 1.4.4 常见架构组合

不要把 OLTP 数据库和 Doris 设计成互相替代，常见组合是：

```text
业务应用 → MySQL/PostgreSQL/Oracle（交易事实）
                    ↓ CDC / Binlog / 消息队列
              Kafka / Flink / Connector
                    ↓
             Apache Doris（分析与报表）
                    ↓
             BI、运营分析、数据服务
```

传统数据库保存权威交易状态，Doris 保存面向分析的明细或汇总数据。需要接受数据同步延迟、重复事件、乱序事件、删除传播和最终一致性等问题，并为同步链路设计幂等和补数机制。

#### 1.4.5 迁移时不能直接照搬的概念

| 传统数据库习惯 | Doris 中的对应思路 |
|---|---|
| 主键唯一约束 | 根据业务选择 Unique Key 表模型，并验证更新语义 |
| B-Tree 二级索引 | 通过排序 Key、分区分桶、Bloom/倒排索引和物化视图解决 |
| 分库分表 | 优先使用 Catalog/Database、Partition、Bucket 和 BE 横向扩展 |
| 单行 UPDATE | 批量 upsert、CDC 或合适的 Unique Key 导入 |
| 外键约束 | 通常在上游保证数据关系，Doris 侧重点是分析查询 |
| OLTP 事务 | 使用导入事务、Label、两阶段提交或 Connector 语义；不要假设完整行锁 |
| `SELECT *` | 明确选择列，利用列裁剪降低扫描 |
| 任意条件都依赖索引 | 先设计分区裁剪、排序 Key、分桶和物化视图 |
| 单节点容量 | 按 BE、Tablet、副本、磁盘和网络进行集群容量规划 |

#### 1.4.6 迁移评估清单

迁移前至少验证：

- DDL、数据类型、字符集、时区和 NULL 语义；
- `UPDATE`、`DELETE`、UPSERT、事务和回滚行为；
- 分页、排序、窗口函数、日期函数和隐式类型转换；
- 业务 SQL 的扫描量、Join 计划和结果正确性；
- CDC 的删除、乱序、重复、断点恢复和幂等；
- 目标数据量、增长率、并发、导入吞吐和查询 SLA；
- 权限、备份、恢复、监控和故障切换流程。

参考：[MySQL Compatibility](https://doris.apache.org/docs/dev/query-data/mysql-compatibility/)、[What is Apache Doris](https://doris.apache.org/docs/dev/getting-started/what-is-apache-doris/)、[Product Concepts](https://doris.apache.org/docs/dev/features-architecture/product-concepts/)。

---

## 2. 架构与核心概念

### 2.1 两种部署架构

#### 集成存算（Integrated Storage and Compute）

- **FE（Frontend）**：SQL 接入、解析与优化、元数据管理、事务协调、集群管理。
- **BE（Backend）**：数据存储、计算执行、导入和 Compaction。
- 数据通常存储在 BE 本地磁盘，副本分布在多个 BE。
- 适用于传统数仓和本地存储场景。

#### 存算分离（Compute-Storage Decoupled）

- 计算节点独立扩缩容；数据放在对象存储等共享存储中。
- 由 FE、MetaService、Compute Group、FoundationDB 和 Storage Vault 等组件协同。
- 适用于弹性计算、云环境和多计算组场景。
- 与集成存算的可用特性、部署方式和限制并不完全相同。

官方参考：[System Architecture](https://doris.apache.org/docs/4.x/features-architecture/system-architecture/)、[Product Concepts](https://doris.apache.org/docs/dev/features-architecture/product-concepts/)。

### 2.2 FE 角色

常见 FE 角色：

- **Follower**：参与元数据日志选举和复制，生产环境通常部署奇数个。
- **Observer**：同步元数据但不参与 Leader 选举，适合分担查询接入。
- **Leader**：由 Follower 选举产生，负责元数据变更协调。

FE 元数据目录必须持久化。FE 宕机不会直接丢失 BE 数据，但元数据和日志可用性决定集群是否能正常工作。

### 2.3 BE、Tablet 与副本

- 表被划分为 Partition。
- Partition 再按分桶规则划分为 Bucket。
- Bucket 对应物理存储分片 Tablet。
- Tablet 通常有多个副本，分布在不同 BE。
- FE 维护 Tablet 元数据；BE 负责数据文件、索引、查询和 Compaction。

常用检查：

```sql
SHOW FRONTENDS;
SHOW BACKENDS;
SHOW TABLETS FROM db_name.table_name;
ADMIN SHOW REPLICA STATUS FROM db_name.table_name;
```

### 2.4 默认端口（集成存算）

| 组件 | 端口 | 用途 |
|---|---:|---|
| FE | 8030 | HTTP 管理/接口 |
| FE | 9010 | FE 编辑日志和节点间通信 |
| FE | 9020 | FE RPC |
| FE | 9030 | MySQL 协议 Query Port |
| BE | 8040 | BE HTTP 服务 |
| BE | 9050 | Heartbeat 服务 |
| BE | 9060 | BE Thrift 服务 |
| BE | 8060 | BE BRPC 服务 |

以实际 `fe.conf`、`be.conf` 和 [Cluster Planning](https://doris.apache.org/docs/dev/install/preparation/cluster-planning/) 为准。防火墙必须放通客户端到 FE Query Port，以及 FE/BE、BE/BE 之间所需的内部端口。

### 2.5 Catalog、Database、Table

Doris 的逻辑层次是：

```text
Catalog → Database → Table
```

- `internal` Catalog：Doris 内部存储。
- External Catalog：连接 Hive、Iceberg、Paimon、JDBC 等外部数据源。
- Database：逻辑隔离单元。
- Table：内部表或外部表，是查询和数据管理的基本对象。

---

## 3. 部署与连接

### 3.1 部署方式选择

| 方式 | 适用场景 | 说明 |
|---|---|---|
| Docker | 学习、开发、功能验证 | 最快，但不等于生产部署 |
| 物理机/虚拟机 | 传统生产环境 | 需要自行规划磁盘、网络、进程和升级 |
| Kubernetes + Doris Operator | 云原生环境 | 通过 CRD 管理 FE、BE、存储和服务暴露 |
| 公有云/托管服务 | 快速生产落地 | 依赖云厂商提供的 Doris 服务 |

官方入口：[Installation and Deployment](https://doris.apache.org/docs/dev/install/intro/)、[Deploy on Kubernetes](https://doris.apache.org/docs/dev/install/deploy-on-kubernetes/intro/)。

### 3.2 生产集群规划

建议在部署前明确：

- Doris 版本、JDK/OS、升级窗口和回滚方案；
- 集成存算还是存算分离；
- FE 节点数量和角色；
- BE 数量、磁盘数量、磁盘类型和副本数；
- 预估数据量、增长量、查询并发、导入吞吐；
- 分区周期、Tablet 大小、桶数和未来扩容；
- 客户端接入地址、负载均衡、TLS 和网络隔离；
- 监控、日志、备份和告警；
- 是否需要 Kafka、对象存储、Flink/Spark 或外部 Catalog。

集成存算生产环境通常至少准备 3 个 BE 才能使用 3 副本；单节点或低副本仅适合开发测试。存算分离的节点规划不同，必须按对应版本文档执行。

### 3.3 硬件与环境基线

以下是官方环境检查文档给出的**起步参考**，不是容量规划结果；生产规格应以数据量、并发、导入吞吐和压测结果为准。

| 项目 | 最低参考 | 生产推荐参考 |
|---|---|---|
| CPU | 支持 AVX2；至少 8 核用于最小环境 | 16 核及以上；优先选择支持 AVX2 的新一代 CPU |
| FE 内存 | 16 GB | 64 GB 及以上 |
| BE 内存 | CPU 核数 × 4 GB | CPU 核数 × 8 GB |
| FE 磁盘 | SSD，10 GB 以上用于测试 | 独立 SSD，100 GB 以上用于元数据和日志 |
| BE 磁盘 | SSD 或 HDD，50 GB 以上用于测试 | SSD 优先；冷数据可使用 HDD/对象存储，多盘分布数据目录 |
| 文件系统 | ext4 或 XFS | ext4 或 XFS |
| 网络 | 1 GbE | 10 GbE 及以上；多网卡可做链路聚合 |
| 架构 | x86-64 或 ARM64 | 与目标 Doris 版本和镜像/安装包匹配 |

#### 3.3.1 节点数量与故障域

- **FE**：生产建议至少 3 个 Follower，数量保持奇数，并分布在不同物理机/机架/可用区；Observer 按查询接入压力增加。
- **BE（集成存算）**：生产通常至少 3 个 BE，以支持 3 副本和水平扩展；副本数不能超过可用 BE 数量。
- **存算分离**：BE/Compute Group 数量不再等同于数据副本数，但 MetaService、FoundationDB、对象存储和缓存仍需要独立规划高可用。
- FE 与 BE 生产上优先分开部署；必须混部时，将 FE 元数据和 BE 数据放到不同磁盘，并评估资源争用。

#### 3.3.2 容量估算

集成存算可先用以下保守估算做容量起点：

```text
BE 原始数据盘 ≈ 数据量 × 副本数 × 1.4
```

官方示例按 3 副本和 40% 后台 Compaction/运行预留估算；实际还要加入压缩率、索引、物化视图、临时文件、备份、历史增长和扩容余量。务必明确“数据量”是原始数据量还是压缩后数据量，不能把该公式当作最终采购值。存算分离时本地 BE 磁盘主要用于缓存，容量应按热数据和缓存策略规划。

#### 3.3.3 磁盘与网络要求

- FE `doris-meta` 使用独立、低延迟 SSD，不要放在安装目录或慢盘上；
- BE 可通过 `storage_root_path` 配置多块数据盘，避免只使用单盘 I/O；
- 高并发查询、频繁更新和 Compaction 优先使用 SSD；冷数据再考虑 HDD/对象存储；
- 10 GbE 是生产推荐起点，存算分离和大规模 Shuffle 应结合对象存储、交换机和跨可用区带宽实测；
- 为数据、日志、临时文件和 Trash 预留空间，不能按磁盘标称容量满配。

#### 3.3.4 操作系统基线

部署前至少检查：

- 关闭 Swap 和 Transparent Huge Pages（THP）；
- 提高进程文件句柄和虚拟内存区域限制；
- 避免 CPU 省电策略导致频率大幅波动；
- 使用 NTP/Chrony 同步集群时钟，官方要求元数据时间偏差小于 5000 ms；
- 校验 `priority_networks`、MTU、防火墙和 FE/BE 所有内部端口；
- 生产节点使用固定版本的 OS、JDK、内核和 Doris 安装包。

参考：[Hardware and Software Environment Check](https://doris.apache.org/docs/dev/install/preparation/env-checking/)、[Operating System Checks](https://doris.apache.org/docs/dev/install/preparation/os-checking/)。

#### 3.3.5 Kubernetes 资源参考

Doris Operator 文档给出的最小启动资源约为 FE/BE 各 4 CPU、8 GiB；正常能力测试建议 8 CPU、8 GiB，生产示例常从 FE 6 CPU/12 GiB、BE 8 CPU/16 GiB 起步。它们仅用于启动和测试，不代表生产容量。生产必须显式设置 requests/limits、持久化卷和 StorageClass，并用压测调整资源。

### 3.4 Docker 快速验证

Docker 仅用于快速验证，正式环境应使用持久化卷、固定版本镜像、资源限制和可靠网络。

连接示例：

```bash
mysql -h 127.0.0.1 -P 9030 -uroot
```

首次使用时不要把“root 无密码”作为生产默认配置；上线前立即创建业务账号、修改密码并限制权限。

### 3.5 Kubernetes 部署要点

使用 Doris Operator 的典型流程：

```bash
# 1. 安装 Operator 和 CRD
# 2. 准备 DorisCluster 资源文件
kubectl apply -f doriscluster.yaml

# 3. 查看资源和 Pod
kubectl get dcr -A
kubectl get pods -n doris
kubectl get svc -n doris
```

生产注意事项：

- FE 元数据目录必须使用持久化存储；
- BE 数据目录和日志目录按需求持久化；
- 配置 requests/limits，避免无界资源使用；
- 根据访问范围选择 ClusterIP、NodePort 或 LoadBalancer；
- Stream Load 从集群外访问时，要确保 FE 重定向到的 BE 地址可达；
- Operator、Doris 镜像、CRD 和 Doris 版本要匹配；
- 滚动升级前确认 Operator 的升级说明和 Doris 的版本兼容矩阵。

### 3.6 MySQL 协议连接

```bash
mysql -h <fe-host> -P 9030 -u <user> -p
```

JDBC 示例：

```text
jdbc:mysql://<fe-host>:9030/<database>?useUnicode=true&characterEncoding=utf8
```

建议客户端连接 FE 的 VIP、负载均衡或稳定域名，不要把单个 BE 作为 SQL 接入点。

---

## 4. 数据库与表设计

### 4.1 三种核心表模型

| 模型 | 行为 | 典型场景 |
|---|---|---|
| Duplicate Key | 保留所有写入行，Key 主要用于排序 | 日志、事件、明细事实表 |
| Unique Key | 相同 Key 的行保留最新版本，支持更新/删除 | 订单、用户、CDC、实时维表 |
| Aggregate Key | 相同 Key 的 Value 按聚合函数合并 | 固定维度报表、指标汇总 |

选择建议：

- 只追加、需要保留原始明细：优先 Duplicate Key。
- 需要按主键更新或删除：选择 Unique Key，并理解 Merge-on-Write/Merge-on-Read 行为。
- 数据天然是聚合指标且不需要原始明细：选择 Aggregate Key。
- 不要仅因为“主键表看起来更像关系库”就使用 Unique Key；它有额外的更新、索引和维护成本。

参考：[Table Model Overview](https://doris.apache.org/docs/dev/table-design/data-model/intro/)、[Data Model](https://doris.apache.org/docs/dev/key-features/data-model/)。

### 4.2 Key 列、Value 列与排序

- `KEY(...)` 中的列是排序 Key；在 Unique/Aggregate 模型中还参与去重或聚合。
- Key 列应优先放置高频过滤、连接和排序使用的列。
- Key 不宜过宽；前缀索引只覆盖有限的前缀字节。
- 字段顺序、类型和基数会影响压缩、扫描和谓词过滤。
- 半结构化字段如 `ARRAY`、`MAP`、`STRUCT`、`JSON`、`VARIANT` 有额外限制，不能盲目作为 Key 或分桶列。

### 4.3 分区（Partition）

分区按范围或列表把数据水平切分，主要用于：

- 分区裁剪，减少扫描；
- 生命周期管理，例如删除历史分区；
- 按时间增量导入和滚动保留；
- 分区级备份、装载和维护。

时间事实表常见选择是按天或月 RANGE 分区。分区不要过细，否则会产生大量 Tablet、元数据和调度开销；也不要过粗，否则生命周期管理和查询裁剪效果变差。

动态分区和自动分区可以减少手工建分区，但要设置好历史保留窗口、未来分区数量和异常数据处理方式。

### 4.4 分桶（Bucket）

分桶决定数据如何分布到 Tablet：

- **Hash 分桶**：按列 Hash，支持基于分桶列的裁剪和特定 Join 优化。
- **Random 分桶**：随机均匀分布，降低错误分桶列导致的数据倾斜；适用范围和表模型有限制。

分桶列选择：

- 选择高基数、分布均匀的列；
- 避免大量 NULL、固定值或极度倾斜列；
- 结合常用等值过滤和 Join 键；
- Aggregate/Unique 表的分桶列必须符合其 Key 约束；
- 规划未来扩容，避免 Tablet 数和桶数过少；
- 不要机械地把桶数设得很大，Tablet 过多会增加调度、元数据和 Compaction 压力。

参考：[Data Bucketing](https://doris.apache.org/docs/dev/table-design/data-partitioning/data-bucketing/)。

### 4.5 一个可调整的建表示例

```sql
CREATE DATABASE IF NOT EXISTS demo;
USE demo;

CREATE TABLE IF NOT EXISTS user_events (
    event_time  DATETIME NOT NULL,
    user_id     BIGINT NOT NULL,
    event_type  VARCHAR(64),
    payload     JSON
)
DUPLICATE KEY(event_time, user_id)
PARTITION BY RANGE(event_time) (
    PARTITION p202501 VALUES LESS THAN ('2025-02-01'),
    PARTITION p202502 VALUES LESS THAN ('2025-03-01')
)
DISTRIBUTED BY HASH(user_id) BUCKETS 8
PROPERTIES (
    "replication_allocation" = "tag.location.default:3",
    "compression" = "ZSTD"
);
```

示例中的日期、桶数、副本数和压缩方式只是模板，不应直接复制到生产。

### 4.6 数据类型

常用类型：

- 整数：`TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`LARGEINT`；
- 小数：`DECIMAL` 系列；
- 时间：`DATE`、`DATETIME` 及对应 V2 类型；
- 字符串：`CHAR`、`VARCHAR`、`STRING`；
- 半结构化：`JSON`、`VARIANT`、`ARRAY`、`MAP`、`STRUCT`；
- 分析类型：`HLL`、`BITMAP`、`QUANTILE_STATE`、`AGG_STATE`。

原则：能使用定长、低精度类型时，不要默认使用超宽字符串或高精度小数；金额等字段必须根据精度要求选择 `DECIMAL`，不要用浮点数替代。

查看当前版本支持的类型：

```sql
SHOW DATA TYPES;
```

参考：[Data Types](https://doris.apache.org/docs/dev/table-design/data-type/)。

### 4.7 Schema 变更

常见操作：

```sql
ALTER TABLE demo.user_events ADD COLUMN source VARCHAR(32) DEFAULT 'unknown';
ALTER TABLE demo.user_events DROP COLUMN source;
SHOW ALTER TABLE COLUMN FROM demo;
```

注意：

- 表模型、分区列、分桶方式等关键设计通常不能直接修改；
- 大表变更要评估 Schema Change、Compaction、查询和磁盘空间；
- 轻量 Schema Change 只适用于官方文档列明的操作；
- 生产变更应记录 DDL、执行人、开始/结束时间和回滚方案。

---

## 5. SQL 使用

### 5.1 常用数据库和对象命令

```sql
SHOW DATABASES;
USE demo;
SHOW TABLES;
SHOW CREATE TABLE user_events;
DESC user_events;
SHOW TABLE STATUS FROM demo;
```

### 5.2 查询基础

```sql
SELECT event_type, COUNT(*) AS cnt
FROM demo.user_events
WHERE event_time >= '2025-01-01'
GROUP BY event_type
ORDER BY cnt DESC
LIMIT 20;
```

Doris 支持聚合、Join、窗口函数、CTE、子查询、数组/JSON 函数及多种分析函数。具体语法、函数参数和版本差异以 [SQL Manual](https://doris.apache.org/docs/dev/sql-manual/) 为准。

### 5.3 插入数据

```sql
INSERT INTO demo.user_events (event_time, user_id, event_type, payload)
VALUES
('2025-01-01 10:00:00', 1001, 'login', '{"from":"app"}');

INSERT INTO demo.user_events
SELECT event_time, user_id, event_type, payload
FROM demo.staging_events;
```

不要在循环中逐行执行 `INSERT ... VALUES`。应合并为批量写入，或使用 Stream Load/Group Commit。

### 5.4 UPDATE 和 DELETE

主要用于支持相应能力的 Unique Key 表。生产执行前必须带明确的 `WHERE`，并先验证影响范围：

```sql
SELECT COUNT(*)
FROM demo.orders
WHERE order_id = 1001;

UPDATE demo.orders
SET status = 'paid'
WHERE order_id = 1001;

DELETE FROM demo.orders
WHERE order_id = 1001;
```

对大范围修改优先考虑重新装载、分区替换或适合的 CDC 方案，避免造成高昂的写放大。

### 5.5 事务

```sql
BEGIN;
INSERT INTO demo.table_a SELECT ...;
UPDATE demo.table_b SET ... WHERE ...;
COMMIT;
-- 失败时：ROLLBACK;
```

官方事务说明：

- 单个查询、DDL 和大多数单条写入是隐式事务；
- 显式事务支持的语句范围有限，不要把 DDL 或查询当作普通事务步骤；
- 默认隔离级别是 `READ COMMITTED`；
- 事务是 Session 级别，连接中断会回滚未提交事务；
- 多表事务通常要求目标表在同一个 Database；
- Label 和两阶段提交用于导入的幂等/一致性场景。

参考：[Transactions](https://doris.apache.org/docs/dev/data-operate/transaction/)。

### 5.6 MySQL 兼容性边界

Doris 兼容 MySQL 协议，但不是 MySQL OLTP 替代品：

- Doris 的表模型、分区、分桶和副本是 OLAP 特有设计；
- 不要假设传统主键、唯一约束、二级索引和行锁语义完全一致；
- DML、事务、数据类型和函数存在差异；
- 迁移前逐条验证 DDL、分页、时间函数、隐式类型转换和事务行为。

参考：[MySQL Compatibility](https://doris.apache.org/docs/dev/query-data/mysql-compatibility/)。

---

## 6. 数据导入

### 6.1 导入方式选择

| 方式 | 数据源/场景 | 特点 |
|---|---|---|
| `INSERT` | Doris 内部表、查询结果、小批量 | SQL 方便，适合批量 SQL 写入 |
| Stream Load | 应用或脚本推送 HTTP 数据 | 同步返回结果，适合文件/字节流 |
| Routine Load | Kafka 持续消费 | 自动调度、断点和持续导入 |
| Broker Load | HDFS、S3、对象存储 | 异步批量导入外部文件 |
| Flink/Spark Connector | 流处理或离线计算 | 集成上游计算框架 |
| Group Commit | 高频小批量写入 | 合并提交，减少小事务开销 |

参考：[Load Overview](https://doris.apache.org/docs/dev/data-operate/import/load-manual/)。

### 6.2 Stream Load

Stream Load 适合客户端通过 HTTP 上传 CSV、JSON、Parquet、ORC 等数据。典型 JSON Lines 示例：

```bash
curl --location-trusted -u user:password \
  -H 'format: json' \
  -H 'read_json_by_line: true' \
  -H 'label: user_events_20250101_0001' \
  -T events.json \
  http://fe-host:8030/api/demo/user_events/_stream_load
```

重点：

- 一个 Stream Load 请求对应一个导入事务；
- 使用稳定、唯一的 `label` 做重试幂等；
- 检查返回 JSON 中的 `Status`、`NumberTotalRows`、`NumberLoadedRows`、`NumberFilteredRows` 和错误信息；
- `max_filter_ratio`、严格模式、列映射、时间格式等参数要按数据质量要求设置；
- FE 可能将请求重定向到 BE，外部客户端必须能访问目标 BE；
- 大文件和高并发要控制并发度，避免 BE 内存、HTTP 线程和 Tablet 资源耗尽。

查询导入状态：

```sql
SHOW LOAD FROM demo ORDER BY CreateTime DESC LIMIT 20;
```

参考：[Stream Load](https://doris.apache.org/docs/dev/key-features/stream-load/)。

### 6.3 Routine Load（Kafka）

Routine Load 适合持续从 Kafka 消费 CSV/JSON 数据：

```sql
CREATE ROUTINE LOAD demo.kafka_user_events ON user_events
COLUMNS(event_time, user_id, event_type, payload)
PROPERTIES
(
    "format" = "json",
    "max_batch_interval" = "10",
    "desired_concurrent_number" = "3"
)
FROM KAFKA
(
    "kafka_broker_list" = "kafka-1:9092,kafka-2:9092",
    "kafka_topic" = "user_events",
    "property.group.id" = "doris-user-events",
    "property.kafka_default_offsets" = "OFFSET_BEGINNING"
);

SHOW ROUTINE LOAD FOR demo;
PAUSE ROUTINE LOAD FOR demo.kafka_user_events;
RESUME ROUTINE LOAD FOR demo.kafka_user_events;
STOP ROUTINE LOAD FOR demo.kafka_user_events;
```

生产要点：

- Kafka 分区数、并发度、目标表分区/Tablet 数需要匹配；
- 监控任务状态、错误行、Lag、消费位点和暂停原因；
- 使用合适的 Group ID 和 Label/任务命名；
- CDC 更新场景要使用与目标 Unique Key 表匹配的更新/删除语义；
- 多表路由、列映射和 JSON 格式必须按当前版本语法配置。

参考：[Routine Load](https://doris.apache.org/docs/dev/data-operate/import/import-way/routine-load-manual/)。

### 6.4 Broker Load

Broker Load 由 Doris 异步从 HDFS、S3 或其他对象存储读取文件，适合离线批量导入。示意：

```sql
LOAD LABEL demo.events_load_20250101
(
    DATA INFILE('s3://bucket/path/events/*.parquet')
    INTO TABLE user_events
    FORMAT AS 'parquet'
)
WITH S3
(
    "s3.endpoint" = "https://s3.example.com",
    "s3.region" = "region",
    "s3.access_key" = "<access-key>",
    "s3.secret_key" = "<secret-key>"
)
PROPERTIES
(
    "timeout" = "3600"
);
```

> 示例中的密钥只能使用占位符；生产应使用安全的 Secret/凭据管理方式，禁止写入 Git、脚本仓库或日志。

查询任务：

```sql
SHOW LOAD FROM demo WHERE LABEL = 'events_load_20250101';
```

大文件、压缩格式、文件数量和文件切分会直接影响并行度；不要把许多极小文件或单个不可切分的大压缩文件直接交给导入任务。

### 6.5 导入性能基线

- 尽量批量导入，减少小事务；
- 控制单次导入涉及的分区和 Tablet 数；
- 设计合理的 Tablet 大小，避免过多小 Tablet；
- 导入并发要以 BE CPU、内存、磁盘和网络为边界；
- 观察 Compaction Score、MemTable、Rowset 数、磁盘利用率；
- Unique/Aggregate 表比 Duplicate 表需要更多合并/更新处理；
- 出错数据要区分“允许过滤”和“必须失败”，不要默认吞掉脏数据；
- 导入系统应保存 Label、源文件、位点、行数和结果状态，支持审计与重试。

---

## 7. 数据导出、更新与事务

### 7.1 查询结果导出

可使用 `SELECT ... INTO OUTFILE` 将查询结果导出到文件系统或对象存储，具体格式、认证和并行参数以版本文档为准。大结果集导出前要评估查询资源、文件切分和下游幂等。

官方 SQL 入口：[Data Export](https://doris.apache.org/docs/dev/data-operate/export/)。

### 7.2 分区生命周期

建议把保留策略设计成自动化流程：

1. 创建未来分区；
2. 导入当前分区；
3. 校验行数和业务日期；
4. 到期删除历史分区；
5. 记录删除操作和备份状态。

对时间表，删除分区通常比按条件删除大量行更简单、成本更低。

### 7.3 Unique Key 更新语义

- 相同 Key 的新行通常覆盖旧行；
- Sequence 列可以用于处理乱序到达的数据；
- Merge-on-Write 能改善读取时的合并成本，但写入和索引成本更高；
- 部分列更新必须满足当前版本的 Session 变量、Key 列、默认值和非空约束；
- CDC 方案必须明确 INSERT、UPDATE、DELETE、乱序和重复事件的语义。

### 7.4 Group Commit

高频小写入可以使用 Group Commit 合并多个客户端提交，减少单行写入的事务和 Compaction 开销。启用前确认：

- 目标表和 Doris 版本支持；
- 延迟窗口是否满足业务；
- 失败重试与可见性语义；
- Group Commit 和显式事务的优先级；
- 批大小、内存和写入吞吐。

---

## 8. 查询、索引与性能优化

### 8.1 标准调优顺序

官方建议按以下顺序排查：

```text
定位慢 SQL → 检查表模型/分区/分桶 → EXPLAIN → Profile → 调整运行时参数 → 回归验证
```

不要先盲目增加并发、关闭优化器或堆叠 Hint。

### 8.2 定位慢 SQL

可从以下来源入手：

- Doris Manager；
- FE `fe.audit.log`；
- `audit_log` 系统表（若已启用）；
- 客户端慢查询日志；
- Prometheus 查询和资源指标。

保留：SQL 文本、用户、数据库、开始时间、耗时、扫描行数、返回行数、峰值内存、Query ID 和执行计划。

### 8.3 EXPLAIN

```sql
EXPLAIN
SELECT event_type, COUNT(*)
FROM demo.user_events
WHERE event_time >= '2025-01-01'
GROUP BY event_type;
```

重点观察：

- 是否命中分区裁剪；
- 扫描的 Tablet/行数/列数；
- Join 顺序和 Join 类型；
- Broadcast、Shuffle、Bucket Shuffle 是否合理；
- 是否使用索引、物化视图或预聚合；
- 估算行数是否明显失真。

### 8.4 Profile

执行查询后通过客户端或 Doris Manager 获取 Profile。重点看：

- 各算子总耗时和 CPU 时间；
- `max` 与 `avg` 差距，识别数据倾斜；
- Scan、Join、Aggregate、Sort 的输入输出行数；
- Runtime Filter 是否生成、下推和生效；
- Exchange/Shuffle 的网络和等待时间；
- 内存峰值、Spill、线程并发和磁盘 I/O。

### 8.5 分区、分桶和数据倾斜

典型现象：

- 某个 BE 或某个算子远慢于其他节点；
- Profile 中 `max` 明显大于 `avg`；
- 单个 Tablet 数据量远大于其他 Tablet；
- Join Shuffle 后少数分片成为瓶颈。

检查示例：

```sql
SHOW TABLETS FROM demo.user_events;

SELECT user_id, COUNT(*) AS cnt
FROM demo.user_events
GROUP BY user_id
ORDER BY cnt DESC
LIMIT 20;
```

修复方向：重新选择分桶列、调整分桶组合、改用 Random Bucketing（适用时）、使用合适的 Join 策略或重建表。不要用无限增加桶数掩盖倾斜。

### 8.6 统计信息与 CBO

CBO 依赖行数、NDV、NULL 比例、最小/最大值等统计信息：

```sql
ANALYZE TABLE demo.user_events;
SHOW ANALYZE;
```

数据量发生较大变化、导入新分区或执行计划明显失真时，应检查和刷新统计信息。大表统计任务安排在低峰期，并观察其资源消耗。

参考：[Statistics](https://doris.apache.org/docs/dev/query-acceleration/optimization-technology-principle/statistics/)。

### 8.7 索引

按场景选择，不要无条件增加：

- **前缀索引**：由 Key/排序设计决定；
- **Bloom Filter**：适合特定高基数等值过滤；
- **倒排索引**：适合全文、字符串或复杂过滤，需评估写入和存储成本；
- **NGram 等索引**：按当前版本和字段类型支持情况使用；
- **Bitmap/HLL 等分析类型**：用于特定聚合语义，不是通用索引替代品。

### 8.8 物化视图

- **同步物化视图**：实时维护，适合强实时、单表场景，但会增加写入成本。
- **异步物化视图**：后台刷新，可支持更复杂的单表/多表场景，通常是最终一致。
- 适合稳定、重复、高成本的聚合和 Join 查询。
- 创建后必须监控刷新状态、延迟、失败和存储占用。

示意：

```sql
CREATE MATERIALIZED VIEW mv_event_daily
BUILD IMMEDIATE
REFRESH AUTO
AS
SELECT DATE(event_time) AS dt, event_type, COUNT(*) AS cnt
FROM demo.user_events
GROUP BY DATE(event_time), event_type;
```

实际属性、刷新模式和透明改写能力以 [Materialized View Overview](https://doris.apache.org/docs/dev/query-acceleration/materialized-view/overview/) 为准。

### 8.9 查询优化原则

- 只选择需要的列，避免 `SELECT *`；
- 尽量提供分区列过滤；
- 尽量在 Join 前过滤和聚合；
- 避免对过滤列套不可下推的函数；
- 控制 Join 的中间结果和广播表大小；
- 对热点报表考虑物化视图或预聚合；
- 通过统计信息让优化器得到可靠基数；
- 以 Profile 证明优化有效，不以单次偶然耗时判断。

### 8.10 性能调优与资源配置手册

#### 8.10.1 先建立基线

一次有效的调优至少记录：Doris 版本、表模型、数据量/分区数/Tablet 数、FE/BE 规格、并发数、SQL、Query ID、P50/P95/P99 延迟、扫描行数、返回行数、CPU、内存、磁盘 I/O、网络、Profile 和执行计划。没有基线时，不要用单次查询耗时宣称优化成功。

建议同时使用 Doris 工具和操作系统工具：

```bash
# 节点资源与磁盘
lscpu
free -h
df -hT
lsblk

# 运行时瓶颈（在授权的生产节点执行）
top
iostat -x 1
vmstat 1
sar -n DEV 1
```

`top/iostat/vmstat/sar` 只能辅助定位 CPU、内存、磁盘和网络瓶颈；最终仍需结合 `EXPLAIN`、Profile、FE/BE 指标和日志。

#### 8.10.2 瓶颈到措施的映射

| 现象 | 优先措施 | 不要先做 |
|---|---|---|
| 分区扫描过多 | 补充分区谓词、调整分区周期、治理分区数量 | 直接加 BE |
| Tablet 数据极不均匀 | 检查分桶列基数和倾斜，必要时重建表 | 盲目增加桶数 |
| CPU 饱和 | 减少并发/中间结果、优化 Join/聚合、检查并行度 | 全局无限提高并行度 |
| CPU 不满但单条复杂 SQL 慢 | 检查并行度、Shuffle、Join 顺序和 Runtime Filter | 只增加机器 |
| 磁盘 I/O 饱和 | 使用 SSD、多盘分布、减少小 Rowset、治理 Compaction | 只调大内存 |
| 网络/Shuffle 饱和 | 减少数据交换、优化 Join、提高网络带宽 | 只调大查询超时 |
| BE 内存高或 OOM | 降低导入/查询并发、限制中间结果、检查活跃 Tablet 数 | 直接关闭内存限制 |
| 导入慢且版本数增长 | 批量写入、Group Commit、减少导入涉及的分区 | 提高 Stream Load 并发 |
| 估算行数明显错误 | `ANALYZE`/自动统计信息、检查数据分布 | 先堆叠 Hint |

#### 8.10.3 并行度调优

`parallel_pipeline_task_num` 控制单个 Fragment 在 BE 内的执行任务数，默认值 `0` 通常表示使用 BE CPU 核数的一半。默认值已经兼顾单条查询和并发吞吐，通常不需要全局修改。

- CPU 密集型、并发较低且 CPU 未饱和：可以按小步长提高并行度并对比 Profile；
- 并发查询已经使 CPU 饱和：优先降低单查询并行度，避免线程和调度开销叠加；
- 点查询或主要瓶颈在 Scan/I/O：提高查询线程数未必有效；
- 压测场景：并发本身已经提供并行度，通常不要叠加很大的单查询并行度；
- 优先使用单 SQL 或 Session 范围调整，确认收益后才考虑全局参数。

示意（先在测试会话验证，具体变量支持以目标版本为准）：

```sql
SET parallel_pipeline_task_num = 1;
-- 执行目标 SQL 并比较 Profile 后恢复/调整
```

在 16 核 BE 上把并行度直接设为 48 通常只会增加调度开销。推荐从默认值开始，逐步测试，而不是套用固定数字。

#### 8.10.4 Join、Runtime Filter 与数据倾斜

检查 Profile 和 `EXPLAIN`：

- Join 前是否已过滤和聚合；
- 小表是否适合 Broadcast，大表是否发生不必要的 Broadcast；
- Join Key 是否存在 NULL、热点值和严重倾斜；
- Runtime Filter 是否生成、下推到 Scan 并实际减少输入；
- Exchange/Shuffle 是否占据主要耗时；
- 算子 `max` 与 `avg` 是否差距很大。

处理顺序通常是：修正统计信息和表分布 → 改写 SQL/减少中间结果 → 选择合适 Join 策略 → 最后再使用针对性 Hint。

#### 8.10.5 导入吞吐与 Compaction 联动

官方导入最佳实践给出的经验边界：

- 单个 Tablet 压缩后建议约 **1–10 GB**；
- 单次大批量导入建议拆分，单批不超过 **100 GB**；
- Stream Load 单个 BE 并发建议不超过 **128**，并且不要超过 **512** 的硬限制；
- 单次导入不要同时覆盖过多分区，否则会同时激活大量 Tablet/MemTable，导致提前 Flush、许多小 Segment 和内存压力；
- 高频小批量写入优先在客户端聚合，或者对适用场景使用 Group Commit；
- Random Bucketing 表在适用时可评估 `load_to_single_tablet=true`，减少分发和小文件开销。

Group Commit 适合客户端无法聚合、但需要高并发小批量写入的场景：

```bash
curl --location-trusted -u user:password \\
  -H 'group_commit:async_mode' \\
  -T events.json \\
  http://fe-host:8030/api/demo/user_events/_stream_load
```

- `sync_mode`：请求等待合并事务提交并可见；
- `async_mode`：先写 WAL 后返回，数据稍后提交并可见；
- 已经是较大批次时，Group Commit 的收益通常有限；
- 需要显式事务、稳定自定义 Label 或严格两阶段提交时，确认是否会绕过 Group Commit。

Compaction 持续追不上时，先减少小批次和活跃 Tablet，检查磁盘 I/O、CPU、内存及表设计；不要把关闭自动 Compaction 当作常规优化。版本数持续增长可能最终触发 `-235`，此时优先降低写入频率、增大批次并让 Compaction 追上。

#### 8.10.6 硬件选型与性能的关系

- **CPU**：查询扫描、Join、聚合、压缩和 Compaction 都会竞争 CPU；AVX2 能启用向量化优化；
- **内存**：影响 Hash Join、聚合、排序、缓存、MemTable 和 Compaction；BE 推荐按“CPU 核数 × 8 GB”作为起步参考，但仍需按并发压测；
- **SSD/磁盘**：影响 Scan、导入 Flush、Compaction、临时 Spill 和副本修复；高频更新/高并发场景优先 SSD；
- **网络**：MPP Exchange、跨 BE 导入、副本复制和存算分离依赖网络；10 GbE 只是推荐起点，需按实际 Shuffle 吞吐验证；
- **FE**：FE 主要消耗在 SQL 解析/规划、元数据、事务和导入协调；高并发小事务会先压 FE，即使 BE 仍有余量；
- **故障域**：把所有副本放在同一机架或可用区不能达到预期高可用，硬件拓扑必须与副本标签配合。

#### 8.10.7 调优验收

每次调优只改变少量变量，并使用同一数据快照、相同并发和相同 SQL 集合回归。至少验收：

- 目标 SQL 的 P95/P99、CPU 时间和扫描量；
- 资源峰值及对其他业务的影响；
- 导入吞吐、可见性延迟、过滤率和 Label 重试；
- Compaction Score、Rowset/版本数和磁盘增长；
- 失败重试、节点故障和扩缩容后的表现；
- 结果正确性，尤其是 Unique/Aggregate 表和物化视图。

参考：[Performance Tuning Overview](https://doris.apache.org/docs/dev/query-acceleration/performance-tuning-overview/tuning-overview/)、[Performance Tuning Process](https://doris.apache.org/docs/dev/query-acceleration/performance-tuning-overview/tuning-process/)、[Parallelism Tuning](https://doris.apache.org/docs/dev/query-acceleration/tuning/parallelism-tuning/)、[Load Best Practices](https://doris.apache.org/docs/dev/data-operate/import/load-best-practices/)、[Data Compaction](https://doris.apache.org/docs/dev/key-features/data-compaction/)。

---

## 9. 外部数据源与湖仓分析

### 9.1 External Catalog

External Catalog 可连接 Hive、Iceberg、Paimon、Hudi、JDBC、Elasticsearch 等外部数据源，支持联邦查询，减少数据搬运。

典型流程：

1. 准备元数据服务、对象存储和认证信息；
2. 创建 External Catalog；
3. `SWITCH` 或使用三段式名称访问；
4. 验证 schema、分区、权限和统计信息；
5. 对高频查询评估导入 Doris 内表或创建物化视图。

示意：

```sql
CREATE CATALOG hive_catalog PROPERTIES (
    "type" = "hms",
    "hive.metastore.uris" = "thrift://hms-host:9083"
);

SHOW CATALOGS;
SWITCH hive_catalog;
SHOW DATABASES;
```

不同 Catalog 的连接属性、认证方式、谓词下推和事务语义差异较大，必须使用对应官方页面的完整配置。

### 9.2 外表与内表取舍

| 场景 | 建议 |
|---|---|
| 数据量大、访问不稳定、低频查询 | 直接查外部表 |
| 高频报表、低延迟要求 | 导入 Doris 内表或构建物化视图 |
| 需要 Doris 数据模型、更新和索引 | 内表 |
| 跨引擎共享数据 | 湖表 + External Catalog |
| 对象存储文件很多且很小 | 先治理文件布局，再接入查询 |

### 9.3 外部查询注意事项

- 外部存储网络、权限和凭据是常见瓶颈；
- 统计信息可能不完整，导致 CBO 估算不准；
- 分区字段、文件格式和列裁剪决定扫描量；
- 外部源的 schema 变更可能破坏 Doris 查询；
- 不要把外部 Catalog 当成自动备份；备份策略需覆盖元数据和对象存储数据。

---

## 10. 应用开发与生态集成

### 10.1 驱动与协议

- MySQL JDBC/ODBC 驱动通常可用于连接 Doris；
- 应用通过 FE Query Port 执行 SQL；
- 大批量导入优先使用 Stream Load 或官方 Connector，而不是普通 JDBC 单行 INSERT；
- 连接池要设置连接超时、读取超时、最大连接数和重试策略；
- 重试写入必须使用幂等 Label，避免重复数据。

### 10.2 Flink/Spark

适用方式：

- Flink：持续流式处理、CDC、Kafka 到 Doris；
- Spark：离线加工、批量写入和大规模 ETL；
- Connector 版本要与 Doris/Flink/Spark 兼容；
- 明确 checkpoint、失败重启、两阶段提交、Exactly-Once/At-Least-Once 和 Label 语义；
- 生产环境监控上游积压、checkpoint、Connector 错误和 Doris 导入任务。

官方入口：[Ecosystem](https://doris.apache.org/docs/ecosystem/)。

### 10.3 HTTP Stream Load 客户端设计

客户端至少应实现：

1. 生成业务唯一 Label；
2. 设置连接、读取和整体超时；
3. 处理 FE/BE 重定向；
4. 解析返回 JSON，不只判断 HTTP 状态码；
5. 区分可重试错误和数据格式错误；
6. 重试时复用同一 Label；
7. 持久化批次、行数、Label、Query/Txn ID 和最终状态；
8. 对不完整或重复数据提供补偿流程。

### 10.4 UDF 和扩展

自定义函数、插件和运行时扩展会增加发布、兼容性和安全风险。只有内置函数无法满足且收益明确时才考虑；部署前验证序列化、类路径、升级兼容性和资源隔离。

---

## 11. 集群运维

### 11.1 日常巡检

每日或每班次检查：

```sql
SHOW FRONTENDS;
SHOW BACKENDS;
SHOW PROC '/cluster_health/tablet_health';
SHOW LOAD FROM demo ORDER BY CreateTime DESC LIMIT 20;
SHOW ROUTINE LOAD FOR demo;
SHOW ALTER TABLE COLUMN FROM demo;
SHOW ALTER TABLE ROLLUP FROM demo;
```

同时检查：

- FE Leader、Follower/Observer 是否正常；
- BE Alive、磁盘容量、Tablet 数和是否被 Decommission；
- Tablet 副本健康、修复队列和版本积压；
- 导入失败、过滤行、Routine Load 暂停和 Kafka Lag；
- Compaction Score、Rowset 数、内存、CPU、磁盘 I/O；
- 慢查询、Query Error、连接数和网络错误；
- FE/BE 日志滚动和磁盘空间。

### 11.2 添加/下线 BE

扩容前：

- 确认新节点版本、配置、网络、磁盘和时钟；
- 确认标签、磁盘路径、资源和副本策略；
- 估算迁移流量和对查询/导入的影响。

下线节点不要直接杀进程或删除数据目录，应先执行 Decommission，让 Tablet 副本迁移完成，再确认节点可安全移除。具体 `ALTER SYSTEM` 语法以目标版本文档为准。

### 11.3 FE 扩缩容

- 修改 FE 前先备份元数据并确认 Leader/Follower 健康；
- FE 节点之间需要稳定网络和一致的端口配置；
- 扩容后检查角色、Journal 回放和元数据同步；
- 不要同时重启过多 Follower；
- Observer 可用于分担接入，但不能替代元数据高可用设计。

### 11.4 磁盘管理

- 监控总容量、可用容量、最高使用率和 Trash；
- 给数据目录、日志目录和临时目录预留空间；
- 不要手工删除 BE 数据文件或 Tablet 目录；
- 磁盘满时优先停止非必要导入、清理有明确保留策略的历史分区/备份，再按官方流程处理；
- 日志轮转、Core、Profile 和临时文件也可能耗尽磁盘。

### 11.5 Compaction

Compaction 合并多个 Rowset、清理旧版本并建立更高效的数据文件。以下现象通常与 Compaction 压力有关：

- 导入越来越慢；
- 查询扫描大量 Rowset；
- Tablet 的 Compaction Score 持续升高；
- BE CPU、磁盘 I/O 或内存长期偏高；
- 高频小批量写入导致写放大。

处理顺序：减少小批量写入、控制导入并发、检查 Tablet/分区设计、确认磁盘和资源，再按官方参数调节 Compaction；不要直接长期关闭自动 Compaction。

### 11.6 滚动升级

升级前：

- 阅读目标版本 Release Notes、升级限制和兼容性说明；
- 备份元数据和关键数据；
- 在测试集群回归 DDL、DML、导入、查询、Connector 和 Catalog；
- 确认 FE/BE/Operator/Connector 版本组合；
- 准备回滚和停机窗口。

升级中：

- 先按官方顺序升级 FE 或 BE；
- 控制并发重启数量；
- 每一步检查节点 Alive、Journal、Tablet、副本和查询；
- 不要跨越官方支持的版本升级路径。

升级后：

- 验证查询结果、导入、Routine Load、物化视图和外部 Catalog；
- 检查日志、错误率、资源和性能基线；
- 保留升级前后配置和审计记录。

---

## 12. 监控、审计与安全

### 12.1 监控体系

推荐分层：

1. **节点层**：CPU、内存、磁盘、网络、文件句柄、时钟；
2. **FE 层**：Leader、Journal、连接数、查询数、慢查询、元数据任务；
3. **BE 层**：Alive、Tablet、Compaction、内存、扫描、导入、磁盘；
4. **业务层**：导入延迟、Kafka Lag、数据新鲜度、行数、空值和异常值；
5. **查询层**：P95/P99 延迟、错误率、扫描量、峰值内存、倾斜；
6. **存储层**：对象存储可用性、容量、请求错误和外部表延迟。

Doris 提供 Prometheus 兼容指标，可接入 Prometheus/Grafana。指标名称和标签以当前版本 `/metrics` 和官方监控文档为准。

### 12.2 必备告警

- FE 无 Leader 或多数 FE 不可用；
- BE Alive=false、节点失联或频繁重启；
- Tablet 副本不足、修复超时或版本异常；
- 磁盘使用率达到阈值；
- Compaction Score 持续升高；
- BE OOM、内存高水位、线程池/HTTP 线程耗尽；
- Stream Load、Broker Load、Routine Load 失败；
- Kafka Lag 超过业务 SLA；
- 慢查询和查询错误率突增；
- 统计信息长期过期；
- 备份任务失败或备份延迟超过 RPO。

### 12.3 用户和权限

示意：

```sql
CREATE USER 'analyst' IDENTIFIED BY 'change-me';
GRANT SELECT_PRIV ON demo.* TO 'analyst';
SHOW GRANTS FOR 'analyst';
```

安全原则：

- 禁止业务应用使用 root；
- 按 Catalog/Database/Table 和操作最小授权；
- 写入、DDL、管理权限分离；
- 凭据放入 Secret/密钥管理系统；
- 周期性回收离职账号和临时权限；
- 对跨网络连接启用 TLS/SSL（以目标版本能力为准）；
- LDAP/Ranger 等企业认证授权方案按官方文档配置并测试故障回退。

### 12.4 审计与日志

- 开启并集中收集 FE audit log、慢查询和管理操作日志；
- 记录用户、来源地址、SQL、对象、耗时、结果和 Query ID；
- 日志中不得输出密码、Access Key、Secret Key 或 Token；
- 为日志设置轮转、保留周期、访问控制和脱敏；
- 将管理操作与变更单、工单或发布系统关联。

---

## 13. 备份、恢复与灾备

### 13.1 备份目标

备份不应只保存 FE 配置。至少考虑：

- 数据库/表数据；
- 表结构、分区、物化视图、索引和属性；
- 用户、权限和安全配置；
- FE 元数据；
- 外部 Catalog 配置和对象存储元数据；
- Connector、ETL 和导入任务配置；
- 业务重放所需的 Kafka 位点/源文件/CDC 日志。

### 13.2 快照备份与恢复

Doris 支持将 Snapshot 备份到 Repository，再从 Repository 恢复。概念流程：

```sql
-- 创建 Repository（认证属性依存储类型和版本）
CREATE REPOSITORY repo_name
WITH S3
ON LOCATION 's3://bucket/doris-backup/'
PROPERTIES (...);

BACKUP SNAPSHOT demo.snapshot_20250101
TO repo_name
PROPERTIES ("type" = "full");

SHOW BACKUP FROM demo;

RESTORE SNAPSHOT demo.snapshot_20250101
FROM repo_name
PROPERTIES (...);

SHOW RESTORE FROM demo;
```

真实环境必须按 [Backup and Restore](https://doris.apache.org/docs/dev/admin-manual/data-backup-and-recovery/backup-and-restore/) 的存储类型、认证、版本和恢复限制配置，不能直接复制占位属性。

### 13.3 RPO/RTO 验证

备份策略必须定期做恢复演练：

- 备份是否能读取；
- 能否恢复到隔离集群；
- 表结构、行数、校验和是否正确；
- 权限和外部依赖是否可重建；
- 恢复耗时是否满足 RTO；
- 源端持续写入期间如何补数据；
- 恢复失败时如何回滚和升级。

“备份任务成功”不等于“灾备可用”，恢复演练才是验证证据。

### 13.4 跨集群复制

需要低延迟异地同步时，可评估官方提供的 CCR/复制能力或上游 CDC 方案。选型时关注：

- 支持的表模型和 DDL；
- 延迟、冲突和故障切换；
- 网络、对象存储和权限；
- 版本兼容性；
- 全量初始化和增量同步；
- 目标端读写策略。

---

## 14. 故障排查

### 14.1 统一排查流程

```text
确认影响范围 → 保存 Query/Txn/Label/Job ID → 看节点和日志
→ 看导入/副本/Compaction 状态 → EXPLAIN/Profile
→ 判断数据、资源、网络还是版本问题 → 小范围修复 → 回归验证
```

不要在没有保留现场信息前重启所有节点或删除数据目录。

### 14.2 常见问题速查

| 现象 | 优先检查 | 常见根因/方向 |
|---|---|---|
| 无法连接 | FE Query Port、VIP、DNS、防火墙、账号 | 端口不通、服务未启动、权限或负载均衡错误 |
| Stream Load 301 后失败 | FE 返回的 BE 地址 | BE 地址对客户端不可达、K8s Service 暴露错误 |
| 导入失败 | Load/Routine Load 详情、BE 日志 | schema 不匹配、格式错误、权限、超时、内存 |
| 导入成功但数据少 | 返回 JSON、过滤行、严格模式 | 脏数据被过滤、列映射/时间格式不正确 |
| Routine Load PAUSED | 任务错误、Kafka、位点、并发 | Broker 不通、消息格式、权限、目标表限制 |
| 查询慢 | EXPLAIN、Profile、统计信息 | 未裁剪分区、数据倾斜、Join/Shuffle、扫描过大 |
| 查询 OOM | Profile、内存指标、Join/Sort/Aggregate | 中间结果过大、并发过高、广播表过大 |
| BE OOM | 内存日志、导入并发、Compaction | 并发分区/Tablet 过多、导入批次过大、查询尖峰 |
| Compaction 堵塞 | Score、Rowset、磁盘 I/O、写入批次 | 小批量写入、Tablet 过多、资源不足 |
| 副本不健康 | `SHOW BACKENDS`、Tablet Health | BE 失联、磁盘满、网络、版本或数据损坏 |
| FE 选主异常 | FE 角色、端口、Journal、网络 | 多数节点不可达、时钟/网络、元数据盘问题 |
| 外部表慢/失败 | Catalog 属性、对象存储、权限、文件布局 | 凭据失效、文件过多、无分区裁剪、网络慢 |

### 14.3 证据采集清单

故障单至少记录：

- Doris 版本、部署方式和变更记录；
- FE/BE/MetaService/Operator 状态；
- 发生时间和时区；
- Query ID、Txn ID、Label、Load Job、Routine Load Job；
- SQL 脱敏文本、执行计划和 Profile；
- 相关日志时间段；
- CPU、内存、磁盘、网络和 Compaction 指标；
- 是否可以稳定复现；
- 最近的 DDL、扩缩容、升级、配置或数据源变更。

### 14.4 不要做的事

- 不要直接删除 Tablet 或 BE 数据目录；
- 不要不确认副本状态就强制删除节点；
- 不要为“解决慢查询”全局关闭优化器；
- 不要把所有错误数据都设置为可过滤；
- 不要使用不稳定 Label 重试写入；
- 不要在生产直接使用 `root` 无密码；
- 不要为了短期速度无限增加并发、桶数或内存；
- 不要跳过备份和回滚方案执行升级。

---

## 15. 生产检查清单

### 15.1 上线前

- [ ] 版本、架构和规模已经评审；
- [ ] CPU 支持 AVX2，FE/BE 内存、磁盘、网络和容量按压测规划；
- [ ] FE 至少 3 个 Follower、BE 副本数与故障域规划合理；
- [ ] Swap/THP、文件句柄、VMA、时钟同步和网络参数已检查；
- [ ] FE/BE/存储目录已持久化；
- [ ] FE/BE 副本和故障域规划完成；
- [ ] 网络端口、DNS、VIP、TLS 和防火墙已验证；
- [ ] 表模型、Key、分区、分桶经过数据分布评估；
- [ ] 已定义数据保留和分区生命周期；
- [ ] 已定义导入 Label、重试、过滤和补数策略；
- [ ] 已完成慢查询、Profile 和数据倾斜基线；
- [ ] 已完成 CPU、内存、磁盘 I/O、网络和 Compaction 基线压测；
- [ ] 已配置用户、权限和凭据管理；
- [ ] 已接入监控、日志、审计和告警；
- [ ] 已完成备份、恢复和升级演练；
- [ ] 已验证 Flink/Spark/Kafka/BI/外部 Catalog 兼容性。

### 15.2 日常运维

- [ ] FE Leader/Follower 正常；
- [ ] 所有 BE Alive；
- [ ] 无持续增长的副本修复、Compaction 或导入失败；
- [ ] 磁盘和 Trash 在阈值内；
- [ ] Routine Load 无异常暂停，Kafka Lag 正常；
- [ ] 慢查询和错误率无异常变化；
- [ ] 统计信息保持新鲜；
- [ ] 备份任务按计划成功；
- [ ] 变更和权限审计记录完整。

### 15.3 发布/升级

- [ ] 已阅读目标版本 Release Notes；
- [ ] 已在测试环境回归；
- [ ] 已备份并验证可恢复；
- [ ] 已准备升级、回滚、联系人和维护窗口；
- [ ] 已确认 Connector、Operator 和驱动兼容；
- [ ] 已安排滚动步骤和每步验收；
- [ ] 升级后已验证导入、查询、权限、监控和备份。

---

## 16. 官方文档索引

### 基础与部署

- [Apache Doris 官方文档](https://doris.apache.org/docs/)
- [Apache Doris 是什么](https://doris.apache.org/docs/dev/getting-started/what-is-apache-doris/)
- [快速开始](https://doris.apache.org/docs/4.x/getting-started/quick-start/)
- [安装与部署](https://doris.apache.org/docs/dev/install/intro/)
- [集群规划](https://doris.apache.org/docs/dev/install/preparation/cluster-planning/)
- [硬件与软件环境检查](https://doris.apache.org/docs/dev/install/preparation/env-checking/)
- [操作系统检查](https://doris.apache.org/docs/dev/install/preparation/os-checking/)
- [Kubernetes 部署](https://doris.apache.org/docs/dev/install/deploy-on-kubernetes/intro/)
- [系统架构](https://doris.apache.org/docs/4.x/features-architecture/system-architecture/)

### 建模与 SQL

- [产品概念](https://doris.apache.org/docs/dev/features-architecture/product-concepts/)
- [表模型](https://doris.apache.org/docs/dev/table-design/data-model/intro/)
- [数据模型](https://doris.apache.org/docs/dev/key-features/data-model/)
- [分桶](https://doris.apache.org/docs/dev/table-design/data-partitioning/data-bucketing/)
- [数据类型](https://doris.apache.org/docs/dev/table-design/data-type/)
- [CREATE TABLE](https://doris.apache.org/docs/dev/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE/)
- [INSERT](https://doris.apache.org/docs/dev/sql-manual/sql-statements/data-modification/DML/INSERT/)
- [SQL Manual](https://doris.apache.org/docs/dev/sql-manual/)
- [MySQL 兼容性](https://doris.apache.org/docs/dev/query-data/mysql-compatibility/)

### 导入、事务与查询优化

- [导入总览](https://doris.apache.org/docs/dev/data-operate/import/load-manual/)
- [Stream Load](https://doris.apache.org/docs/dev/key-features/stream-load/)
- [Routine Load](https://doris.apache.org/docs/dev/data-operate/import/import-way/routine-load-manual/)
- [事务](https://doris.apache.org/docs/dev/data-operate/transaction/)
- [查询总览](https://doris.apache.org/docs/dev/query-data/querying-overview/)
- [性能调优总览](https://doris.apache.org/docs/dev/query-acceleration/performance-tuning-overview/tuning-overview/)
- [性能调优流程](https://doris.apache.org/docs/dev/query-acceleration/performance-tuning-overview/tuning-process/)
- [并行度调优](https://doris.apache.org/docs/dev/query-acceleration/tuning/parallelism-tuning/)
- [导入最佳实践](https://doris.apache.org/docs/dev/data-operate/import/load-best-practices/)
- [Compaction](https://doris.apache.org/docs/dev/key-features/data-compaction/)
- [统计信息](https://doris.apache.org/docs/dev/query-acceleration/optimization-technology-principle/statistics/)
- [物化视图](https://doris.apache.org/docs/dev/query-acceleration/materialized-view/overview/)

### 生态、运维与安全

- [生态集成](https://doris.apache.org/docs/ecosystem/)
- [集群管理](https://doris.apache.org/docs/dev/admin-manual/cluster-management/intro/)
- [备份与恢复](https://doris.apache.org/docs/dev/admin-manual/data-backup-and-recovery/backup-and-restore/)
- [监控与指标](https://doris.apache.org/docs/dev/admin-manual/monitoring/)
- [安全](https://doris.apache.org/docs/dev/admin-manual/security/)
- [系统表](https://doris.apache.org/docs/dev/admin-manual/system-tables/)
- [磁盘容量管理](https://doris.apache.org/docs/dev/admin-manual/maint-monitor/disk-capacity/)

> 如果某个链接因官方文档目录调整而失效，请从 [Apache Doris 文档首页](https://doris.apache.org/docs/) 按关键词搜索同名主题；以目标版本页面为准。