# macOS 代码签名证书操作指南

本文档详细说明如何创建、导出和配置 macOS **Developer ID Application** 证书，用于 MateClaw Desktop 的签名与公证。

---

## 前置条件

- [Apple Developer Program](https://developer.apple.com/programs/) 会员（$99/年）
- macOS 系统（需要钥匙串访问生成密钥对）

## Step 1: 撤销旧证书（如有）

如果本地证书已过期或私钥丢失，需先撤销线上旧证书：

1. 登录 https://developer.apple.com/account/resources/certificates/list
2. 找到旧的 `Developer ID Application` 证书 → 点击进入详情
3. 点击 **Revoke** → 确认撤销
4. 回到本地 **钥匙串访问** → 删除过期证书（右键 → 删除）

## Step 2: 生成 CSR（证书签名请求）

CSR 会在本地生成密钥对（私钥留在钥匙串，公钥随 CSR 提交给 Apple）。

1. 打开 **钥匙串访问**
2. 菜单栏 → 钥匙串访问 → **证书助理** → **从证书颁发机构请求证书…**
3. 填写：
   - **用户电子邮件地址**：你的 Apple ID 邮箱
   - **常用名称**：与开发者账号一致（如 `ZHANFU XU`）
   - **CA 电子邮件地址**：留空
   - **请求是**：选择 **存储到磁盘**
4. 保存 `CertificateSigningRequest.certSigningRequest` 到桌面

## Step 3: 创建 Developer ID Application 证书

1. 访问 https://developer.apple.com/account/resources/certificates/add
2. 在 **Software** 分类下，选择 **Developer ID Application**
3. 点击 **Continue**
4. 上传 Step 2 保存的 CSR 文件
5. 点击 **Continue** → **Download** 下载 `developerID_application.cer`
6. **双击**下载的 `.cer` 文件 → 自动安装到钥匙串

## Step 4: 验证安装

```bash
security find-identity -v -p codesigning | grep "Developer ID Application"
```

应输出类似：

```
"Developer ID Application: ZHANFU XU (MR97WAD978)"
```

在钥匙串访问 → 登录 → **我的证书**中，展开该证书应能看到关联的**私钥**（左侧三角展开）。

## Step 5: 导出 .p12 文件

`.p12` 文件包含证书 + 私钥，是 `electron-builder` 签名所需的文件。

1. 钥匙串访问 → 登录 → **我的证书**
2. 找到 `Developer ID Application: Your Name (TEAMID)`
3. 点左侧三角**展开**，确认包含私钥
4. **右键证书**（不是私钥）→ **导出…**
5. 格式选择：**个人信息交换 (.p12)**
6. 保存为 `developer_id_application.p12`
7. 设置一个强密码（后续用作 `CSC_KEY_PASSWORD` 环境变量）

> **安全提醒**：`.p12` 文件包含私钥，绝不要提交到 Git 仓库。

## Step 6: 创建 App 专用密码（公证用）

Apple 公证（notarization）需要通过 Apple ID 验证身份，使用 App 专用密码代替账号密码。

1. 访问 https://appleid.apple.com/account/manage
2. 登录 → **登录与安全** → **App 专用密码** → **生成**
3. 标签填：`mateclaw-notarize`
4. 记录生成的密码（格式如 `xxxx-xxxx-xxxx-xxxx`）

## Step 7: 查找 Team ID

```bash
security find-identity -v -p codesigning | grep "Developer ID Application"
```

输出中括号内的 10 位字母数字即为 Team ID（如 `MR97WAD978`）。

## Step 8: 配置环境变量并构建

### 方式 A：本地钥匙串自动发现（推荐）

证书已安装到本地钥匙串时，**不需要设置 `CSC_LINK` 和 `CSC_KEY_PASSWORD`**，electron-builder 会自动从钥匙串中发现 Developer ID Application 证书。

```bash
cd mateclaw-desktop

# 只需设置公证相关变量
export APPLE_ID="your@apple.id"
export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="XXXXXXXXXX"

# 执行签名+公证构建
bash scripts/build-all-platforms.sh --mac-only
```

> **为什么推荐这种方式？** 设置 `CSC_LINK` 时，electron-builder 会创建一个临时钥匙串来导入 `.p12` 文件，这可能导致签名过程静默卡死（无报错）。直接使用本地钥匙串可以避免此问题。

### 方式 B：指定 .p12 文件（CI/CD 专用）

在 CI/CD 环境或证书不在本地钥匙串时，需要通过环境变量指定 `.p12` 文件：

```bash
cd mateclaw-desktop

export CSC_LINK="$HOME/developer_id_application.p12"
export CSC_KEY_PASSWORD="你的p12密码"
export APPLE_ID="your@apple.id"
export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="XXXXXXXXXX"

bash scripts/build-all-platforms.sh --mac-only
```

> **注意**：`CSC_KEY_PASSWORD` 中如有特殊字符（`$`、`!`、`"`、`` ` ``），必须用**单引号**包裹，如 `export CSC_KEY_PASSWORD='pa$$w0rd!'`。

### GitHub Actions Secrets

将 `.p12` 文件 Base64 编码后存为 GitHub Secret：

```bash
base64 -i developer_id_application.p12 | pbcopy
# 粘贴到 GitHub Secret: MAC_CSC_LINK
```

| GitHub Secret | 值 |
|---|---|
| `MAC_CSC_LINK` | `.p12` 的 Base64 内容 |
| `MAC_CSC_KEY_PASSWORD` | `.p12` 密码 |
| `APPLE_ID` | Apple ID 邮箱 |
| `APPLE_APP_SPECIFIC_PASSWORD` | App 专用密码 |
| `APPLE_TEAM_ID` | 10 位 Team ID |

## Step 9: 验证签名和公证

构建完成后验证：

```bash
# 验证代码签名
codesign --verify --deep --strict release/mac-arm64/MateClaw.app

# 验证 Gatekeeper 公证状态
spctl --assess --type execute --verbose release/mac-arm64/MateClaw.app
# 期望输出: accepted, source=Developer ID

# 验证 DMG
spctl --assess --type open --context context:primary-signature release/MateClaw-*.dmg
```

---

## 故障排查

### 签名卡死（无报错）

**现象**：构建停在 `signing` 行不动，`ps aux | grep codesign` 无进程或进程短暂出现后消失。

**原因**：设置了 `CSC_LINK` 后，electron-builder 会创建临时钥匙串导入 `.p12`，临时钥匙串的访问权限可能导致 `codesign` 静默卡死。

**解决**：
```bash
# 方案一（推荐）：取消 CSC_LINK，使用本地钥匙串自动发现
unset CSC_LINK
unset CSC_KEY_PASSWORD

# 方案二：授权 codesign 访问钥匙串
security unlock-keychain -p "你的Mac登录密码" ~/Library/Keychains/login.keychain-db
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "你的Mac登录密码" ~/Library/Keychains/login.keychain-db
```

### `Permission denied` (classes.jsa)

**现象**：`codesign` 报错 `Permission denied`，通常指向 JRE 中的 `classes.jsa` 文件。

**原因**：下载的 Adoptium JRE 中部分文件是只读的，`codesign --force` 需要写权限。

**解决**：`download-jre.sh` 已在解压后自动执行 `chmod -R u+w`。如果使用旧版 JRE，手动修复：
```bash
# 删除旧 JRE 重新下载（推荐）
rm -rf resources/jre/mac-arm64 resources/jre/mac-x64
npm run setup:jre

# 或手动修复权限
chmod -R u+w resources/jre/
```

### `MAC verification failed` (wrong password)

**现象**：`SecKeychainItemImport: MAC verification failed during PKCS12 import (wrong password?)`

**原因**：`CSC_KEY_PASSWORD` 与导出 `.p12` 时设置的密码不匹配。

**解决**：
```bash
# 验证密码是否正确
openssl pkcs12 -in ~/developer_id_application.p12 -nokeys -passin pass:"你的密码"

# 如果报错 mac verify failure，重新导出 .p12：
# 钥匙串访问 → 我的证书 → 右键 Developer ID Application → 导出 → 重新设置密码

# 注意特殊字符需用单引号包裹
export CSC_KEY_PASSWORD='pa$$w0rd!'
```

### 公证上传超时 (deadlineExceeded)

**现象**：`HTTPClientError.deadlineExceeded`，公证上传到 Apple S3 超时。

**原因**：网络到 Apple 服务器不稳定，700MB+ 的应用上传容易超时。

**解决**：先跳过公证构建，再用 `xcrun notarytool` 手动公证（支持断点续传，超时容忍度更高）：
```bash
# 1. 去掉公证变量，仅签名
unset APPLE_ID
unset APPLE_APP_SPECIFIC_PASSWORD
unset APPLE_TEAM_ID
bash scripts/build-all-platforms.sh --mac-only

# 2. 手动公证
xcrun notarytool submit release/MateClaw_1.0.0_arm64.zip \
  --apple-id "your@apple.id" \
  --password "app专用密码" \
  --team-id "XXXXXXXXXX" \
  --wait

xcrun notarytool submit release/MateClaw_1.0.0_x64.zip \
  --apple-id "your@apple.id" \
  --password "app专用密码" \
  --team-id "XXXXXXXXXX" \
  --wait

# 3. 装订公证票据到 DMG
xcrun stapler staple release/MateClaw_1.0.0_arm64.dmg
xcrun stapler staple release/MateClaw_1.0.0_x64.dmg
```

---

## 常见问题

### 证书过期了怎么办？

Developer ID Application 证书有效期 **5 年**。过期后需重复 Step 1 ~ Step 5 重新创建。Apple 会在自动轮换日期前通过邮件提醒。

### 导出 .p12 时没有"导出"选项？

说明本地钥匙串中没有该证书对应的私钥。私钥只存在于当初生成 CSR 的那台 Mac 上。解决方案：
- **方案 A**：在原 Mac 上导出 `.p12`，再导入到当前 Mac
- **方案 B**：撤销旧证书，在当前 Mac 重新创建（Step 1 ~ Step 5）

### 签名很慢正常吗？

正常。700MB+ 的应用（含 JRE + Electron Framework）签名需要 **15~30 分钟**，公证上传+审核需要额外 **5~15 分钟**。可以用以下命令监控签名进度：
```bash
watch -n 2 'ps aux | grep codesign | grep -v grep'
# macOS 需先安装：brew install watch
```

### 跳过签名（开发测试用）

```bash
export CSC_IDENTITY_AUTO_DISCOVERY=false
bash scripts/build-all-platforms.sh --mac-only
```

未签名的应用无法使用自动升级功能，macOS 用户需手动下载 DMG 安装。