8.0 KiB
8.0 KiB
插件系统阶段实现计划
本文以 plugin-system-design.md 作为最终目标设计文档，把插件系统拆分成多个可上线的实现阶段。每个阶段都必须在结束时保持 gateway 当前可用：可以启动、可以回滚、可以排障，且不会要求后续阶段补齐后才能恢复基本能力。
插件开发工具链作为跨阶段交付项单独设计，见 plugin-development-toolchain-design.md。工具链主入口为 gateway plugin init/build/test，并需要从第一批 Go plugin 示例开始预留未来 runtime adapter。
拆分原则
- 以可用的纵向切片拆分，而不是按数据库、API、UI、SDK 等横向模块拆分。
- 每个阶段都必须有明确的启用路径、失败回退路径和最小运维证据。
- 默认运行路径保持保守：先稳定
go-plugin + upstream.connect/v1，再增加源码包、治理、观测和未来 runtime。 - 未来能力必须可关闭、可灰度或只做设计预留，不能破坏前一阶段的可用状态。
plugin-system-design.md是目标状态；阶段文档只描述实现顺序和阶段边界。
阶段总览
| 阶段 | 文档 | 阶段结束时可用状态 |
|---|---|---|
| 1 | Managed Binary Plugin MVP | 管理员可以上传二进制 .mcgp，通过 Admin API/CLI 加载、启用、禁用、删除可信插件；upstream.connect/v1 dialer mode 可用 |
| 2 | Protocol Proxy MVP | upstream.connect/v1 protocol-proxy mode 可用，插件可以接管 MC 字节流并实现登录代理示例 |
| 3 | Source Package Builder | 管理员可以上传 source .mcgp，受控 builder 产出可加载 artifact，构建失败不影响当前插件 |
| 4 | Admin UI, Config, Secret, Rollback | 管理页具备可操作的插件管理闭环，支持配置 schema、secret、配置快照和回滚 |
| 5 | Governance And Release Gates | 生产启用前有准入策略、review、冲突分析、preflight/self-test、性能门禁和安全公告处理 |
| 6 | Observability And Operations | 插件 metrics、events、trace、日志、诊断、background task、plugin_data 和文件资源治理可用 |
| 7 | Extension Ecosystem | 在稳定主路径上增加 route/status/provider/event/rule/Admin auth 等扩展点和官方插件能力 |
| 8 | Future Runtimes And Distribution | 可选引入 go-plugin-process、sandbox/WASM、ingress service、仓库、签名和构建期增强；默认路径仍可运行 |
功能到阶段映射
下表用于确认 plugin-system-design.md 中的目标能力已经拆入某个阶段。一个能力可能在早期阶段先实现最小可用版本，后续阶段再补齐治理、UI 或生态扩展。
| 目标能力 | 阶段 | 拆分说明 |
|---|---|---|
.mcgp binary artifact、manifest 静态校验、artifact 登记 |
1 | 先支持二进制可信 Go plugin，上传不执行代码 |
| Plugin Manager、desired/runtime state、dispatch table、审计 | 1 | 建立正式管理路径，替代探索式 config 插件入口 |
upstream.connect/v1 dialer mode |
1 | 第一条可用数据路径，覆盖 upstream rewrite、自定义拨号 |
upstream.connect/v1 protocol-proxy mode 和 net.Conn 接管 |
2 | 支持完整 MC 字节流接管、initial data replay、draining |
| MC 正版/三方登录插件、forwarding、登录后协议处理 | 2 | 由 protocol-proxy 插件实现，core 不消费认证结果 |
| Minecraft capability manifest、protocol smoke fixture | 2 | 支撑管理页展示和后续发布门禁 |
source .mcgp、builder、构建 provenance |
3 | 源码包构建成 plugin.so 后复用阶段 1/2 加载路径 |
| builder 隔离、Go/module/ABI 记录、source/build log GC | 3 | 构建失败不影响 active artifact |
gateway plugin init/build/test 开发工具链 |
1-3，后续扩展 | 阶段 1/2 提供 Go plugin 模板和 harness，阶段 3 收敛 source/binary 打包；后续 runtime 通过 adapter 接入 |
| Admin 页面基础管理闭环 | 4 | 上传、构建状态、加载、启用、禁用、删除、回滚 |
| 配置 schema、配置快照、配置迁移入口 | 4 | 错误配置不切换 active artifact |
| SecretStore、secret version、reload/rotation 基础 | 4 | secret 不在页面、日志、审计中明文展示 |
| artifact rollback、config rollback | 4 | 回滚前重新执行当前基础门禁 |
| admission policy、review、risk、warning override | 5 | 生产启用前可解释和可审计 |
| composition conflict、scope overlap、dispatch plan | 5 | 阻断 protocol-proxy 重叠、provider 单例冲突等 |
| preflight/self-test、benchmark release gate | 5 | 高风险插件启用前有证据 |
| denylist、quarantine、revoke、安全公告 | 5 | 阻断受影响 artifact 的 enable/rollback |
| metrics、custom metrics、business events、trace | 6 | 提供运行时观测和脱敏摘要 |
| plugin logger、diagnostic package、Runbook 支撑 | 6 | 插件故障可定位、可降级、可导出摘要 |
| background task、ExternalClient、外部依赖治理 | 6 | 周期同步、受控外联、熔断和健康状态 |
| PluginDataStore、PluginFileStore、runtime file GC | 6 | 插件私有数据和文件资源受配额/retention 管理 |
| route resolver/provider、route decision | 7 | 降低动态路由和外部 CMDB 集成成本 |
| status ping、MOTD、维护模式 | 7 | 不必完整 protocol-proxy 即可定制状态响应 |
| middleware、provider、event subscriber、rule/policy engine | 7 | 补齐 Hook 之外的生产扩展形态 |
| Admin auth provider、外部身份绑定 | 7 | 只影响管理页登录，保留本地 break-glass |
go-plugin-process 服务启动模式、进程级卸载、fd/shm 迁移 |
8 | 未来可选，默认 in-process 路径仍可运行 |
| sandbox-process、WASM、capability enforcement | 8 | 面向隔离、跨语言和轻量规则场景 |
ingress.service/v1 自定义入口服务 |
8 | 由 gateway/supervisor 管理 listener，不允许插件任意监听 |
| 插件仓库、签名、SBOM 漏洞扫描、license policy | 8 | 仓库只导入本地 artifact，不自动启用 |
| build-time instrumentation | 8 | 官方/组织 CI 能力，产物是 gateway binary，不是热加载插件 |
| promotion、drift、DR drill | 4-6 | 阶段 4 建立回滚和快照，阶段 5/6 补齐门禁、diff、诊断和演练证据 |
全阶段不变量
这些规则从阶段 1 开始就不能被破坏：
- 上传包校验不能执行插件代码。
- 生产路径统一以
.mcgpartifact 为单位管理。 - 插件管理写操作必须有审计日志。
- 启用失败不能破坏旧 dispatch table。
- 禁用插件后，新连接不能再进入该插件。
- 已加载 Go plugin 不能承诺真正热卸载；只能逻辑禁用或未来通过
go-plugin-process退出子进程回收。 - MC 正版/三方登录、身份映射、forwarding 和后续协议处理属于 protocol-proxy 插件，不由 gateway core 拼装。
- 玩家名、UUID、source IP、secret、token、session response 和 packet payload 默认不进入指标标签、审计明文或普通诊断输出。
阶段推进规则
进入下一阶段前必须满足：
- 当前阶段文档中的验收项全部通过。
- 已实现能力有最小自动化测试或可重复手动验证步骤。
- 失败路径已验证：加载失败、启用失败、禁用、删除、重启恢复。
- 文档已更新：用户怎么启用、怎么回滚、怎么排障。
如果某阶段出现实现复杂度超出预期，允许拆出子阶段，但子阶段也必须保持“当前可用”。