部署与维护

简介

本指南旨在为CMS.Plugin.MyPluginName插件的部署与维护提供全面的实践指导。涵盖从代码发布、数据库迁移、编译清理到后台任务监控和故障排查的完整生命周期管理。重点介绍如何使用publish.ps1脚本进行自动化发布，利用CMSPluginRuntimeMigrator实现数据库运行时迁移，以及通过批处理脚本管理编译产物和数据库结构更新。同时提供生产环境下的性能监控、日志管理和安全更新策略。

项目结构

本插件采用模块化分层架构，遵循领域驱动设计原则，包含多个独立但相互关联的组件。主要目录结构包括：

• src/：核心源码，按功能划分为多个子项目
• test/：单元测试和集成测试
• 根目录脚本：publish.ps1（发布）、delete-bin-obj-folders.bat（清理）
• 数据库脚本：位于各数据库实现模块的Scripts/目录下

发布流程

插件发布通过PowerShell脚本publish.ps1自动化完成，支持指定输出目录或使用默认路径output/publish。脚本执行流程如下：

1. 环境准备：恢复NuGet包，指定私有源和运行时目标（win-x64）
2. 项目构建：遍历预定义项目列表（当前仅包含主插件项目）
3. 发布输出：以Release模式发布到指定目录，禁用日志输出和重复还原
4. 目录结构：每个项目输出到独立子目录，名称小写化

发布命令示例：

.\publish.ps1 "C:\Deployment\MyPluginName"

该脚本确保了发布过程的一致性和可重复性，避免手动操作带来的错误。

数据库迁移与版本升级

插件的数据库迁移通过Entity Framework Core的迁移机制实现，并在运行时自动执行。

迁移脚本管理

• UpdateMigrations.bat：创建新的迁移脚本，初始为InitialCreate，后续可通过取消注释添加版本更新
• UpdateDB.bat：将迁移应用到数据库，执行dotnet ef database update

运行时迁移

CMSPluginRuntimeMigrator类实现了IProjectRuntimeMigrator接口，在项目加载时自动触发：

编译文件清理

delete-bin-obj-folders.bat脚本用于清理项目中所有bin和obj目录，避免编译缓存导致的问题。

脚本特性：

• 递归遍历当前目录及子目录
• 自动跳过node_modules中的bin/obj目录
• 输出删除过程日志
• 执行完成后提示并等待用户按键退出

使用场景：

• 发布前清理确保干净构建
• 解决编译异常或引用冲突
• 减少项目目录占用空间

后台任务监控

插件通过MyPluginNameWorker实现周期性后台任务，继承自AsyncPeriodicBackgroundWorkerBase。

任务配置

• 执行周期：300秒（5分钟）
• 启动时立即运行：RunOnStart = true
• 依赖服务：VariableService用于变量读写

监控建议

1. 日志监控：启用ILogger<MyPluginNameWorker>的详细日志
2. 执行状态：检查DoWorkAsync是否正常完成
3. 变量读写：验证_variableService的读写操作成功率
4. 异常处理：监控CalculateOEEAsync等业务方法的异常

运行时问题排查

常见问题及解决方案

问题现象	可能原因	解决方案
插件无法加载	依赖项缺失或版本不匹配	检查publish.ps1是否完整发布所有依赖
数据库迁移失败	迁移脚本与数据库状态不一致	使用UpdateDB.bat手动执行迁移，检查错误日志
后台任务不执行	Worker未正确注册或启动	检查CMSPluginEntry.AfterReadyAsync中是否添加Worker
变量读写失败	VariableService不可用	确认_variableService已正确注入
OEE计算异常	输入变量值无效	验证Availability、Performance、Quality变量是否存在且为数值

日志分析

• 关键日志点：
  • CMSPluginRuntimeMigrator中的数据库迁移日志
  • MyPluginNameWorker的周期性执行日志
  • CMSPluginEntry的注册和配置日志
• 日志级别：建议生产环境使用Information，调试时使用Debug

生产环境部署最佳实践

性能监控

1. 后台任务性能：监控MyPluginNameWorker执行时间，避免超过周期间隔
2. 数据库性能：监控迁移和查询响应时间
3. 内存使用：定期检查插件内存占用

日志管理

• 集中式日志收集（如ELK、Splunk）
• 设置合理的日志保留策略
• 敏感信息脱敏处理

故障恢复

1. 健康检查：实现插件健康检查端点
2. 自动重启：配置进程监控工具（如Windows服务、Docker）
3. 备份策略：定期备份数据库和配置文件

安全部署

• 使用最小权限账户运行插件
• 敏感配置通过环境变量注入
• 定期更新依赖库

插件更新与回滚策略

安全更新流程

1. 备份：备份当前部署文件和数据库
2. 预发布测试：在隔离环境验证新版本
3. 逐步发布：先在非关键环境部署
4. 监控验证：确认新版本运行正常

回滚方案

1. 文件回滚：恢复备份的插件文件
2. 数据库回滚：执行反向迁移或从备份恢复
3. 配置回滚：恢复之前的appsettings.json

版本控制

• 使用EF Core迁移脚本管理数据库版本

• 插件版本号与迁移脚本关联

• 记录每次更新的变更日志

• publish.ps1

附录

脚本使用速查

脚本	用途	参数	输出
publish.ps1	发布插件	[输出目录]	output/publish/ 或指定目录
delete-bin-obj-folders.bat	清理编译文件	无	控制台日志
UpdateMigrations.bat	创建数据库迁移	无	Migrations/ 目录
UpdateDB.bat	应用数据库迁移	无	数据库结构变更

关键类依赖关系