CommModifyKit/docs/CommModifyKit-Distribution.md

CommModifyKit 分发与部署指南

1. 分发准备（发布者操作）

1.1 打包文件清单

CommModifyKit-Release/
├── CommModifyKit.dll           # 用户态 DLL（build\Release\Win32\）
├── CommModifyKit.sys           # 内核态驱动（build\Release\x64\）
├── CommModifyKit.inf           # 驱动安装描述（driver\）
├── install.ps1                 # 安装脚本（installer\）
├── uninstall.ps1               # 卸载脚本（installer\）
├── docs/
│   ├── CommModifyKit-Design.md     # 设计文档
│   ├── CommModifyKit-Usage.md      # 使用说明
│   └── CommModifyKit-Distribution.md  # 本文档
└── README.txt                  # 快速入门

1.2 制作发布包

# 在项目根目录执行
Compress-Archive -Path `
    "build\Release\Win32\CommModifyKit.dll", `
    "build\Release\x64\CommModifyKit.sys", `
    "driver\CommModifyKit.inf", `
    "installer\install.ps1", `
    "installer\uninstall.ps1", `
    "docs\CommModifyKit-Design.md", `
    "docs\CommModifyKit-Usage.md", `
    "docs\CommModifyKit-Distribution.md" `
    -DestinationPath CommModifyKit-Release.zip

1.3 README.txt 内容

CommModifyKit 串口监控套件
=========================

包含文件：
  CommModifyKit.dll  - 用户态 DLL，供 CommModifyService 加载
  CommModifyKit.sys  - 内核态过滤驱动
  CommModifyKit.inf  - 驱动安装描述文件
  install.ps1        - 自动安装脚本（需管理员权限）
  uninstall.ps1      - 自动卸载脚本（需管理员权限）

快速开始：
  1. 解压到任意目录
  2. 右键 PowerShell → 以管理员身份运行
  3. cd 到解压目录
  4. 执行 .\install.ps1
  5. 重启计算机（首次启用测试签名需要）
  6. 将 CommModifyKit.dll 拷贝到 CommModifyService.exe 所在目录

详细文档见 docs\ 目录

---

2. 驱动签名（必须）

内核驱动无签名则无法加载，没有例外。根据分发场景选择签名方案：

方案	成本	接收方操作	适用场景
测试签名	免费	启用 testsigning + 重启	内部开发/测试
EV 代码签名	~$300-500/年	无需额外操作	正式交付客户
WHQL 签名	~$250/年 + 认证	无需额外操作	大规模公开分发

2.1 测试签名（免费，推荐内部分发）

发布者：创建测试签名并签名

# 1. 创建测试签名证书（一次性）
makecert -r -pe -ss PrivateCertStore -n "CN=CommModifyKitTestCert" CommModifyKitTest.cer

# 2. 对驱动签名
signtool sign /fd SHA256 /s PrivateCertStore /n CommModifyKitTestCert CommModifyKit.sys

# 3. 对 DLL 签名（可选但推荐）
signtool sign /fd SHA256 /s PrivateCertStore /n CommModifyKitTestCert CommModifyKit.dll

接收方：启用测试签名

# 以管理员身份执行（一次性，重启后永久生效）
bcdedit /set testsigning on
Restart-Computer

重启后桌面右下角会出现"测试模式"水印，这是唯一可见的副作用。

2.2 EV 代码签名（正式分发）

1. 从 DigiCert / GlobalSign 等购买 EV 代码签名证书

2. 用 signtool 签名：

   # EV 签名（需要硬件令牌）
   signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a CommModifyKit.sys
   signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a CommModifyKit.dll
   

3. Windows 10 1607+ 可直接加载 EV 签名的内核驱动，接收方无需任何额外操作

2.3 WHQL 签名（最正规）

1. 注册 Windows Hardware Developer Center（$250/年）
2. 创建硬件提交，上传驱动包（.cab 格式）
3. 通过微软 WHQL 测试认证
4. 下载签名后的驱动分发

WHQL 签名后接收方零配置，驱动可直接加载，无水印。

---

3. 接收方安装流程（详细步骤）

步骤 1：解压文件

将 CommModifyKit-Release.zip 解压到任意目录，例如 C:\CommModifyKit\。

确认目录结构完整：

C:\CommModifyKit\
├── CommModifyKit.dll
├── CommModifyKit.sys
├── CommModifyKit.inf
├── install.ps1
├── uninstall.ps1
└── docs\

步骤 2：以管理员身份打开 PowerShell

1. 开始菜单搜索 PowerShell
2. 右键 → 以管理员身份运行

3. 导航到解压目录：

   cd C:\CommModifyKit
   

步骤 3：运行安装脚本

.\install.ps1

预期输出：

=== CommModifyKit 安装脚本 ===
驱动 .sys: C:\CommModifyKit\CommModifyKit.sys
驱动 .inf: C:\CommModifyKit\CommModifyKit.inf
用户态 DLL: C:\CommModifyKit\CommModifyKit.dll

添加驱动包...
  完成
测试签名已启用，需要重启计算机才能生效

=== 安装完成 ===

说明：驱动使用 PnP 方式安装（pnputil /add-driver），自动注册为 Ports 类的 UpperFilters。

步骤 4：重启计算机

首次安装必须重启（启用测试签名后生效）。

Restart-Computer

步骤 5：重启后验证驱动

# 检查驱动是否在驱动库中
pnputil /enum-drivers | Select-String "CommModifyKit"

# 检查测试签名
bcdedit /enum | Select-String "testsigning"
# 期望：testsigning Yes

# 检查驱动文件
Test-Path "$env:windir\System32\drivers\CommModifyKit.sys"
# 期望：True

# 在设备管理器中确认串口设备有 CommModifyKit 驱动
# 设备管理器 → 端口 (COM 和 LPT) → 右键串口 → 属性 → 驱动程序
# 应显示 CommModifyKit 作为过滤驱动

步骤 6：拷贝 DLL 到 CommModifyService 目录

# 根据实际部署位置调整
$ServiceDir = "C:\Program Files\CommModifyService"
Copy-Item C:\CommModifyKit\CommModifyKit.dll $ServiceDir\

# 验证
Test-Path "$ServiceDir\CommModifyKit.dll"

步骤 7：配置 CommModifyService

确保 config.json 中启用 DLL 模式：

{
  "comm": {
    "use_dll": true
  }
}

步骤 8：启动并验证

# 启动服务
Start-Service CommModifyService

# 或直接运行 exe（调试用）
& "$ServiceDir\CommModifyService.exe"

验证串口监控生效：

1. 用 DebugView 查看 CommModifyKit 日志
2. 确认看到 DriverClient opened \\.\CommModifyKit 和 EventLoop started
3. 对串口执行读写，确认回调触发

---

4. 手动安装（脚本失败时备用）

# 1. 启用测试签名
bcdedit /set testsigning on

# 2. 使用 pnputil 安装驱动（PnP 方式）
cd C:\CommModifyKit
pnputil /add-driver CommModifyKit.inf /install

# 3. 扫描硬件改动（触发 PnP 重新加载过滤驱动）
# 设备管理器 → 操作 → 扫描硬件改动

# 4. 验证安装
pnputil /enum-drivers | Select-String "CommModifyKit"

# 5. 拷贝 DLL
Copy-Item C:\CommModifyKit\CommModifyKit.dll "C:\Program Files\CommModifyService\"

---

5. 卸载

自动卸载

cd C:\CommModifyKit
.\uninstall.ps1

手动卸载

# 1. 找到并删除驱动包
pnputil /enum-drivers | Select-String "CommModifyKit"
# 假设显示 oem12.inf

pnputil /delete-driver oem12.inf /uninstall /force

# 2. 删除驱动文件
Remove-Item "$env:windir\System32\drivers\CommModifyKit.sys" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:windir\System32\drivers\CommModifyKit.inf" -Force -ErrorAction SilentlyContinue

# 3. 删除 DLL
Remove-Item "C:\Program Files\CommModifyService\CommModifyKit.dll" -Force

# 4. 可选：关闭测试签名
bcdedit /set testsigning off
Restart-Computer

---

6. 分发注意事项

事项	说明
操作系统	仅 Windows 10/11 x64
管理员权限	安装驱动必须，无法绕过
测试签名水印	启用后桌面右下角显示"测试模式"水印，仅影响视觉
杀毒软件	可能拦截内核驱动安装，需提前加白名单
DLL 位数	CommModifyKit.dll 为 Win32(x86)，CommModifyService 必须是 32 位进程
驱动位数	CommModifyKit.sys 为 x64，仅支持 64 位 Windows
测试签名安全性	启用后任何测试签名驱动都可加载，降低系统安全性
Windows 更新	大版本更新可能重置 testsigning 设置，需重新启用

---

7. 常见问题

Q: 不获取 WHQL 签名可以吗？

可以。选择测试签名（免费）或 EV 代码签名（付费但无需接收方操作）即可。

Q: 测试签名的水印能去掉吗？

只有两种方式：购买 EV 证书签名，或获取 WHQL 签名。测试签名的水印无法单独关闭。

Q: 接收方不想重启怎么办？

首次启用 testsigning 必须重启，之后安装更新版本无需重启。如果使用 EV 或 WHQL 签名，则完全不需要重启（首次安装驱动除外）。

Q: 多台机器批量部署怎么做？

1. 在一台机器上完成安装和验证
2. 用 sysprep 封装系统镜像（含 testsigning 和驱动服务）
3. 将镜像部署到其他机器
4. 每台机器上拷贝 DLL 到 CommModifyService 目录即可