📚 课程目录第4章访问控制列表(ACL)

4. 访问控制列表(ACL)：ACL数据结构与权限模型、ACL编程与调试、ACL导致的操作拒绝故障排查

ACL，全称是Access Control List。说白了，它就是Matter设备里的「门禁系统」。每个设备上有什么权限，谁能操作哪个端点，都由它说了算。我刚开始接触Matter协议时，觉得ACL就是个简单的权限表，后来踩了不少坑才明白——ACL出问题，设备就「装死」，你发什么指令它都给你回个错误。

这一章，我们就来拆解ACL的数据结构、权限模型，以及最常见的故障排查方法。

4.1 ACL数据结构

ACL在Matter中是一个列表，每个条目（Entry）包含几个关键字段。我习惯把它理解成一张「权限通行证」：

字段	类型	说明
Subject	uint64	被授权者的Node ID，或者为`null`表示通配
Subjects	list	Matter 1.1+支持多个Subject
Targets	list	允许访问的端点/集群列表，`null`表示全部
Privilege	enum	权限等级：View、Operate、Manage、Administer
AuthMode	enum	认证模式：Case、Group、Pase

每个字段都有讲究。比如Subject如果设为null，那就意味着「对所有人开放」。我在项目中见过有人把管理员权限的ACL设成通配Subject，结果任何设备都能控制它——这等于把家门钥匙挂在了门口。

注意：ACL条目数量有限制。Matter Core规范规定，每个设备最多支持5条ACL条目。超过这个数，设备会拒绝写入。我曾经遇到一个客户，在开发板上写了6条ACL，结果第6条怎么也写不进去，查了半天才发现是数量超限。

4.2 权限模型

Matter的权限模型分四个等级，从低到高：

View：只读，能看属性、事件，不能写。
Operate：能执行命令、写部分属性（比如开关灯）。
Manage：能修改配置，比如改Wi-Fi、升级固件。
Administer：最高权限，能管理ACL本身。

你想想看，如果一个设备只给了你View权限，你发个开关命令，它肯定拒绝。这就是最常见的「操作拒绝」原因之一。

另外，权限是向下兼容的。Administer权限的人，自然也能View和Operate。但反过来不行。

4.3 ACL编程与调试

在实际开发中，ACL的读写是通过AccessControl Cluster来操作的。这个Cluster的ID是0x001F，属性ACL的ID是0x0000。

下面是一个用C++读取ACL的示例：

// 读取ACL列表
chip::app::AttributePathParams attributePath(
    chip::app::Clusters::AccessControl::Id,
    chip::app::Clusters::AccessControl::Attributes::Acl::Id
);

chip::app::ReadClient readClient(
    exchangeMgr,
    sessionHandle,
    chip::app::ReadClient::Callback(&callback)
);

CHIP_ERROR err = readClient.SendReadRequest(attributePath);
if (err != CHIP_NO_ERROR) {
    ChipLogError(NotSecure, "读取ACL失败: %s", err.AsString());
}

写入ACL时，要特别注意权限检查。只有拥有Administer权限的节点才能修改ACL。我调试时经常遇到这种情况：明明代码逻辑没问题，但写入ACL总是返回CHIP_ERROR_ACCESS_DENIED。后来发现，是当前会话的权限不够。

调试技巧：在Matter的日志中，搜索AccessControl或ACL关键字。很多SDK会打印详细的权限检查过程，比如「Subject 1234 has Operate privilege on endpoint 1」。这能帮你快速定位问题。

4.4 ACL导致的操作拒绝故障排查

操作拒绝（Operation Denied）是ACL问题最常见的表现。设备收到命令后，返回Status::UnsupportedAccess或Status::Busy。嗯，这里要注意，Busy有时候也是ACL引起的，因为权限检查失败后，设备可能进入保护状态。

我总结了一套排查流程，你可以照着做：

确认ACL条目是否存在：用chip-tool读取ACL属性，看看列表是不是空的。
检查Subject是否匹配：当前操作者的Node ID，是否在ACL的Subject列表中？
检查Targets是否覆盖：你要操作的端点（Endpoint）和集群（Cluster），是否在ACL的Targets范围内？
检查Privilege等级：当前操作需要的权限，是否小于等于ACL授予的权限？
检查AuthMode：当前会话的认证模式（Case/Group/Pase），是否与ACL的AuthMode一致？

举个例子。有一次，我用chip-tool给一个灯发送开关命令，结果一直返回UnsupportedAccess。我查了ACL，发现Subject是对的，Targets也覆盖了OnOff Cluster，但Privilege是View。说白了，我只有看的权限，没有操作的权限。改完ACL后，问题就解决了。

  核心原则：ACL的检查是「与」逻辑。Subject、Targets、Privilege、AuthMode四个条件必须全部满足，操作才会被允许。任何一个不匹配，都会导致拒绝。

4.5 ACL故障的常见场景

我整理了几个我在项目中遇到过的典型场景：

场景一：ACL条目被覆盖——OTA升级后，ACL被恢复成出厂默认值，导致之前的授权全部失效。
场景二：Subject写错——Node ID写成了十进制，但设备期望的是十六进制。比如0x1234写成了1234，结果匹配不上。
场景三：Targets遗漏——只授权了Endpoint 1，但操作的是Endpoint 2。
场景四：AuthMode不匹配——ACL要求Case认证，但当前用的是Pase会话。

这些场景，每一个我都亲自排查过。尤其是场景一，那次客户反馈说设备升级后无法控制，我远程抓日志才发现ACL被重置了。从那以后，我建议所有产品在OTA升级后，都要主动检查并恢复ACL配置。

4.6 ACL知识体系图

下面这张图，帮你把ACL的核心逻辑串起来：

这张图把ACL的四个核心字段、权限等级、常见故障和排查流程都串起来了。你可以把它当作排查时的「地图」，遇到问题就按图索骥。

4.7 小结

ACL是Matter安全模型的核心。它不复杂，但容易出错。我个人习惯在开发阶段就写一个ACL检查工具，每次修改ACL后自动验证一遍。这样能省去很多调试时间。