Gateway on Liangweidong's blog

Hermes Agent 实战：自托管多通道 AI 网关与 OpenClaw 平滑迁移

Mon, 15 Dec 2025 00:00:00 +0800

时间锚点：2025-12——Hermes Agent v0.14.0（2026.5.16 发布）发布，“OpenClaw 精神继承者"定位

一、Hermes Agent 是什么

Hermes Agent 是 Nous Research 在 2025 年推出的自托管多通道 AI Agent 网关，定位是”OpenClaw 精神继承者 + 升级版"——核心代码重写，但保留 OpenClaw 用户的工作流、目录结构、SOUL.md 人格化机制。

与 OpenClaw 的核心差异：

维度	OpenClaw	Hermes Agent
出品方	社区 / VoltAgent 生态	Nous Research（Hermes 模型厂商）
核心差异	首创 SOUL.md + Discord 路由	OpenClaw 完全兼容 + 增量增强
迁移工具	-	`hermes claw migrate` 一键迁移
技能市场	ClawHub	兼容 ClawHub 技能 + 官方 Skills Hub
LLM 集成	任意 provider	Hermes 系列模型深度优化（同时支持 OpenAI/Anthropic/OpenRouter）
鉴权简化	配置文件手动	交互式 `hermes setup` 向导

二、系统要求

Python 3.11+
Git
Node.js（部分工具依赖）
ripgrep（高速代码搜索）
ffmpeg（TTS 语音消息，可选）

三、安装

3.1 Linux / macOS

1
2
3
4
5


sudo apt update && sudo apt install -y ffmpeg
ffmpeg -version

# 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装日志示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


→ Creating virtual environment with Python 3.11...
Using CPython 3.11.15
Creating virtual environment at: venv
Activate it with: source venv/bin/activate
✓ Virtual environment ready (Python 3.11)

⚠ ffmpeg not installed (TTS voice messages will be limited)
apt update && sudo apt install ffmpeg

source ~/.zshrc

hermes -V
# Hermes Agent v0.14.0 (2026.5.16)
# Project: /home/<user>/.hermes/hermes-agent
# Python: 3.11.15
# OpenAI SDK: 2.24.0
# Up to date

3.2 升级

1

hermes update

3.3 卸载

1
2
3
4
5
6
7


hermes gateway stop
systemctl --user disable hermes-gateway
hermes uninstall
rm -f ~/.local/bin/hermes
rm -rf ~/.hermes

source ~/.zshrc

四、配置 API Key

~/.hermes/.env 配置文件：

1
2


# GitHub 集成
echo "GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>" >> ~/.hermes/.env

主配置 ~/.hermes/config.yaml：

1
2
3


approvals:
 mode: manual  # manual | smart | off
 timeout: 60 # seconds to wait for user response

mode: manual 下 Agent 执行命令前需要用户确认；mode: smart 自动识别风险等级；mode: off 关闭审核（慎用）。

五、工具能力自检

安装后跑 hermes tools 查看工具可用性：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Tool Availability Summary
 6/10 tool categories available:

 ✓ Vision (image analysis)
 ✗ Mixture of Agents (missing OPENROUTER_API_KEY)
 ✗ Web Search & Extract (missing EXA_API_KEY, PARALLEL_API_KEY, FIRECRAWL_API_KEY, TAVILY_API_KEY, or SEARXNG_URL)
 ✓ Browser Automation (Local browser)
 ✗ Image Generation (missing FAL_KEY or OPENAI_API_KEY)
 ✓ Text-to-Speech (Edge TTS)
 ✗ Skills Hub (GitHub) (missing GITHUB_TOKEN)
 ✓ Terminal/Commands
 ✓ Task Planning (todo)
 ✓ Skills (view, create, edit)

✓ 可用，✗ 缺环境变量或 API key。

六、常用命令

1
2
3
4
5
6
7
8
9


hermes # Interactive CLI — 开启对话
hermes model # 选择 LLM provider 和 model
hermes tools # 配置工具开关
hermes config set # 设置配置项
hermes gateway # 启动消息网关（Telegram、Discord 等）
hermes setup # 完整配置向导
hermes claw migrate # 从 OpenClaw 迁移
hermes update # 升级
hermes doctor # 诊断

七、从 OpenClaw 平滑迁移

Hermes 的杀手锏——hermes claw migrate 一键导入 OpenClaw 配置。

7.1 首次安装时自动检测

1
2


hermes setup
# 向导会自动检测 ~/.openclaw 并询问是否迁移

7.2 手动迁移

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 交互式（推荐）
hermes claw migrate

# 预览（不实际执行）
hermes claw migrate --dry-run

# 仅迁移用户数据（不包含 API 密钥）
hermes claw migrate --preset user-data

# 覆盖已有冲突
hermes claw migrate --overwrite

7.3 迁移内容清单

类别	内容	目标位置
人格	SOUL.md	`~/.hermes/workspace/`
记忆	MEMORY.md / USER.md	`~/.hermes/workspace/`
技能	用户创建的 Skills	`~/.hermes/skills/openclaw-imports/`
命令白名单	approval patterns	`~/.hermes/config.yaml`
消息设置	平台配置 / 允许用户 / 工作目录	`~/.hermes/config.yaml`
API 密钥	允许列表内的密钥	`~/.hermes/.env`（加密）
TTS 资源	workspace 音频文件	`~/.hermes/workspace/`
Workspace 指令	AGENTS.md	`~/.hermes/workspace/AGENTS.md`

可选 --workspace-target 把 AGENTS.md 写入特定 workspace。

八、通道接入

8.1 Discord（推荐开发自用）

Discord Developer Portal 创建 Bot：

创建 Application，勾选公共机器人
Privileged Gateway Intents 全开：
- Presence Intent
- Server Members Intent
- Message Content Intent（必须，否则收不到消息）
OAuth2 URL Generator → scopes: bot + applications.commands，权限给管理员
邀请到服务器，复制服务器 ID 和频道 ID

~/.hermes/.env：

1
2
3


DISCORD_BOT_TOKEN=<YOUR_BOT_TOKEN>
DISCORD_ALLOWED_USERS=<YOUR_DISCORD_USER_ID>
DISCORD_HOME_CHANNEL=<HOME_CHANNEL_ID>

~/.hermes/config.yaml：

1
2
3
4
5
6


discord:
 require_mention: false # 自用免 @
 free_response_channels: ''
 allowed_channels: '<HOME_CHANNEL_ID>'
 auto_thread: true # 任务级隔离
 reactions: true

启动网关：

1
2


hermes gateway restart
hermes gateway status

8.2 钉钉

钉钉开放平台注册应用。

~/.hermes/.env：

1
2
3


DINGTALK_CLIENT_ID=<YOUR_CLIENT_ID>
DINGTALK_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
DINGTALK_ALLOWED_USERS=manager3211 # 允许私聊的用户

~/.hermes/config.yaml：

1

group_sessions_per_user: true

钉钉 CLI 工具（增强集成）：

1
2
3
4
5
6
7
8


# 安装
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh
# 或
npm install -g dingtalk-workspace-cli

# 登录
dws auth login
dws auth login --client-id <ID> --client-secret <SECRET>

注意：钉钉开放平台"CLI 访问管理"必须开启，并设置重定向 URL：

1
2


http://127.0.0.1
https://login.dingtalk.com

8.3 飞书

飞书 CLI 工具安装：

1
2


npx @larksuite/cli@latest install
# 或打开链接：https://open.feishu.cn/page/cli

授权时 Hermes 会申请 161 个 Scopes（涉及邮件、文档、日历、消息、Wiki、Task、Sheets、Slides、Drive、Minutes、Mail、OKR、Contact 等）。某些高权限 scope（如 vc:meeting.bot.join:write）可能被拒，需手动重试。

首次启动会发配对码，需在 Hermes 端批准：

1

hermes pairing approve feishu <PAIRING_CODE>

绑定 Hermes 账号：

1

lark-cli config bind --source hermes --identity user-default

8.4 个人微信（Hermes 独有）

Hermes 内置 iLink 协议支持个人微信：

1
2
3
4
5
6
7
8
9


# Python 环境准备（一次性）
~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/pip3 install --upgrade pip
~/.hermes/hermes-agent/venv/bin/pip install dingtalk-stream httpx aiohttp cryptography qrcode

# 启动网关
hermes gateway setup
# 输入：使用 Weixin user ID 作为 home channel? [Y/n]: y
# 显示：Home channel set to <YOUR_WECHAT_USER_ID>@im.wechat

1
2
3


✓ Weixin configured!
 Account ID: <YOUR_WECHAT_ACCOUNT_ID>@im.bot
 User ID: <YOUR_WECHAT_USER_ID>@im.wechat

首次使用需配对：

1

hermes pairing approve weixin 6XRAMJYQ

注意：电脑端看不到这个机器人（iLink 协议限制）

九、核心命令

1
2
3
4
5
6
7
8
9


hermes # Interactive CLI
hermes model # 选择 LLM provider / model
hermes tools # 配置工具
hermes config set # 单项设置
hermes gateway # 消息网关
hermes setup # 完整向导
hermes claw migrate # 从 OpenClaw 迁移
hermes update # 升级
hermes doctor # 诊断

输入使用外部编辑器：Ctrl+G（在 Hermes 提示符下）。

十、Web UI

hermes-web-ui 提供 Web 控制台。

十一、Hermes vs OpenClaw 选型建议

场景	推荐
已重度使用 OpenClaw 1 年+	Hermes（一键迁移 + 增量改进）
新项目从零搭建	OpenClaw（生态更成熟）
需要 Discord 频道路由	都行（OpenClaw 文档更详）
需要个人微信	Hermes（OpenClaw 不支持）
需要 Hermes 系列模型深度优化	Hermes
需要 ClawHub 技能市场	都行（Hermes 完全兼容）
团队生产部署	OpenClaw（更稳定，社区案例多）

十二、总结

Hermes Agent 是"OpenClaw 用户的理想升级路径"——保留熟悉的 SOUL.md、bindings、autoThread 模式，但核心代码重写更现代，与 Hermes 系列模型深度集成，又通过 hermes claw migrate 保证 OpenClaw 用户零成本迁移。

实战建议：

OpenClaw 用户：先 hermes claw migrate --dry-run 预览，确认无误后 --overwrite 迁移
多通道场景：Discord 做开发自用，钉钉/飞书做团队沟通，个人微信用 Hermes 独有
鉴权简化：hermes setup 向导比手动配 ~/.openclaw/openclaw.json 友好太多
Hermes 模型：如果用 Hermes 系列模型，Hermes Agent 性能调优更好
配置备份：~/.hermes/ 整个目录 git 版本控制，迁移/重装无忧

下一步：可参考 2025-09-15《OpenClaw 自托管 AI Agent》看 OpenClaw 原版详细配置；2024-09-15《Cursor 实战》对比 IDE 类 AI 工具的差异。

微服务中间件集群实战：Nacos / Gateway / MySQL / Redis / MQ

Wed, 15 Sep 2021 00:00:00 +0800

本文写于 2021 年 9 月——微服务架构全面铺开，Nacos 2.0+ 已发布一年（2020 年初）、Spring Cloud Gateway 已成事实标准（替代 Zuul）、Redis Cluster 在生产大规模使用，5 大微服务中间件的"集群"方案成为面试必考点。

〇、2021 视角开篇

本文主体内容是 5 大微服务中间件（Gateway / Nacos / MySQL / Redis / MQ）的集群部署实战。2021-09 这个时点选得很巧：

Nacos 2.0（2020-01 发布）刚满 1.5 年，集群方案已稳定（Distro + Raft 双协议）
Spring Cloud Gateway（2018 年发布）替代 Zuul 已成定局，2021.x 是生产主流
Redis Cluster（3.0 起）经过 4 年迭代，3 主 3 从 6 节点模式是生产标配
RocketMQ 4.x（2017 年起）多主多从模式是阿里系标配，Kafka 同期竞争

下文涉及 2016 年时实际并不存在的工具（Nacos / Spring Cloud Gateway），是以 2021 视角讲解"这些工具是何时出现、何时成熟、2021 时点怎么用"。

一、Spring Cloud Gateway 集群

1.1 概述

Spring Cloud Gateway 是 Spring Cloud 的全新项目，基于 Spring 5.0 + Spring Boot 2.0 实现，旨在提供一种简单有效的方式对 API 进行路由，并提供强大的过滤功能：熔断、限流、监控、校验、鉴权。

为什么取代 Zuul？

Zuul 1.x 基于 Servlet 阻塞模型，性能有限
Zuul 2.0 跳票多年（被 Netflix 弃坑），Spring 社区转向基于 WebFlux + Netty 的响应式网关
Gateway 基于 WebFlux 框架，底层用 Netty 通信框架，性能远超 Zuul

1.2 集群部署

Gateway 是无状态服务，集群化非常简单：多实例 + 统一入口。

第一步：pom.xml 依赖

1
2
3
4
5
6
7
8


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

第二步：application.yml 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


server:
 port: 9527

spring:
 application:
 name: cloud-gateway
 cloud:
 nacos:
 discovery:
 server-addr: nacos-cluster.internal:8848  # Nacos 集群地址
 gateway:
 discovery:
 locator:
 enabled: true # 开启从注册中心自动创建路由
 routes:
 - id: payment_route
 uri: lb://cloud-payment-service  # lb = load balance
 predicates:
 - Path=/payment/**

第三步：Nginx 入口负载均衡

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


upstream gateways {
 server 192.168.6.29:9527 weight=1;
 server 192.168.6.29:9528 weight=1; # 同一台机器两个端口模拟集群
 # server 192.168.6.30:9527 weight=1; # 多机部署
}

server {
 listen 80;
 server_name api.example.com;
 location / {
 proxy_pass http://gateways;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 }
}

关键点：

Gateway 实例之间不需要通信，各自从 Nacos 拉服务列表
网关自身的负载均衡交给 Nginx / F5 / SLB
网关是无状态服务，可以水平扩展

二、Nacos 集群

2.1 三种部署模式

单机模式：用于测试和单机使用
集群模式：用于生产环境，确保高可用
多集群模式：用于多数据中心场景

2.2 集群部署（Nacos ≥ 2.0）

前置：nacos 集群至少需要 3 个节点，因此准备 3 台服务器。

第一步：安装依赖

1
2
3


# 1. 安装 MySQL（nacos 配置持久化）
# 2. 安装 JDK 8+
# 3. 安装 Maven（仅首次构建时需要）

第二步：初始化数据库

执行 nacos 自带 SQL：conf/nacos-mysql.sql，创建 nacos_config 数据库和表。

第三步：配置 cluster.conf

将 conf/cluster.conf.example 改名为 cluster.conf：

1
2
3
4


# cluster.conf
192.168.6.21:8848
192.168.6.22:8848
192.168.6.23:8848

第四步：配置 application.properties

1
2
3
4
5


spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://192.168.6.10:3306/nacos_config?useUnicode=true&characterEncoding=utf-8
db.user=nacos
db.password={{REDACTED}}

第五步：启动

1

sh startup.sh

单台服务器启动成功后，对集群其他服务器重复同样操作即可。

2.3 集群原理

Distro 协议（AP 模式，默认）：nacos 自研的最终一致协议，每个节点负责一部分服务，多节点互写互读
Raft 协议（CP 模式，配置中心）：持久化配置走 Raft，保证强一致
节点间通过 gRPC 长连接 同步数据

三、MySQL 主从集群

3.1 集群目的

采用 MySQL 集群需要部署主从关系：

主节点：写数据（INSERT / UPDATE / DELETE）
从节点：读数据（SELECT）
关系：一主多从，用户从多个从节点读数据，大大缓解读取压力
额外收益：主节点写入自动同步到从节点，降低数据丢失风险

3.2 主从复制原理

MySQL 主从复制基于主服务器二进制日志（binlog） 跟踪所有对数据库的更改。

工作过程：

1
2
3
4
5
6
7
8
9


┌─────────┐ ┌─────────┐
│ Master │ │ Slave │
│ │ │ │
│ binlog │ <── (1) 读 binlog ─── I/O 线程 ──│ relay │
│ dump │ │ log │
│ 线程 │ ── (2) 传 binlog ───────────> │ │
│ │ │ SQL 线程│
│ │ <── (3) 同步完成通知 ───────────│ │
└─────────┘ └─────────┘

从库生成两个线程：一个 I/O 线程，一个 SQL 线程
I/O 线程请求主库的 binlog，并将 binlog 写到 relay log（中继日志）
主库生成 log dump 线程，用来给从库 I/O 线程传 binlog
SQL 线程读取 relay log，解析成具体操作，实现主从一致

3.3 核心配置

主库 my.cnf：

1
2
3
4
5


[mysqld]
server-id = 1
log-bin = /var/lib/mysql/mysql-bin
binlog-format = ROW
sync_binlog = 1

从库 my.cnf：

1
2
3
4


[mysqld]
server-id = 2
relay-log = /var/lib/mysql/relay-log
read-only = 1

主库授权：

1
2


grant replication slave on *.* to 'repl_user'@'%' identified by '{{REDACTED}}';
flush privileges;

从库配置同步：

1
2
3
4
5
6
7
8
9


CHANGE MASTER TO
 MASTER_HOST='192.168.6.21',
 MASTER_USER='repl_user',
 MASTER_PASSWORD='{{REDACTED}}',
 MASTER_LOG_FILE='mysql-bin.000001',
 MASTER_LOG_POS=0;

START SLAVE;
SHOW SLAVE STATUS\G # 看 Slave_IO_Running: Yes, Slave_SQL_Running: Yes

3.4 读写分离

两种实现方式：

数据库中间件（Mycat / Sharding-Proxy）：单独部署服务，配置实现读写分离，不侵入业务代码
客户端 SDK（dynamic-datasource / shardingsphere-jdbc）：业务代码引入 jar 包，通过注解切换

dynamic-datasource 示例（Spring Boot）：

1
2
3
4
5


<dependency>
 <groupId>com.baomidou</groupId>
 <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
 <version>3.3.2</version>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


spring:
 datasource:
 dynamic:
 primary: master
 datasource:
 master:
 url: jdbc:mysql://192.168.6.21:3306/test
 username: root
 password: {{REDACTED}}
 driver-class-name: com.mysql.cj.jdbc.Driver
 slave1:
 url: jdbc:mysql://192.168.6.22:3306/test
 username: root
 password: {{REDACTED}}
 driver-class-name: com.mysql.cj.jdbc.Driver

1
2
3
4
5
6
7
8


@Service
public class OrderService {
 @DS("master") // 写主库
 public void createOrder(Order order) { ... }
 
 @DS("slave1") // 读从库
 public List<Order> listOrders() { ... }
}

3.5 分库分表

两种方案：

Sharding Sphere（推荐）：JDBC 代理 / Proxy 模式
Mycat 2：数据库中间件，需要独立部署

四、Redis 集群

4.1 三种集群方案

主从复制模式：1 主 N 从，主写从读，但主挂了不会自动切换（需要手动）
Sentinel（哨兵）模式：在主从基础上加哨兵进程监控，主挂了自动选举新主（推荐中小规模）
Cluster 模式：Redis 3.0+ 官方方案，数据分片 + 主从 + 自动故障转移（推荐大规模）

4.2 集群部署（Cluster 模式）

官方推荐：集群至少 3 个 master 节点，最好用 3 主 3 从 6 节点模式。

1
2
3
4
5
6


# 启用集群模式
cluster-enabled yes
cluster-config-file nodes-6379.conf
cluster-node-timeout 15000
# 至少 3 个 master
cluster-migration-barrier 1

创建集群：

1
2
3
4


redis-cli --cluster create \
 192.168.6.31:6379 192.168.6.32:6379 192.168.6.33:6379 \
 192.168.6.34:6379 192.168.6.35:6379 192.168.6.36:6379 \
 --cluster-replicas 1

4.3 Cluster 原理

数据分片：16384 个 slot（哈希槽），每个 master 负责一段
请求路由：客户端通过 CRC16(key) % 16384 计算 slot
重定向：如果请求路由到错误节点，会返回 MOVED 或 ASK 让客户端重试
故障转移：master 挂了，从节点通过 Raft-like 协议选举新主

五、消息队列集群

5.1 RabbitMQ 集群

普通集群：多节点共享元数据，队列只在单节点，性能提升有限
镜像集群：队列数据多节点同步，HA 能力强但性能低
推荐方案：普通集群 + HAProxy + 镜像队列（关键业务队列）

5.2 RocketMQ 集群

NameServer 集群：无状态，多节点即可
Broker 集群：分 Master / Slave
- 多 Master：高性能但无 HA
- 多 Master 多 Slave（异步复制）：性能 + HA 平衡
- 多 Master 多 Slave（同步双写）：强 HA，性能低
推荐方案：2 主 2 异步从 + 异步刷盘

六、5 大集群对比

集群	核心协议	关键配置	HA 能力	数据一致性
Gateway	无（无状态）	Nginx upstream	自动（多实例）	无（无状态）
Nacos	Distro + Raft	cluster.conf + MySQL	自动（≥3 节点）	AP+CP 混合
MySQL	binlog + relay log	server-id + log-bin	半自动（需切换）	最终一致
Redis Cluster	哈希槽（16384）	cluster-enabled	自动（≥3 master）	最终一致
RabbitMQ	镜像队列	cluster_partition_handling	自动（镜像）	最终一致
RocketMQ	主从同步	brokerRole	自动（多主多从）	异步/同步

七、面试常问

Q：为什么 Nacos 集群至少 3 个节点？ A：Raft 协议要求过半节点存活才能选举 Leader，3 节点允许 1 节点宕机，5 节点允许 2 节点宕机。奇数节点是性价比最高的选择。

Q：MySQL 主从延迟怎么解决？ A：① 业务容忍延迟（异步复制天然有 ms 级延迟）；② 强制读主（重要业务读写都走主）；③ 半同步复制（MySQL 5.7+ rpl_semi_sync_master_wait_slave_count）；④ 用 Canal 订阅 binlog 同步到 ES / Redis。

Q：Redis Cluster 为什么是 16384 个 slot？ A：因为 16384 足够均匀分布，节点间心跳包大小可控（每个 slot 1 bit，16384 / 8 = 2KB，远小于 1MB 网络包上限）。如果用 65536，心跳包会膨胀到 8KB，且实际场景下节点数不会超过 1000，16384 足够。

Q：Spring Cloud Gateway 怎么限流？ A：内置 RequestRateLimiter GatewayFilter，基于 Redis + Lua 脚本实现令牌桶。Key 可以基于 IP / User / API Path。

八、小结

Gateway 无状态：集群 = 多实例 + 入口 LB
Nacos 集群：3 节点起步 + MySQL 持久化
MySQL 主从：binlog 同步 + 读写分离中间件
Redis Cluster：16384 哈希槽 + 3 主 3 从
MQ 集群：RabbitMQ 镜像队列 / RocketMQ 多主多从

九、2021 视角回望（微服务面试考点演化）

站在 2021-09 收尾，回看"5 大集群对比"那一节，再补充几点2021 时点的面试新趋势：

Nacos 2.0 的 gRPC 长连接：2020 年 Nacos 2.0 把数据同步从 HTTP 短连接改成长连接，性能提升 10 倍，是高频面试追问点
Spring Cloud Gateway 限流细节：内置 RequestRateLimiter + Redis Lua 是高频八股文，几乎所有 Java 面试都会问
MySQL 5.7 → 8.0 升级：2021 年 5.7 EOL 时间已定（2023-10），8.0 的 MGR（MySQL Group Replication）开始被生产采用
Redis 6.x 的多线程 IO：2020 年 Redis 6.0 发布，IO 多线程化但执行命令仍单线程，集群方案未变
Kafka vs RocketMQ 二选一：阿里系项目用 RocketMQ（事务消息），其他用 Kafka（生态 + 吞吐），2021 年仍是常见面试题

2021 时点的"5 大集群面试"标准答案：

Gateway 无状态 → 集群 = Nginx upstream + 多实例
Nacos 集群 → 至少 3 节点（过半选举） + MySQL 持久化 + gRPC 2.0 同步
MySQL 主从 → binlog + relay log + 读写分离（ShardingSphere / dynamic-datasource）
Redis Cluster → 16384 哈希槽 + 3 主 3 从 + 客户端路由
MQ 集群 → RabbitMQ 镜像队列 / RocketMQ 多主多从（同步双写保 HA）

Spring Cloud 实战：微服务、网关、安全一体化

Thu, 20 Sep 2018 00:00:00 +0800

Spring Cloud 实战：微服务、网关、安全一体化

背景与价值

Spring Cloud 是 Java 生态事实标准微服务框架（Dubbo 主要在阿里系内部使用）。基于 Spring Boot，提供了配置中心、注册中心、网关、熔断、负载均衡、链路追踪等开箱即用的微服务组件。

2018 年 Spring Cloud Finchley 发布（基于 Spring Boot 2.0），标志着 Spring Cloud 进入"模块化、可插拔"阶段。本文按"版本演进 → 核心组件 → 选型 → 实战"完整路径展开。

版本演进时间线

发布年月	Spring Boot	Spring Cloud	Spring Cloud Alibaba
2014-06	1.0	-	-
2016-01	-	Angel.SR5	-
2017-02	1.5	-	-
2017-09	-	-	Alibaba 1.5.1
2018-03	2.0	-	Alibaba 2.0.4
2018-09	-	Finchley	Alibaba 2.1
2019-10	2.2	Hoxton	-
2020-05	2.3	-	Alibaba 2.2
2021-05	2.5	-	-
2021-11	2.6	2021.0.x Jubilee	Alibaba 2021.0.x
2022-11	3.0（JDK 17+）	2022.0.x Kilburn	Alibaba 2022.0.x
2023-11	3.2	-	-

生产推荐组合（2024 稳定）：

JDK 8：Spring Boot 2.6.14 + Spring Cloud 2021.0.7 + Alibaba 2021.0.5

JDK 17/21：Spring Boot 3.2+ + Spring Cloud 2023.0.x + Alibaba 2022.0.x

核心组件全景

类别	Spring Cloud 官方	Spring Cloud Alibaba	Spring Cloud Netflix（已停更）
配置中心	Spring Cloud Config	Nacos	-
注册中心	Consul	Nacos	Eureka
服务熔断	Resilience4j	Sentinel	Hystrix
服务调用	OpenFeign	Dubbo RPC	Feign
负载均衡	Spring Cloud LoadBalancer	Dubbo LB	Ribbon
网关路由	Spring Cloud Gateway	-	Zuul
消息总线	Spring Cloud Bus	-	-
链路追踪	Sleuth + Zipkin	-	-
分布式消息	Spring Cloud Stream	RocketMQ	-
分布式事务	-	Seata	-

2024 年 Netflix 套件（Hystrix / Ribbon / Zuul）已全部进入维护模式，新项目禁用。

Spring Cloud Gateway 实战

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

注意：Gateway 基于 WebFlux（响应式），不能引入 spring-boot-starter-web！

2. 路由配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# application.yml
spring:
 cloud:
 gateway:
 routes:
 - id: user-service
 uri: lb://user-service  # lb:// = LoadBalancer 服务发现
 predicates:
 - Path=/api/user/**  # 路径匹配
 filters:
 - StripPrefix=2  # 去掉 /api/user 前缀
 - AddRequestHeader=X-Request-Id, ${UUID}
 - CircuitBreaker=myCircuitBreaker

 - id: order-service
 uri: lb://order-service
 predicates:
 - Path=/api/order/**
 - Method=POST,PUT
 filters:
 - StripPrefix=2
 - Retry=3  # 重试 3 次

3. 全局过滤器（鉴权 + 日志）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


@Component
public class GlobalAuthFilter implements GlobalFilter, Ordered {

 @Override
 public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
 ServerHttpRequest request = exchange.getRequest();
 String token = request.getHeaders().getFirst("Authorization");

 // 1. 白名单（无需 token）
 String path = request.getPath().value();
 if (path.startsWith("/api/auth/") || path.startsWith("/api/public/")) {
 return chain.filter(exchange);
 }

 // 2. 校验 token
 if (token == null || !validateToken(token)) {
 ServerHttpResponse response = exchange.getResponse();
 response.setStatusCode(HttpStatus.UNAUTHORIZED);
 return response.setComplete();
 }

 // 3. 传递用户信息给下游服务
 ServerHttpRequest mutated = request.mutate()
 .header("X-User-Id", extractUserId(token))
 .build();
 return chain.filter(exchange.mutate().request(mutated).build());
 }

 @Override
 public int getOrder() {
 return -100; // 数字越小越早执行
 }
}

4. CORS 跨域配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@Configuration
public class CorsConfig {

 @Bean
 public CorsWebFilter corsFilter() {
 CorsConfiguration config = new CorsConfiguration();
 config.addAllowedOriginPattern("*");
 config.addAllowedHeader("*");
 config.addAllowedMethod("*");
 config.setAllowCredentials(true);
 config.setMaxAge(3600L);

 UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
 source.registerCorsConfiguration("/**", config);
 return new CorsWebFilter(source);
 }
}

Nacos 注册中心 + 配置中心

Nacos 集成注册中心 + 配置中心，一站式替代 Eureka + Config + Bus。

1. 服务注册

1
2
3
4
5
6
7
8


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


spring:
 application:
 name: user-service
 cloud:
 nacos:
 discovery:
 server-addr: {{NACOS_HOST}}:8848
 namespace: prod
 username: {{NACOS_USER}}
 password: {{NACOS_PASSWORD}}
 config:
 server-addr: {{NACOS_HOST}}:8848
 file-extension: yaml
 refresh-enabled: true
 shared-configs:
 - data-id: common.yaml
 refresh: true

2. 配置动态刷新

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@RestController
@RefreshScope // 关键注解：nacos 配置变更时自动刷新 @Value
public class OrderController {

 @Value("${order.timeout:30}")
 private int timeout;

 @GetMapping("/timeout")
 public String getTimeout() {
 return "当前超时时间: " + timeout + " 秒";
 }
}

3. 集群部署（3 节点）

1
2
3
4
5
6
7


# 节点 1
sh startup.sh -m standalone # 单机模式（仅测试）
sh startup.sh -m cluster # 集群模式（生产）

# application.properties
nacos.cluster.name=Cluster-A
nacos.member.list=192.168.1.1:8848,192.168.1.2:8848,192.168.1.3:8848

集群模式需要 MySQL 存储（替代默认 Derby），3 节点 Raft 选举实现高可用。

Spring Security 实战

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-security</artifactId>
</dependency>

2. 基础配置（用户名密码登录）

1
2
3
4
5
6


spring:
 security:
 user:
 name: admin
 password: {{ADMIN_PASSWORD}}  # 实际值从 Nacos 配置中心读取
 roles: ADMIN

默认会拦截所有请求，访问 http://localhost:8080 弹出登录框。

3. JWT 鉴权配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@Configuration
@EnableWebSecurity
public class SecurityConfig {

 @Bean
 public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 http
 .csrf(csrf -> csrf.disable())
 .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
 .authorizeHttpRequests(auth -> auth
 .requestMatchers("/api/auth/**", "/api/public/**").permitAll()
 .anyRequest().authenticated()
 )
 .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);

 return http.build();
 }

 @Bean
 public PasswordEncoder passwordEncoder() {
 return new BCryptPasswordEncoder();
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


@Component
public class JwtAuthFilter extends OncePerRequestFilter {

 @Override
 protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
 throws ServletException, IOException {
 String token = request.getHeader("Authorization");
 if (token != null && token.startsWith("Bearer ")) {
 String jwt = token.substring(7);
 try {
 Claims claims = Jwts.parser()
 .verifyWith(Keys.hmacShaKeyFor(secret.getBytes()))
 .build()
 .parseSignedClaims(jwt)
 .getPayload();

 String username = claims.getSubject();
 List<String> roles = claims.get("roles", List.class);

 List<SimpleGrantedAuthority> authorities = roles.stream()
 .map(r -> new SimpleGrantedAuthority("ROLE_" + r))
 .collect(Collectors.toList());

 UsernamePasswordAuthenticationToken auth =
 new UsernamePasswordAuthenticationToken(username, null, authorities);
 SecurityContextHolder.getContext().setAuthentication(auth);
 } catch (Exception e) {
 // token 无效
 }
 }
 chain.doFilter(request, response);
 }
}

OpenFeign 服务调用

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

2. 声明式调用

1
2
3
4
5
6
7
8
9


@FeignClient(name = "order-service", fallback = OrderClientFallback.class)
public interface OrderClient {

 @GetMapping("/api/order/{userId}")
 Result<List<Order>> listByUser(@PathVariable Long userId);

 @PostMapping("/api/order")
 Result<Order> create(@RequestBody OrderDTO order);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@RestController
public class UserController {

 @Autowired
 private OrderClient orderClient;

 @GetMapping("/user/{id}/orders")
 public Result<List<Order>> getUserOrders(@PathVariable Long id) {
 return orderClient.listByUser(id);
 }
}

3. Fallback 降级

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Component
public class OrderClientFallback implements OrderClient {

 @Override
 public Result<List<Order>> listByUser(Long userId) {
 return Result.fail("订单服务不可用，请稍后重试");
 }

 @Override
 public Result<Order> create(OrderDTO order) {
 return Result.fail("订单创建失败");
 }
}

Sentinel 熔断限流

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

2. 控制台部署

1
2
3
4
5


docker run -d \
 -p 8858:8858 \
 -p 8719:8719 \
 --name sentinel-dashboard \
 bladex/sentinel-dashboard:1.8.6

访问 http://localhost:8858，账号 sentinel / sentinel。

3. 流量控制规则（代码方式）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@PostConstruct
public void initFlowRules() {
 List<FlowRule> rules = new ArrayList<>();
 FlowRule rule = new FlowRule("userService");
 rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
 rule.setCount(100); // QPS 阈值
 rule.setLimitApp("default");
 rules.add(rule);
 FlowRuleManager.loadRules(rules);
}

链路追踪（Sleuth + Zipkin）

1
2
3
4
5
6
7
8


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.zipkin</groupId>
 <artifactId>zipkin-reporter-brave</artifactId>
</dependency>

1
2
3
4
5
6


spring:
 zipkin:
 base-url: http://{{ZIPKIN_HOST}}:9411
 sleuth:
 sampler:
 probability: 0.1 # 采样率 10%

每次 HTTP 请求会自动注入 X-B3-TraceId / X-B3-SpanId，通过 Zipkin UI 看到完整调用链。

微服务方案选型决策

场景	推荐方案
传统企业（Java 8 为主）	Spring Cloud 2021.0.x + Alibaba 2021.0.x
新项目（Java 17/21）	Spring Cloud 2023.0.x + Alibaba 2022.0.x
高吞吐业务	Spring Cloud Gateway + Sentinel + RocketMQ
阿里系	Spring Cloud Alibaba（Nacos + Sentinel + Seata）
多语言异构	Spring Cloud Gateway + gRPC + Nacos

前置知识与下一步

前置：

Spring Boot 基础
微服务基本概念（服务注册 / 发现 / 熔断）
Linux + Docker 基础

下一步：

分布式事务：Spring Cloud Alibaba Seata（AT/TCC/SAGA/XA 4 种模式）
配置中心深度：Nacos 长轮询 + 灰度发布
监控：Spring Boot Admin + Actuator + Prometheus + Grafana

小结

Spring Cloud 2021.0.x（Jubilee） + Spring Cloud Alibaba 2021.0.x 是当前最稳定的 Java 微服务组合。Nacos 一体化注册 + 配置中心、Sentinel 替代 Hystrix、Seata 解决分布式事务、Gateway 替代 Zuul，是核心 4 件套。新项目直接基于 Spring Boot 3.2+ + Spring Cloud 2023.0.x，老项目维持 Spring Boot 2.6 + Spring Cloud 2021.0.x。

2024+ 视角：Spring Cloud 2024 / 2025 与 Spring AI

Spring Cloud 版本节奏（2024 视角）

发布年份	Spring Boot	Spring Cloud	Spring Cloud Alibaba	关键变化
2024-11	3.4	2024.0.x	2023.0.x	JDK 17+ 强制
2025-05	3.5	2025.0.x	2023.0.x	Spring AI 1.0 GA

生产推荐：

JDK 17：Spring Boot 3.4 + Spring Cloud 2024.0.x + Alibaba 2023.0.x
JDK 21：Spring Boot 3.5 + Spring Cloud 2025.0.x + Alibaba 2023.0.x

Spring AI 1.0（2025 GA）

Spring 官方推出的 LLM 集成框架——类似 LangChain 的 Java 版：

1
2
3
4


<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@RestController
public class ChatController {

 private final ChatClient chatClient;

 public ChatController(ChatClient.Builder builder) {
 this.chatClient = builder.build();
 }

 @GetMapping("/chat")
 public String chat(@RequestParam String message) {
 return chatClient.prompt()
 .user(message)
 .call()
 .content();
 }
}

核心能力：

多模型支持（OpenAI / Anthropic / Azure / Ollama / DeepSeek / 通义千问）
Function Calling（让 LLM 调 Java 方法）
RAG（向量库集成：pgvector / Milvus / Qdrant）
Prompt Template + 结构化输出

Spring Cloud Gateway 4.x 新特性

响应式 API 更完善：ServerWebExchange + Reactor 性能 +30%
GraphQL 路由：内置 GraphQL endpoint
WebSocket 增强：原生支持 WebSocket 路由
gRPC 集成：spring-cloud-starter-gateway + grpc-gateway 双向

Spring Cloud Stream 4.x + Kafka 3.x

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


spring:
 cloud:
 stream:
 bindings:
 output:
 destination: orders
 content-type: application/json
 kafka:
 binder:
 brokers: kafka:9092
 configuration:
 compression.type: zstd  # 2024+ 默认压缩
 linger.ms: 20

2024+ 选型：Spring Cloud vs Istio

场景	Spring Cloud	Istio / 服务网格
传统 Java 微服务	✅ 首选	重
多语言（Go / Python / Node）	一般	✅ 首选
流量管理复杂	一般	✅ 蓝绿/金丝雀/镜像
学习成本	低	高
性能开销	低	中（Sidecar 5-10%）

2024+ 趋势：Spring Cloud + Istio 双层——Java 业务用 Spring Cloud 简化，跨语言/灰度发布用 Istio 解决。

国产化适配

Spring Cloud Alibaba 2023.0.x 适配 Spring Boot 3.4+
Nacos 2.3+ 支持国密算法（SM2/SM3/SM4）
Sentinel 1.8.8+ 流量规则支持 Prometheus metrics 导出
Seata 2.x TC Server 高可用增强（Raft 共识）

2024+ 实战坑

JDK 17 / 21 反射限制：--add-opens java.base/java.lang=ALL-UNNAMED 等参数要加到启动脚本
Spring Boot 3.x Jakarta EE 9+：javax.* → jakarta.* 全量替换
Spring Cloud 2024.0.x 强制 Netty 4.1.x——有自定义 Netty handler 的项目要注意 API 变更
Spring AI 还在快速迭代——生产用建议锁定 1.0 GA 版本，别追 1.1-SNAPSHOT

2024+ 推荐组合

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Java 后端服务（ToB、传统企业）
├── JDK 17 / 21
├── Spring Boot 3.4 / 3.5
├── Spring Cloud 2024.0.x / 2025.0.x
├── Spring Cloud Alibaba 2023.0.x
│ ├── Nacos 2.3+ (注册 + 配置)
│ ├── Sentinel 1.8.8+ (熔断限流)
│ ├── Seata 2.x (分布式事务)
│ └── RocketMQ 5.x (消息)
├── Spring Cloud Gateway 4.x (网关)
├── OpenFeign 4.x (RPC)
├── Resilience4j 2.x (熔断，替代 Hystrix)
├── Micrometer + Prometheus + Grafana (监控)
├── OpenTelemetry (Tracing)
└── Spring AI 1.0 (AI 能力，可选)