.NET 开发框架与生态（AI 应用方向）¶

用途：本分册是 AppDocs 库中 ".NET 开发框架与生态" 技术维度的速查文档，供 AI 助手在 Windows Server 宿主机上指导 .NET 侧的开发、部署与 AI 能力集成（TTS/ASR/OCR/NLP 的 .NET 集成 + 应用框架）操作。

环境说明：宿主机为 Windows Server 2022 Datacenter（2×Xeon Gold 6138、256GB 内存、无 GPU）。.NET 项目可原生跑在 Windows 或 Ubuntu 22.04 VM（Hyper-V）中，容器化方案优先（Docker）。落盘约束：所有产物只存 F:\EricLiu\ 下。

版本基线（核对日期 2026-11-11，来源：官网/GitHub/NuGet）： - .NET 运行时/SDK：.NET 10 = 当前 LTS（SDK 10.0.403，支持至 2028-11-14）；.NET 11 于 2026-11-10 GA（STS）；.NET 8/9 支持于 2026-11-10 到期（⚠️ 已/即将 EOL，存量 .NET 8 项目应规划迁移到 .NET 10） - ABP Framework 10.6.2（LGPL-3.0）｜nopCommerce 4.90.8 稳定 / 5.00 beta（NPL 4.0，AGPL-3.0 系）｜Orchard Core 3.0.1（BSD-3-Clause，要求 .NET 10） - Semantic Kernel 1.81.0（MIT，维护模式，继任者 Microsoft Agent Framework 1.x）｜Microsoft.Extensions.AI 10.11.0（MIT）｜ML.NET 5.0.0（MIT） - ONNX Runtime（C#）1.31.1（MIT）｜Sdcb.PaddleOCR 3.3.1（Apache-2.0）｜Sdcb.OpenVINO 0.8.1（Apache-2.0）｜Sdcb.SimdPaddleOCR 1.4.2（Apache-2.0） - 注：用户此前提到的 "simdcodes/simdPaddleOCR" 应指 GitHub 用户 sdcb 的 SimdPaddleOCR 项目（NuGet: Sdcb.SimdPaddleOCR）；Sdcb.Whisper 不存在，.NET 侧 Whisper 绑定是 sandrohanea 的 Whisper.net 1.9.1（MIT），详见第一节。

1. 选型对比表¶

1.1 应用框架（ABP vs nopCommerce vs Orchard Core）¶

维度	ABP Framework	nopCommerce	Orchard Core
定位	企业级 DDD 模块化应用框架（脚手架+模块生态）	开箱即用的电商平台（B2C/B2B，多店铺/多商户）	CMS + 模块化多租户应用框架
当前版本	10.6.2（10.7.0-rc.3）	4.90.8 稳定；5.00 beta（2026-09）	3.0.1（2026-07）
.NET 要求	ASP.NET Core（随新版跟进）	.NET 9（4.80 起迁移）	.NET 10（3.0 起硬性要求）
许可证	LGPL-3.0（开源框架）；商业模块/工具另购（ABP Commercial/ABP Studio 高级功能）	nopCommerce Public License 4.0（基于 AGPL-3.0 + 每页须保留 "powered by nopCommerce" 链接，去除需购买版权移除密钥）	BSD-3-Clause（最宽松，.NET Foundation 背书）
数据库	EF Core：SQL Server / MySQL / PostgreSQL / SQLite 等	SQL Server / MySQL / PostgreSQL	SQL Server / SQLite / MySQL / PostgreSQL（YesSql）
CPU 资源	中等偏重（模块多、启动依赖多），256GB 内存下无压力	中等（生产建议 SQL Server + 4C8G 级别起步）	轻量，"fast by default"，无需额外缓存模块
推荐场景	自研企业业务系统/多租户 SaaS，需要权限、审计、租户等全套基础设施	需要成品电商（含 4.90 新增 B2B 模块、AI 内容生成/SEO 工具）	内容型网站、多租户门户、headless CMS
与 AI 应用结合方式	业务系统底座，AI 服务以插件/应用服务形式接入	平台自带 AI 工具 + 外挂 AI 服务（见第 4 节）	Workflow 模块可编排 AI 调用，GraphQL API 做内容分发

1.2 .NET AI 栈（Semantic Kernel vs Microsoft.Extensions.AI vs ML.NET）¶

维度	Semantic Kernel	Microsoft.Extensions.AI	ML.NET
定位	LLM 编排 SDK（插件/Agent/记忆/过滤器）	底层抽象层：`IChatClient` / `IEmbeddingGenerator` 统一接口 + 中间件	传统机器学习 + Tokenizer/GenAI 管线
当前版本	1.81.0（维护模式：继任者 Microsoft Agent Framework 1.x 于 2026-04 GA，MIT）	10.11.0	5.0.0
许可证	MIT	MIT	MIT
关系	基于 M.E.AI 类型体系构建（Agent Framework 直接跑在 `IChatClient` 上）	全栈地基：SK / Agent Framework / Whisper.net(1.9+) 都实现它的接口	Tokenizers、CausalLMPipeline 可作为 M.E.AI.IChatClient 接入
适用判断	存量 SK 项目继续维护即可；新项目优先 Microsoft Agent Framework 或裸用 M.E.AI	只需"调 LLM/Embedding + 工具调用 + 中间件"时最轻量	表格分类/异常检测/自定义 tokenizer 场景；无 GPU 约束下 CPU 推理可用
本环境建议	TTS/ASR/OCR 不经 SK；NLP 编排见第 4 节（对接 Ollama）	推荐：所有 LLM 调用统一走 `IChatClient`，本地 Ollama 用 OllamaSharp（官方 Microsoft.Extensions.AI.Ollama 已弃用）	仅在需要传统 ML 时引入

1.3 本地 AI 推理 .NET 绑定（ONNX Runtime vs Sdcb.PaddleOCR vs Sdcb.OpenVINO vs Sdcb.SimdPaddleOCR）¶

背景：Python 原生方案（PaddleOCR/Whisper/Transformers）成熟但部署链复杂（Python 环境、原生库、进程隔离）。.NET 绑定方案可进程内运行、随应用分发。

维度	ONNX Runtime (Microsoft.ML.OnnxRuntime)	Sdcb.PaddleOCR (PaddleSharp)	Sdcb.OpenVINO (+ .PaddleOCR)	Sdcb.SimdPaddleOCR
版本 / 许可证	1.31.1 / MIT	3.3.1 / Apache-2.0	0.8.1（OpenVINO 2026.2.0）/ Apache-2.0	1.4.2 / Apache-2.0（2026-09 首发，新项目）
原理	通用 ONNX 推理引擎（C# 托管绑定 + 各平台原生 so/dll NuGet 包）	绑定百度 Paddle Inference 原生库跑 PP-OCR 模型	绑定 Intel OpenVINO 原生库，跑 PP-OCR（v4/v5/v6 ONNX）模型	纯 C# 自带托管 ONNX 解释器，手写 SIMD Kernel，PP-OCRv6 DET+CLS+REC
原生依赖	原生 dll/so 随 NuGet runtime 包分发（跨平台矩阵齐全）	需 `Sdcb.PaddleInference.runtime.win64.mkl` / Linux 对应包 + OpenCvSharp runtime	需 `Sdcb.OpenVINO.runtime.*` 平台包 + OpenCvSharp4	零原生依赖（net10.0 / netstandard2.0，支持 NativeAOT），模型嵌在程序集资源
与 Python 原生跑的优劣	✅ 单一运行时跑任意 ONNX 模型，免 Python 进程；❌ 预处理/后处理要自己写	✅ 官方 Paddle 精度/算子兼容最好；❌ 部署痛点：mkl dll/so、VC++ 运行库、CPU 指令集匹配，跨平台矩阵难维护	✅ OpenVINO 对 Intel CPU（Xeon）优化好、模型格式统一 ONNX、支持 PP-OCRv6；❌ 仍需原生库 + OpenCvSharp	✅ 部署最简（xcopy 即用）、比纯 C 版更快、内存低、准确率高（1.4.x CLS 评测 100%）；❌ 仅 CPU、仅 PP-OCRv6 场景 OCR（作者明确暂无 GPU 计划）
本机（无 GPU、Xeon Gold）建议	通用兜底；跑自定义 ONNX 模型	存量项目可继续用	Xeon 上可优先试用（iGPU/CPU 加速）	OCR 新项目首选（本机纯 CPU 场景与其定位完全吻合）

其他 .NET 本地推理补充： - Whisper.net 1.9.1（MIT）：whisper.cpp 的 .NET 绑定（注意：不是 sdcb 的项目），CPU 运行时要求 AVX/AVX2/FMA/F16C（Xeon Gold 6138 满足）；1.9 起提供 ISpeechToTextClient（Microsoft.Extensions.AI）实现，可直接接入 M.E.AI 管线。 - TTS：.NET 侧无强势统一绑定，建议走 HTTP 服务化（对接本库 TTS 分册）或 ONNX 模型 + ONNX Runtime。

1.4 推荐结论（按场景）¶

首选 = .NET 10 LTS（SDK 10.0.403，支持至 2028-11-14）：.NET 8/9 已于 2026-11-10 EOL，新项目/新镜像一律禁止 8/9；.NET 11 是 STS，不适合做长期基线。
应用框架首选 = Orchard Core 3.0.1（BSD-3，最宽松）；企业业务系统/多租户 SaaS 用 ABP 10.6.2（LGPL-3.0，NuGet 动态链接合规，勿改框架源码闭源内嵌）；nopCommerce 4.90.8 只在"要成品电商"时选——NPL 4.0 属 AGPL 系，改核心有开源传导义务、页面须留 powered-by 链接。
AI 栈首选 = Microsoft.Extensions.AI 10.11 + OllamaSharp（业务只依赖 IChatClient）；Semantic Kernel 已进维护模式，新项目写 Microsoft Agent Framework 或裸用 M.E.AI。
OCR 进程内首选 = Sdcb.SimdPaddleOCR 1.4.2（纯 C#、零原生依赖、支持 NativeAOT，CPU 场景定位完全吻合）；需要 PP-Structure 版面/表格才退回 Python HTTP 服务。Whisper 绑定 = Whisper.net 1.9.1（Sdcb.Whisper 不存在，勿按错误包名搜索）。
选配 = nopCommerce 4.90.8（只要成品电商，须按 AGPL 系合规使用）/ Sdcb.PaddleOCR 3.3.1（存量项目、需官方 Paddle 算子兼容）/ Sdcb.OpenVINO 0.8.1（Xeon 上可先做性能验证）/ Semantic Kernel 1.81（仅维护存量代码）。
回避 = .NET 8/9 新部署（EOL 无补丁）、在开源 ABP 项目里引商业包（Volo.Abp.Commercial.*/LeptonX 商业主题）、直接改 nopCommerce 核心源码（AGPL 合规与升级双输）。

2. 安装部署¶

2.1 dotnet SDK 安装（Windows Server）¶

# winget 方式（推荐）
winget install Microsoft.DotNet.SDK.10
# 或官网下载 exe 安装：https://dotnet.microsoft.com/download/dotnet/10.0

# 验证
dotnet --list-sdks    # 期望 10.0.4xx
dotnet --list-runtimes

Ubuntu 22.04 VM 内（canonical feed）：

sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0 aspnetcore-runtime-10.0

⚠️ .NET 8/9 支持已于 2026-11-10 结束，新装一律 .NET 10；Docker 基础镜像用 mcr.microsoft.com/dotnet/aspnet:10.0 / sdk:10.0。

2.2 ABP CLI（abp new）¶

dotnet tool install -g Volo.Abp.Cli          # 安装
abp new MyCompany.MyProject -u blazor.server -cs --database-provider ef   # 生成解决方案
abp cli 常用: abp login / abp install-module / abp update / abp add-module <Module>

要点： - ABP CLI abp new 生成的是完整可拥有源码的解决方案（LGPL-3.0 框架 NuGet 包 + 业务代码归你）；商业模块（LeptonX Theme 的高级版、部分 SaaS 模块）需 ABP Commercial 许可证，AI 助手不要擅自往开源项目里加商业模块。 - 数据库连接串在 appsettings.json；首次运行 dotnet ef database update 或让 DbMigrator 项目跑迁移种子。

2.3 nopCommerce Docker 部署（compose 模板）¶

# F:\EricLiu\stacks\nopcommerce\docker-compose.yml
services:
  nop-web:
    image: nopcommerce/nopcommerce:latest   # 官方镜像；生产建议固定 tag 如 4.90
    container_name: nop-web
    ports:
      - "8080:8080"
    environment:
      # 生产建议先配好数据库再进安装向导
      - ASPNETCORE_URLS=http://+:8080
    volumes:
      - nop_appdata:/app/App_Data             # 插件、上传文件、installed 标记
    depends_on:
      - nop-db
    restart: unless-stopped

  nop-db:
    image: postgres:16
    container_name: nop-db
    environment:
      - POSTGRES_DB=nopcommerce
      - POSTGRES_USER=nop
      - POSTGRES_PASSWORD=ChangeMe_StrongPwd
    volumes:
      - nop_pgdata:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  nop_appdata:
  nop_pgdata:

要点： - 首次访问 http://<host>:8080 进安装向导，填上面的 PostgreSQL 连接信息；安装完成后 App_Data/appsettings.json 里落定连接串。 - 升级策略见第 6 节：跨大版本（4.90→5.00）必须走官方升级文档 + 数据库备份。 - SQL Server 更省心（官方第一支持），PostgreSQL 官方支持存在但踩坑概率略高。

2.4 Sdcb.PaddleOCR / Sdcb.SimdPaddleOCR（OCR 集成要点）¶

路线 A：SimdPaddleOCR（新项目首选，零原生依赖）

dotnet add package Sdcb.SimdPaddleOCR
dotnet add package Sdcb.SimdPaddleOCR.Models.ChineseV6Tiny   # tiny/small/medium 三档，tiny 会传递引用 CLS 方向分类
dotnet add package SixLabors.ImageSharp                      # 任选解码库：ImageSharp/SkiaSharp/OpenCvSharp/System.Drawing

using Sdcb.SimdPaddleOCR;
using Sdcb.SimdPaddleOCR.Models.ChineseV6Tiny;
using SixLabors.ImageSharp;

using PaddleOcrAll ocr = await PaddleOcrAll.LoadAsync(ChineseV6TinyModels.Default); // 模型嵌在程序集资源
using Image image = await Image.LoadAsync("sample.jpg");
byte[] bgr = new byte[image.Width * image.Height * 3];
image.CopyPixelDataTo(bgr);
PaddleOcrResult result = ocr.Run(bgr, image.Width, image.Height);  // 核心 API 只吃 8bit BGR 内存
Console.WriteLine(result.Text);

路线 B：Sdcb.PaddleOCR（PaddleSharp，需原生依赖）

dotnet add package Sdcb.PaddleOCR
dotnet add package Sdcb.PaddleOCR.Models.Local          # 本地 V5 模型包
dotnet add package Sdcb.PaddleInference                 # Paddle Inference 托管绑定
dotnet add package Sdcb.PaddleInference.runtime.win64.mkl   # Windows x64 原生库（Linux 用对应 runtime 包）
dotnet add package OpenCvSharp4.runtime.win             # OpenCV 原生 runtime（仅解码用）

原生依赖路径要点： - Windows：Sdcb.PaddleInference.runtime.win64.mkl 包内含 paddle_inference.dll（及其 mkl/openvino 依赖 dll），还原后位于 ~\.nuget\packages\sdcb.paddleinference.runtime.win64.mkl\<ver>\runtimes\win-x64\native\；发布时确保输出目录包含这些 dll（dotnet publish 的 NuGet runtimes 布局会自动带上）。 - Linux（Ubuntu 22.04 VM/容器）：使用 Sdcb.PaddleInference.runtime.linux-x64 系包，.so 位于对应 runtimes/linux-x64/native/；容器内需 glibc 兼容（Ubuntu 22.04 OK）。 - 若报 DllNotFoundException: paddle_inference / mkldnn：先查输出目录是否带齐原生 dll/so，再查 CPU 是否缺指令集（mkl 版对 AVX2 有要求，Xeon Gold 6138 支持 AVX-512，满足）。 - 模型选择：LocalFullModels.ChineseV5（本地包，离线可用）或 OnlineFullModels.*（首次用时联网下载，缓存到本地目录）。

3. 高频命令¶

3.1 dotnet CLI¶

dotnet new webapi -n MyApi            # 新建项目（模板：console/webapi/webapp/mstest/xunit...）
dotnet new sln -n MySolution && dotnet sln add .\MyApi\MyApi.csproj
dotnet build -c Release               # 构建
dotnet run --project .\MyApi          # 运行
dotnet test                           # 跑测试
dotnet publish -c Release -r win-x64 --self-contained false -o .\publish   # 发布
dotnet publish -c Release -r linux-x64 --self-contained -p:PublishAot=true # Linux 自包含/AOT（SimdPaddleOCR 支持 AOT）
dotnet add package <Package>          # 加包（如 dotnet add package Microsoft.Extensions.AI）
dotnet tool install -g <Tool>         # 全局工具（abp cli 即此方式）
dotnet list package --include-transitive   # 排查传递依赖版本

3.2 abp CLI¶

abp new Acme.BookStore -u none --database-provider ef -cs   # 生成项目（-u blazor.server|blazor.webapp|mvc|angular|none）
abp install-module Acme.Payment.Module                       # 安装开源模块
abp update                                                   # 升级到最新 ABP
abp add-module Volo.Blogging --solution-path .\Acme.BookStore
abp cli --version                                            # 查看 CLI 版本

3.3 EF Core 迁移¶

dotnet ef migrations add InitSchema           # 生成迁移（需 dotnet-ef 工具：dotnet tool install -g dotnet-ef）
dotnet ef database update                     # 应用迁移
dotnet ef migrations list                     # 列出迁移
dotnet ef migrations remove                   # 撤销最近一次未应用的迁移
dotnet ef migrations script 0 InitSchema -o mig.sql   # 导出 SQL（生产变更走 DBA 流程时用）
dotnet ef database drop                       # ⚠️ 危险：删库，仅开发环境

nopCommerce 场景注意：nop 的数据层自带 Upgrade 服务，跨版本升级不要用裸 EF 迁移命令，走官方升级程序（见第 6 节）。

4. 与本库其他维度集成¶

4.1 Sdcb.PaddleOCR 替代 Python OCR 服务（进程内 vs HTTP 服务取舍）¶

本库 OCR/文档识别分册原有 Python（PaddleOCR）方案。.NET 化后有两条路径：

取舍	进程内（Sdcb.SimdPaddleOCR / Sdcb.PaddleOCR NuGet 直接引用）	HTTP 服务（Python PaddleOCR 或 .NET WebAPI 包装 OCR）
延迟	最低（无 IPC），tiny 模型单图 ~300ms 级	多一跳网络 + 序列化
部署	随应用分发，SimdPaddleOCR 零原生依赖，Docker 镜像无需装 Python	需独立服务与生命周期管理
资源隔离	与主应用同进程，CPU 密集可能拖垮 Web 请求（可用 `Task.Run` + 限并发，或专用 Worker 进程）	隔离好，可独立扩缩容（本机 CPU 48 逻辑核足够）
语言/生态	纯 .NET 团队首选	需要用到 Python 独有模型（如版面分析 PP-StructureV3）时保留
建议	默认进程内 + Sdcb.SimdPaddleOCR；高并发或需 PP-Structure 再拆 HTTP 服务	兜底

4.2 Semantic Kernel / Microsoft.Extensions.AI 调 Ollama（对接 NLP 分册）¶

本机 NLP 分册用 Ollama 跑本地模型，其 OpenAI 兼容端点（默认 http://localhost:11434/v1）可直接被 .NET 调用：

// 方案 1：Microsoft.Extensions.AI + OllamaSharp（官方 M.E.AI.Ollama 已弃用）
using OllamaSharp;
using Microsoft.Extensions.AI;

IChatClient client = new OllamaApiClient("http://localhost:11434", "qwen3:8b");
var reply = await client.GetResponseAsync("用一句话总结这段文本：" + text);

// 方案 2：M.E.AI.OpenAI 指向 Ollama 的 OpenAI 兼容端点
using Microsoft.Extensions.AI;
using OpenAI;

IChatClient client = new OpenAIClient(new Uri("http://localhost:11434/v1"), "ollama")
    .AsChatClient("qwen3:8b");

统一原则：业务代码只依赖 IChatClient/IEmbeddingGenerator，本地 Ollama 与远端 API 用 DI 注册切换（AddChatClient 管道：OpenTelemetry、缓存、函数调用中间件可叠加）。
新建 Agent 类项目：用 Microsoft Agent Framework（Microsoft.Agents.AI），它直接消费 IChatClient，与上面写法同源。
与 NLP 分册对接约定：模型名、端点以 NLP 分册的 Ollama 部署记录为准，不要在本分册硬编码另一套。

4.3 nopCommerce 外挂 AI 服务（商品描述/评论分析示意）¶

nopCommerce 4.90 自带部分 AI 内容工具（文案生成、SEO），更深的定制走插件机制：

插件骨架：用官方插件模板建 Nop.Plugin.Misc.AiAssistant（实现 BasePlugin + IAdminMenuPlugin）。
商品描述生成：挂 ProductService 事件或后台 Action → 组装商品属性/类目上下文 → 经 IChatClient（本地 Ollama）生成多语言描述 → 写回 Product.FullDescription（保存前留人工确认入口，AI 产物先落草稿表）。
评论分析：订阅 ProductReviewApprovedEvent/插入事件 → 异步 Worker 批量调 LLM 打情感标签 + 提炼关键词 → 存自建表（_ai_review_analysis），后台报表展示；避免在事件处理器里同步阻塞调 LLM。
部署注意：AI 调用集中在插件内用 HttpClient 打本地推理服务或进程内 IChatClient；不要改 nop 核心源码（否则 AGPL 合规与升级都会变复杂，见第 6 节）。

5. 排障速查¶

症状	排查方向
`dotnet run` 报 "framework not found"	`dotnet --list-runtimes`；项目 `TargetFramework` 与已装运行时不匹配；装对应 ASP.NET Core Runtime
NuGet 还原慢/失败	配内网镜像源（`nuget.config`）；公司代理 HTTPS 证书问题
`DllNotFoundException: paddle_inference / openvino / onnxruntime`	① 输出目录是否含原生 dll/so（NuGet runtimes 布局）② RID 是否匹配（win-x64 vs linux-x64）③ VC++ 运行库（Windows）④ 换 `win-mt-x64` 变体（Sdcb.OpenVINO 静态 CRT 版）
SimdPaddleOCR 在 .NET Framework 4.8 跑不起来	它支持 netstandard2.0，但 SIMD 加速需 .NET 10；旧框架跑的是降级路径，性能差属正常
ONNX 模型加载失败 "invalid proto"	模型文件损坏/版本过新；`onnxruntime` C# 包与生成该模型的 opset 兼容性；换 1.31.x 最新包
Whisper.net 报 AVX 相关崩溃	CPU 缺 AVX2/FMA → 换 `Whisper.net.Runtime.NoAvx` 包（本机 Xeon Gold 6138 不会遇到）
Ollama 连接拒绝	Ollama 服务未起/端口非 11434；容器内访问宿主 Ollama 用 `host.docker.internal`
M.E.AI 运行时 `TypeLoadException: ChatCompletion`	旧代码编译产物 + 新 Abstractions 混用：`dotnet clean` 后全量重建；`dotnet list package --include-transitive` 查版本
nopCommerce 安装向导卡住	检查 `App_Data` 卷可写；数据库账号权限；`installed` 标记文件已存在时向导不再出现
ABP 项目启动报模块缺失	`abp update` 后未同步 NuGet 包；ABP 版本与模块版本不齐（全部对齐到同一个小版本线）
Docker 内 .NET 时区/编码乱	`TZ=Asia/Shanghai` 环境变量；Linux 容器装 tzdata；`DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false`

6. AI 操作守则¶

ABP 开源版 vs 商业版边界：开源 = abpframework/abp（LGPL-3.0）+ NuGet Volo.Abp.* 开源模块 + ABP CLI 基础功能；商业 = ABP Studio 完整功能、LeptonX 商业主题、部分 SaaS/付费模块、官方支持。AI 助手不得在开源项目中引用商业包名（如 Volo.Abp.Commercial.*、商业主题）或建议下载商业试用绕过许可；商业能力一律先提示用户确认购买。LGPL 下动态链接（NuGet 引用）合规，不要把 ABP 框架源码改后闭源内嵌。
nopCommerce 许可证与升级策略：
NPL 4.0 = AGPL-3.0 系 + 页面 "powered by nopCommerce" 链接要求。对公网店铺，修改核心源码有开源传导义务；定制一律走插件/主题机制，并保留署名链接（去除需购版权移除密钥）。内部专用（不对公网提供服务）场景 AGPL 触发面较窄，但拿不准时按"必须合规"处理并提示用户。
升级：小版本（4.90.x→4.90.y）直接换镜像 + 备份；跨大版本（4.90→5.00，5.00 目前 beta）必须：全量备份数据库与 App_Data → 读官方 upgrade guide → 测试环境演练 → 生产执行，不要用 dotnet ef database update 硬套。
许可证注意（本分册涉及）：ABP LGPL-3.0、Orchard Core/微软 AI 栈/ONNX Runtime MIT、Sdcb 系 Apache-2.0、Whisper.net MIT——集成均安全；唯一"重"许可是 nopCommerce（AGPL 系）。注意传递依赖：OpenCvSharp（Apache-2.0）、ImageSharp（Six Labors Split License：多数场景免费，商用分发需自查）。
版本纪律：.NET 8/9 已于 2026-11-10 EOL——任何新项目/新镜像禁止 .NET 8/9，存量项目排迁移计划（目标 .NET 10 LTS，支持至 2028-11）。Semantic Kernel 新功能冻结：引用 SK 的存量代码可留，新代码写 Microsoft Agent Framework 或裸 M.E.AI，并在注释里标注理由。
AI 助手操作红线：不未经确认执行 dotnet ef database drop、删除迁移文件、覆盖 App_Data；不在文档/代码里硬编码密码；OCR 模型包（Sdcb..Models.）首次下载需联网，离线环境必须提前准备 Local 模型包；对外发布 .NET 应用镜像前检查许可证文件（NOTICES）是否随包带上。