Azure Local 离线模式：已知问题（Known Issues）

来源：Release Notes for Disconnected Operations for Azure Local

⚠️ 本文档随官方更新而变。部署前必查最新版。

---

1. 2604 版本已知问题

1.1 Worker Cluster 在 "Deploy Arc Infrastructure Components" 失败（罕见）

症状：air-gapped 环境下 workload 集群部署失败

错误：

New-ArcHciApplianceConfigs failed with error MOC Role StorageContainerContributor is unavailable

修复：在第一台 Azure Local 节点上 elevated PowerShell：

New-MocRole -Name StorageContainerContributor `
        -actionProviders "StorageContainer" `
        -actionOperations "all"

之后用相同方式（portal / ARM）恢复部署。

---

2. 2602 / 2603 版本已知问题

2.1 从 2602 升级到 2604 在 air-gapped 下失败

症状：

Update package 'arca.update.package.2603.1.25553.zip' did not pass validation.
- ManifestSignatureInvalid: File signature on Manifest.xml is invalid or it is not signed.
The package may be tampered with or corrupted.

根因：2602 内置的代码签名证书不认 2603/2604 的更新包签名。

修复步骤：

1. 下载 aka.ms/aldo-fix1/2602-update zip，拷到 seed node

2. 修改并运行：

   targetFolder = 'C:\ALDO\2602' targetFile = Join-Path targetFolder "2602-update.zip" (New-Item -ItemType Directory targetFolder -force) | Out-null

   Expand-Archive targetFile -destinationPath targetFolder
   Import-Module "$applianceConfigBasePath\OperationsModule\Azure.Local.DisconnectedOperations.psd1" -Force

   managementEndpoint = "192.168.200.10" password = ConvertTo-SecureString 'RETRACTED' -AsPlainText -Force
   context = Set-DisconnectedOperationsClientContext ` -ManagementEndpointClientCertificatePath "{env:localappdata}\AzureLocalOpModuleDev\certs\ManagementEndpoint\ManagementEndpointClientAuth.pfx" -ManagementEndpointClientCertificatePassword $password
   -ManagementEndpointIpAddress $managementEndpoint

   recoveryKeys = (Get-ApplianceBitlockerRecoveryKeys).recoverykeyset & "(targetFolder)\ImportCodeSignCertsOffline.ps1" ` -CertsFolder targetFolder `
   -BitLockerRecoveryKeys $recoveryKeys

3. 等 10 分钟

4. 同样 context 里跑：

   Get-ApplianceUpdateHistory

   报错可能仍含 Failed，但 ManifestSignatureInvalid 不再出现 = 修好

5. 继续升级：

   $updateTargetVersion = ""
   Wait-AppliancePreUpdate -TargetVersion $updateTargetVersion
   Start-ApplianceUpdate -TargetVersion $updateTargetVersion -Wait

   总耗时约 3 小时

2.2 Bootstrap 因证书无效失败

症状：

ALDO services failed to come up after 00:45:00 minutes, failing Arc registration.

根因：CRL（Certificate Revocation List）空或配置错误。

修复：先验证 CA 配正确，证书含 CRL endpoint 且节点可达。

替代修复（无法重配 CA 时）：每台 Azure Local 节点跑：

Write-Host "Updating Windows MAE Config for the Bootsrap service"
$basePath = "C:\windows\system32\bootstrap"

Write-Host "Looking for config file under $basePath"
$contentDir = Get-ChildItem -Path $basePath -Filter "content_*" -Directory -ErrorAction SilentlyContinue | Sort-Object Name -Descending | Select-Object -First 1
if (-not $contentDir) {
    Write-Warning "Could not find content_* directory under $basePath"
    return
}
Write-Host "Found content directory: $($contentDir.FullName)"

$ConfigPath = Join-Path $contentDir.FullName "Microsoft.Azure.Edge.Bootstrap.ManagementService\windows.mae.config.json"
if (-not (Test-Path $ConfigPath)) {
    Write-Warning "Config file $ConfigPath not found"
    return
}
Write-Host "Config file found at $ConfigPath"

$configContent = Get-Content -Path $ConfigPath -Raw | ConvertFrom-Json
$configContent.ManagementSettings.CheckCertificateRevocationList = $false
Write-Host "Updated existing CheckCertificateRevocationList property to false"

Stop-Service -Name "BootstrapManagementService" -Force -ErrorAction Stop
Write-Host "BootstrapManagementService stopped successfully"

$configContent | ConvertTo-Json -Depth 10 | Set-Content -Path $ConfigPath -Force
Write-Host "Successfully saved modified config"

Write-Host "Starting BootstrapManagementService..."
Start-Service -Name "BootstrapManagementService"
Write-Host "Waiting 60 seconds for service to fully initialize..."
Start-Sleep -Seconds 60
Write-Host "Successfully started BootstrapManagementService"

⚠️ 跳过 CRL 检查降低安全强度------只用于紧急修复，之后必须恢复 CRL 校验。

2.3 Portal 问题

Policy

症状 ：Azure Policy portal 界面有已知问题。 修复 ：用 Azure CLI 或 Azure PowerShell 替代。

SSH keys

症状 ：portal 创建 Linux VM / AKS 集群时无法生成 SSH key。 修复：用 CLI 生成 SSH key，创建 VM/集群时传入。

2.4 后续集群部署失败 --- HGS 证书不可用

症状 ：管理集群成功部署后，新增 workload 集群失败。 根因 ：workload 节点缺 HGS 证书。 修复 ：从管理集群第一节点复制两份 .pfx 到所有 workload 节点：

C:\Users\Administrator\AppData\Roaming\AzureLocal\AzsVmHostGuardian-IRVM01-encryption.pfx
C:\Users\Administrator\AppData\Roaming\AzureLocal\AzsVmHostGuardian-IRVM01-signing.pfx

2.5 Control plane 部署卡住超时（罕见）

症状 ：8 小时仍未 100% 收敛。 修复：重新部署断开操作 appliance；若 2-3 次 clean redeploy 都失败 → 收集日志 + 开 support ticket。

2.6 证书生成卡住

症状 ：通过 RDP 会话跑证书生成会挂。 修复 ：不要用 RDP，直接在 console / PowerShell Remoting / VNC 操作。

---

3. "官方没明说"的事项

• 文档没说"这些 issue 是否会在 2605 修复"------版本对应关系按官方 release notes 查
• "StorageContainerContributor role" 失败是罕见------但 air-gapped 环境下出现概率上升
• HGS 证书复制是纯手动步骤------易遗漏，建议写成 checklist
• "clean redeploy" 没说"具体 cleanup 步骤"------应参照官方 Cleanup Script（如果存在）
• 文档没说"已知 issue 总数"或"哪些是 blocker"------以官方为准