Gopeed（Go Speed）下载器全解析：多协议下载内核、AI 接入与跨平台构建实战

本文以 README_zh-CN.md 为主线，结合仓库源码，系统讲解 Gopeed 的协议能力、任务管理、AI（MCP）接入、Web 服务部署、CLI 使用与桌面/移动/Web 三端构建流程。读完你既能快速上手安装使用，也能理解其 Go + Flutter 双端架构与核心实现。

项目概览：Go Speed，够快下载器

Gopeed（全称 Go Speed，中文名"够快下载器"）是一款使用 Go 与 Flutter 开发的高速、现代、免费开源下载器，支持 HTTP、HTTPS、BitTorrent、磁力链接（Magnet）和 ed2k 协议，覆盖桌面端（Windows / macOS / Linux）、移动端（Android / iOS）与 Web 端。

除日常下载任务管理外，Gopeed 还提供浏览器接管、JavaScript 扩展、REST API、命令行工具和可自托管 Web UI，便于高级用户扩展与自动化自己的下载流程。项目采用 GPLv3 协议开源，中文版文档还包括 English、日本語、正體中文、Tiếng Việt 等多个语言版本。

核心特性一览

• 高速下载 — 多任务并发、HTTP 多连接分段传输和 BitTorrent P2P 下载，充分利用可用带宽。
• 多协议支持 — 在同一个界面管理 HTTP、HTTPS、BitTorrent、磁力链接和 ed2k。
• 完整 BT 能力 — 支持 DHT 节点发现、uTP 传输、Web Seed、按文件选择下载、Tracker 管理、Peer/分片统计，以及按分享率或时间控制做种。
• 实用任务管理 — 暂停、续传、重试、批量操作、搜索、状态筛选、下载分类和启动恢复。
• 轻量原生体验 — 主界面使用 Flutter 原生渲染，非 Electron、非 WebView 套壳，安装包更轻量、运行开销更低、响应更流畅。
• 全平台覆盖 — 支持 Windows、macOS、Linux、Android、iOS 和 Web，并提供 Docker、QNAP 部署方式。
• 个性化主题 — 支持跟随系统、浅色、深色三种模式，以及 8 种主题强调色。
• 响应式界面 — 任务列表、导航、设置和详情视图会针对手机、平板及可调整大小的桌面窗口自动布局。
• 20+ 种界面语言 — 支持简体中文、繁体中文、英语、日语、韩语等多种语言（界面语言资源位于 ui/flutter/lib/l10n）。
• 浏览器接管 — 支持 Chrome、Edge、Firefox 等兼容浏览器，将下载任务直接发送到 Gopeed。
• JavaScript 扩展 — 扩展视频网站、AI 模型站、网盘等更多下载源（扩展引擎基于 goja，见 pkg/download/extension_engine.go 与 internal/controller）。
• AI 接入 — 开放 MCP 接口，可接入 AI Agent，通过自然语言创建、查询和管理下载任务。
• 开放接口 — 通过 REST API、CLI、带身份认证的 Web UI、Webhook 和下载后脚本进行自动化。
• 常用内置能力 — 自定义 Header 与 User-Agent、代理、GitHub 镜像、通知和自动解压。

架构：Go 核心 + Flutter 前端

README 明确指出本项目分为前端和后端两部分：前端使用 Flutter，后端使用 Golang，两边通过 HTTP 协议通讯；在 Unix 系统下使用 unix socket，在 Windows 系统下使用 tcp 协议。前端代码位于 ui/flutter 目录。

Gopeed 2.0 进一步引入了通过 FFI 直连 Go 核心的原生通信架构。桌面端通过 cgo 将 Go 核心编译为动态库（libgopeed.dll / libgopeed.dylib / libgopeed.so），导出 Start、Stop、Invoke、SubscribeTaskEvents、FreeCString 等 C 函数供 Flutter 侧直接调用，见 bind/desktop/main.go；移动端则通过 gomobile bind 生成 Android AAR 与 iOS XCFramework，入口在 bind/mobile/main.go。项目还保留了一套基于 webview 的扩展运行时（internal/webview 与 pkg/download/engine/webview），用于执行 JavaScript 扩展脚本。

值得注意的是，Gopeed 2.0.0 目前处于公开 Beta 测试阶段，引入了全新界面、原生通信架构、更一致的多端体验、更完善的任务管理、更灵活的 API，以及用于 AI Agent 接入的 MCP 能力。已安装 Beta 版本的用户可直接升级到最终正式版，现有稳定版用户不会被自动切换到 Beta 渠道。

安装与获取

正式稳定版

• 官方网站下载：https://gopeed.com
• GitHub Releases 发布页：https://github.com/GopeedLab/gopeed/releases/latest

Gopeed 2.0.0 Beta

Beta 版本可从 https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.1 下载。部分功能可能仍不够完善或稳定，欢迎提前体验并向项目反馈问题。

命令行工具（go install）

go install github.com/GopeedLab/gopeed/cmd/gopeed@latest

安装后即可用 gopeed 命令直接下载。命令入口位于 cmd/gopeed/main.go，参数解析见 cmd/gopeed/flags.go：

参数	默认值	说明
-C	16	HTTP 并发连接数（Concurrent connections）。
-D	当前工作目录	下载存储目录（Store directory）。
位置参数	无	下载地址，支持 URL、.torrent 文件与磁力链接。

用法示例（与 cmd/gopeed/flags.go 中的提示信息一致）：

gopeed https://www.google.com
gopeed bt.torrent
gopeed magnet:?xt=urn:btih:...
gopeed -C 32 -D /data/downloads https://example.com/file.zip

从源码看，CLI 会通过 download.Boot().URL(...).Listener(...).Create(...) 创建任务，并将 http.OptsExtra{Connections: *args.connections} 传入选项，监听进度事件后在终端渲染 ■/□ 字符构成的进度条，任务完成或失败时输出保存路径或失败原因。官方还提供了最小可运行示例，见 _examples/basic/main.go：

package main

import (
	"fmt"

	"github.com/GopeedLab/gopeed/pkg/base"
	"github.com/GopeedLab/gopeed/pkg/download"
	"github.com/GopeedLab/gopeed/pkg/protocol/http"
)

func main() {
	finallyCh := make(chan error)
	_, err := download.Boot().
		URL("https://www.baidu.com/index.html").
		Listener(func(event *download.Event) {
			if event.Key == download.EventKeyFinally {
				finallyCh <- event.Err
			}
		}).
		Create(&base.Options{
			Extra: http.OptsExtra{
				Connections: 8,
			},
		})
	if err != nil {
		panic(err)
	}
	err = <-finallyCh
	if err != nil {
		fmt.Printf("download fail:%v\n", err)
	} else {
		fmt.Println("download success")
	}
}

Docker / 自托管部署

仓库提供了 Dockerfile 与 docker-compose.yml。Dockerfile 使用 golang:1.25.4-alpine3.22 构建，以 CGO_ENABLED=0 go build -tags nosqlite,web 编译 cmd/web，运行阶段基于 alpine:3.23，暴露 9999 端口，存储卷挂载在 /app/storage。入口脚本 entrypoint.sh 支持通过 PUID、PGID、UMASK 环境变量控制容器内运行身份与文件权限，外部参数通过 ./gopeed "$@" 透传。

典型的自托管启动方式（以 docker-compose 或 docker run 为例）：

docker run -d \
  -p 9999:9999 \
  -v /path/to/storage:/app/storage \
  -e PUID=1000 -e PGID=1000 \
  gopeed/gopeed \
  --address 0.0.0.0 --port 9999

浏览器接管扩展

Gopeed 提供浏览器扩展用于接管浏览器下载，支持 Chrome、Edge、Firefox 等浏览器。扩展将下载任务直接发送给本地或自托管的 Gopeed 实例。浏览器扩展的宿主逻辑在 UI 侧实现（见 ui/flutter/lib/util/browser_extension_host），可直接参考官方扩展仓库进行安装与配置。

AI 接入：MCP 服务器与自然语言下载

Gopeed 2.0 开放 MCP（Model Context Protocol） 接口，可将 Gopeed 接入 AI Agent，通过自然语言创建、查询和管理下载任务。例如直接对 AI Agent 说：

帮我下载最新的 Gopeed Windows 客户端

MCP 服务器实现位于 pkg/mcpserver/server.go，基于 github.com/modelcontextprotocol/go-sdk（见 go.mod），以无状态 Streamable HTTP Handler 方式对外提供，工具全部注册在 registerTools 中，并带有 JSON Schema 输入校验（协议相关的 extra 使用 oneOf 联合结构区分 HTTP 与 BitTorrent 参数，避免 MCP 客户端误读）。

可用 MCP 工具表

Tool	功能说明
resolve_task	解析下载 URL 或 URI，在创建任务前返回资源信息及文件列表。
create_task	使用已解析的资源 ID 或直接下载请求创建并启动任务。
list_tasks	查询任务列表，并可按任务 ID 或状态筛选。
get_task	获取单个任务的请求、资源、选项及当前进度等完整信息。
get_task_status	获取单个任务的轻量运行状态和各文件下载进度。
get_task_stats	获取协议相关统计信息，包括 HTTP 连接或 BitTorrent Peer 与做种数据。
pause_task	暂停任务。
continue_task	继续已暂停或失败的任务。
delete_task	删除任务，并可选择同时删除已下载文件。

从 pkg/mcpserver/server.go 源码可以看出几个关键行为：

• create_task 接受两种方式：传入 rid（resolve_task 返回的资源 ID）时调用 downloader.Create(rid)；传入 req 时调用 downloader.CreateDirect(req, opts)。
• list_tasks 支持 id、status、notStatus 过滤，任务状态枚举见 pkg/base/constants.go：ready（已创建未开始）、running、pause、wait（等待运行）、error、done。
• delete_task 的 force 参数为 true 时会同时删除磁盘上的已下载文件，否则仅删除任务记录。
• get_task_stats 返回协议相关统计：HTTP 对应连接数，BT 对应 Peer 与做种数据。

如何启用 MCP

Web 服务（自托管模式）通过启动参数开启 MCP 端点（见 cmd/web/flags.go 与 cmd/web/main.go）：

gopeed --mcp-enable --address 0.0.0.0 --port 9999

对应环境变量为 GOPEED_MCPENABLE=true（配置加载顺序为：命令行参数 → 配置文件 → 环境变量 GOPEED_ 前缀 → 非默认命令行参数覆盖，见 cmd/web/flags.go）。

REST API 与 Webhook

除 MCP 外，Gopeed 还提供 REST API 与 Webhook。REST 层实现在 pkg/rest，路由定义见 pkg/api/routes.go 与 pkg/rest/server.go。当启用 Web 身份认证后，调用 HTTP API 需要配置 API Token（见下文 Web 服务参数）。Webhook 配置与下载后脚本可参考 pkg/download/webhook.go 与 pkg/download/script.go。

自托管 Web UI 服务参数

Web 端服务通过 cmd/web 提供，支持命令行、配置文件（默认 ./config.json，可用 -c/--config 指定）与环境变量（GOPEED_ 前缀）三种配置来源。核心参数如下（源码依据 cmd/web/flags.go）：

短参数	长参数	默认值	说明
-A	--address	0.0.0.0	绑定地址。
-P	--port	9999	绑定端口。
-u	--username	gopeed	Web 认证用户名。
-p	--password	空	Web 认证密码，不设置则不启用 Web 认证。
-T	--api-token	空	API Token，启用 Web 认证后调用 HTTP API 时必须配置。
-d	--storage-dir	可执行文件目录下 storage	存储目录。
	--white-download-dirs	空	允许的下载目录白名单，逗号分隔。
-c	--config	./config.json	配置文件路径。
	--mcp-enable	false	启用 MCP 端点。

典型自托管启动：

# 启用 Web 认证 + API Token + MCP
gopeed --address 0.0.0.0 --port 9999 \
  --username admin --password your-password \
  --api-token your-token \
  --mcp-enable \
  --storage-dir /data/gopeed/storage

从 cmd/web/main.go 源码看，Web 构建产物通过 //go:embed dist/* 嵌入二进制，ProductionMode: true、Storage: model.StorageBolt（bbolt 存储，见 go.mod 中的 go.etcd.io/bbolt），并支持 WhiteDownloadDirs 目录白名单约束。

多协议下载内核速览

Gopeed 的协议实现集中在 internal/fetcher（注册与抽象）和 internal/protocol（各协议具体实现）：

• HTTP/HTTPS：实现在 internal/protocol/http，支持多连接分段下载（Op tsExtra.Connections）、Range 请求（相关头定义见 pkg/base/constants.go）、自定义 Header、User-Agent 与代理；HTTP 任务选项（连接数、autoTorrent、autoExtract、压缩包密码等）在 MCP 层以 httpTaskExtra 暴露（见 pkg/mcpserver/server.go）。
• BitTorrent / 磁力链接：实现在 internal/protocol/bt，基于 github.com/anacrolix/torrent（go.mod），支持 DHT 节点发现、uTP、Web Seed、Tracker 管理与做种控制；配置项见 internal/protocol/bt/config.go，测试数据位于 internal/protocol/bt/testdata。
• ed2k：实现在 internal/protocol/ed2k，基于 github.com/monkeyWie/goed2k。

任务的核心数据结构定义在 pkg/base/model.go：Request（下载请求，含 URL、Labels、Proxy、SkipVerifyCert）、Resource（解析结果，含文件名、大小、是否支持 Range、文件列表与哈希）、RequestProxy（代理模式支持 follow/none/custom）。任务状态的完整枚举见 pkg/base/constants.go。扩展引擎基于 goja（github.com/dop251/goja）执行 JavaScript，相关模块见 pkg/download/extension_engine.go 与 pkg/download/engine。

开发环境与编译

环境要求

1. Golang 1.25+（当前仓库 go.mod 声明 go 1.25.4）
2. Flutter 3.41+

克隆项目

git clone [e-mail]:GopeedLab/gopeed.git

贡献代码

请参考 贡献指南。

编译桌面端

首先需要按照 Flutter Desktop 官方文档配置环境，并准备好 cgo 环境。

• Windows

go build -tags nosqlite -ldflags="-w -s" -buildmode=c-shared -o ui/flutter/windows/libgopeed.dll github.com/GopeedLab/gopeed/bind/desktop
cd ui/flutter
flutter build windows

• macOS

go build -tags nosqlite -ldflags="-w -s" -buildmode=c-shared -o ui/flutter/macos/Frameworks/libgopeed.dylib github.com/GopeedLab/gopeed/bind/desktop
cd ui/flutter
flutter build macos

• Linux

go build -tags nosqlite -ldflags="-w -s" -buildmode=c-shared -o ui/flutter/linux/bundle/lib/libgopeed.so github.com/GopeedLab/gopeed/bind/desktop
cd ui/flutter
flutter build linux

nosqlite 标签用于在桌面端关闭 sqlite 依赖，动态库导出 Start/Stop/Invoke/SubscribeTaskEvents/FreeCString 等 C 接口（见 bind/desktop/main.go），Flutter 侧通过 dart:ffi 调用（见 ui/flutter/lib/core/ffi）。

编译移动端

同样需要 cgo 环境，并安装 gomobile：

go install golang.org/x/mobile/cmd/gomobile@latest
go get golang.org/x/mobile/bind
gomobile init

• Android

gomobile bind -tags nosqlite -ldflags="-w -s -checklinkname=0" -o ui/flutter/android/app/libs/libgopeed.aar -target=android -androidapi 21 -javapkg="com.gopeed" github.com/GopeedLab/gopeed/bind/mobile
cd ui/flutter
flutter build apk

• iOS

gomobile bind -tags nosqlite -ldflags="-w -s" -o ui/flutter/ios/Frameworks/Libgopeed.xcframework -target=ios github.com/GopeedLab/gopeed/bind/mobile
cd ui/flutter
flutter build ios --no-codesign

编译 Web 端

cd ui/flutter
flutter build web
cd ../../
rm -rf cmd/web/dist
cp -r ui/flutter/build/web cmd/web/dist
go build -tags nosqlite,web -ldflags="-s -w" -o bin/ github.com/GopeedLab/gopeed/cmd/web

Web 端将 Flutter 构建产物复制到 cmd/web/dist，随后以 -tags nosqlite,web 编译并嵌入二进制（对应 cmd/web/main.go 中的 //go:embed dist/*）。仓库的 Dockerfile 采用的正是这条 nosqlite,web 构建链路，并通过 -X github.com/GopeedLab/gopeed/pkg/base.Version=$VERSION -X .../pkg/base.InDocker=true 注入版本号与容器标识。

小结

Gopeed 是一个以 Go 为核心、Flutter 为前端的现代下载器：内核层覆盖 HTTP/HTTPS 多连接分段、BitTorrent/Magnet（DHT、uTP、Web Seed、做种）与 ed2k；对外层提供 CLI（cmd/gopeed）、自托管 Web UI（cmd/web）、REST API、Webhook、JavaScript 扩展以及面向 AI Agent 的 MCP 接口（pkg/mcpserver）。无论你是想把它当作日常下载工具、自托管一个带认证的下载服务，还是通过 AI Agent 用自然语言管理下载任务，都能在本文所述的安装、配置与构建流程中找到对应的落地路径。