配置、文件与交付

本文面向运维人员，说明如何用 Beacon v2 管理配置和文件，并通过变更单把它们安全交付到 Agent。业务插件不应直接调用控制面 HTTP；它们应使用本机 Agent API，见 业务插件 SDK。

版本边界：本文以 v2 为准。/admin/v1 的旧配置、文件树和覆盖集 API 仅为兼容参考，不能与 v2 的配置文件、文件资产、变更单混在一次发布中。

1. 先理解三类对象

对象	用途	是否直接改目标服
配置文件	受五层作用域覆盖的文本配置	否，先形成版本
文件资产	Agent 扫描上报的本机文件清单	否，只读索引、预览与对比
变更单	把配置工件或文件差异投放到选定服务器的发布单元	是，由 Agent 执行

配置的作用域从低到高为：namespace → BCCluster → Region → Zone → server。相同配置文件在更具体层会覆盖更宽泛层；先使用有效预览确认结果，再创建交付。

2. 配置文件操作

1. 在管理台的「配置」选择 namespace，并新建或打开目标配置文件。
2. 选择要写入的作用域。全局默认放在 namespace；只针对某个小区或单服的差异放到 Zone 或 server，避免复制整份文件。
3. 编辑前查看当前版本、历史版本和 Diff；保存时填写可追溯的变更说明。
4. 运行格式/结构校验。校验失败先修复内容，不能以跳过校验的方式发布。
5. 在「有效预览」选择一个实际目标服务器，核对合并后的内容、来源层和被删除的键。
6. 如需撤销尚未交付的版本，使用该文件的版本回滚；已交付的变更应按变更单回滚，不要手工覆写目标服文件。

建议把一项业务变更拆成小且可解释的配置版本。敏感值不要写入截图、审计备注、工单或 Wiki；需要保存敏感配置时，先确认控制面已按部署要求配置静态加密和密钥管理。

3. 文件资产与受管文件

Agent 可按本地 assets.enabled 和扫描周期上报 plugins 目录及服务器根目录的文件清单。它用于盘点、跨服比较和受控发布前的事实确认。

1. 在「文件资产」按 namespace、服务器或路径搜索；先检查扫描时间和状态，过期时请求重新扫描。
2. 用预览和比较确认内容、哈希、大小及差异范围。二进制或敏感文件应只查看允许的摘要/脱敏预览。
3. 需要纳管的现存文件，先以受控导入或审核流程创建文件差异；不要在多台机器上手工复制后再假定内容一致。批量导入单次最多 2000 个文件（每文件需配一条等长的相对路径，两者按提交顺序一一对应）；超限返回 422 并带上限数字，数量不一致会报出两个实际数量——据此判断是拆批还是修表单。
4. 对第三方插件的覆盖或重载，只能使用经过审批的变更单。Agent 本地 override.command-whitelist 为空时不会执行任何重载命令；不要为方便而放宽白名单。

文件资产索引是只读事实，不等于文件已被 Beacon 托管。仅当变更单明确包含文件差异或配置工件时，才会写入目标 Agent。

4. 创建并执行变更单

一次变更单只处理一个可回滚的目的，例如「为某个 Zone 更新大厅配置」或「向一批测试服发布同一插件配置」。

1. 选定来源：添加已冻结的配置版本和/或已审核的文件差异。
2. 选择目标：按 namespace、BCCluster、Region、Zone、server 或明确服务器名单选择；再次核对不会跨 namespace。
3. 执行差异扫描和影响面预览，确认目标数、文件清单、覆盖关系与可能重启方式。
4. 提交变更单，按权限完成审批。审批前可撤回；被拒绝后修订内容并新建或按流程重新提交。提交时必须填写操作原因（未填写时确认按钮置灰）；同一提审意图因网络等原因重试时，请复用同一幂等键，弹窗关闭或向导重开后该键作废。
5. 启动交付后，在变更单详情跟踪每个目标的下载、应用和生效状态——逐台状态、失败原因与备份标记都在单服级状态墙上；页内汇总行「本页 M 台失败」只覆盖当前页（默认 20 台/页），总台数请以全单统计为准。事件时间线优先走 SSE 实时推送；连接失败或流结束会自动回退 5 秒轮询，界面会标注当前处于「实时推送中」还是「轮询刷新中」——看到后者不是故障，按 seq 去重不会丢进度。
6. hot_reload 必须等待 Agent 的成功回执；restart 以服务心跳恢复为生效依据。超时或失败目标不会被视为成功。
   • restart 需要宿主机具备自启能力（docker restart / systemd）：Beacon 只负责关服，不负责拉起。
   • 若目标平台未实现「优雅关服」原语，Agent 不会回执成功，而是直接判 failed 并提示改用 hot_reload / push_only 或手工重启。同一命令只会有一条回执，因此「回执 success 但服务没关」这类假成功已不再可能；若仍见不到重启，先查宿主自启配置。
7. 在观察窗内查看健康、TPS、玩家数和告警。确认无异常后再推广到下一批；发现问题立即停止后续批次并优先回滚出问题的目标（见下节）。
   • 观察窗防呆：restart 生效的目标有 90 秒重启预热期，预热期内不参与健康恶化评估。因此「restart + 健康恶化阈值 > 0 + 观察窗 < 90 秒」是无效组合，创建/编辑时会被直接拒绝并说明原因——请把观察窗调到 ≥ 90 秒，或改用 push_only / hot_reload，或关闭健康恶化阈值。该防呆只在本次提交改动了「生效方式 / 健康恶化阈值 / 观察窗」三者之一时生效，存量单仍可编辑无关字段。
8. 已开始执行的动作会返回 202 票据并提示「已提交审批（申请号 X）」——这表示申请已建、尚未生效，请到审批中心处理；不要把它当成「点完就推进」。

Agent 通过控制面中转的内容寻址 blob 流式传输文件，可断点续传；控制命令本身不承载文件正文。控制面不会主动反连 Agent。

5. 审批与受控内容

• 发布、回滚、导入、删除、覆盖集与系统更新会创建统一审批申请；提交人应填写影响和原因，审批人与申请人应保持职责分离。例外：健康权重调整与敏感路径规则变更属直接执行（写审计），通用设置项 PUT /admin/v1/settings/{key} 仍走审批。
• 审批中心显示冻结快照、影响范围、状态时间线和执行结果。只有 worker 成功并写入执行回执后，领域变更才算完成。
• 内容读取不走审批：文件正文、实时日志、受限目录浏览与消息 payload 读取为 content.read + management.read 直接执行，不创建审批、不签发或消费一次性授权。审计前置于返回内容之前，记录主体、时间、目标路径与结果，但不保存正文。
• 这条放宽有明确代价，部署时须知情：任何具备 management.read 的主体都可直接读取上述正文，明确包括只读 API key——持有相应凭据的自动化因此可能读取服务器上的凭据文件。接受前提是凭据已按最小权限发放；若存在过度发放的只读凭据，应视为需要收敛的风险。
• 旧的一次性授权领取路径（文件预览/差异、payload、日志与目录浏览的 grants/{grantId}/consume）仍保留可用，供过渡期客户端逐步切换；新接入方不应再走该路径。
• 敏感路径规则：修改规则本身直接执行（不改正文读取权限），命中 glob 的文件被标记为敏感。写入时做 glob 归一化与逐条编译校验（无效 glob 拒绝落库，防止敏感保护静默失效），事务内落库并记录改前改后差异审计；清空规则等价于关闭敏感保护，允许但同样入审计。

6. 交付前后验收清单

• 目标均处于预期 namespace，且身份已确认、在线并有近期健康数据。
• 已看过有效配置和影响面，不存在意外覆盖或敏感文件泄露。
• 交付策略、批次范围、生效方式和回滚负责人已明确。
• 每个目标都有最终状态；失败、超时和跳过项均已解释。
• 观察窗内健康、日志、命令结果与业务验收均正常。

7. 常见失败处理

现象	先做什么
有效预览与预期不同	检查五层作用域、版本和删除标记；修正来源层后重新冻结工件。
目标长期未生效	查看命令观测与 Agent 本地 /beacon status；确认 hot_reload 回执或 restart 后的心跳。
某批失败、其余成功	暂停推广，导出失败目标与错误摘要；优先用子集回滚只回滚受影响目标（见 回滚与交付版本），再修正并重新建单。
Agent 拒绝重载	核对本地白名单和命令安全规则；不要通过扩大任意命令权限绕过。

8. 对象状态口径

详细症状分流见 排障手册。上文各对象的状态口径如下：

• 配置版本：一旦冻结即不可变，所有修改都产生新版本；已交付的变更只能用变更单回滚，不能靠覆盖旧版本“修复”。
• 文件资产：索引是只读的扫描事实，扫描过期时先请求重新扫描再据以决策；索引本身不代表文件已受 Beacon 托管。
• 变更单：按批次推进，每个目标都必须落到终态（成功、失败或跳过），失败与超时不计入成功；hot_reload 以 Agent 成功回执为准，restart 以心跳恢复为准。
• 紧急终止后的目标状态：从未开始的 pending 目标变 skipped（确实没动盘）；已推送 / 生效中的在途目标会被收口为 failed（原因固定为「变更单已紧急终止，目标未确认生效」）——它们已经动过盘，必须检查并按需回滚。终止不等于安全。
• 回滚粒度：支持整单回滚、目标级（子集）回滚与回滚失败重试，语义见 回滚与交付版本。

9. 配置热重载的两个运行参数

hot_reload 的等待行为由 Agent 侧两个参数决定。两者都可由控制面下发（同样是 namespace 默认 + server 覆盖），也可写在目标 Agent 的 config.yml 的 delivery 段或经 BEACON_AGENT_DELIVERY_* 环境变量注入：

键	类型	默认	范围	说明
delivery.config-reload-timeout-ms	int	30000	0–3600000	单业务插件配置重载超时（毫秒）。填 0 = 不设超时（不建议：卡死的插件会一直占住派发线程）
delivery.reload-pool-size	int	64	1–256	单服并发 reload 的插件数上限

改超时不重建执行载体：超时只是等待预算，新值在下一次派发时按新预算判定，不打断在途任务。因此下发后最长约 30 秒被 Agent 拉取，随后的一次 hot_reload 即按新值计算。

改并发位会换线程池，但在途任务不丢：新池接管后续派发，旧池只停止接收新提交，已排队与在跑的重载都会跑完——不会因为「顺手调了个参数」把一批插件的重载判成失败。只有停机时才会强制中断排队任务。

不抖动、不静默改值：

• 新值与当前值相同时不重建线程池（周期下发会反复送同一个值）。
• 越界或非法的下发值有明确处置：控制面写入侧直接拒绝并说明期望类型与范围；Agent 侧对非整数保留当前值并告警，对越界值收口到边界并告警。不会静默套用默认值——「Web 显示已下发、实际与你填的毫无关系」比拒绝更难排查。

超时必须小于变更单的生效超时（activateTimeoutSec）：否则控制面先判整体超时，回执里看不出是哪个插件卡住，单插件超时保护等于失效。若某张变更单把生效超时设得很短，请同步调小该值。

影响面：这两项只影响 hot_reload 下派发给业务插件的重载等待与并发度；不改变文件下载、落盘、push_only / restart 的行为，也不改变回执的成功判定口径。