Aeraki Mesh：超详细部署与使用教程

Aeraki（希腊语「微风」）是腾讯云开源、CNCF Sandbox 项目的服务网格增强方案：与 Istio 集成，专门解决服务网格中 Dubbo、Thrift、Kafka、Redis 等非 HTTP 七层流量的管理问题，让你在同一个 Service Mesh 里管理「任意」七层协议流量。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

主流服务网格（包括 Istio）主要聚焦 HTTP 协议，把其他协议当作普通 TCP 流量处理。但微服务里真实存在的协议远不止 HTTP：RPC（Thrift、Dubbo、私有 RPC）、消息（Kafka、RabbitMQ）、缓存（Redis、Memcached）、数据库（MySQL、PostgreSQL、MongoDB）。Aeraki Mesh 的目标就是以「无侵入、高可扩展」的方式，让服务网格能够管理任意七层流量。

注意：Aeraki 只负责非 HTTP 的七层流量，HTTP 流量仍交给 Istio 等现有方案，不重复造轮子。Aeraki 当前与 Istio 集成，未来可能支持其他服务网格项目。

1.2 核心功能

• 多协议支持：Dubbo、Thrift、Kafka、Redis（Envoy 原生过滤器）；MetaProtocol 上构建的 Dubbo、Thrift、bRPC（百度开源 RPC）、tRPC（腾讯内部 RPC）、qza（腾讯音乐私有协议）、videoPacket（腾讯媒体数据平台）以及任意私有协议。
• 流量管理：请求级负载均衡/地域负载均衡（一致性哈希/会话粘滞）、熔断、灵活路由匹配、动态路由更新（MetaRDS）、版本路由、流量拆分、本地限流、全局限流、消息改写、流量镜像。
• 可观测性：请求级 Metrics（延迟、次数、错误）、分布式链路追踪、访问日志。
• 安全：接口/方法级对等授权（Peer Authorization）；请求级授权在规划中。
• MetaProtocol 框架：新增协议只需实现 Codec 接口 + 少量配置，无需编写 Envoy Filter 与控制面。

1.3 技术架构

下图是微服务中常见的七层协议分布：Service 之间通过 RPC 调用，并访问 Cache / RDB / NoSQL，前端经 Message Broker 解耦——这些都是 Aeraki 要纳入网格管理的对象：

Aeraki Mesh 由两部分组成：

• Aeraki（控制面）：向运维人员提供友好的高层流量管理规则，把规则翻译成 Envoy Filter 配置，通过 Istio 的 EnvoyFilter API 推送到 Sidecar；同时作为数据面 MetaProtocol Proxy 的 RDS 服务器（与专注 HTTP 的 Envoy RDS 不同，Aeraki RDS 面向所有七层协议提供通用动态路由能力）。
• MetaProtocol Proxy（数据面）：提供七层协议通用能力——负载均衡、熔断、路由、限流、故障注入、鉴权；新协议只需实现 Codec 接口；内置应用级 Filter 链机制，可写自定义七层 Filter。

二、环境要求

Aeraki / MetaProtocol Proxy / Istio 版本兼容矩阵（官方文档）：

安装前务必先对照此表选择 Istio 版本，否则数据面 Sidecar 可能无法启动。

三、部署方式

3.1 方式一：官方脚本安装（生产推荐）

步骤 0：前置安装 Istio（详细）

按兼容矩阵选版本（Aeraki 1.4.x ↔ Istio 1.18.x）：

# 下载 Istio
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.18.7 sh -
cd istio-1.18.7
export PATH=$PWD/bin:$PATH

# 安装 demo profile（包含 istiod 与 ingress）
istioctl install --set profile=demo -y

# 给目标命名空间开启 Sidecar 自动注入
kubectl label namespace default istio-injection=enabled

生产环境建议用 default profile 并通过 IstioOperator 精细定制；具体以 Istio 官方文档为准。

步骤 1：按兼容矩阵安装对应版本 Istio

例如使用 Aeraki 1.4.x 时安装 Istio 1.18.x（以官方文档为准）：

# 下载并安装 Istio（示例版本，需与 Aeraki 兼容矩阵一致）
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.18.7 sh -
cd istio-1.18.7
export PATH=$PWD/bin:$PATH
istioctl install --set profile=demo -y

步骤 2：修改 Istio ConfigMap（开启 DNS 捕获与协议统计）

kubectl edit cm istio -n istio-system

在 mesh: 段中加入以下内容：

apiVersion: v1
data:
  mesh: |-
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_CAPTURE: "true"
      proxyStatsMatcher:
        inclusionPrefixes:
        - thrift
        - dubbo
        - kafka
        - meta_protocol
        inclusionRegexps:
        - .*dubbo.*
        - .*thrift.*
        - .*kafka.*
        - .*zookeeper.*
        - .*meta_protocol.*

步骤 3：安装 Aeraki

git clone https://github.com/aeraki-mesh/aeraki.git
cd aeraki
export AERAKI_TAG=1.4.1   # 与兼容矩阵、Istio 版本对应
make install

步骤 4（可选）：安装 aerakictl 调试工具

git clone https://github.com/aeraki-mesh/aerakictl.git ~/aerakictl
source ~/aerakictl/aerakictl.sh

3.2 方式二：快速体验 Demo（本地/演示）

官方提供 Quickstart 教程，演示如何把 Dubbo 等应用接入网格并配置流量管理：

# 按官方 Quickstart 页面步骤操作
# https://www.aeraki.net/docs/v1.x/quickstart/

Demo 页面会引导创建命名空间、注入 Sidecar、部署 Dubbo 示例应用，并演示路由、限流、熔断等规则。

3.3 方式三：源码编译

# 编译 Aeraki 二进制（Linux）
make build

# macOS
make build IMAGE_OS=darwin

# 构建 Docker 镜像（默认 latest tag）
make docker-build

# 指定 tag
make docker-build IMAGE_TAG=xxx

# 构建 e2e 镜像
make docker-build-e2e

3.4 验证部署成功

# 1) Aeraki 控制面 Pod 正常运行
kubectl get pod -n aeraki-system

# 2) 命名空间开启 Sidecar 注入后，示例应用 Pod 变为 2/2（业务容器 + Envoy）
kubectl get pod -n <你的命名空间>

# 3) 查看 Aeraki 下发的 EnvoyFilter
kubectl get envoyfilter -A

3.5 卸载与升级

# 卸载 Aeraki（在仓库目录）
make uninstall

# 升级：切换 tag 后重装
cd aeraki
git pull
export AERAKI_TAG=1.4.1
make install

升级前务必先核对新 Aeraki 版本对应的 Istio 兼容矩阵，必要时先升级 Istio。

四、使用方法

4.1 基础概念

接入 Aeraki 的应用需要通过 Aeraki 的 CRD（如 MetaRouter、MetaProtocol、ApplicationProtocol 等，具体以官方 Reference 文档为准）声明流量管理规则，而不是直接操作 EnvoyFilter。

4.2 配置流量路由（示例）

参考官方教程「How to configure traffic routing」（https://www.aeraki.net/docs/v1.x/tutorials/），典型流程：

# 查看 Dubbo 应用的服务入口
kubectl get svc -A | grep -E 'dubbo|thrift'

# 应用路由规则（CRD 示例，字段以官方 MetaProtocol Traffic Policy 文档为准）
kubectl apply -f routing-rule.yaml

# routing-rule.yaml 示意：把 user-center 服务的 v1 请求路由到 v2
apiVersion: v1
kind: Namespace
metadata:
  name: dubbo-demo
---
# 具体路由规则字段请参考官方文档：
# https://www.aeraki.net/docs/v1.x/reference/

路由匹配条件可以从七层报文中提取任意属性（方法名、版本、业务标签）作为匹配键；支持一致性哈希、版本路由、流量拆分。

Dubbo 服务接入流程（以官方 Quickstart 为例）：

1. 部署 Dubbo 示例应用（官方仓库提供示例 yaml）；
2. 在对应命名空间确认 Sidecar 注入成功（Pod 2/2）；
3. 用 kubectl get metarouters / 对应 CRD 查看 Aeraki 生成的路由规则；
4. 配置流量拆分：把 90% 流量打给 v1，10% 打给 v2（灰度）。

# 查看 Aeraki 管理的协议资源
kubectl get metaprotocol -A
kubectl get metarouter -A

# 查看 Dubbo 服务列表
kubectl get dr -A

具体 CRD 字段名（MetaRouter / DestinationRule 扩展）以官方 Reference 文档为准：https://www.aeraki.net/docs/v1.x/reference/

数据面调试命令：

# 进入业务 Pod 的 Sidecar 查看配置
kubectl exec -it <pod> -c istio-proxy -- curl localhost:15000/config_dump

# 查看集群/监听器/路由
kubectl exec -it <pod> -c istio-proxy -- curl localhost:15000/clusters
kubectl exec -it <pod> -c istio-proxy -- curl localhost:15000/listeners

4.3 常用能力配置入口（官方教程）

4.4 进阶：接入私有协议

闭源私有协议只需实现 MetaProtocol 的 Codec 接口（src/meta_protocol_proxy/codec/codec.h），配合少量配置即可纳入网格管理，无需编写 Envoy Filter 与控制面代码。

4.5 适用场景

• 存量 Dubbo/Thrift 微服务希望平滑迁入服务网格，不想改造成 HTTP；
• 消息队列（Kafka）、缓存（Redis）流量纳入统一治理与可观测体系；
• 有私有 RPC 协议、需要统一流量管理与监控的团队（腾讯音乐 qza、腾讯 tRPC 等均为生产案例）。

五、常见问题排查（FAQ）

Q1：Aeraki 安装后 Dubbo 应用 Sidecar 无法启动 - 原因：Istio 版本与 Aeraki 版本不匹配（最常见）。 - 解决：对照兼容矩阵（本文档第二章），Istio 1.18.x 配 Aeraki 1.4.x，依次降级/升级。

Q2：改了 Istio ConfigMap 但 Sidecar 不生效 - 原因：ConfigMap 修改后需重启已注入的 Envoy Sidecar。 - 解决：kubectl rollout restart deploy -n <ns>，或删除 Pod 重建。

Q3：EnvoyFilter 已下发但路由规则不生效 - 原因：CRD 规则未正确应用到对应命名空间，或服务未标记为 MetaProtocol/目标协议。 - 解决：kubectl get envoyfilter -A 检查；用 aerakictl 查看数据面配置；对照官方 Tutorial 逐字段核对。

Q4：Kafka / Redis 流量无法被 Aeraki 管理 - 原因：这两类协议走 Envoy 原生过滤器路线，需确认对应 Envoy 版本与配置；Redis 的 slot 路由特殊。 - 解决：参考官方 Redis 教程（部署模式透明、前缀路由、读写分离、流量镜像、故障注入）。

Q5：请求级指标缺失 - 原因：Istio ConfigMap 未配置 proxyStatsMatcher 包含 dubbo/thrift/kafka/meta_protocol。 - 解决：按本文档第三章步骤 2 补齐 inclusionPrefixes/inclusionRegexps 并重启 Sidecar。

Q6：如何在腾讯云 TCM 中使用 Aeraki？ - 解答：官方支持 TCM（腾讯云 Mesh）集成，需联系 TCM 销售或商务顾问开通。

Q7：Aeraki 与普通 Istio 的边界如何划分？ - 解答：HTTP/gRPC 流量完全交给 Istio；Aeraki 只接管你声明为 MetaProtocol 或原生过滤器协议（Dubbo/Thrift/Kafka/Redis）的流量，不要让同一服务同时被两套规则重复配置。

Q8：请求授权（Request Authorization）什么时候可用？ - 解答：官方路线图中「Peer Authorization on Interface/Method」已支持，请求级授权尚未完成，以官方 README 勾选清单为准。

Q9：Aeraki 控制面 Pod 起不来 - 原因：镜像拉取失败或资源不足。 - 解决：kubectl describe pod -n aeraki-system 看事件；确认 AERAKI_TAG 对应镜像已 push 到集群可达的 registry；必要时 make docker-build 后推送到内网镜像仓库。

六、部署注意事项与最佳实践

1. 版本对齐是第一原则：Aeraki ↔ MetaProtocol Proxy ↔ Istio 三者版本必须按矩阵对齐，升级 Aeraki 前先升级 Istio。
2. 只接管非 HTTP 流量：HTTP 继续交给 Istio，不要重复配置。
3. DNS 捕获必须开：ISTIO_META_DNS_CAPTURE=true 是 MetaProtocol 服务发现的基础。
4. 监控先行：安装时即配置好 statsMatcher，后续 Grafana 面板才能看到 dubbo/thrift 指标。
5. 私有协议充分测试：新 Codec 先用 e2e 环境（make docker-build-e2e）验证再上生产。
6. 社区渠道：微信联系 zhao_huabing 入群；Slack #aeraki-mesh；社区会议录像见 aeraki.net/community。
7. 灰度接入：先用一个 Dubbo/Thrift 示例 namespace 跑通 Quickstart，再逐步把真实业务迁入，避免一次性大切换。
8. 观测先行：在 Grafana 面板中预置 dubbo/thrift/redis 等协议的请求级指标看板后再放量。
9. 资源评估：Sidecar 增加了一层 MetaProtocol Proxy，注意评估 CPU/内存开销，压测后再定资源配额。

七、参考资料

• GitHub 仓库：https://github.com/aeraki-mesh/aeraki
• 官网与文档：https://www.aeraki.net
• 快速开始：https://www.aeraki.net/docs/v1.x/quickstart/
• 安装指南：https://www.aeraki.net/docs/v1.x/install/
• MetaProtocol Proxy：https://github.com/aeraki-mesh/meta-protocol-proxy
• aerakictl 工具：https://github.com/aeraki-mesh/aerakictl
• CNCF Sandbox Landscape：https://landscape.cncf.io/?selected=aeraki-mesh
• IstioCon 2022 演讲（腾讯音乐实践）：https://events.istio.io/istiocon-2022/sessions/tencent-music-aeraki/