后端文件存储【免费下载链接】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点击查看免费下载本指南以仓库中 pkg/aria2/rpc/README.md 的包文档为骨架系统讲解 Alist 内置的 aria2 JSON-RPC 客户端库从客户端初始化、全量 RPC 方法语义新增下载、状态查询、配置管理、队列控制、会话维护与批量调用到 HTTP/WebSocket 双传输层、通知机制与 JSON-RPC 2.0 编解码等源码级实现并给出该包在 Alist 离线下载模块中的真实集成范例。读完本文你将能够独立使用或二次封装这套客户端把 aria2 的完整能力接入自己的 Go 服务。一、包定位一份 Go 语言实现的 aria2 JSON-RPC 客户端pkg/aria2/rpc是 Alist 仓库中独立维护的 aria2 RPC 客户端库其包文档以 godoc 风格写成见 pkg/aria2/rpc/README.md完整覆盖了 aria2 守护进程aria2 daemon即通过aria2c --enable-rpc启动的服务端暴露的全部 RPC 方法新增下载、暂停/继续/删除、状态查询、选项配置、队列调整、会话关闭等。在 Alist 中的实际应用场景非常明确它服务于**离线下载offline download**功能。internal/offline_download/aria2/aria2.go通过本包连接 aria2 守护进程把远程 URL 交给 aria2 下载后再取回文件并实时跟踪任务进度。需要特别说明的一点是README 记录的是该包早期版本的 API 形态如顶层Call(address, method, params, reply)函数、New(uri string) *Client构造函数而当前仓库源码中的接口已经演化——New增加了ctx、token、timeout、notifier参数并返回(Client, error)Call演化为caller接口方法。下文将以当前仓库源码为准同时保留 README 中与行为语义相关的完整描述。二、快速开始建立与 aria2 守护进程的连接README 中记录的构造方式为func New(uri string) *Client而当前源码的签名是见 pkg/aria2/rpc/client.go#L32-L52func New(ctx context.Context, uri string, token string, timeout time.Duration, notifier Notifier) (Client, error)参数含义如下参数说明ctx控制客户端生命周期Close()时会基于它取消内部 goroutineuriaria2 RPC 端点支持http、https、ws、wss四种 schemetokenaria2 的 RPC 密钥对应启动参数--rpc-secret为空则匿名访问timeout连接与单次调用的超时时间notifier事件通知处理器接收 aria2 推送的下载事件可为 nil典型的初始化代码ctx : context.Background() client, err : rpc.New(ctx, http://localhost:6800/jsonrpc, my-secret-token, 4*time.Second, rpc.DummyNotifier{}) if err ! nil { log.Fatalf(connect aria2 failed: %v, err) } defer client.Close() version, err : client.GetVersion() // 校验连通性 if err ! nil { log.Fatalf(get aria2 version failed: %v, err) }这里给出的是常用端点http://localhost:6800/jsonrpcaria2 默认监听地址。New内部通过url.Parse解析 uri再根据 scheme 分发到不同的传输层实现无法识别的 scheme 会返回errInvalidParameter。2.1 Token 的自动注入机制源码中所有方法的参数组装都遵循同一模式以 AddURI 实现 为例只要c.token非空就在参数列表最前面插入token:c.token再拼上业务参数。因此调用方无需手工传 token这正是 aria2 RPC 规定的鉴权参数格式aria2.addUri([secret, ]uris[, options[, position]])中方括号内的secret部分。三、底层调用函数 Call 与 JSON-RPC 2.0 编解码README 将Call列为包的顶层函数func Call(address, method string, params, reply interface{}) error。在当前的源码结构里它被定义为caller接口方法见 pkg/aria2/rpc/call.go#L17-L21由httpCaller与websocketCaller两个实现分别承担 HTTP 与 WebSocket 两种通道的请求收发type caller interface { Call(method string, params, reply interface{}) (err error) Close() error }无论走哪条通道请求与响应都遵循 JSON-RPC 2.0 协议编解码实现在 pkg/aria2/rpc/json2.goEncodeClientRequest(method, args)组装{jsonrpc:2.0,method:...,params:...,id:...}请求体id 由包内的原子自增函数reqid()生成DecodeClientResponse(r, reply)解析响应体若error字段非空则反序列化为rpc.Error并返回result为空则返回ErrNullResult。协议层的错误码定义如下见 json2.go#L91-L98错误码常量含义-32700E_PARSE解析错误-32600E_INVALID_REQ无效请求-32601E_NO_METHOD方法不存在-32602E_BAD_PARAMS参数无效-32603E_INTERNAL内部错误-32000E_SERVER服务端错误四、新增下载AddUri / AddTorrent / AddMetalink4.1 AddUri添加 HTTP(S)/FTP/Magnet 下载对应 RPC 方法aria2.addUri(uris[, options[, position]])Go 封装签名client.go#L63func (c *client) AddURI(uris []string, options ...interface{}) (gid string, err error)要点uris是字符串数组所有 URI 必须指向同一个文件。如果混入指向其他文件的 URIaria2 不会报错但下载很可能失败若要添加 BitTorrent Magnet URIuris只能有一个元素且必须是 Magnet 链接options是map[string]interface{}形式的键值对如{dir: /data/downloads}对应 aria2 的输入文件选项position为从 0 开始的整数新下载插入等待队列的指定位置不传或大于队列长度时追加到队尾返回值为新注册下载的 GID下载全局唯一标识。4.2 AddTorrent上传 .torrent 文件对应aria2.addTorrent(torrent[, uris[, options[, position]]])Go 封装client.go#L91func (c *client) AddTorrent(filename string, options ...interface{}) (gid string, err error)参数是本地 .torrent 文件的路径源码内部用os.ReadFile读出字节后做base64.StdEncoding编码再作为torrent参数发送若想添加 Magnet URI请改用AddURI而不是本方法uris用于 Web-seeding单文件种子中 URI 可以是指向资源的完整链接若以/结尾则自动拼接种子内的文件名多文件种子则按种内的 name 和 path 逐文件拼出 URI与 AddUri 相同的options、position语义返回单个 GID。4.3 AddMetalink上传 .metalink 文件对应aria2.addMetalink(metalink[, options[, position]])Go 封装client.go#L122func (c *client) AddMetalink(filename string, options ...interface{}) (gid []string, err error)参数同样为本地文件路径内部 base64 编码后上传与 AddTorrent 不同Metalink 可能包含多个下载项因此返回 GID 数组。4.4 rpc-save-upload-metadata 与元数据落盘三条上传类方法Torrent/Metalink共享同一个行为细节若 aria2 启动参数--rpc-save-upload-metadata为 true上传的数据会以「SHA-1 哈希的十六进制串 扩展名」命名保存到--dir指定的目录例如0a3893293e27ac0490424c06de4d09242215f0a6.torrent 0a3893293e27ac0490424c06de4d09242215f0a6.metalink同名文件已存在时会被覆盖若保存失败或该开关为 false则这些方法添加的下载不会写入--save-session的会话文件中重启后无法恢复。五、下载生命周期控制暂停、继续、删除这一组方法负责对已注册的下载执行状态流转全部以 GID 为操作句柄Go 方法RPC 方法行为Pause(gid)aria2.pause暂停指定下载若正在下载则移到等待队列第一位返回被暂停的 GIDForcePause(gid)aria2.forcePause同pause但跳过耗时动作如联系 BitTorrent tracker 注销立即暂停PauseAll()aria2.pauseAll对所有 active/waiting 下载执行pause成功返回OKForcePauseAll()aria2.forcePauseAll对所有下载执行forcePause成功返回OKUnpause(gid)aria2.unpause将下载状态从 paused 改为 waiting使其可重新开始返回 GIDUnpauseAll()aria2.unpauseAll对所有下载执行unpause成功返回OKRemove(gid)aria2.remove移除下载进行中的任务先停止状态变为 removed返回 GIDForceRemove(gid)aria2.forceRemove同remove但跳过耗时动作立即移除普通方法与 Force 版本的本质区别在于是否等待 tracker 注销等耗时操作——普通版更优雅但更慢Force 版更激进、响应更快。源码中这组方法均通过 const.go 中定义的方法名常量如aria2Pause aria2.pause调用每个方法都会在参数头部注入token:前缀。六、状态与进度查询6.1 TellStatus单任务详情对应aria2.tellStatus(gid[, keys])Go 封装client.go#L256func (c *client) TellStatus(gid string, keys ...string) (info StatusInfo, err error)keys为字符串数组指定后响应只包含所列键keys为空或省略则返回全部字段可用于减少不必要的数据传输。例如TellStatus(2089b05ecca3d829, gid, status)只返回gid和status返回的StatusInfo结构体定义在 pkg/aria2/rpc/resp.go#L6-L36核心字段如下字段说明gid下载全局唯一标识statusactive下载/做种中、waiting队列中未开始、paused已暂停、error出错停止、complete完成、removed被用户移除totalLength/completedLength/uploadLength总长度 / 已完成 / 已上传字节downloadSpeed/uploadSpeed下载 / 上传速度字节/秒bitfield下载进度的十六进制位图最高位对应第 0 个 pieceinfoHash/numSeeders/seederBitTorrent 专属InfoHash、已连接做种数、本端是否做种者connections已连接的 peer/server 数量errorCode/errorMessage停止下载的错误码与可读错误信息仅 stopped/completed 任务followedBy本下载衍生出的 GID 列表如 Metalink 的 follow-metalink 行为belongsTo父下载的 GID如 Metalink 内文件包含的 torrent 下载files文件列表元素结构与GetFiles返回一致bittorrent种子信息announceList、comment、creationDate、mode、info.name6.2 TellActive / TellWaiting / TellStopped队列浏览三者都返回[]StatusInfo元素结构与tellStatus相同区别在于查询的集合不同TellActive(keys ...string)当前正在进行的下载列表TellWaiting(offset, num int, keys ...string)等待队列含已暂停中的下载TellStopped(offset, num int, keys ...string)已停止的下载offset从最旧的停止任务算起。offset/num的语义值得单独说明README 中以等待队列为例offset为正整数时返回[offset, offsetnum)区间offset可以为负-1指向队尾最后一个下载-2指向倒数第二个依此类推且返回顺序反转。假设等待队列依次为 A、B、Caria2.tellWaiting(0, 1) - [A] aria2.tellWaiting(1, 2) - [B, C] aria2.tellWaiting(-1, 2) - [C, B]6.3 文件与连接明细GetFiles / GetUris / GetPeers / GetServersGo 方法RPC 方法返回内容GetFiles(gid)aria2.getFiles[]FileInfo每个文件含index从 1 起、path、length、completedLength、selected及该文件的 URI 列表。注意getFiles的 completedLength 只统计完整 piece可能小于tellStatus的 completedLengthGetURIs(gid)aria2.getUris[]URIInfoURI 及其状态used使用中/waiting排队中GetPeers(gid)aria2.getPeers[]PeerInfo仅 BitTorrentpeerId、IP、端口、bitfield、amChoking/peerChoking、双向速度、是否做种者GetServers(gid)aria2.getServers[]ServerInfo当前连接的 HTTP(S)/FTP 服务器含原始 URI、经重定向后的当前 URI、下载速度6.4 全局统计与信息GetGlobalStat / GetVersion / GetSessionInfoGetGlobalStat()返回GlobalStatInfodownloadSpeed、uploadSpeed、numActive、numWaiting、numStopped受--max-download-result上限约束、numStoppedTotal不受约束的累计值GetVersion()返回VersionInfoaria2 版本号字符串与启用的功能特性列表enabledFeaturesGetSessionInfo()返回SessionInfo每次启动 aria2 时生成的sessionId。七、动态配置管理GetOption / ChangeOption / GetGlobalOption / ChangeGlobalOption7.1 任务级选项GetOption(gid)返回指定下载的选项Option即map[string]interface{}。README 明确指出没有默认值且未通过命令行/配置文件/RPC 设置过的选项不会出现在响应中ChangeOption(gid, option)动态修改下载选项。**活动下载active**仅支持下列选项bt-max-peers bt-request-peer-speed-limit bt-remove-unselected-file force-save max-download-limit max-upload-limit对于waiting 或 paused下载除上述选项外还支持输入文件小节Input File列出的选项但以下除外dry-run、metalink-base-uri、parameterized-uri、pause、piece-length、rpc-save-upload-metadata。成功返回OK。7.2 全局级选项GetGlobalOption()返回全局选项由于全局选项是新下载的模板响应中的键集合与getOption一致ChangeGlobalOption(options)动态修改全局选项可用列表README 版本download-result log log-level max-concurrent-downloads max-download-result max-overall-download-limit max-overall-upload-limit save-cookies save-session server-stat-of当前源码版本还额外支持bt-max-open-files见 client.go#L499-L529。此外除checksum、index-out、out、pause、select-file之外Input File 小节的选项也均可用。细节通过log选项可以动态开始记录日志或更换日志文件传空字符串即停止记录日志日志文件始终以追加模式打开。成功返回OK。八、队列与 URI 管理ChangePosition / ChangeUri8.1 ChangePosition调整队列位置对应aria2.changePosition(gid, pos, how)func (c *client) ChangePosition(gid string, pos int, how string) (p int, err error)how有三种取值取值语义POS_SET相对队列开头移动POS_CUR相对当前位置移动POS_END相对队列末尾移动目标位置小于 0 或超出队尾时分别移到队首或队尾。返回值p为移动后的最终位置。示例若 GID2089b05ecca3d829当前在位置 3则ChangePosition(2089b05ecca3d829, -1, POS_CUR)将其移到位置 2ChangePosition(2089b05ecca3d829, 0, POS_SET)将其移到队首位置 0。8.2 ChangeUri增删任务的 URI对应aria2.changeUri(gid, fileIndex, delUris, addUris[, position])func (c *client) ChangeURI(gid string, fileindex int, delUris []string, addUris []string, position ...int) (p []int, err error)一个下载可能含多个文件URI 附着在文件上fileIndex用于选择操作哪个文件从 1 开始position从 0 开始指定新 URI 插入现有等待 URI 列表的位置省略时追加到列表末尾方法先执行删除再执行添加因此position指的是删除完成之后的位置删除同名 URI 时每个delUris元素只删除一个匹配项——若存在 3 个http://example.org/aria2而要全部删除delUris中至少要写 3 次该 URI返回[]int第一个整数是删除的 URI 数量第二个是添加的 URI 数量。九、会话维护与关闭PurgeDownloadResult / RemoveDownloadResult / SaveSession / ShutdownPurgeDownloadResult()清空已完成/出错/被移除的下载记录以释放内存返回OKRemoveDownloadResult(gid)从内存移除指定 GID 的完成/出错/移除记录返回OKSaveSession()将会话立即保存到--save-session指定的文件该能力在 client.go#L633 中有封装README 未列出属于当前源码的补充实现Shutdown()优雅关闭 aria2返回OKForceShutdown()同Shutdown但跳过耗时动作如向 tracker 注销立即关闭。十、批量调用与能力发现Multicall / ListMethodsMulticall(methods)对应system.multicall把多个方法调用封装进单个请求。methods是[]Method每个元素含methodName方法名与params参数数组。返回值为响应数组每个元素要么是单元素数组方法返回值要么在调用失败时是 fault 结构体。源码实现client.go#L649-L656要求methods非空否则返回errInvalidParameterListMethods()对应system.listMethods返回全部可用 RPC 方法名字符串数组。与其它方法不同它不需要 secret token——仅返回方法名无安全风险。十一、传输层与通知机制源码级剖析11.1 HTTP 通道请求-响应模式httpCallerpkg/aria2/rpc/call.go#L23-L135每次调用都执行一次POST请求EncodeClientRequest编码请求体 →http.Client.Post发送 →DecodeClientResponse解码响应。其http.Transport做了连接复用配置MaxIdleConnsPerHost: 1、KeepAlive: 60s、3 秒 TLS 握手超时ResponseHeaderTimeout与调用方传入的timeout一致。HTTP 通道还内置了一个通知监听能力在setNotifier中额外建立一条ws://连接用于接收推送事件scheme 从原 uri 推导http变ws。11.2 WebSocket 通道全双工与并发控制websocketCallercall.go#L137-L261维持一条长连接内部有两条 goroutinerecv 协程循环ReadJSON。无id的消息是 RPC 通知push 事件转交Notifier带id的消息交给ResponseProcessor按 id 匹配回调send 协程从容量 16 的sendChan取出请求先向ResponseProcessor注册 id 对应的回调再WriteJSON发送。每个请求 id 由原子自增的reqid()生成调用方通过context.WithTimeout控制单次调用超时发送通道写满时会立即返回sending channel blocking错误。ResponseProcessorpkg/aria2/rpc/proc.go内部用sync.RWMutex保护的 map 维护 id→回调的映射处理完即删除保证响应与请求一一对应。11.3 事件通知Notifier 接口aria2 守护进程会单向推送事件通知无 id客户端不应回复。包内定义了六个事件pkg/aria2/rpc/notification.go通知方法Notifier 回调触发时机aria2.onDownloadStartOnDownloadStart下载开始aria2.onDownloadPauseOnDownloadPause下载暂停aria2.onDownloadStopOnDownloadStop用户停止下载aria2.onDownloadCompleteOnDownloadComplete下载完成BT 下载指完成且做种结束aria2.onDownloadErrorOnDownloadError下载因错误停止aria2.onBtDownloadCompleteOnBtDownloadCompleteBT 下载完成但仍在做种事件参数为[]EventEvent仅含Gid字段。包内提供DummyNotifier作为默认实现仅打印日志生产代码应实现Notifier接口来响应真实事件Alist 正是通过它把 aria2 的任务状态同步到自己的任务系统。十二、在 Alist 中的实际集成与测试验证12.1 离线下载模块的调用范式Alist 的离线下载工具在 internal/offline_download/aria2/aria2.go 中注册名为aria2的下载工具其用法可视为本包的权威实战模板配置项Aria2Uri默认http://localhost:6800/jsonrpc与Aria2Secret两个设置项初始化Init()中以4*time.Second超时调用rpc.New(ctx, uri, secret, timeout, notify)并立即GetVersion()校验连通性失败则返回错误并置空 client添加任务AddURL将dir选项指向临时目录后调用client.AddURI([]string{url}, options)返回的 GID 与任务信号一起存入通知器任务控制Remove调用client.Remove(gid)Status通过TellStatus轮询进度详见该文件剩余实现。12.2 测试用例仓库自带针对两个传输层的集成测试pkg/aria2/rpc/client_test.go 中的TestHTTPAll/TestWebsocketAll分别以http://localhost:6800/jsonrpc与ws://localhost:6800/jsonrpc为端点走完「AddURI → TellActive → PauseAll → TellStatus → GetURIs → GetFiles → GetPeers → TellWaiting → TellStopped → GetOption → GetGlobalOption → GetGlobalStat → GetSessionInfo → Remove」的完整调用链覆盖了 README 中绝大多数方法pkg/aria2/rpc/call_test.go 则针对编解码与错误处理做单元级验证。运行这些测试需要本地已启动启用了 RPC 的 aria2 实例对纯编解码逻辑的验证则无需外部依赖。结语pkg/aria2/rpc是一个麻雀虽小五脏俱全的 aria2 RPC 客户端对外它完整复刻了 aria2 的全部 JSON-RPC 方法语义新增、控制、查询、配置、队列、会话、批量README 中的每一条方法说明都能在 client.go、proto.go 与 resp.go 中找到对应的实现与结构化返回类型对内它通过 HTTP 与 WebSocket 双通道设计、ResponseProcessor的请求-响应匹配机制以及Notifier事件接口为 Alist 的离线下载功能提供了稳定可靠的底层支撑。无论是想为自有 Go 服务接入 aria2还是想理解 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点击查看免费下载相关推荐Polar 前端工程实践为什么不能在组件内部定义组件——React 重渲染优化规则深度解析Polar 前端工程实践为什么不能在组件内部定义组件——React 重渲染优化规则深度解析 导读 本文深度解析 Vercel React 性能最佳实践体系中的后端对象存储Ghost Downloader 3 能替代 Aria2 吗Aria2 兼容 RPC 协议深度解析Ghost Downloader 3 能替代 Aria2 吗Aria2 兼容 RPC 协议深度解析 Ghost Downloader 3 是一款跨平台的下载管桌面应用网络插件系统aria2 RPC远程控制接口详解aria2 RPC远程控制接口详解 本文深入解析aria2的远程过程调用RPC接口架构涵盖JSON RPC、XML RPC和WebSocket三种协议实现CLI网络上一篇GET3D与其他3D生成模型的终极对比分析技术优势与应用场景详解下一篇10倍提升Flutter开发效率Dart Code插件深度优化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考