旧系统配置中心迁移，先固定配置契约，再改变读取来源

先按变更语义决定配置去向，不把所有键都做成动态开关

适用边界：先确认问题是配置治理，不是顺便重写业务规则

本文适用于仍在生产运行、配置来源分散且需要逐步接入统一配置能力的企业软件。目标是统一来源、验证和发布责任，不要求先更换语言、框架或部署平台，也不默认微服务和配置中心一定优于少量受控文件。

如果系统只有一个实例、配置很少且变更必须随代码发布，版本控制下的部署配置可能已经足够；引入独立配置中心会新增网络依赖、权限、备份和运维责任。相反，当同一键在多个文件、数据库和控制台里被修改，或不同实例长期使用不同值时，应先治理来源与生效证据，再讨论具体产品。

业务价格、审批条件、租户策略和功能开放范围虽然可以表现为键值，但往往需要业务审核、适用对象、开始结束时间和历史追溯。它们不应被当作普通技术配置随意覆盖。AI 智能体的模型、知识范围和工具权限，小程序与 APP 的最低版本、接口地址和开关，也要按真实业务与客户端缓存边界单独定义。

• 明确本次覆盖的应用、环境、实例、客户端和配置类别。
• 区分技术配置、业务规则、实验开关与秘密，分别指定责任人。
• 记录不会迁移的旧参数、原因、使用者和后续退出条件。

从运行实例反查真实来源和优先级

仓库中的示例文件通常不是生产事实。旧系统可能同时读取代码默认值、多个目录文件、启动参数、环境变量、数据库表、注册中心、运维脚本和控制台缓存；同名键由谁覆盖必须以实际启动过程和运行结果核对。

为每个键记录规范名称、类型、默认值、允许范围、是否必填、敏感级别、所属环境、读取组件、当前来源、覆盖顺序、生效时机和负责人。通过代码搜索、部署清单、进程启动参数、配置读取日志及隔离环境实验交叉确认，不在报告中抄出秘密值。对从未读取、名称拼错、只存在于某台机器或无法确认用途的键标为待决，不能直接复制后宣布完成。

优先级应形成一条可解释的链，并为冲突采取明确策略。迁移期可以暂时保留旧来源作为回退，但只能由一层负责写入，其他层只读或冻结；否则新中心改为 A、旧后台又写回 B，最终值取决于重启顺序。实例应能输出配置版本、来源标识和校验结果，而不是输出原始秘密。

• 按实际进程建立配置键、来源、优先级与生效时机清单。
• 同名键冲突、未知键和孤立机器配置进入单独处置队列。
• 迁移期指定唯一写入源，禁止新旧控制台双向覆盖。

先定义配置契约，再让应用接入新来源

配置中心通常只能保存和分发数据，不能自动理解业务语义。应用需要为关键键定义类型、范围、单位、枚举、依赖关系和缺失行为，在启动或更新进入业务路径之前完成校验。

把毫秒与秒、比例与百分数、空字符串与未设置、列表顺序和大小写规则写入契约。关键依赖地址、数据库模式、队列名称和租户隔离开关缺失时应拒绝启动或拒绝发布；可以安全使用默认值的界面文案、采样率等配置，也要让默认来源可见。未知键是拼写错误还是向前兼容，需要按版本策略决定，不能统一静默忽略。

跨键约束同样重要：启用某功能时对应接口、权限和回退资源必须齐全；下调超时要与上游调用预算和重试策略协调。配置模式随应用版本演进时，为旧实例保留明确兼容窗口，先让代码同时理解新旧结构，再发布新值，最后移除旧键。不要先删除旧键，再期待尚未升级的小程序接口、后台任务或旧实例自动适配。

• 为关键键提供类型、单位、允许范围、缺失和未知键处理规则。
• 发布前执行单键与跨键校验，失败配置不得进入生效版本。
• 配置模式按先兼容代码、再发布数据、最后退役旧键的顺序演进。

普通配置与秘密分开迁移，读取权限按工作负载收敛

数据库密码、API 令牌、私钥和证书不能因为换到统一平台就自动安全。存储加密、传输保护、最小权限、运行时暴露、轮换、撤销和审计是不同控制面，需要共同设计。

Kubernetes 官方资料明确区分用于非机密数据的 ConfigMap 和用于机密数据的 Secret，并提醒 Base64 编码不提供保密性，Secret 的静态加密与最小权限还需另行配置。无论是否使用 Kubernetes，都应避免把秘密写入源码、普通配置导出、构建产物、命令历史、错误页和日志；能读取某工作负载定义或创建其运行实例的人，是否会间接获得秘密，也要纳入权限评估。

为每个秘密记录用途、所有者、使用者、来源、轮换和撤销方式，但验收材料只保存标识与状态。迁移可采用新旧凭据短期并存：先让服务提供方接受新凭据，灰度消费者，再停止旧凭据并确认无调用，最后撤销旧值。停止应用并不等于秘密已经失效；泄露或离职场景需要服务提供方的明确撤销与审计证据。

• 秘密不进入普通配置、源码、构建产物、日志或可下载快照。
• 每个工作负载只获得运行所需的秘密和操作范围。
• 轮换包含生成、分发、切换、观察、撤销和失败回退完整过程。

为启动读取、文件更新和动态重载分别定义生效语义

中心里的值已修改，不代表运行中的进程已经采用。应用可能只在启动时读取环境变量，也可能周期拉取、监听变更或读取挂载文件；每种方式的延迟、失败和一致性不同。

Kubernetes 的官方 ConfigMap 更新教程说明：用作环境变量的值不会更新到已运行进程，需要替换 Pod；以卷文件挂载的更新会在后续同步后出现。这只是特定平台的语义示例，应用仍要决定是否以及何时重新读取文件。迁移时应按实际运行环境验证，不能把“控制台已保存”当作“所有实例已生效”。

启动时配置通过滚动发布统一，发布系统记录应用版本与配置版本的配对。动态配置先生成不可变版本，通过订阅或拉取取得完整快照，校验成功后在清晰边界原子替换内存视图；校验失败、连接中断或收到旧版本时继续使用最后一个已确认版本并告警。对支付、库存、权限、路由等影响正确性的配置，避免在单个业务事务中途切换版本，必要时把版本绑定到请求、任务或业务对象。

• 每个键标注重启生效、重新加载生效或按业务审批生效。
• 实例暴露不含秘密的应用版本、配置版本、加载时间和结果。
• 更新失败保留最后确认版本，不把空值或部分响应当作完整配置。

实施步骤：影子比较、单一写源、小范围切换再退役旧入口

迁移顺序应先让新读取路径可验证，再改变业务行为。直接把生产全部键导入中心并关闭旧文件，会把拼写、类型、权限和网络问题集中到一次不可逆切换。

第一步冻结键清单和优先级，清理重复命名但暂不改变行为；第二步建立配置契约、版本快照、权限和审计；第三步让应用在影子模式读取新来源，只比较规范化后的结果并报告差异，不驱动业务；第四步选择内部环境、后台任务或低风险实例，以新来源为主、已确认旧快照为回退；第五步按实例或租户扩大，观察加载失败、版本分布和业务指标；第六步停止旧入口写入，超过观察窗口后移除旧读取代码与权限。

回滚对象应是完整、已验证的配置版本和与之兼容的应用版本，而不是逐个手工改键。回滚前判断失败来自配置内容、分发系统还是应用兼容；若配置中心不可用，应用是否继续使用本地最后快照、拒绝启动或进入受限模式，要按配置的重要性提前决定。缓存快照必须限制权限并有更新、过期和清理规则，不能成为无人治理的新旧配置文件。

• 影子读取只比较结果，不写业务数据、不触发外部调用。
• 按环境、实例或租户灰度，记录继续、暂停和回滚条件。
• 旧写入、旧读取、旧账号与旧配置文件分别取得退役证据。

验收与风险：证明配置正确、分发一致、故障可控

验收不能只检查配置中心在线。需要覆盖合法与非法值、版本并发、实例重启、网络中断、权限拒绝、过期秘密、动态更新、滚动发布、客户端缓存和完整回滚。

准备包含正常、边界、缺失、类型错误、跨键冲突和旧版本的脱敏样例，确认发布前校验能够拒绝错误。并行运行多个实例，检查同一灰度组使用预期版本；在更新过程中重启、扩容和恢复网络，验证新实例不会意外拿到另一批配置。对小程序、APP 和 AI 智能体入口核对服务端配置变化是否与客户端版本、缓存、租户及工具权限一致，不把客户端尚未刷新误判为中心失效。

风险清单至少包括来源优先级反转、双写覆盖、秘密泄露、部分键更新、实例版本漂移、中心故障阻断启动、过快动态变更、旧应用不识别新结构，以及回滚后秘密或业务状态被错误复活。验收交付保留键目录、契约、版本记录、审批、实例分布、差异报告、轮换结果、故障演练和旧入口退役证明；任何关键实例来源不明、秘密无法撤销或回滚只能靠人工猜值时，应停止扩大发布。

• 错误配置在生效前被拒绝，拒绝原因不包含秘密值。
• 灰度、重启、扩容、断网和恢复后实例版本均可核对。
• 配置、秘密、应用与客户端各自的回滚边界已经演练。

需求讨论中的问题

关联服务与实施资料

下面的页面可继续核对相关技术边界、业务接入方式与项目交付条件。

• 旧运行时与依赖升级指南：配合运行时替换，核对启动参数、组件版本和环境差异。
• 旧系统定时任务迁移指南：为任务开关、调度参数、幂等边界和单一执行责任建立受控配置。
• 旧系统登录认证升级指南：处理配置与秘密平台的服务身份、会话、密钥轮换和旧入口退役。
• 旧系统多租户改造指南：让租户级参数、缓存和工具权限遵守统一租户边界。
• AI Agent 智能体开发：将模型、知识库和工具配置与用户委托、租户权限和秘密分开管理。
• 小程序与 APP 一体化开发：协调服务端配置、客户端版本、本地缓存和最低支持策略。
• 软件项目启动资料包：整理环境、账号、依赖、配置责任和验收样例。