项目初始化

2026-09-25 使用 start.spring.io API 生成，选择当时默认正式版 Spring Boot 4.1.1、 Java 25、Gradle Groovy DSL、YAML 配置和 Jar。应用包名为 top.ddupan.iam.login。

curl -fsSLG https://start.spring.io/starter.zip \
  --data-urlencode type=gradle-project \
  --data-urlencode language=java \
  --data-urlencode bootVersion=4.1.1 \
  --data-urlencode javaVersion=25 \
  --data-urlencode groupId=top.ddupan.iam \
  --data-urlencode artifactId=iam-login \
  --data-urlencode name=iam-login \
  --data-urlencode packageName=top.ddupan.iam.login \
  --data-urlencode 'description=Independent IAM login and authentication service for Hydra' \
  --data-urlencode packaging=jar \
  --data-urlencode configurationFileFormat=yaml \
  --data-urlencode dependencies=native,devtools,lombok,configuration-processor,web,security,spring-security-webauthn,data-ldap,validation,actuator,prometheus,opentelemetry,distributed-tracing,unboundid-ldap,testcontainers \
  -o iam-login-starter.zip

生成器提供 Gradle Wrapper、应用入口、上下文测试、依赖和 Native 构建插件。为生成的 .gitignore 补充秘密文件与日志忽略规则，以中文项目文档替代生成器的 HELP.md。 Initializr 的可选版本会变化，未来可能需要调整请求；已提交源码、Gradle Wrapper 与插件版本是构建依据。

LDAP 和 WebAuthn 依赖尚未配置为真实认证流程；数据库和 MFA 凭据持久化随首轮实现引入。 Actuator 与 Prometheus 依赖存在不等于监控端点已按生产策略开放。

骨架验证

构建环境为 ghcr.io/graalvm/native-image-community:25，固定 digest： sha256:0d936f32bb8acb5bc60c41b33e05f064d7a6aaf36b726538296c54949bd4a3c0。

验证分为 test（JVM）、testAot（JVM 上的 AOT 上下文）、nativeTest（原生测试）和应用二进制 HTTP 检查。JVM/AOT/Native 测试均使用真实 LGTM Testcontainer，显式初始化指标、追踪导出器，并验证容器连接与 CPU 时间读取。结果随 PR 记录。这些检查不连接真实 AD 或 Hydra，也不验证 MFA。

Docker 开发与 Gradle 缓存

Linux 主机示例：将缓存保留在宿主机用户缓存目录，避免每次临时容器重新下载 Wrapper、插件和依赖。项目工作目录也需要挂载，以保留 build/ 和项目级 .gradle/。

scripts/gradle-in-docker test testAot
scripts/gradle-in-docker nativeTest nativeCompile
python3 scripts/native-smoke.py

scripts/gradle-in-docker 默认挂载 ${XDG_CACHE_HOME:-$HOME/.cache}/iam-login/gradle 到容器 /gradle，并设置 Gradle 缓存与构建用户目录到该目录，避免无 passwd 条目的宿主 UID 导致 Testcontainers 向项目内的 ?/ 写配置。原生测试同时显式传入 user.home。可通过 IAM_GRADLE_CACHE 覆盖宿主路径；默认限制 4 CPU、8 GiB 内存，可通过 IAM_BUILD_CPUS、IAM_BUILD_MEMORY 调整。需要 sudo 才能访问 Docker 时设置 IAM_DOCKER_USE_SUDO=1；只提升 Docker 命令权限，容器内仍使用当前用户 UID/GID。

宿主机 Docker socket 供 Testcontainers 使用，host network 让测试能访问它启动的动态端口。 Docker Desktop 的网络方式需按平台调整。首次本地验证使用 /tmp/iam-login-gradle 作为上述缓存目录，未写入仓库；长期开发使用持久缓存目录。构建容器使用宿主 UID/GID，避免产物和缓存变为 root 所有。

原生启动检查

native-smoke.py 在 Linux 上直接启动 build/native/nativeCompile/iam-login ELF 文件，不调用 Java。需要 Python 3 标准库及编译产物依赖的系统库；监听随机 loopback 端口，结束时清理进程，并检查包括关闭阶段在内的 Native 注册错误；结果保存在 build/reports/native-smoke/。

检查匿名 liveness 端点、应用与指标端点拒绝匿名访问、使用临时测试凭据读取 Prometheus，以及健康请求的 HTTP 计数器增长。记录二进制大小、可响应耗时和请求后 RSS；这些单次数据不是负载基准或资源预算。脚本不请求依赖目录的聚合健康端点，不验证目录就绪、MFA、Hydra 或追踪导出。

应用在构建期声明 health、prometheus 暴露范围与健康探针。默认安全配置继续保护指标端点；liveness 使用应用可用性状态，不把尚未配置 AD 的聚合健康状态描述为正常。

AOT 测试与容器连接

初始生成的 @Bean + @ServiceConnection 测试配置在 Boot 4.1.1 的 Native 测试中出现过缺少 OtlpLoggingConnectionDetails 的启动失败。测试改用类静态字段上的 @Container + @ServiceConnection，由测试上下文在运行时重建连接信息，并断言日志导出 URL 指向本次运行的 LGTM 容器。JVM 开发入口仍使用原有配置类。

testAot 使用生成的 AOT 测试上下文在 JVM 中运行，可先发现 AOT 装配错误；它不替代 nativeTest。Native 测试二进制启用 quickBuild 降低编译成本，应用 nativeCompile 保持默认优化；启动和内存数据必须来自应用二进制，不能取测试二进制的数据。

参考 Spring Boot Testcontainers 与 Native Build Tools Gradle 配置。

Native 反射元数据

Micrometer OTLP 使用的 Protobuf 4.35.1 通过反射调用 ExtensionRegistry 的 getEmptyRegistry() 与 newInstance()。实际原生应用启动曾因前一个方法缺少注册而失败，项目的 reachability-metadata.json 中对 Protobuf 只补充这两个工厂方法。升级依赖时应重新验证能否移除。

上下文测试显式启用 @AutoConfigureMetrics 与 @AutoConfigureTracing，初始化真实导出器，避免 Spring 测试默认关闭导出导致 Native 问题漏测。它验证初始化及容器连接信息，完整的 OTLP 数据接收、持久化和查询验收仍属后续观测性集成测试。

Micrometer 1.17.1 自带的反射声明已覆盖 CPU 使用率和文件描述符读取，但遗漏了 OperatingSystemMXBean.getProcessCpuTime()。项目只补这一项；回归测试直接读取 Prometheus 注册器中的 CPU 时间计数器并断言数值有效，避免后台导出异常被误报为测试通过。其他 JVM 指标在 Native 中的语义仍需分别验证，不能保证 HotSpot 仪表盘完全适用。

2026-09-25 本地验证结果

代码版本 4c7be4c，Java/GraalVM 25.0.2、Gradle 9.7.1，Linux amd64，Native 目标 x86-64-v3。构建容器限制 4 CPU、8 GiB；应用使用默认 O2 优化，测试镜像使用 quickBuild。

验证	结果
JVM `test`	2 成功，0 失败，0 跳过
JVM AOT `testAot`	2 成功，0 失败，0 跳过
`nativeTest`	2 成功，0 失败，0 跳过；包含真实导出器初始化及 CPU 时间读取
`nativeCompile`	成功；生成独立 ELF，动态链接 libc、libz
原生应用 liveness	UP
匿名应用／指标请求	401
带临时测试凭据的 Prometheus 请求	200
额外 3 次 liveness 请求	HTTP 计数器增加 3
运行及关闭阶段 Native 注册错误	未发现
启动至首次 liveness 响应	0.582 秒
请求后进程 RSS	144.56 MiB
ELF 文件大小	119.88 MiB

这是一次本地 smoke 测量，启动耗时含检查器轮询，RSS 不是峰值或负载预算，ELF 大小不等于运行镜像大小。未验证 AD、MFA、Hydra、目录就绪或 OTLP 后端数据查询，也尚未接入 CI。运行报告生成在 build/reports/native-smoke/result.json，不提交运行日志或构建产物。

手写 Native 补丁位于 META-INF/native-image/top.ddupan.iam/iam-login-manual/，与 Spring AOT 生成的 iam-login/ 目录分开，避免 bootJar 中同名元数据冲突。

7.8 KiB Raw Blame History Unescape Escape