以下是从Nacos 3.x服务部署到Spring Boot项目双配置文件编写的完整可落地方案，包含所有关键配置、避坑点和验证步骤，直接复刻即可完成整套环境搭建。

一、前置环境确认

技术栈 版本要求 核心说明
JDK 21 必须使用21+版本，支持虚拟线程
Spring Boot 3.2.x+ 适配Jakarta EE规范、JDK21
Spring Cloud Alibaba 2025.0.0.0+ 适配Nacos 3.x客户端
Nacos Server 3.1.1（稳定版） 禁止使用latest避免兼容性问题
MySQL 8.0+ Nacos 3.x外置存储必选

二、Nacos 3.x 单机部署（Docker Compose）

2.1 初始化MySQL数据库

  1. 创建数据库&用户（替换自定义密码）：
CREATE DATABASE IF NOT EXISTS nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER IF NOT EXISTS 'nacos'@'%' IDENTIFIED BY 'Nacos@123456';
GRANT ALL PRIVILEGES ON nacos_config.* TO 'nacos'@'%';
FLUSH PRIVILEGES;
  1. 执行Nacos 3.1.1官方初始化脚本，补全3.x专属表结构。

2.2 Docker Compose配置文件

创建/opt/nacos/docker-compose.yml：

version: '3.8'
services:
  nacos:
    image: nacos/nacos-server:v3.1.1
    container_name: nacos-3.1.1
    restart: always
    privileged: true
    environment:
      - MODE=standalone
      # 端口配置（3.x核心变更）
      - NACOS_SERVER_PORT=8848  # 客户端SDK通信端口
      - SERVER_PORT=8080        # 控制台Web端口
      - SERVER_SERVLET_CONTEXT_PATH=/
      # JVM内存（3.x最低1G）
      - JVM_XMS=1024m
      - JVM_XMX=1024m
      - JVM_XMN=512m
      # MySQL连接（替换为你的MySQL地址）
      - SPRING_DATASOURCE_PLATFORM=mysql
      - MYSQL_SERVICE_HOST=192.168.1.100
      - MYSQL_SERVICE_PORT=3306
      - MYSQL_SERVICE_DB_NAME=nacos_config
      - MYSQL_SERVICE_USER=nacos
      - MYSQL_SERVICE_PASSWORD=Nacos@123456
      - MYSQL_SERVICE_DB_PARAM=characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
      # 鉴权配置（3.x必填）
      - NACOS_AUTH_ENABLE=true
      - NACOS_AUTH_TOKEN=U2VjcmV0S2V5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5
      - NACOS_AUTH_IDENTITY_KEY=ServerIdentityKey0123
      - NACOS_AUTH_IDENTITY_VALUE=ServerIdentityValue456789
      # 关闭自动迁移（避坑）
      - NACOS_CONFIG_MIGRATE_ENABLE=false
    ports:
      - "8080:8080"   # 控制台
      - "8848:8848"   # 客户端
      - "8849:8849"
      - "9848:9848"
      - "9849:9849"
      - "9850:9850"
    volumes:
      - ./logs:/home/nacos/logs
      - ./data:/home/nacos/data
    networks:
      - nacos-network

networks:
  nacos-network:
    driver: bridge

2.3 启动Nacos

# 后台启动容器
docker-compose up -d

# 查看容器状态（STATUS为Up则启动中）
docker-compose ps

# 实时查看日志（核心：排查启动失败）
docker-compose logs -f nacos
# 成功标识：Nacos started successfully in standalone mode. use external storage

2.4 Nacos控制台创建配置

访问http://服务器IP::8080/index.html（账号nacos/nacos），创建配置：

  • Data ID：jdk21-dev.yaml
  • Group：DEFAULT_GROUP
  • 配置格式：YAML
  • 配置内容（示例）：
# 远程配置可覆盖本地配置
server:
  port: 8081
spring:
  cloud:
    nacos:
      discovery:
        enabled: true
# 自定义业务配置
app:
  name: jdk21-demo
  env: dev

三、Spring Boot项目完整配置

3.1 核心依赖（pom.xml）

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>jdk21-nacos-demo</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <spring-cloud-alibaba.version>2025.0.0.0</spring-cloud-alibaba.version>
        <spring-cloud.version>2024.0.0</spring-cloud.version>
    </properties>

    <dependencies>
        <!-- Spring Boot核心依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!-- Spring Cloud Alibaba Nacos -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>

        <!-- 接口文档（Knife4j + SpringDoc） -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.4.0</version>
        </dependency>

        <!-- 测试依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${project.parent.version}</version>
            </plugin>
        </plugins>
    </build>
</project>

3.2 application.yml（本地业务配置）

创建src/main/resources/application.yml：

# 本地基础配置（可被Nacos远程配置覆盖）
server:
  port: 8081

spring:
  application:
    name: jdk21
  profiles:
    active: test
  config:
    import:
      # 导入环境专属配置（jdk21-test.yaml）
      - "optional:nacos:${spring.application.name}-${spring.profiles.active}.yaml"
      # 导入共享配置（jdk21.yaml）
      - "optional:nacos:${spring.application.name}.yaml"
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/cloud_user?useSSL=false&serverTimezone=Asia/Shanghai&allowMultiQueries=true&allowPublicKeyRetrieval=true&characterEncoding=utf-8&rewriteBatchedStatements=true
    username: root
    password: root
  threads:
    virtual:
      enabled: true
  cloud:
    nacos:
      # 全局地址配置
      server-addr: localhost:8848
      username: nacos
      password: nacos
      # 配置中心设置
      config:
        group: DEFAULT_GROUP
        file-extension: yaml
      # 服务发现设置
      discovery:
        group: DEFAULT_GROUP

# MyBatis-Plus 配置
mybatis-plus:
  mapper-locations: classpath:mapper/*/*.xml
  configuration:
    #    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    log-impl: org.apache.ibatis.logging.nologging.NoLoggingImpl
  global-config:
    db-config:
      where-strategy: not_empty
      update-strategy: not_empty
      insert-strategy: not_empty

# Knife4j / SpringDoc 配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs
  show-actuator: true

knife4j:
  enable: true
  setting:
    language: zh_cn

3.3 启动类

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

/**
 * 启动类：开启服务发现（Nacos）
 */
@SpringBootApplication
@EnableDiscoveryClient  // 启用Nacos服务注册发现
public class Jdk21NacosDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(Jdk21NacosDemoApplication.class, args);
    }
}

四、验证方案（确保全流程生效）

4.1 服务启动验证

  1. 启动Spring Boot项目，日志中出现以下内容表示Nacos配置拉取成功：
Fetching config from server at : http://localhost:8848
Located environment: name=jdk21, profiles=[dev], label=null, version=xxx, state=normal
Loaded nacos config: dataId='jdk21-dev.yaml', group='DEFAULT_GROUP'
  1. 访问http://localhost:8081/doc.html，能正常打开接口文档表示本地配置生效。

4.2 Nacos服务注册验证

  1. 登录Nacos控制台（http://localhost:8080/index.html）；
  2. 进入「服务管理→服务列表」，能看到jdk21服务实例，表示服务注册成功。

4.3 远程配置覆盖验证

  1. 在Nacos控制台修改jdk21-dev.yaml的server.port为8082；
  2. 重启Spring Boot项目，服务会启动在8082端口，表示远程配置覆盖本地配置生效。

五、核心避坑总结

  1. 端口冲突：Spring Boot服务端口避开8080（Nacos控制台）、8848（Nacos客户端）；
  2. bootstrap依赖：Spring Boot3.x必须添加spring-cloud-starter-bootstrap，否则bootstrap.yml不生效；
  3. Nacos鉴权：3.x开启鉴权后，项目配置必须填username/password，否则403；
  4. Data ID匹配：${spring.application.name}-${spring.profiles.active}.yaml必须和Nacos控制台的Data ID完全一致；
  5. JVM内存：Nacos 3.x单机JVM内存最低1024m，否则启动OOM；
  6. 虚拟线程：JDK21+Spring Boot3.x才能开启spring.threads.virtual.enabled，低版本会报错。

六、生产环境优化建议

  1. Nacos鉴权：修改默认账号密码，生成自定义Base64的NACOS_AUTH_TOKEN；
  2. 配置加密：Nacos控制台开启配置加密，敏感配置（如数据库密码）加密存储；
  3. 日志配置：添加logback.xml，配置日志滚动，避免日志占满磁盘；
  4. 健康检查：通过Actuator监控端点（/actuator/health）监控服务状态；
  5. 配置热更新：Nacos配置修改后，项目无需重启，通过@RefreshScope实现配置热更新。
# mysql # java
Logo
腾讯云开发者社区

腾讯云面向开发者汇聚海量精品云计算使用和开发经验，营造开放的云计算技术生态圈。

更多推荐

终极指南：Flink SQL连接器版本管理从混乱到有序的升级之路

Apache Flink作为流处理领域的佼佼者，其SQL连接器的版本管理一直是开发者面临的核心挑战。本文将系统讲解Flink SQL连接器版本管理的最佳实践，帮助你轻松应对版本兼容性问题，实现从混乱到有序的升级之旅。## 连接器版本管理的常见痛点 😫在Flink应用开发中，连接器版本管理常常让开发者头疼不已。不同版本的连接器可能导致各种兼容性问题，例如API变更、功能差异甚至运行时错误。

avatar 腾讯云开发者社区

Elasticsearch复杂数据类型终极指南：从入门到精通

Elasticsearch作为功能强大的搜索引擎，支持多种复杂数据类型，让开发者能够灵活处理各种结构化和非结构化数据。本文将带你全面了解Elasticsearch中的复杂数据类型，从基础概念到实际应用，助你轻松掌握数据建模的核心技巧。## 内部对象：构建层级化数据结构在Elasticsearch中，对象类型（Object）是最基础的复杂数据类型之一，用于表示具有嵌套关系的数据。例如，我们可

avatar 腾讯云开发者社区

如何快速搭建Neon无服务器PostgreSQL：面向初学者的完整指南

Neon是一款革命性的无服务器PostgreSQL解决方案，它通过分离存储和计算层，实现了自动扩缩容、类代码式数据库分支以及零级扩展能力。本指南将帮助你从零开始搭建Neon开发环境，体验这款创新数据库的强大功能。## 准备工作：环境要求与依赖项在开始搭建Neon环境前，请确保你的系统满足以下要求：- Linux操作系统（推荐Ubuntu 20.04+或Debian 11+）- Git

avatar 腾讯云开发者社区