🎯 今日核心问题

  1. 一个 Spring Boot Agent 服务的镜像怎么做到 200MB 以内、启动 10 秒内?
  2. API Key 不进镜像、不进 Git、不进日志,那它到底放在哪、怎么轮换?
  3. 只有一台服务器,也要有的最小可观测是什么?

📖 精读提纲

【一】镜像:分层缓存决定你一天部署几次

三个动作把镜像从 700MB 压到 180MB 左右、构建从三分钟压到二十秒:

  1. 多阶段构建:maven:3.9-eclipse-temurin-17 负责编译,eclipse-temurin:17-jre-alpine 只装 JRE,源码和 Maven 仓库不进最终镜像。
  2. 先拷 pom 再拷源码:COPY pom.xml → mvn dependency:go-offline → 再 COPY src。改代码时依赖层命中缓存,这是最有效的一招。
  3. 非 root 运行 + JAVA_TOOL_OPTIONS:容器里用 appuser,JVM 参数走环境变量而不是写死在 ENTRYPOINT,方便演示机和服务器共用一套镜像。

【二】密钥:三道闸门

轮换的做法:配置两个 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 的第一屏决定招聘方给不给你面试。