企业官网建设流程全解析

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

【免费下载链接】gopeedA fast, modern download manager for HTTP, BitTorrent, Magnet, and ed2k. Cross-platform, built with Golang and Flutter.项目地址: https://gitcode.com/GitHub_Trending/go/gopeed

本文以 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：

用法示例（与 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 工具表

从 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）：

典型自托管启动：

# 启用 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 git@github.com: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 用自然语言管理下载任务，都能在本文所述的安装、配置与构建流程中找到对应的落地路径。

【免费下载链接】gopeedA fast, modern download manager for HTTP, BitTorrent, Magnet, and ed2k. Cross-platform, built with Golang and Flutter.项目地址: https://gitcode.com/GitHub_Trending/go/gopeed