3步批量导入配置：Apollo 配置中心批量处理指南

3步批量导入配置：Apollo 配置中心批量处理指南

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

生产环境要改 200 个配置项，UI 表格模式只能一条条录入，改完发布窗口已经过了。本文覆盖 Apollo 配置中心的两条批量通道——Portal 文本模式整文件导入和 OpenAPI 脚本批量增改，外加灰度与权限的管控手段。读完你可以独立完成：

1. 用文本模式整文件导入 properties 并发布
2. 用 openapi.sh 批量更新配置项并发布
3. 用灰度规则让一批配置变更先在小部分实例生效

快速通道：文本模式整文件导入

适用场景：一次性迁移已有配置文件，或变更量在几十到两百项以内，不值得写脚本。

切换文本模式

打开应用 Namespace 页面，点右上角"文本模式"。该模式支持 properties、yaml、json 格式的批量录入，是把传统配置文件迁进 Apollo 的常规路径。

粘贴整份配置文件

点右侧"修改配置"，把文件内容整个粘进文本框。系统会自动解析键值对并识别注释、空行，本地文件内容可以原样使用。

详见：Apollo用户指南 §1.3.2 关于文本模式编辑的说明

提交并发布

提交修改后系统展示变更 diff。注意提交完成不等于生效，还要点"发布"并填写发布说明，否则客户端拿到的仍是旧版本。

自动化路径：用 OpenAPI 批量增改配置项

适用场景：变更周期性发生、要进 CI/CD，或单项量上千条。

创建访问令牌

批量操作走 Portal 的 OpenAPI，先由项目管理员在开放平台管理页创建 token。token 可以按operations、appIds、envs、namespaces圈定范围——生产批量变更只授目标 namespace 的 Modify 和 Publish，不要给全量权限。

设置两个环境变量，地址不带末尾斜杠：

export APOLLO_PORTAL_ADDRESS=http://your-portal:8070 export APOLLO_OPENAPI_TOKEN=<你的token>

执行批量 upsert

在能访问 Portal 的机器上运行，先 source 仓库自带脚本。item_update_create_if_not_exists对指定 key 做"存在则改、不存在则建"：

source scripts/openapi/bash/openapi.sh # 批量更新/插入两个配置项 item_update_create_if_not_exists "PRO" "order-service" "default" "application" \ "timeout" "5000" "批量更新超时" "admin" "admin" item_update_create_if_not_exists "PRO" "order-service" "default" "application" \ "batch.size" "200" "批量大小" "admin" "admin"

全部改完后调用一次namespace_release发布，参数依次为 env、appId、cluster、namespace、标题、说明、操作人：

namespace_release "PRO" "order-service" "default" "application" \ "2026-10 超时调整" "批量脚本发布" "admin"

直接调用 3.0.0 批量接口

3.0.0 起 OpenAPI 支持一次提交一批配置项，三个接口各自独立，没有跨接口原子性：

用 curl 批量修改的写法，items.json 是OpenItemDTO数组：

curl -X PUT "${APOLLO_PORTAL_ADDRESS}/openapi/v1/envs/PRO/apps/order-service/clusters/default/namespaces/application/items/batch-update" \ -H "Authorization: ${APOLLO_OPENAPI_TOKEN}" \ -d @items.json

详见：Apollo开放平台 §3.2.20 关于批量新增/修改/删除三个接口的参数与 404 行为说明

安全与边界：灰度与权限管控

批量操作放大了单个配置错误的爆炸半径，管控手段就两个：先让少数实例拿到变更，再限制谁能执行变更。

灰度版本先行验证

创建灰度版本、修改灰度配置后，到"灰度规则"Tab 新增规则并选择目标实例：

IP 规则适合固定机器；Kubernetes 这类 IP 不固定的环境，2.0.0 起支持按 Label 匹配。灰度发布后到"灰度实例列表"核对拿到灰度值的实例是否符合预期：

验证通过就全量发布，灰度版本会合并回主版本并自动发布一次；验证不通过直接放弃灰度，主版本不受影响。

各操作风险等级对比

⚠️ 生产环境直接全量发布批量变更之前，先走一遍灰度。

权限分两层：UI 侧按 env+cluster+namespace 维度授予 Modify 和 Publish，生产建议编辑与发布由不同人操作；OpenAPI 侧看 token 的授权范围。另外若系统开启了单 namespace 配置项数量限制，批量新增超限会直接失败，脚本里要处理这类错误。

做完这轮批量变更后执行的 3 件事

1. 核对灰度实例列表与观察窗口，再点全量发布，操作路径见 用户指南 §5.6。
2. 脚本进 CI 之前先跑一遍自带示例，验证环境变量和 token 是否配通：bash scripts/openapi/bash/openapi-usage-example.sh。
3. OpenAPI 返回非 200 时先查 400（参数错误）和 401（token 非法或过期），对照 开放平台文档 "错误码说明"一节。

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