mirror of
https://github.com/kunkundi/crossdesk.git
synced 2026-11-07 06:39:10 +08:00
[fix] preserve macOS permissions and defer legacy migration to launch
This commit is contained in:
dijunkun
+6
-2
@@ -59,7 +59,11 @@ xmake r crossdesk
|
||||
./apps/desktop/scripts/macos/pkg_x64.sh 1.4.3
|
||||
```
|
||||
|
||||
打包脚本会生成包含 Slint 运行库的 `.app` 和 `.pkg`。屏幕录制、辅助功能授权与应用路径及签名有关；测试被控能力时请使用固定路径下的应用包。
|
||||
打包脚本会生成包含 Slint 运行库的 `.app` 和 `.pkg`。正式版本持续使用同一团队的 Developer ID 签名、相同 Bundle ID 及兼容的签名要求时，正常升级通常可以沿用录屏、辅助功能等授权。测试被控能力时请使用固定路径下的应用包。
|
||||
|
||||
Developer ID 安装包通过 `preinstall` 检查覆盖前的旧应用。检测到未签名或 ad-hoc 的 CrossDesk 时，原子保存迁移标记到目标卷的 `/Library/Application Support/CrossDesk/permission-migration.json`。安装完成后退出旧版并启动新版，正式签名的新版会在后台按当前用户分别迁移辅助功能与录屏授权。迁移标记支持离线卷安装和稍后登录的其他用户。
|
||||
|
||||
每项权限的处理进度保存在当前用户的 `~/Library/Application Support/CrossDesk/PermissionMigration/progress.json`。已处理或已有效授权的项目会跳过，失败或中断的项目可在“设置 → 系统权限”中点击“重试权限迁移”。迁移处理中及失败时均可选择“稍后”，受影响的被控功能在获得授权后启用。安装器记录迁移状态失败时会写入安装日志并继续安装。已完成安装后遗留的异常授权、更换证书签名身份等情况，参照 [macOS 权限排查](FAQ.md#macos-有连接但黑屏或无法操作键鼠)。
|
||||
|
||||
### Developer ID 签名与公证
|
||||
|
||||
@@ -120,7 +124,7 @@ base64 -i "$HOME/Downloads/crossdesk-installer.p12" | pbcopy
|
||||
|
||||
配置后先手动运行工作流：填写 `desktop_version`，勾选 `sign_macos`，确认 ARM64、Intel 的 `Notarize and staple macOS installer` 步骤均成功，再推送发布标签。需要先将工作流和配套脚本提交、推送到 GitHub，新的开关和步骤才会生效。
|
||||
|
||||
CI 最多等待公证 60 分钟；若 Apple 仍在处理，任务失败并阻止发布，但会保留 `macos-pending-notarization-*` 安装包及 `macos-notarization-*` JSON 诊断产物 14 天。下载产物后，按上一节用已保存的提交 ID 查询并附加票据，无需重复上传同一个包。不要将 pending 产物当作已经完成公证的发布包。自动签名流程不改变安装器当前的权限重置逻辑；辅助功能授权是否保留还需单独调整安装脚本。
|
||||
CI 最多等待公证 60 分钟；若 Apple 仍在处理，任务失败并阻止发布，但会保留 `macos-pending-notarization-*` 安装包及 `macos-notarization-*` JSON 诊断产物 14 天。下载产物后，按上一节用已保存的提交 ID 查询并附加票据，无需重复上传同一个包。不要将 pending 产物当作已经完成公证的发布包。
|
||||
|
||||
## Linux
|
||||
|
||||
|
||||
+6
-2
@@ -56,7 +56,11 @@ The current CI sets macOS 14.0 as the minimum target for both Intel and Apple Si
|
||||
./apps/desktop/scripts/macos/pkg_x64.sh 1.4.3
|
||||
```
|
||||
|
||||
The scripts create an `.app` and `.pkg` containing the Slint runtime. Screen Recording and Accessibility grants depend on the app path and signature; use a consistent application bundle when testing host functionality.
|
||||
The scripts create an `.app` and `.pkg` containing the Slint runtime. Release updates can normally retain Screen Recording, Accessibility and other grants when they use Developer ID signing from the same team, the same bundle ID and compatible code signing requirements. Use a consistent application path when testing host functionality.
|
||||
|
||||
Developer ID installers inspect the old app in `preinstall`. For unsigned or ad-hoc builds, they atomically record a migration marker at `/Library/Application Support/CrossDesk/permission-migration.json` on the target volume. After installation, quit the old app and launch the new version. The Developer ID app migrates Accessibility and Screen Recording in the background for the current user. The marker also supports offline target volumes and users who log in later.
|
||||
|
||||
Per-service progress is stored in `~/Library/Application Support/CrossDesk/PermissionMigration/progress.json` for each user. Completed services and valid grants are preserved. Failed or interrupted services can be retried from **Settings → System permissions → Retry migration**. Choose **Later** to continue using the app while migration is running or needs attention. Affected host features become available after authorization. Failure to record the installer marker is logged and installation continues. For stale grants from earlier installations or changes between certificate signing identities, see [macOS permission repair](FAQ.md#repair-macos-permissions).
|
||||
|
||||
### Developer ID signing and notarization
|
||||
|
||||
@@ -117,7 +121,7 @@ Your local `crossdesk-notary` profile does not synchronize to GitHub runners. Th
|
||||
|
||||
After committing and pushing the workflow and supporting scripts, first run it manually with `desktop_version` set and `sign_macos` enabled. Confirm that `Notarize and staple macOS installer` succeeds for both ARM64 and Intel before pushing a release tag.
|
||||
|
||||
CI waits up to 60 minutes for notarization. If Apple is still processing, the job fails and blocks publication, while preserving `macos-pending-notarization-*` installer artifacts and `macos-notarization-*` JSON diagnostics for 14 days. Download them and use the saved submission ID as described above to resume checking and staple the package without uploading it again. Pending artifacts are not completed notarized releases. CI signing does not change the installer's existing permission-reset behavior; preserving Accessibility grants requires a separate installer change.
|
||||
CI waits up to 60 minutes for notarization. If Apple is still processing, the job fails and blocks publication, while preserving `macos-pending-notarization-*` installer artifacts and `macos-notarization-*` JSON diagnostics for 14 days. Download them and use the saved submission ID as described above to resume checking and staple the package without uploading it again. Pending artifacts are not completed notarized releases.
|
||||
|
||||
## Linux
|
||||
|
||||
|
||||
+33
-1
@@ -20,6 +20,21 @@
|
||||
|
||||
在“系统设置 → 隐私与安全性”中检查 CrossDesk 的屏幕录制与辅助功能权限。更换应用位置或签名、更新开发构建后，可能需要重新授权并重启应用。
|
||||
|
||||
同一团队正式签名且应用标识与签名要求兼容的版本，正常升级通常可以沿用权限。从未签名或 ad-hoc 旧版升级后，退出旧版并启动新版，新版会在后台处理当前用户的辅助功能和录屏权限迁移，再引导重新授权。每项权限的完成状态会单独保存。
|
||||
|
||||
迁移失败或中断时，打开“设置 → 系统权限”，点击“重试权限迁移”。也可选择“稍后”继续使用客户端，受影响的被控功能在授权后启用。若系统设置仍显示已授权但功能异常，彻底退出 CrossDesk，在对应权限列表中移除旧条目后重新添加 `/Applications/CrossDesk.app`，再启动应用。
|
||||
|
||||
问题仍存在时，再次退出 CrossDesk，在当前登录用户的终端中仅执行与故障对应的一条命令，重置 CrossDesk 的该项授权。
|
||||
|
||||
```bash
|
||||
# 录屏权限异常
|
||||
tccutil reset ScreenCapture cn.crossdesk.app
|
||||
# 辅助功能权限异常
|
||||
tccutil reset Accessibility cn.crossdesk.app
|
||||
```
|
||||
|
||||
执行后重新启动 CrossDesk，按提示在系统设置中授权。仍有旧路径或旧版本条目时，可在对应权限列表中移除旧条目后重新添加当前应用。
|
||||
|
||||
## Linux Wayland 无法捕获画面
|
||||
|
||||
Wayland 画面捕获依赖启用了 Wayland 支持的构建、宿主系统 PipeWire 0.3 和桌面门户授权；无法捕获时也可在 X11 会话中对比验证。构建选项见 [Linux 构建说明](BUILD.md#linux)。
|
||||
@@ -98,7 +113,7 @@ Windows 安装包和便携包内置了 Amyuni 的 `usbmmidd_v2` 虚拟显示器
|
||||
| Server disconnected / TLS error | Network access, signaling endpoint, certificate dates, hostname, and system trust. See [self-hosting](SELF_HOSTING_EN.md). |
|
||||
| Remote device offline | Keep the host running, connect both sides to the same signaling server, and copy its current ID again. |
|
||||
| P2P connection failed | The default connection policy already allows TURN relay fallback. Enable Force Relay in Settings, save, and reconnect to troubleshoot direct connections. For self-hosting, check Coturn and relay/media firewall ports. Review [release compatibility notes](https://github.com/kunkundi/crossdesk/releases). |
|
||||
| Black screen / no input on macOS | Grant Screen Recording and Accessibility, then reopen the app. A changed app path or signature may require fresh permission grants. |
|
||||
| Black screen / no input on macOS | Grant Screen Recording and Accessibility, then reopen the app. Release updates with compatible signing identities normally retain permissions. For migration or stale grants, see [macOS permission repair](#repair-macos-permissions). |
|
||||
| No capture on Linux Wayland | Check the Wayland build option, host PipeWire 0.3, and desktop portal permission. Compare with an X11 session. See [Linux build instructions](BUILD_EN.md#linux). |
|
||||
| Linux host has no monitor or graphical session | Start CrossDesk normally to automatically discover and select your existing desktop, preserving its Dock and apps; no display number is needed. A bare Xvfb shows only CrossDesk on a black background; use an existing session or install Xfce and specify `--headless-session startxfce4`. See [Linux headless operation](HEADLESS_EN.md). |
|
||||
| Cannot control a Windows lock screen | Install/start CrossDesk Service and keep the host client running. See [service commands](../README_EN.md#windows-service). |
|
||||
@@ -112,4 +127,21 @@ Windows 安装包和便携包内置了 Amyuni 的 `usbmmidd_v2` 虚拟显示器
|
||||
| Windows build without CUDA | Build with `--USE_CUDA=false`, or follow the [CUDA build instructions](BUILD_EN.md). Use `$env:CUDA_PATH` in PowerShell. |
|
||||
| iOS artifact cannot be installed directly | CI exports an unsigned app. Sign it yourself or build and run from Xcode on a physical device. See [iOS requirements](../apps/ios/README.md). |
|
||||
|
||||
### Repair macOS permissions
|
||||
|
||||
Release upgrades with compatible signing identities normally retain permissions. After upgrading an unsigned or ad-hoc build, quit the old app and launch the new version. It migrates Accessibility and Screen Recording in the background for the current user, then guides you through authorization. Completion is saved separately for each permission.
|
||||
|
||||
For failed or interrupted migrations, open **Settings → System permissions** and choose **Retry migration**. Choose **Later** to continue using the client. Affected host features become available after authorization. If access appears enabled while capture or input still fails, quit CrossDesk, remove the old entry from the affected privacy list, add `/Applications/CrossDesk.app` again, and reopen the app.
|
||||
|
||||
If the issue persists, quit CrossDesk and run only the command for the affected permission in the logged-in user's terminal.
|
||||
|
||||
```bash
|
||||
# Screen Recording permission issue
|
||||
tccutil reset ScreenCapture cn.crossdesk.app
|
||||
# Accessibility permission issue
|
||||
tccutil reset Accessibility cn.crossdesk.app
|
||||
```
|
||||
|
||||
Reopen CrossDesk and grant the requested permission in System Settings. If entries for older paths or builds remain, remove the old entry from the affected permission list and add the current app again.
|
||||
|
||||
If the issue persists, [open an issue](https://github.com/kunkundi/crossdesk/issues) with both OS versions, client versions, connection mode, and reproduction steps. Remove passwords and private device information from logs or screenshots before sharing them.
|
||||
|
||||
Reference in New Issue
Block a user