105 lines
6.4 KiB
Markdown
105 lines
6.4 KiB
Markdown
# 项目初始化
|
||
|
||
2026-09-25 使用 start.spring.io API 生成，选择当时默认正式版 Spring Boot 4.1.1、
|
||
Java 25、Gradle Groovy DSL、YAML 配置和 Jar。应用包名为 `top.ddupan.iam.login`。
|
||
|
||
```sh
|
||
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/`。
|
||
|
||
```sh
|
||
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](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html)
|
||
与 [Native Build Tools Gradle 配置](https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html)。
|
||
|
||
## Protobuf Native 元数据
|
||
|
||
Micrometer OTLP 使用的 Protobuf 4.35.1 通过反射调用 `ExtensionRegistry` 的
|
||
`getEmptyRegistry()` 与 `newInstance()`。实际原生应用启动曾因前一个方法缺少注册而失败，
|
||
项目的 `reachability-metadata.json` 只补充这两个工厂方法。升级依赖时应重新验证能否移除。
|
||
|
||
上下文测试显式启用 `@AutoConfigureMetrics` 与 `@AutoConfigureTracing`，初始化真实导出器，
|
||
避免 Spring 测试默认关闭导出导致 Native 问题漏测。它验证初始化及容器连接信息，完整的
|
||
OTLP 数据接收、持久化和查询验收仍属后续观测性集成测试。
|
||
|
||
Micrometer 1.17.1 自带的反射声明已覆盖 CPU 使用率和文件描述符读取，但遗漏了
|
||
`OperatingSystemMXBean.getProcessCpuTime()`。项目只补这一项；回归测试直接读取
|
||
Prometheus 注册器中的 CPU 时间计数器并断言数值有效，避免后台导出异常被误报为测试通过。
|
||
其他 JVM 指标在 Native 中的语义仍需分别验证，不能保证 HotSpot 仪表盘完全适用。
|