Scala 云原生部署实战：容器化、健康检查与 Kubernetes 运维

- sbt-assembly：单 jar 交付，核心难点是 META-INF 合并冲突与 reference.conf 合并
- sbt-native-packager：JavaAppPackaging 生成 bin/ 启动脚本 + lib/ 依赖，DockerPlugin 可直接出镜像
- GraalVM native image：毫秒级启动、低内存，但反射与资源需配置，构建耗时长
- 分层镜像：依赖与业务代码分层，代码变更只重建最上层，推送体积下降一个数量级
- 版本号：镜像 tag 使用 git sha 或语义化版本，禁止只用 latest

// project/plugins.sbt
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "2.2.0")
addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.10.4")

// build.sbt：合并策略是 fat jar 成败的关键
ThisBuild / version := sys.env.getOrElse("GIT_SHA", "0.0.1-SNAPSHOT")

assembly / assemblyJarName := "scala-api.jar"
assembly / assemblyMergeStrategy := {
  case PathList("META-INF", "services", xs @ _*) => MergeStrategy.concat
  case PathList("META-INF", xs @ _*)             => MergeStrategy.discard
  case "reference.conf"                          => MergeStrategy.concat
  case _                                         => MergeStrategy.first
}

- 多阶段构建：构建阶段用 JDK，运行阶段只留 JRE，镜像通常可省 300MB 以上
- 基础镜像：eclipse-temurin:21-jre 稳妥；alpine 更小但 musl 对 glibc 依赖不友好，慎用
- jlink 裁剪：只保留应用实际用到的模块，运行时镜像可压到 80MB 以内
- 非 root：创建普通用户后 USER 切换，降低容器逃逸后的权限
- 层缓存：先 COPY 依赖描述文件跑一次解析，再 COPY 源码，改代码不重下依赖

#--- 构建阶段 ---
FROM eclipse-temurin:21-jdk AS builder
WORKDIR /src
COPY build.sbt ./
COPY project ./project
RUN sbt -batch update
COPY src ./src
RUN sbt -batch assembly

#--- 运行时阶段 ---
FROM eclipse-temurin:21-jre AS runtime
RUN groupadd -r app && useradd -r -g app -d /app app
WORKDIR /app
COPY --from=builder /src/target/scala-3.3.3/scala-api.jar /app/app.jar
RUN chown -R app:app /app
USER app
EXPOSE 8080
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "/app/app.jar"]

- UseContainerSupport：默认开启，JVM 读取 cgroup 内存上限而非宿主机物理内存
- MaxRAMPercentage：按 limit 的百分比设堆，比硬编码 Xmx 更适合弹性规格
- 堆外开销：Metaspace、直接内存、线程栈、JIT 代码缓存合计常占 20%~30%
- cgroup v2：Kubernetes 1.25+ 普遍启用，需 JDK 11.0.16+ 或 17.0.4+ 才正确识别
- CPU 限制：limit 过低会触发 CFS throttling，可用 ActiveProcessorCount 校正并行度
- GC 选择：堆小于 4G 且追求低延迟用 G1；大堆低延迟用 ZGC；单核小堆 Serial 反而更省

java \
  -XX:MaxRAMPercentage=75.0 \
  -XX:InitialRAMPercentage=50.0 \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+ExitOnOutOfMemoryError \
  -XX:NativeMemoryTracking=summary \
  -jar /app/app.jar

- resources：requests 决定调度，limits 决定上限，内存两者相等最稳
- 探针三件套：startup 保护慢启动，readiness 控制流量，liveness 负责重启
- terminationGracePeriodSeconds：必须大于应用排空连接所需时间
- topologySpreadConstraints：按 zone 打散，避免单可用区故障全量不可用
- PDB：配合节点排空，保证滚动维护时仍有可用副本
- HPA：基于 CPU 或自定义指标扩缩，需与 requests 联动才有意义

apiVersion: apps/v1
kind: Deployment
metadata:
  name: scala-api
spec:
  replicas: 3
  strategy:
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: scala-api
  template:
    metadata:
      labels:
        app: scala-api
    spec:
      terminationGracePeriodSeconds: 45
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: scala-api
      containers:
        - name: api
          image: registry.example.com/scala-api:1.4.2
          resources:
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              memory: "1Gi"
          env:
            - name: JAVA_TOOL_OPTIONS
              value: "-XX:MaxRAMPercentage=75"
          startupProbe:
            httpGet: { path: /health/live, port: 8080 }
            failureThreshold: 30
            periodSeconds: 2
          readinessProbe:
            httpGet: { path: /health/ready, port: 8080 }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /health/live, port: 8080 }
            periodSeconds: 10
            failureThreshold: 3

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: scala-api
spec:
  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: scala-api }
  minReplicas: 3
  maxReplicas: 12
  metrics:
    - type: Resource
      resource:
        name: cpu
        target: { type: Utilization, averageUtilization: 65 }

- liveness：进程是否还活着，失败即重启容器，绝不能检查下游依赖
- readiness：是否可以接收流量，失败仅从 Service Endpoints 摘除
- startup：启动是否完成，成功前不执行 liveness/readiness，专治慢启动
- 排空语义：收到 SIGTERM 后先置 ready=false，等待 Endpoint 摘除，再关闭监听
- 关闭顺序：停止接收新请求 → 排空在途请求 → 关闭连接池 → 退出进程

import cats.effect.*
import org.http4s.*
import org.http4s.dsl.io.*

// http4s 风格的探针路由：live 只证明进程存活，ready 反映真实可用性
def healthRoutes(readiness: Ref[IO, Boolean]): HttpRoutes[IO] = HttpRoutes.of[IO] {
  case GET -> Root / "health" / "live" =>
    Ok("ok")
  case GET -> Root / "health" / "ready" =>
    readiness.get.flatMap {
      case true  => Ok("ready")
      case false => ServiceUnavailable("draining")
    }
}

import akka.actor.CoordinatedShutdown

// Akka HTTP：先摘流量，再在解绑监听前完成连接排空
CoordinatedShutdown(system).addTask(
  CoordinatedShutdown.PhaseBeforeServiceUnbind, "drain"
) { () => readyFlag.set(false); binding.flatMap(_.terminate(30.seconds)).map(_ => Done) }

- 优先级：命令行参数 > 环境变量 > 挂载配置文件 > 打包内默认值
- ConfigMap：非敏感配置，可整目录挂载，更新后文件同步但需应用自行 reload
- Secret：base64 编码并非加密，务必开启 etcd 静态加密与 RBAC 最小权限
- 外部化：数据库、下游地址全部走配置，镜像做到「一次构建，多环境运行」
- 版本化：配置纳入 Git 管理，变更走 PR 与灰度，而非直接 kubectl edit

apiVersion: v1
kind: ConfigMap
metadata:
  name: scala-api-config
data:
  application.conf: |
    http.port = 8080
    db.pool.size = 16
    feature.new-pipeline = false
---
apiVersion: v1
kind: Secret
metadata:
  name: scala-api-secret
type: Opaque
stringData:
  db.password: change-me-in-vault

import pureconfig.*
import pureconfig.generic.derivation.default.*

case class DbConfig(url: String, user: String, password: String, poolSize: Int)
    derives ConfigReader

// 启动即解析，失败直接终止，避免带着半截配置对外服务
val db: DbConfig = ConfigSource.default.at("db").loadOrThrow[DbConfig]

- 日志：JSON 结构化输出到 stdout，由采集器统一收走，禁止写文件
- 指标：Prometheus 端点暴露 JVM、HTTP、连接池与业务指标
- 链路：OpenTelemetry javaagent 零代码侵入，W3C traceparent 贯穿上下游
- 关联：日志中带上 traceId，实现「指标发现异常 → 链路定位 → 日志下钻」
- 基数控制：标签不要用用户 ID、请求 ID 等高基数字段

env:
  - name: JAVA_TOOL_OPTIONS
    value: >-
      -XX:MaxRAMPercentage=75
      -Xlog:gc*:stdout:time,uptime,level,tags
  - name: OTEL_SERVICE_NAME
    value: scala-api
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://otel-collector:4317

- 滚动更新：默认策略，maxUnavailable=0 配合 readiness 可做到零中断
- 蓝绿：两套完整环境切换 Service，回滚最快，但资源成本翻倍
- 金丝雀：按流量比例逐步放量，配合指标断言自动回滚
- 数据库兼容：expand-contract 三步走，先加列、双写、再删旧列
- 回滚前提：镜像 tag 不可变，配置可回退，迁移脚本必须向前兼容
- 版本可观测：请求头或日志中带上版本号，便于按版本切分指标

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: scala-api
spec:
  replicas: 6
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: { duration: 5m }
        - analysis: { templates: [{ templateName: error-rate }] }
        - setWeight: 50
        - pause: { duration: 10m }

- 启动慢：多为 JIT 预热与大量反射扫描，可用 CDS/AppCDS 或 native image 改善
- OOMKilled：先看堆外内存与堆大小之和是否超过 limit，再看是否存在泄漏
- 连接泄漏：数据库与 HTTP 客户端连接池必须有上限与超时
- 混沌演练：定期注入 Pod 删除、网络分区、依赖超时，验证降级与自愈
- 成本优化：按实际用量调 requests、开启 HPA、低峰缩容到最小副本
- Serverless：Knative 需配合 scale-to-zero，冷启动敏感的 Scala 服务更适配 native image