markbase/docs/SYSTEM_EXTENSION_REGISTRATION_GUIDE.md

System Extension 注册指南

当前状态检查

# 检查代码签名证书
security find-identity -v -p codesigning
# 输出：0 valid identities found ❌

# 检查已安装的System Extensions
systemextensionsctl list
# 输出：0 extension(s) ❌

注册流程（3步骤）

步骤1：Developer Portal（需要手动操作）

访问： https://developer.apple.com/account

需要完成：

1. 创建App ID

   • Bundle ID: com.momentry.markbase.fskit
   • Entitlements: com.apple.developer.system-extension

2. 创建Developer Certificate

   • 类型：Mac App Development
   • 下载：.cer文件

3. 创建Provisioning Profile

   • App ID: com.momentry.markbase.fskit
   • Certificate: 刚创建的证书
   • Device: 当前Mac（需获取UDID）

获取Mac UDID：

system_profiler SPHardwareDataType | grep "Serial Number" | awk '{print $4}'

---

步骤2：本地配置（可代为操作）

2.1 导入证书到Keychain

# 导入Developer Certificate
security import ~/Downloads/developer_certificate.cer \
  -k ~/Library/Keychains/login.keychain-db \
  -T /usr/bin/codesign \
  -T /Applications/Xcode.app/Contents/Developer/usr/bin/codesign

# 验证导入成功
security find-identity -v -p codesigning
# 输出：1 valid identities found ✅

2.2 配置Xcode Signing（自动化脚本）

# 创建Xcode项目配置
xcodebuild -project MarkBaseFSKit.xcodeproj \
  -scheme MarkBaseFSKit \
  -configuration Release \
  -destination 'platform=macOS' \
  CODE_SIGN_IDENTITY="Apple Development" \
  DEVELOPMENT_TEAM="<YOUR_TEAM_ID>" \
  PRODUCT_BUNDLE_IDENTIFIER="com.momentry.markbase.fskit"

2.3 构建签名应用

# 构建Release版本
xcodebuild clean build \
  -project MarkBaseFSKit.xcodeproj \
  -scheme MarkBaseFSKit \
  -configuration Release \
  CODE_SIGN_IDENTITY="Apple Development" \
  DEVELOPMENT_TEAM="<YOUR_TEAM_ID>" \
  PRODUCT_BUNDLE_IDENTIFIER="com.momentry.markbase.fskit"

# 验证签名
codesign -d -vv --entitlements - build/Release/MarkBaseFSKit.app

---

步骤3：用户批准（需要手动操作）

安装System Extension：

# 使用systemextensionsctl安装
systemextensionsctl install \
  --team <TEAM_ID> \
  --bundleID com.momentry.markbase.fskit \
  --type filesystem \
  build/Release/MarkBaseFSKit.app

用户批准流程：

1. macOS弹出提示："MarkBaseFSKit wants to install a system extension"
2. 打开 System Settings → Privacy & Security
3. 点击 Allow 按钮
4. 重启Mac完成安装

验证安装成功：

systemextensionsctl list
# 输出：1 extension(s) ✅
# MarkBaseFSKit (com.momentry.markbase.fskit) [active]

---

可代为操作的步骤

步骤	可自动化	需要手动
Developer Portal登录	❌	✅ 需要Apple ID密码
创建App ID	❌	✅ 需要手动填写
创建Certificate	❌	✅ 需要手动操作
下载.cer文件	❌	✅ 需要手动下载
导入证书到Keychain	✅	- 脚本自动执行
配置Xcode Signing	✅	- 脚本自动执行
构建签名应用	✅	- 脚本自动执行
System Settings批准	❌	✅ 需要用户点击
重启Mac	❌	✅ 需要用户操作

总结：

• 60%可自动化（导入证书、构建、签名）
• 40%需手动（Portal操作、用户批准）

---

快速开始（假设已有证书）

如果用户已下载证书到 ~/Downloads/，可以执行：

# 一键安装脚本（假设证书已下载）
./scripts/install_system_extension.sh

脚本内容：

#!/bin/bash
# scripts/install_system_extension.sh

# 1. 导入证书
security import ~/Downloads/developer_certificate.cer \
  -k ~/Library/Keychains/login.keychain-db \
  -T /usr/bin/codesign

# 2. 构建签名应用
xcodebuild -project MarkBaseFSKit.xcodeproj \
  -scheme MarkBaseFSKit \
  -configuration Release \
  CODE_SIGN_IDENTITY="Apple Development" \
  DEVELOPMENT_TEAM="<TEAM_ID>" \
  PRODUCT_BUNDLE_IDENTIFIER="com.momentry.markbase.fskit"

# 3. 安装System Extension
systemextensionsctl install \
  --team <TEAM_ID> \
  --bundleID com.momentry.markbase.fskit \
  --type filesystem \
  build/Release/MarkBaseFSKit.app

echo "✅ System Extension已安装，请到System Settings批准"

---

下一步

需要用户提供：

1. Apple Developer账户状态（是否有账户？）
2. 是否已下载Developer Certificate
3. Team ID（10字符，如：ABC12DEF34）

我可以提供：

1. 完整的自动化脚本（install_system_extension.sh）
2. Xcode项目模板（MarkBaseFSKit.xcodeproj）
3. Entitlements配置文件

---

最后更新： 2026-05-18 17:28