用途
unifi-fleet-operations 把一个 UniFi MCP Server 变成多控制器舰队的管理面。它适合一个环境里存在不止一台 UniFi 控制器、或某个任务必须针对指定控制器执行的场景：服务器持有控制器注册表，将每次工具调用路由到正确的控制器，并记录谁做了什么。
前置条件
舰队模式比单控制器部署多几项要求：
- Postgres：设置
DATABASE_URL。缺失时服务器按单控制器运行，没有舰队工具和注册表。 - Redis：设置
REDIS_URL。缺失时共享读缓存被禁用，会变慢但不会损坏。 - 凭据密钥：设置
UNIFI_CREDENTIAL_KEY。缺失时控制器凭据无法加密存储，服务器拒绝启动。
fleet_* 与注册表类工具仅在设置了 DATABASE_URL 时注册；在单控制器部署中这些工具不存在，点名调用会被拒绝。
调用如何到达控制器
每个绑定控制器的工具都接受可选的 controller 参数。不传时，服务器使用当前选中的控制器，没有选中则使用默认控制器。
# 显式：本次调用发往指定控制器
await client.call_tool("list_sites", {"controller": "edge-paris"})
# 隐式：选中的控制器，否则默认控制器
await client.call_tool("list_sites", {})
为后续调用选择控制器：
await client.call_tool("select_controller", {"name": "edge-paris"})
select_controller 只在当前会话内生效。在无状态 HTTP 模式（MCP_STATELESS_HTTP=true）下它会被拒绝，因为没有会话保存选择；该模式下应在每次调用时传入 controller。
查询工具
list_controllers：注册表中包含哪些控制器及其标签。get_active_controller：不传controller的调用会到达哪台控制器。fleet_health：逐控制器健康状态、能力、Network 11 的 USG 门控信号以及快照年龄。fleet_sites：每台控制器持有哪些站点。fleet_inventory：全舰队设备清单，含固件与状态。fleet_compare_versions：按型号比较各控制器的固件版本，并标记落后。fleet_compare_sites：跨控制器比较站点短名称，区分共有与独有。fleet_fanout：在一组有界控制器上运行同一个读工具。
fleet_health 是快照而非实时读取：它回答 worker 上次检查的结果，不联系控制器，因此开销低、可安全地对整个舰队调用。快照过期意味着缺少证据，而不是控制器健康；工具会报告快照年龄，下结论前先读它。
Network 11 / UniFi OS 6 兼容信号
当同步的设备清单中在任何位置发现 USG 网关时，控制器会带 platform_compat.network_11_capable: false，因为 USG 支持止于 Network 10.6，该站点没有 Network 11 目标。platform_compat 缺失应理解为“未发现 USG 门控信号”，绝不能当作“该控制器可运行 Network 11”的肯定结论：云控制器（从未清点）、worker 尚未同步的本地控制器、确实没有 USG 的站点三者表现相同，都没有 platform_compat 字段。
另一项平台断裂——经典自托管 Network Application Server——没有自动信号：集成 API 的 /v1/info 只返回 applicationVersion，没有主机类型字段。若已知某控制器运行在经典服务器上，应依据其他证据（运维人员说明、已设置的标签）说明，不要从 fleet_health 推断，也不要臆造该舰队尚未使用的标签约定。完整矩阵见 docs/NETWORK_11_COMPATIBILITY.md。
fleet_fanout 的边界
fleet_fanout 会在多台控制器上实时运行读工具，属于昂贵调用且有约束：目标工具必须是读层级工具，写层级工具或其他 fleet 工具会被拒绝；控制器列表必须显式给出，不要为追一个细节而对整舰队扇出；扇出有自身的并发与截止时间限制。应先看 fleet_health，仅当快照无法回答问题时才使用 fleet_fanout，并说明联系了哪些控制器及原因。
跨舰队阅读顺序
面对一般性问题，建议顺序为：list_controllers 确定范围；fleet_health 查看在线、降级与过期情况；fleet_sites 了解站点分布；聚焦设备时用 fleet_inventory 查看设备状态与固件。仅覆盖部分控制器时必须明确说明——二十台中的三台只是部分摘要。
角色与作用域
舰队服务器签发自己的令牌，每个令牌带角色与可选过滤器：
- viewer：仅读工具。
- operator：读与写工具。
- admin：读、写与破坏性工具。
- fleet-admin：全部，包括注册表与令牌工具。
过滤器包括 allow_modules（仅可达匹配模块的工具）、deny_modules（拒绝匹配模块的工具）、controller_labels（仅可达带有全部所列标签的控制器）。对超出调用者标签范围的控制器发起调用会以权限错误拒绝，且拒绝会被审计；调用者无法通过点名访问未获授权的控制器。
管理注册表
以下为 fleet-admin 工具，修改的是注册表而非控制器：register_controller（注册控制器及其凭据）、update_controller（修改设置或标签）、register_cloud_account（为舰队注册云账户）、rotate_fleet_credentials（替换已存储的控制器凭据）、list_api_tokens、create_api_token（签发带角色与过滤器的令牌）、revoke_api_token、update_api_token_role（修改已签发令牌的角色或过滤器）、export_audit_log、search_audit_log、verify_audit_chain（校验审计哈希链）。
注册控制器时凭据以 UNIFI_CREDENTIAL_KEY 为密钥加密存储；设置了 DATABASE_URL 而缺少该密钥时服务器拒绝启动。更换密钥会使所有已存凭据不可读，应视为需要重新录入凭据的轮换。切勿在提示词、报告或日志行中传递控制器的 API 密钥；注册表工具把凭据作为参数接收，那是它唯一该出现的地方。
常见故障
fleet_*工具缺失：未设置DATABASE_URL，舰队模式关闭。select_controller被拒绝：处于无状态 HTTP 模式，应逐次传controller。- 控制器不可达：控制台宕机或网络路径错误，用
fleet_health查看状态并从服务器主机排查。 - 快照过期：worker 近期未检查，检查 worker 健康，或用
fleet_fanout获取实时结果。 - 控制器提示权限拒绝：调用者标签不匹配，作用域按配置生效。
- 凭据解密失败：
UNIFI_CREDENTIAL_KEY已变更，需重新录入该控制器凭据。 - 扇出被拒绝：目标工具为写层级或本身是 fleet 工具；应使用读工具，
fleet_fanout不能对自身扇出。
安全注意事项
fleet_fanout 同时在多台控制器上运行，错误参数会在列表内每台控制器上同样出错。修改或轮换控制器凭据不能靠换回旧凭据恢复，且在客户端重新认证前会切断其对控制器的访问。撤销令牌会切断所有使用该令牌的客户端，包括你正在与之通信的那一个。检查优先使用 fleet_health 与快照类工具，仅在快照无法回答时使用 fleet_fanout。通过该接口做任何变更前，请先阅读 unifi-safe-changes。