MistRelay

基于 Telegram 机器人的 aria2 下载控制系统，支持 OneDrive 自动上传，并集成了文件直链功能。

✨ 功能特点

核心功能

• Telegram 控制: 基于电报机器人控制 aria2，支持任务管理。
• 自动上传: 下载完成后通过 rclone 自动上传到 OneDrive。
• 数据完整性保障:
  • 下载文件大小校验（与 aria2 报告对比）。
  • OneDrive 上传后远程文件校验（存在性 + 大小 + MD5）。
  • 校验失败自动重试（最多3次）。
  • 确保数据安全，防止数据丢失。
• 文件直链: 整合 TG-FileStreamBot，为 Telegram 文件生成可访问的直链。
• 下载管理:
  • 支持 HTTP/HTTPS、磁力链接、种子文件下载。
  • 支持批量添加任务。
  • 支持自定义下载目录。
  • 实时进度显示（Bot 消息 & Web 界面）。
  • 任务重试/删除/自动重连。
  • 智能文件过滤: 支持跳过小于指定大小的媒体文件（可配置最小文件大小）。
• Web 管理界面:
  • 集成 AriaNg 和自定义系统管理页面。
  • 实时日志流（WebSocket）支持，无需刷新即可查看容器日志。
  • 下载记录管理，支持查看跳过文件状态。
  • 任务中心: 统一管理下载和上传任务，支持实时状态更新。
  • 数据一致性保证: WebSocket 实时同步，确保前后端数据一致。
• 部署友好: Docker 一键部署，集成 aria2、rclone 和前端。
• 性能优化:
  • 上传操作完全异步化，不阻塞 API 响应。
  • 支持配置热重载，无需重启服务。

🚀 快速开始

1. 配置文件设置

下载项目到本地：

git clone https://github.com/Lapis0x0/MistRelay.git
cd MistRelay

重命名 db/config.example.yml 为 config.yml 并设置参数（详细配置见文件内注释）：

API_ID: xxxx                      # Telegram API ID
API_HASH: xxxxxxxx                # Telegram API Hash
BOT_TOKEN: xxxx:xxxxxxxxxxxx      # Telegram Bot Token
ADMIN_ID: management_id           # 管理员 Telegram ID

# 下载配置
SKIP_SMALL_FILES: false          # 是否跳过小于指定大小的媒体文件
MIN_FILE_SIZE_MB: 100            # 最小文件大小（MB），小于此大小的文件将被跳过

# ... 其他配置 ...

2. 配置 Rclone

由于 VPS 通常没有图形界面，建议在本地配置 rclone 后上传配置文件：

1. 本地配置: 在本地电脑运行 rclone config 完成 OneDrive 授权。
2. 上传配置: 将本地生成的 rclone.conf 复制到项目的 rclone/ 目录下。

# 示例：创建目录并上传
mkdir -p rclone
# 将 rclone.conf 放入此目录

3. Docker 部署 (生产环境)

MistRelay 使用 Docker Compose 进行一键部署，集成了前后端和所有依赖。

# 构建并启动服务
docker compose up -d --build

# 查看日志
docker compose logs -f --tail=100

端口说明:

• Web 界面: http://your-server:8080 (端口映射可在 docker-compose.yml 中修改)
• API 接口: http://your-server:8080/api/*

4. 访问服务

启动后，访问 http://your-server:8080 即可使用 Web 管理界面。

• AriaNg: 用于管理 Aria2 下载任务。
• 系统管理: http://your-server:8080/system 用于管理 Docker 容器状态。

📖 使用指南

Telegram Bot 命令

• /start - 开始使用
• /help - 查看帮助
• /info - 查看系统信息
• /web - 获取 Web 控制台地址
• /path [目录] - 设置下载目录

菜单功能

• 正在下载/等待/已完成: 查看各状态的任务列表。
• 重试/删除: 管理选中任务。

文件直链功能

默认启用（可配置）。

1. 使用: 发送或转发文件给 Bot。
2. 结果: Bot 会返回文件的直链地址（支持文档、视频、音频等）。
3. 自动下载:
   • 若开启 STREAM_AUTO_DOWNLOAD: true，管理员发送的文件会自动加入 Aria2 下载队列。
   • 需配置 BIN_CHANNEL 以确保日志存储正常。

快捷提示

• OneDrive 上传优化: 项目默认配置了优化参数（如 --transfers 4, --checkers 8, --buffer-size 64M 等）以提升速度。
• 自动删除: 配置 AUTO_DELETE_AFTER_UPLOAD: true 可在上传成功后自动清理本地文件。
• 跳过小文件:
  • 配置 SKIP_SMALL_FILES: true 启用跳过小文件功能。
  • 配置 MIN_FILE_SIZE_MB: 100 设置最小文件大小（默认 100MB）。
  • 小于指定大小的文件会被静默跳过，不会下载和上传。
  • 可在下载页面查看被跳过的文件状态。

🛠 系统管理模块

系统管理模块 (/system) 提供 Docker 容器的实时监控与控制。

功能

• 状态查看: 实时查看容器运行状态、镜像信息。
• 热重载: 支持通过 Web 界面一键重启容器 (Restart Container)。
• 日志查看:
  • 支持 HTTP 方式获取历史日志（支持筛选行数：50/100/200/500）。
  • WebSocket 实时日志流: 点击播放按钮开启实时日志流，自动推送最新日志，无需手动刷新。
  • 支持清空日志显示。

配置要求

系统管理模块依赖于 Docker Socket 挂载 (已在 docker-compose.yml 默认配置):

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

🖥️ 桌面客户端

MistRelay 提供独立的 Windows 桌面客户端，基于 Tauri 2 构建，支持：

• 本地文件下载: 文件直接保存到本地下载目录
• 视频流预览: 边下载边预览，无需等待下载完成
• 自动更新: 内置 updater，检测到新版本后一键更新重启
• 代理支持: 桌面端独立代理配置（HTTP/SOCKS5）

项目结构

MistRelay/
├── web/                  # Web 前端（纯浏览器，独立开发）
├── desktop/              # 桌面客户端（完全独立）
│   ├── frontend/         # 桌面端 Vue 前端
│   │   ├── src/          # 桌面专属前端源码
│   │   ├── vite.config.ts
│   │   └── index.html
│   ├── src/main.rs       # Tauri Rust 后端
│   ├── tauri.conf.json   # Tauri 配置
│   ├── Cargo.toml
│   └── package.json      # 桌面端全部依赖
├── dev-scripts/          # 开发辅助脚本
└── .github/workflows/    # CI/CD

web/ 和 desktop/ 完全独立，各自拥有独立的前端源码、依赖和构建流程，互不影响。

安装

前往 Releases 下载最新的 Windows 安装包。

已知兼容性：如果当前桌面客户端是 v0.2.10，由于该版本内置 updater 密钥配置错误，升级到 v0.2.11+ 需要先手动下载安装包一次；完成后后续版本会恢复自动更新。

桌面端开发

cd desktop
npm install
npm run dev

桌面端构建

cd desktop
npm run build

当前 Windows NSIS 安装器默认使用简体中文界面。

桌面端本地预发布检查：

cd desktop
npm run check:release

实验性 Qt 客户端位于 desktop-qt/，作为独立 Windows Beta 通道发布：

cd desktop-qt
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python scripts/check_release.py

Qt 客户端发布 tag 使用 desktop-qt-v<semver>，客户端会通过 GitHub Releases API 解析该通道下的 qt-latest.json 资产，不影响现有 Tauri 客户端的自动更新链路。

Linux/macOS 开发机默认只做本地预发布校验；正式 Windows 安装包、签名文件和 latest.json 仍以 GitHub Actions 的 windows-latest 构建结果为准。

构建时需设置签名环境变量：

export TAURI_SIGNING_PRIVATE_KEY_PATH="/path/to/MistRelay.key"
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""

GitHub Actions 中的 TAURI_SIGNING_PRIVATE_KEY 必须填写 MistRelay.key 私钥文件内容本身。 如果使用仓库当前这套新生成的 key，TAURI_SIGNING_PRIVATE_KEY_PASSWORD 应留空。 desktop/tauri.conf.json 里的 updater pubkey 必须填写 MistRelay.key.pub 文件中的 base64 内容本身，不要手动解码成两行 minisign 文本。 不要把下面这些值填到 TAURI_SIGNING_PRIVATE_KEY Secret 里：

• tauri.conf.json 里的 updater pubkey
• 私钥文件路径
• 带空格拆开的 base64 字符串

CI 自动构建

推送 v* 或 desktop-v* tag 会自动触发 GitHub Actions 构建 Windows 安装包并创建 Release。 工作流会在发布前校验安装包签名、latest.json 和内置 updater pubkey 是否一致，任一不匹配都会阻止发布。

git tag -a v0.1.1 -m "v0.1.1"
git push origin v0.1.1

💻 开发者指南

如果您想参与开发或进行二次开发，请参考以下信息。

架构概述

• 后端: Python + aiohttp (Port 8080)
• Web 前端: Vue3 + Vite + Element Plus (Dev Port 5173)
• 桌面客户端: Tauri 2 + Vue3（独立前端 + Rust 原生能力）

开发模式启动

使用 start-dev.sh 脚本可一键启动前后端分离的开发环境：

./start-dev.sh

此模式下：

• 前端支持 HMR (热重载)。
• API 请求会自动代理到后端容器。
• 访问 http://localhost:5173 进行开发。

生产构建原理

Dockerfile 使用多阶段构建：

1. node 阶段构建前端静态资源 (dist 目录)。
2. python 阶段通过 aiohttp 提供 API 服务，并将 / 路由指向前端 index.html。

📝 更新日志

[0.2.15] - 2026-04-22 (桌面预发布校验入口)

• 🧪 本地预发布检查标准化:
  • 桌面端新增 npm run check:release，统一执行前端生产构建和 cargo check，用于发版前本地校验。
  • 文档明确 Linux/macOS 机器只承担本地预发布检查，正式 Windows 安装包继续以 GitHub Actions 结果为准。
• 🧹 构建产物忽略补全:
  • 补充 desktop-qt 本地虚拟环境与构建目录忽略规则，避免后续实验性 Qt 客户端污染工作树。

[0.2.14] - 2026-04-22 (桌面安装包打包修复)

• 📦 安装包主程序修正:
  • 桌面端 Cargo 配置显式锁定默认运行目标为 mistrelay-desktop，避免发布时把辅助校验工具错误打进 NSIS 安装包。
  • Windows Release 工作流新增默认 bin 校验和安装包体积下限校验，打到错误主程序时会在发布前直接失败。
• ⚠️ 版本警示:
  • v0.2.13 的 Windows 安装包体积异常，属于错误打包版本，请不要下载；请改用 v0.2.14+。

[0.2.13] - 2026-04-21 (桌面更新链路加固)

• 🔄 已知升级问题定向提示:
  • v0.2.10 现在会被识别为已知 updater 密钥配置错误版本，检查到新版本时明确提示“需手动升级一次”。
  • 其他版本仍保留通用回退逻辑：原生 updater 校验失败时改为给出手动下载安装包入口，不再只报模糊错误。
• 🛡️ 发布前自动验签:
  • Windows Release 工作流新增安装包、.sig、latest.json 与内置 updater pubkey 的一致性校验。
  • 若签名、下载地址或版本号不匹配，CI 会在创建 Release 前直接失败，避免再次发布出“能发现更新但无法自动安装”的客户端。
• ⚠️ 发布说明:
  • 该版本的 Windows 安装包错误地打进了辅助工具，体积异常偏小；请跳过此版本，直接升级到 v0.2.14+。

[0.2.3] - 2026-03-13 (本地下载操作补齐)

• 🧰 本地下载补足核心操作:
  • 桌面端“本地下载”新增取消、重试、打开文件、打开目录操作。
  • 失败和已取消任务现在都能在下载页直接重新发起，不必回到网盘页重下。
• 📡 下载状态更完整:
  • 本地下载状态补充“取消中 / 已取消”，前端统计与清理逻辑一并对齐。
  • 下载速度刷新改得更稳，列表观察时不再频繁跳值。
• 🧭 网盘导航补口:
  • 桌面端“我的网盘”顶部补上返回上级入口，媒体组视图支持返回列表。

[0.1.6] - 2026-03-13 (更新检查兜底 & 页面继续收口)

• 🔄 更新检查兜底:
  • 桌面端更新检查在原生 updater 失败时，会回退读取 GitHub 发布的 latest.json。
  • 已是最新版本时不再误报“检查失败”；若发现新版本但自动更新暂不可用，会明确给出手动下载安装提示。
• 🧼 页面继续收口:
  • 设置中心继续压缩重复说明，减少层层标题和告警块。
  • “任务中心 / 本地下载 / 我的网盘”顶部文案进一步简化，页面更紧凑。

[0.1.5] - 2026-03-13 (任务中心合页 & 设置页瘦身)

• 🗂️ 任务页合并:
  • “任务中心”和“任务队列”合并到同一页面，通过 Tab 切换。
  • 原独立 /tasks 入口重定向到下载页队列 Tab，侧边栏不再重复显示。
• 📁 本地下载职责收口:
  • “我的网盘”页面移除本地下载任务面板，避免和“本地下载”页面重复。
  • 本地下载任务统一留在“本地下载”和合并后的任务页中查看。
• 🧼 设置页信息压缩:
  • 设置中心移除重复的大标题、摘要卡和告警块，客户端/服务端说明改为轻量提示。
  • 连接、更新、代理及各类服务端配置统一为更紧凑的操作布局。

[0.1.4] - 2026-03-13 (下载入口整理 & 全局代理)

• 🧭 下载入口去重:
  • 设置中心移除重复的“下载控制”，客户端下载参数统一收口到“本地下载”页面。
  • 设置中心新增跳转入口，避免两套入口配置互相冲突。
• 🗂️ 本地下载页重构:
  • “本地下载”页面拆分为“下载配置 / 下载任务”两个 Tab。
  • 配置与任务分开展示，减少页面混杂感。
• 🌐 PC 端全局代理:
  • 桌面代理语义调整为 PC 客户端全局代理。
  • 覆盖页面请求、接口访问、更新检查、桌面下载和本地预览等客户端侧流量。

[0.1.3] - 2026-03-13 (本地下载管理增强)

• 📁 本地下载管理独立入口:
  • 桌面端侧边栏新增“本地下载”独立页面，不再把本地下载任务只挂在“我的网盘”里。
  • 页面支持集中查看下载任务状态、保存位置和失败原因。
• ⚙️ 本地下载配置直达:
  • 本地下载页面可直接配置下载目录、最大并发数、每文件线程数。
  • 设置中心中的客户端下载配置同步补齐上述参数，两个入口保持一致。
• 🗂️ 原生目录选择器:
  • 接入桌面端原生文件夹选择器，可直接选择本地下载目录。
  • 留空时自动回退到系统下载目录下的 MistRelay 默认目录。

[0.1.1] - 2026-03-12 (桌面客户端独立 & 自动更新)

• 🖥️ 桌面客户端独立:
  • 桌面端从 web/ 完全分离为独立 desktop/ 项目。
  • 桌面端拥有独立的 Vue 前端源码、依赖和构建流程。
  • web/ 不再包含任何 Tauri/桌面相关代码。
• 🔄 自动更新:
  • 集成 tauri-plugin-updater，支持检查更新、下载安装和自动重启。
  • 设置页面新增"软件更新"区域，显示当前版本和下载进度。
  • CI 自动生成签名安装包和 latest.json 更新清单。
• 🏗️ CI/CD:
  • GitHub Actions 工作流适配独立桌面项目结构。
  • 推送 v* 或 desktop-v* tag 自动构建 Windows 安装包并发布 Release。

[1.3.0] - 2026-01-28 (数据一致性优化)

• 🔧 数据一致性增强:
  • 修复 WebSocket 下载更新缺少上传信息的问题。
  • 优化前端数据同步逻辑，确保上传下载记录数据一致。
  • WebSocket 推送现在包含完整的上传信息，前端可正确判断完成状态。
  • 改进任务中心的数据更新机制，实时同步关联数据。
• 🗑️ 功能简化:
  • 移除下载和上传任务的暂停/恢复功能，简化操作流程。
  • 保留重试和删除功能，确保核心功能正常使用。
• 📊 数据同步机制:
  • 数据库查询正确关联所有相关表（downloads、uploads、tg_media）。
  • WebSocket 推送包含完整关联数据，确保前端显示准确。
  • 前端自动同步更新关联数据，保持数据一致性。

[1.2.0] - 2026-01-26 (功能增强与性能优化)

• 🎯 智能文件过滤:
  • 新增跳过小文件功能，可配置最小文件大小（默认 100MB）。
  • 在添加下载任务前检查文件大小，避免不必要的下载。
  • 下载页面显示跳过状态和统计信息。
  • 静默处理，不发送通知消息。
• ⚡ 性能优化:
  • 上传操作完全异步化，使用 asyncio.create_subprocess_exec 替代阻塞的 subprocess.Popen。
  • API 响应不再被上传操作阻塞，提升系统响应速度。
  • 支持配置热重载，修改配置后无需重启服务。
• 📊 Web 管理界面增强:
  • 新增 WebSocket 实时日志流功能，无需刷新即可查看最新日志。
  • 支持开始/停止实时日志流。
  • 支持清空日志显示。
  • 下载页面适配显示跳过文件状态。
• 🔧 代码优化:
  • 修复 asyncio.subprocess.Process 的 poll() 方法错误。
  • 优化异步日志读取，避免阻塞事件循环。

[1.1.0] - 2026-01-26 (数据完整性增强)

• 🔒 数据安全:
  • 新增下载文件大小校验（与 aria2 totalLength 对比）。
  • 新增 OneDrive 上传后远程文件校验（存在性 + 大小）。
  • 新增 MD5 哈希校验（可选，提供字节级完整性保证）。
  • 新增自动重试机制（校验失败时自动重试最多3次）。
• 🛡️ 防护机制:
  • 校验失败时保留本地文件，防止数据丢失。
  • 智能降级策略（MD5 不可用时降级为大小校验）。
  • 详细的错误日志和用户通知。

[1.0.0] - 2026-01-22 (首个发行版)

• 🎉 发布: 整合了 MistRelay 和 TG-FileStreamBot。
• ✨ 新增:
  • 完整的 Aria2 + Rclone 自动化流程。
  • 统一的 Web UI。
  • Docker 容器集成与系统管理功能。
  • 消息美化与实时进度展示。

🔍 数据一致性保证

MistRelay 采用多层数据同步机制，确保任务中心的上传下载记录数据一致性：

数据库层面

• 外键约束: 使用 SQLite 外键约束保证数据完整性
• 事务管理: 所有数据库操作使用事务，确保原子性
• WAL 模式: 启用 Write-Ahead Logging，提升并发性能

应用层面

• WebSocket 实时推送: 每次数据库更新后立即推送状态变更
• 轮询同步: 定期同步 aria2 状态与数据库，确保一致性
• 关联数据查询: 使用 LEFT JOIN 正确关联 downloads、uploads、tg_media 表

前端层面

• 实时更新: WebSocket 接收更新后同步更新关联数据
• 状态判断: 基于完整数据（包括上传状态）判断任务完成状态
• 统计计算: 基于实际状态重新计算组统计信息

详细的数据同步机制请参考 DATABASE_SYNC_REPORT.md 和 DATA_CONSISTENCY_CHECK.md。

🗓 未来计划

• 支持文件重命名
• 优化菜单交互 (更清晰的键盘布局)
• 引入大模型 (LLM) 自动整理文件列表
• 更多云存储服务支持
• 文件预览与搜索功能

🙏 致谢

本项目整合了以下优秀的开源项目：

• TG-FileStreamBot - 文件直链生成
• MistRelay - Aria2 下载控制
• HouCoder/tele-aria2
• jw-star/aria2bot