← 返回学习路线

SYSTEM

博客项目微服务化 — 阶段2 验证 + Docker Compose 部署实战笔记

后端实战
src/content/notes/blog-dev/部署.md

博客项目微服务化 — 阶段2 验证 + Docker Compose 部署实战笔记

日期:2026-08-14 目标:完成阶段2 测试验证(Nacos 热更新 / Feign 容错 / Gateway 过滤器 / Redis 前缀隔离 / 数据库隔离 / 单体+微服务并行),并落地 Docker Compose 容器化部署 + Nginx 反代网关。


一、今日工作概览

环节 内容 结果
阶段2 验证 Nacos 配置中心 + 热更新 ✅
阶段2 验证 Feign 容错(停 user 服务降级) ✅
阶段2 验证 Gateway 全局过滤器日志 ✅
阶段2 验证 Redis key 前缀隔离 ✅
阶段2 验证 数据库 blog_cloud 建表隔离 ✅
阶段2 验证 单体 + 微服务并行运行 ✅
部署 Docker Compose 容器化(nacos/mysql/redis/rabbitmq/user/article/gateway/nginx) ✅
部署 Nginx 反代网关(3.4 可选) ✅

当前运行架构(并行双轨):

【单体】blog :8088  →  blog_db 库  →  blog:article:* 前缀
【微服务】Gateway :8080 → article-service :8082 / user-service :8081 → blog_cloud 库 → ms:article:* 前缀
【Nginx】:80 → gateway:8080(容器内)

二、项目代码结构(当前状态)

blog-cloud/                          # 微服务聚合父工程 (Spring Boot 3.5.4 / Cloud 2025.0.0 / Alibaba 2025.0.0.0)
├── pom.xml                          # 父 POM:统一版本管理 + spring-boot-maven-plugin
├── docker-compose.yml               # 一键编排全部中间件与业务服务
├── nginx.conf                       # Nginx 反代 + 限流
├── blog-common/                     # 公共模块:Result / PageResult / 全局异常
├── blog-gateway/                    # 网关 :8080(WebFlux,无数据库)
├── blog-user-service/               # 用户服务 :8081(JWT / 安全)
└── blog-article-service/            # 文章服务 :8082(文章/评论/分类 + Feign 调用户)

每个业务服务内部统一分层:

controller → service/impl → repository(JPA) → MySQL
              └── feign(article 调 user 取昵称)
              └── config(Redis 序列化 / Nacos / Redisson)
              └── util(RedisUtil)
resources/
  ├── bootstrap.yml    # 启动期:Nacos 地址 / shared-configs
  └── application.yml  # 业务配置:端口 / 数据源 / Redis / 路由

三、配置分层:bootstrap.yml 与 application.yml

3.1 职责划分

文件 加载时机 内容 作用
bootstrap.yml 最先(引导上下文) Nacos 注册/配置中心地址、命名空间、shared-configs 公共配置 先连上 Nacos,保证后续配置能拉到
application.yml 引导之后 端口、数据源、Redis、JWT、路由、Feign 超时 业务配置 + 本地兜底默认值

3.2 当前 bootstrap.yml(以 article-service 为例)

spring:
  application:
    name: blog-article-service
  cloud:
    nacos:
      server-addr: ${NACOS_ADDR:nacos:8848}   # 占位符 + 默认值,可被 compose 环境变量覆盖
      namespace: ${NACOS_NAMESPACE:}
      config:
        file-extension: yaml                  # 必须与 Nacos 里 dataId 后缀一致(.properties 找不到)
        group: DEFAULT_GROUP
        refresh-enabled: true                 # 开启配置热更新
        shared-configs:                       # 多服务共享的公共配置
          - dataId: blog-common.yaml
            group: DEFAULT_GROUP
            refresh: true
      discovery:
        ephemeral: true

3.3 当前 application.yml(article-service 关键段)

server:
  port: 8082
spring:
  application:
    name: blog-article-service
  config:
    import:                                    # Spring Boot 3.x 官方推荐:替代 bootstrap 自动导入
      - optional:nacos:blog-article-service.yml?group=DEFAULT_GROUP&refreshEnabled=true
  datasource:
    url: jdbc:mysql://${DB_HOST:mysql}:${DB_PORT:3306}/blog_cloud?...
    password:[已隐藏]                   # 由 compose 注入
  data:
    redis:
      host: ${REDIS_HOST:redis}
      password:[已隐藏]             # 修正后:不传为空字符串,绝不传 "null"

3.4 思考(面试重点)

  • 为什么还要 bootstrap.yml? 因为 shared-configs(如 blog-common.yaml 公共配置)必须在业务上下文启动前就绪,而 bootstrap 阶段是最早的加载时机。
  • spring.config.import 是什么? Spring Boot 3 / Spring Cloud 2022 起默认禁用 bootstrap 上下文,官方用 spring.config.import 导入外部配置。optional: 前缀表示 Nacos 不可用时不阻断启动(本地开发友好)。
  • 配置优先级(从高到低): 环境变量(compose environment)> application.yml 默认值;bootstrap.yml 里的 ${NACOS_ADDR:默认} 占位符同样能被环境变量覆盖。因此 compose 里注入 NACOS_ADDR: nacos:8848 可以覆盖 bootstrap 默认值 localhost:8848,实现”本地 IDE 直连 / 容器内走服务名”两种场景共用一套配置。
  • 更准确的理解:不是”环境变量覆盖不了 bootstrap”,而是 bootstrap 里的默认值要写对(本地开发指向 localhost),容器环境用环境变量覆盖为服务名(nacos:8848)。两者结合才能一份配置双场景跑通。

四、阶段2 核心功能代码细节

4.1 Nacos 配置中心 + 热更新

Nacos 控制台 blog-article-service.yml 中的配置:

ms:
  redis:
    prefix: ms:article-nacos

业务侧通过 @RefreshScope + @Value 动态读取:

@Component
@RefreshScope          // 关键:配置变更后自动重建 Bean,实现热更新
@Data
public class ArticleConfig {
    @Value("${ms.redis.prefix:ms:article}")
    private String prefix;
}

验证方式:GET /api/article/config → 返回 {"prefix": "ms:article-nacos"};改 Nacos 里该值 → 应用无需重启自动刷新。

思考:@RefreshScope 通过把 Bean 实例放入可刷新的作用域,配置发布后靠 Spring Cloud Bus / Nacos 长轮询推送触发重建,实现零重启改配置。生产上这是灰度、应急降级的基石。

4.2 Redis 前缀隔离(Redis key 设计)

问题:单体与微服务共用同一个 Redis,key 必须隔离,否则互相覆盖。

微服务统一前缀 ms:article::

// ArticleServiceImpl 浏览量 ZSet
String key = articleConfig.getPrefix() + ":article:view_count";
stringRedisTemplate.opsForZSet().incrementScore(key, articleId.toString(), 1);

// CommentServiceImpl 评论缓存
String cacheKey = articleConfig.getPrefix() + ":comment:article:" + articleId;

实际验证到的 Redis key:

# 单体(blog 前缀)
blog:article:list  blog:article:detail:24  blog:article:bloom ...
# 微服务(ms 前缀)
ms:article:article:view_count  ms:article:comment:article:* ...

思考:key 隔离不仅是命名规范,更是多套系统共享基础设施时的第一道防线。规范:业务:实体:操作:标识。面试时可说”用前缀区分环境/应用,避免缓存穿透到错误数据”。

4.3 Gateway 路由 + 全局过滤器

spring:
  cloud:
    gateway:
      server:
        webflux:
          discovery:
            locator:
              enabled: true          # 自动发现 Nacos 里的服务
              lower-case-service-id: true
          routes:
            - id: article-service
              uri: lb://blog-article-service   # lb:// 走负载均衡
              predicates: [Path=/api/article/**]
            - id: user-service
              uri: lb://blog-user-service
              predicates: [Path=/api/user/**]

全局过滤器(记录请求耗时 + 透传网关标识头):

@Slf4j
@Component
public class GatewayGlobalFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        long start = System.currentTimeMillis();
        log.info("[网关] 请求: {} {}", request.getMethod(), request.getURI());
        ServerHttpRequest mutated = request.mutate()
                .header("X-Gateway", "blog-gateway")
                .build();
        return chain.filter(exchange.mutate().request(mutated).build())
                .then(Mono.fromRunnable(() ->
                        log.info("[网关] 完成: {} 耗时 {}ms", request.getURI(), System.currentTimeMillis() - start)));
    }
    @Override
    public int getOrder() { return 0; }
}

思考:Gateway 是 WebFlux(响应式、非阻塞),不能引入 servlet 容器 / JPA / spring-boot-starter-web,否则与 webflux 冲突。因此 gateway 的 pom 里把 blog-common 传递进来的 web/tomcat/jpa 全部 exclude 掉(见 parent pom 注释)。getOrder()=0 越小越先执行,可在此统一做鉴权、限流、日志。

4.4 Feign 容错降级

article-service 通过 Feign 调 user-service 取作者昵称:

@FeignClient(name = "blog-user-service", fallback = UserFeignClientFallback.class)
public interface UserFeignClient {
    @GetMapping("/api/user/info/{id}")
    Result<Map<String, Object>> getUserById(@PathVariable("id") Long id);
}

降级实现(user 服务宕机时返回默认昵称,主流程不中断):

@Component
public class UserFeignClientFallback implements UserFeignClient {
    @Override
    public Result<Map<String, Object>> getUserById(Long id) {
        return Result.success(Map.of("username", "用户"));  // 兜底默认昵称
    }
}

调用侧再套一层 try-catch,双保险:

try {
    Result<Map<String, Object>> result = userFeignClient.getUserById(comment.getUserId());
    if (result.getData() != null) {
        comment.setUsername((String) result.getData().get("username"));
    }
} catch (Exception e) {
    log.error("Feign 获取用户信息失败, userId={}", comment.getUserId(), e);
    comment.setUsername("用户");
}

验证:停掉 user-service 后,评论列表仍正常返回,昵称显示”用户”,无异常堆栈。

思考:Feign fallback 依赖 spring-cloud-starter-openfeign + spring-cloud-starter-loadbalancer(lb:// 寻址需要)。容错三件套:超时(connect 2s / read 3s)→ 降级(fallback)→ 兜底(try-catch + 默认值)。面试时强调”故障隔离 + 优雅降级”,避免单点故障拖垮整条链路。

4.5 数据库隔离

  • 单体:blog_db(http://localhost:8088)
  • 微服务:blog_cloud(JPA ddl-auto: update 自动建表)

两条访问链同时返回各自数据,互不干扰,验证了多环境并行可行性。


五、四大问题:现象 → 根因 → 排查 → 解决 → 思考

问题 1:Redisson 报错,手动编写 RedissonConfig 后项目才可启动

现象:引入 redisson 依赖后应用启动异常/行为异常,只有补上自定义配置类才正常。

根因:仅引入 redisson-spring-boot-starter 依赖,Spring Boot 自动装配逻辑在缺少显式连接配置(host/port/密码来源)时无法正确构建客户端,或与项目中自定义的 RedisTemplate 序列化方案不协调。项目放弃自动装配,改为显式构建 RedissonClient。

解决方案(当前代码 RedissonConfig.java,位于单体应用 config 包):

@Configuration
public class RedissonConfig {
    @Value("${spring.data.redis.host}") private String redisHost;
    @Value("${spring.data.redis.port}") private int redisPort;
    @Value("${spring.data.redis.password:}") private String redisPassword; // 空串兼容无密码
    @Value("${spring.data.redis.database:0}") private int database;

    @Bean
    public RedissonClient redissonClient() {
        Config config = new Config();
        config.useSingleServer()
                .setAddress("redis://" + redisHost + ":" + redisPort)
                .setDatabase(database)
                .setConnectionPoolSize(8)
                .setConnectionMinimumIdleSize(2)
                .setConnectTimeout(10000)
                .setTimeout(3000)
                .setIdleConnectionTimeout(60000)
                .setRetryAttempts(3)
                .setRetryInterval(1500);
        if (StringUtils.hasText(redisPassword)) {
            config.useSingleServer().setPassword(redisPassword);
        }
        config.setLockWatchdogTimeout(30000);   // 看门狗:分布式锁自动续期
        config.setTransportMode(TransportMode.NIO);
        return Redisson.create(config);
    }
}

思考(面试亮点):

  • 手动装配的收益:连接池参数、看门狗间隔、密码注入方式完全可控,符合”企业级关键组件显式配置、失败快速暴露”的原则。
  • leaseTime=-1 时看门狗默认 30s 自动续期,防止长任务持锁期间锁过期;这是 Redisson 相对自研 SETNX 的核心优势。
  • 版本坑(项目 memory 有记录):redisson-spring-boot-starter 3.31.0 与 Spring Boot 4.x 有自动配置冲突(引用被移除的 RedisProperties),需 exclude 自动配置 + 手动建 Bean。本项目固定 Spring Boot 3.5.4,手动配置规避。

问题 2:Docker Compose 微服务 UnknownHostException 域名解析失败

现象:容器里服务启动报 UnknownHostException: xxx-1,连不上 Nacos/MySQL。

根因:错误使用了容器的 container_name(compose 默认生成的 xxx-1 容器名)作为连接地址。compose 内置 DNS 只解析 services: 下一级的 key(服务名),xxx-1 不是合法的服务名。

解决方案(当前 docker-compose.yml 已落地):

  1. 所有连接地址用服务名:nacos:8848、mysql、redis,禁止 -1 后缀;
  2. 通过 compose environment 注入环境变量覆盖配置(DB_HOST: mysql、NACOS_ADDR: nacos:8848、REDIS_HOST: redis、`REDIS_PASSWORD:[已隐藏]
  3. depends_on 补齐依赖顺序。
user-service:
  build: ./blog-user-service
  environment:
    DB_HOST: mysql
    DB_PASSWORD: root
    NACOS_ADDR: nacos:8848
    REDIS_HOST: redis
    REDIS_PASSWORD:[已隐藏]
  depends_on: [nacos, mysql, redis]

思考:compose 的 DNS 域名 = services 下的 key。depends_on 只保证启动顺序,不保证就绪(MySQL/Nacos 起来但端口未就绪)。生产要么用 healthcheck,要么在应用侧做好重试。服务间通信一律走服务名,这是容器编排的”解耦点”。

问题 3:bootstrap.yml 和 application.yml 分不清

现象:Nacos 配置拉不到 / 注册中心连不上,两头配置写了又改,反复重启。

根因:不清楚两个配置文件的加载时机与职责,把 Nacos 地址写进了 application.yml,或在 bootstrap.yml 里放业务配置,导致启动期找不到配置中心。

解决方案(分层职责):

  • bootstrap.yml:启动最先加载,只放 Nacos 注册/配置中心地址、命名空间、shared-configs 公共配置。
  • application.yml:业务配置(端口、数据源、Redis、JWT、路由、Feign 超时)。
  • Nacos 地址用占位符 ${NACOS_ADDR:localhost:8848},本地 IDE 直接用默认值;compose 里用环境变量覆盖为 nacos:8848。

思考(更准确的理解):

  • 环境变量优先级高于配置文件,所以 compose 的 NACOS_ADDR 能覆盖 bootstrap 默认值。真正要小心的是:bootstrap 的默认值必须写对——默认值是为”无环境变量的本地启动”兜底的。
  • Spring Boot 3 建议用 spring.config.import(application.yml 里)导入 Nacos 配置;bootstrap.yml + spring-cloud-starter-bootstrap 依赖用于加载 shared-configs 和极早期配置。两者可共存,职责不同。
  • 面试回答模板:“配置文件分层本质是把’去哪个配置中心拿配置’和’业务配置本身’分离,保证应用在任何环境都能先找到配置源,再加载业务参数。”

问题 4:Redis AUTH 密码报错 ERR AUTH <password> called without any password configured,应用直接退出

现象:redis 容器没设密码,但应用传了密码 → 报 AUTH 错误;或容器设了密码而服务没拿到 → 同样连不上。应用直接退出。

根因:两处配置不一致 + 占位符写法缺陷:

  • yml 中 ${REDIS_PASSWORD:[已隐藏] REDIS_PASSWORD环境变量未注入时,默认值#{null}在部分场景会被当成字符串”null”` 作为密码传入,触发 AUTH 校验失败。
  • compose 里 redis 容器设了 `REDIS_PASSWORD:[已隐藏] user/article 服务没注入该环境变量 → 无密码连接被拒。

解决方案(当前代码已统一):

  1. yml 密码占位符改为 `${REDIS_PASSWORD:[已隐藏]
spring:
  data:
    redis:
      host: ${REDIS_HOST:redis}
      port: ${REDIS_PORT:6379}
      password:[已隐藏]    # 空默认值,绝不出现字符串 "null"
  1. compose 中 redis 容器与服务同步注入相同密码:
redis:
  image: redis:7-alpine
  environment:
    - REDIS_PASSWORD:[已隐藏]
user-service:
  environment:
    REDIS_PASSWORD:[已隐藏]
article-service:
  environment:
    REDIS_PASSWORD:[已隐藏]
  1. 不硬编码密码到 yml,全部环境变量注入。

思考(面试亮点):

  • #{} 是 SpEL 表达式语法,${} 才是占位符。`${REDIS_PASSWORD:[已隐藏] 想表达”缺省为 null”,但混淆了两个语法,风险极高——默认值宁可空字符串也不要 null。
  • 密码一致性三处校验:容器端 set → 服务端注入 → 代码读取;任何一处断链都会导致连接失败。
  • 安全实践:密钥/密码一律环境变量注入,yml 只留占位符,避免明文进 Git 历史。

补充问题 5:Docker 里 no main manifest attribute, in app.jar

现象:docker compose up 后容器日志报 no main manifest attribute, in app.jar,服务全部启动失败。

根因:target/ 下的 JAR 是 thin JAR(只有本模块 class,几 KB ~ 几十 KB),不是 Spring Boot fat JAR——spring-boot-maven-plugin 的 repackage 目标没执行(JAR 是 mvn compile/jar:jar 产出,而非 mvn package)。

解决方案:

cd [本地路径]
mvn clean package -DskipTests      # 触发 repackage,产出几十 MB 的 fat JAR
docker compose down --rmi all
docker compose up -d --build

思考:fat JAR 把依赖的 BOOT-INF/lib 和 Main-Class 一起打进 jar,java -jar 才能找到启动入口;thin JAR 只是编译产物。用 Dockerfile 之前必须先 mvn package,这是容器化最常见的一步坑。


六、通用操作流程(改配置后必做)

1. 修改 yml 配置文件
2. mvn clean package -DskipTests          # 重新打包 fat JAR
3. docker compose down --rmi all           # 清旧容器、旧镜像
4. docker compose up -d --build            # 全新构建启动

提示:--rmi all 会删除全部镜像(含中间件),后续只需 down + up -d --build 即可保留基础镜像加快启动。


七、关键知识点速查(记忆卡片)

  1. compose 内部 DNS 域名 = services 下一级 key(服务名),不是容器名(xxx-1 不行)。
  2. 配置优先级:环境变量(compose environment)> application.yml 默认值;bootstrap.yml 的 ${VAR:默认} 同样可被环境变量覆盖。
  3. depends_on 只控制启动顺序,不保证中间件就绪;就绪要靠 healthcheck 或应用重试。
  4. ${} 是占位符,#{} 是 SpEL;Redis 密码缺省写 ${VAR:},别写 ${VAR:#{null}}。
  5. Spring Boot 3 用 spring.config.import 导入 Nacos 配置;optional: 前缀=配置中心不可用不阻断启动。
  6. @RefreshScope + Nacos = 配置热更新,改配置无需重启。
  7. bootstrap 的 file-extension 必须与 Nacos dataId 后缀一致(.yaml 就写 yaml)。
  8. Gateway 是 WebFlux,禁止引入 web/tomcat/jpa,否则与响应式模型冲突。
  9. 应用崩溃后的 Nacos InterruptedException 是收尾堆栈,不是根因——先看真正的启动异常。
  10. 容器化先 mvn package 产出 fat JAR,否则 no main manifest attribute。

八、面试话术总结(升华)

Q:你们项目为什么用微服务,Gateway 做什么?

单体(blog:8088)与微服务(blog-cloud)并行开发迁移。Gateway 统一入口:路由转发(lb:// 负载均衡)、全局过滤器(日志/耗时/透传头)、统一跨域,后续可扩展统一鉴权与限流。WebFlux 响应式,不引入 servlet。

Q:Nacos 怎么用的?配置热更新怎么实现?

双职责:服务注册发现(discovery)+ 配置中心(config)。启动经 bootstrap.yml 先连 Nacos,spring.config.import 拉取业务配置;@RefreshScope 让 Bean 感知配置发布自动重建,实现改配置零重启。

Q:Feign 调用失败怎么办?

三层容错:① 超时(connect 2s/read 3s);② @FeignClient(fallback) 降级返回默认昵称;③ 调用侧 try-catch 兜底 + 默认值。保证下游宕机不影响主流程,符合故障隔离、优雅降级的理念。

Q:单体与微服务共用 Redis/MySQL 怎么隔离?

Redis 用 key 前缀隔离(单体 blog:、微服务 ms:article:),通过 ArticleConfig 统一维护,Nacos 可热更新;数据库用不同 schema(blog_db / blog_cloud)。基础设施共享但数据空间隔离。

Q:Docker 部署踩过什么坑?

① 服务间通信必须用 compose 服务名(DNS 只认 services 下的 key),不能用容器名 xxx-1;② depends_on 不保证就绪,需要 healthcheck;③ 密码必须 compose 注入环境变量,yml 占位符缺省写空串避免 null 字符串;④ 打包必须先 mvn package 得到 fat JAR,否则 no main manifest attribute。

Q:配置文件的优先级?

环境变量(OS/compose)> application.yml 默认值;bootstrap.yml 负责启动早期加载 Nacos 地址与共享配置,其占位符默认值可被环境变量覆盖。核心是”先连配置源,再加载业务配置”。