water-repo 产品剖析

gitee仓库地址
github仓库地址

本文章基于产品三要素分析 以及 数据六纬度 两个分析方法对 基于 go 的轻量级CLI个人/小团体的仓库管理工具 wt 进行分析

三要素

理念

• 易用
• 极简
• 稳定
• 高效
• 零依赖
• 跨平台友好
• 认知负荷小
• Token 分级校验

关系

• 超级管理员
  • 对仓库: 是绝对拥有者，拥有全部权限,备份和维护只需要打包仓库所在的目录，没有复杂的树状结构，因为扁平化标签管理而精简高效
  • 对其他普通标签的管理员: 开放特定的权限， 通过三级权限(read install write)以及扁平化标签进行管理
  • 对仓库外的访问者: 通过 public 命令一键分享某个包, private 命令撤回分享
  • 对包: 完全实现私有化存储，不限网络带宽，实现安全存储和高效分发
  • 对权限管理: 使用 全局 Token 权限 + Tag 局部权限 分层管理,保证权限的正确分配

总结: 仓库从维护的负担成为易于管理控制权限, 无需注册，本地安全，备份简单，分发极简的高效工具

• 标签级别管理员
  • 对仓库: 只能看到有权限的包和标签，不需要关心其他的标签维护情况和进度，精力和注意力消耗小
  • 对其他普通标签的管理员: 通过标签化管理在各自负责的范围内进行包的管理，互不打扰，只有在分发的时候进行交换

总结: 仓库不需要占用大量的精力和时间进行整理和维护，只需要按照要求上传自己复杂的包，几乎没有维护的要求,三级权限管理防止误操作

• 仓库外的访问者
  • 对包: 点击链接一键下载， 没有网盘广告，网速限制，对仓库内部的包完全无感，按需下载

总结: 提升下载和访问的体验，避免网盘下载速度控制以及复杂的文件查找

规则

• 3 Token
  摒弃传统角色注册体系，采用‘全局 Token + 标签级 Token’的两级权限体系，仅通过 3 级权限（read/install/write）控制操作，无需关心‘用户是谁’，仅校验‘是否有权限’

• n Tag
  不使用目录进行数据的组织, 而是所有的包都放在同一个目录下， 通过标签区别用途和权限，使用扁平化标签进行组织和分发，不需要记住复杂的逻辑结构(当然这跟wt的定位密不可分, wt 是包管理器而不是git版本控制器，只负责存储和分发打包好的东西). 备份和维护极其简单,打包一个目录直接迁移

• soft link + funnel
  使用tailscale funnel + 软链接进行公网的分享: wt public <package> -> 建立软链接到 /path/to/data/public/文件夹 -> funnel 暴露 public 文件夹 -> 多个包通过链接直接下载. 不占用存储空间， 调用private命令直接删除软链接取消分享，设计极简而高效

六维度

• 输入
  用户通过 tag config 几个核心命令即可完成所有必要的仓库初始化和权限管理， 只有前期配置token的时候花费2-3分钟，其余时间直接使用类 linux的命令 search upload ls mv rm install 进行简单的管理，这里特地使用了 linux包管理器的命令以及 ls, mv, rm 等原生linux命令，直接无缝衔接开发者的日常操作. 做到易用性
• 存储
  用户完全自定义存储，只需要通过 wt server -d /path/to/dir 指定目录就能够直接使用， 不依赖任何的特定结构和操作系统. 配置文件完全本地留存，支持 wt uninstall 一条命令卸载
• 处理
  之保留最必要的信息，包名， 大小， 修改时间， 标签，标签和token的权限关系， 没有任何的用户敏感信息
• 分析
  通过标签对包进行查看和管理，设计极简, 不引入不必要的设计
• 分发
  wt 的默认网络环境是在内网进行的， 但是也可以使用tailnet 进行异地组网进行文件的共享，默认的http协议跟 tailnet进行配合能够保证安全性， 或者在公司的内网进行使用。也集成了tailscale funnel 进行公网的分发和使用。
• 呈现
  wt 工具的呈现层以极简为核心，不强制展示包的复杂逻辑关系，而是通过标签过滤 + FZF 交互式检索实现高效呈现，完全适配开发者的命令行操作习惯；

可复用的理念

1. 极简设计
   • 去除不必要的文件夹树状结构，保留最简单的tag + CLI 管理方式
2. 渐进式展开设计
   • 提供 simple default advance 三个帮助手册， 让用户按需取用
3. 减法原则
   • 显式地列出不做的内容，保证理念始终成为产品核心

关系设计的通用模式

1. 最小认知负荷模式: 每个角色只需要知道自己需要完成对应的任务所需要的信息， 其他的无关信息使用权限隔离和自动过滤等方法进行屏蔽，避免造成没有必要的认知负荷
   • 应用: 使用标签来隔离用户的视角， 只有拥有阅读权限的用户才能看到相应的标签
2. 最小权限模式: 给用户分配完成任务所需的最小权限
   • 应用: read/install/write 三级权限控制
3. 隔离协作模式: 将不同分工的角色进行信息和权限的隔离， 避免互相干扰和误操作
   • 应用: 使用不可读标签屏蔽的方法隔离不同标签的负责人

规则设计

1. Token 权限管理
   • 权限到资源直接的分发，没有任何多余的兼容层(角色)
2. 标准配置文件 + 交互式配置修改接口
   • 从配置文件读取配置信息，做配置的持久化,并支持动态的配置修改
3. 热门工具集成复用
   • 兼容fzf工具实现高效查找和打标签， 集成tailscale funnel满足公网临时分享需求
4. 使用现有的操作系统级别的解决方案进行特殊功能的实现
   • 使用软链接的方式实现临时的文件分享和分享的取消，用最低的开发成本和维护成本实现了最高的稳定性和易用性

重要决策

1. 采用了扁平化的存储结构而不是存储的文件夹树状结构
   • 在开发的过程中我发现对于一个包管理器来说，是不需要文件夹结构的，因为包本身就内涵了需要的结构，打包是上传者的事情而不是 wt 需要做的事情，所以采用了扁平化的存储策略， 这降低复杂度的同时也降低了维护和迁移成本
2. 采用 token 权限认证机制而不是用户登录认证方式
   • 因为 wt 的核心定位是包的存储与分发，无需追溯上传者身份（类似镜像站无需登录即可使用），因此用户系统属于冗余设计，严重偏离 “极简” 的核心理念。
3. 权限控制中混合了 全局管理员权限和标签管理员权限， 使用了 read/install/write 三种模式的不同权限分发
   • 全局管理员权限类似于linux中的root,可以对任何的包进行操作和修改，分发，保证仓库管理者的高效。tag 管理员则严格限制权限的范围，保证了在特定的标签下有足够的权限完成交付任务，并降低管理风险. 三种模式的设计则完美符合了 小团队的包管理和分发的需求，在权限冗余和权限不足中找到合适的平衡点
4. 兼容了fzf 工具进行高效而体验良好的工具优化
   • fzf 工具简单易用， 并且容易集成， 能够很好的提升体验。只需要稍微修改代码进行兼容就能获得很好的收益，避免重复造轮子
5. 集成了 tailscale funnel 实现文件的公网分享
   • 使用一个简单的 public 命令创建软链接并进行分享，这个方式是我觉得非常得意的一个点，方便而优雅地解决了多个文件分享，撤回文件分享的问题，并且轻量和极致的高效。让wt实现方便的临时共享功能
6. 复用linux的原生命令(ls, mv, search, rm)
   • 考虑到wt的目标使用者大多数都是拥有服务器的linux玩家， 复用linux的命令让学习成本降到最低， 完美符合易用的设计理念