# 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 制作发布包

```powershell
# 在项目根目录执行
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 测试签名（免费，推荐内部分发）

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

```powershell
# 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
```

#### 接收方：启用测试签名

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

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

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

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

```powershell
# 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](https://partner.microsoft.com/dashboard/hardware)（$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. 导航到解压目录：

```powershell
cd C:\CommModifyKit
```

### 步骤 3：运行安装脚本

```powershell
.\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：重启计算机

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

```powershell
Restart-Computer
```

### 步骤 5：重启后验证驱动

```powershell
# 检查驱动是否在驱动库中
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 目录

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

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

### 步骤 7：配置 CommModifyService

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

```json
{
  "comm": {
    "use_dll": true
  }
}
```

### 步骤 8：启动并验证

```powershell
# 启动服务
Start-Service CommModifyService

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

**验证串口监控生效**：
1. 用 DebugView 查看 CommModifyKit 日志
2. 确认看到 `DriverClient opened \\.\CommModifyKit` 和 `EventLoop started`
3. 对串口执行读写，确认回调触发

---

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

```powershell
# 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. 卸载

### 自动卸载

```powershell
cd C:\CommModifyKit
.\uninstall.ps1
```

### 手动卸载

```powershell
# 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 目录即可