QuickBlue AI微服务底座环境准备：从Docker到K8s的完整指南

1. 先想清楚QuickBlue 底座环境准备到底在准备什么做 QuickBlue AI 微服务应用底座之前我在各种项目里给开发环境擦屁股的时间远比写业务代码的时间多。团队拿到代码第一句问的永远是“怎么跑起来”明明都是微服务有的项目用 Nacos 做注册中心有的用 Consul有的干脆 Eureka 顶着用数据库一会 MySQL 一会 PostgreSQL缓存层更是五花八门。到了 AI 应用阶段更麻烦多个服务要统一接大模型每个人本地的 Python 环境、CUDA 版本、模型路径全不一样联调一次能折腾一整天。所以 QuickBlue 这个底座想解决的本质上不是“某个功能怎么做”而是“团队里任何一个人 clone 下代码能不能在半天内把整套环境拉起来并且保证互相之间联调不出幺蛾子”。它是一套标准化的微服务基础设施加 AI 能力接入层的组合包含开发机侧的工程规范、容器化中间件、Kubernetes 调度底座、大模型接入网关这些部分。这篇先把环境准备讲透。因为环境准备是所有后续工作的地基这个阶段偷的懒后面都会加倍还回来。你会发现很多微服务项目死在第一步不是代码多烂而是环境说明文档缺失、脚本过期、依赖版本冲突新人根本无从下手。2. 开发机侧的一次性配置JDK、Maven、IDE 与镜像加速2.1 版本统一这件事越早定越省事QuickBlue 底座如果走 Java 技术栈JDK 版本是第一个要拍板的事。现在这个阶段我不会再看 8 了虽然很多老项目还在跑但 Spring Boot 3 和 Spring Cloud 2023 之后的主线版本都要求 JDK 17 起步。AI 场景里的 Java 客户端库比如 Spring AI对高版本 JDK 的支持也明显更积极。所以团队统一用 JDK 17别跳版本别有的机器装 11 有的装 21。Maven 用 3.9IDEA 至少用 2023.2 之后的版本因为对 Spring Boot 3 的启动配置支持更好。这一步看起来基础但只要你团队里出现一个“我本地好好的啊”的人大概率就是版本差异。2.2 Maven 镜像与依赖私服的坑国内环境跑 Maven 依赖默认中央仓库能不能拉得动全看运气。这个不展开但本地settings.xml里的 mirror 配置是必做的mirror idaliyunmirror/id mirrorOfcentral/mirrorOf nameAliyun Mirror/name urlhttps://maven.aliyun.com/repository/public/url /mirror如果公司有内网私服把mirrorOf配成*,!private-repo这种方式让私服依赖走内网地址其他走公共镜像。我踩过的坑是团队里有人的 IDE 默认用了捆绑的 Maven导致配置没生效。一定要在 IDEA 的 Settings - Build Tools - Maven 里把User settings file指到自定义的settings.xml并且勾选Override。另外建议在settings.xml的profiles里加上 JDK 编译版本约束profile idjdk-17/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target /properties /profile2.3 IDEA 里多模块微服务的启动姿势QuickBlue 底座肯定不是单服务而是多个微服务模块比如gateway、auth、system、ai-service、base-common。这种多模块工程在 IDEA 里启动有个很头疼的点每次都要在模块列表里翻找 main 方法。我的做法是建立一个自定义 Run Configuration 列表给每个需要启动的服务命名成01-gateway、02-auth、03-system这样带序号的名称并且把不需要跑的服务比如模块基础库 base-common排除掉。再配合 IDEA 的 Compiler - Build Project automatically改完代码不用手动重启服务。还有一个隐藏功能在 services 工具窗口IDEA 2022里可以同时看到多个 Spring Boot 服务的启动状态比一个个 Terminal 清爽得多。3. 中间的这条“数据总线”Docker 环境与基础设施中间件3.1 Docker 不是装完就不管的现在的微服务项目中间件全套容器化是标准操作。QuickBlue 底座这一层至少需要MySQL、Redis、Nacos、RabbitMQ 或 Kafka 二选一。这么一算开发机必须装 Docker。Docker Desktop 在 Windows 和 macOS 上比较方便但在国内环境拉镜像需要配 registry mirror。一个小提醒很多第三方加速地址现在都不好用要选实时可用的并且daemon.json里可以多配几个Docker 会依次尝试{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ], log-driver: json-file, log-opts: { max-size: 50m, max-file: 5 } }日志限制这个配置新手特别容易忽略不加的话一个 Nacos 容器跑几个月能吃掉几十 G 磁盘。我见过不止一次服务器磁盘被容器日志写满导致服务全挂的情况。任何环境准备都要把日志治理提前做不要等出问题再补。3.2 用 Compose 编排底座中间件用docker run一个个启动中间件不是不行但维护成本高。QuickBlue 环境准备更建议把底座中间件写成一个docker-compose.yml放在项目deploy/dev目录下。这样任何人 clone 下来一条命令就能拉起所有基础设施。下面是我实际在用的 QuickBlue 开发环境 Compose 文件核心片段version: 3.8 services: mysql: image: mysql:8.0 container_name: qb-mysql ports: - 3306:3306 environment: MYSQL_ROOT_PASSWORD: root123 TZ: Asia/Shanghai volumes: - qb_mysql_data:/var/lib/mysql - ./mysql/init:/docker-entrypoint-initdb.d command: - --character-set-serverutf8mb4 - --collation-serverutf8mb4_general_ci healthcheck: test: [CMD, mysqladmin, ping, -h, localhost, -proot123] interval: 5s timeout: 3s retries: 10 redis: image: redis:7.2-alpine container_name: qb-redis ports: - 6379:6379 command: redis-server --appendonly yes --requirepass redis123 volumes: - qb_redis_data:/data nacos: image: nacos/nacos-server:v2.3.2 container_name: qb-nacos ports: - 8848:8848 - 9848:9848 environment: MODE: standalone NACOS_AUTH_ENABLE: false SPRING_DATASOURCE_PLATFORM: mysql MYSQL_SERVICE_HOST: mysql MYSQL_SERVICE_PORT: 3306 MYSQL_SERVICE_USER: root MYSQL_SERVICE_PASSWORD: root123 MYSQL_SERVICE_DB_NAME: nacos_config depends_on: mysql: condition: service_healthy rabbitmq: image: rabbitmq:3.13-management container_name: qb-mq ports: - 5672:5672 - 15672:15672 environment: RABBITMQ_DEFAULT_USER: qbuser RABBITMQ_DEFAULT_PASS: qbpass volumes: qb_mysql_data: qb_redis_data:这个编排里有几个容易被忽略的细节值得单独说。第一depends_on配合healthcheck条件判断保证 Nacos 启动时 MySQL 已经可用。Nacos 启动时会初始化自己的配置库如果连不上数据库会直接启动失败等 MySQL 健康了再启动它能避免很多“为什么我的 Nacos 起不来”的疑问。第二Nacos 2.x 不仅监听 8848还有 9848 这个 gRPC 端口。微服务客户端和 Nacos 通信默认走 gRPC如果你只映射 8848代码里注册服务时大概率会报连接异常。这个坑在环境准备阶段提前处理掉后面联调能省一天时间。第三MySQL 8.0 的认证插件默认是 caching_sha2_password老版本的连接驱动可能不兼容。QuickBlue 的 pom 里统一用mysql-connector-j8.x 或 9.x这个问题就自然规避了。4. 底座运行时的载体单节点 Kubernetes 的落地方案4.1 为什么 QuickBlue 要把底座架构在 K8s 之上很多团队的环境准备止步于 Docker Compose服务一多就觉得够用了。但 QuickBlue 既然叫微服务应用底座面向的不止是本地跑通而是应用能平滑迁移到测试、预发、生产环境。这里涉及一个关键认知Compose 管理的是容器K8s 管理的是应用。Compose 只能让我知道“中间件怎么启动”K8s 能让微服务具备自动重启、水平扩缩容、滚动发布、配置挂载这些生产级能力。QuickBlue 选用 K8s 作为底座调度层目标是把开发环境到生产环境的差距缩到最小。4.2 单节点 K8s 怎么选生产环境之前本地或单机测试环境没必要建复杂的多节点集群。目前比较务实的选择是 K3s 或者 kind。K3s 的优点是安装快、内存占用低单机能跑完整套 Kubernetes API还内置了 Traefik 作为 ingress controller。QuickBlue 底座在开发机上用 K3s 就够了。安装命令一行搞定curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRRORcn sh -装完用kubectl get node确认节点 Ready 状态。这里提醒一下国内网络环境下 K3s 安装脚本有一些镜像加速参数具体以官方文档为准装不上的先检查网络和容器运行时。如果你不想在本地直接装太重的东西也可以选择 kindKubernetes in Docker适合 CI 环境中临时拉起集群做集成测试。但作为日常开发底座K3s 更稳定。4.3 一套全家桶QuickBlue 服务在 K8s 上的部署骨架在环境准备阶段就要把 K8s 部署骨架搭好而不是等代码写完再补。QuickBlue 的每个微服务模块标准交付物应包含Dockerfile和deploy/k8s下的Deployment.yaml、Service.yaml、ConfigMap.yaml。一个典型的Deployment.yaml片段长这样apiVersion: apps/v1 kind: Deployment metadata: name: qb-auth namespace: quickblue spec: replicas: 1 selector: matchLabels: app: qb-auth template: metadata: labels: app: qb-auth spec: containers: - name: qb-auth image: registry.local/quickblue/qb-auth:1.0.0 ports: - containerPort: 8080 env: - name: SPRING_PROFILES_ACTIVE value: dev - name: NACOS_ADDR value: qb-nacos:8848注意命名空间统一用quickblue避免所有服务挤在 default 里互相污染。镜像版本号必须显式指定1.0.0这种而不能写latest否则后面滚动发布时镜像不变但 tag 相同K8s 不会拉取新镜像这是非常常见的坑。4.4 单节点上跑微服务的资源底线如果要在单节点 K8s 上跑整套 QuickBlue——几个中间件加三四个核心服务——机器配置建议至少 8 核 16G能上 16 核 32G 更好。注意在 K8s 里一定要给每个服务设置resources.requests和resources.limits。不设置 limit 的话某个服务出现内存泄漏会拖垮整个节点的其他 Pod。这是环境准备阶段就应该写进模板的规范。5. AI 能力接入环境大模型访问、GPU 与推理资源配置5.1 QuickBlue 的 AI 层要准备两套接入路径QuickBlue 定位是 AI 微服务应用底座AI 能力接入层是不可或缺的部分。在环境准备阶段要把 AI 相关环境抽象成两层外部 API 路径调用云上大模型接口比如通义千问开发环境只要有一个 API Key 和网络连通性就够了。本地模型路径在自建环境部署开源模型比如通过 Ollama 或 vLLM 跑 Qwen 系列模型适合数据敏感和离线场景。我建议 QuickBlue 的 AI 模块在开发阶段默认走外部 API这样团队不用每个人都扛一台 GPU 机器。真正的 GPU 推理环境由专门的ai-gateway服务统一对接业务服务不直接感知模型部署细节。5.2 GPU 驱动与容器化推理环境的检查清单如果你要在开发机或服务器上本地部署大模型环境准备要提前确认这些项NVIDIA 驱动版本用nvidia-smi查看。Docker 的 NVIDIA Container Toolkit确保容器里能访问 GPU。显存与模型规模的匹配关系。经验公式一个 7B 参数的模型做 FP16 推理大约需要 14-16G 显存如果做 INT8 量化能低至 8G 左右。QuickBlue 默认推荐 7B 级别模型起步因为效果和资源损耗相对均衡。容器环境验证 GPU 是否可用docker run --rm --gpus all nvidia/cuda:12.4.1-runtime-ubuntu22.04 nvidia-smi如果容器里nvidia-smi能正常输出 GPU 信息说明 Docker GPU 环境没问题。这一条不提前验证后面部署模型服务时会花大量时间在“为什么 CUDA 不可用”的排查上。5.3 Spring AI 接入层的配置模板QuickBlue 的 AI 模块如果基于 Spring AI 封装配置文件里要预置好模型供应商和超参而且不能把 Key 硬编码。开发环境建议写在环境变量里spring: ai: dashscope: api-key: ${AI_API_KEY} chat: options: model: qwen-plus temperature: 0.7启动脚本里统一从~/.quickblue/env这个本地文件加载环境变量export $(grep -v ^# ~/.quickblue/env | xargs)这样每个开发者在自己的机器上只要设置一次后续所有服务通过同一个环境变量名称就能读取到 Key代码仓库里永远不会出现真实的 API Key。6. 联调前的连通性验证把环境问题掐死在代码启动前6.1 分层的环境自检清单环境准备的最后一步不是写代码而是把所有中间件、注册中心、AI 服务串起来做一次连通性验证。QuickBlue 这套底座如果每个人装完环境就急着启动服务一定会遇到各种玄学问题。我建议在仓库里放一个scripts/check-env.sh大致分层检查网络层Docker 是否运行、镜像仓库能否连通。中间件层MySQL、Redis、Nacos、消息队列的端口连通性账号密码是否正确。注册中心层Nacos 控制台能否打开命名空间是否创建。AI 层API Key 能否调用或本地推理服务端口是否有响应。检查方式很简单一个 bash 脚本用nc -zv或curl判断端口。但从环境准备的角度把该自动化检查的内容自动化能极大降低团队的沟通成本。否则每天都会有人问“我的服务起不来怎么办”一问才发现 Redis 没装。6.2 Nacos 命名空间与分组一开始就规划好如果你直接把 QuickBlue 的服务配置全塞在 Nacos 默认 public 命名空间后面环境一多就乱套。环境准备阶段建议在 Nacos 里创建dev、test、prod三个命名空间每个服务的配置文件按namespace隔离。服务启动时通过spring.cloud.nacos.discovery.namespace和config.namespace指定。这一步没做好的后果是开发环境注册的服务被测试环境消费或者测试配置覆盖了本地配置各种跨环境事故频发。这些都是架构设计层面的事但根源是环境准备初期没有把命名空间模型确定下来。6.3 第一个 Demo 服务启动的完整验证线环境自检脚本通过之后用 QuickBlue 里的一个最简服务比如qb-gateway做一次端到端验证这是环境准备阶段的“验收测试”。启动流程确定 Nacos 控制台可访问确认dev命名空间 ID。启动qb-auth和qb-gateway两个服务。打开 Nacos 服务列表看到两个服务的健康实例。通过网关调用认证服务的健康检查接口curl http://localhost:8080/api/auth/health如果返回 JSON 结构体包含status:UP说明链路已经通了一半。再验证 Redis 缓存和 MySQL 连接调用一个会自动写缓存的查询接口看 Nacos 日志无异常就说明底座环境完全打通。我实际做这个验收的时候发现一个问题网关转发时需要配置跨域和服务名映射很多人只启动服务不配网关路由导致服务注册到 Nacos 了但外部根本访问不了。环境准备阶段一定要把网关路由和服务的对应关系也放进配置中心而不是只在本地 IDE 里改了测试。6.4 记录环境版本到一个文件最后一个小建议仓库根目录放一个ENV.md内容包括JDK、Maven、IDEA 版本。Docker 镜像加速地址和配置文件位置。Compose 启动命令和初始化脚本。K8s 集群安装方式。每个服务需要设置的环境变量名。这个文件不是摆设它是新人上手的第一份文档也是你几个月后自己排查环境问题时翻的第一份资料。我自己的体会是环境准备阶段最忌讳“我以为大家都会”的心态。QuickBlue 这套底座既然号称能快速部署那环境准备的产物就应该是可执行、可验证、可重复的脚本和文档而不是靠某个人脑子里的记忆。把本文这些步骤落地成目录和文件团队里任何一个人都能把环境拉起来后续开发效率会有质的提升。