# Windows 代码签名配置指南

> 本文档说明美家卡智影 Windows 版本的签名机制与配置方法。

---

## 一、当前状态

| 签名类型 | 状态 | 说明 |
|----------|------|------|
| Tauri Updater 自签名 | ✅ 已启用 | 使用 minisign 免费签名，确保自动更新包的完整性 |
| Windows 安装包签名 (NSIS/MSI) | ⏳ 待配置 | 暂未购买商业代码签名证书，安装包运行时可能触发 SmartScreen |

---

## 二、Tauri Updater 自签名（已启用）

### 2.1 作用
- 对自动更新包（`.nsis.zip` / `.msi.zip`）进行数字签名
- 客户端下载更新后，通过 `tauri.conf.json` 中的公钥验证更新包未被篡改
- **这是免费的，且与 Windows 操作系统信任无关**

### 2.2 密钥管理

**公钥**
- 文件: `src-tauri/.tauri-signing-key.pub`
- 已嵌入 `tauri.conf.json` → `plugins.updater.pubkey`
- **已提交到 Git 仓库**（公钥可以公开）

**私钥**
- 文件: `.tauri-signing-key`（**已加入 .gitignore，未提交到 Git**）
- 必须保存在安全位置（如 GitLab CI/CD Variables、1Password、公司密码管理器）
- **切勿泄露或提交到仓库**

### 2.3 GitLab CI 配置

在 GitLab 项目设置 → **CI/CD → Variables** 中添加：

| 变量名 | 类型 | 值 | 保护级别 |
|--------|------|-----|----------|
| `TAURI_SIGNING_PRIVATE_KEY` | Variable | `dW50cnVzdGVk...`（私钥 base64 字符串）| Masked + Protected |

> CI 构建时会自动读取该变量，对更新包进行签名。

### 2.4 私钥丢失后的恢复

若私钥丢失，必须重新生成密钥对：

```bash
cd tauri-app
npm run tauri signer generate -- --write-keys src-tauri/.tauri-signing-key
```

然后：
1. 将新生成的公钥（`.tauri-signing-key.pub` 内容）更新到 `tauri.conf.json`
2. 将新生成的私钥保存到 GitLab CI/CD Variables
3. **旧版本客户端将无法通过自动更新升级**（公钥不匹配），必须重新下载安装包

---

## 三、Windows 安装包签名（待购买证书后启用）

### 3.1 为什么要商业签名

没有签名的 `.exe` 安装包在 Windows 上运行时：
- Microsoft Defender SmartScreen 会显示 **"此应用可能会威胁你的设备安全"**
- 用户必须点击 **"仍要运行"** 才能继续安装
- 影响品牌信任度和转化率

### 3.2 证书类型选择

| 类型 | 价格（参考） | SmartScreen 效果 | 推荐度 |
|------|-------------|------------------|--------|
| 标准代码签名证书 (OV) | ¥1,500-3,000/年 | 初次下载仍可能触发，随下载量积累信誉后消除 | ⭐⭐⭐ |
| 扩展验证代码签名证书 (EV) | ¥3,000-6,000/年 | 立即消除 SmartScreen | ⭐⭐⭐⭐⭐ |
| 自签名证书 | 免费 | 需用户手动信任根证书，不适合分发 | ❌ |

**推荐**: 预算充足时直接购买 **EV 代码签名证书**（如 DigiCert、Sectigo、GlobalSign）。

### 3.3 启用商业签名的步骤

#### 步骤 1: 购买并获取证书
从正规 CA 购买 Windows 代码签名证书，获取 `.pfx` 或 `.p12` 文件。

#### 步骤 2: 配置 GitLab CI Variables

在 GitLab 项目设置 → **CI/CD → Variables** 中添加：

| 变量名 | 类型 | 值 | 说明 |
|--------|------|-----|------|
| `WINDOWS_CERTIFICATE` | Variable | 证书文件的 **base64 编码内容** | `certutil -encode certificate.pfx cert.b64` 生成 |
| `WINDOWS_CERTIFICATE_PASSWORD` | Variable | 证书密码 | Masked |

> 注意：Tauri CLI 会自动读取这两个环境变量并对 NSIS/MSI 安装包进行签名。

#### 步骤 3: 验证签名

构建完成后，在 Windows 上右键安装包 → **属性 → 数字签名**，应能看到签名者信息。

---

## 四、常见问题

### Q1: 现在没有商业证书，用户能用吗？
**可以。** 安装包功能完全正常，只是首次运行时会遇到 SmartScreen 提示。可在官网/下载页添加说明，指导用户点击"更多信息"→"仍要运行"。

### Q2: Updater 自签名和 Windows 商业签名有什么区别？
| | Updater 自签名 | Windows 商业签名 |
|--|----------------|------------------|
| 成本 | 免费 | 付费 |
| 作用 | 验证更新包完整性 | 验证软件发布者身份 |
| 影响范围 | Tauri 自动更新流程 | Windows 系统级信任 / SmartScreen |
| 是否必须 | 是（否则更新无法验证） | 否（但强烈推荐） |

### Q3: 可以先用自签名证书绕过 SmartScreen 吗？
**不建议。** 自签名证书需要每个用户手动在系统信任存储中安装根证书，操作复杂且极不专业，仅适用于内部测试。

---

## 五、相关文件

- `src-tauri/tauri.conf.json` — updater 公钥配置
- `src-tauri/.tauri-signing-key.pub` — minisign 公钥（已提交）
- `.gitlab-ci.yml` — CI 构建流程与签名环境变量
