Redis ACL SETUSER 怎样限制可访问命令

Redis 的 ACL SETUSER 可以限制用户能执行哪些命令，但“允许命令”不等于“允许所有键”。要把一个应用账号收窄到可用范围，至少要同时配置命令规则和键模式；否则可能出现命令已经放行，却因为键范围不足仍然返回 NOPERM。

官方地址：https://redis.io/docs/latest/commands/acl-setuser/

最稳妥的做法是先用 reset 清空旧规则，再显式写入 on、密码、最小命令集合和键模式。单个命令长期更容易审查；命令分类适合快速建立边界；Redis 7.0 及以上还可以用选择器把不同命令绑定到不同键前缀。

ACL SETUSER 实际限制了哪两层权限

ACL 判断可以拆成两层：第一层判断用户是否有权调用某条命令，第二层判断这条命令访问的键是否匹配允许的模式。+get 只解决第一层，~cache:read:* 主要解决第二层，两者缺一不可。

先用 reset 重建一个只读账号

如果用户以前已经配置过规则，直接追加 +get 并不会自动删除旧权限。下面的写法先恢复默认能力，再重新打开账号、设置密码、允许读取命令，并把键范围限定在 cache:read: 前缀。

# 先清理旧规则，再创建只读用户；密码参数用引号避免被 Shell 特殊解析
redis-cli ACL SETUSER app-reader reset on '>ChangeThisPassword' nocommands +get +mget '~cache:read:*'

# 查看用户的命令、键模式和启用状态；这是配置检查，不会修改 ACL
redis-cli ACL GETUSER app-reader

# 查看当前连接实际认证成哪个用户，避免把规则改在错误账号上
redis-cli ACL WHOAMI

reset 会把用户恢复成关闭、无密码、无命令、无键权限的状态，所以后面必须补上 on 和需要的规则。nocommands 的作用是显式清空命令集合，和 reset 一起使用时，配置意图更清楚，也能避免未来维护者误以为命令是从旧规则继承来的。

这条规则只允许 GET 和 MGET，而且键名要匹配 cache:read:*。因此，用户即使认证成功，也不应该能够调用 SET 或读取 cache:write:1。

单命令和命令分类应该怎么选

需要长期稳定审查的生产账号，优先写单命令。例如只读缓存账号可以明确列出 +get +mget +exists；写入账号再按业务补充 +set、+del 等实际需要的命令。这样做的优点是规则与代码调用关系直接对应，缺点是新增业务命令时需要同步修改 ACL。

# 单命令白名单：只开放读取缓存所需的三个命令
redis-cli ACL SETUSER app-reader reset on '>ChangeThisPassword' nocommands +get +mget +exists '~cache:read:*'

# 分类适合快速建立只读边界；再按部署策略排除不希望开放的命令
redis-cli ACL SETUSER report-reader reset on '>ChangeThisPassword' nocommands +@read '~report:*'

# 查看某个分类实际包含哪些命令；分类内容以当前 Redis 实例为准
redis-cli ACL CAT read

+@read 是按分类授权，不应被理解成“所有模块的所有读取命令”。Redis 官方文档说明，除 +@all 外，普通分类不包含模块命令；因此引入模块或新能力后，仍要按实例的 ACL CAT 结果和应用调用清单复查。若安全边界要求可审计，宁可多写几个单命令，也不要为了省配置把权限扩大到不需要的类别。

Redis 7.0 以上怎样限制子命令

从 Redis 7.0 开始，ACL 可以用竖线区分命令和子命令。例如允许 CONFIG GET，同时拒绝 CONFIG SET，可以把根规则写成：

# 只放行 CONFIG GET 子命令，不把整个 CONFIG 管理面交给应用账号
redis-cli ACL SETUSER config-reader reset on '>ChangeThisPassword' nocommands +config|get '~app:config:*'

# 如果要封锁某个已放开的子命令，Redis 7.0 起可以使用 -command|subcommand
redis-cli ACL SETUSER ops-user -config|set

这里的竖线是 ACL 规则语法的一部分。在 Shell 中直接执行带竖线的参数时，建议把整个规则用单引号包住，否则 Shell 可能把它解释成管道。不要把“允许第一个参数”的旧式写法和子命令选择器混为一谈；官方文档把 first-arg 机制标记为已弃用，而 Redis 7.0 的子命令规则更适合表达明确边界。

同一用户需要两组键范围时用选择器

如果一个账号既要读取公共缓存，又只能写入自己的业务前缀，可以使用 Redis 7.0 引入的 selectors。根权限和每个选择器分别保存一组规则；命令请求只要匹配根权限或任一选择器即可通过，因此每个选择器中的命令和键模式要成对设计。

# 根权限只读公共缓存；选择器只允许写入业务写入前缀
redis-cli ACL SETUSER app-worker reset on '>ChangeThisPassword' nocommands +get +mget '%R~cache:read:*' \
  '(+set +expire %W~cache:write:*)'

# 读取用户的 selectors 与根权限，确认规则是否按预期保存
redis-cli ACL GETUSER app-worker

如果部署版本还没有 Redis 7.0 的 selector 和读写键权限语法，就退回到单一键模式，或者拆分成两个账号。选择器增加了表达力，也增加了审查成本；只有在同一连接确实需要多组权限时才值得引入。

遇到 NOPERM 时按三个方向排查

NOPERM 说明用户已经认证，但当前 ACL 不允许执行命令或访问键。不要只盯着 +get，可以按下面顺序缩小范围：

1. 确认身份：执行 ACL WHOAMI，确认连接不是仍然使用 default 用户。
2. 确认命令：用 ACL GETUSER username 查看命令规则，必要时用 ACL CAT category 查看分类实际包含的命令。
3. 确认键和子命令：检查键名是否匹配 ~、%R~ 或 %W~，以及调用的是否是被单独封锁的子命令。

# 读取最近的 ACL 拒绝记录；重点看 user、reason 和 object 字段
redis-cli ACL LOG 10

# 用最小测试分别验证命令拒绝和键拒绝；不要在生产键上随意写入
redis-cli --user app-reader --pass 'ChangeThisPassword' GET cache:read:demo
redis-cli --user app-reader --pass 'ChangeThisPassword' SET cache:read:demo value

如果第一条 GET 因键模式不匹配失败，日志通常会把原因指向键；如果第二条 SET 失败，则更可能是命令权限不足。测试命令只应使用专门的测试键，密码也应由安全的凭据注入方式提供，示例中的字符串不能直接作为生产密码。

一份可落地的权限决策表

最后再强调一次：ACL SETUSER 修改已有用户时默认是追加或调整现有规则，不会自动替你“收敛”到最小权限。正式改造时，把 reset、账号状态、认证方式、命令清单、键前缀和回滚方式一起写进变更记录，避免只改了一个 +command 就误以为边界已经完成。

相关问题

• 为什么有 +get 仍然返回 NOPERM？ 因为命令允许和键模式允许是两层检查，键名还必须匹配规则。
• +@read 能代替所有只读命令吗？ 不能直接假设，应该用当前实例的 ACL CAT read 查看，并注意模块命令边界。
• 修改 ACL SETUSER 后旧连接会立刻失效吗？ 用户关闭后，已经认证的连接仍可能继续工作；需要按官方 ACL 管理方式处理存量连接。
• 什么时候不该使用 selector？ 当账号只需要一组稳定的命令和键范围时，单命令加单键模式更容易审查和回滚。