Authelia storage bans user 命令详解：通过 CLI 管理 regulation 系统中的用户封禁

Authelia storage bans user 命令详解：通过 CLI 管理 regulation 系统中的用户封禁

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia

本文以authelia storage bans user命令的官方参考文档为主线，完整覆盖该命令的定位、子命令树、参数与继承选项，并结合 Authelia 仓库中 storage.go、storage_run.go 等源码实现，深入讲解 list / add / revoke 三个子命令的调用链、输出格式与边界行为，帮助运维人员在 Authelia 中通过命令行查看、创建和撤销用户对登录的封禁。读完后你将能够独立完成用户封禁的增删查操作，并理解封禁记录在存储层与 regulation 防暴力破解机制之间的关系。

一、命令定位：authelia storage bans user 是什么

authelia storage bans user是 Authelia CLI 中authelia storage bans（管理用户与 IP 封禁）命令下的用户封禁分支。根据 官方参考文档，其 Synopsis 描述为：

Manages user bans.

This subcommand allows listing, creating, and revoking user bans from the regulation system.

即该子命令允许管理员从 regulation 系统（防暴力破解封禁体系）中列出、创建和撤销用户封禁。

从源码结构看，该命令在 newStorageBansUserCmd 中定义：它是一个不带RunE的纯父级命令（Args: cobra.NoArgs），本身只负责挂载子命令并展示帮助，实际执行逻辑全部下沉到三个子命令：

authelia storage └── bans # Manages user and ip bans ├── user # Manages user bans（本文主题） │ ├── list # Lists user bans │ ├── add <user> # Adds user bans │ └── revoke [user] # Revokes user bans └── ip # Manages ip bans（与 user 平行的结构）

这一层级与参考文档中的 SEE ALSO 一致：上级是 authelia storage bans，兄弟命令为 authelia storage bans ip，子命令文档分别为 add、list、revoke。ip分支与user分支共用同一套 list/revoke/add 构造逻辑（use参数为user或ip），因此理解 user 分支即可同时理解 ip 分支的行为。

二、命令参考：原文档要素完整继承

Synopsis

authelia storage bans user --help

Options（本命令自身选项）

-h, --help help for user

Options inherited from parent commands（从父命令继承的选项）

以下全局选项在所有 storage 子命令下均可用，用于指定加载哪个配置文件以及直连存储后端：

这些选项的实际作用是：执行authelia storage bans user任意子命令时，CLI 会先加载-c指定的配置，再按配置（或上述直连参数）建立存储连接，从而对同一个 Authelia 实例的封禁数据做直接读写。

三、子命令速查与参数语义

3.1 authelia storage bans user list

列出全部用户封禁。语法为authelia storage bans user list [flags]，除-h, --help外没有专属选项。

3.2 authelia storage bans user add

添加一条用户封禁。语法为authelia storage bans user add <user> [flags]，用户名为必填位置参数（源码中Args: cobra.ExactArgs(1)，见 newStorageBansAddCmd）。专属选项如下：

关键约束（源码 storage.go#L383-L389）：add命令的PreRunE会检查--permanent与--duration不能同时指定，违反时直接报错invalid flag combination specified: both duration and permanent flags can't be used at the same time。此外时长必须能解析为正数，否则报错duration must be a positive value（见 runStorageBansAdd）。

3.3 authelia storage bans user revoke

撤销用户封禁。语法为authelia storage bans user revoke [user] [flags]。注意user是可选参数（Args: cobra.RangeArgs(0, 1)），因为可以改用 ID 精确定位：

定位规则由 runStorageBansRevokeUser 决定：id == 0时按用户名查（此时用户名不能为空，否则报either the username or id is required）；id != 0时按主键查单条记录。

四、源码级解析：三个子命令的执行链

4.1 公共前置：Schema 检查

三个子命令的RunE（StorageBansListRunE、StorageBansRevokeRunE、StorageBansAddRunE）结构一致：先defer关闭存储连接，然后调用ctx.CheckSchema()校验存储 schema 是否满足当前版本要求，不满足时以storageWrapCheckSchemaErr包装错误返回。这意味着执行任何封禁操作前，CLI 会先做存储 schema 检查，失败即终止——这是操作能安全落库的前提。

4.2 list：分页拉取 + 表格输出

runStorageBansListUser 以每页 10 条的步长循环调用store.LoadBannedUsers(ctx, limit, page)，直到某一页不足 10 条为止，把全量记录汇总到内存后统一打印。输出行为：

• 无任何封禁时，仅输出一行No results.；
• 有数据时通过tabwriter输出对齐表格，表头为ID Username Expires Source Reason。

其中Expires列经regulation.FormatExpiresShort格式化；永久封禁没有过期时间（对应BannedUser.Expires为空），Source列标识封禁来源——CLI 创建的记录固定为cli（见 runStorageBansAddUser 中Source: "cli"），regulation 系统自动触发的封禁则带有各自的来源标记，两类记录共享同一张表、同一次 list 输出。相关测试用例见 storage_run_test.go 中的ShouldListUserBansEmpty、ShouldListUserBansWithData、ShouldListUserBansWithReason等场景。

4.3 add：构造 BannedUser 并落库

runStorageBansAddUser 的构造逻辑：

1. 新建model.BannedUser，Username为位置参数，Source置为cli；
2. 若指定了-r/--reason，将其写入Reason（sql.NullString，未指定时该字段为 NULL）；
3. 若未指定-p/--permanent，则Expires = time.Now().Add(duration)，即默认一天后过期；永久封禁不设置过期时间；
4. 调用store.SaveBannedUser(ctx, ban)写入存储。

成功后输出（与 IP 分支同构的 runStorageBansAddIP 可作对照）：

Successfully banned user '<username>' until '<RFC3339 时间>'. # 限时封禁 Successfully banned user '<username>' permanently. # 永久封禁

源码中还保留了// TODO: Check for existing ban and revoke it?注释，可以推断重复 add 同一用户会新增记录而非先撤销旧记录，管理多条并存封禁时应配合 list / revoke 使用。

4.4 revoke：软撤销 + 逐条结果报告

撤销不是物理删除，而是打撤销标记：对加载出的每条封禁，若ban.Revoked已为真，输出SKIPPED Ban has already been revoked；否则调用store.RevokeBannedUser(ctx, ban.ID, time.Now())记录撤销时间戳，成功输出SUCCESS，失败输出FAILURE Error: ...。表头为ID Username Result Information。

这一设计意味着封禁历史可追溯：被撤销的封禁仍保留在表中，list 输出与撤销行为围绕BannedUser的Revoked标记展开。

五、与 regulation 系统的关系

authelia storage bans user操作的底层数据由 regulation 包 定义其语义：该包实现 regulator，在用户或 IP 反复认证失败后自动封禁，防止暴力破解。因此封禁记录有两类来源：

1. 自动封禁：regulator 在认证流程中累计失败次数达到配置阈值后写入，登录页会提示账号/来源已被封禁及其过期时间（Ban结构见 regulation/types.go，含BanTypeUser、BanTypeIP等类型与IsBanned、Expires等访问方法）；
2. 手动封禁：即本文档描述的 CLI 命令写入，Source列值为cli。

regulator 对封禁的检查行为有完整的黑盒测试佐证，见 regulator_blackbox_test.go 中的TestShouldHandleBanCheckUserBanned、TestShouldHandleBanCheckUserBannedPermanent（含追加失败时的降级路径TestShouldHandleBanCheckUserBannedFailToAppend）。存储层的查询/撤销实现则位于 internal/storage（如LoadBannedUsers、SaveBannedUser、RevokeBannedUser等方法及其 mock 测试）。

从源码结构看，CLI 只是这些存储接口的一个客户端：它不经过 Authelia 的 HTTP 服务，而是加载同一份配置直连同一存储，因此对 CLI 的增删改对运行中的实例立即生效（认证失败检查读取的是同一批记录）。

六、实操示例

以下示例假设已存在可用的存储配置（SQLite 路径、PostgreSQL 或 MySQL 均可），通过-c或对应--postgres.*/--sqlite.path等继承选项指定。

# 查看帮助 authelia storage bans user --help # 列出所有用户封禁（ID/Username/Expires/Source/Reason） authelia storage bans user list # 封禁用户 30 分钟，并附原因 authelia storage bans user add alice -d "30 minutes" -r "credential leak suspected" # 使用默认时长（1 天）封禁 authelia storage bans user add bob # 永久封禁（注意：与 --duration 互斥） authelia storage bans user add mallory -p -r "brute force" # 按用户名撤销（加载该用户名下所有封禁并逐条处理） authelia storage bans user revoke alice # 按 list 输出中的 ID 精确撤销某一条 authelia storage bans user revoke -i 42

注意事项：

• add必须且只能带一个用户名参数；revoke最多带一个，且「用户名」与-i/--id二者至少要有一种定位方式，否则报either the username or id is required；
• --duration取值为 Go duration 风格字符串（如1 day、30 minutes），解析失败或为 0/负数会直接报错；
• 执行前 CLI 会先做 schema 检查（CheckSchema），存储 schema 版本不满足要求时命令会失败退出；
• 命令需要访问真实存储，生产环境请确保配置的访问凭据最小化，并通过--encryption-key等继承选项处理加密存储场景。

七、相关命令与延伸阅读

• authelia storage bans：用户与 IP 封禁的总入口，含ip分支；
• authelia storage bans user add / list / revoke：三个子命令的独立参考页；
• authelia storage：整个authelia storage命令树（用户标识、TOTP、WebAuthn、加密等）的上级参考；
• 源码入口：命令定义 internal/commands/storage.go、执行逻辑 internal/commands/storage_run.go、regulation 模型 internal/regulation/types.go。

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia