xiis插件上传治理与热更新生命周期

插件上传治理把文件校验下沉到内核：大小上限按三层取最小值，扩展名先过黑名单再过白名单，内容类型与文件头魔数逐项核对，任一不符即拒绝且不转发插件。正文则按大小与编码自动选择落盘、内存与编码三种通道，插件与内核的内存占用都保持在常数级。

上传治理的校验链

校验链在大小的处理上遵循取交集与只收紧原则：全局请求体上限、站点级上传上限与清单边界三者取最小值，任何一层配大都不会放宽其余层。扩展名校验先看禁止访问名单，命中即拒绝；随后核对站点与清单两级白名单的交集；最后检查请求声明的内容类型与文件头魔数是否匹配，防止改名伪装。

上传声明是可选标记：只有声明了上传段的路由才套用文件名与扩展名校验，普通回显类路由不会被误伤。需要落盘但不需要校验的路由，只声明传输方式即可。

正文三通道

正文通道由内核按条件自动选择：路由显式声明落盘或正文预计超过阈值时走文件通道，内核把正文写入插件数据目录并只传路径；合法且长度可控的文本走正文通道；二进制或转义后超限的内容走编码通道。插件应当三种都实现，统一按先看文件字段、再看编码字段、最后看文本字段的顺序读取。

生命周期全景

加载阶段创建数据目录、拉起实例并等待握手；转发阶段从空闲实例池取实例、写请求、读响应；超时实例被强制终止并重启，绝不回收，防止残留数据与后续请求错位；崩溃实例上的在途请求立即失败；窗口内失败累计达到阈值即熔断停用，修复程序文件后自动恢复。卸载通过关闭实例标准输入完成，主程序退出时并行发送关闭信号，总预算之内未退出即强制终止。

配置边界有一条容易忽略的规则：插件上传通道采用配置文件口径，不读数据库；数据库中的上传上限只作用于常规 CMS 上传。调整插件上传能力只需要改配置文件与清单两处，改动即可全链路生效。

热更新节拍

目录扫描复用配置热更新的节拍：比对插件根目录与各站点目录的修改时间以及清单与程序文件的指纹，没变立即返回；发现变化后把加载、卸载与重启投递到独立处理流程，本轮回调立即返回。清单与程序文件任一变化都会触发重载，程序文件变化还会重启该插件进程。

上传审计与提示

含正文的请求与声明了上传段的路由会留下一条审计记录：站点、插件、路径、客户端地址、字节数、通道、中转文件、耗时与结果都会被记录，日志中不含正文与请求头，避免凭据泄漏。排查上传问题时先看审计记录，通道选择与校验结果一目了然。

表单上传需要插件自行解析，或者改用正文即文件字节、查询串传文件名的约定。大文件下载有两条现成通道，按文件是否已在磁盘上选择即可。

使用要点

• 上传类路由显式声明超时秒，超时只衡量排队与插件处理时间
• 落盘中转文件由内核在响应写回后清理，插件不要删除
• 大文件下载优先用响应落盘通道或静态资源托管，不走正文通道
• 熔断停用后修改程序文件即可自动恢复，不需要重启主程序

上传治理把最容易做错的上传校验变成内核统一职责，热更新把生效过程变成秒级自动动作。两者配合之下，插件的维护成本集中在业务逻辑本身，边界与生命周期由内核兜底。