filebrowser rules 命令完全指南：全局规则与用户规则的添加、查询与删除

filebrowser rules 命令完全指南全局规则与用户规则的添加、查询与删除【免费下载链接】filebrowserFile Browser provides a file managing interface within a specified directory and it can be used to upload, delete, preview and edit your files.项目地址: https://gitcode.com/gh_mirrors/fi/filebrowser本指南以 File Browser 官方 CLI 文档 docs/cli/filebrowser-rules.md 为核心系统讲解filebrowser rules命令族的完整用法如何通过--username/--id指定作用对象、如何理解add/ls/rm三个子命令的参数语义以及规则在运行期如何被 HTTP 层实际执行。读完本文你将掌握使用命令行对 File Browser 的访问规则进行精细化管理的完整实战方案并理解规则匹配允许/拒绝、路径/正则的底层实现原理。命令概览规则管理工具filebrowser rules是 File Browser 的命令行规则管理工具对应源码 cmd/rules.go 中的rulesCmdShort描述为 Rules management utility。它本身不执行任何规则操作而是作为add、ls、rm三个子命令的父命令存在负责统一提供两个持久化Persistent参数username与id并决定规则作用在全局集合还是某个用户上。从文档 Synopsis 可知其核心语义On each subcommand youll have available at least two flags: username and id. You must either set only one of them or none. If you set one of them, the command will apply to an user, otherwise it will be applied to the global set of rules.即在每个子命令上username与id要么只设置其中一个要么都不设置。设置了则规则作用于该用户否则作用于全局规则集合。这一逻辑在源码中有精确实现——cmd/rules.go 的getUserIdentifier函数按id 优先、username 其次的顺序解析参数func getUserIdentifier(flags *pflag.FlagSet) (interface{}, error) { id, err : flags.GetUint(id) ... if id ! 0 { return id, nil } else if username ! { return username, nil } return nil, nil }随后runRulescmd/rules.go根据解析结果分发有 id 时从存储中取出对应用户并操作user.Rules无 id 时读取全局设置并操作settings.Rules最终统一调用printRules打印结果。全局参数说明rules 命令自身选项-h, --help help for rules -i, --id uint id of user to which the rules apply -u, --username string username of user to which the rules apply-i, --id uint目标用户 ID无符号整数。根据 cmd/rules.go 的定义默认值为0因此id为0视为未指定。-u, --username string目标用户名。-h, --help查看帮助。从父命令继承的选项-c, --config string config file path -d, --database string database path (default ./filebrowser.db)-c, --config string配置文件路径对应filebrowser config子命令生成/管理的配置文件。-d, --database string数据库路径默认./filebrowser.db。规则数据无论是用户规则还是全局规则最终持久化在 BoltDB 数据库中见 storage/bolt/config.go 与 storage/bolt/users.go 的实现。三个子命令详解1.filebrowser rules add添加规则文档 docs/cli/filebrowser-rules-add.md 给出的用法为filebrowser rules add path|expression [flags]其选项为-a, --allow indicates this is an allow rule -h, --help help for add -r, --regex indicates this is a regex rule参数语义非常关键第一个位置参数path|expression在-r未指定时是路径指定时是正则表达式-a, --allow标记该规则为允许规则不指定则默认为拒绝disallow规则-r, --regex标记该规则为正则规则。对应源码 cmd/rules_add.go 展示了完整的处理流程var rulesAddCmd cobra.Command{ Use: add path|expression, ... RunE: withStore(func(cmd *cobra.Command, args []string, st *store) error { ... if regex { regexp.MustCompile(exp) // 编译校验非法正则直接报错 } rule : rules.Rule{Allow: allow, Regex: regex} if regex { rule.Regexp rules.Regexp{Raw: exp} } else { rule.Path exp } user : func(u *users.User) error { u.Rules append(u.Rules, rule) return st.Users.Save(u) } global : func(s *settings.Settings) error { s.Rules append(s.Rules, rule) return st.Settings.Save(s) } return runRules(st.Storage, cmd, user, global) }, storeOptions{}), }可见正则模式会先用regexp.MustCompile做编译期校验非法表达式会直接返回错误避免把坏规则写入数据库-a与-r的默认值均为false因此最简单的filebrowser rules add /path添加的是一条路径拒绝规则。典型用法示例# 为全局规则集合添加一条路径拒绝规则拒绝访问 /secret filebrowser rules add /secret # 为用户 adminID 或用户名均可添加一条允许规则允许访问 /uploads filebrowser rules add -a /uploads --username admin filebrowser rules add -a /uploads --id 1 # 添加一条正则拒绝规则拒绝所有 .tmp 后缀文件 filebrowser rules add -r \.tmp$ # 添加一条大小写不敏感的正则允许规则 filebrowser rules add -r -a (?i)^/Public/2.filebrowser rules ls列出规则文档 docs/cli/filebrowser-rules-ls.md 给出的用法为filebrowser rules ls [flags]该命令本身只有-h, --help选项作用范围完全由继承的-i/-u决定。源码 cmd/rules_ls.go 极为简洁直接调用runRules且两个回调均为nil即只做查询与打印。打印格式由 cmd/rules.go 的printRules定义无-i/-u时输出标题Global Rules:有-i/-u时输出Rules for user id:每条规则以序号(0)、(1)… 开头并按规则类型输出为四种形式之一Allow Path:、Disallow Path:、Allow Regex:、Disallow Regex:。# 列出全局规则 filebrowser rules ls # 列出某个用户的规则 filebrowser rules ls --username admin filebrowser rules ls --id 1示例输出Global Rules: (0) Disallow Path: /secret (1) Disallow Regex: \.tmp$注意这里的(0)、(1)序号就是后续rm命令需要使用的索引且每次增删后索引都会变化见下文。3.filebrowser rules rm删除规则文档 docs/cli/filebrowser-rules-rm.md 给出的用法为filebrowser rules rm index [index_end] [flags]其选项为-h, --help help for rm --index uint index of rule to remove文档特别强调了两点注意事项传入的index与执行rules ls时打印的索引一致每次删除/添加后规则的索引都会发生变化因此连续删除时必须谨慎最好基于最新的ls结果操作。index_end是可选参数用于一次性删除从index到index_end含index_end的连续区间。从源码 cmd/rule_rm.go 的Long描述可确认该语义You can also specify an optional parameter (index_end) so you can remove all commands from index to index_end, including index_end.实现细节cmd/rule_rm.go参数校验使用cobra.RangeArgs(1, 2)并逐个做strconv.Atoi数字校验删除操作用 Go 切片拼接完成u.Rules append(u.Rules[:i], u.Rules[f1:]...)其中i为起始索引f为终止索引未提供index_end时f i。# 删除全局规则中的第 0 条 filebrowser rules rm 0 # 删除用户 admin 规则中的第 1 到第 3 条含第 3 条 filebrowser rules rm 1 3 --username admin规则模型与匹配原理源码级要真正用好规则需要理解规则的底层数据结构与匹配算法。规则类型定义在 rules/rules.gotype Rule struct { Regex bool json:regex Allow bool json:allow Path string json:path Regexp *Regexp json:regexp }四个字段对应四条关键语义Regex是否为正则规则-r标志Allow是否允许规则-a标志false表示拒绝Path路径规则的目标路径Regexp正则规则的表达式包装内部保存原始表达式Raw并延迟编译rules/rules.go 的MatchString在首次调用时用regexp.MustCompile编译。路径规则的匹配算法Matches方法rules/rules.go定义了路径规则如何命中先做精确匹配path rulePath直接命中否则将规则路径规范化为带/结尾的前缀根路径/除外再做前缀匹配。这意味着路径规则覆盖其下所有子路径但不会误伤同名前缀的兄弟路径如/uploads不会命中/uploads_backup/...。fold参数用于大小写不敏感场景当文件系统大小写不敏感CaseInsensitiveFs时规则路径与被测路径同时转小写后比较防止因大小写变体绕过规则见 rules/rules_test.go 中针对GHSA-fgm5-pw99-w2p7安全公告的回归测试。正则规则的匹配特性正则规则不做大小写折叠——文档与源码注释明确指出管理员的表达式应当所见即所得如需忽略大小写应显式使用(?i)内联修饰符。这一行为由测试 rules/rules_test.go 严格验证^/Secret\.txt$只命中/Secret.txt而(?i)^/Secret\.txt$才能命中/secret.TXT。隐藏文件的处理rules/rules.go 提供MatchHidden辅助函数判断路径基名basename是否以.开头。它在 HTTP 层与隐藏点文件设置HideDotfiles配合使用见下节。规则在运行期如何生效CLI 管理的是存储层的数据而真正的鉴权发生在 HTTP 请求处理阶段。http/data.go 中的data结构体实现了rules.Checker接口func (d *data) Check(path string) bool { if d.user.HideDotfiles rules.MatchHidden(d.rulePath(path)) { return false } return d.CheckRules(path) } func (d *data) CheckRules(path string) bool { path d.rulePath(path) allow : true for _, rule : range d.settings.Rules { // 先应用全局规则 if rule.Matches(path, d.server.CaseInsensitiveFs) { allow rule.Allow } } for _, rule : range d.user.Rules { // 再应用用户规则覆盖全局 if rule.Matches(path, d.server.CaseInsensitiveFs) { allow rule.Allow } } return allow }由此可以总结出运行期的核心行为全局规则与用户规则按顺序叠加全局规则先执行用户规则后执行后命中的规则覆盖先前的判定结果allow被顺序改写因此用户规则可以针对性地放行或收紧全局规则。默认允许没有任何规则命中时allow保持初始值true即默认放行。Check与CheckRules的区别Check额外检查HideDotfiles隐藏点文件属于显示偏好会直接拦截展示CheckRules只做规则判定保证隐藏文件规则不阻止用户对含点文件目录树的操作。路径规范化rulePathhttp/data.go先将路径做slashClean清洗统一/分隔符避免 Windows 下\与/混用导致的绕过并在公共分享public share将文件系统重定位到子目录时通过checkerPrefix把路径还原到用户原始作用域再匹配防止规则被静默绕过。测试对行为的验证仓库测试覆盖了上述关键行为可作为行为契约参考rules/rules_test.go 验证路径规则的精匹配、子路径前缀匹配、兄弟前缀不误伤、根路径/全匹配、尾部斜杠行为以及大小写折叠的边界rules/rules_test.go 验证MatchHidden对点文件/点目录的判定http/utils_test.go 覆盖路径清洗在规则判定与文件系统解析之间的一致性。实用场景速查需求命令全局拒绝某目录filebrowser rules add /secret全局允许某目录默认拒绝策略配合使用filebrowser rules add -a /public只对某个用户加规则追加--username name或--id id用正则批量拒绝某类文件filebrowser rules add -r \.(tmp\|bak)$查看当前生效规则含索引filebrowser rules ls查看某用户规则filebrowser rules ls -u name删除单条规则filebrowser rules rm index批量删除连续区间filebrowser rules rm start end指定非默认数据库追加-d /path/to/filebrowser.db小结filebrowser rules命令族提供了全局 用户两级、且允许/拒绝 路径/正则二维可组合的规则管理能力add负责新增路径规则或正则规则、允许或拒绝ls负责查看并给出删除所需索引rm支持单条或区间删除作用范围由-i/-u精确控制。配合 http/data.go 中全局先、用户后、后命中覆盖、默认放行的判定顺序以及路径清洗、大小写折叠、公共分享前缀还原等安全细节这一整套机制足以支撑生产环境下的细粒度文件访问控制。相关子命令的完整参数参考见 filebrowser rules add、filebrowser rules ls 与 filebrowser rules rm主命令总览见 filebrowser。【免费下载链接】filebrowserFile Browser provides a file managing interface within a specified directory and it can be used to upload, delete, preview and edit your files.项目地址: https://gitcode.com/gh_mirrors/fi/filebrowser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考