后端文件存储【免费下载链接】alist️A file list/WebDAV program that supports multiple storages, powered by Gin and Solidjs. / 一个支持多存储的文件列表/WebDAV程序使用 Gin 和 Solidjs。项目地址https://gitcode.com/GitHub_Trending/al/alist点击查看免费下载导读alist 是一个基于 Go 与前端框架构建的多存储文件列表/WebDAV 程序仓库根目录命令描述见 cmd/root.go。本文以仓库根目录的 CONTRIBUTING.md 为主线完整梳理从开发环境搭建、克隆源码、本地前后端预览到基于drivers/template模板新增一个存储驱动、编写符合规范的提交信息并提交 Pull Request 的端到端流程。读完本文你将掌握 alist 开发者视角的完整工作流并理解驱动注册与加载的底层机制能够独立为该项目贡献新存储后端。一、环境准备搭建 alist 开发机1.1 前置依赖alist 由 Go 编写后端、前端框架编写 Web 界面CONTRIBUTING.md 原文表述为 React仓库命令描述则写作 Go/Solid.js见 cmd/root.go。按照 CONTRIBUTING.md 的要求开发机器需要安装以下工具依赖用途说明git版本控制克隆源码、管理分支与提交Go 1.20后端编译运行文档要求 1.20当前仓库 go.mod 中声明的版本为go 1.25.0实际编译时建议使用较新的 Go 工具链gcc编译 CGO 依赖部分第三方库如本地缩略图、加密相关依赖依赖 CGOnodejs前端开发配合 pnpm 运行前端开发服务器1.2 克隆源码按文档要求将后端仓库alist与前端仓库alist-web克隆到任意位置$ git clone https://github.com/alist-org/alist.git $ git clone --recurse-submodules https://github.com/alist-org/alist-web.git其中前端仓库必须使用--recurse-submodules以同时拉取子模块。开发时应切换到main分支与上游主线保持一致。克隆得到的alist后端仓库核心目录结构如下以当前仓库实际内容为准main.go程序入口仅调用cmd.Execute()cmd/基于 Cobra 的命令行实现root.go、server.go、storage.go、user.go等drivers/全部存储驱动每个子目录是一个独立驱动另含template模板与 all.go 注册聚合文件internal/核心业务逻辑其中 internal/driver 定义了驱动接口server/HTTP/FTP/SFTP/WebDAV 等服务端路由pkg/通用工具库二、预览你的改动前后端开发服务器2.1 后端go run main.go在alist仓库根目录直接运行$ go run main.go该命令会编译并启动开发服务器。从源码看main.go 只做一件事调用cmd.Execute()进而执行 cmd/root.go 中的 Cobra 命令分发。真正拉起服务的是 cmd/server.go 中的ServerCmd它会依次完成配置初始化、加载存储bootstrap.LoadStorages()、初始化任务管理器与 FRP 内网穿透然后启动 HTTP/HTTPS/Unix Socket、S3、FTP、SFTP 与 MCP 等监听服务。因此go run main.go默认行为等同于执行alist server监听地址等由配置文件决定相关实现见 cmd/server.go。2.2 前端pnpm dev进入alist-web目录运行$ pnpm dev即可启动前端开发服务器。前后端联调时前端开发服务器通常需要配置代理指向本机后端端口开发期间修改 Go 代码后重启go run main.go修改前端代码则由 Vite 热更新自动生效。三、新增一个存储驱动Driver这是 alist 贡献中最核心的扩展点。CONTRIBUTING.md 给出的方法极为简洁——复制drivers/template文件夹并重命名然后按照其中的注释实现。下面结合源码把这条指引展开成可操作的完整步骤。3.1 模板文件夹结构drivers/template共包含 4 个文件见 drivers/template文件职责meta.go定义驱动注册信息config、用户可配置字段Addition并在init()中调用op.RegisterDriver完成注册driver.go定义驱动主体结构Template并实现全部接口方法大部分为 TODO 占位types.go类型定义占位文件util.go工具函数占位文件注释提示“可在此实现 Driver 接口之外的其他逻辑”3.2 注册信息与配置字段meta.godrivers/template/meta.go 揭示了每个驱动的两个核心组成部分Addition结构体通过 struct tag 声明用户在前端页面填写的配置项。模板默认嵌入driver.RootPath或driver.RootID二者之一通常按驱动是按路径还是按 ID 标识文件来选择并示范了一个自定义字段type Addition struct { // Usually one of two driver.RootPath driver.RootID // define other Field string json:field type:select required:true options:a,b,c default:a }这里的 tag 约定json、type、required、options、default、help会被管理界面自动解析为表单控件。以本地驱动 drivers/local/meta.go 为真实范例可以看到更丰富的字段例如thumbnail是否启用缩略图、use_ffmpeg是否用 ffmpeg 生成视频缩略图、thumb_pixel缩略图目标宽度像素、video_thumb_pos视频缩略图时间点支持秒数或百分比、mkdir_perm新建目录权限、recycle_bin_path回收站路径等每个字段都带有help说明非常值得模仿。config变量类型为driver.Config用于描述驱动的能力与行为var config driver.Config{ Name: Template, LocalSort: false, OnlyLocal: false, OnlyProxy: false, NoCache: false, NoUpload: false, NeedMs: false, DefaultRoot: root, / or other, CheckStatus: false, Alert: , NoOverwriteUpload: false, }字段含义可从命名推断OnlyLocal表示仅限本机文件系统本地驱动 drivers/local/meta.go 将其置为true并开启LocalSort、NoCacheNoUpload表示不支持上传DefaultRoot是默认根路径提示Alert可在界面上展示注意事项。注册文件末尾的init()调用op.RegisterDriverfunc init() { op.RegisterDriver(func() driver.Driver { return Template{} }) }所有驱动正是通过各包的init()副作用完成注册而 drivers/all.go 以空导入方式统一聚合了全部驱动注释写明“All do nothing, just for import”。3.3 驱动主体与接口方法driver.godrivers/template/driver.go 定义的驱动结构体嵌入model.Storage与自定义Addition从而自动获得存储基础属性与配置字段type Template struct { model.Storage Addition }必实现方法标注required方法签名职责ConfigConfig() driver.Config返回驱动能力配置GetAdditionGetAddition() driver.Additional返回配置字段指针供 JSON 反序列化使用见 internal/driver/driver.go 中Meta接口注释InitInit(ctx) error初始化如登录/刷新 Token注释提示可调用op.MustSaveDriverStorage(d)保存存储DropDrop(ctx) error销毁时清理资源ListList(ctx, dir, args) ([]model.Obj, error)列出目录文件必实现LinkLink(ctx, file, args) (*model.Link, error)返回文件下载链接/本地路径/读取流必实现可选方法标注optionalMakeDir建目录、Move移动、Rename重命名、Copy复制、Remove删除、Put上传、GetArchiveMeta/ListArchive/Extract/ArchiveDecompress压缩包相关能力。未实现的可选方法统一返回errs.NotImplement框架会自动降级为内置工具处理或提示不支持。3.4 接口层驱动的契约由谁定义模板中每个方法签名都来自 internal/driver/driver.go 定义的Driver接口体系type Driver interface { Meta Reader }MetaConfig、GetStorage/SetStorage、GetAddition、Init/Dropinternal/driver/driver.goReaderList与Link两个只读核心方法internal/driver/driver.go这就是“必实现”的来源写操作通过Mkdir、Move、Rename、Copy、Remove、Put等可选接口以能力组合方式扩展internal/driver/driver.goPut接口的注释还给出了上传取消、进度上报、限速的最佳实践模板末尾有一行编译期断言var _ driver.Driver (*Template)(nil)drivers/template/driver.go确保实现始终满足接口契约。3.5 参考真实实现drivers/local是最适合对照学习的完整示例其 driver.go 中List通过readDir读取真实目录并过滤隐藏文件Link支持普通文件与缩略图两种请求drivers/local/driver.goPut用utils.CopyWithCtx实现可取消、带进度上报的写入drivers/local/driver.go。新增驱动时若目标存储 API 与某个已有驱动相近直接在 drivers/ 下寻找同名实现做参照会事半功倍。四、创建符合规范的提交Commit MessageCONTRIBUTING.md 要求提交信息必须格式化、标准化采用业界常见的 Conventional Commits 风格。4.1 总体格式type(scope): subject BLANK LINE body BLANK LINE footerheader必填其中scope可选任何一行不得超过 100 个字符以便在 GitHub 与各类 git 工具中清晰阅读4.2 Type提交类型必须为下表之一原文定义见 CONTRIBUTING.mdType含义feat新功能fix修复缺陷docs仅文档变更style不影响代码语义的格式调整空白、缺失分号等refactor既不修复缺陷也不增加功能的代码重构perf性能改进test补充缺失或修正已有测试build影响构建或依赖变更revert还原某次提交ci持续集成相关文件修改chore构建流程、辅助工具与库的变更如文档生成release发布新版本4.3 Scope作用域scope指明变更所在位置例如$location、$browser、$compile、$rootScope、ngHref、ngClick、ngView等。结合 alist 的实际目录结构实践中可自然使用如drivers/local、server/webdav、cmd等作为作用域当变更影响多个作用域时使用*。4.4 Subject主题行主题行是对变更的简洁描述必须遵守三条规则使用祈使句、一般现在时写change不写changed或changes首字母不大写末尾不加句号.4.5 Body正文与 Subject 相同正文同样使用祈使句、一般现在时。正文应包含变更动机并与变更前的行为形成对比让审阅者理解“为什么要改、怎么改的”。4.6 Footer页脚页脚承载两类信息破坏性变更必须以BREAKING CHANGE:开头后跟一个空格或两个换行其余部分作为详细说明关闭 Issue 的引用可在此引用本次提交所关闭的 GitHub Issue4.7 Revert还原提交若提交用于还原之前的某次提交必须以revert:开头并紧跟被还原提交的 header正文中需写明This reverts commit hash.其中hash为被还原提交的 SHA。一个符合规范的提交示例综合上述规则feat(drivers/local): support recycle bin path for remove move deleted files into configured recycle bin instead of permanently deleting them, so users can recover accidental removals. BREAKING CHANGE: remove behavior changes when recycle_bin_path is configured. This reverts nothing.五、提交 Pull Request完成开发与本地验证后按以下流程提交贡献CONTRIBUTING.md将本地分支推送到你的alistfork 仓库在 GitHub 上向上游alist仓库的main分支发起 Pull Request在 PR 描述中说明变更动机、实现方式与验证结果配合符合上一节规范的提交信息便于维护者高效审阅建议在提交 PR 前先在本地完整跑通一次后端go run main.go与前端pnpm dev确认新驱动能正常列出、预览与操作文件再进入提交流程。小结本文围绕 CONTRIBUTING.md 展开从环境搭建、源码克隆、前后端预览到基于 drivers/template 新增存储驱动、编写规范提交信息、提交 PR给出了 alist 贡献者的完整工作流。其中“新增驱动”是 alist 扩展能力的核心路径理解 internal/driver/driver.go 的接口契约、参考 drivers/local 的真实实现再配合 drivers/all.go 的注册机制你就能把任意一个云存储/网盘后端接入 alist。更多细节可继续阅读仓库内各驱动的实现与测试文件。赞分享后端文件存储【免费下载链接】alist️A file list/WebDAV program that supports multiple storages, powered by Gin and Solidjs. / 一个支持多存储的文件列表/WebDAV程序使用 Gin 和 Solidjs。项目地址https://gitcode.com/GitHub_Trending/al/alist点击查看免费下载相关推荐OmniRoute 贡献指南从本地开发环境搭建到新增 Provider 的完整工程工作流OmniRoute 贡献指南从本地开发环境搭建到新增 Provider 的完整工程工作流 本文以 docs/i18n/id/CONTRIBUTING.md h后端API网关LLM 网关人工智能大模型MCP 服务桌面应用OmniRoute 贡献指南从本地开发环境搭建到新增 AI Provider 的完整实战流程OmniRoute 贡献指南从本地开发环境搭建到新增 AI Provider 的完整实战流程 OmniRoute 是一个开源的统一 AI 网关MIT Lic后端API网关LLM 网关人工智能大模型MCP 服务桌面应用Element Plus 贡献指南从环境搭建、本地开发到提交 PR 的完整流程Element Plus 贡献指南从环境搭建、本地开发到提交 PR 的完整流程 Element Plus 是一个使用 TypeScript 编写的 Vue 3前端UI组件上一篇Dagger TypeScript SDK 深度指南ContainerWithMountedCacheOpts 缓存卷挂载选项全解析下一篇OpenMed Agent Skills 捆绑包导出与安装离线、确定性与可审计的 Skill 分发实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考