Apollo 使用指南从项目创建、权限管理到灰度发布的 Portal 全流程实战【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo本文是 Apollo 配置中心ApolloPortal 侧的用户级实战指南覆盖普通应用与公共组件两大类接入场景并深入讲解权限模型、配置编辑/发布/回滚、灰度发布、访问密钥以及系统参数调优等核心能力。读完本文你将能够在 Apollo Portal 上独立完成项目创建、权限分配、配置管理与发布、集群独立配置、公共组件配置覆盖以及灰度发布的全套操作并能理解这些操作背后的实现机制。名词解释普通应用与公共组件在开始接入之前先明确两个贯穿全文的基础概念普通应用指独立运行的程序例如 Web 应用程序、带有 main 函数的程序。它的配置由自己独占维护。公共组件指发布的类库、客户端程序本身不会独立运行而是被嵌入到业务应用中例如 Java 的 jar 包、.Net 的 dll 文件如 CAT 客户端、Hermes Producer 客户端等。两者的接入流程几乎一致核心区别在于公共组件需要创建自己唯一的 Namespace以便其它应用可以关联并覆盖其中的部分配置详见本文「二、公共组件接入指南」。一、普通应用接入指南1.1 创建项目要使用 Apollo第一步是在 Portal 上创建项目打开 apollo-portal 主页点击「创建项目」入口见 create-app-entry.png。填写项目信息部门选择应用所在的部门应用 AppId用来标识应用身份的唯一 id格式为 string需要与客户端app.properties中配置的app.id一一对应应用名称仅用于界面展示应用负责人被选中的人默认成为该项目的管理员具备项目权限管理、集群创建、Namespace 创建等权限。点击提交。创建成功后会自动跳转到项目首页见 app-created.png。从源码结构看项目App、集群Cluster、Namespace、Item 等实体在 apollo-common 的 entity 包 中均有对应定义Portal 侧通过 AppController 等控制器完成项目创建与查询。1.2 项目权限分配1.2.1 项目管理员权限项目管理员拥有以下权限管理项目的权限分配、创建集群、创建 Namespace。创建项目时填写的应用负责人默认即管理员之一。如需添加更多管理员点击页面左侧的「管理项目」见 app-permission-entry.png搜索需要添加的成员并点击添加见 app-permission-search-user.png 与 app-permission-user-added.png。1.2.2 配置编辑、发布权限Apollo 将配置权限拆分为编辑与发布两个维度编辑权限允许用户在界面上创建、修改、删除配置。注意配置修改后只在 Apollo 界面上变化不会影响应用实际使用的配置发布权限允许用户发布、回滚配置。配置只有在发布、回滚动作后才会被应用实际使用到Apollo 会在发布、回滚后实时通知到应用并让最新配置生效。项目创建完成后默认没有分配编辑与发布权限需要项目管理员授权点击application这个 Namespace 的授权按钮见 namespace-permission-entry.png分配修改权限见 namespace-permission-edit.png分配发布权限见 namespace-publish-permission.png。1.2.3 不同维度的权限管理Apollo 在初始设计时把配置权限绑定在Namespace上同时权限管理本身非常灵活可以在此基础上扩展。基于 Apollo 主要实体类的设计 E-R Diagram可以认为Namespace 是权限的最小单元App 是权限的最大单元中间依次是 Env、Cluster从而支持对不同维度的权限进行管理AppEnvClusterNamespaceModelImpl☑️App → *未实现☑️☑️App → Namespace已实现☑️☑️App Env → *未实现☑️☑️☑️App Env → Namespace已实现☑️☑️☑️App Env Cluster → *已实现☑️☑️☑️☑️App Env Cluster → Namespace未实现各权限模型的释义ModelTargetPermissionType (e.g. Modify)TargetIdApp → *App 的所有 namespaceApp → NamespaceApp 下所有指定名字的 namespaceModifyNamespaceAppNamespaceApp Env → *App 的 env 下所有 namespaceApp Env → NamespaceApp 的 env 下所有指定名字的 namespaceModifyNamespaceAppNamespaceEnvApp Env Cluster → *App 的 env 中 cluster 的所有 namespaceModifyNamespaceInClusterAppEnvClusterNameApp Env Cluster → NamespaceApp 的 env 中 cluster 下指定名字的 namespaceApp 下的所有指定名字的 namespace点击application的授权按钮ns-permission-app-allns-entry.png→ 选择「所有环境」ns-permission-app-allns-select.png→ 分配修改、发布权限。App 的 env 下所有指定名字的 namespace点击授权按钮ns-permission-app-allns-entry.png→ 选择指定环境ns-permission-app-env-ns-select.png→ 分配修改、发布权限。App 的 env 中 cluster 的所有 namespace点击「管理集群」进入集群管理页面manage-cluster-entry.png→ 点击目标 Cluster 的授权按钮ns-permission-app-env-cluster-entry.png→ 编辑权限ns-permission-app-env-cluster-edit.png。1.3 添加配置项编辑配置需要拥有该 Namespace 的编辑权限若没有「新增配置」按钮请联系项目管理员授权。表格模式点击新增配置create-item-entry.png→ 输入配置项 key/valuecreate-item-detail.png→ 提交item-created.png。文本模式Apollo 除表格模式逐个添加、修改外还支持文本模式批量操作对从已有 properties 文件迁移尤其有用切换到文本编辑模式text-mode-config-overview.png点击右侧「修改配置」按钮text-mode-config-entry.png输入配置项并点击提交修改text-mode-config-submit.png。1.4 发布配置配置只有在发布后才会被应用真正使用到因此编辑完成后需要发布。发布需要该 Namespace 的发布权限点击「发布」按钮hermes-portal-publish-entry.png填写发布相关信息发布人、发布说明等点击发布hermes-portal-publish-detail.png。发布动作会在 ReleaseService 中生成一条 Release 记录并触发消息通知客户端据此实时拉取最新配置。1.5 应用读取配置配置发布成功后应用即可通过 Apollo 客户端读取配置。Apollo 提供官方 Java 客户端具体参见 Java 客户端使用文档若使用其它语言可通过直接访问 Http 接口获取配置参考其它语言客户端接入指南。1.6 回滚已发布配置若发现已发布配置有问题可点击「回滚」按钮将客户端读取到的配置回滚到上一个已发布版本。这里的回滚机制与发布系统类似发布系统中的回滚是把部署到机器上的安装包回滚到上一个部署版本但代码仓库中的代码不会回滚开发修复后可重新发布。Apollo 同理——点击回滚后客户端读取到的配置恢复到上一个已发布版本但页面上编辑状态的配置不会回滚开发修复配置后可重新发布。该逻辑对应 ReleaseService.rollback 的实现其中仅当存在两个及以上的活跃 Release 时才允许回滚。1.7 配置查询管理员权限配置添加或修改后管理员可进入「管理员工具 - Value 的全局搜索」页面对配置项进行所属查询以及跳转修改。该查询为模糊检索对配置项的 key 与 value 至少一项进行匹配从而定位该配置在哪个应用、环境、集群、命名空间中被使用properties 格式配置可直接对 key 与 value 进行检索xml、json、yml、yaml、txt 等格式配置由于存储时以 content-value 形式保存可通过keycontent、value配置项内容进行检索。二、公共组件接入指南2.1 公共组件和普通应用的区别公共组件指发布给其它应用使用的客户端代码如 CAT 客户端、Hermes Producer 客户端等。这类组件虽然由其它团队开发维护但运行时在业务实际应用内部本质上可以认为是应用的一部分。通常情况下公共组件所用配置由原始开发团队维护但由于实际应用的运行时、环境各不相同Apollo 也允许应用在实际使用时覆盖公共组件的部分配置。2.2 公共组件接入步骤公共组件接入步骤与普通应用几乎一致唯一区别是公共组件需要创建自己唯一的 Namespace。因此先按「一、普通应用接入指南」完成 创建项目 与 项目管理员权限 两个步骤再按以下步骤操作。2.2.1 创建 Namespace创建 Namespace 需要项目管理员权限若没有「添加 Namespace」按钮请联系项目管理员授权点击页面左侧「添加 Namespace」create-namespace.png点击「创建新的 Namespace」create-namespace-select-type.png输入公共组件的 Namespace 名称注意Namespace 名称全局唯一Apollo 会默认把部门代号添加在最前面create-namespace-detail.png提交后页面自动跳转到关联 Namespace 页面先选中所有需要有该 Namespace 的环境和集群一般建议全选再选中刚创建的 namespace最后点击提交link-namespace-detail.png关联成功后跳转到 Namespace 权限管理页面分配修改权限与发布权限点击「返回」回到项目页面。2.2.2 添加配置项编辑配置需要该 Namespace 的编辑权限。表格模式点击新增配置public-namespace-edit-item-entry.png→ 输入配置项public-namespace-edit-item.png→ 提交public-namespace-item-created.png。文本模式与普通应用完全一致参见1.3.2 通过文本模式编辑。2.2.3 发布配置同样遵循「配置只有在发布后才会被应用使用到」的原则发布需要该 Namespace 的发布权限点击「发布」按钮public-namespace-publish-items-entry.png填写发布相关信息后发布public-namespace-publish-items.png。2.2.4 应用读取配置配置发布成功后应用即可通过 Apollo 客户端读取公共组件的配置参见 Java 客户端使用文档 中的「获取公共 Namespace 的配置」部分其它语言参考其它语言客户端接入指南。2.3 应用覆盖公共组件配置步骤由于实际应用运行时、环境不同应用可以覆盖公共组件的部分配置。以下假设 apollo-portal 应用使用了 hermes producer 客户端并希望调整 hermes 的批量发送大小。关联公共组件 Namespace进入使用公共组件的应用项目首页本例为 apollo-portal 首页点击左侧「添加 Namespace」link-public-namespace-entry.png需项目管理员权限→ 找到 hermes producer 的 namespace选择需要关联的环境和集群link-public-namespace.png→ 关联成功后分配修改权限与发布权限然后点击「返回」。覆盖公共组件配置点击新增配置override-public-namespace-entry.png→ 输入要覆盖的配置项override-public-namespace-item.png→ 提交override-public-namespace-item-done.png。发布配置点击「发布」按钮override-public-namespace-item-publish-entry.png→ 填写发布信息后发布override-public-namespace-item-publish.png。配置发布成功后hermes producer 客户端在 apollo-portal 应用内运行时读取到的sender.batchSize即为覆盖后的值 1000。覆盖的优先级实现从源码结构看可追溯至客户端按「应用自身关联的公共 Namespace 覆盖项优先于公共组件原始配置项」的合并规则进行加载。三、集群独立配置说明某些场景下应用需要对不同集群做不同配置例如部署在 A 机房的应用连接的 es 服务器地址与部署在 B 机房的不同。此时可在 Apollo 中创建不同集群来解决。创建集群点击页面左侧「添加集群」create-cluster.png需项目管理员权限→ 输入集群名称、选择环境并提交create-cluster-detail.png切换到对应集群修改配置并发布即可cluster-created.png通过上述配置部署在 SHAJQ 机房的应用会读到 SHAJQ 集群下的配置若应用还部署在其它机房则会读到default 集群下的配置。集群在客户端侧由app.properties中的集群配置与运行时数据中心信息共同决定未命中任何自定义集群时回落到 default 集群这是 Apollo 多机房部署的常用做法。四、多个 AppId 使用同一份配置即使应用本身不是公共组件也可能需要在多个 AppId 之间共用同一份配置例如同一产品的不同项目XX-Web、XX-Service、XX-Job 等。基本概念与公共组件一致在其中一个 AppId 下创建一个 namespace写入公共配置信息然后各项目读取该 namespace 的配置即可若某个 AppId 需要覆盖公共配置则在该 AppId 下关联公共 namespace并写入需要覆盖的配置即可。具体步骤参考二、公共组件接入指南。五、灰度发布使用指南通过灰度发布功能可以对影响较大的配置先在一个或多个实例生效观察一段时间无问题后再全量发布对需要调优的配置参数通过灰度实现 A/B 测试不同机器应用不同配置调整、测评后找出较优配置再全量发布。下面结合一个实际例子说明完整流程。5.1 场景介绍项目100004458 (apollo-demo)有两个客户端实例10.32.21.19与10.32.21.22见 initial-instance-list.png。灰度目标当前配置timeout2000希望对10.32.21.22灰度发布timeout3000对10.32.21.19保持timeout2000见 initial-config.png。5.2 创建灰度点击 application namespace 右上角的「创建灰度」按钮create-gray-release.png点击确定后灰度版本创建成功页面自动切换到「灰度版本」Tabinitial-gray-release-tab.png。5.3 灰度配置点击「主版本的配置」中 timeout 配置最右侧的「对此配置灰度」按钮edit-gray-release-config.png在弹出框中填入灰度的值 3000 并提交submit-gray-release-config.png、gray-release-config-submitted.png。灰度配置完成后点击「灰度发布」按钮click-gray-release.png在弹框中与主版本的值对比确认将要发布的灰度配置gray-release-diff-items.png。5.4 配置灰度规则切换到「灰度规则」Tab点击「新增规则」new-gray-release-rule.png按 IP 灰度弹出框中「灰度的 IP」下拉框默认展示当前使用配置的机器列表选择目标 IPselect-gray-release-ip.png、gray-release-ip-selected.png若下拉框中没有所需 IP说明机器尚未从 Apollo 取过配置可手动输入 IP 后添加manual-input-gray-release-ip.png、manual-input-gray-release-ip-2.png按 Label 灰度从 2.0.0 版本开始还支持通过 label 标识灰度实例列表适用于 IP 不固定的场景如 Kubernetes。手动输入 label 标签后点击添加manual-input-gray-release-label.png、manual-input-gray-release-label2.png。规则配置完成后gray-release-rule-saved.png灰度配置会对 AppId 为100004458、IP 为10.32.21.22或 Label 标记为myLabel/appLabel的实例生效。关于 Label 如何标记参见 Java 客户端使用文档 - ApolloLabel。注对于公共 Namespace 的灰度规则需要先指定要灰度的appId然后再选择 IP 和 Label。从源码看灰度规则在 GrayReleaseRulesHolder 中以缓存形式维护并通过 GrayReleaseRuleCache.matches 同时匹配clientAppId、clientIp与clientLabel其中 label 规则还额外维护了reversedGrayReleaseRuleLabelCache反向缓存这正是 2.0.0 起 Label 灰度能力的底层实现。5.5 灰度发布规则已生效但灰度配置尚未发布。切换到「配置」Tab再次检查灰度配置部分确认无误后点击「灰度发布」prepare-to-do-gray-release.png。在弹出框中可以看到主版本的值是 2000、灰度版本即将发布的值是 3000填入其它信息后点击发布gray-release-confirm-dialog.png。发布后切换到「灰度实例列表」Tab可以看到10.32.21.22已使用灰度发布的值gray-release-instance-list.png切换到「主版本」的「实例列表」主版本配置只剩10.32.21.19在使用master-branch-instance-list.png。之后可继续修改配置或更改规则配置的修改需要点击灰度发布后才会生效规则的修改在规则点击完成后就会实时生效。5.6 全量发布若灰度配置测试理想、符合预期可执行「全量发布」prepare-to-full-release.png。全量发布的效果灰度版本的配置会合并回主版本——本例中主版本 timeout 会被更新成 3000主版本的配置会自动进行一次发布在全量发布页面可选择是否保留当前灰度版本默认为不保留full-release-confirm-dialog.png、full-release-confirm-dialog-2.png。本例选择不保留灰度版本因此发布后的效果是主版本配置更新、灰度版本删除点击主版本的实例列表可见10.32.21.22与10.32.21.19都使用了主版本最新配置master-branch-instance-list-after-full-release.png。5.7 放弃灰度如果灰度版本不理想或不再需要点击「放弃灰度」即可abandon-gray-release.png。5.8 发布历史点击主版本的「发布历史」按钮可以看到当前 namespace 主版本以及灰度版本的发布历史view-release-history.png、view-release-history-detail.png。六、其它功能配置6.1 配置查看权限从 1.1.0 版本开始apollo-portal 增加了查看权限支持可配置某个环境只允许项目成员查看私有 Namespace 的配置。这里的项目成员指项目管理员或具备该私有 Namespace 在该环境下修改/发布权限的用户。配置方式用超级管理员账号登录后进入「管理员工具 - 系统参数」页面新增或修改configView.memberOnly.envs配置项即可configure-view-permissions.png。该配置项在 Portal 侧的读取逻辑位于 PortalConfig.isConfigViewMemberOnly支持对 env 别名如 prod/PROD/PRO做归一化匹配后判定是否启用成员可见限制。6.2 配置访问密钥Apollo 从 1.6.0 版本开始引入访问密钥机制只有经过身份验证的客户端才能访问敏感配置。若应用开启了访问密钥客户端必须配置密钥否则无法获取配置。从 3.0.0 起若在各环境ApolloConfigDB.ServerConfig中将apollo.access-key.auto-provision.enabled设为true详见分布式部署指南 - 该配置项说明则在 Portal 中新建应用并成功同步到对应环境后该环境会自动创建一条已启用的访问密钥随机密钥、FILTER 模式减少手工创建与启用的步骤。未开启时仍按下列步骤手动管理密钥项目管理员打开「管理密钥」页面为项目的每个环境生成访问密钥。注意密钥默认是禁用的建议在客户端都配置完成后再开启客户端侧配置访问密钥参见 Java 客户端使用文档 - 配置访问密钥。从源码结构看密钥管理在 Portal 侧由 AccessKeyService 与 OpenAPI 层的 AccessKeyOpenApiService 提供创建、查询、启用/禁用、删除等操作其中启用接口支持指定模式如 FILTER 过滤模式。6.3 全局搜索配置项的系统参数设置从 2.4.0 版本开始apollo-portal 增加了全局搜索配置项功能可对配置项的 key 与 value 模糊检索定位其在哪个应用、环境、集群、命名空间被使用。为防止全局搜索时内存溢出OOM引入系统参数apollo.portal.search.perEnvMaxResults用于限制每个环境配置项单次最大搜索结果数量默认值为200管理员可按需调整。设置方法用超级管理员账号登录 Apollo 配置中心界面进入「管理员工具 - 系统参数」页面新增或修改apollo.portal.search.perEnvMaxResults配置项即可。注意修改系统参数可能影响搜索功能的性能修改前应充分测试并理解参数作用。该参数在 Portal 侧由 PortalConfig.getPerEnvSearchMaxResults 读取。6.4 AppIdCluster 维度下命名空间数量限制功能参数设置从 2.4.0 版本开始apollo-portal 提供 AppIdCluster 维度下可创建的命名空间数量上限校验功能。此功能默认关闭相关系统参数namespace.num.limit.enabled开启/关闭功能默认关闭。进入「管理员工具 - 系统参数 - ConfigDB 配置管理」页面新增或修改为 true/falsenamespace-num-limit-enabled.pngnamespace.num.limitAppIdCluster 维度下 Namespace 数量上限默认 200namespace-num-limit.pngnamespace.num.limit.white校验白名单配置后不受数量上限影响。考虑到网关、消息队列、Redis、数据库等基础组件需要特殊处理可将对应 AppId 加入白名单多个 AppId 使用英文逗号分隔namespace-num-limit-white.png。6.5 单个命名空间下的配置项数量限制从 2.4.0 版本开始apollo-portal 提供限制单个命名空间下配置项数量的功能默认关闭。相关系统参数item.num.limit.enabled开启/关闭功能在「管理员工具 - 系统参数 - ConfigDB 配置管理」页面配置为 true/falseitem-num-limit-enabled.pngitem.num.limit单个 Namespace 下 item 数量上限值item-num-limit.png。七、最佳实践7.1 安全相关配置中心作为基础服务存储着公司非常重要的配置信息安全因素需要重点关注。以下注意事项供参考。7.1.1 认证建议接入公司统一的身份认证系统如 SSO、LDAP 等接入方式参考 Portal 实现用户登录功能。如果使用 Apollo 提供的 Spring Security 简单认证务必记得修改超级管理员 apollo 的密码。7.1.2 授权Apollo 支持细粒度的权限控制请务必根据实际情况做好授权项目管理员权限Apollo 默认允许所有登录用户创建项目若只允许部分用户创建项目可开启创建项目权限控制配置编辑、发布权限支持按环境配置例如开发环境由开发人员自行完成编辑与发布生产环境发布权限交由测试或运维人员。生产环境建议同时开启发布审核namespace.lock.switch从而控制一次配置发布只能由一人修改、另一人发布确保修改得到充分检查配置查看权限可指定某个环境只允许项目成员查看私有 Namespace 的配置避免敏感配置泄露如生产环境。7.1.3 系统访问除了用户权限系统访问层面也需要加以考虑apollo-configservice与apollo-adminservice基于内网可信网络设计出于安全考虑禁止直接暴露在公网对敏感配置可考虑开启访问密钥只有经过身份验证的客户端才能访问敏感配置1.7.1 及以上版本可为apollo-adminservice开启访问控制从而只有受控的apollo-portal才能访问对应接口增强安全性2.1.0 及以上版本可为 eureka 开启访问控制从而只有受控的apollo-configservice与apollo-adminservice可以注册到 eureka增强安全性。以上安全相关参数的具体配置位置与默认值均可在 分布式部署指南 与 Apollo 设计文档 中查到详细说明建议在生产环境部署前逐一核对。【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考