Authelia CLIstorage bans ip命令详解管理 Regulation 系统中的 IP 封禁【免费下载链接】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 中当用户或源 IP 因多次认证失败触发 regulation封禁调控策略时被封禁的记录会持久化到存储层运维人员则可以通过authelia storage bans ip这一组 CLI 子命令直接查看、创建和撤销 IP 封禁而无需登录数据库手工操作。本文围绕 authelia_storage_bans_ip 参考文档 展开完整覆盖该命令的定义、选项与子命令用法并结合 internal/commands/storage.go、internal/commands/storage_run.go、internal/regulation/regulator.go 等源码深入说明每条子命令底层的执行逻辑与存储实现。命令定位与命令树结构authelia storage bans ip是authelia storage命令树下的一个分组子命令官方文档对它的描述为Manages ip bans管理 IP 封禁This subcommand allows listing, creating, and revoking ip bans from the regulation system.该子命令允许从 regulation 系统中列出、创建和撤销 IP 封禁从 internal/commands/storage.go 中newStorageBansCmd第 285-302 行与newStorageBansIPCmd第 324-342 行的源码结构看bans命令下挂有user与ip两个平行的子命令组二者共用同一套list/revoke/add工厂函数仅通过use参数ip或user区分目标类型。ip分组的完整子命令关系如下命令作用参考文档authelia storage bans ipIP 封禁管理分组无独立动作authelia_storage_bans_ip.mdauthelia storage bans ip add ip添加一条 IP 封禁authelia_storage_bans_ip_add.mdauthelia storage bans ip list列出全部 IP 封禁authelia_storage_bans_ip_list.mdauthelia storage bans ip revoke [ip]撤销一条 IP 封禁authelia_storage_bans_ip_revoke.mdauthelia storage bans用户与 IP 封禁的父级分组authelia_storage_bans.md示例摘自官方文档authelia storage bans ip --help选项说明命令自身选项authelia storage bans ip作为分组命令自身仅保留帮助选项-h, --help help for ip从父命令继承的选项执行任何storage子命令时都会继承 internal/commands/storage.go 中以PersistentFlags()注册的一组存储连接参数这些选项由newStorageCmd统一注册-c, --config strings configuration files or directories to load, for more information run authelia -h authelia config (default [configuration.yml]) --config.experimental.filters strings list of filters to apply to all configuration files, for more information run authelia -h authelia filters --encryption-key string the storage encryption key to use --mysql.address string the MySQL server address (default tcp://127.0.0.1:3306) --mysql.database string the MySQL database name (default authelia) --mysql.password string the MySQL password --mysql.username string the MySQL username (default authelia) --postgres.address string the PostgreSQL server address (default tcp://127.0.0.1:5432) --postgres.database string the PostgreSQL database name (default authelia) --postgres.password string the PostgreSQL password --postgres.schema string the PostgreSQL schema name (default public) --postgres.username string the PostgreSQL username (default authelia) --sqlite.path string the SQLite database path从源码看这些命令行选项并非孤立生效internal/commands/storage_run.go 中的ConfigStorageCommandLineConfigRunE会把它们一一映射到配置项上例如--encryption-key→storage.encryption_key、--sqlite.path→storage.local.path、--mysql.address→storage.mysql.address等从而可以临时覆盖-c指定配置文件里的存储设置方便在 CI 或多环境场景中直接指向不同的数据库。子命令执行前的统一准备流程三个具体子命令add、list、revoke共享同一套执行前置逻辑这一链条定义在newStorageCmd的PersistentPreRunE中internal/commands/storage.goConfigStorageCommandLineConfigRunE把上述存储命令行选项合并进配置HelperConfigLoadRunE加载配置文件ConfigValidateStorageRunE校验存储配置合法性见 internal/commands/storage_run.goLoadProvidersStorageRunE初始化存储 Provider 并挂到命令上下文internal/commands/storage_run.go。在每个子命令的RunE入口如StorageBansListRunEinternal/commands/storage_run.go还会再调用ctx.CheckSchema()确认存储模式已迁移到有效版本命令执行完毕后会统一Close()数据库连接。也就是说执行storage bans ip任何子命令的前提是配置文件可加载、存储配置校验通过、且数据库模式处于正常迁移状态。add子命令创建一条 IP 封禁命令格式authelia storage bans ip add ip [flags]专属选项-d, --duration string the duration for the ban (default 1 day) -h, --help help for add -p, --permanent makes the ban effectively permanent -r, --reason string includes a reason for the ban结合 internal/commands/storage_run.go 中runStorageBansAddIP的实现可以确认以下行为细节IP 合法性校验add的参数会经过net.ParseIP解析非法地址直接报错invalid IP address: target来源标记CLI 创建的封禁Source字段固定为cli而自动封禁的Source为regulation见 internal/regulation/regulator.go因此在list输出中可以区分一条封禁是人工添加还是策略自动触发过期时间默认duration为1 day最终封禁到time.Now().Add(duration)若指定-p/--permanent则不写入Expires存储模型中该字段为sql.NullTime见 internal/model/regulation.go即事实上永久封禁互斥约束internal/commands/storage.go 的PreRunE会拦截同时指定--permanent与--duration的组合报错 both duration and permanent flags cant be used at the same time原因记录-r指定的原因写入Reason字段未指定时该字段为空值成功输出永久封禁输出Successfully banned IP ip permanently.时限封禁输出Successfully banned IP ip until RFC3339 时间。实际调用链为StorageBansAddRunEinternal/commands/storage_run.go→runStorageBansAdd负责解析 duration 并要求其为正值→runStorageBansAddIP→ 存储层的SaveBannedIPinternal/storage/sql_provider.go向 banned IP 表插入一条包含expires、ip、source、reason的记录。list子命令列出全部 IP 封禁命令格式authelia storage bans ip list [flags]无专属选项仅有-h, --help。从 internal/commands/storage_run.go 的runStorageBansListIP源码看其工作方式是以每页 10 条的固定分页循环调用存储层LoadBannedIPsinternal/storage/sql_provider.go对应 SQL 会过滤掉已撤销且已过期的记录直到取完所有有效封禁无任何结果时输出No results.否则以表格形式输出表头为ID、IP、Expires、Source、Reason其中过期时间通过regulation.FormatExpiresShort做短格式渲染internal/regulation/util.go。输出示例依据源码格式推断ID IP Expires Source Reason 1 203.0.113.7 2026-09-13T10:00:00 regulation Exceeding Maximum Retries 2 198.51.100.2 Permanent cli suspicious activityrevoke子命令撤销 IP 封禁命令格式authelia storage bans ip revoke [ip] [flags]专属选项internal/commands/storage.go 的newStorageBansRevokeCmd-h, --help help for revoke -i, --id int revokes the ban with the given id instead of the ip value定位目标有两种方式二者必须提供其一否则报错either the ip or id is required传入 IP 值通过LoadBannedIP按 IP 查询全部匹配封禁传入-i/--id通过LoadBannedIPByID按 ID 精确查询单条封禁。从 internal/commands/storage_run.go 的runStorageBansRevokeIP看撤销结果以表格输出ID、IP、Result、Information四列且撤销是软撤销底层RevokeBannedIPinternal/storage/sql_provider.go传入当前时间戳并校验恰好影响一行标记封禁为已撤销而非物理删除。每条封禁会落入以下三种状态之一Result含义SKIPPED该封禁此前已被撤销Ban has already been revokedSUCCESS撤销成功FAILURE撤销失败Information 列附带具体错误底层机制regulation 系统如何产生与消费这些封禁理解storage bans ip的前提是理解 Authelia 的 regulation 机制。配置模板 internal/configuration/config.template.yml 中的相关配置如下# regulation: ## Regulation Mode. # modes: # - user # - ip ## The number of failed login attempts before user is banned. Set it to 0 to disable regulation. # max_retries: 3 ## The time range during which the user can attempt login before being banned in the duration common syntax. The user ## is banned if the authentication failed max_retries times in a find_time seconds window. # find_time: 2 minutes ## The length of time before a banned user can login again in the duration common syntax. # ban_time: 5 minutes对照 internal/regulation/regulator.go 的实现可以确认其运行逻辑Regulator依据max_retries 0且modes中包含ip来决定是否启用 IP 封禁第 20-28 行每次认证尝试都会写入AppendAuthenticationLog只有在尝试失败、当前未处于封禁态、regulation 已启用、且认证类型为 1FA时才执行封禁检查HandleAttempt第 31-67 行若某 IP 在find_time窗口内的失败次数达到max_retries则以Source: regulation、Reason: Exceeding Maximum Retries自动落库一条BannedIP封禁时长为ban_timehandleAttemptPossibleBannedIP第 69-107 行请求侧的封禁判断由BanCheck完成且优先检查 IP 封禁再检查用户封禁第 147-184 行命中即拒绝后续认证。因此storage bans ip命令管理的数据正是这套机制的持久化结果list可以看到策略自动封禁与手工封禁并存的记录add用于在策略之外人工追加封禁例如封禁扫描器 IPrevoke用于误封或攻击结束后的解封。实战示例完整的封禁管理流程假设使用 SQLite 存储完整的一次封禁管理流程如下# 1. 查看当前所有 IP 封禁 authelia -c /etc/authelia/configuration.yml --sqlite.path /etc/authelia/storage.sqlite \ storage bans ip list # 2. 对某攻击源 IP 下 48 小时封禁并备注原因 authelia -c /etc/authelia/configuration.yml --sqlite.path /etc/authelia/storage.sqlite \ storage bans ip add 203.0.113.66 -d 48 hours -r brute force attack # 3. 确认封禁已生效 authelia -c /etc/authelia/configuration.yml --sqlite.path /etc/authelia/storage.sqlite \ storage bans ip list # 4. 攻击停止后按 IP 撤销封禁 authelia -c /etc/authelia/configuration.yml --sqlite.path /etc/authelia/storage.sqlite \ storage bans ip revoke 203.0.113.66 # 4. 或者仅知 list 输出的 ID 时按 ID 撤销 authelia ... storage bans ip revoke -i 7 # 5. 需要立即生效的永久封禁 authelia ... storage bans ip add 198.51.100.23 -p -r malformed traffic需要注意的适用前提与限制duration使用通用时长语法如1 day、48 hours、5 minutes解析失败会报failed to parse duration string且必须为正值add与revoke均要求存储模式处于有效版本CheckSchema未迁移的数据库会先被拦截撤销是软标记list只展示仍然有效的封禁若同一 IP 已存在未撤销的封禁源码中留有TODO: Check for existing ban and revoke it?internal/commands/storage_run.go当前实现是追加一条新记录而非覆盖因此可能同时看到同 IP 的多条记录可用revoke -i精确清理。小结authelia storage bans ip为 Authelia 的 regulation 封禁体系提供了直接的命令行管理入口add-d/-p/-r三选项负责创建带时限或永久的 IP 封禁list以分页查询输出全部有效封禁revoke支持按 IP 或-i按 ID负责软撤销。三个子命令共享同一套加载配置 → 校验 → 建立存储连接 → 检查模式的执行链底层通过 internal/storage/sql_provider.go 中的SaveBannedIP/LoadBannedIPs/RevokeBannedIP等方法读写存储并与 internal/regulation/regulator.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），仅供参考