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 分支的行为。二、命令参考原文档要素完整继承Synopsisauthelia storage bans user --helpOptions本命令自身选项-h, --help help for userOptions inherited from parent commands从父命令继承的选项以下全局选项在所有 storage 子命令下均可用用于指定加载哪个配置文件以及直连存储后端选项说明默认值-c, --config strings要加载的配置文件或目录更多信息运行authelia -h authelia config[configuration.yml]--config.experimental.filters strings应用于所有配置文件的过滤器列表更多信息运行authelia -h authelia filters无--encryption-key string要使用的存储加密密钥无--mysql.address stringMySQL 服务器地址tcp://127.0.0.1:3306--mysql.database stringMySQL 数据库名authelia--mysql.password stringMySQL 密码无--mysql.username stringMySQL 用户名authelia--postgres.address stringPostgreSQL 服务器地址tcp://127.0.0.1:5432--postgres.database stringPostgreSQL 数据库名authelia--postgres.password stringPostgreSQL 密码无--postgres.schema stringPostgreSQL schema 名public--postgres.username stringPostgreSQL 用户名authelia--sqlite.path stringSQLite 数据库路径无这些选项的实际作用是执行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。专属选项如下选项说明默认值-d, --duration string封禁时长1 day-p, --permanent使封禁事实上永久生效false-r, --reason string附带封禁原因无-h, --help显示帮助—关键约束源码 storage.go#L383-L389add命令的PreRunE会检查--permanent与--duration不能同时指定违反时直接报错invalid flag combination specified: both duration and permanent flags cant 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 精确定位选项说明-i, --id int用给定的 id 而非用户名来撤销封禁-h, --help显示帮助定位规则由 runStorageBansRevokeUser 决定id 0时按用户名查此时用户名不能为空否则报either the username or id is requiredid ! 0时按主键查单条记录。四、源码级解析三个子命令的执行链4.1 公共前置Schema 检查三个子命令的RunEStorageBansListRunE、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: cliregulation 系统自动触发的封禁则带有各自的来源标记两类记录共享同一张表、同一次 list 输出。相关测试用例见 storage_run_test.go 中的ShouldListUserBansEmpty、ShouldListUserBansWithData、ShouldListUserBansWithReason等场景。4.3 add构造 BannedUser 并落库runStorageBansAddUser 的构造逻辑新建model.BannedUserUsername为位置参数Source置为cli若指定了-r/--reason将其写入Reasonsql.NullString未指定时该字段为 NULL若未指定-p/--permanent则Expires time.Now().Add(duration)即默认一天后过期永久封禁不设置过期时间调用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 反复认证失败后自动封禁防止暴力破解。因此封禁记录有两类来源自动封禁regulator 在认证流程中累计失败次数达到配置阈值后写入登录页会提示账号/来源已被封禁及其过期时间Ban结构见 regulation/types.go含BanTypeUser、BanTypeIP等类型与IsBanned、Expires等访问方法手动封禁即本文档描述的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考