Renovate：从依赖发现、规则编译到受控合并
一夜之间出现几十个 PR，问题不一定是机器人太勤快
周一早上，仓库里同时出现运行时、测试库、基础镜像和 GitHub Actions 的更新 PR。有人先把机器人停掉，因为 CI 队列已经被占满；另一个人把所有 patch 更新合成一组，结果一个测试工具的破坏性变更混进了本该自动合并的低风险组。更糟的是，团队后来发现另一个目录里的锁文件从未被识别，所谓“依赖都在自动更新”只是主目录看起来很热闹。
这不是一个“PR 太多”的单点问题。Renovate 每次运行都要经历配置合成、文件发现、依赖抽取、版本查询、候选过滤、分支计算、锁文件重建、PR 编排和合并判断。任何一层的输入错误，都可能在最后表现为“没更新”“反复重建”“突然刷屏”或“错误自动合并”。架构师需要观察的是这条状态链，而不是只统计机器人发了多少 PR。
Renovate 实际在处理哪些对象
Renovate 不是一个定时执行 npm update 的脚本。它先由 manager 识别某类文件和其中的依赖，例如 npm manager 读取 package.json，Dockerfile manager 读取镜像引用，GitHub Actions manager 读取 workflow 中的 action 引用。manager 产出的依赖记录通常包含包名、当前值、版本方案和 datasource 等信息。
datasource 决定去哪里查询候选版本及其元数据。npm 依赖通常查询 npm registry，Docker 镜像查询容器 registry，GitHub tag 则从 GitHub release/tag 元数据获得候选。manager 回答“仓库里写了什么”，datasource 回答“外部世界有哪些可选版本”；把二者混为一谈，会让排障停在错误位置。文件没有被 manager 发现时，改 Registry Token 没有用；依赖已经抽取但 lookup 失败时，继续扩大文件匹配范围也没有用。当前支持对象和每种对象的边界应从官方的 manager 目录与 datasource 目录核对，不能依据一份静态数量清单作承诺。
候选版本查到以后，Renovate 还会应用版本规则、稳定性判断、忽略规则、分组、时间窗和并发限制。通过过滤的更新才进入分支或 PR 状态。PR 上的 CI 结果、审批和平台保护规则继续决定它能否合并。因此一条依赖的典型状态可以写成：
未发现 -> 已抽取 -> 查询成功 -> 候选已过滤 -> 等待时间窗
-> 计算分支 -> 重建锁文件 -> 创建/更新 PR -> 检查通过 -> 合并每个箭头都可能停住。debug 日志里的 packageFiles、depCount、lookup、config、branch 和 pr 相关事件，是把表面现象还原到中间状态的证据。最终配置只在本次运行中合成，并不会作为一个永久对象保存；官方配置概览说明它可以从日志中观察。治理上应保存配置源码、运行镜像身份和必要的脱敏日志，而不是假设下次运行仍使用完全相同的隐式默认值。
托管 App 与自托管的责任边界
GitHub Cloud 仓库可以安装 Mend 托管的 Renovate App。平台侧负责运行基础设施和 Renovate 进程，仓库团队仍要决定 App 能访问哪些仓库、是否接受 onboarding PR、仓库配置如何评审、哪些检查是必需的，以及更新 PR 最终由谁负责。安装后没有 onboarding PR 时，应沿 App 安装范围、仓库授权、默认分支和托管日志排查，而不是在仓库里反复创建多份配置。入口和行为以 GitHub 平台接入文档与安装和 onboarding 文档为准。
版本与许可必须跟运行形态一起记录。Renovate OSS CLI 按连续发行线快速发布，源码与官方 CLI 使用 AGPL-3.0-only；Mend Renovate Self-Hosted Community Edition / Enterprise Edition 是另一种有状态产品形态，发布节奏更慢，并使用 Mend EULA，而不是 AGPL。托管 App 的实际运行版本由 Mend 维护，仓库不能从 renovate.json 固定它；自托管 CLI 则应固定容器 digest 或精确包版本，并把 renovate --version、镜像 digest、配置 preset 版本写入每轮证据。不能只写“使用最新版”，也不能把 OSS CLI、Mend CE/EE 与托管 App 的版本和许可混成一条基线，边界见官方运行方式与许可说明和Renovate 文档首页。
自托管把更多控制权和更多故障责任交给团队。团队要提供运行节点或 CI Job、机器人身份、平台 Token、网络与 CA、调度器、临时工作目录、缓存、日志采集和 Renovate 自身升级。官方同时提供 npm CLI 和容器等运行入口；不同镜像形态、工具内置情况和运行要求会变化，应从运行方式文档选择，而不是把某个动态镜像标签写成永久基线。
选择标准不只是“是否想维护服务器”。满足以下任一情况时，自托管通常更容易建立清晰边界：代码平台位于内网；私有 Registry 只能从受控网络访问；需要自有 CA、代理或出口审计；组织要严格限制仓库发现范围；日志不得进入外部托管域。反过来，如果仓库在 GitHub Cloud、依赖源可公开访问、团队不愿承担运行和升级责任，托管 App 通常能减少控制面的维护量。商业托管能力、套餐和界面会变化，决策时应回到当前官方入口核对。
无论哪种形态，机器人都需要读取仓库；要创建更新分支和 PR，还需要相应写权限。它不应拥有绕过分支保护、管理组织成员、读取无关仓库 Secret 或发布制品的权限。运行 Renovate 等于允许它解析仓库配置，并可能调用包管理器或辅助工具处理仓库内容；自托管实例与被处理仓库之间存在信任关系。官方自托管示例也明确提醒这一安全含义。高敏感仓库和普通业务仓库不宜无条件共用一个高权限 Bot、缓存和日志域。
先用本地 dry run 看见抽取与查询
下面的实验不需要 GitHub 或 GitLab Token，也不会创建分支和 PR。它使用官方容器的 local 平台读取当前目录。这个平台目前是实验能力，默认执行 dryRun=lookup；即使传入 full 也会退回 lookup，而且不支持创建分支。因此它适合验证配置、manager 抽取、datasource 查询和规则匹配，不适合证明平台写权限与 PR 生命周期。限制以 local 平台文档为准。
实验需要 Docker 能拉取官方镜像，并允许容器访问公开 npm Registry。先创建一个一次性目录：
mkdir renovate-lab && cd renovate-lab
cat > package.json <<'JSON'
{
"name": "renovate-lab",
"private": true,
"dependencies": {
"lodash": "4.17.20"
},
"devDependencies": {
"eslint": "8.0.0"
}
}
JSON
cat > renovate.json <<'JSON'
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"enabledManagers": ["npm"],
"packageRules": [
{
"description": "生产依赖独立处理",
"matchDepTypes": ["dependencies"],
"groupName": "runtime dependencies"
},
{
"description": "实验中禁用 eslint 更新",
"matchPackageNames": ["eslint"],
"enabled": false
}
]
}
JSON在 Linux、macOS 或 Git Bash 中运行：
docker run --rm \
-e LOG_LEVEL=debug \
-e LOG_FORMAT=json \
-v "$PWD:/workspace" \
-w /workspace \
renovate/renovate \
--platform=local \
--dry-run=lookupPowerShell 对应命令是：
docker run --rm `
-e LOG_LEVEL=debug `
-e LOG_FORMAT=json `
-v "${PWD}:/workspace" `
-w /workspace `
renovate/renovate `
--platform=local `
--dry-run=lookup首次运行会拉取镜像并查询 npm Registry。日志字段会随发行线演进，不要把整行文本作为监控契约；判断成功应抓住稳定语义：仓库配置被解析、npm manager 找到 package.json、抽取到两个依赖、lodash 有可用候选，而 eslint 被规则禁用。末尾不应出现“已创建 PR”的结论，因为 local 平台没有这个能力。可以把完整 JSON 日志保存到临时文件，再以 depName、manager、datasource、skipReason 和级别筛选证据。
生产自托管不应长期追随浮动镜像。上面的无标签镜像只是为了让一次性实验可复制；进入团队运行环境后，应由依赖更新流程本身把 Renovate 镜像固定到经过审批的 tag 或 digest，并定期升级。固定过久会积累解析器、安全修复和平台兼容性差距，永远追随浮动标签又会让同一配置在两次运行间改变执行器，二者都不利于复盘。
反向实验：让 Registry 查询稳定失败
现在把一个 scoped 包指向保留域名 example.invalid。这个域名不会误触真实内部服务，也不需要伪造 Token：
cat > package.json <<'JSON'
{
"name": "renovate-lab",
"private": true,
"dependencies": {
"@lab/private-widget": "1.0.0"
}
}
JSON
cat > .npmrc <<'NPMRC'
@lab:registry=https://registry.example.invalid/
NPMRC重新执行同一个容器命令。预期 manager 仍然发现 package.json 并抽取 @lab/private-widget，随后 datasource 查询在 registry.example.invalid 失败。网络栈和发行线可能把证据呈现为 DNS、连接或 datasource lookup 错误，但关键因果必须同时成立：抽取成功，查询失败，没有更新分支或 PR。如果日志连依赖名都没有，先检查 manager 和文件匹配；如果能看到依赖却看不到目标 Registry，检查 .npmrc 是否被工作目录和包管理器语义读取；如果目标正确且认证失败，才进入 hostRules 和凭据排查。
修复时恢复公开依赖和 .npmrc：
rm -f .npmrc
cat > package.json <<'JSON'
{
"name": "renovate-lab",
"private": true,
"dependencies": {
"lodash": "4.17.20"
},
"devDependencies": {
"eslint": "8.0.0"
}
}
JSON再次运行后，应重新出现 lodash 的候选查询证据，且不再访问 registry.example.invalid。这次“修复”只证明本地抽取和公开查询恢复；它没有证明托管 App、真实私库、平台 Token、分支写入、CI 或自动合并可用。
配置不是一份 JSON，而是一轮有优先级的合成
Renovate 按层读取默认配置、全局配置、继承配置、解析后的 preset 和仓库配置。高优先级值通常覆盖低优先级值；只有配置参考中标记为 mergeable 的字段才按定义合并。同一仓库若同时存在多个候选仓库配置文件，Renovate 使用搜索顺序中第一份，忽略后续文件。配置概览给出了当前顺序和例外。
这里还要分清两种“配置文件”。自托管进程默认在工作目录读取全局 config.js，也可用 RENOVATE_CONFIG_FILE 指定 .js 或 .json；仓库配置默认是默认分支上的 renovate.json，其他候选名只用于兼容和定制。组织共享 preset 推荐使用 renovate-config 仓库中的 default.json；回退查找其中 renovate.json 的行为已经被官方标记为 deprecated，不应继续作为新组织模板。配置发现实验应故意同时放两份候选仓库配置，确认日志只加载第一份，然后删除多余文件恢复单一事实源；这能证明“发现顺序”，而 schema validator 只能证明每一份单独可解析。
这带来两个常见误判。第一，仓库里新加 renovate.json5，但更早命中的 renovate.json 仍存在，新文件不会成为“补充配置”。第二，组织 preset 里有两条 packageRules，仓库又加一条规则，数组的合成与规则顺序可能让同一个依赖连续匹配多条；最后匹配到的字段会影响最终策略。不能只看某一份源码推断结果，应在 debug 日志里检查合成后的配置与该依赖匹配的规则。
自托管的全局配置负责平台身份、仓库发现、管理员强制边界和运行参数，仓库配置负责开发者应能看见和评审的更新策略。凭据不要放进仓库 preset。仓库专属规则也不宜隐藏在只有平台管理员能看见的环境变量里，否则开发者看到一个异常 PR 时无法解释机器人为何这样决策。
extends 引用 preset。preset 可以是官方内置规则，也可以是组织仓库中维护的共享配置。下面的仓库配置把组织基线和仓库局部策略分开：
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": [
"config:recommended",
"github>example-org/renovate-config:service-default"
],
"packageRules": [
{
"description": "数据库驱动必须由数据平台 owner 审查",
"matchPackageNames": ["pg", "mysql2"],
"addLabels": ["dependency:database"],
"automerge": false
}
]
}config:recommended 的展开内容会随 Renovate 演进，因此把它当作一个可升级依赖，而不是复制一份永不复核的口头说明。组织 preset 也应做版本化发布、测试仓灰度和变更记录。仓库里显式 extends 的好处是开发者能追到规则来源；若共享 preset 被删除、改名或访问权限撤销，配置解析会失败，影响范围可能覆盖整个组织。
配置变更先运行官方 renovate-config-validator 或容器内的 validator，只能证明语法和 schema；再做 dry run 才能看到文件抽取和候选；最后在低风险试点仓观察真实平台分支、PR 和 CI。三层验证不能互相替代。配置验证文档提供当前入口。
packageRules 要写成可解释的策略编译
packageRules 由 matcher 与动作组成。matcher 可以按 manager、datasource、包名、依赖类型、更新类型、文件名等维度选择依赖；动作决定是否启用、怎样分组、何时运行、加什么标签、是否自动合并。完整字段和可组合性必须查 packageRules 配置参考。
一条规则里至少应让 reviewer 看懂“选择谁”和“对它做什么”：
{
"packageRules": [
{
"description": "低风险开发工具按月度窗口成组更新",
"matchDepTypes": ["devDependencies"],
"matchUpdateTypes": ["minor", "patch"],
"groupName": "development tooling",
"schedule": ["after 02:00 and before 05:00 on monday"],
"automerge": false
},
{
"description": "运行时 major 独立升级并禁止自动合并",
"matchDepTypes": ["dependencies"],
"matchUpdateTypes": ["major"],
"groupName": null,
"automerge": false,
"addLabels": ["dependency:major", "review:architecture"]
}
]
}分组减少 PR 数量，却扩大了失败归因和回滚单元。把同一兼容单元中的框架核心与插件放在一起通常合理；仅因“都是 patch”就把数据库驱动、构建插件、基础镜像和测试框架合成一组，会让一个失败检查无法定位到具体更新。规则应沿运行时边界、owner 和回滚方式分组，而不是只沿版本号级别分组。
规则顺序也会改变结果。多条规则可以同时匹配同一个依赖，后续动作可能覆盖前面动作；有些对象则按 mergeable 语义累积。一次“为什么自动合并了”的排障，必须列出该依赖命中的全部规则和最终配置，不能只找到第一条看起来相关的规则就停止。
hostRules 只解决 Renovate 到主机的一部分认证
hostRules 用来按主机或 datasource 提供 Token、用户名密码、超时、并发和启停等连接策略，字段以 hostRules 配置参考为准。自托管可以在全局配置中从 Secret 环境读取凭据：
module.exports = {
hostRules: [
{
hostType: 'npm',
matchHost: 'registry.example.invalid',
token: process.env.RENOVATE_NPM_TOKEN,
},
],
};示例中的域名和变量都是占位符。真实 Token 由 CI Secret、编排平台 Secret 或密钥服务注入，不能提交到 preset、仓库配置或 debug 日志附件。matchHost 过宽可能把凭据发给不该访问的端点；一份组织级 Token 覆盖所有私库，会放大泄露和供应链混淆风险。更稳妥的模型是按安全域拆分身份，让每个运行实例只访问明确仓库集合和明确 Registry 命名空间。
版本查询成功不等于锁文件更新成功。Renovate 自己可能通过 hostRules 查询到候选，但它调用的 npm、Maven、Gradle、pip 或其他包管理器仍可能从自己的配置读取 Registry 和凭据。于是日志会表现为 lookup 成功，分支阶段的 lockfile 重建却出现 401、证书错误或包找不到。私有包文档要求分别考虑 Renovate datasource 与包管理器执行链。排障时应标出失败发生在“候选查询”还是“重建锁文件”，不能把一个 Token 机械复制到所有配置层。
托管 App 的私库凭据注入入口和可用边界与自托管不同，应从当前托管文档核对；不要把自托管环境变量示例提交进仓库，期待托管平台替你读取。企业 CA 也有双重边界：Node.js 进程信任某个 CA，不代表 Git 和外部包管理器都信任它。自托管镜像需要同时验证 Renovate 进程、Git clone、Registry lookup 和锁文件重建的 TLS 链。
GitHub 与 GitLab 的自托管接入
GitHub 自托管实例至少需要明确 platform=github、仓库集合或受限发现规则、机器人 Token，以及 GitHub Enterprise Server 场景下的 endpoint。下面只展示控制面骨架，Token 由环境注入：
module.exports = {
platform: 'github',
token: process.env.RENOVATE_TOKEN,
repositories: [
'example-org/service-a',
'example-org/service-b',
],
onboarding: true,
};固定 repositories 最容易审计；使用 autodiscover 时必须限制组织、主题或仓库过滤条件，避免机器人因为新授权而扩大处理面。GitHub App、细粒度 Token 和经典 PAT 的权限模型会变化，应按 GitHub 平台文档为当前部署核对。生产验证按读取仓库、创建分支、创建 PR、更新既有 PR、读取状态检查和关闭分支逐项证明，不用“Token 可登录”代替最小权限测试。
GitLab 自托管使用 platform=gitlab 和实例 API endpoint：
module.exports = {
platform: 'gitlab',
endpoint: 'https://gitlab.example.invalid/api/v4/',
token: process.env.RENOVATE_TOKEN,
autodiscover: true,
autodiscoverFilter: [
'platform-services/**',
],
onboarding: true,
};共享 GitLab Bot 被邀请进项目或组时，权限传播可能让它看到超出预期的仓库；恶意仓库还可能利用 Bot 的流水线身份或发布能力。官方的 GitLab Bot 安全说明建议 autodiscover 同时配置过滤，并限制共享服务只覆盖信任边界一致的项目。平台字段、MR 能力和版本相关行为以 GitLab 平台文档为准，不把某个当前平台能力写成永久承诺。
两种平台都应先以只读或 dry run 证明发现范围，再给试点仓分支写权限，最后才扩大仓库集合。直接用组织级高权限 Token 开启 autodiscover，会把“发现错误”放大成“批量写入错误”。
需要向无直接写权限的 GitHub 仓库提 PR 时，Renovate 还有实验性的 fork mode：配置 forkToken 后，它在该 PAT 所属账号或 forkOrg 创建 fork、保持 fork 默认分支同步，并从 fork 分支向上游开 PR。这个 Token 同时扩大了 fork 创建、同步和上游 PR 的权限面；forkOrg 也会改变“允许 maintainer 编辑”的行为。不要把 fork mode 当作绕过上游分支保护的办法，先在测试组织验证 fork 创建、上游目标、同名分支冲突、Token 撤销和 fork 删除；退出时先关闭 PR，再撤销 Token 并清理受控 fork。forkCreation、forkOrg、forkToken 都是可能变化或移除的实验能力，生产采用前应核对自托管配置中的 fork mode。
受保护分支若要求已验证签名，自托管也要单独设计提交身份。GitHub App 可以通过 platformCommit 让 GitHub API 代为创建可验证的 App 提交；直接 Git 写入则可用 gitPrivateKey 注入 PGP 或 SSH 私钥签名。签名密钥属于高价值凭据，应来自密钥服务并限制读取者、轮换和撤销；不能提交到全局配置，更不能用关闭签名规则来换取 Bot 可写。正向证据是 Renovate PR 的每个提交显示预期 signer/Verified 且规则集接受，反向实验使用无签名的隔离 Bot 提交并确认规则阻断。具体模式见platformCommit与gitPrivateKey。
两层调度、两个 PR 限制和一个 CI 容量预算
自托管进程何时启动，由 cron、CI schedule、Kubernetes CronJob 或常驻服务的调度机制决定；仓库配置中的 schedule 只定义某类更新允许被创建或更新的窗口，不会唤醒一个没有运行的 Renovate 进程。调度说明强调了这两个时钟。若进程只在窗口外运行，仓库就会长期显示“等待 schedule”，即使配置本身完全合法。
prConcurrentLimit 限制同时打开的 Renovate PR 数，保护 reviewer 和 CI 的在途容量；prHourlyLimit 限制单位时间创建 PR 的速度，抑制一次配置变化产生的突发。二者语义不同，也不能替代 branchConcurrentLimit 或平台 API 限流。字段默认值和特殊值可能变化，配置时应显式写出经过容量测算的值，并从配置参考核对当前语义。
{
"prConcurrentLimit": 4,
"prHourlyLimit": 2,
"schedule": ["after 01:00 and before 06:00 every weekday"]
}这里的数字只是演示值，不是生产推荐。团队应从更新 PR 的平均 CI 时长、Runner 并发、人工审查吞吐、失败重试量和发布窗口倒推。假设每个 PR 都触发完整端到端测试，允许四个并发 PR 可能同时生成更多分支检查和 rebase 检查；真正消耗的是 Job 数与执行分钟，而不是 PR 计数本身。
当积压增长时，先区分“没有候选”“等待 schedule”“达到 PR 上限”“已有同依赖 PR”“分支出错”和“平台 API 限流”。粗暴提高限制会把策略阻塞转化为 CI 队列阻塞。一个健康不变量是：在依赖源可达、配置有效和窗口持续命中的条件下，符合策略的候选最终离开等待状态；若 PR 年龄和等待原因长期不变，owner 必须收到可行动的告警。
自动合并必须消费平台门禁，而不是替代门禁
Renovate 的 automerge 默认关闭。启用以后，它仍要依据更新状态、检查结果和平台分支保护决定能否合并；如果仓库没有选定必需状态检查，存在测试失败却仍满足 Renovate 合并条件的风险。自动合并文档要求同时检查平台保护配置。
{
"packageRules": [
{
"description": "仅自动合并已固定 digest 的补丁级开发依赖",
"matchDepTypes": ["devDependencies"],
"matchUpdateTypes": ["patch", "digest"],
"automerge": true,
"automergeType": "pr",
"platformAutomerge": true
}
]
}这段配置不是安全证明。上线前还要在平台上验证默认分支保护确实要求构建、单元测试、安全扫描或团队规定的其他检查；失败检查保持阻断；缺失检查不会被当成成功；高风险目录触发 CODEOWNERS；冻结窗口和合并队列语义符合团队发布制度。不要给 Bot 绕过保护规则的权限来“修复自动合并不工作”。
platformAutomerge 默认开启时，Renovate 会把自动合并委托给平台；如果平台没有明确选择 required checks，检查尚未开始、仍在运行甚至失败都可能没有形成阻断。它还会在 PR 创建时登记平台自动合并，因此 automergeSchedule 不能约束平台最终落库时刻；需要严格合并窗口时必须关闭 platformAutomerge，让 Renovate 自己在窗口内决策。若启用 GitHub Merge Queue，CI 还必须监听 merge_group 并把队列临时提交上的检查设为 required。自动合并验收至少做两个反例：一个 required check 失败、一个 required check 根本不产生，两者都必须保持不可合并；只验证“绿灯能合并”是不完整的。
自动合并的风险单元是整个分组。若一个 PR 含多个依赖，只要规则让这个 PR 进入 automerge，所有变更一起越过人工确认。因此低风险组需要同 owner、同回滚方式、同测试覆盖和相近故障半径。运行时依赖 major、数据库驱动、编译器、基础镜像大版本和基础设施 provider 通常应保留人工审查与专门验证。
lockFileMaintenance 刷新的不是一条直接依赖
普通版本更新从某个直接依赖的新版本出发，随后重建锁文件。lockFileMaintenance 则在 manifest 约束不变的情况下重新生成锁文件，让允许范围内的传递依赖重新解析。它有自己的调度和 PR 行为，配置入口见 lockFileMaintenance 参考。
{
"lockFileMaintenance": {
"enabled": true,
"schedule": ["before 05:00 on the first monday of the month"],
"automerge": false
}
}锁文件维护可能一次改变大量传递版本，却不改变 package.json、pyproject.toml 或其他 manifest 中的直接约束。reviewer 应比较实际 lockfile diff、来源完整性、安装脚本变化和构建结果，不能因“没有直接依赖改名”就降低风险。共享锁文件的 monorepo 还可能让一个子目录的维护重写整个仓库解析结果，CI 成本和回滚半径都更大。
若锁文件重建失败，先使用 Renovate 日志确认调用了哪个包管理器和版本，再在同一镜像、同一工作目录、同一 Registry 配置下复现权威安装命令。开发机上能安装不代表 Bot 容器具备相同 CA、代理、CPU 架构、运行时或私库权限。锁文件维护的价值是暴露可解析性漂移；用 ignoreScripts、删除校验或放宽来源来换取绿色 PR，可能掩盖真正的供应链差异。
日志要能回答“停在哪一层”，又不能泄露仓库
自托管首先给每次运行设置关联标识，把启动调度、仓库、分支和平台 API 事件串起来。正常运行可以保留 info 级别摘要；故障窗口临时提高到 debug，并限制保存时间与访问权限。托管 App 的日志通过其托管入口查看，具体界面和保留期属于动态能力，不应写入固定 SOP。故障排查文档给出了从日志定位配置和依赖问题的入口。
一条可行动的故障记录至少要区分：配置解析失败、仓库未发现、manager 未匹配、依赖被忽略、datasource 查询失败、lockfile 重建失败、分支冲突、PR 达到限制、平台检查未通过和合并被保护规则拒绝。只记录 run failed 会迫使值班人员打开全量 debug 日志，也容易把凭据和内部元数据扩大传播。
日志中的仓库名、私有包名、Registry 路径、依赖图和漏洞关联都可能敏感。URL 查询参数、Authorization Header、Token 和包管理器输出必须脱敏；日志发送到外部平台前，评估数据驻留和高基数成本。指标标签不要直接使用完整仓库路径、包名、PR URL 或人员账号，否则监控成本和信息泄露会同时增长。
容量治理还包括平台 API、Registry API、Git clone、磁盘缓存和包管理器下载。仓库数增长时，单轮运行时间可能超过调度间隔，造成重叠任务；缓存完全隔离会增加带宽，跨信任域共享缓存又可能泄露私有包与仓库元数据。自托管执行器应采用互斥或队列保证同一仓库不会被两个实例并发写入，并为临时目录和缓存设置容量、清理与审计策略。
从试点仓接入到团队模板
真实项目接入先盘点 manifest、lockfile、镜像、workflow、IaC、Helm 和自定义版本引用，确认哪些 manager 能识别、哪些需要 custom manager、哪些必须保留人工升级。随后在一个低风险仓启用 onboarding，让生成的配置 PR 接受正常 review。仓库 owner 应检查 manager 发现结果、首轮候选数量、预期分组、时间窗、标签、reviewer 和 CI 成本，再逐步开启更多对象。
组织 preset 适合承载共同基线，例如依赖仪表盘、时区、统一标签、危险 major 禁止自动合并和基础 PR 限制；仓库配置保留业务特有 owner、目录、分组和例外。preset 的 owner 要维护契约测试：固定几个合成仓库，验证规则命中、禁用项、分组和最终配置。一次 preset 变更先 dry run，再灰度到试点仓，最后扩大引用面。
项目验收不能只看“出现了一个 PR”。正向路径应证明 manager 发现完整、datasource 候选可信、规则命中可解释、锁文件由权威工具重建、CI 使用与主分支相同入口、失败检查阻断、合并后发布和运行指标正常。反向路径至少要故意制造一次无效配置、一次 Registry 失败和一次必需检查失败，确认它们分别停在配置、lookup 和合并层，而不是被重试或高权限绕过。
长期 owner 需要定期回答：哪些仓库从未运行；哪些依赖长期被忽略；哪些 PR 超过团队年龄预算；哪些 datasource 或 Registry 失败率上升；哪些规则永远没有命中；Renovate 镜像与组织 preset 多久没有升级；Bot Token 何时轮换；缓存和日志是否跨越了安全域。工具价值来自候选持续流动并留下证据，不来自安装数量。
配置迁移、暂停与彻底退出
从旧机器人迁移时，先暂停旧系统创建新 PR，导出仍在处理的依赖、分支前缀和规则，再让 Renovate 在 dry run 中观察同一仓库。若需要接管旧 PR，可使用 ignorePrAuthor、branchPrefixOld 等迁移能力，但这些开关会放宽身份或分支归属判断，只应在受控迁移窗口使用，语义以自托管配置参考和仓库配置参考为准。
迁移期间最危险的是双机器人同时管理同一依赖：它们可能创建重复 PR、交替 rebase、互相关闭分支，甚至使用不同锁文件工具产生抖动。切换门禁应证明旧系统已停止写入、新系统只管理预期仓库、遗留 PR 的 owner 已确定、分支前缀不会碰撞。不要用长期 ignorePrAuthor=true 掩盖身份混乱。
临时暂停某个仓库，可以在仓库配置中设置 enabled: false。Renovate 处理这个状态时能够关闭其 PR 并清理分支；直接先撤销 Token 或卸载 App，机器人会失去执行清理的能力。退出顺序应是：合并禁用配置，运行一轮并确认 Renovate PR/分支已关闭或转交，停止调度，清理缓存和临时 clone，撤销 Registry 与平台凭据，卸载 App 或移除 Bot，最后删除不再使用的配置和 Secret 引用。enabled 的当前行为见配置参考。
若只是回滚一次错误规则，不要删除全部 Renovate 配置。通过普通 PR 恢复上一个已知配置，运行 validator 和 dry run，再观察机器人对现有分支的处理。需要重新 onboarding 时，官方还提供重新配置流程；它可能关闭现有 Renovate PR，因此必须先记录处理中的升级和审查结论。
清理本地实验，并给生产系统留下可恢复状态
本地实验结束后退出目录，确认目标是当前目录下名为 renovate-lab 的合成工作区，再执行删除：
cd ..
parent="$(pwd -P)"
lab="$(cd -- "$parent/renovate-lab" && pwd -P)"
test "$lab" = "$parent/renovate-lab" || exit 1
rm -rf -- "$lab"PowerShell 使用：
Set-Location ..
$lab = (Resolve-Path -LiteralPath .\renovate-lab).Path
if ((Split-Path -Leaf $lab) -ne 'renovate-lab' -or (Split-Path -Parent $lab) -ne (Get-Location).Path) { throw 'unexpected lab path' }
Remove-Item -LiteralPath $lab -Recurse -Force不要在真实仓库里用递归清理命令，也不要把实验生成的 debug 日志提交到 Git。若为了排障保存日志，先检查是否包含 Token、内部域名、私有包名和仓库路径，再存入受控证据系统并设置销毁时间。
一次生产接入真正结束的标志不是“机器人在线”，而是配置来源可追踪，manager 覆盖面可证明，datasource 与锁文件执行链都能访问必要来源，候选能在容量预算内流动，失败能停在正确状态，自动合并受平台门禁约束，凭据可轮换撤销，暂停和退出已经演练。到这里，Renovate 才从一个会开 PR 的账号，变成一套可解释、可恢复、可治理的升级控制系统。