Apollo 3.0.0 发布说明深度解读：Portal OpenAPI 全面迁移、用户令牌体系与 ServerConfig 多集群管理

Apollo 3.0.0 发布说明深度解读：Portal OpenAPI 全面迁移、用户令牌体系与 ServerConfig 多集群管理

【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo

Apollo 3.0.0 是一次以"管理面 API 化"为主线的大版本升级：Portal 的全部管理型 UI 操作从内部 WebAPI 迁移到 OpenAPI v1，新增面向 AI Agent 与自动化的用户访问令牌（User Token）体系，并让 ConfigDB 的 ServerConfig 支持按key + cluster粒度管理。本文基于 CHANGES.md 中 3.0.0 版本的 22 条变更记录逐主题展开，并结合仓库源码说明每一项变更的实际实现位置、默认行为与升级注意事项，帮助运维和二次开发者评估升级影响面、快速启用新能力。

版本基线：Spring Boot 4.x 与 Java 17

CHANGES.md 中 3.0.0 共包含两次基线升级记录：先是将 Apollo Server 基线迁移到 Spring Boot 4.0.x 并对齐 Spring Cloud 服务发现集成（PR 5585），随后进一步升级到 Spring Boot 4.1.1 与 Spring Cloud 2025.1.3（PR 5671）。当前仓库根 pom.xml 中的属性可以确认最终基线：

• revision：3.0.0-SNAPSHOT（即 3.0.0 开发线）
• java.version：17
• spring-boot.version：4.1.1
• spring-cloud.version：2025.1.3
• spring-cloud-alibaba.version：2025.1.0.0
• 配套 Java SDKapollo-java.version：2.5.0

从源码结构看，3.0.0 的模块组成与 2.x 保持一致（apollo-common、apollo-biz、apollo-configservice、apollo-adminservice、apollo-portal、apollo-assembly），并新增了apollo-audit多模块审计子工程和apollo-build-sql-converter构建模块，这也与本版引入的审计日志 OpenAPI 端点相呼应。

官方包默认改用数据库服务发现

3.0.0 的一个重要行为变更是：官方发布的 Config/Admin 包默认改为数据库（database）服务发现。对从旧版 Eureka 方式部署升级而来的用户，CHANGES.md 明确给出迁移约束——需要显式保留githubprofile 才能维持旧的服务发现行为。仓库中apollo-biz模块的registry包提供了多种注册中心实现，eureka包仍保留 Eureka 相关配置类，从源码结构看，默认发现方式的切换正是在这一层完成的。

与之配套，CI 侧新增了"外部服务发现冒烟工作流"（external discovery smoke workflow），仓库中对应 e2e/discovery-smoke 目录，包含run-smoke.sh与provider.sh脚本，用于验证外部注册中心场景下的服务连通性。

升级提示：如果你此前依赖 Eureka 作为官方部署形态的服务发现，升级前请先检查启动 profile，保留githubprofile 或同步切换为数据库发现，否则升级后 ConfigService/AdminService 之间的互相发现方式会发生变化。

Portal 管理操作全面迁移至 OpenAPI

这是 3.0.0 中数量最多、影响面最大的一组变更（PR 5608–5618），CHANGES.md 按领域分列了五个阶段：

1. Portal OpenAPI 迁移适配 apollo-openapi v0.2.0（PR 5608）；
2. 配置项（config item）UI 操作迁移到 OpenAPI（PR 5610）；
3. 命名空间（namespace）核心 UI 操作迁移（PR 5612）；
4. 发布（release）、分支（branch）、实例（instance）UI 操作迁移（PR 5616）；
5. 权限（permission）与 AccessKey UI 操作迁移（PR 5617），至此完成全部 Portal UI 管理操作迁移（PR 5618）。

源码层面可以验证这条演进路线。PortalManagementController.java 是承接 Portal 管理类端点的新控制器，它直接实现 OpenAPI 生成的接口PortalManagementApi，并标注"OpenAPI v1 controller for Portal UI-only management endpoints"。同一个openapi/v1包下还有 AppController.java、NamespaceController.java、ItemController.java、NamespaceBranchController.java、AccessKeyController.java、ClusterController.java 等十余个控制器，覆盖了 CHANGES.md 列出的各迁移领域。

旧的内部 WebAPI 控制器则被统一标记为废弃但保留兼容。以 ServerConfigController.java 为例，类上的注释写明：

/** * @deprecated Portal UI uses /openapi/v1 endpoints. This legacy WebAPI controller is kept for * compatibility. */ @Deprecated @RestController public class ServerConfigController { ... }

也就是说 3.0.0 采取的是"新端点先行、旧端点冻结"的策略：Portal 前端请求走/openapi/v1，旧的/server/...等路径仍可用，为存量集成留出了过渡期。此外，审计能力也在同一迁移中接入 OpenAPI——PortalManagementController注入了ApolloAuditLogApi与ApolloAuditProperties，提供审计属性查询、审计日志分页搜索、按操作名/traceId/字段影响查询等超管端点，与 apollo-audit 子模块（annotation、api、impl、spring-boot-starter 四件套）配套。

权限语义修复：超管纳入 hasAnyPermission

CHANGES.md 第一条修复（PR 5568）是"让hasAnyPermission语义包含超级管理员"。从源码结构看，权限判定集中在 UnifiedPermissionValidator.java 及其@PreAuthorize调用链上（PortalManagementController中大量使用@unifiedPermissionValidator.isSuperAdmin()/isAppAdmin(#appId)等表达式）。该修复的意义在于：此前若权限校验逻辑通过"是否持有任何命名空间权限"来放行部分操作，超管在特定路径下可能不被识别；修复后超管在hasAnyPermission语义下与持有任意权限的用户等价，消除了管理类 API 对超管的漏判。

Consumer Token 获得管理 Portal 用户的授权角色

PR 5623 允许被显式授权的 consumer token 管理 Portal 用户。在PortalManagementController的createConsumer方法中可以看到对应的授权开关：创建 consumer 时若请求体中allowManageUsers为 true，则调用consumerService.assignManageUsersRoleToConsumer(...)为该 token 分配管理用户角色；allowCreateApplication同理。该角色机制由 ConsumerRole 实体承载，使机器身份（consumer token）在受控范围内可代管账号，而不再仅限于读写配置。

ServerConfig 支持按 key + cluster 管理，UI 具备集群感知

PR 5601 让 ConfigDB 管理端的 ServerConfig 支持按key + cluster创建/更新/删除，并在 UI 上做到集群感知、补充了多集群安全测试。源码中有两处直接证据：

• 新版 OpenAPI 端点（PortalManagementController）中，删除 ConfigDB 配置的方法签名携带了cluster参数：

@PreAuthorize(value = "@unifiedPermissionValidator.isSuperAdmin()") @ApolloAuditLog(type = OpType.DELETE, name = "ServerConfig.deleteConfigDBConfig") public ResponseEntity<Void> deleteConfigDBConfig(String env, String key, String cluster) { requirePortalUserRequest(); serverConfigService.deleteConfigDBConfig(parseEnv(env), key, cluster, currentUserId()); return ResponseEntity.ok().build(); }

• 旧的 ServerConfigController.java 中deleteConfigDBConfig同样接收key与cluster两个参数，说明 cluster 维度在旧端点上同步补齐。

值得注意的是，PortalManagementController.validateServerConfig要求key与value均非空，否则抛BadRequestException；所有写操作都叠加了@PreAuthorize("@unifiedPermissionValidator.isSuperAdmin()")与@ApolloAuditLog审计注解。也就是说，ServerConfig 的写权限收敛到超管，且每次增删改都会落审计日志。

AccessKey 自动签发：新应用创建即获得每环境可用的 AccessKey

PR 5589 是 3.0.0 中一个对集成方非常实用的新特性：创建新应用时，可为每个环境自动签发一个已启用的 AccessKey，由 ConfigDB 中ApolloConfigDB.ServerConfig表的apollo.access-key.auto-provision.enabled开关控制。

配置项定义在 BizConfig.java：

public boolean isAccessKeyAutoProvisionEnabled() { return getBooleanProperty("apollo.access-key.auto-provision.enabled", false); }

默认值为false，即不启用，升级不会改变现有行为。启用路径在 AppController.java（AdminService 的/apps创建端点）：

1. adminService.createNewApp(entity)创建应用；
2. 若bizConfig.isAccessKeyAutoProvisionEnabled()为 true，则构造默认 AccessKey：secret 由UniqueKeyGenerator.generateId()生成、模式固定为AccessKeyMode.FILTER、enabled置为true；
3. 操作人取值有回退链：优先dataChangeCreatedBy，其次dataChangeLastModifiedBy，最后回落到ownerName；
4. 关键点：自动签发失败不会导致建应用失败，异常仅被记录为 warn 日志（Failed to auto-provision access key for appId=...），保证主流程的健壮性。

对应的测试覆盖了开关默认关闭、开启后的建应用行为（见 BizConfigTest.java 及 ControllerExceptionTest.java）。

配合本版的另一个权限修复看，"应用创建即自动具备 OpenAPI 访问凭证 + consumer token 可被授权管理用户"共同降低了机器接入 Apollo 的门槛。

用户访问令牌（User Token）：为 AI Agent 与自动化场景提供身份

PR 5632 引入了面向 AI Agent 与自动化脚本的用户访问令牌，PR 5637 则修复了限流场景下的响应行为——超限时返回 429 状态码，而不是重定向到登录页，这对程序化调用方是明确的协议约束。

令牌的全生命周期管理在PortalManagementController中通过/openapi/v1/user-tokens端点族暴露（源码位置）：

几个实现细节值得注意：

• 作用域（Scope）：令牌可限定appIds、envs和按环境划分的namespaces范围（UserTokenNamespaceScope），并可声明允许执行的operations集合，能力边界通过/capabilities端点动态查询（userTokenDefaultExpireDays/userTokenMaxExpireDays来自 Portal 配置 PortalConfig）；
• 审计与元信息：令牌摘要中带有lastUsedTime、lastUsedIp、lastUsedUserAgent以及吊销人与吊销时间，实体层对应 UserToken.java 与 UserTokenAudit.java；
• 认证链：请求侧由 UserTokenAuthenticationFilter.java 完成令牌认证并写入 Spring Security 上下文（UserTokenAuthenticationToken），权限判定由UserTokenPermissionValidator等组件按操作范围校验。

这套机制让"人用浏览器、Agent 用令牌"成为一等公民：自动化脚本、CI 流水线或 LLM 驱动的工具可以以受限、可吊销、可审计的令牌身份操作 Portal，而不必借用某个人的会话。

认证与身份：OIDC 用户名声明可配置

PR 5655 增加了spring.security.oidc.user-id-claim-name配置，允许在 OIDC 登录场景下显式指定从 ID Token 中取哪个 claim 作为 Apollo 用户身份（user id）。此前用户身份默认绑定固定的 claim，当企业 IdP 的 username 字段并非默认 claim 名时，只能靠改代码适配；该配置项使 Portal 用户登录扩展（参见 用户登录功能扩展文档）在 OIDC 场景下可直接配置完成，无需定制。

数据层与存储：发布历史物理清理、严格格式校验与撤销改进

3.0.0 在数据治理上有四条记录，均能对应到仓库中的具体实现：

1. 物理删除保留的发布历史与无引用 release 行（PR 5641）。与 BizConfig.java 中的两个配置项配套：

   • apollo.release-history.retention.size：保留条数上限，默认-1表示不限制（DEFAULT_RELEASE_HISTORY_RETENTION_SIZE = -1），启用后取值范围为[1, MAX]；
   • apollo.release-history.retention.size.override：JSON 形式的按 appId 覆盖配置，例如可按应用单独调大保留量，解析时值必须> 0，非法 JSON 只记录 error 日志并返回空 map，不会中断服务。

   仓库中还提供了一整套存量数据迁移脚本 scripts/sql/migration/release-history-retention，按"预检需恢复的 release → 预检软删行 → 恢复被引用 release → 物理清除软删行"四步组织（01-precheck-releases-needing-restore.sql…04-purge-soft-deleted-rows.sql），目录内 README.md 说明执行顺序。从源码结构看，这套脚本与"物理删除"特性配套，用于在启用清理策略前修正历史软删数据，避免误删仍被引用（如回滚目标）的 release。

2. 撤销未发布变更时保留 item 类型（PR 5646）与支持非 properties 命名空间撤销未发布变更（PR 5656）。这两项作用于 Commit 撤销链路（AdminService 的 CommitController.java），修复了撤销操作导致 item 的 type 字段丢失的问题，并把撤销能力从仅 properties 格式扩展到 yaml/json 等非 properties 命名空间。

3. 权威保存路径上的严格 JSON/YAML 合法性校验（PR 5660）。此前格式合法性可能依赖客户端或展示层，本版在最终落库的保存路径上做了严格的 well-formedness 校验，防止非法 JSON/YAML 内容进入命名空间——这是配合"非 properties 命名空间"能力扩张（撤销、JSON 视图等）的数据正确性兜底。

4. Portal 增加格式化与原始 JSON 双视图（PR 5657）。json 格式命名空间在 Portal 中同时提供 formatted 与 raw 两种查看方式，方便既需要可读结构又需要精确原文的场景。

升级与迁移清单

结合 CHANGES.md 与源码，从 2.x 升级到 3.0.0 时建议按以下清单核对：

1. 运行环境：JDK 17、Spring Boot 4.1.1 / Spring Cloud 2025.1.3 基线；依赖 Spring 生态的二次开发插件需确认与 Boot 4.x（jakarta 命名空间）的兼容；
2. 服务发现：默认改为数据库发现；沿用 Eureka 的官方部署需显式保留githubprofile；
3. API 集成：前端与脚本如直接调用 Portal 旧版 WebAPI（/server/...等）仍可工作（已标记@Deprecated但保留兼容），但建议规划切换到/openapi/v1端点，以对齐 apollo-openapi v0.2.0 的契约；
4. 新能力开关：apollo.access-key.auto-provision.enabled（ConfigDB ServerConfig，默认 false）按需开启；发布历史保留策略通过apollo.release-history.retention.size（默认 -1 不启用）与 override 配置项开启；
5. 自动化身份：为 Agent/流水线创建受限 User Token 并定期 rotate，利用 429 限流语义做客户端退避；
6. 数据库迁移：启用发布历史清理前，按 release-history-retention 迁移目录 中的脚本顺序执行预检与数据修正。

相关入口

• 变更记录原文：CHANGES.md，各历史版本明细见 changes/ 目录（changes-1.9.0.md 至 changes-2.5.0.md）
• 版本基线：pom.xml
• Portal OpenAPI 管理控制器：PortalManagementController.java
• 服务端配置项中心：BizConfig.java
• 用户令牌过滤器：UserTokenAuthenticationFilter.java
• 外部服务发现冒烟测试：e2e/discovery-smoke

【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo