28|容器化与部署:从本地到可交付
你好,我是Robert。
Hify的所有功能开发完了,测试也补了。但它现在只能在你的开发机上跑,换一台机器就要装JDK、装Node.js、配环境变量,折腾半天。
这一讲把它变成可交付的。和之前学RAG一样,你不需要懂Dockerfile和K8s YAML的语法细节,用自然语言告诉Claude Code你要什么,它帮你生成,你执行命令就行。
先和Claude Code讨论部署形态
不急着生成任何文件。先用咨询模式和Claude Code讨论清楚要支持哪些部署形态,有什么需要提前准备的。
Hify 是一个 Spring Boot + Vue 的 AI 应用,
后端调用外部 LLM API,依赖 MySQL、Redis、pgvector,
目标用户是企业内部团队,规模从几人到几十人不等。
我想把它做成可交付的形态,方便部署到不同环境。
帮我分析应该支持哪些部署形态,以及每种形态需要提前准备什么。
不要写任何代码,先给我分析。
Claude Code的分析给出了三种部署形态,以及每种形态需要准备的内容。
形态一:tar.gz本地部署
适合客户内网无Docker、纯Linux环境,运维能力弱的场景。
需要准备:fat jar + 前端dist、application.yml配置模板、start.sh / stop.sh / status.sh、Nginx配置模板(含SSE配置)、数据库初始化schema.sql。目标机器需要自行安装JRE 17+、MySQL、Redis、PostgreSQL + pgvector。
形态二:Docker部署
适合有Docker环境的技术型中小团队。
需要准备:前后端各自的Dockerfile(多阶段构建)、docker-compose.yml、.env模板。pgvector有官方镜像 pgvector/pgvector:pg16,比本地部署友好很多。
形态三:K8s部署
适合有K8s集群、追求高可用的企业。
需要准备:Deployment、Service、ConfigMap、Secret、Ingress等YAML文件。MySQL/Redis通常复用客户已有实例,pgvector需要单独处理。
Claude Code还给出了三种形态的横向对比和建议优先级: 先做Docker(投入产出比最高)、再做tar.gz(面向传统企业)、最后做K8s(复用Docker镜像)。这里我们按照从简单到复杂的顺序来做。
Claude Code主动提出的四个确认问题:
MySQL、Redis、pgvector是跟Hify一起部署,还是连接已有的外部服务?外部服务,通过配置连接
目标机器有没有Java环境?有,不需要打包JDK
Docker部署是否把数据库也包进去?不包含,只部署Hify自身
当前Hify有没有HTTP健康检查接口?三种部署形态都需要它,本地部署用来确认服务起来了,Docker用来做healthcheck指令,K8s用来做存活和就绪探针。如果没有,需要先补。
前三个问题确定了部署边界,第四个是我没想到的遗漏,Claude Code主动提醒了一个前置工作。这是咨询模式的价值:不是让AI直接执行,而是先讨论清楚,让它帮你发现遗漏,再动手。
先补健康检查接口
Claude Code提醒了,先把前置工作做完,再做部署。
帮 Hify 加一个健康检查接口 GET /api/v1/health,
返回 HTTP 200 和 {"code":0,"data":"ok"}。
这个接口会被三个地方用到:
- 本地部署:启动后 curl 确认服务起来了
- Docker:healthcheck 指令
- K8s:liveness 和 readiness 探针
接口本身只需要返回 ok,不需要检查数据库连接。
Claude Code没有直接生成代码,而是先扫描了项目,发现 HealthController.java 已经存在了,接口也有。但它主动发现了一个格式不一致的问题:
现有接口返回的是 {"code":200,"message":"success","data":"ok"},和要求的 {"code":0,"data":"ok"} 有差异,code值不同,多了message字段。
Claude Code给出了两个选项:
保持现状:健康检查场景里curl/Docker/K8s只看HTTP状态码,不解析body,code值无所谓。
改成code:0:需要改动,但会影响所有接口的响应格式。
Claude Code的建议是,选1,不必为健康检查改全局响应格式。
确认选1之后,Claude Code直接修改了 HealthController.java,在这个接口单独返回 Map.of("code", 0, "data", "ok"),不动全局 Result 类,改动最小。
顺带给出了三种部署形态下怎么使用健康检查接口的方式:
- tag.gz形态
curl -f http://localhost:8080/api/v1/health
- Docker形态
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD curl -f http://localhost:8080/api/v1/health || exit 1
- K8s形态:
# K8s probe
livenessProbe:
httpGet:
path: /api/v1/health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /api/v1/health
port: 8080
initialDelaySeconds: 10
periodSeconds: 5
这个交互有两个值得注意的点:第一,Claude Code没有盲目执行,而是先查了项目里有没有,避免重复创建;第二,发现格式不一致后主动问了你,没有自作主张改全局格式。这是咨询模式和执行模式结合的正确节奏。
本地部署:打成tar包
本地部署的目标:一个tar包,解压、填配置、执行start.sh,服务跑起来。目标机器只需要有Java环境。
帮 Hify 生成本地部署的打包脚本。
要求:
- 产物是一个 tar 包,包含:后端 jar、前端 dist 目录、start.sh、stop.sh、配置模板 application.yml
- 目标机器已有 Java 环境,不需要打包 JDK
- start.sh 支持通过环境变量或配置文件注入 MySQL、Redis、pgvector 的连接信息
- stop.sh 优雅停止,等待进程退出
- Makefile 加 package 命令,一键打包
不需要包含 MySQL、Redis、pgvector,它们是外部服务。
Claude Code没有直接生成脚本,而是先读了现有的start.sh、stop.sh、Makefile和application.yml,发现:现有start.sh是开发模式,跑的是 mvn build + npm dev server,不适合生产部署,需要完全重写。
确认情况后,CC生成了五个文件:
1. start.sh(完全重写)
生产模式直接运行jar,不再跑mvn/npm。关键逻辑:
启动前检查Java版本是否17+,jar文件是否存在
自动加载同目录的
.env文件,再接受环境变量覆盖外部
application.yml优先级高于jar内置配置启动后轮询
/api/v1/health确认就绪,最多等90s;进程异常退出会立即打印最后30行日志
2. stop.sh(精简)
去掉了前端进程管理,只管后端。发SIGTERM,等最多30s,超时强制SIGKILL。
3. deploy/application.yml.template
打包时复制为application.yml,所有连接信息用 ${ENV_VAR:default} 占位符,用户只需要填实际的地址和密码。
4. deploy/env.template
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=hify
DB_USERNAME=hify
DB_PASSWORD=your_mysql_password
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
JVM_OPTS=-Xms256m -Xmx512m
用户解压后 cp env.template .env,填好密码就可以启动。
5. Makefile的package命令
make package 先触发 build(编译后端 + 打包前端),再把产物打成tar包:
hify-0.0.1-SNAPSHOT/
├── hify-app.jar # 后端 fat jar
├── web/ # 前端静态文件,给 Nginx 托管
├── start.sh
├── stop.sh
├── application.yml # 配置模板
└── env.template # 环境变量模板
目标机器的部署流程:
tar -xzf hify-0.0.1-SNAPSHOT.tar.gz
cd hify-0.0.1-SNAPSHOT
cp env.template .env && vi .env # 填写 DB/Redis 密码
bash start.sh
start.sh启动后会自动轮询健康检查接口,就绪了打印“Hify启动成功”,失败了打印日志告诉你哪里出了问题。
Docker部署:Dockerfile + docker-compose
Docker部署的目标:两个Dockerfile分别打包前后端镜像,一条命令启动。
后端Dockerfile
帮我写 Hify 后端的 Dockerfile。
情况说明:
- Maven 多模块项目,主模块是 hify-app
- JDK 17
- 不需要打包 MySQL、Redis、pgvector,它们是外部服务
要求:
- 多阶段构建,减小镜像体积
- 非 root 用户运行(安全最佳实践)
- 健康检查用 /api/v1/health 接口
Claude Code生成的后端Dockerfile有几个值得关注的细节:
层缓存优化:先单独Copy所有pom文件执行
dependency:go-offline,再Copy源码编译。依赖没变时直接命中缓存,省去3-5分钟下载时间。运行阶段还用了Spring Boot layertools把jar拆成四层(dependencies → loader → snapshot-dependencies → application),每次只改业务代码时只有最后一层失效。安全:构建用JDK alpine,运行只用JRE alpine,镜像体积差约200MB。
addgroup/adduser创建无home目录、无shell的系统用户,进程以非root运行。加了-Djava.security.egd=file:/dev/./urandom,避免容器内熵不足导致启动慢。健康检查:用
wget(alpine内置)而非curl(需额外安装),减少镜像层。--start-period=60s给Spring Boot足够的初始化时间,这段时间内失败不计入重试。外部配置注入:挂载
/app/config/application.yml覆盖内置配置,用optional:前缀保证没挂载时也能启动。
前端Dockerfile
帮我写 Hify 前端的 Dockerfile。
情况说明:
- Vue 3 项目,npm run build 打包
- 用 Nginx 托管静态文件
- 前端需要把 /api 请求反向代理到后端
特别注意:
- Hify 有流式响应(SSE),Nginx 需要关闭缓冲
- LLM 调用可能很慢,超时时间要够长
Claude Code先读了 package.json 和 vite.config.ts 确认项目结构,然后生成了两个文件。
前端Dockerfile同样两阶段:Node镜像打包出dist,只把dist复制进Nginx镜像,最终运行镜像约40MB,不含Node.js。
Nginx配置是关键,Claude Code给出了几个针对Hify的特殊处理:
location /api/ {
proxy_pass http://backend:8080;
# LLM 调用可能很慢,给足超时时间
proxy_read_timeout 120s;
# SSE 必须关闭缓冲,否则事件被攒批,前端收不到实时流
proxy_buffering off;
proxy_cache off;
# SSE 长连接保活
proxy_set_header Connection "";
}
proxy_buffering off 是SSE的关键,如果不关,Nginx会把事件攒批后一次性发出,用户看不到打字机效果,要等LLM全部输出完才能看到内容。 proxy_read_timeout 120s 比后端超时稍长,避免Nginx先断连。
proxy_pass http://backend:8080 用的是Docker网络服务名,和后面docker-compose里的服务名直接对应。
生成docker-compose.yml
帮我生成 Hify 的 docker-compose.yml。
要求:
- 包含前端和后端两个服务
- MySQL、Redis、pgvector 是外部服务,通过环境变量配置连接地址
- 后端健康检查用 /api/v1/health 接口
- 前端依赖后端健康检查通过后才启动
- 敏感配置(密码、API Key)从 .env 文件读取攒批
Claude Code先读了env.template确认变量名,再生成docker-compose.yml,同步更新了 .env模板加入Docker特有的端口映射变量。
几个值得注意的设计:
depends_on: condition: service_healthy:前端容器等后端健康检查通过后才启动,避免Nginx上线时后端还没就绪就开始接流量,出现502。敏感配置隔离:docker-compose.yml里只写变量名,所有密码和地址从 .env 读取,.env 不进 git。
外部服务不能用localhost:MySQL/Redis/pgvector完全不在compose里定义,只传连接地址。Claude Code在注释里特别提醒:目标机器上的外部服务要用真实IP,不能用localhost,容器内的localhost是容器自身,不是宿主机。
端口映射可配置:宿主机80/8080被占时,只改 .env里的
FRONTEND_EXPOSE_PORT/BACKEND_EXPOSE_PORT,不需要动compose文件。
启动方式:
cp deploy/env.template .env
vi .env # 填写真实 IP 和密码
docker compose up -d --build
docker compose ps # 确认两个服务都 Running
docker compose logs -f backend # 看后端启动日志
K8s部署
K8s部署的目标:前后端各自的Deployment和Service,加上Secret和ConfigMap管理配置,共六个文件。
后端Deployment和Service
帮我写 Hify 后端的 K8s 部署文件,包含 Deployment 和 Service。
要求:
- 初始 2 个副本,支持水平扩容
- 配置和密码从 ConfigMap 和 Secret 读取,不硬编码在镜像里
- liveness 和 readiness 探针都用 /api/v1/health 接口
- 设置资源限制,防止单个 Pod 占用过多资源
- Service 类型 ClusterIP,不对外暴露,只在集群内访问
前端Deployment和Service
帮我写 Hify 前端的 K8s 部署文件,包含 Deployment 和 Service。
要求:
- 初始 2 个副本
- 资源需求比后端小(Nginx 托管静态文件)
- Service 类型 NodePort,对外暴露访问
Claude Code生成前端文件前先读了已有的后端Service,确认命名风格和namespace保持一致。
前后端资源配置对比:

Nginx只做静态文件托管 + 反向代理,不跑JVM,资源需求低一个数量级。前端探针的 initialDelaySeconds 也比后端短很多,Nginx秒级启动,不需要等60s。
探针路径用 /api/v1/health 而不是 /:前端健康检查通过Nginx代理探后端接口,同时验证了静态托管和API代理两条路径都通,比只探 / 更有价值。
前端Service用 NodePort: 30080,访问方式是 http://<任意节点IP>:30080。端口冲突时只改这一个字段。
Secret和ConfigMap
帮我生成 K8s 的 Secret 和 ConfigMap 模板。
Secret 存储:数据库密码、Redis 密码、pgvector 密码、OpenAI API Key
ConfigMap 存储:数据库地址端口、Redis 地址端口、pgvector 地址端口
Claude Code先读了已有文件,发现Secret里缺少 OPENAI_API_KEY,直接在原文件上更新,同时修改了backend-deployment.yml把新增的key注入进去。
ConfigMap填好地址后直接apply:
vi deploy/k8s/backend-configmap.yml # 填写真实 host
kubectl apply -f deploy/k8s/backend-configmap.yml
Secret通过CI/CD环境变量注入,不把密码写进文件:
kubectl create secret generic hify-backend-secret \
--from-literal=DB_PASSWORD=$DB_PASSWORD \
--from-literal=REDIS_PASSWORD=$REDIS_PASSWORD \
--from-literal=PGVECTOR_PASSWORD=$PGVECTOR_PASSWORD \
--from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \
-n hify --dry-run=client -o yaml | kubectl apply -f -
--dry-run=client -o yaml | kubectl apply -f - 这个写法支持幂等更新,Secret已存在时会覆盖而不报错,适合CI/CD每次部署时执行。
所有文件放在 deploy/k8s/ 下:
deploy/k8s/
├── backend-deployment.yml
├── backend-service.yml
├── frontend-deployment.yml
├── frontend-service.yml
├── backend-configmap.yml
└── backend-secret.yml
执行与验收
三种形态的执行命令。
本地部署:
make package # 打包成 tar.gz
scp hify-*.tar.gz user@target-server:~ # 传到目标机器
ssh user@target-server
tar -xzf hify-*.tar.gz && cd hify-*
cp env.template .env && vi .env # 填写 DB/Redis 密码
bash start.sh # 启动,自动轮询健康检查
Docker部署:
docker compose build # 构建镜像
cp deploy/env.template .env && vi .env # 填写外部服务地址和密码
docker compose up -d # 启动
docker compose ps # 确认两个服务都 Running
docker compose logs -f backend # 看启动日志
K8s部署:
kubectl create namespace hify
vi deploy/k8s/backend-configmap.yml # 填写外部服务地址
kubectl apply -f deploy/k8s/backend-configmap.yml
# Secret 通过环境变量注入,不写进文件
kubectl create secret generic hify-backend-secret \
--from-literal=DB_PASSWORD=$DB_PASSWORD \
--from-literal=PGVECTOR_PASSWORD=$PGVECTOR_PASSWORD \
--from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \
-n hify --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f deploy/k8s/ # 部署所有资源
kubectl get pods -n hify # 确认 Pod 都 Running
kubectl scale deployment hify-backend --replicas=4 -n hify # 按需扩容
验收流程(三种形态统一):
服务起来后,走一遍完整链路
创建Provider,测试LLM连通性
创建Agent,发消息确认流式响应正常(打字机效果)
上传知识库文档,提问验证RAG检索注入
配置工作流,测试CONDITION分支路由
绑定MCP工具,查询订单
全部通过,Hify从“只能在你机器上跑”变成了“任何环境都能部署”。
总结
这一讲做完,deploy目录下多了这些东西,里面的内容我就不展开讲了,你可以去看一下源码。
.
├── Dockerfile 后端镜像
├── docker-compose.yml
├── Makefile 含 package / docker-build 命令
├── start.sh / stop.sh 本地部署脚本(完全重写为生产模式)
├── hify-*/ 各业务模块
├── hify-web/
│ └── Dockerfile 前端镜像
└── deploy/
├── application.yml.template 本地部署配置模板
├── env.template 环境变量模板(本地 + Docker 通用)
├── docker/
│ └── nginx.conf 前端 Nginx 配置
└── k8s/
├── backend-configmap.yml
├── backend-secret.yml
├── backend-deployment.yml
├── backend-service.yml
├── frontend-deployment.yml
└── frontend-service.yml
零基础手写配置文件,你做了三件事: 用自然语言描述需求、检查Claude Code生成结果的关键点、按顺序执行命令。
有一个细节值得回味:健康检查接口不是我们一开始就想到的,是Claude Code在讨论部署形态时主动提出来的。而且在补接口时,Claude Code没有直接生成新文件,而是先扫了项目发现接口已存在,发现格式不一致后问了你再改。生成Dockerfile时读了package.json和vite.config.ts,生成docker-compose时读了env.template确认变量名。
这是我这一讲真正想说的:AI不只是代码生成器,用对了是协作者。咨询模式让它帮你发现遗漏,执行前让它先读项目了解上下文,每一步它都在基于你的实际情况做决策,而不是套模板输出。
思考题
当前的部署流程是手动的,每次更新代码要手动build、push、apply。让Claude Code帮你写一个GitHub Actions workflow,推送到main分支后自动构建镜像并部署到K8s。描述你的需求,看它生成的YAML是否可以直接用,有哪些地方需要你来判断和调整。
K8s Secret默认只是base64编码,不是加密。让Claude Code帮你了解更安全的方案,比如sealed-secrets或云厂商的密钥管理服务,对比一下各自的成本和适用场景,看哪种适合Hify的目标用户。
期待你的分享!如果今天的课程让你有所收获,也欢迎转发给有需要的朋友,邀请他来一起学习,我们下节课再见!