136 lines
3.1 KiB
Markdown
136 lines
3.1 KiB
Markdown
# qimingcode 二进制代码签名问题
|
||
|
||
**日期**: 2026-03-28
|
||
**影响**: macOS 平台
|
||
|
||
---
|
||
|
||
## 问题描述
|
||
|
||
在 macOS 上，当从本地构建复制 qimingcode 二进制到 `~/.qimingclaw/node_modules/qimingcode-darwin-arm64/bin/` 时，运行时会收到 SIGKILL 信号。
|
||
|
||
### 症状
|
||
|
||
```log
|
||
[2026-03-28 10:29:08.097] [info] [AcpClient stdin] 📤 {"jsonrpc":"2.0","id":0,"method":"initialize"...}
|
||
[2026-03-28 10:29:09.380] [info] [AcpClient] Process exited { code: null, signal: 'SIGKILL' }
|
||
```
|
||
|
||
直接运行也失败：
|
||
```bash
|
||
~/.qimingclaw/node_modules/qimingcode-darwin-arm64/bin/qimingcode --version
|
||
# Exit code 137 (SIGKILL)
|
||
```
|
||
|
||
---
|
||
|
||
## 根因分析
|
||
|
||
macOS 的代码签名验证机制会拒绝未正确签名的二进制文件。
|
||
|
||
### 验证过程
|
||
|
||
1. 源二进制有 adhoc 签名：
|
||
```
|
||
codesign -dv ~/workspace/qimingcode/.../qimingcode
|
||
Signature=adhoc
|
||
```
|
||
|
||
2. 复制后文件哈希一致（排除文件损坏）：
|
||
```
|
||
shasum -a 256 source/qimingcode: 69605cb4...
|
||
shasum -a 256 target/qimingcode: 69605cb4... # 相同
|
||
```
|
||
|
||
3. 但运行时被系统终止
|
||
|
||
### 原因
|
||
|
||
macOS 对从网络下载或复制的二进制有额外的安全检查。即使文件有 adhoc 签名，某些情况下仍需要重新签名才能通过验证。
|
||
|
||
---
|
||
|
||
## 解决方案
|
||
|
||
### 临时修复（手动）
|
||
|
||
```bash
|
||
# 重新签名
|
||
codesign --force --sign - /path/to/qimingcode
|
||
|
||
# 验证
|
||
/path/to/qimingcode --version
|
||
```
|
||
|
||
### 长期方案
|
||
|
||
#### 方案 1：CI/CD 构建时签名
|
||
|
||
在 qimingcode 的构建流程中添加正式签名步骤：
|
||
|
||
```yaml
|
||
# .github/workflows/release.yml
|
||
- name: Sign binary (macOS)
|
||
if: runner.os == 'macOS'
|
||
run: |
|
||
codesign --force --sign - ./dist/qimingcode-darwin-arm64/bin/qimingcode
|
||
```
|
||
|
||
#### 方案 2：Electron 端自动签名
|
||
|
||
在复制二进制后自动签名：
|
||
|
||
```typescript
|
||
// src/main/services/packages/dependencies.ts
|
||
import { execSync } from "child_process"
|
||
|
||
function copyQimingCodeBinary(source: string, target: string) {
|
||
fs.copyFileSync(source, target)
|
||
|
||
// macOS 需要重新签名
|
||
if (process.platform === "darwin") {
|
||
try {
|
||
execSync(`codesign --force --sign - "${target}"`, { stdio: "pipe" })
|
||
log.info("Binary re-signed successfully", { target })
|
||
} catch (error) {
|
||
log.warn("Failed to re-sign binary", { error })
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 方案 3：使用 adhoc 签名 + 时间戳
|
||
|
||
```bash
|
||
codesign --force --sign - --timestamp none /path/to/qimingcode
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
1. **开发环境**：复制二进制后始终运行 `codesign --force --sign -`
|
||
|
||
2. **生产环境**：
|
||
- 使用 Apple Developer 证书正式签名
|
||
- 或在 CI/CD 中使用 adhoc 签名 + 公证
|
||
|
||
3. **调试技巧**：
|
||
```bash
|
||
# 检查签名状态
|
||
codesign -dv --verbose=4 /path/to/binary
|
||
|
||
# 检查扩展属性
|
||
xattr -l /path/to/binary
|
||
|
||
# 清除扩展属性
|
||
xattr -c /path/to/binary
|
||
```
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- qimingcode 性能优化文档：`/Users/apple/workspace/qimingcode/docs/PERF-PLUGIN-INIT-2026-03-28.md`
|
||
- Apple Code Signing Guide: https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/
|