doc: Add the "docs\macOS_Support_Design.md" to git
This commit is contained in:
yuanyuanxiang
576
docs/macOS_Support_Design.md
Normal file
576
docs/macOS_Support_Design.md
Normal file
@@ -0,0 +1,576 @@
|
|||||||
|
# macOS 远程桌面客户端设计文档
|
||||||
|
|
||||||
|
## 1. 概述
|
||||||
|
|
||||||
|
### 1.1 目标
|
||||||
|
|
||||||
|
在不影响现有 Windows/Linux 功能的基础上，为 YAMA 项目添加 macOS 客户端支持，前期实现远程桌面控制功能。
|
||||||
|
|
||||||
|
### 1.2 功能范围（Phase 1）
|
||||||
|
|
||||||
|
| 功能 | 优先级 | 状态 | 说明 |
|
||||||
|
|-----|--------|------|------|
|
||||||
|
| 连接服务器 | P0 | ⏳ Stub | 复用现有网络协议 |
|
||||||
|
| 屏幕捕获 | P0 | ✅ 完成 | CGDisplayCreateImage 实现 |
|
||||||
|
| 鼠标控制 | P0 | ✅ 完成 | CGEvent 实现 |
|
||||||
|
| 键盘控制 | P0 | ✅ 完成 | CGEvent + VK映射 |
|
||||||
|
| 光标同步 | P1 | ⏳ 待实现 | 显示当前光标类型 |
|
||||||
|
| 多显示器 | P2 | ⏳ 待实现 | 支持多屏幕选择 |
|
||||||
|
|
||||||
|
### 1.3 参考实现
|
||||||
|
|
||||||
|
- **Linux 客户端** (`linux/`): 架构相似，协议兼容
|
||||||
|
- **RustDesk**: 成熟的跨平台远程桌面开源项目
|
||||||
|
- **Sunshine**: 高性能游戏串流项目
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 架构设计
|
||||||
|
|
||||||
|
### 2.1 目录结构（已实现）
|
||||||
|
|
||||||
|
```
|
||||||
|
YAMA/
|
||||||
|
├── common/ # 跨平台共享（已有）
|
||||||
|
│ ├── commands.h # 协议定义
|
||||||
|
│ └── ...
|
||||||
|
├── client/ # Windows 客户端（不动）
|
||||||
|
├── linux/ # Linux 客户端（不动）
|
||||||
|
└── macos/ # macOS 客户端（Phase 1 完成）
|
||||||
|
├── CMakeLists.txt # 构建配置
|
||||||
|
├── build.sh # 一键编译脚本
|
||||||
|
├── README.txt # 使用说明
|
||||||
|
├── IOCPClient.h # 网络客户端 stub
|
||||||
|
├── main.mm # 入口点 + 系统信息
|
||||||
|
├── Permissions.h # 权限检查声明
|
||||||
|
├── Permissions.mm # 权限检查实现
|
||||||
|
├── ScreenHandler.h # 屏幕捕获声明
|
||||||
|
├── ScreenHandler.mm # 屏幕捕获实现
|
||||||
|
├── InputHandler.h # 输入模拟声明
|
||||||
|
├── InputHandler.mm # 输入模拟实现
|
||||||
|
├── SystemManager.h # 进程管理声明
|
||||||
|
└── SystemManager.mm # 进程管理实现
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 模块依赖关系
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────┐
|
||||||
|
│ main.mm │
|
||||||
|
│ (入口、权限检查、系统信息收集) │
|
||||||
|
└─────────────┬───────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────┼─────────┬─────────────┐
|
||||||
|
▼ ▼ ▼ ▼
|
||||||
|
┌───────┐ ┌───────┐ ┌───────┐ ┌────────────┐
|
||||||
|
│Screen │ │Input │ │System │ │IOCPClient │
|
||||||
|
│Handler│ │Handler│ │Manager│ │(网络 stub) │
|
||||||
|
└───┬───┘ └───┬───┘ └───────┘ └────────────┘
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ macOS 系统框架 │
|
||||||
|
│ CoreGraphics (截屏) │
|
||||||
|
│ Carbon (键码定义) │
|
||||||
|
│ ApplicationServices (权限) │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 技术选型
|
||||||
|
|
||||||
|
### 3.1 屏幕捕获方案（已选定）
|
||||||
|
|
||||||
|
| 方案 | 最低版本 | 性能 | 复杂度 | 选择 |
|
||||||
|
|-----|---------|------|--------|-----|
|
||||||
|
| `CGDisplayCreateImage` | 10.5 | 中 | 低 | **✅ 已采用** |
|
||||||
|
| `CGDisplayStream` | 10.8 | 中 | 中 | 备选 |
|
||||||
|
| `ScreenCaptureKit` | 12.3 | 高 | 高 | 未来考虑 |
|
||||||
|
|
||||||
|
**选择 CGDisplayCreateImage**：
|
||||||
|
- 实现简单，兼容性好
|
||||||
|
- 与 Linux 端 `XGetImage` 方案一致
|
||||||
|
- 足以支持 10-30 FPS 传输
|
||||||
|
|
||||||
|
### 3.2 输入模拟方案（已实现）
|
||||||
|
|
||||||
|
| 功能 | API | 实现状态 |
|
||||||
|
|-----|-----|---------|
|
||||||
|
| 鼠标移动 | `CGEventCreateMouseEvent` | ✅ 完成 |
|
||||||
|
| 鼠标点击 | `CGEventCreateMouseEvent` | ✅ 完成 |
|
||||||
|
| 鼠标拖动 | `kCGEventLeftMouseDragged` | ✅ 完成 |
|
||||||
|
| 鼠标滚轮 | `CGEventCreateScrollWheelEvent` | ✅ 完成 |
|
||||||
|
| 键盘输入 | `CGEventCreateKeyboardEvent` | ✅ 完成 |
|
||||||
|
| 事件发送 | `CGEventPost(kCGHIDEventTap)` | ✅ 完成 |
|
||||||
|
|
||||||
|
### 3.3 VK 键码映射（已实现）
|
||||||
|
|
||||||
|
Windows VK 码到 macOS CGKeyCode 的完整映射：
|
||||||
|
|
||||||
|
| 按键类型 | VK 范围 | macOS 映射 |
|
||||||
|
|---------|---------|-----------|
|
||||||
|
| 字母 A-Z | 0x41-0x5A | kVK_ANSI_A - kVK_ANSI_Z |
|
||||||
|
| 数字 0-9 | 0x30-0x39 | kVK_ANSI_0 - kVK_ANSI_9 |
|
||||||
|
| 小键盘 | 0x60-0x69 | kVK_ANSI_Keypad0 - 9 |
|
||||||
|
| F1-F12 | 0x70-0x7B | kVK_F1 - kVK_F12 |
|
||||||
|
| 方向键 | 0x25-0x28 | kVK_LeftArrow 等 |
|
||||||
|
| 修饰键 | 0x10-0x12 | kVK_Shift/Control/Option |
|
||||||
|
| Win 键 | 0x5B-0x5C | kVK_Command |
|
||||||
|
|
||||||
|
### 3.4 差分算法（与 Linux 一致）
|
||||||
|
|
||||||
|
| 算法 | ID | 说明 |
|
||||||
|
|-----|-----|------|
|
||||||
|
| ALGORITHM_GRAY | 0 | 灰度压缩 |
|
||||||
|
| ALGORITHM_DIFF | 1 | BGRA 差分 |
|
||||||
|
| ALGORITHM_H264 | 2 | 硬件编码（未实现）|
|
||||||
|
| ALGORITHM_RGB565 | 3 | RGB565 压缩 |
|
||||||
|
|
||||||
|
### 3.5 macOS 版本支持
|
||||||
|
|
||||||
|
| 版本 | 代号 | 发布年份 | 支持状态 |
|
||||||
|
|-----|------|---------|---------|
|
||||||
|
| 10.13 | High Sierra | 2017 | ✅ 目标最低版本 |
|
||||||
|
| 10.14 | Mojave | 2018 | ✅ 支持 |
|
||||||
|
| 10.15 | Catalina | 2019 | ✅ 支持（需权限） |
|
||||||
|
| 11.x | Big Sur | 2020 | ✅ 支持 |
|
||||||
|
| 12.x | Monterey | 2021 | ✅ 支持 |
|
||||||
|
| 13.x | Ventura | 2022 | ✅ 支持 |
|
||||||
|
| 14.x | Sonoma | 2023 | ✅ 支持 |
|
||||||
|
|
||||||
|
**注意**：macOS 10.15+ 需要用户授予屏幕录制权限。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 权限处理
|
||||||
|
|
||||||
|
### 4.1 所需权限
|
||||||
|
|
||||||
|
| 权限 | 用途 | 最低要求版本 | 授权方式 |
|
||||||
|
|-----|------|------------|---------|
|
||||||
|
| **屏幕录制** | 捕获屏幕内容 | 10.15 | 系统偏好设置 > 隐私 > 屏幕录制 |
|
||||||
|
| **辅助功能** | 模拟键盘/鼠标输入 | 所有版本 | 系统偏好设置 > 隐私 > 辅助功能 |
|
||||||
|
|
||||||
|
### 4.2 权限检查实现（Permissions.mm）
|
||||||
|
|
||||||
|
```objc
|
||||||
|
// 检查屏幕录制权限
|
||||||
|
bool Permissions::checkScreenCapture() {
|
||||||
|
if (@available(macOS 10.15, *)) {
|
||||||
|
CGImageRef image = CGWindowListCreateImage(
|
||||||
|
CGRectMake(0, 0, 1, 1),
|
||||||
|
kCGWindowListOptionOnScreenOnly,
|
||||||
|
kCGNullWindowID,
|
||||||
|
kCGWindowImageDefault
|
||||||
|
);
|
||||||
|
if (image == nil) return false;
|
||||||
|
CGImageRelease(image);
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
return true; // 10.15 之前不需要权限
|
||||||
|
}
|
||||||
|
|
||||||
|
// 检查辅助功能权限
|
||||||
|
bool Permissions::checkAccessibility() {
|
||||||
|
return AXIsProcessTrusted();
|
||||||
|
}
|
||||||
|
|
||||||
|
// 请求辅助功能权限（弹出系统对话框）
|
||||||
|
void Permissions::requestAccessibility() {
|
||||||
|
NSDictionary *options = @{
|
||||||
|
(__bridge id)kAXTrustedCheckOptionPrompt: @YES
|
||||||
|
};
|
||||||
|
AXIsProcessTrustedWithOptions((__bridge CFDictionaryRef)options);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 权限引导流程
|
||||||
|
|
||||||
|
```
|
||||||
|
程序启动
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
检查屏幕录制权限 ──否──▶ 打开系统偏好设置
|
||||||
|
│
|
||||||
|
是
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
检查辅助功能权限 ──否──▶ 弹出授权对话框
|
||||||
|
│
|
||||||
|
是
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
正常运行
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 核心代码实现
|
||||||
|
|
||||||
|
### 5.1 ScreenHandler（已实现）
|
||||||
|
|
||||||
|
```objc
|
||||||
|
// ScreenHandler.h
|
||||||
|
class ScreenHandler {
|
||||||
|
public:
|
||||||
|
ScreenHandler();
|
||||||
|
~ScreenHandler();
|
||||||
|
|
||||||
|
bool init(); // 初始化
|
||||||
|
void start(IOCPClient* client, uint64_t id); // 开始捕获
|
||||||
|
void stop(); // 停止捕获
|
||||||
|
|
||||||
|
int getWidth() const;
|
||||||
|
int getHeight() const;
|
||||||
|
|
||||||
|
void sendBitmapInfo(); // 发送屏幕信息
|
||||||
|
void onReceive(const uint8_t* data, size_t size);
|
||||||
|
void applyQualityLevel(int8_t level, bool persist);
|
||||||
|
|
||||||
|
private:
|
||||||
|
bool captureScreen(std::vector<uint8_t>& buffer); // 截屏
|
||||||
|
void sendFirstScreen(); // 发送首帧
|
||||||
|
void sendDiffFrame(); // 发送差分帧
|
||||||
|
uint32_t compareBitmap(...); // 差分计算
|
||||||
|
void convertBGRAtoGray(...); // 灰度转换
|
||||||
|
void convertBGRAtoRGB565(...); // RGB565转换
|
||||||
|
void captureLoop(); // 捕获循环
|
||||||
|
|
||||||
|
// 成员变量
|
||||||
|
IOCPClient* m_client;
|
||||||
|
CGDirectDisplayID m_displayID;
|
||||||
|
BITMAPINFOHEADER_MAC m_bmpHeader;
|
||||||
|
std::vector<uint8_t> m_prevFrame, m_currFrame;
|
||||||
|
std::atomic<bool> m_running;
|
||||||
|
std::atomic<uint8_t> m_algorithm;
|
||||||
|
std::atomic<int> m_maxFPS;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 InputHandler（已实现）
|
||||||
|
|
||||||
|
```objc
|
||||||
|
// InputHandler.h
|
||||||
|
class InputHandler {
|
||||||
|
public:
|
||||||
|
InputHandler();
|
||||||
|
~InputHandler();
|
||||||
|
|
||||||
|
bool init(); // 初始化（检查权限）
|
||||||
|
void handleInputEvent(const MSG64_MAC* msg); // 处理输入事件
|
||||||
|
bool hasAccessibilityPermission() const;
|
||||||
|
|
||||||
|
private:
|
||||||
|
void handleMouseMove(int x, int y);
|
||||||
|
void handleMouseButton(CGMouseButton button, bool down, int x, int y);
|
||||||
|
void handleMouseDoubleClick(CGMouseButton button, int x, int y);
|
||||||
|
void handleMouseWheel(int delta);
|
||||||
|
void handleKeyEvent(uint32_t vkCode, bool down);
|
||||||
|
|
||||||
|
static CGKeyCode vkToMacKeyCode(uint32_t vk); // VK 到 macOS 键码映射
|
||||||
|
|
||||||
|
bool m_hasPermission;
|
||||||
|
CGPoint m_lastMousePos;
|
||||||
|
bool m_leftButtonDown, m_rightButtonDown, m_middleButtonDown;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 SystemManager（已实现）
|
||||||
|
|
||||||
|
```objc
|
||||||
|
// SystemManager.h
|
||||||
|
class SystemManager {
|
||||||
|
public:
|
||||||
|
SystemManager(IOCPClient* client, uint64_t clientID);
|
||||||
|
~SystemManager();
|
||||||
|
|
||||||
|
void onReceive(const uint8_t* data, size_t size);
|
||||||
|
|
||||||
|
private:
|
||||||
|
void sendProcessList(); // 进程列表
|
||||||
|
void killProcesses(const uint8_t* data, size_t size);
|
||||||
|
void sendWindowsList(); // 窗口列表
|
||||||
|
|
||||||
|
static std::vector<pid_t> getAllPids(); // 枚举进程
|
||||||
|
static std::string getProcessName(pid_t pid);
|
||||||
|
static std::string getProcessPath(pid_t pid);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.4 main.mm（已实现）
|
||||||
|
|
||||||
|
主要功能：
|
||||||
|
- 命令行参数解析
|
||||||
|
- 权限检查和引导
|
||||||
|
- 系统信息收集（主机名、OS版本、CPU、内存等）
|
||||||
|
- 初始化各处理器
|
||||||
|
- 主事件循环
|
||||||
|
|
||||||
|
```objc
|
||||||
|
int main(int argc, const char* argv[]) {
|
||||||
|
@autoreleasepool {
|
||||||
|
// 1. 解析命令行参数
|
||||||
|
// 2. 检查权限
|
||||||
|
// 3. 收集系统信息
|
||||||
|
// 4. 初始化 ScreenHandler, InputHandler
|
||||||
|
// 5. 主循环
|
||||||
|
}
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 构建配置
|
||||||
|
|
||||||
|
### 6.1 CMakeLists.txt
|
||||||
|
|
||||||
|
```cmake
|
||||||
|
cmake_minimum_required(VERSION 3.15)
|
||||||
|
project(ghost_macos)
|
||||||
|
|
||||||
|
set(CMAKE_CXX_STANDARD 17)
|
||||||
|
set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13")
|
||||||
|
set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64") # Universal Binary
|
||||||
|
|
||||||
|
set(SOURCES
|
||||||
|
main.mm
|
||||||
|
ScreenHandler.mm
|
||||||
|
InputHandler.mm
|
||||||
|
SystemManager.mm
|
||||||
|
Permissions.mm
|
||||||
|
)
|
||||||
|
|
||||||
|
add_executable(ghost ${SOURCES})
|
||||||
|
|
||||||
|
target_include_directories(ghost PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
|
||||||
|
|
||||||
|
# 链接 macOS 框架
|
||||||
|
find_library(COCOA_FRAMEWORK Cocoa REQUIRED)
|
||||||
|
find_library(COREGRAPHICS_FRAMEWORK CoreGraphics REQUIRED)
|
||||||
|
find_library(IOKIT_FRAMEWORK IOKit REQUIRED)
|
||||||
|
find_library(IOSURFACE_FRAMEWORK IOSurface REQUIRED)
|
||||||
|
find_library(APPLICATIONSERVICES_FRAMEWORK ApplicationServices REQUIRED)
|
||||||
|
find_library(SECURITY_FRAMEWORK Security REQUIRED)
|
||||||
|
find_library(CARBON_FRAMEWORK Carbon REQUIRED)
|
||||||
|
|
||||||
|
target_link_libraries(ghost PRIVATE
|
||||||
|
${COCOA_FRAMEWORK}
|
||||||
|
${COREGRAPHICS_FRAMEWORK}
|
||||||
|
${IOKIT_FRAMEWORK}
|
||||||
|
${IOSURFACE_FRAMEWORK}
|
||||||
|
${APPLICATIONSERVICES_FRAMEWORK}
|
||||||
|
${SECURITY_FRAMEWORK}
|
||||||
|
${CARBON_FRAMEWORK}
|
||||||
|
)
|
||||||
|
|
||||||
|
target_compile_options(ghost PRIVATE -Wall -Wextra -fobjc-arc)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 编译命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 方式 1: 使用脚本
|
||||||
|
chmod +x build.sh
|
||||||
|
./build.sh
|
||||||
|
|
||||||
|
# 方式 2: 手动编译
|
||||||
|
mkdir build && cd build
|
||||||
|
cmake ..
|
||||||
|
make -j$(sysctl -n hw.ncpu)
|
||||||
|
|
||||||
|
# 输出: build/bin/ghost
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 实现进度
|
||||||
|
|
||||||
|
### Phase 1: 基础框架 ✅ 完成
|
||||||
|
|
||||||
|
| 任务 | 状态 | 产出 |
|
||||||
|
|-----|------|------|
|
||||||
|
| 创建目录结构 | ✅ | `macos/` 目录 |
|
||||||
|
| CMakeLists.txt | ✅ | 构建配置 |
|
||||||
|
| Permissions.h/mm | ✅ | 权限检查 |
|
||||||
|
| ScreenHandler.h/mm | ✅ | 屏幕捕获 |
|
||||||
|
| InputHandler.h/mm | ✅ | 输入模拟 |
|
||||||
|
| SystemManager.h/mm | ✅ | 进程管理 |
|
||||||
|
| main.mm | ✅ | 入口点 |
|
||||||
|
| IOCPClient.h | ✅ | 网络 stub |
|
||||||
|
|
||||||
|
### Phase 2: 网络集成 ⏳ 待实现
|
||||||
|
|
||||||
|
| 任务 | 状态 | 说明 |
|
||||||
|
|-----|------|------|
|
||||||
|
| IOCPClient 实现 | ⏳ | 复用 client/IOCPClient |
|
||||||
|
| 登录信息发送 | ⏳ | LOGIN_INFOR 结构 |
|
||||||
|
| 心跳保活 | ⏳ | Heartbeat 机制 |
|
||||||
|
| 命令分发 | ⏳ | DataProcess 回调 |
|
||||||
|
|
||||||
|
### Phase 3: 功能完善 ⏳ 待实现
|
||||||
|
|
||||||
|
| 任务 | 状态 |
|
||||||
|
|-----|------|
|
||||||
|
| 光标类型同步 | ⏳ |
|
||||||
|
| 多显示器支持 | ⏳ |
|
||||||
|
| 文件传输 | ⏳ |
|
||||||
|
| 剪贴板同步 | ⏳ |
|
||||||
|
|
||||||
|
### Phase 4: 代码保护 ⏳ 待实现
|
||||||
|
|
||||||
|
| 任务 | 状态 |
|
||||||
|
|-----|------|
|
||||||
|
| 服务端密钥对生成 | ⏳ |
|
||||||
|
| 服务端签名逻辑 | ⏳ |
|
||||||
|
| 闭源库 libYamaCore | ⏳ |
|
||||||
|
| 客户端绑定验证 | ⏳ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 测试指南
|
||||||
|
|
||||||
|
### 8.1 编译前准备
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装 Xcode Command Line Tools
|
||||||
|
xcode-select --install
|
||||||
|
|
||||||
|
# 安装 CMake (通过 Homebrew)
|
||||||
|
brew install cmake
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 编译运行
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 获取代码
|
||||||
|
git clone <repo-url>
|
||||||
|
cd YAMA/macos
|
||||||
|
|
||||||
|
# 编译
|
||||||
|
./build.sh
|
||||||
|
|
||||||
|
# 运行
|
||||||
|
./build/bin/ghost [server_ip] [port]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.3 首次运行权限授予
|
||||||
|
|
||||||
|
1. **屏幕录制权限**：
|
||||||
|
- 系统偏好设置 > 隐私与安全性 > 屏幕录制
|
||||||
|
- 添加 `ghost` 可执行文件
|
||||||
|
|
||||||
|
2. **辅助功能权限**：
|
||||||
|
- 系统偏好设置 > 隐私与安全性 > 辅助功能
|
||||||
|
- 添加 `ghost` 可执行文件
|
||||||
|
|
||||||
|
### 8.4 预期输出
|
||||||
|
|
||||||
|
```
|
||||||
|
=== macOS Ghost Client (Phase 1) ===
|
||||||
|
Server: 192.168.0.55:6543
|
||||||
|
Checking permissions...
|
||||||
|
Collecting system information...
|
||||||
|
Hostname: MacBook-Pro.local
|
||||||
|
OS: macOS 14.0.0
|
||||||
|
CPU: Apple M1 (0 MHz, 8 cores)
|
||||||
|
Memory: 16.0 GB
|
||||||
|
User: username
|
||||||
|
Resolution: 1:2560x1600
|
||||||
|
Executable: /path/to/ghost
|
||||||
|
Start Time: 2024-04-29 12:00:00
|
||||||
|
Initializing handlers...
|
||||||
|
Screen handler initialized: 2560x1600
|
||||||
|
Input handler initialized
|
||||||
|
=== Phase 1 Status ===
|
||||||
|
Screen Capture: READY
|
||||||
|
Input Control: READY
|
||||||
|
Network: STUB (Phase 2)
|
||||||
|
======================
|
||||||
|
Starting main loop (Ctrl+C to exit)...
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 常见问题
|
||||||
|
|
||||||
|
### 9.1 编译问题
|
||||||
|
|
||||||
|
| 问题 | 原因 | 解决方案 |
|
||||||
|
|-----|------|---------|
|
||||||
|
| 找不到 Foundation.h | 缺少 Xcode CLT | `xcode-select --install` |
|
||||||
|
| CMake 找不到 | 未安装 CMake | `brew install cmake` |
|
||||||
|
| 架构不匹配 | Universal Binary 问题 | 检查 CMAKE_OSX_ARCHITECTURES |
|
||||||
|
|
||||||
|
### 9.2 运行时问题
|
||||||
|
|
||||||
|
| 问题 | 原因 | 解决方案 |
|
||||||
|
|-----|------|---------|
|
||||||
|
| 程序无法打开 | 未签名 | `xattr -d com.apple.quarantine ghost` |
|
||||||
|
| Screen Capture: NEED PERMISSION | 无录屏权限 | 系统偏好设置授权 |
|
||||||
|
| Input Control: NEED PERMISSION | 无辅助功能权限 | 系统偏好设置授权 |
|
||||||
|
|
||||||
|
### 9.3 权限重置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 如果权限状态混乱，可重置
|
||||||
|
tccutil reset ScreenCapture
|
||||||
|
tccutil reset Accessibility
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 代码保护机制（待实现）
|
||||||
|
|
||||||
|
### 10.1 保护策略
|
||||||
|
|
||||||
|
核心思路：客户端内嵌服务端公钥，连接时验证服务端身份。
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────┐ ┌─────────────────────┐
|
||||||
|
│ macOS Client │ │ Your Server │
|
||||||
|
│ │ 1. 挑战请求 │ │
|
||||||
|
│ ┌─────────────────┐ │ ─────────────────▶ │ ┌─────────────────┐ │
|
||||||
|
│ │ libYamaCore.a │ │ │ │ 服务端私钥 │ │
|
||||||
|
│ │ (闭源) │ │ ◀───────────────── │ │ │ │
|
||||||
|
│ │ 内嵌服务端公钥 │ │ 2. 签名响应 │ └─────────────────┘ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ │ 验证签名 ─────▶ 匹配 ──▶ 正常工作 │
|
||||||
|
│ │ ─────▶ 不匹配 ──▶ 拒绝连接 │
|
||||||
|
│ └─────────────────┘ │ │ │
|
||||||
|
└─────────────────────┘ └─────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10.2 实施步骤
|
||||||
|
|
||||||
|
1. 生成服务端密钥对
|
||||||
|
2. 服务端添加签名逻辑
|
||||||
|
3. 创建闭源库 libYamaCore
|
||||||
|
4. 嵌入公钥编译
|
||||||
|
5. 客户端集成验证
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 参考资料
|
||||||
|
|
||||||
|
### 11.1 官方文档
|
||||||
|
|
||||||
|
- [CGDisplayCreateImage](https://developer.apple.com/documentation/coregraphics/1454434-cgdisplaycreateimage)
|
||||||
|
- [CGEvent Reference](https://developer.apple.com/documentation/coregraphics/cgevent)
|
||||||
|
- [Carbon Events.h](https://developer.apple.com/documentation/carbon/events_h)
|
||||||
|
- [Accessibility API](https://developer.apple.com/documentation/applicationservices/axuielement_h)
|
||||||
|
|
||||||
|
### 11.2 开源项目参考
|
||||||
|
|
||||||
|
- [RustDesk macOS](https://github.com/rustdesk/rustdesk/tree/master/src/platform/macos)
|
||||||
|
- [Sunshine Screen Capture](https://github.com/LizardByte/Sunshine/tree/master/src/platform/macos)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. 修订历史
|
||||||
|
|
||||||
|
| 日期 | 版本 | 修改内容 |
|
||||||
|
|-----|------|---------|
|
||||||
|
| 2026-04-28 | 1.0 | 初始版本（设计文档） |
|
||||||
|
| 2026-04-29 | 1.1 | 更新为实现文档，Phase 1 完成 |
|
||||||
Reference in New Issue
Block a user