摘要

• 依据 Spring Cloud Alibaba 版本发布说明，搭建与 Spring Cloud Alibaba 2025.0.0.0 对应的 Sentinel Dashboard 1.8.9。

• 本文侧重 Dashboard 单机搭建（JAR / Docker / systemd），并补充应用侧接入、OpenFeign / RestTemplate / Gateway 适配，以及 Nacos 规则持久化。

• 生产推荐：规则持久化到 Nacos（Push 模式）；Dashboard 可选（仅监控时需要），限流生效不依赖控制台。

• 同版本配套的 Nacos Server 见 Spring Cloud Alibaba 2025.0.0.0 配套搭建 Nacos 3.0.3。

一、版本对照

1. Spring Cloud Alibaba 2025.0.x 适配关系

摘自官方 版本发布说明：

同页「组件版本关系」中，与 2025.0.0.0 对应的 Sentinel 版本为：

对比：同属 2025.x 的 2025.1.0.0 亦使用 Sentinel 1.8.9，服务端 Dashboard 版本可共用。

2. 环境准备

端口规划（与 Nacos 同机时建议错开控制台端口）：

二、搭建 Sentinel Dashboard 1.8.9

官方发布包：Sentinel v1.8.9 Release（资源文件 sentinel-dashboard-1.8.9.jar）。
控制台说明见 Sentinel Wiki · Dashboard。

1. 方式一：JAR 直接启动（推荐）

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

mkdir -p /usr/local/sentinel && cd /usr/local/sentinel

# 跟随请求重定向
curl -L https://github.com/alibaba/Sentinel/releases/download/1.8.9/sentinel-dashboard-1.8.9.jar

# 使用 8858，避免与 Nacos 控制台 8080 冲突
nohup java \
  -Dserver.port=8858 \
  -Dcsp.sentinel.dashboard.server=10.10.2.45:8858 \
  -Dproject.name=sentinel-dashboard \
  -jar sentinel-dashboard-1.8.9.jar \
  > sentinel-dashboard.log 2>&1 &

访问：http://127.0.0.1:8858
默认账号 / 密码：sentinel / sentinel（生产务必修改）。

2. 方式二：Docker 启动

官方在 sentinel-dashboard 目录提供 Dockerfile（1.8.9 / 1.8 分支均有）。镜像构建时会从 GitHub Release 再下载 sentinel-dashboard-1.8.9.jar，因此构建机需能访问 GitHub；网络不稳时优先用上文「方式一」官方 JAR。

构建前必读

1. 基础镜像失效：官方 Dockerfile 的基础镜像 openjdk:8-jre-slim 已在 Docker Hub 上失效，无论用下面（1）（2）（3）哪种方式，都需先修改 Dockerfile 中的 FROM（例如改为 openjdk:8u212-jre-slim），再执行 docker build。具体替换命令与 slim / 非 slim 说明见下文 （3）。
2. GitHub 下载失败：官方 Dockerfile 在构建阶段会通过 curl 访问 release-assets.githubusercontent.com 拉取 JAR。若出现 curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL，说明 Docker 构建网络无法稳定访问 GitHub Release（国内环境较常见）。此时请改用下文 （3.1）宿主机预下载 JAR，或直接用上文「方式一」JAR 启动。

docker build 的上下文必须是含 Dockerfile 的 sentinel-dashboard 目录，任选下面一种准备源码：

（1）完整克隆（最简单）

1
2
3
4
5
6
7
8

git clone https://github.com/alibaba/Sentinel.git
cd Sentinel
git checkout 1.8.9

docker build \
  --build-arg SENTINEL_VERSION=1.8.9 \
  -t sentinel-dashboard:1.8.9 \
  sentinel-dashboard

（2）稀疏克隆（只取 sentinel-dashboard，省流量）

1
2
3
4
5
6
7
8
9
10

git clone --filter=blob:none --sparse \
  https://github.com/alibaba/Sentinel.git
cd Sentinel
git sparse-checkout set sentinel-dashboard
git checkout 1.8.9

docker build \
  --build-arg SENTINEL_VERSION=1.8.9 \
  -t sentinel-dashboard:1.8.9 \
  sentinel-dashboard

（3）不克隆仓库，只下载 Dockerfile

官方 Dockerfile 本质是拉取 Release JAR，也可单独下载该文件后构建。

注意：官方 Dockerfile 的基础镜像为 openjdk:8-jre-slim，该标签在 Docker Hub 上已不可用（docker pull 会报 not found）。下载后需改为仍可拉取的标签，例如 openjdk:8u212-jre-slim（与本节开头「构建前必读」一致）。

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

mkdir -p sentinel-dashboard && cd sentinel-dashboard
curl -fsSL -o Dockerfile \
  https://raw.githubusercontent.com/alibaba/Sentinel/1.8.9/sentinel-dashboard/Dockerfile

# 将已失效的 openjdk:8-jre-slim 替换为可用镜像
sed -i.bak 's|FROM openjdk:8-jre-slim|FROM openjdk:8u212-jre-slim|' Dockerfile
# macOS / Linux 通用；也可用编辑器手动改 FROM 那一行

docker build \
  --build-arg SENTINEL_VERSION=1.8.9 \
  -t sentinel-dashboard:1.8.9 \
  .

修改后的关键行应类似：

1

FROM openjdk:8u212-jre-slim

PS：openjdk:8-*-slim 与不带 slim 的镜像区别

• 带 slim：基于 Debian slim 精简根文件系统，体积更小、攻击面更小，适合只跑 JRE 的生产镜像；但预装工具更少（如部分调试命令、额外字体/locale 可能缺失）。
• 不带 slim（如 openjdk:8u212-jre）：完整 Debian 基础层，体积更大，调试与兼容性通常更好，一般用于开发排查或对系统库有额外依赖的场景。
  Sentinel Dashboard 仅依赖 JRE 跑 JAR，优先用 slim 即可；若构建或运行时缺库，再改用不带 slim 的同版本标签。

（4）构建阶段 GitHub 下载失败（SSL_ERROR_SYSCALL）

若 docker build 在 installer 阶段报错类似：

1

curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to release-assets.githubusercontent.com:443

说明官方多阶段 Dockerfile 在 容器内 拉取 GitHub Release 失败。可在 宿主机 先下载 JAR，再改用本地 COPY，避免构建时再访问 GitHub：

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

mkdir -p sentinel-dashboard && cd sentinel-dashboard

# 在宿主机下载 JAR（可用代理、镜像站，或从内网机器 scp 过来）
wget https://github.com/alibaba/Sentinel/releases/download/1.8.9/sentinel-dashboard-1.8.9.jar

cat > Dockerfile <<'EOF'
FROM openjdk:8u212-jre-slim

COPY sentinel-dashboard-1.8.9.jar /home/sentinel-dashboard.jar

ENV JAVA_OPTS '-Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080'

RUN chmod -R +x /home/sentinel-dashboard.jar

EXPOSE 8080

CMD java ${JAVA_OPTS} -jar /home/sentinel-dashboard.jar
EOF

docker build -t sentinel-dashboard:1.8.9 .

若宿主机同样无法访问 GitHub，可在一台能下载的机器上取回 sentinel-dashboard-1.8.9.jar 后拷贝到构建目录，再执行 docker build。若不需要容器化，直接用上文「方式一」JAR 启动更简单。

（5）运行容器

1
2
3
4
5

docker run -d \
  --name sentinel-dashboard \
  -p 8858:8080 \
  -e JAVA_OPTS='-Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080' \
  sentinel-dashboard:1.8.9

访问宿主机：http://127.0.0.1:8858。

社区也有第三方镜像（如 bladex/sentinel-dashboard:1.8.9），使用前请确认来源可信；本文优先官方 JAR。

3. systemd 托管示例（可选）

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

# /etc/systemd/system/sentinel-dashboard.service
[Unit]
Description=Sentinel Dashboard 1.8.9
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/usr/local/sentinel
ExecStart=/usr/bin/java -Dserver.port=8858 -Dcsp.sentinel.dashboard.server=127.0.0.1:8858 -Dproject.name=sentinel-dashboard -jar /usr/local/sentinel/sentinel-dashboard-1.8.9.jar
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

1
2
3

systemctl daemon-reload
systemctl enable --now sentinel-dashboard
systemctl status sentinel-dashboard

三、应用侧快速接入（SCA 2025.0.0.0）

官方指南：SCA · Sentinel 快速开始。

1. BOM 与依赖

父 POM / 依赖管理：

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

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2025.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>com.alibaba.cloud</groupId>
      <artifactId>spring-cloud-alibaba-dependencies</artifactId>
      <version>2025.0.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

业务模块引入：

1
2
3
4

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

Starter 会传递依赖 sentinel-* :1.8.9，与上文 Dashboard 版本对齐。

2. application.yml 示例

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

server:
  port: 18082

spring:
  application:
    name: demo-provider
  cloud:
    sentinel:
      transport:
        dashboard: 127.0.0.1:8858
        # 客户端供 Dashboard 回调的本地端口，默认 8719，冲突时可改
        # port: 8719
      eager: true

3. 代码最小示例

1
2
3
4
5
6
7
8
9

@RestController
public class TestController {

    @GetMapping("/hello")
    @SentinelResource("hello")
    public String hello() {
        return "Hello Sentinel";
    }
}

应用启动并访问一次受保护接口后，打开 Sentinel 控制台，应能看到应用名 demo-provider 及资源 hello，随后可在控制台配置流控规则验证限流。

四、客户端组件适配（OpenFeign / RestTemplate / Gateway）

spring-cloud-starter-alibaba-sentinel 对 Spring Cloud 生态常见 HTTP 客户端做了适配。完整说明见 SCA · Sentinel 进阶指南 · 客户端支持。

Servlet 侧的 spring.cloud.sentinel.filter.*、servlet.block-page 等配置对 OpenFeign / RestTemplate 不生效，需按下面各自方式配置限流与降级处理。

1. OpenFeign

依赖：Sentinel Starter + OpenFeign（版本由 BOM 管理）：

1
2
3
4
5
6
7
8

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

需显式打开开关：

1
2
3

feign:
  sentinel:
    enabled: true

示例：

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

@FeignClient(
    name = "service-provider",
    fallback = EchoServiceFallback.class,
    configuration = FeignConfiguration.class
)
public interface EchoService {

    @GetMapping("/echo/{str}")
    String echo(@PathVariable("str") String str);
}

class FeignConfiguration {
    @Bean
    public EchoServiceFallback echoServiceFallback() {
        return new EchoServiceFallback();
    }
}

class EchoServiceFallback implements EchoService {
    @Override
    public String echo(@PathVariable("str") String str) {
        return "echo fallback";
    }
}

要点：

2. RestTemplate

对 RestTemplate Bean 加 @SentinelRestTemplate：

1
2
3
4
5
6
7
8

@Bean
@SentinelRestTemplate(
    blockHandler = "handleException",
    blockHandlerClass = ExceptionUtil.class
)
public RestTemplate restTemplate() {
    return new RestTemplate();
}

blockHandler / fallback 对应方法必须是 blockHandlerClass / fallbackClass 中的 静态方法；参数、返回值与 ClientHttpRequestInterceptor#intercept 一致，并多一个 BlockException：

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

import com.alibaba.cloud.sentinel.rest.SentinelClientHttpResponse;
import com.alibaba.csp.sentinel.slots.block.BlockException;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpResponse;

public class ExceptionUtil {

    public static ClientHttpResponse handleException(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution,
            BlockException exception) {
        return new SentinelClientHttpResponse("blocked by sentinel");
    }
}

要点：

例：GET https://www.taobao.com/test 对应资源名可为 GET:https://www.taobao.com/test 或 GET:https://www.taobao.com。

3. Spring Cloud Gateway（简述）

网关限流需额外依赖（与普通业务服务的 Starter 组合使用）：

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

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

规则类型使用 gw-flow / gw-api-group（见第五节对照表）。熔断后的响应可通过 spring.cloud.sentinel.scg.fallback.* 配置（mode=redirect | response 等），详见 进阶指南 与 Sentinel 网关限流。

五、单台 Dashboard + Nacos 规则持久化

官方 Dashboard 不提供集群，生产更务实的做法是：把规则落到 Nacos 配置中心（Push 模式）。应用启动后从 Nacos 拉取规则并监听变更，重启不丢。单台 Dashboard 仅作可选监控面板。动态数据源说明见 SCA · Sentinel 进阶指南。

前提：已按 Spring Cloud Alibaba 2025.0.0.0 配套搭建 Nacos 3.0.3 跑通 Nacos 3.0.3（含鉴权账号密码）。

1. 架构说明

1
2
3
4
5
6
7

                  推送 / 监听（自动）
Nacos Config  ─────────────────────►  业务应用（Sentinel Client 内存）
（规则真源）                                   │
     ▲                                         │ 控制台打开规则页时查询客户端（可选）
     │ 人工维护配置（推荐）                      ▼
Nacos 控制台                        Sentinel Dashboard（单台，可选）
                                        监控、看板；开箱不写回 Nacos

同步方向（务必分清）

一句话：真源永远是 Nacos，不是控制台。
Nacos 改了会自动到应用，控制台打开规则页时通常也能查到；控制台改了不会进 Nacos。两边一起改容易互相覆盖，持久化启用后请统一在 Nacos 维护。

Dashboard 是否必须启动？

不必须。 只保证限流 / 熔断生效时，可以不启 Sentinel Dashboard：

• sentinel-datasource-nacos 在应用启动时从 Nacos 拉规则并监听变更，与 Dashboard 无关

• 不配 / 不启控制台时，流控、熔断照常工作

• spring.cloud.sentinel.transport.dashboard 也可去掉或先注释掉

Dashboard 只是可选运维面板（实时 QPS、机器列表、簇点链路等）。需要临时看监控时再启一台，把 transport.dashboard 指过去即可；规则仍以 Nacos 为准。

% note tip %
若强依赖「控制台点几下就落库」，需二次开发 Dashboard（源码自带 Nacos 推拉示例，社区亦有改版包），本文不展开，优先 Nacos 直配。
% endnote %

2. 应用依赖

在已有 spring-cloud-starter-alibaba-sentinel 之外，再引入 Nacos 数据源（版本由 SCA BOM 管理）：

1
2
3
4

<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

不必单独声明 nacos-client 版本；与同体系 Nacos 3.0.3 对齐即可。若项目已引入 spring-cloud-starter-alibaba-nacos-discovery / config，账号密码等可复用。

3. application.yml 示例

在第三节配置基础上增加 datasource（可并存多种 rule-type，每种对应一个 Nacos DataId）。下面一次挂上常用五类，按需删减即可：

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

server:
  port: 18082

spring:
  application:
    name: demo-provider
  cloud:
    sentinel:
      # 仅做监控时需要；纯 Nacos 规则持久化可不配 / 不启 Dashboard
      transport:
        dashboard: 127.0.0.1:8858
      eager: true
      datasource:
        flow:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            namespace:                   # 留空即 public；与 Nacos 控制台所选命名空间一致
            data-id: ${spring.application.name}-flow-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: flow
        degrade:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-degrade-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: degrade
        authority:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-authority-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: authority
        system:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-system-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: system
        param-flow:
          nacos:
            server-addr: 127.0.0.1:8848
            username: nacos
            password: YourStrongPassword
            data-id: ${spring.application.name}-param-flow-rules
            group-id: SENTINEL_GROUP
            data-type: json
            rule-type: param-flow

常用 rule-type 与文档对照（Nacos 中均为对应实体的 JSON 数组；下一节给出五类示例）：

SCA 的 进阶指南 说明 datasource 怎么挂；字段有疑问时再对照上表 *Rule.java。

4. 在 Nacos 中创建规则配置

统一在 Nacos 控制台 → 配置管理 → 配置列表 新建，Group 均为 SENTINEL_GROUP，配置格式 为 JSON：

4.1 流控 flow（demo-provider-flow-rules）

对资源 hello 限流 QPS = 2：

1
2
3
4
5
6
7
8
9
10
11

[
  {
    "resource": "hello",
    "limitApp": "default",
    "grade": 1,
    "count": 2,
    "strategy": 0,
    "controlBehavior": 0,
    "clusterMode": false
  }
]

4.2 熔断 degrade（demo-provider-degrade-rules）

异常比例熔断（grade: 1，count 为 0~1）：

1
2
3
4
5
6
7
8
9
10

[
  {
    "resource": "hello",
    "grade": 1,
    "count": 0.5,
    "timeWindow": 10,
    "minRequestAmount": 5,
    "statIntervalMs": 1000
  }
]

4.3 授权 authority（demo-provider-authority-rules）

仅允许来源 appA、appB 访问资源 hello（白名单，strategy: 0）：

1
2
3
4
5
6
7

[
  {
    "resource": "hello",
    "limitApp": "appA,appB",
    "strategy": 0
  }
]

% note tip %
授权规则依赖请求「来源」标识。Web 场景需实现 RequestOriginParser（解析 Header / 参数等为 origin），否则 limitApp 对不上，规则不按预期生效。
% endnote %

4.4 系统保护 system（demo-provider-system-rules）

入口级自适应保护（对全部入口生效，无单独 resource；未用到的指标保持 -1 表示不启用）：

1
2
3
4
5
6
7
8
9

[
  {
    "highestSystemLoad": 5.0,
    "highestCpuUsage": 0.8,
    "avgRt": 200,
    "maxThread": 100,
    "qps": 1000
  }
]

4.5 热点参数 param-flow（demo-provider-param-flow-rules）

对资源 hello 的第 0 个参数默认 QPS = 5；参数值 1001 单独放开到 QPS = 10：

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

[
  {
    "resource": "hello",
    "grade": 1,
    "paramIdx": 0,
    "count": 5,
    "controlBehavior": 0,
    "durationInSec": 1,
    "clusterMode": false,
    "paramFlowItemList": [
      {
        "object": "1001",
        "classType": "int",
        "count": 10
      }
    ]
  }
]

% note tip %
热点规则必须把参数传入 Sentinel 埋点，例如 SphU.entry("hello", EntryType.IN, 1, userId)，paramIdx: 0 即对应第一个 args。仅写 @SentinelResource("hello")、调用时不传参，热点规则不会按参数生效。
% endnote %

5. 验证步骤

6. 可选：Dashboard 侧双向推送（源码改造）

开箱 Dashboard 不会把控制台改动写回 Nacos。下文 6.2～6.4 按推荐路线介绍 Dashboard 侧改造（V2 + Nacos Provider/Publisher）；若在网上看到「客户端 WritableDataSource 反写 Nacos」的做法，见本章末尾 6.5 作对照了解即可。

官方在 1.8.9 源码里只放了一套 流控规则 的 Dashboard 改造示例（不是完整生产方案），且位于 src/test，发布包 JAR 里看不到。

6.1 代码到底在哪（为何在仓库里不好找）

克隆并切到 tag 后路径为（浏览器可直接打开）：

对应本地目录：

1
2
3
4
5

sentinel-dashboard/src/test/java/com/alibaba/csp/sentinel/dashboard/rule/nacos/
├── NacosConfig.java
├── NacosConfigUtil.java
├── FlowRuleNacosProvider.java
└── FlowRuleNacosPublisher.java

找不到时常见原因：

1. 只下了 sentinel-dashboard-1.8.9.jar（不含 src/test）

2. 在 src/main 里搜（示例默认不在 main）

3. 看了错误分支 / 未切到 1.8.9

4. 以为还有 degrade / authority 等示例——没有；官方 test 样例 只有 flow，其它规则类型需自行照抄扩展

官方样例约定与本文一致性较好：

• Group：SENTINEL_GROUP（见 NacosConfigUtil.GROUP_ID）

• DataId：{app}-flow-rules（见 FLOW_DATA_ID_POSTFIX = "-flow-rules"），与上文 demo-provider-flow-rules 一致

6.2 改造步骤（以流控双向同步为例）

1
2
3
4

git clone https://github.com/alibaba/Sentinel.git
cd Sentinel
git checkout 1.8.9
cd sentinel-dashboard

步骤 1：放开 Nacos 依赖（去掉 test scope）

编辑 sentinel-dashboard/pom.xml，将：

1
2
3
4
5

<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
  <scope>test</scope>
</dependency>

改为（删除 <scope>test</scope>，必要时升到与 Nacos 3.x 兼容的客户端版本）：

1
2
3
4

<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

步骤 2：把 test 样例拷到 main

1
2
3

mkdir -p src/main/java/com/alibaba/csp/sentinel/dashboard/rule/nacos
cp src/test/java/com/alibaba/csp/sentinel/dashboard/rule/nacos/*.java \
   src/main/java/com/alibaba/csp/sentinel/dashboard/rule/nacos/

步骤 3：改 NacosConfig，接上 Nacos 3.x 地址与鉴权

官方默认是 ConfigFactory.createConfigService("localhost")，对 Nacos 3.x（含鉴权、端口 8848）不够用。建议改成可配置，例如：

1
2
3
4
5
6
7
8
9

@Bean
public ConfigService nacosConfigService() throws Exception {
    Properties properties = new Properties();
    properties.put("serverAddr", "127.0.0.1:8848");
    properties.put("namespace", "");          // public 留空；其它命名空间填 namespaceId
    properties.put("username", "nacos");
    properties.put("password", "YourStrongPassword");
    return ConfigFactory.createConfigService(properties);
}

（也可用 application.properties + @Value 注入，避免把密码写死在代码里。）

步骤 4（建议）：发布时转成客户端可直接消费的 FlowRule JSON

官方 encoder 直接 JSON.toJSONString(List<FlowRuleEntity>)，会带上 app / gmtCreate 等控制台字段。客户端 rule-type: flow 一般能忽略多余字段，但更干净的做法是发布前 toRule()：

1
2
3
4
5
6

@Bean
public Converter<List<FlowRuleEntity>, String> flowRuleEntityEncoder() {
    return list -> JSON.toJSONString(
        list.stream().map(FlowRuleEntity::toRule).collect(Collectors.toList())
    );
}

decoder 仍可 JSON.parseArray(s, FlowRuleEntity.class)（字段重合部分能填上；打开规则页时 Controller 还会补 app）。

步骤 5：让 FlowControllerV2 使用 Nacos 的 Provider / Publisher

编辑 com.alibaba.csp.sentinel.dashboard.controller.v2.FlowControllerV2.java。该类通过 @Qualifier 注入规则读写 Bean；默认走内存实现，需 只改两个 Qualifier 名，指向步骤 2 拷到 main 的 Nacos 实现（@Component("flowRuleNacosProvider") / @Component("flowRuleNacosPublisher")）：

修改前（默认，读写内存，不写 Nacos）：

1
2
3
4
5
6

@Autowired
@Qualifier("flowRuleDefaultProvider")
private DynamicRuleProvider<List<FlowRuleEntity>> ruleProvider;
@Autowired
@Qualifier("flowRuleDefaultPublisher")
private DynamicRulePublisher<List<FlowRuleEntity>> rulePublisher;

修改后（读写 Nacos）——仅替换 Qualifier 中的 Bean 名：

1
2
3
4
5
6

@Autowired
@Qualifier("flowRuleNacosProvider")      // default → nacos
private DynamicRuleProvider<List<FlowRuleEntity>> ruleProvider;
@Autowired
@Qualifier("flowRuleNacosPublisher")     // default → nacos
private DynamicRulePublisher<List<FlowRuleEntity>> rulePublisher;

即：flowRuleDefaultProvider → flowRuleNacosProvider，flowRuleDefaultPublisher → flowRuleNacosPublisher。字段类型与其它代码不用动。

步骤 6：前端菜单切到 V2 流控页

1.8.9 默认侧边栏「流控规则」指向 V1：

1
2

<!-- sidebar.html -->
<a ui-sref="dashboard.flowV1({app: entry.app})">流控规则</a>

改为（注意：V2 的 state 名是 dashboard.flow，URL 为 /v2/flow/:app）：

1

<a ui-sref="dashboard.flow({app: entry.app})">流控规则</a>

文件：src/main/webapp/resources/app/scripts/directives/sidebar/sidebar.html。

簇点链路里「加流控」走的是 identity.js + FlowServiceV1，同样要改：

• FlowServiceV1 → FlowServiceV2

• 跳转路径 /dashboard/flow/ → /dashboard/v2/flow/

文件：src/main/webapp/resources/app/scripts/controllers/identity.js。

步骤 7：打包替换官方 JAR

1
2
3
4

# 在仓库根目录或 dashboard 模块按官方方式打包
mvn -pl sentinel-dashboard -am clean package -DskipTests
# 产物一般在 sentinel-dashboard/target/sentinel-dashboard.jar
java -Dserver.port=8858 -jar target/sentinel-dashboard.jar

6.3 改造后如何验证

6.4 能力边界

• 官方样例 只覆盖 flow；熔断 / 授权 / 系统 / 热点需自行增加成对的 Provider/Publisher，并改对应 Controller（它们默认也不是 V2 + DynamicRule 模式）。

• 运维成本明显高于「应用直连 Nacos、控制台只做监控」。中小型环境通常 不必 做本节改造。

7. 附录：客户端 WritableDataSource 写回 Nacos（了解即可）

网上另一种常见做法是 不改 Dashboard，而在客户端注册 写数据源：Dashboard（默认 V1）把规则推到客户端内存后，Sentinel transport 模块回调 WritableDataSource.write()，由客户端把规则 反写 到 Nacos。

1
2
3
4
5
6
7

Dashboard（V1 默认）
    │  API 推送到客户端内存
    ▼
WritableDataSource.write()  →  Nacos publishConfig
    ▲
    │  Nacos 监听（spring.cloud.sentinel.datasource）
客户端内存 ←────────────────┘

官方 FileDataSourceInit 演示的就是这个钩子——只不过写的是 本地文件，不是 Nacos：

1
2
3
4
5
6
7

// 读：注册到 RuleManager（Push 模式常规做法）
ReadableDataSource<String, List<FlowRule>> ds = new NacosDataSource<>(serverAddr, groupId, dataId, parser);
FlowRuleManager.register2Property(ds.getProperty());

// 写：Dashboard 推送后回调；社区常自实现 NacosWritableDataSource
WritableDataSource<List<FlowRule>> wds = new NacosWritableDataSource<>(serverAddr, groupId, dataId, JSON::toJSONString);
WritableDataSourceRegistry.registerFlowDataSource(wds);

注意：sentinel-datasource-nacos 1.8.9 官方只有 NacosDataSource（只读），没有 NacosWritableDataSource；网上教程里的写 Nacos 实现多为 社区自写（在 write() 里调 configService.publishConfig()），或通过 InitFunc / @PostConstruct 注册到 WritableDataSourceRegistry。

与上文 6.2 Dashboard 改造 对比：

适用场景：单机联调、不想改 Dashboard 源码 时可了解此路；生产多实例仍建议走 6.2 Dashboard 改造，或更简单——只在 Nacos 维护规则（上文第五节 Push 模式），Dashboard 仅做监控。

六、联调检查清单

常见问题：

1. 控制台无应用：需真实流量触发一次资源；检查 spring.cloud.sentinel.transport.dashboard 指向与 Dashboard 实际端口一致。

2. 端口冲突：与 Nacos 3.x 同机时，勿再占用 8080；本文默认使用 8858。

3. Nacos 规则不生效：核对 data-id / group-id / namespace / 账号密码；rule-type 与配置内容类型一致；看应用日志是否有 datasource 转换失败。

4. 控制台改了规则，重启又没了：未接 Nacos，或未把 Dashboard 改成写回 Nacos；请以 Nacos 为准。

5. 版本混用：按 SCA 官方矩阵固定 Sentinel 1.8.9 最省事。

七、参考链接

• Spring Cloud Alibaba 版本发布说明（2025.x）

• SCA · Sentinel 快速开始

• SCA · Sentinel 进阶指南（客户端支持 / 动态数据源）

• Sentinel Wiki · 如何使用（各规则字段）

• Sentinel Wiki · 热点参数限流

• Sentinel Wiki · 网关限流

• Sentinel · 动态规则扩展

• Sentinel · 在生产环境中使用 Sentinel（Push / Pull / WritableDataSource）

• Sentinel v1.8.9 Release

• Sentinel Wiki · Dashboard

• Sentinel Dashboard · Nacos 规则样例（1.8.9 / src/test）

• Spring Cloud Alibaba 2025.0.0.0 配套搭建 Nacos 3.0.3

摘要

• 依据 Spring Cloud Alibaba 版本发布说明，搭建与 Spring Cloud Alibaba 2025.0.0.0 对应的 Nacos Server 3.0.3。

• 覆盖服务端单机搭建（二进制包 + Docker）、MySQL 外置持久化、多节点集群，并补充 Spring Boot 应用侧的最小接入配置。

• 同版本配套的 Sentinel Dashboard 见 Spring Cloud Alibaba 2025.0.0.0 配套搭建 Sentinel Dashboard 1.8.9。

一、版本对照

1. Spring Cloud Alibaba 2025.0.x 适配关系

摘自官方 版本发布说明：

同页「组件版本关系」中，与 2025.0.0.0 对应的 Nacos 版本为：

对比：同属 2025.x 的 2025.1.0.0 适配 Spring Boot 4.0 / Spring Cloud 2025.1，组件为 Nacos 3.1.1。若走 Boot 4 路线请勿混用本文 Nacos 版本。

2. 环境准备

端口规划：

二、搭建 Nacos 3.0.3

官方文档：Nacos 快速开始、Docker 快速开始。

1. 方式一：二进制包单机启动（推荐先理解流程）

（1）下载

1
2
3
4
5
6
7
8
9
10

# 任选其一
# 官网下载页：https://nacos.io/download/nacos-server/
wget https://download.nacos.io/nacos-server/nacos-server-3.0.3.zip
unzip nacos-server-3.0.3.zip

# GitHub Release：https://github.com/alibaba/nacos/releases/tag/3.0.3
wget https://github.com/alibaba/nacos/releases/download/3.0.3/nacos-server-3.0.3.tar.gz
tar -zxvf nacos-server-3.0.3.tar.gz

cd nacos

（2）生成鉴权相关配置

三个参数均无官方默认值，需自行生成并固定保存（集群节点必须一致）：

示例生成方式：

1
2
3
4
5
6
7
8
9
10
11

# JWT 密钥：先生成 ≥32 字符明文，再 Base64
openssl rand -base64 32
# 3kphyB8N/h/7NHvoXdvM7hwfCsnpBXK+1nlruWb2gUQ=
openssl rand -base64 48
# PZhCxx3Rj5Z3GZ59tBkxSElxHCKPMTEtInHiJSVqUnz435/H2iwY3buSEX0DFQ6j

# identity key / value 可用任意自定义字符串，例如：
echo -n 'nacos_identity_key' | base64
# bmFjb3NfaWRlbnRpdHlfa2V5
echo -n 'nacos_identity_value' | base64
# bmFjb3NfaWRlbnRpdHlfdmFsdWU=

也可在首次执行 startup.sh -m standalone 时按提示交互填入，
填入后会写入 conf/application.properties。
但建议直接修改配置文件，因为 base64 生成的编码可能含有特殊字符导致配置失败。

手动写入示例（请替换为你自己的值）：

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

### conf/application.properties 片段
# 使用“内置的 Nacos 原生鉴权体系”，默认 nacos，还支持 ldap
nacos.core.auth.system.type=nacos


# 总开关，是否开启 Nacos 服务端 API 的鉴权系统，默认为 false（当前值）：表示关闭鉴权。
# 此时任何人无需用户名密码即可通过 Open API 访问、修改 Nacos 上的配置和服务列表。这在生产环境是极不安全的。
nacos.core.auth.enabled=true
# 是否开启 Nacos 管理 API 的鉴权，默认为true
nacos.core.auth.admin.enabled=true
# 是否开启 Nacos 控制台（Web UI）的鉴权，默认为true
nacos.core.auth.console.enabled=true


# 用于识别请求来源的身份键值对（白名单机制）
# 当 nacos.core.auth.enabled=true 时生效
# 如果请求的 Header 中包含 key=nacos_identity_key 且 value=nacos_identity_value，Nacos 会认为这是一个受信任的内部服务器请求（例如通过 Nginx 代理转发的请求，或者 Nacos 集群节点间的通信），从而跳过常规的用户 Token 鉴权。
# 在生产环境中，必须修改这两个默认值，防止被恶意利用绕过鉴权。
nacos.core.auth.server.identity.key=替换为你的identityKey
nacos.core.auth.server.identity.value=替换为你的identityValue


# 用于生成 Token 的密钥（Base64 编码的字符串）
# Nacos 使用 JWT (JSON Web Token) 机制，该密钥用于签名和验证 Token。
# 在生产环境中，必须将其设置为一个复杂的、唯一的 Base64 字符串，并确保所有 Nacos 节点使用相同的密钥（集群模式下）
nacos.core.auth.plugin.nacos.token.secret.key=替换为你的Base64密钥

（3）修改端口（可选）

Nacos 3.x 已把 Server API 与 控制台 拆成两个独立 HTTP 端口。改端口时请使用下面专用配置，不要再写 server.port（它是 Spring Boot 全局 HTTP 端口，容易让 Server 与控制台抢同一端口而启动失败）。参见 系统参数。

conf/application.properties 示例（把主端口改成 8849、控制台改成 8081）：

1
2

nacos.server.main.port=8849
nacos.console.port=8081

改完后实际端口变为：

客户端 spring.cloud.nacos.server-addr 只填主端口即可，例如 127.0.0.1:8849；gRPC 端口由客户端按同样偏移规则自动推算。

防火墙 / 安全组至少放行：控制台端口、主端口、客户端 gRPC（主端口+1000）。

（4）启动 / 停止

1
2
3
4
5
6
7
8
9
10
11

# Linux / macOS 单机模式
sh bin/startup.sh -m standalone
# Ubuntu 若 [[ 报错，改用：
# bash bin/startup.sh -m standalone

# 指定jdk环境，也可以将 JAVA_HOME 添加到 bin/startup.sh 中
JAVA_HOME=/usr/local/jvm/jdk17  \
  sh bin/startup.sh -m standalone

# 查看启动日志
tail -f logs/start.out

看到类似日志表示成功：

1

Nacos started successfully in stand alone mode. use embedded storage

停止：

1

sh bin/shutdown.sh

（5）验证

1. 浏览器打开：http://127.0.0.1:8080/index.html（若改过控制台端口则替换），按提示初始化 nacos 管理员密码。

2. 或用 API 首次初始化管理员密码（密码为空则会随机生成，务必保存）：

1
2

curl -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/admin' \
  -d 'password=YourStrongPassword'

1

{"code":409,"message":"have admin user cannot use it.","data":null}

1
2
3

curl -s -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  -d 'username=nacos' \
  -d 'password=当初初始化时设置的密码'

3. 服务注册 / 发现快速探测（v3 Client API）。

若已开启客户端鉴权（nacos.core.auth.enabled=true，报 401 User not found / 403 Forbidden 时就是这种情况），须先登录拿 accessToken：

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

# 登录（密码为你初始化的 nacos 管理员密码）
TOKEN=$(curl -s -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  -d 'username=nacos' \
  -d 'password=YourStrongPassword' | sed -n 's/.*"accessToken":"\([^"]*\)".*/\1/p')

echo "TOKEN=$TOKEN"

# 注册（Header 或 query 携带 accessToken 均可）
curl -X POST "http://127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=quickstart.test.service&ip=127.0.0.1&port=8080&accessToken=${TOKEN}"

# 发现
curl -X GET "http://127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=quickstart.test.service&accessToken=${TOKEN}"

未开启客户端鉴权时，可省略登录，直接调用无 accessToken 的 URL（官方快速开始示例即为此种情况）。

2. 方式二：Docker 单机（嵌入式 Derby）

官方镜像：nacos/nacos-server:v3.0.3。

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

export NACOS_AUTH_TOKEN="$(openssl rand -base64 48)"
export NACOS_AUTH_IDENTITY_KEY="nacos_identity_key"
export NACOS_AUTH_IDENTITY_VALUE="nacos_identity_value"

docker pull nacos/nacos-server:v3.0.3

docker run -d \
  --name nacos-standalone \
  -e MODE=standalone \
  -e NACOS_AUTH_TOKEN="${NACOS_AUTH_TOKEN}" \
  -e NACOS_AUTH_IDENTITY_KEY="${NACOS_AUTH_IDENTITY_KEY}" \
  -e NACOS_AUTH_IDENTITY_VALUE="${NACOS_AUTH_IDENTITY_VALUE}" \
  -e JVM_XMS=512m \
  -e JVM_XMX=512m \
  -p 8080:8080 \
  -p 8848:8848 \
  -p 9848:9848 \
  nacos/nacos-server:v3.0.3

若要改容器内端口，使用镜像环境变量（对应配置见上一节）：

示例：主端口 8849、控制台 8081（gRPC 随之变为 9849，映射要一起改）：

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

docker run -d \
  --name nacos-standalone \
  -e MODE=standalone \
  -e NACOS_APPLICATION_PORT=8849 \
  -e NACOS_CONSOLE_PORT=8081 \
  -e NACOS_AUTH_TOKEN="${NACOS_AUTH_TOKEN}" \
  -e NACOS_AUTH_IDENTITY_KEY="${NACOS_AUTH_IDENTITY_KEY}" \
  -e NACOS_AUTH_IDENTITY_VALUE="${NACOS_AUTH_IDENTITY_VALUE}" \
  -e JVM_XMS=512m \
  -e JVM_XMX=512m \
  -p 8081:8081 \
  -p 8849:8849 \
  -p 9849:9849 \
  nacos/nacos-server:v3.0.3

查看日志：

1

docker logs -f nacos-standalone

出现 Nacos started successfully ... 后，访问 http://127.0.0.1:8080/index.html 初始化管理员密码。

% note info %
低配机器务必限制 JVM，否则容易 OOM / 卡死。生产请改用外置 MySQL，详见下文「三、MySQL 持久化」。

% endnote %

3. Docker Compose 最小示例

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

# docker-compose-nacos.yml
services:
  nacos:
    image: nacos/nacos-server:v3.0.3
    container_name: nacos
    environment:
      MODE: standalone
      # 如需改端口，取消注释并同步改 ports 映射与 gRPC（主端口+1000）
      # NACOS_APPLICATION_PORT: 8849
      # NACOS_CONSOLE_PORT: 8081
      NACOS_AUTH_TOKEN: ${NACOS_AUTH_TOKEN}
      NACOS_AUTH_IDENTITY_KEY: ${NACOS_AUTH_IDENTITY_KEY}
      NACOS_AUTH_IDENTITY_VALUE: ${NACOS_AUTH_IDENTITY_VALUE}
      JVM_XMS: 512m
      JVM_XMX: 512m
      TZ: Asia/Shanghai
    ports:
      - "8080:8080"
      - "8848:8848"
      - "9848:9848"
    restart: unless-stopped

1
2
3
4
5

export NACOS_AUTH_TOKEN="$(openssl rand -base64 32)"
export NACOS_AUTH_IDENTITY_KEY="nacos_identity_key"
export NACOS_AUTH_IDENTITY_VALUE="nacos_identity_value"

docker compose -f docker-compose-nacos.yml up -d

三、MySQL 持久化

单机快速体验可用嵌入式 Derby；配置中心数据、用户权限等需要跨重启保活，或后续要做集群时，必须切换外置 MySQL。官方部署说明：单机模式部署、集群模式部署。

1. 准备数据库

1. MySQL 5.6.5+（建议 8.0），字符集建议 utf8mb4。

2. 创建库与账号（密码请自行替换）：

1
2
3
4
5

CREATE DATABASE nacos DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'nacos'@'%' IDENTIFIED BY 'Nacos_Db_Passw0rd';
GRANT ALL PRIVILEGES ON nacos.* TO 'nacos'@'%';
FLUSH PRIVILEGES;

3. 导入官方表结构（发行包内 conf/mysql-schema.sql，或从 Nacos 源码 conf 下载同版本脚本）：

1
2

# 在 nacos 解压目录执行
mysql -h127.0.0.1 -P3306 -unacos -p nacos < conf/mysql-schema.sql

2. 二进制包：改配置后单机启动

编辑 conf/application.properties，取消 / 补充 MySQL 相关项（示例）：

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

### 使用 MySQL 数据源（与 3.0.3 发行包 conf/application.properties 一致）
spring.sql.init.platform=mysql

db.num=1
db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
db.user=nacos
db.password=Nacos_Db_Passw0rd

### 鉴权（与第二节一致，必须已配置）
nacos.core.auth.enabled=true
nacos.core.auth.system.type=nacos
nacos.core.auth.plugin.nacos.token.secret.key=替换为你的Base64密钥
nacos.core.auth.server.identity.key=替换为你的identityKey
nacos.core.auth.server.identity.value=替换为你的identityValue

启动方式与单机 Derby 相同：

1

sh bin/startup.sh -m standalone

成功时日志类似：

1

Nacos started successfully in stand alone mode. use external storage

对比 Derby 时的 use embedded storage，若仍显示 embedded，说明 MySQL 配置未生效。

3. Docker：单机 + 外置 / Compose 内置 MySQL

（1）连接已有 MySQL

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

docker run -d \
  --name nacos-standalone-mysql \
  -e MODE=standalone \
  -e SPRING_DATASOURCE_PLATFORM=mysql \
  -e MYSQL_SERVICE_HOST=192.168.1.10 \
  -e MYSQL_SERVICE_PORT=3306 \
  -e MYSQL_SERVICE_DB_NAME=nacos \
  -e MYSQL_SERVICE_USER=nacos \
  -e MYSQL_SERVICE_PASSWORD=Nacos_Db_Passw0rd \
  -e MYSQL_SERVICE_DB_PARAM='characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true' \
  -e NACOS_AUTH_TOKEN="${NACOS_AUTH_TOKEN}" \
  -e NACOS_AUTH_IDENTITY_KEY="${NACOS_AUTH_IDENTITY_KEY}" \
  -e NACOS_AUTH_IDENTITY_VALUE="${NACOS_AUTH_IDENTITY_VALUE}" \
  -e JVM_XMS=512m \
  -e JVM_XMX=512m \
  -p 8080:8080 \
  -p 8848:8848 \
  -p 9848:9848 \
  nacos/nacos-server:v3.0.3

容器启动前请已在目标库执行过 mysql-schema.sql。

（2）Docker Compose 一键（Nacos + MySQL）

也可直接参考 nacos-docker 的 example/standalone-mysql.yaml（版本在 .env 固定为 v3.0.3，并先跑 mysql-init.sh 准备初始化脚本）。自写最小示例如下：

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# docker-compose-nacos-mysql.yml
services:
  mysql:
    image: mysql:8.0.30
    container_name: nacos-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: nacos
      MYSQL_USER: nacos
      MYSQL_PASSWORD: Nacos_Db_Passw0rd
      TZ: Asia/Shanghai
    volumes:
      # 将 mysql-schema.sql 放到 ./mysql-init/ 下，首次启动自动导入
      - ./mysql-init:/docker-entrypoint-initdb.d
      - nacos-mysql-data:/var/lib/mysql
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 10s
      retries: 10
    restart: unless-stopped

  nacos:
    image: nacos/nacos-server:v3.0.3
    container_name: nacos
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      MODE: standalone
      SPRING_DATASOURCE_PLATFORM: mysql
      MYSQL_SERVICE_HOST: mysql
      MYSQL_SERVICE_PORT: 3306
      MYSQL_SERVICE_DB_NAME: nacos
      MYSQL_SERVICE_USER: nacos
      MYSQL_SERVICE_PASSWORD: Nacos_Db_Passw0rd
      MYSQL_SERVICE_DB_PARAM: characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
      NACOS_AUTH_TOKEN: ${NACOS_AUTH_TOKEN}
      NACOS_AUTH_IDENTITY_KEY: ${NACOS_AUTH_IDENTITY_KEY}
      NACOS_AUTH_IDENTITY_VALUE: ${NACOS_AUTH_IDENTITY_VALUE}
      JVM_XMS: 512m
      JVM_XMX: 512m
      TZ: Asia/Shanghai
    ports:
      - "8080:8080"
      - "8848:8848"
      - "9848:9848"
    restart: unless-stopped

volumes:
  nacos-mysql-data:

1
2
3
4
5
6
7
8
9

mkdir -p mysql-init
# 从发行包拷贝同版本脚本
cp /path/to/nacos/conf/mysql-schema.sql mysql-init/

export NACOS_AUTH_TOKEN="$(openssl rand -base64 32)"
export NACOS_AUTH_IDENTITY_KEY="nacos_identity_key"
export NACOS_AUTH_IDENTITY_VALUE="nacos_identity_value"

docker compose -f docker-compose-nacos-mysql.yml up -d

常见问题：

1. Public Key Retrieval is not allowed：JDBC URL / MYSQL_SERVICE_DB_PARAM 追加 allowPublicKeyRetrieval=true。

2. db.num is null / 连不上库：确认 spring.sql.init.platform=mysql（或环境变量 SPRING_DATASOURCE_PLATFORM=mysql）及 db.* 完整。

3. 重启后数据仍丢：可能仍跑在 Derby，或 MySQL volume 未挂载成功。

四、集群搭建

生产推荐：≥ 3 个 Nacos 节点 + 外置 MySQL（建议高可用）+ 域名 / 内网 SLB 对外暴露主端口与客户端 gRPC。直连任意单节点 IP 也可工作，但节点故障后客户端需改配置，运维成本更高。架构说明见 集群模式部署。

1. 二进制包三节点示例

假设三台机器（或同机不同端口，演示时可改；生产请每机一进程）：

（1）各节点统一 application.properties

在上一节 MySQL 配置基础上，保证三台鉴权参数相同，并按需指定本机地址（多网卡时尤其重要）：

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

### 多网卡时可固定对外 IP，避免注册成错误网卡
# nacos.inetutils.ip-address=192.168.1.11

spring.sql.init.platform=mysql
db.num=1
db.url.0=jdbc:mysql://192.168.1.10:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
db.user=nacos
db.password=Nacos_Db_Passw0rd

nacos.core.auth.enabled=true
nacos.core.auth.console.enabled=true
nacos.core.auth.system.type=nacos
nacos.core.auth.plugin.nacos.token.secret.key=替换为你的Base64密钥
nacos.core.auth.server.identity.key=替换为你的identityKey
nacos.core.auth.server.identity.value=替换为你的identityValue

（2）各节点相同的 conf/cluster.conf

三台机器内容一致，每行 ip:主端口：

1
2
3
4

# conf/cluster.conf
192.168.1.11:8848
192.168.1.12:8848
192.168.1.13:8848

（3）启动与验证

每台分别执行（集群模式，无 -m standalone）：

1
2

sh bin/startup.sh
# Ubuntu：bash bin/startup.sh

成功日志类似：

1

Nacos started successfully in cluster mode. use external storage

任选一台控制台（或经 SLB）打开：http://任意节点控制台端口/index.html。管理员密码只需初始化一次（数据在 MySQL）。

控制台「集群管理」应能看到 3 个节点；也可用健康检查 / 成员列表 API（需先登录拿 token，方式同第二节）。

客户端 server-addr 可填：

1
2
3
4
5
6
7

spring:
  cloud:
    nacos:
      # 推荐：VIP / 域名（内网 SLB 同时转发 8848 与 9848）
      server-addr: nacos.example.internal:8848
      # 或直连多地址（逗号分隔）
      # server-addr: 192.168.1.11:8848,192.168.1.12:8848,192.168.1.13:8848

% note tip %
若前面挂了四层负载或 Nginx，8848 与 9848 都要转发且保持「主端口 +1000 = gRPC」的偏移。只转 8848、不转 gRPC，或把 gRPC 配成 HTTP/HTTP2，会出现注册失败或频繁超时。完整示例见下文「Nginx 反向代理」。

% endnote %

2. Docker Compose 集群示例（hostname 模式）

官方示例：nacos-docker example/cluster-hostname.yaml。核心环境变量：

自写精简示例如下（生产请将 MySQL 换为外部高可用库，并收紧密码）：

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

# docker-compose-nacos-cluster.yml
services:
  mysql:
    image: mysql:8.0.30
    container_name: nacos-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: nacos
      MYSQL_USER: nacos
      MYSQL_PASSWORD: Nacos_Db_Passw0rd
    volumes:
      - ./mysql-init:/docker-entrypoint-initdb.d
      - nacos-mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 10s
      retries: 10
    restart: unless-stopped

  nacos1: &nacos-node
    image: nacos/nacos-server:v3.0.3
    hostname: nacos1
    container_name: nacos1
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      PREFER_HOST_MODE: hostname
      NACOS_SERVERS: nacos1:8848 nacos2:8848 nacos3:8848
      SPRING_DATASOURCE_PLATFORM: mysql
      MYSQL_SERVICE_HOST: mysql
      MYSQL_SERVICE_PORT: 3306
      MYSQL_SERVICE_DB_NAME: nacos
      MYSQL_SERVICE_USER: nacos
      MYSQL_SERVICE_PASSWORD: Nacos_Db_Passw0rd
      MYSQL_SERVICE_DB_PARAM: characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
      NACOS_AUTH_TOKEN: ${NACOS_AUTH_TOKEN}
      NACOS_AUTH_IDENTITY_KEY: ${NACOS_AUTH_IDENTITY_KEY}
      NACOS_AUTH_IDENTITY_VALUE: ${NACOS_AUTH_IDENTITY_VALUE}
      JVM_XMS: 512m
      JVM_XMX: 512m
      TZ: Asia/Shanghai
    ports:
      - "8080:8080"
      - "8848:8848"
      - "9848:9848"
    restart: unless-stopped

  nacos2:
    <<: *nacos-node
    hostname: nacos2
    container_name: nacos2
    ports:
      - "8081:8080"
      - "8849:8848"
      - "9849:9848"

  nacos3:
    <<: *nacos-node
    hostname: nacos3
    container_name: nacos3
    ports:
      - "8082:8080"
      - "8850:8848"
      - "9850:9848"

volumes:
  nacos-mysql-data:

1
2
3
4
5
6
7
8
9

mkdir -p mysql-init
cp /path/to/nacos/conf/mysql-schema.sql mysql-init/

export NACOS_AUTH_TOKEN="$(openssl rand -base64 32)"
export NACOS_AUTH_IDENTITY_KEY="nacos_identity_key"
export NACOS_AUTH_IDENTITY_VALUE="nacos_identity_value"

docker compose -f docker-compose-nacos-cluster.yml up -d
docker compose -f docker-compose-nacos-cluster.yml logs -f nacos1

本机快速验证时，应用可临时连 127.0.0.1:8848（或逗号列出 8848,8849,8850）。真实环境仍建议用域名 / SLB / Nginx 统一入口。

3. Nginx 反向代理示例

官方说明：部署架构概览、Nginx 负载均衡指南。

对外建议暴露：

不要把 gRPC 配成 http / http2 反代，否则连接会被掐断，表现为服务反复上下线。节点间端口 9849、7848 仅内网互通，勿对公网开放。

先确认 Nginx 带 stream 模块：

1
2

nginx -V 2>&1 | tr ' ' '\n' | grep -E 'stream'
# 应能看到 --with-stream

（1）推荐：保持默认端口偏移（客户端无感）

server-addr 填 nacos.example.com:8848 时，客户端会自动连 nacos.example.com:9848，因此 Nginx 对外监听端口也必须满足同一偏移：

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# /etc/nginx/nginx.conf 片段（stream 必须与 http 同级，不能写在 http {} 里）

worker_processes auto;

events {
    worker_connections 10240;
}

# ---------- gRPC：四层 TCP 反代 ----------
stream {
    upstream nacos_grpc {
        # 可选：按客户端 IP 粘滞，减少长连接漂移
        hash $remote_addr consistent;
        server 192.168.1.11:9848 max_fails=3 fail_timeout=30s;
        server 192.168.1.12:9848 max_fails=3 fail_timeout=30s;
        server 192.168.1.13:9848 max_fails=3 fail_timeout=30s;
    }

    server {
        listen 9848;
        proxy_pass nacos_grpc;
        proxy_connect_timeout 10s;
        # gRPC 长连接，超时宜设大一些
        proxy_timeout 300s;
        proxy_next_upstream on;
    }
}

# ---------- HTTP：API + 控制台 ----------
http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout 65;
    # 配置内容可能较大
    client_max_body_size 20m;

    upstream nacos_api {
        server 192.168.1.11:8848 max_fails=3 fail_timeout=30s;
        server 192.168.1.12:8848 max_fails=3 fail_timeout=30s;
        server 192.168.1.13:8848 max_fails=3 fail_timeout=30s;
    }

    upstream nacos_console {
        server 192.168.1.11:8080 max_fails=3 fail_timeout=30s;
        server 192.168.1.12:8080 max_fails=3 fail_timeout=30s;
        server 192.168.1.13:8080 max_fails=3 fail_timeout=30s;
    }

    # 客户端 / OpenAPI：http://nacos.example.com:8848
    server {
        listen 8848;
        server_name nacos.example.com;

        location / {
            proxy_pass http://nacos_api;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_connect_timeout 5s;
            proxy_read_timeout 60s;
            proxy_send_timeout 60s;
        }

        # 可选：简单探活
        location = /nacos/v3/console/health/readiness {
            proxy_pass http://nacos_api;
            access_log off;
        }
    }

    # 控制台：http://nacos-console.example.com:8080/index.html
    server {
        listen 8080;
        server_name nacos-console.example.com;

        location / {
            proxy_pass http://nacos_console;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            # 控制台前端资源 / 接口
            proxy_connect_timeout 5s;
            proxy_read_timeout 60s;
        }
    }
}

检查并热加载：

1

nginx -t && nginx -s reload

应用侧只填 Nginx 入口：

1
2
3
4
5
6

spring:
  cloud:
    nacos:
      server-addr: nacos.example.com:8848
      username: nacos
      password: YourStrongPassword

浏览器访问控制台：http://nacos-console.example.com:8080/index.html。

（2）自定义对外端口时：仍须保持 +1000 偏移

若希望对外用 7847（HTTP）而不想占用 8848，则 gRPC 必须对外监听 8847（= 7847 + 1000），客户端才能算出正确端口：

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
34
35
36
37
38
39
40
41
42
43
44
45
46

stream {
    upstream nacos_grpc {
        server 192.168.1.11:9848;
        server 192.168.1.12:9848;
        server 192.168.1.13:9848;
    }
    server {
        listen 8847;          # = 对外主端口 + 1000
        proxy_pass nacos_grpc;
        proxy_timeout 300s;
    }
}

http {
    upstream nacos_api {
        server 192.168.1.11:8848;
        server 192.168.1.12:8848;
        server 192.168.1.13:8848;
    }
    upstream nacos_console {
        server 192.168.1.11:8080;
        server 192.168.1.12:8080;
        server 192.168.1.13:8080;
    }

    # 对外主端口 7847：可同时按路径拆 API 与控制台（官方指南同思路）
    server {
        listen 7847;
        server_name nacos.example.com;

        location /nacos/ {
            proxy_pass http://nacos_api/nacos/;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }

        # Nacos 3.x 控制台路径无 /nacos 前缀
        location / {
            proxy_pass http://nacos_console;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
    }
}

此时客户端：

1

spring.cloud.nacos.server-addr: nacos.example.com:7847

控制台：http://nacos.example.com:7847/index.html。

（3）HTTPS 控制台（可选）

仅给控制台上证书即可；客户端注册发现一般仍走内网明文 8848/9848。证书终止在 Nginx，后端继续 http://nacos_console。

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

server {
    listen 443 ssl http2;
    server_name nacos-console.example.com;

    ssl_certificate     /etc/nginx/certs/nacos-console.crt;
    ssl_certificate_key /etc/nginx/certs/nacos-console.key;

    location / {
        proxy_pass http://nacos_console;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

（4）Nginx 相关注意点

1. stream 与 http 同级：写在 http {} 内会直接报错。

2. 偏移不能破：对外 主端口 与 主端口+1000 必须成对出现。

3. 单机也可用同一套配置：upstream 里只留一个 server 即可。

4. 扩容：新增节点后改 Nginx upstream 再 nginx -s reload，应用无需改 server-addr。

5. 安全：生产尽量内网暴露 8848/9848；控制台可单独域名 + HTTPS + IP 白名单。

4. 集群常见问题

1. 节点无法互相发现：检查 cluster.conf / NACOS_SERVERS 是否互通；防火墙是否放行 8848/9848/9849/7848。

2. 鉴权不一致导致节点异常：三件套任一不一致都会出问题，务必三台拷贝同一份配置。

3. 多网卡注册成内网错误 IP：设置 nacos.inetutils.ip-address 或 Docker 的 NACOS_SERVER_IP。

4. 只用 2 节点：偶数节点在半数故障时易无法选主，生产请用奇数台（≥3）。

5. Nginx 后客户端连不上 / 反复掉线：检查是否遗漏 9848 的 stream TCP 转发，或误用了 HTTP2；对外端口是否满足「主端口 +1000」。

五、应用侧快速接入（SCA 2025.0.0.0）

官方指南：SCA · Nacos 快速开始。

1. BOM 与依赖

父 POM / 依赖管理：

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

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2025.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>com.alibaba.cloud</groupId>
      <artifactId>spring-cloud-alibaba-dependencies</artifactId>
      <version>2025.0.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

业务模块按需引入（版本由 BOM 管理）：

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

<!-- 注册发现 -->
<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>

<!-- 服务间调用负载均衡（消费端常用） -->
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

Starter 会传递依赖 nacos-client:3.0.3，与上文服务端版本对齐。

2. application.yml 示例

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

server:
  port: 18082

spring:
  application:
    name: demo-provider
  config:
    import:
      - optional:nacos:demo-provider.properties?refreshEnabled=true
  cloud:
    nacos:
      server-addr: 127.0.0.1:8848
      username: nacos
      password: YourStrongPassword
      discovery:
        server-addr: ${spring.cloud.nacos.server-addr}
      config:
        server-addr: ${spring.cloud.nacos.server-addr}
        file-extension: properties

% note tip %
2025.0.x 起建议统一使用 spring.config.import 拉取 Nacos 配置；shared-configs / extension-configs 等旧方式已废弃。更靠后的 2025.1.x 会正式废弃 Bootstrap，接入时直接写在 application.yml 即可。

% endnote %

3. 代码最小示例

1
2
3
4
5
6
7

@SpringBootApplication
@EnableDiscoveryClient
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

六、联调检查清单

常见问题：

1. 应用连不上 Nacos：除了 8848，还必须打通 9848（gRPC）；经 Nginx / SLB 时两条链路都要转，且保持主端口 +1000 偏移。

2. 控制台 404 / 打不开：Nacos 3.x 用 8080，不要再用 8848/nacos。

3. 外网 IP 打不开控制台：本机 curl 正常且监听 *:8080 时，多半是云安全组未放行控制台端口；与 nacos.inetutils.ip-address 无关。

4. 重启后配置丢失：仍在用 Derby，或未导入 / 未指向 MySQL。

5. 集群某节点起不来：核对 cluster.conf、鉴权三件套一致性、数据库连通性。

6. 经 Nginx 后服务反复上下线：常因 gRPC 用了 HTTP/HTTP2 反代；应改为 stream TCP，并把 proxy_timeout 调大。

7. 版本混用：按 SCA 官方矩阵固定 Nacos 3.0.3 最省事。

七、参考链接

• Spring Cloud Alibaba 版本发布说明（2025.x）

• SCA · Nacos 快速开始

• Nacos 3.0 快速开始

• Nacos Docker 快速开始

• Nacos 单机模式部署

• Nacos 集群模式部署

• Nacos 部署架构概览（含 VIP/Nginx 注意点）

• Nacos 集群 Nginx 负载均衡指南

• Nacos 权限校验（3.0）

• Nacos 系统参数（含端口）

• mysql-schema.sql（3.0.3）

• nacos-docker

• Spring Cloud Alibaba 2025.0.0.0 配套搭建 Sentinel Dashboard 1.8.9