部署与配置

本文档引用的文件

• appsettings.json
• launchSettings.json
• CMSPluginMyPluginNameOptions.cs
• CMSPluginMyPluginNameFeatures.cs
• CMSPluginEntry.cs
• CMSPluginModule.cs
• CMSPluginEntityFrameworkCoreModule.cs
• UpdateDB.bat
• UpdateMigrations.bat
• appsettings.json

目录

1. 简介
2. 核心配置文件
3. appsettings.json 配置详解
4. 功能开关（Features）配置
5. 插件选项（CMSPluginMyPluginNameOptions）
6. 开发环境配置：launchSettings.json
7. 数据库迁移脚本使用指南
8. 多数据库平台支持
9. Docker 部署建议
10. 环境变量配置
11. 健康检查与监控集成
12. 总结

简介

本指南详细说明了从开发到生产环境的全流程部署与配置管理，涵盖 appsettings.json 配置项、功能开关、插件选项、数据库迁移脚本使用、Docker 部署建议及监控集成方案，确保系统稳定运行。

核心配置文件

系统主要依赖以下配置文件进行部署与运行：

• appsettings.json：主配置文件，包含外部 API 地址、连接字符串等
• launchSettings.json：开发环境启动配置
• CMSPluginMyPluginNameFeatures.cs：功能开关定义
• CMSPluginMyPluginNameOptions.cs：插件运行时选项
• UpdateDB.bat 和 UpdateMigrations.bat：数据库 Schema 更新脚本

Section sources

• appsettings.json
• launchSettings.json
• CMSPluginMyPluginNameFeatures.cs
• CMSPluginMyPluginNameOptions.cs

appsettings.json 配置详解

主配置文件 (CMS.Plugin.MyPluginName/appsettings.json)

该文件用于配置插件级别的运行参数，建议将配置存储在宿主应用的 host/appsettings.json 或数据库中，以避免插件升级时被覆盖。

{
    "IMyPluginNameExternalApi": {
        "HttpHost": "http://127.0.0.1:18000/"
    }
}

• IMyPluginNameExternalApi.HttpHost：外部 API 对接地址，用于调用第三方服务。

Section sources

• appsettings.json

数据库连接配置 (CMS.Plugin.MyPluginName.EntityFrameworkCore/appsettings.json)

{
    "ConnectionStrings": {
        "Default": "Server=127.0.0.1;Database=CMS.Plugin.MyPluginName;User ID=root;Password=123456"
    }
}

• ConnectionStrings.Default：默认数据库连接字符串，支持 MySQL、SQL Server、PostgreSQL 等多种数据库。

Section sources

• appsettings.json

功能开关（Features）配置

功能开关通过 CMSPluginMyPluginNameFeatures 类定义，用于控制插件功能的启用与禁用。

public class CMSPluginMyPluginNameFeatures
{
    private const string Prefix = "LMES";
    public const string GroupName = Prefix + ".MyPluginName";
    public const string Enable = GroupName + ".Enable";
}

• LMES.MyPluginName.Enable：控制插件是否启用，可在运行时动态配置。

功能开关通常通过配置中心或数据库进行管理，避免硬编码。

Section sources

• CMSPluginMyPluginNameFeatures.cs

插件选项（CMSPluginMyPluginNameOptions）

CMSPluginMyPluginNameOptions 类定义了插件的运行时配置选项。

public class CMSPluginMyPluginNameOptions
{
    public List<ExtraProperty> ExtraProperties { get; set; } = new();
}

• ExtraProperties：扩展属性集合，用于存储动态配置项或元数据。

该选项通过依赖注入注入到服务中，支持运行时修改。

Section sources

• CMSPluginMyPluginNameOptions.cs

开发环境配置：launchSettings.json

launchSettings.json 定义了开发环境的启动配置。

{
  "profiles": {
    "DebugFromCMS": {
      "commandName": "Executable",
      "executablePath": "$(CMSRootPath)\\host\\CMS.Host.exe",
      "workingDirectory": "$(CMSRootPath)\\host",
      "commandLineArgs": "-d",
      "environmentVariables": {
        "DOTNET_ENVIRONMENT": "Development",
        "ASPNETCORE_URLS": "http://*:18000",
        "PluginPath": "../plugins",
        "DatabaseType": "MySQL"
      }
    }
  }
}

关键配置项：

• DOTNET_ENVIRONMENT：环境标识，决定加载哪个 appsettings.{Environment}.json
• ASPNETCORE_URLS：监听端口，当前为 18000
• PluginPath：插件目录路径
• DatabaseType：数据库类型，支持 MySQL、SqlServer、PostgreSql

Section sources

• launchSettings.json

数据库迁移脚本使用指南

系统提供批处理脚本用于数据库 Schema 的更新与维护。

UpdateMigrations.bat

用于创建新的数据库迁移。

cd ../
dotnet ef migrations add InitialCreate -c CMSPluginDbContext -o Migrations

• 功能：生成初始迁移文件
• 使用方法：
  1. 打开命令行
  2. 运行 UpdateMigrations.bat
  3. 根据需要修改迁移名称（如 Update1, Update2）

注释行用于版本迭代时添加新迁移。

UpdateDB.bat

用于将迁移应用到数据库。

cd ../
dotnet ef database update -c CMSPluginDbContext

• 功能：执行数据库更新，同步 Schema
• 使用方法：直接运行脚本，自动应用所有未执行的迁移

Section sources

• UpdateMigrations.bat
• UpdateDB.bat

多数据库平台支持

系统通过模块化设计支持多种数据库平台：

• MySQL：CMS.Plugin.MyPluginName.MySQL
• SQL Server：CMS.Plugin.MyPluginName.SqlServer
• PostgreSQL：CMS.Plugin.MyPluginName.PostgreSql

在 CMSPluginEntry.cs 中根据配置动态加载对应数据库模块：

var databaseType = configuration[SectionName.DatabaseType] ?? "mysql";
if (KnowsDbCode.IsMysql(databaseType))
{
    options.PlugInSources.Add(new TypePlugInSource(typeof(MySQL.CMSPluginMySQLModule)));
}

Section sources

• CMSPluginEntry.cs

Docker 部署建议

Dockerfile 示例

FROM mcr.microsoft.com/dotnet/aspnet:7.0 AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:7.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "CMS.Plugin.MyPluginName.dll"]

部署要点

• 使用多阶段构建优化镜像大小
• 挂载配置文件目录实现配置外部化
• 设置健康检查端点 /healthz

环境变量配置

生产环境建议通过环境变量覆盖配置：

环境变量	说明
DOTNET_ENVIRONMENT	环境类型（Production/Development）
ASPNETCORE_URLS	服务监听地址
ConnectionStrings__Default	数据库连接字符串（双下划线表示层级）
DatabaseType	数据库类型

健康检查与监控集成

健康检查端点

建议实现 /healthz 端点，返回 JSON 格式健康状态：

{
  "status": "Healthy",
  "checks": [
    {
      "name": "Database",
      "status": "Healthy"
    }
  ]
}

监控集成

• 日志：集成 Serilog 或 ELK
• 指标：暴露 Prometheus 指标端点 /metrics
• 追踪：集成 OpenTelemetry 实现分布式追踪

总结

本文档详细说明了插件的部署与配置全流程，涵盖配置管理、数据库迁移、多数据库支持、Docker 部署及监控方案。通过合理配置功能开关与环境变量，可实现灵活的生产环境部署。