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(JPAddl-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 已落地):
- 所有连接地址用服务名:
nacos:8848、mysql、redis,禁止-1后缀; - 通过 compose
environment注入环境变量覆盖配置(DB_HOST: mysql、NACOS_ADDR: nacos:8848、REDIS_HOST: redis、`REDIS_PASSWORD:[已隐藏] 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 服务没注入该环境变量 → 无密码连接被拒。
解决方案(当前代码已统一):
- yml 密码占位符改为 `${REDIS_PASSWORD:[已隐藏]
spring:
data:
redis:
host: ${REDIS_HOST:redis}
port: ${REDIS_PORT:6379}
password:[已隐藏] # 空默认值,绝不出现字符串 "null"
- compose 中 redis 容器与服务同步注入相同密码:
redis:
image: redis:7-alpine
environment:
- REDIS_PASSWORD:[已隐藏]
user-service:
environment:
REDIS_PASSWORD:[已隐藏]
article-service:
environment:
REDIS_PASSWORD:[已隐藏]
- 不硬编码密码到 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即可保留基础镜像加快启动。
七、关键知识点速查(记忆卡片)
- compose 内部 DNS 域名 = services 下一级 key(服务名),不是容器名(
xxx-1不行)。 - 配置优先级:环境变量(compose environment)> application.yml 默认值;bootstrap.yml 的
${VAR:默认}同样可被环境变量覆盖。 depends_on只控制启动顺序,不保证中间件就绪;就绪要靠 healthcheck 或应用重试。${}是占位符,#{}是 SpEL;Redis 密码缺省写${VAR:},别写${VAR:#{null}}。- Spring Boot 3 用
spring.config.import导入 Nacos 配置;optional:前缀=配置中心不可用不阻断启动。 @RefreshScope+ Nacos = 配置热更新,改配置无需重启。- bootstrap 的
file-extension必须与 Nacos dataId 后缀一致(.yaml 就写 yaml)。 - Gateway 是 WebFlux,禁止引入 web/tomcat/jpa,否则与响应式模型冲突。
- 应用崩溃后的 Nacos
InterruptedException是收尾堆栈,不是根因——先看真正的启动异常。 - 容器化先
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 地址与共享配置,其占位符默认值可被环境变量覆盖。核心是”先连配置源,再加载业务配置”。