mirrors / mediago-dev--mediago

项目文件夹

mediago-dev--mediago
文件
master
T
caorushizi a9e3ed6a22 feat(core): switch direct downloader from gopeed to aria2 
Gopeed's last release is aging and its SChannel-linked Windows build
chokes on modern CDN TLS handshakes (we hit SEC_I_MESSAGE_FRAGMENT on
twimg.com). Replace it with aria2 — same short flags (-x/-s/-k carry
over verbatim), stricter arg handling, and well-trodden cross-platform
builds.

Binaries are vendored in-tree at extra/aria2/<os>/<arch>/ rather than
pulled from a single GitHub release, because aria2 static builds for
Linux / macOS / Windows come from different upstream repos. To keep
the deps pipeline unified:

- `scripts/download-deps.ts` grows a "source": "local" branch that
  copies from `extra/<tool>/<os>/<arch>/` into `.deps/<os>-<arch>/`
  instead of fetching from GitHub. Resulting layout matches the rest
  of the tools, so binaryResolver.ts needs no changes.
- `scripts/deps-versions.json`: `gopeed` entry removed, `aria2`
  entry added with source:"local" + path:"extra/aria2".
- `apps/core/internal/core/types.go`: BinaryNames[TypeDirect]
  `"gopeed"` → `"aria2c"`.
- `apps/core/internal/core/schema/loader.go`: direct schema's Args
  map to aria2's flags (-d / -o, plus --console-log-level=notice /
  --summary-interval=1 / --allow-overwrite=true /
  --auto-file-renaming=false for parseable output and predictable
  rerun behaviour). ConsoleReg regexes updated to aria2's summary
  line format (e.g. "DL:512KiB" for speed, "(83%)" for percent).
  `--check-certificate=false` tacked on as a workaround for the
  SChannel handshake issue on the bundled 1.19.0 Windows build —
  proper fix is upgrading the vendored binary to a build that links
  against OpenSSL (e.g. 1.37.0), comment calls that out.
- `apps/core/.env`, `Dockerfile`, `apps/electron/scripts/build.ts`,
  `apps/core/README.md`: gopeed → aria2c / aria2 references.

No DB migration: existing `type: "direct"` rows keep working, the
underlying binary just swaps.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 17:09:35 +08:00

411 行
10 KiB
Markdown
原始文件 永久链接 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
# MediaGo Core
> 多任务下载系统 - Go (Gin) 实现
## 🚀 快速导航
### 📖 核心文档
- **[快速开始（5 分钟）](QUICKSTART.md)** - 新手必读
- **[完整使用文档](README_core.md)** - API 与配置详解
- **[最终交付总结](FINAL_SUMMARY.md)** - 项目概览
### 🔧 技术文档
- **[实现总结](IMPLEMENTATION_SUMMARY.md)** - 技术细节与核心特性
- **[项目结构](PROJECT_STRUCTURE.md)** - 架构与模块关系
- **[交付清单](DELIVERY_CHECKLIST.md)** - 验收标准
---
## ⚡ 快速开始
### 使用 NPM Scripts（推荐）
```bash
# 安装依赖
pnpm install
# 查看所有可用命令
pnpm run help
# 运行开发服务器
pnpm dev
# 编译当前平台的开发版本
pnpm run build
```
### 传统方式
```bash
# 安装依赖
go mod tidy
# 运行服务
go run ./cmd/server
```
### Docker 部署
```bash
# Docker Compose
docker-compose up -d
```
---
## 🎯 核心特性
- ✅ **JSON 配置**（从 YAML 迁移）
- ✅ **进度节流**（200ms + 0.5%）
- ✅ **并发控制**（动态调整）
- ✅ **事件驱动**（SSE 实时推送）
- ✅ **Swagger 文档**（完整的 API 文档）
- ✅ **Gulp 构建系统**（模块化 TypeScript 任务）
- ✅ **Docker 支持**（一键部署）
---
## 📖 API 文档
项目集成了 **Swagger API 文档**，提供了完整的接口说明和在线测试功能。
### 访问 Swagger UI
```bash
# 1. 启动服务
gulp dev
# 2. 访问 Swagger UI
# http://localhost:8080/swagger/index.html
```
### 生成 Swagger 文档
```bash
# 安装 swag 工具
gulp devTools
# 生成文档
gulp devSwagger
# 或手动生成
swag init -g cmd/server/main.go -o docs --parseDependency --parseInternal
```
### API 端点列表
- `POST /api/tasks` - 创建下载任务
- `POST /api/tasks/:id/stop` - 停止任务
- `POST /api/config` - 更新配置
- `GET /api/events` - SSE 事件流
- `GET /swagger/*any` - Swagger UI
---
## 📦 支持的下载类型
1. **M3U8** - HLS 流媒体下载
2. **Bilibili** - B站视频下载
3. **Direct** - 直接文件下载（aria2c）
---
## 🛠️ 可用命令
### 开发任务
```bash
pnpm dev # 启动开发服务器
pnpm run build # 编译当前平台的开发版本
```
### NPM 包构建
```bash
pnpm run build:core # 构建 Core NPM 包（包含所有平台二进制）
pnpm run build:deps # 构建 Deps NPM 包（包含依赖工具）
pnpm run npm:build # 构建所有 NPM 包（Core + Deps）
# 别名（更明确的命名）
pnpm run npm:build:core # 同 build:core
pnpm run npm:build:deps # 同 build:deps
```
### NPM 包发布
```bash
pnpm run npm:publish # 发布所有 NPM 包
pnpm run npm:publish:core # 仅发布 Core NPM 包
pnpm run npm:publish:deps # 仅发布 Deps NPM 包
```
### 帮助命令
```bash
pnpm run help # 显示所有可用的 Gulp 任务和说明
pnpm run tasks # 显示 Gulp 任务树（技术视图）
```
---
## 📦 发布指南
### 1. 开发阶段
```bash
# 启动开发服务器
pnpm dev
# 快速编译当前平台
pnpm run build
```
### 2. 构建 NPM 包
`pnpm run npm:build` 会执行以下步骤：
1. 清理旧的构建产物
2. 构建所有平台的二进制文件
3. 生成 NPM 包的 package.json、README 和 install.js
4. 复制二进制文件和依赖工具到对应的包目录
构建完成后，NPM 包文件位于 `./npm/@mediago/`。
#### 指定版本号
版本号获取优先级：**环境变量 VERSION > Git Tag > 'dev'**
```bash
# 方法 1: 使用环境变量（推荐）
VERSION=1.2.3 pnpm run npm:build
# 方法 2: 使用 Git Tag
git tag v1.2.3
pnpm run npm:build # 会自动使用 v1.2.3
# 方法 3: 分别指定 Core 和 Deps 版本
CORE_VERSION=1.2.3 DEPS_VERSION=1.0.0 pnpm run npm:build
```
#### 单独构建 Core 或 Deps
```bash
# 只构建 Core 包
VERSION=1.2.3 pnpm run build:core
# 只构建 Deps 包
VERSION=1.0.0 pnpm run build:deps
```
### 3. 发布到 NPM
> 发布前请先执行 `pnpm run npm:build` 确保包已准备好，并且已经完成 `npm login`。
```bash
# 发布所有 NPM 包（Core + Deps）
pnpm run npm:publish
# 仅发布 Core 包
pnpm run npm:publish:core
# 仅发布 Deps 包
pnpm run npm:publish:deps
```
#### NPM 包结构
生成的 NPM 包：
- `@mediago/core` - 主包（根据平台自动安装对应的二进制包）
- `@mediago/core-darwin-x64` - macOS x64 二进制
- `@mediago/core-darwin-arm64` - macOS ARM64 二进制
- `@mediago/core-linux-x64` - Linux x64 二进制
- `@mediago/core-linux-arm64` - Linux ARM64 二进制
- `@mediago/core-win32-x64` - Windows x64 二进制
- `@mediago/core-win32-arm64` - Windows ARM64 二进制
- `@mediago/deps` - 依赖工具主包
- `@mediago/deps-*` - 各平台的依赖工具包
**详细说明**: 查看 [版本号管理指南](docs/VERSION_GUIDE.md)
---
## 📦 发布包的使用
### Windows
1. 解压 zip 文件
2. 双击运行 `mediago-core.exe`
### Linux/macOS
1. 解压 zip 文件
2. 在终端中运行：
```bash
cd mediago-core-xxx
chmod +x mediago-core
./start.sh
```
### NPM 安装
```bash
npm install @mediago/core
# or
pnpm add @mediago/core
# or
yarn add @mediago/core
# 运行
npx @mediago/core
```
---
## 🔧 环境变量说明
发布包中的程序会自动使用相对路径查找下载器工具：
- `./bin/N_m3u8DL-RE` (或 `.exe`)
- `./bin/BBDown` (或 `.exe`)
- `./bin/aria2c` (或 `.exe`)
用户无需配置任何环境变量即可运行！
可选的环境变量：
- `MEDIAGO_M3U8_BIN` - M3U8 下载器路径
- `MEDIAGO_BILIBILI_BIN` - Bilibili 下载器路径
- `MEDIAGO_DIRECT_BIN` - 直接下载器路径
- `MEDIAGO_LOG_LEVEL` - 日志级别 (debug/info/warn/error)
- `MEDIAGO_LOG_DIR` - 日志目录路径
- `MEDIAGO_SERVER_ADDR` - 服务器监听地址 (默认 :8080)
---
## 🏗️ 项目架构
### 目录结构
```
mediago-core/
├── cmd/
│ └── server/ # 主程序入口
├── internal/ # 内部包
│ ├── api/ # API 路由和处理器
│ ├── config/ # 配置管理
│ ├── download/ # 下载器实现
│ ├── events/ # 事件系统
│ └── task/ # 任务管理
├── configs/ # 配置文件
├── scripts/ # 构建脚本 (TypeScript)
│ ├── config.ts # 配置常量和平台定义
│ ├── utils.ts # 工具函数（文件操作、模板渲染等）
│ ├── dev.ts # 开发任务
│ ├── release.ts # 发布构建（完整发布包）
│ └── npm.ts # NPM 包管理（元数据生成 + 组装 + 发布）
├── templates/ # NPM 包模板文件
│ ├── *.json.tpl # package.json 模板
│ ├── *.md.tpl # README.md 模板
│ └── *.js.tpl # install.js 模板
├── gulpfile.ts # Gulp 主入口
├── .bin/ # 下载器工具（按平台）
├── bin/ # 编译产物（二进制文件）
├── npm/ # NPM 包构建输出
│ └── @mediago/ # NPM scope
│ ├── core/ # Core 主包
│ ├── core-*/ # 各平台 Core 包
│ ├── deps/ # Deps 主包
│ └── deps-*/ # 各平台 Deps 包
└── release/ # 完整发布包
```
### 构建脚本架构
所有构建脚本都使用 TypeScript 编写，职责清晰：
- **config.ts** - 配置变量、常量和平台定义
- **utils.ts** - 通用工具函数（文件操作、命令执行、模板渲染等）
- **dev.ts** - 开发环境任务（开发服务器、快速编译）
- **release.ts** - 发布构建任务（构建二进制、打包完整发布包）
- **npm.ts** - NPM 包完整流程（元数据生成、组装、发布）
---
## 📚 完整文档列表
| 文档 | 说明 | 适合人群 |
| ------------------------------------------------------ | -------------------- | ---------- |
| [QUICKSTART.md](QUICKSTART.md) | 5 分钟快速启动 | 所有人 |
| [docs/VERSION_GUIDE.md](docs/VERSION_GUIDE.md) | 版本号管理指南 | 发布者 |
| [SWAGGER_GUIDE.md](SWAGGER_GUIDE.md) | Swagger API 文档指南 | API 开发者 |
| [README_core.md](README_core.md) | 完整使用文档 | API 使用者 |
| [FINAL_SUMMARY.md](FINAL_SUMMARY.md) | 最终交付总结 | 项目经理 |
| [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) | 实现总结 | 架构师 |
| [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) | 项目结构 | 维护者 |
| [DELIVERY_CHECKLIST.md](DELIVERY_CHECKLIST.md) | 交付清单 | QA 测试 |
---
## 🎉 项目状态
**✅ 已完成，可直接运行**
- 代码：~700 行（8+ 个 Go 文件）
- 文档：~70 KB（7+ 份文档）
- 构建任务：30+ 个 Gulp 任务
- API 文档：完整 Swagger 支持
- 测试：完整客户端页面
- 脚本：模块化 TypeScript
---
## ❓ 常见问题
### Q: 如何只打包特定平台？
A: 可以修改 `scripts/config.ts` 中的 `BUILD_PLATFORMS` 数组，注释掉不需要的平台。
### Q: 下载器工具从哪里来？
A: 从项目根目录的 `.bin/<platform>/<arch>/` 目录复制。确保这些文件存在且可执行。
### Q: 如何添加新的下载器工具？
A: 将工具放入 `.bin/<platform>/<arch>/` 目录，它会自动被复制到发布包中。
### Q: 为什么使用 pnpm 而不是 npm？
A: pnpm 更快、更节省磁盘空间。当然你也可以使用 npm 或 yarn，只需将 `pnpm` 替换即可。
### Q: 如何自定义构建流程？
A: 编辑 `scripts/` 目录下的 TypeScript 文件。所有任务都是模块化的，职责清晰，易于修改和扩展。
### Q: Core 和 Deps 包有什么区别？
A:
- **Core 包**：包含 mediago-core 的二进制文件和配置
- **Deps 包**：包含依赖的下载工具（N_m3u8DL-RE、BBDown、aria2c、yt-dlp）
- 分开发布可以单独更新，减少不必要的下载
---
## 📞 获取帮助
有问题？查看文档：
1. **新手入门** → [QUICKSTART.md](QUICKSTART.md)
2. **API 文档** → [SWAGGER_GUIDE.md](SWAGGER_GUIDE.md) 或访问 http://localhost:8080/swagger/index.html
3. **API 调用** → [README_core.md](README_core.md)
4. **故障排查** → [README_core.md#故障排查](README_core.md#故障排查)
---
**版本：** v1.0.0
**最后更新：** 2025-01-24
**构建工具：** Gulp + TypeScript
在新工单中引用 查看 Git Blame 复制永久链接