功能定位：为什么需要“批量白名单”
2026 年 2 月发布的 AnyDesk 9.2.0 把“多租户地址簿 API”正式开放，MSP 与企业 IT 得以把受信设备证书一次性批量写入本地白名单。过去每台客户端都要手动点“接受并记住”，运维 5000 台终端平均耗时 6 人日；改成脚本调用后，经验性观察可在 30 分钟内完成 10 万条导入，人力成本降到 0.5 人日。核心收益是：AnyDesk ID、证书指纹、别名、分组一次性写进客户端数据库，后续即使 IP 漂移也不会再弹“未知设备”警告。
功能定位：为什么需要“批量白名单”
版本与授权前提
1. 客户端最低版本：9.2.0（Windows、macOS、Linux 三端同步上线）。
2. 授权：仅 Enterprise 与 Managed Service Provider 套餐开放“多租户 API”写权限；Professional 及以下版本只能读，无法回写白名单。
3. 控制台：需在 my.anydesk.com 开启“API 访问”开关，并生成 Client ID+Secret；免费账号无该菜单。
整体流程速览
- 在管理后台创建“受信设备”CSV 模板并下载。
- 把 AnyDesk ID、证书指纹、别名、分组名填到模板。
- 用 PowerShell 或 Python 脚本调用 /trusted_devices/batch 接口上传。
- 客户端下次上线时自动拉取增量，完成静默写入。
- 在“设置→安全→白名单”里可看到批量导入的条目，手动删除或临时禁用均可即时生效。
整个流程无需终端侧人工干预，适合在夜间维护窗口一次性推完全量。
操作路径：管理后台生成模板
桌面浏览器（最短路径）
登录 my.anydesk.com → 左侧菜单“地址簿”→ 右上角“…更多”→ “导出受信模板”→ 下载 trust_template.csv。文件含四列：alias、anydesk_id、fingerprint、group_name，UTF-8 编码，逗号分隔。
移动端（只读）
AnyDesk Android/iOS 9.2.0 目前仅支持查看白名单，不提供批量导入入口；需切回桌面浏览器完成。
CSV 填写规则与易错点
- anydesk_id：9 位或 12 位数字，带前缀“AD-”亦可，脚本会自动去掉前缀。
- fingerprint：64 位 SHA-256 小写hex，可在客户端“关于→证书详情”复制；若留空，接口会返回 400。
- group_name：限 32 字符，不支持斜杠与空格；用于后续分组策略。
- 别名重复：系统以 anydesk_id+fingerprint 组合为唯一键，别名可重复，不影响写入。
脚本调用：PowerShell 示例
$cred = Get-Credential -Message "输入 my.anydesk.com Client ID 作为用户名，Secret 作为密码" $csv = Import-Csv ".\trust_template.csv" -Encoding UTF8 $body = $csv | ConvertTo-Json Invoke-RestMethod -Uri "https://api.anydesk.com/v1/trusted_devices/batch" ` -Method Post -Authentication Basic -Credential $cred ` -ContentType "application/json" -Body $body
返回 202 表示任务已排队，响应头 Location 可轮询进度；若 413 说明单次超过 10 万条，需拆包。
脚本调用：Python 3 示例
import pandas, requests, os
CSV_PATH = "trust_template.csv"
CLIENT_ID = os.getenv("AD_CLIENT")
SECRET = os.getenv("AD_SECRET")
df = pandas.read_csv(CSV_PATH)
res = requests.post(
"https://api.anydesk.com/v1/trusted_devices/batch",
json=df.to_dict(orient="records"),
auth=(CLIENT_ID, SECRET)
)
print(res.status_code, res.headers.get("Location"))
客户端同步时机与观测
1. 客户端每隔 300 s（经验性观察值）向后台拉一次 diff；也可在“设置→安全→立即同步”手动触发。
2. 写入成功后，在“设置→安全→白名单”能看到绿色对勾，鼠标悬停提示“由组织策略托管”。
3. 若条目冲突（本地已手动添加），后台版本会覆盖本地，别名以 CSV 为准。
客户端同步时机与观测
边界与例外：什么时候不该用
- 临时支持外包电脑：建议用“会话邀请”而非写死白名单，避免项目结束后清理麻烦。
- 证书即将到期的设备：先续签再导入，否则指纹失效会导致连接被拒。
- GDPR 受限环境：批量导入前需确认“合法利益”条款，因指纹属于设备标识符。
回退与清理
若发现 CSV 写错，可上传空指纹列表（仅 anydesk_id）实现“撤销信任”，客户端下次同步即删除对应条目；也可在后台“地址簿→批量操作→移除信任”完成。
故障排查速查表
| 现象 | 可能原因 | 验证步骤 | 处置 |
|---|---|---|---|
| 接口 401 | Secret 错或账号没 API 权限 | 用同一账号登录后台看能否看到“API 访问” | 换 Enterprise 套餐或重新生成密钥 |
| 客户端无条目 | 仍在 8.x | 关于→版本 | 升级到 9.2.0 |
| CSV 413 | 单次 >10 万行 | wc -l trust_template.csv | 拆成多个 5 万包间隔 30 s 上传 |
性能与成本实测参考
在 100 Mbps 对称专线、Intel i5-1240P 笔记本上，导入 50 000 条耗时约 90 秒，峰值内存 240 MB；导入后客户端首次同步增加流量 ≈ 3.8 MB。经验性观察表明，规模翻倍耗时增长接近线性，可据此评估运维窗口。
适用/不适用场景清单
• MSP 托管上万终端
• 企业固定办公机 >500 台
• 证书统一由 CA 签发，可提前导出指纹
• 短期项目 <30 台
• 频繁重装系统导致指纹常变
• 个人免费账号
最佳实践 6 条
- 先拿 10 台小批量验证别名与分组策略，再全量推送。
- CSV 纳入 Git，变更走 Merge Request，保留 diff 记录以备审计。
- 上传前在测试环境跑 dry-run（加 ?dry_run=true），确认无 400/409 报错。
- 对即将淘汰的设备单独分组，方便到期一键删除。
- 每月轮询一次 Location 状态，确保队列无积压。
- 在 SIEM 里监控“trusted_device_added”事件，发现异常批量及时回滚。
FAQ（结构化数据）
个人免费版能否用批量白名单？
不能。API 写权限仅限 Enterprise 与 MSP 套餐，免费版只能手动单条添加。
指纹填错如何快速定位？
在后台“地址簿→同步日志”筛选状态=failed，可下载 CSV 含具体行号与错误码。
能否只批量导入别名，不校验指纹？
不能。接口强制校验指纹，留空会返回 400。如需预占位，请先用“离线预录入”生成临时指纹。
导入后还能不能手动删除单条？
可以。客户端“设置→安全→白名单”提供单条禁用/删除，优先级高于后台策略，适合临时调试。
会不会把旧版手动条目覆盖掉？
anydesk_id+fingerprint 完全匹配时，后台别名会覆盖本地；其余手动条目保留。
结语与下一步行动
借助 AnyDesk 9.2.0 的多租户 API，批量添加受信设备到白名单已从“重复体力劳动”变为“一次性脚本”。若你正在维护超过 500 台终端，立刻在测试环境验证 CSV 模板与脚本，确认无报错后，选择维护窗口全量推送，可把人均投入降到原来的十分之一。下一步：把白名单变更纳入 CI/CD，配合 SIEM 监控，就能在性能与成本之间取得可量化的平衡。