企业官网建设流程全解析

• 后端
• 前端
• 企业应用
• 运维
• 网络安全

更换一台 Mac，最难的不是买新机，而是如何把用户的数据搬到新机器上——过去这要么被 IT 一刀切禁止，要么完全交给用户在迁移界面里自行勾选。macOS 26.4 引入的Managed Migration Assistant（受管迁移助手）改变了这一局面：它让 MDM 在 ADE 自动注册（Automated Device Enrollment）过程中，用一份声明式配置（declaration）精确指定用户的 Home 目录里哪些内容随迁移传往新机。Fleet 完整支持其所需的await_device_configured键，能在 Setup Assistant 的正确时机下发配置，并通过声明式状态通道（declarative status channel）在迁移期间和迁移结束后提供全程可见性。读完本文，你将掌握在 Fleet 中通过 GitOps 与 Fleet UI 两种方式配置 Managed Migration Assistant 的完整方法、路径作用域与排除规则、以及标准用户认证的解决方案。

为什么受管迁移能让 Fleet 的 MDM 保持正常

Migration Assistant（传统迁移助手）对受管 Mac 一直有一个隐藏风险：当用户按标准流程迁移并保留Other Files & Folders选项时，macOS 会把旧 Mac 的 MDM 注册状态一并复制到新机器上。结果是新 Mac 带着旧设备的配置描述文件和一个没有有效身份的陈旧注册（stale enrollment）。此时 fleetd 仍在正常签到、osquery 也在工作，主机看起来一切正常，但 MDM 已经坏了：命令挂起，或落到错误的设备上。

Managed Migration Assistant 恰好补上了这个缺口。传输的内容由你部署的声明（declaration）界定：用户数据，加上你选择包含的若干设置（详见下文"传输什么、不传输什么"）。这些数据落到 Setup Assistant 期间创建的账户中。旧 Mac 的管理状态则留在原地，新 Mac 保留自己独立的 ADE 注册，Fleet 的 MDM 身份不被破坏。部署下文描述的描述文件后，用户可以把数据带过来，既不会弄坏 fleetd 或 MDM，也不必依赖任何人记得取消勾选某个选项框。

前置要求

部署之前请逐一核对：

• 源 Mac（旧机）必须运行 macOS 15 或更高版本。
• 目标 Mac（新机）必须运行 macOS 26.4 或更高版本。
• 目标 Mac必须在 Apple School Manager 或 Apple Business Manager 中注册，并通过 Automated Device Enrollment（ADE）完成注册。该配置要求设备处于受监管（supervision）状态，不支持其他注册方式。
• 两台 Mac 都需要网络连接。Migration Assistant 在可用时优先使用点对点 Wi-Fi，并在整个传输过程中持续探测是否有更快的通道；它也支持基础网络 Wi-Fi、以太网和 Thunderbolt。

源 Mac 不需要任何 MDM 配置，也无需预先向它部署任何内容。

传输什么、不传输什么

Managed Migration Assistant 作用范围限定在用户的 Home 目录内。它可以传输：

• Home 目录下的可见文件夹
• 隐藏文件夹与文件（.ssh、.bash_history等）
• Home 目录内的文件夹别名与符号链接（指向 Home 目录之外的原始对象不会传输）
• 隐私与安全设置

以下内容不可迁移：

• 应用程序（/Applications）
• /Users/Shared/下的文件与文件夹
• Home 目录内的文件级别名与符号链接
• 打印机与服务
• 其他系统设置

注意上面两处"别名与符号链接"的差异是有意为之：Apple 传输文件夹级别名和符号链接，但不传输文件级的。如果符号链接指向的是文件而非文件夹，它就不会被移动。

~/Library文件夹始终会传输，无法排除。请把应用、安全工具和系统配置的部署交给 Fleet 单独处理：迁移负责用户文件，其余一切都由 Fleet 负责。

在 Fleet 中配置 Managed Migration Assistant

声明类型为com.apple.configuration.migration-assistant.settings。无论使用 GitOps 还是 Fleet UI，声明文件本身完全一致。以下是一个可直接起步的示例：

{ "Type": "com.apple.configuration.migration-assistant.settings", "Identifier": "com.example.migration-assistant", "Payload": { "ShouldDoManagedMigration": true, "ShouldMigrateSecurityPrivacySettings": true, "RequiredPaths": [ "Desktop/", "Documents/" ], "ExcludedPaths": [ "Downloads/", ".Trash/" ] } }

ShouldDoManagedMigration和ShouldMigrateSecurityPrivacySettings同时为true是让迁移对受管 Mac 安全的基础配置，两者必须同时出现。RequiredPaths与ExcludedPaths是可选项，只影响哪些文件夹会被移动。只含两个布尔键的描述文件就是一份有效且完整的配置。

自定义路径之前，有几点需要了解：

• 路径相对于用户的 Home 目录。要包含~/Documents/Work/，就写Documents/Work/。
• 文件夹路径必须以斜杠（/）结尾。
• RequiredPaths与ExcludedPaths可以组合使用：要求Documents/同时排除Documents/Archive/是合法的。
• RequiredPaths中的顺序有含义。当目标 Mac 存储空间不足时，传输优先级按照你列出的顺序执行。
• 两个数组都支持隐藏路径。要排除.Trash，写.Trash/即可。

用户账户创建后，Managed Migration Assistant 会向用户展示传输界面。必选路径（RequiredPaths）会预先选中且不可取消勾选；被排除的路径（ExcludedPaths）则完全不会出现。

还有一个来自 Apple 的限制：当该功能启用时，Setup Assistant 中的Restore（恢复）窗格无法隐藏，Restore跳过键（skip key）在这里不生效。

将描述文件作用域限定到 macOS 26.4 及以上

com.apple.configuration.migration-assistant.settings声明类型只在 macOS 26.4 及更高版本上存在。如果 Fleet 把它下发到更老的 Mac，描述文件会失败，主机的 OS 设置中会显示：

Error.UnknownDeclarationType: Unknown Declaration Type map[UnknownDeclarationType:com.apple.configuration.migration-assistant.settings]

请把描述文件作用域限定到一个动态标签（dynamic label），确保只有符合条件的宿主机才会收到它。在 Fleet 中，进入Labels，添加一个名为macOS 26.4+之类的动态标签，使用如下查询：

SELECT 1 FROM os_version WHERE major > 26 OR (major = 26 AND minor >= 4);

然后在下发描述文件时将该标签作为目标，见下文两种方式。

GitOps 方式

1. 将声明保存为仓库中的.json文件。
2. 在团队（team）YAML 的controls.macos_settings.custom_settings下引用它，并以标签为作用域：

controls: macos_settings: custom_settings: - path: ./platforms/macos/declaration-profiles/migration-assistant.json labels_include_any: - macOS 26.4+

3. 提交并推送。你的 CI/CD 流水线会运行fleetctl gitops并应用该声明。

labels_include_any是 Fleet GitOps 配置中对声明/描述文件做标签作用域的常用键，类似的作用域语义在 server/fleet/labels.go 等处有对应实现，可结合团队配置一并管理。

Fleet UI 方式

1. 将声明保存为.json文件。
2. 在 Fleet UI 中进入Controls > OS settings > Configuration profiles。
3. 选择要添加描述文件的 fleet（车队）。
4. 选择Add profile并上传你的.json文件。
5. 在Target下选择Include any，并选中macOS 26.4+标签。
6. 选择Save。

Fleet 会将该声明下发给该 fleet 中受监管、通过 ADE 注册且匹配该标签的 macOS 主机。

Fleet 如何保证声明在正确的时机下发

Managed Migration Assistant 能否生效，关键前提是声明必须在用户走到传输步骤之前就位。这依赖 DEP 注册描述文件中的await_device_configured键：它让 Setup Assistant 在设备完成配置（包括接收并应用声明式配置）之前不会向用户释放操作界面。

从源码看，Fleet 在向 Apple 注册 DEP 描述文件时始终把await_device_configured置为true。在 server/mdm/apple/apple_mdm.go 中可以看到明确的注释与赋值逻辑：

// always set await_device_configured to true - it will be released either // automatically by Fleet or manually by the user if // enable_release_device_manually is true. jsonProf.AwaitDeviceConfigured = true

也就是说，Fleet 默认就保证声明类配置（包括迁移声明）会在 Setup Assistant 流程中被及时下发与应用，这正是 Managed Migration Assistant 所要求的交付时机。这也意味着你无需为迁移功能单独调整 DEP 描述文件——Fleet 已替你处理了。

当声明被下发到不支持的旧系统时

如果你没有使用动态标签做作用域限制，声明落到 macOS 26.4 以下的宿主机时，主机会在 DDM 状态上报中返回Error.UnknownDeclarationType。Fleet 的服务端对该错误有专门的识别与处理逻辑：在 server/service/apple_mdm.go 中，isUnknownDeclarationType会检测声明的状态是否为未知类型（Valid == Unknown、Active == false且首条 reason 的 code 为Error.UnknownDeclarationType），从而在主机详情等界面中把这类失败标识为"声明类型未知"而非其他配置错误，便于管理员快速定位原因——这也是上面建议用动态标签限定作用域的另一个理由。对应的 DDM 集成测试在 server/service/integration_mdm_ddm_test.go 中也有覆盖。

处理标准用户认证

源 Mac 上的 Migration Assistant 在传输开始前，要求用户使用本地管理员凭据进行认证。如果你的用户是标准用户（standard user），没有管理员协助他们就无法启动迁移。

如果无法在环境中把用户提升为管理员，可以修改authorizationdb，允许标准用户用自己的凭据认证 Migration Assistant，而不再要求管理员密码。

在迁移开始前，于源 Mac 上执行：

sudo security authorizationdb write com.apple.system-migration.launch-password authenticate-session-owner

这条命令会把管理员认证提示替换为普通用户级认证对话框。

迁移完成后，将其恢复为默认值：

sudo security authorizationdb write com.apple.system-migration.launch-password authenticate-admin-nonshared-password

另一种实践思路是配合即时（just-in-time）特权提升工具，让标准用户短暂获得启动 Migration Assistant 的权限，而不持有长期管理员权限。无论采用哪种方案，都建议在发布策略之前先规划好"标准用户如何临时获得权限"这一环，而不是等第一次换机在登录提示处卡住之后才去补救。

端到端流程

一切配置就绪后，整个流程如下：

1. 用户在源 Mac 上打开 Migration Assistant 并完成认证。
2. 用户给新 Mac 开机，进入 Setup Assistant。
3. 在Transfer Your Data to This Mac窗格，用户选择源 Mac。
4. 新 Mac 通过 ADE 注册到 Fleet。Fleet 下发迁移声明（得益于await_device_configured，此时机被正确锁定）。
5. 用户账户创建后，Managed Migration Assistant 以你配置的路径呈现传输界面。
6. 传输开始。Fleet 通过声明式状态通道（declarative status channel）上报进度。
7. 迁移完成。Fleet 交付一份迁移后的报告（post-transfer report）。

两台 Mac 在传输完成前需要保持在彼此的通信范围内。

这套流程把"换机"从一次不可控的用户操作，变成了可审计、可回滚、可复现的受管事件：迁移期间有状态通道持续上报，迁移结束有含日期、时间、传输数据量以及失败文件清单的报告；同时因为整个策略只是一份小型 JSON 声明，通过 GitOps 版本化管理后，它可以获得同行评审（PR review）、变更历史与一键回滚能力——决定"哪些公司数据会落到每一台新 Mac 上"的策略，理应像其他基础设施一样可审计、可回滚。仓库中的相关示例与配套文章 articles/managed-migration-assistant.md 对上述治理价值有更完整的论述，可一并阅读。

深入阅读

• 本仓库内配套的治理视角文章：articles/managed-migration-assistant.md
• Fleet 的 DEP 注册描述文件实现（await_device_configured固定开启）：server/mdm/apple/apple_mdm.go
• Fleet 对Error.UnknownDeclarationType的识别逻辑：server/service/apple_mdm.go
• 相关 DDM 集成测试：server/service/integration_mdm_ddm_test.go
• DEP 描述文件中await_device_configured字段的定义：server/mdm/nanodep/godep/profile.go

• 后端
• 前端
• 企业应用
• 运维
• 网络安全