🎯 今日核心问题
- 一个 Spring Boot Agent 服务的镜像怎么做到 200MB 以内、启动 10 秒内?
- API Key 不进镜像、不进 Git、不进日志,那它到底放在哪、怎么轮换?
- 只有一台服务器,也要有的最小可观测是什么?
📖 精读提纲
【一】镜像:分层缓存决定你一天部署几次
三个动作把镜像从 700MB 压到 180MB 左右、构建从三分钟压到二十秒:
- 多阶段构建:
maven:3.9-eclipse-temurin-17负责编译,eclipse-temurin:17-jre-alpine只装 JRE,源码和 Maven 仓库不进最终镜像。 - 先拷 pom 再拷源码:
COPY pom.xml→mvn dependency:go-offline→ 再COPY src。改代码时依赖层命中缓存,这是最有效的一招。 - 非 root 运行 +
JAVA_TOOL_OPTIONS:容器里用appuser,JVM 参数走环境变量而不是写死在 ENTRYPOINT,方便演示机和服务器共用一套镜像。
【二】密钥:三道闸门
- 代码层:配置只用
@ConfigurationProperties绑定,值来自环境变量;启动时校验非空(@Validated @NotBlank),缺密钥直接启动失败,而不是跑到线上才发现 401。 - 运行层:compose 用
env_file: .env,.env写进.gitignore;生产用宿主机的/etc/agent/agent.env(600 权限)或 Docker secrets。镜像里永远grep不到 key。 - 日志层:加一个
MaskingFilter,对sk-、Bearer、手机号做正则替换。密钥泄漏最常见的路径不是仓库,是异常堆栈和curl -v打出来的日志。
轮换的做法:配置两个 key 环境变量(主/备),启动时读主,429 或 401 时自动切备并告警。这也顺带解决了单 key 限流的问题。
【三】健康检查与优雅停机
/actuator/health 要区分 liveness 与 readiness:liveness 只看进程活着,readiness 还要检查数据库和模型端点可达。readiness 挂了不该重启容器,只该摘流量。
优雅停机必配 server.shutdown=graceful + spring.lifecycle.timeout-per-shutdown-phase=30s。Agent 请求动辄十几秒,没有优雅停机,每次发版都会砍掉一批正在跑的 trace,用户看到的就是「系统繁忙」。
【四】最小可观测:四个指标 + 一份日志
指标只上四个就能覆盖 90% 的故障定位:agent.request.count(按 status 分)、agent.latency.p95、agent.steps.avg(步数突增说明模型在打转)、agent.tool.fail.rate(按工具名分)。用 Micrometer 暴露 /actuator/prometheus,compose 里挂个 Prometheus 就够演示了。
日志用 JSON 格式,每条至少带 traceId、stepNo、toolName、latencyMs。用户报障时拿 traceId 一条 grep 就能还原全链路,D3 落的那两张表才有意义。再补一条:告警只配两条——P95 连续五分钟翻倍、工具失败率单工具超过 10%。告警多了没人看。
💻 代码示例
Dockerfile(多阶段、分层缓存、非 root):
# ---- build ----
FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /workspace
COPY pom.xml .
RUN mvn -B -q dependency:go-offline
COPY src ./src
RUN mvn -B -q clean package -DskipTests
# ---- runtime ----
FROM eclipse-temurin:17-jre-alpine
RUN addgroup -S app && adduser -S -G app app
WORKDIR /app
COPY --from=build /workspace/target/agent-*.jar app.jar
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+UseG1GC" \
TZ=Asia/Shanghai
USER app
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
CMD wget -qO- http://127.0.0.1:8080/actuator/health/liveness || exit 1
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
docker-compose.yml(含依赖、密钥外置、健康检查):
services:
agent:
build: .
image: example/agent:0.8.0
env_file: .env
environment:
SPRING_PROFILES_ACTIVE: prod
LLM_API_KEY: ${LLM_API_KEY}
LLM_API_KEY_BACKUP: ${LLM_API_KEY_BACKUP}
SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/agent?useUnicode=true&characterEncoding=utf8
MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE: health,prometheus,metrics
ports:
- "8080:8080"
depends_on:
mysql:
condition: service_healthy
restart: unless-stopped
stop_grace_period: 35s
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/actuator/health/readiness"]
interval: 30s
timeout: 5s
retries: 3
start_period: 40s
mysql:
image: mysql:8.0
environment:
MYSQL_DATABASE: agent
MYSQL_USER: agent
MYSQL_PASSWORD: ${DB_PASSWORD}
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
volumes:
- mysql-data:/var/lib/mysql
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-p${DB_ROOT_PASSWORD}"]
interval: 10s
timeout: 5s
retries: 10
prometheus:
image: prom/prometheus:v2.53.0
volumes:
- ./deploy/prometheus.yml:/etc/prometheus/prometheus.yml:ro
ports:
- "9090:9090"
volumes:
mysql-data:
启动前校验密钥,缺了直接失败:
@ConfigurationProperties(prefix = "llm")
@Validated
public record LlmProperties(@NotBlank String baseUrl, @NotBlank String apiKey,
String apiKeyBackup, Duration timeout) {}
【五】资源与成本
JVM 设 -XX:MaxRAMPercentage=75 而不是绝对值。堆外还有 direct buffer、元数据、线程栈,容器限 1GB 而 -Xmx1g 一定被 OOMKill。
Agent 的特性是延迟长、并发低:单请求 5–8 秒,50 并发就需 50 个线程,Tomcat 默认 200 够用,但 HikariCP 默认 10 会成为瓶颈。做法是把工具里的数据库调用做成短事务,绝不在事务里调模型。成本记一个数:单次工单 3.2k 输入 + 0.4k 输出 token。把「每个请求烧多少 token」当成和 QPS 一样的常规指标看,是 Agent 服务跟普通 CRUD 服务最大的区别——一次模型打转能烧掉平常一天的钱。
【六】演示环境
跑在便宜的云主机上配固定域名,本地留一份 demo profile 用 Ollama 兜底。演示只走三条路径:正常查询、两次工具调用、工具失败降级。故意演示失败路径是加分项,因为它证明你不怕被追问边界。再准备一份预录 trace,现场网络不通时直接讲链路,比干讲强。
✏️ 今日动手
docker compose up -d 起全栈,docker image ls 记下镜像体积;docker logs 里 grep 一次 key 确认打码生效;用 docker stop 触发优雅停机,观察日志里在途请求是否正常返回。
🔖 明日预告
能跑、能看、能停。明天写给人看的东西:README 的第一屏决定招聘方给不给你面试。