## 目录 - [功能介绍](#what-it-does) - [系统要求](#requirements) - [演示](#demo) - [安装](#install) - [设置](#setup) - [日常使用](#daily-use) - [安全模型](#security-model) - [技术栈](#tech-stack) - [从早期版本迁移](#migration-from-earlier-versions) - [致谢](#acknowledgments) - [许可证](#license) ## 功能介绍 - 使用 **ArcFace**（InsightFace ResNet50，已转换为 Core ML 并在 Apple Neural Engine 上运行）从 7 个姿势录入你的面容。 - 在锁屏界面，按下空格键/回车键（或唤醒显示器）会触发扫描，验证身份 + 活体检测，然后为你自动输入 Mac 密码。 - 作为菜单栏 agent 运行。 - 你的 Mac 密码和 face embeddings 使用存储在 Keychain 中并由 Touch ID 保护的 session key 进行 AES-GCM 加密。每次重启后需要进行一次 Touch ID 解锁以启用自动解锁。 ## 系统要求 - macOS 14 (Sonoma) 或更高版本 - 强烈推荐使用 Apple Silicon（Intel 也可用，但速度较慢） - 默认摄像头（内置、外置或 Continuity Camera） - Touch ID 或设备密码 ## 演示 YouTube 上的完整安装 + 设置演示： [](https://youtu.be/TZHXuBUaZ_8) ## 安装 ### 通过 Homebrew 1. 添加 tap： brew tap sh4dow-clone/tap 2. 安装 cask： brew install --cask sh4dow-clone/tap/faceunlock ### 直接下载 或者，直接从 [Releases](../../releases) 页面下载该应用。 ## 设置 1. 打开 **FaceUnlock.app**，并在出现提示时允许访问 **摄像头**。 2. 授予 **辅助功能** 权限（设置选项卡 → “Request Permission…”） - 这是在锁屏界面输入密码所必需的。 3. **设置 Mac 密码**：设置选项卡 → “Set Password…”，两次输入你的登录密码。 4. **录入你的面容**：面容识别选项卡 → “Capture”（需要 Touch ID）并遵循 7 个姿势的指引。 5. 开启 **“Auto-unlock when display wakes (while screen is locked)”**。 稍后你可以使用 **“Add Captures”** 在不同的光照条件下录入更多 embeddings（最多 35 个，优先淘汰最旧的） - 这能提高准确性，并让你可以安全地提高匹配阈值。 ### 可选设置 | 设置 | 描述 | |---|---| | **Icon Placement** | 独立显示/隐藏 Dock 和菜单栏图标。 | | **Launch at Login** | 通过系统设置 → 通用 → 登录项添加 FaceUnlock。 | | **Auto-scan when face is centered** | 无需按键自动触发扫描。默认关闭。 | | **Match threshold** | 默认 0.70。建议在几次录入后设置为：0.75（均衡），0.80（安全），0.85（高安全）。 | | **Auto-unlock delay** | 默认在触发和激活摄像头之间有 4 秒延迟，以便你可以使用 `⌃⌘Q` 中止。 | ## 日常使用 1. 锁定你的 Mac。 2. 唤醒显示器，并在锁屏界面按下 **空格键** 或 **回车键**。 3. 摄像头最长运行 15 秒，检查面容 + 活体检测，并自动输入你的密码。 4. 如果无法及时识别你，摄像头将关闭，你需要手动输入密码 - 这与 Face ID / Windows Hello 的回退方式相同。 有效工作距离：距离摄像头约 20–70 厘米。 ## 安全模型 | 数据 | 存储 | 加密 | |---|---|---| | Mac 密码 | Keychain | AES-GCM + Keychain | | Session key | Keychain | `SecAccessControl(.userPresence)` - 需要 Touch ID | | Face embeddings | `~/Library/Application Support/FaceUnlock/embeddings.enc` | AES-GCM，使用相同的 session key | | 设置 | UserDefaults | 明文（非敏感信息） | session key 是唯一的解密点 - 如果没有 Touch ID，密码数据块和 embeddings 文件都是毫无意义的密文。 **内置保护：** - ArcFace 面容匹配，具有适当的对齐/归一化功能，并与已录入的集合进行余弦相似度比对。 - 多帧平均和姿态过滤器以减少噪音。 - 基于被动运动的活体检测（可抵御静态照片攻击）。 - 仅考虑位于居中 ROI 内的面容。 - 密码仅在短时间内以明文形式存在，使用后立即清零。 - Hardened Runtime，防调试程序保护，最小权限原则（仅限摄像头 + Keychain - 无网络，无其他权限）。 - 完全本地处理 - 无遥测，无第三方 SDK。 **注意事项：** - 在 Touch ID 授权访问后，FaceUnlock 仅在完成解锁时短暂访问你的密码。该应用使用 Hardened Runtime 和最小系统权限来帮助保护此过程，而 macOS 的安全机制继续提供主要的保护层。 - FaceUnlock 使用基于运动的活体检测来区分真人和静态照片。虽然它不使用专用的深度硬件，但它为日常使用提供了可靠的验证。 - 如果你有一个极其相似的人（例如同卵双胞胎），提高匹配阈值可以提供额外的信心。 **总结：** FaceUnlock 增加了快速、便捷的解锁体验，同时保留你现有的 macOS 密码作为安全基础。请查阅安全模型以选择最适合你偏好的设置。 ## 技术栈 SwiftUI · AVFoundation · Vision · Core ML (ArcFace on ANE) · CryptoKit (AES-GCM) · LocalAuthentication · Keychain Services · CGEvent keystroke injection ## 从早期版本迁移 旧版本将 embeddings 存储为明文 JSON。这将在你下次录入时自动迁移到加密存储 - 你现有的录入在此期间会继续工作。要立即迁移：面容识别选项卡 → Reset → Capture。 ## 致谢 - **InsightFace** 提供了 [w600k_r50](https://github.com/deepinsight/insightface/tree/master/model_zoo) ## 许可证 仅供个人使用。如果你进行再分发，请验证 InsightFace 的模型许可条款是否适用于你的使用场景。 ## 支持 如果它为你节省了时间，请考虑提供支持 - 我是一名在业余时间维护此项目的学生。 目前我正试图筹集 **$99 以购买 Apple Developer Program 会员**。这是获得正确签名和公证该应用所需的费用 - 这将完全消除安装时的安全警告。不再有可怕的弹窗，不再需要为了打开应用而在终端中运行 `xattr` 和 `codesign`。 如果你自己也遇到过那个警告，这正是你的支持将为后来的每个人解决的问题。 [](https://ko-fi.com/sh4dow_clone) 点个 ⭐ star 也有帮助 - 这能让其他需要此功能的 macOS 用户更容易找到该项目。

标签：Core ML, 人脸识别, 本地部署, 系统工具