微服务平台需求-部署一体化文档V1.0 - 实践

微服务平台需求-部署一体化文档

版本号：V1.0
日期：2025-08-07
作者：平台架构组

---

修订记录

日期	版本	修订人	变更摘要
2025-08-07	V1.0	架构组	首版发布

---

目录

1. 引言
2. 需求概述
3. 功能需求
4. 非功能需求
5. 总体架构
6. 部署环境清单
7. 基础设施部署步骤
8. 微服务容器化规范
9. Gateway & Security 配置
10. CI/CD 流水线
11. 灰度发布与回滚
12. 监控、日志、告警
13. 安全加固清单
14. 验收标准
15. 附录

---

1 引言

本文档面向产品经理、架构师、运维、测试及安全团队，用于统一理解“基于 Spring Boot 3.x + Spring Cloud Alibaba 2023”微服务平台的业务需求与生产级部署方案。

---

2 需求概述

维度	说明
业务目标	统一技术栈、统一认证、统一网关、统一配置、统一监控，支撑 5 条业务线未来 3 年增长
技术范围	Spring Boot 3.2.x、Spring Cloud Gateway、Spring Security 6、Nacos 2.3.2、MySQL 8、Docker、K8S 1.29、Nginx Ingress
交付范围	代码仓库改造、Helm Chart、CI/CD、文档、培训

---

3 功能需求

编号	需求	验收标准
FR1	服务注册发现	任意业务 Pod 启动后 30 秒内出现在 Nacos 控制台
FR2	统一认证鉴权	网关层可解析 JWT 并透传用户信息；未携带合法 Token 返回 401
FR3	动态配置	修改 Nacos 配置后 5 秒内业务指标无重启生效
FR4	灰度发布	支持按请求头或权重 0–100 % 灰度，回滚时间 < 2 min
FR5	接口文档	网关聚合 Swagger，地址 /doc，无需认证即可访问

---

4 非功能需求

维度	指标
性能	单机 Gateway ≥ 5 000 QPS，P99 < 50 ms
可用性	整体 SLA 99.9%，Nacos & MySQL 集群 3 节点
扩展性	10 分钟内扩容一倍 Pod
安全	镜像来源白名单、Pod 非 root、网络策略

---

5 总体架构

┌────────────┐      ┌────────────┐
│ 浏览器/APP │─────▶│ Nginx Ingress│
└────────────┘      └────┬───────┘
│
┌─────────┴────────┐
│ Spring Gateway   │
│ Security Filter  │
└─────────┬────────┘
│ 服务发现
┌────────────────┴────────────────┐
│         Nacos 2.3.2 集群        │
└────────────────┬────────────────┘
┌────────────┬────────┴────────┬────────────┐
│  order-svc │  stock-svc ...  │  pay-svc   │
└────────────┴─────────────────┴────────────┘

6 部署环境清单

组件	版本	节点数	备注
K8S	1.29	3 Master + 6 Worker	离线包已准备
Nacos	2.3.2	3	MySQL 持久化
MySQL	8.0.36	1 主 1 从	Semi-sync
Harbor	v2.10	1	镜像仓库
GitLab	16.x	1	CI/CD 源码托管
Prometheus	2.50	1	监控
Loki	2.9	1	日志聚合
Vault	1.14	3	统一密钥托管

7 基础设施部署步骤

7.1 离线镜像导入

# 在能联网的跳板机
docker pull nacos/nacos-server:v2.3.2
docker save -o nacos-2.3.2.tar nacos/nacos-server:v2.3.2
# 拷贝到生产节点
docker load -i nacos-2.3.2.tar
docker tag nacos/nacos-server:v2.3.2 harbor.local/base/nacos:2.3.2
docker push harbor.local/base/nacos:2.3.2`

7.2 Nacos 集群 Helm 安装

# 如网络可用
helm repo add nacos https://nacos-group.github.io/nacos-k8s
helm install nacos nacos/nacos -n middleware -f values-nacos.yaml --create-namespace
# 若网络不可用，请离线：
# 1. 克隆 https://github.com/nacos-group/nacos-k8s
# 2. helm install nacos ./nacos-k8s/helm -n middleware -f values-nacos.yaml

values-nacos.yam

global:
mode: cluster
storage:
type: mysql
db:
host: mysql.middleware.svc.cluster.local
port: 3306
name: nacos_config
user: nacos
password: N@c0s#2025
replicaCount: 3

7.3 MySQL 主从

helm install mysql bitnami/mysql -n middleware \
--set auth.rootPassword=Root#2025 \
--set architecture=replication

8 微服务容器化规范

基础镜像： eclipse-temurin:21-jre-alpine

非 root 运行：

RUN addgroup -g 1001 app && adduser -D -u 1001 -G app app
USER 1001

健康检查：

HEALTHCHECK --interval=30s --timeout=3s \
CMD wget -q -O /dev/null http://localhost:8080/actuator/health || exit 1

9 Gateway & Security 配置

application-prod.yml

spring:
cloud:
gateway:
discovery.locator.enabled: true
routes:
- id: order
uri: lb://order-svc
predicates:
- Path=/api/order/**
filters:
- StripPrefix=2
security:
oauth2.resourceserver.jwt.jwk-set-uri: http://security-svc.middleware:8080/.well-known/jwks.json

SecurityConfig.java

@Bean
public SecurityWebFilterChain filterChain(ServerHttpSecurity http) {
http.authorizeExchange(ex -> ex
.pathMatchers("/api/public/**").permitAll()
.anyExchange().authenticated())
.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
return http.build();
}

10 CI/CD 流水线

10.1 GitLab Runner

helm install gitlab-runner gitlab/gitlab-runner -n gitlab --set rbac.create=true

10.2 .gitlab-ci.yml

stages: [build, docker, deploy]
variables:
HARBOR: harbor.local
NAMESPACE: dev
build:
stage: build
image: maven:3.9-eclipse-temurin-21
script: mvn -B clean package -DskipTests
artifacts:
paths: [target/app.jar]
docker:
stage: docker
image: gcr.io/kaniko-project/executor:latest
script:
- /kaniko/executor --context $CI_PROJECT_DIR
--dockerfile Dockerfile
--destination $HARBOR/micro/$CI_PROJECT_NAME:$CI_COMMIT_TAG
deploy:
stage: deploy
image: bitnami/kubectl:latest
script:
- helm upgrade --install $CI_PROJECT_NAME ./helm/$CI_PROJECT_NAME
-n $NAMESPACE --set image.tag=$CI_COMMIT_TAG

11 灰度发布与回滚

灰度 Ingress

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "X-Canary"
nginx.ingress.kubernetes.io/canary-weight: "20"

回滚

helm rollback order-svc 2
# 或
kubectl rollout undo deployment/order-svc

12 监控、日志、告警

类别	方案	端口/路径	Dashboard
指标	Prometheus + ServiceMonitor	/actuator/prometheus	Grafana ID 1860
日志	Loki + Promtail	stdout	Grafana Explore
告警	Alertmanager	webhook 飞书	内置规则

13 安全加固清单

PodSecurityPolicy 禁止 root
NetworkPolicy 禁止跨 namespace
Kyverno 强制镜像来源 harbor.local
Vault 存储 MySQL、Nacos 密码
Ingress TLS 全站 https（cert-manager）

14 验收标准

场景	指标	通过标准
压测	wrk -t4 -c100 -d60s	Gateway P99 < 50 ms
故障	kill -9 任意 Nacos Pod	服务发现无中断 > 30 s
灰度	修改 header 20% 流量	Grafana 观测 QPS 曲线正确
回滚	helm rollback	30 秒内流量恢复

15 附录

A. 一键验证脚本

#!/bin/bash
TOKEN="eyJhbGciOiJSUzI1NiIs..."
kubectl run test --image=curlimages/curl -it --rm --restart=Never -- \
curl -H "Authorization: Bearer $TOKEN" \
http://gateway.middleware/api/order/health

B. 常用命令

# 查看网关路由
kubectl get ingress -A
# 实时查看 Nacos 日志
stern nacos -n middleware
# 手动扩容
kubectl scale deploy order-svc --replicas=6 -n dev