wannayoung/xtools repository overview

⁠xtools

独立的自托管同步控制台（单用户）：导入 xchina 帐户、搜索或从收藏入队，下载图集 / 小说 / 影片，在浏览器里看进度。和桌面端 xchina⁠ 分开维护，互不依赖。

⁠功能

• 控制台登录：JWT（Bearer）；封面 / 文件流 / SSE 使用短时 ticket（勿把会话 JWT 放进 URL）。管理员账号由必填环境变量在首次启动创建；本项目仅支持单用户。
• xchina 帐户：邮箱密码或 Cookie 导入；Cookie / 密码 AES-256-GCM 加密入库。每个帐户独立 CookieStore。Cookie 失效时若勾选「记住密码」会自动重登，否则标 expired
• 收藏同步：分页拉取 myFavs 写入 favorites；收藏页筛选、勾选加入队列
• 站点搜索：按关键词检索图集 / 小说 / 影片，勾选入队
• 下载 worker：消费 queued 任务；任务并行数可配（默认 2，上限 8），单任务超时 4 小时；图集内部默认并发 3、间隔约 300ms，处理 429。启动时自动把未完成任务重新入队；进程退出会 drain 进行中的任务。
  • 图集 → {download_dir}/photos/...
  • 小说整本 EPUB → {download_dir}/books/...
  • 影片：解析 playUrl。mp4 流式写入（可续传 .part）；m3u8 调 ffmpeg → {download_dir}/videos/...
• 进度：SSE 推 taskId / phase / done / total / speed，任务页进度条 + 轮询兜底。支持暂停 / 重试 / 失败原因 / 任务日志
• 链接与去重：只接受完整 xchina 链接（不再支持裸 ID）。media 表按 (kind, obj_id) 去重，同一资源不占第二份盘
• 已下载库：搜索、本地路径、去重状态；「同步资源」会扫盘导入缺失索引
• 仪表盘：真实队列、磁盘、帐户状态
• 设置：下载目录、并发、间隔、任务并行、全局代理、首选站点、ffmpeg、无图模式；Clash 订阅 + Mihomo 托管生成多路本地 HTTP 代理，帐户可绑定节点；可探测站点可达性

⁠环境

• Rust 1.85+
• Node.js 20+ 与 pnpm
• MySQL 8（本机自行安装，镜像不内置）
• 本机下 HLS 影片需要系统里有 ffmpeg（Docker 镜像已打入）
• 多节点代理需要系统里有 mihomo⁠（Docker 镜像已打入 /usr/local/bin/mihomo）

⁠本地开发

本机先建库，例如：

CREATE DATABASE xtools CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

cp .env.example .env
# 必填：MYSQL_*、ADMIN_*
# 可选：BIND、WEB_DIR、CONFIG_PATH、WORKER_SLOTS、MIHOMO_PATH

cargo run -p xtools

cd web
pnpm install
pnpm dev

本地 cargo run 会读取根目录 .env。浏览器打开 http://127.0.0.1:3080⁠，或用局域网 IP 给手机访问。后端默认在 Docker 下听 3030，本地 .env 覆盖为 0.0.0.0:3000。

下载目录等在设置页或 config.yaml 配置（本地可用 ./downloads）。

⁠Mihomo 多代理（防 429 / 多帐户分流）

1. 安装 mihomo，或使用 Docker 镜像（已内置）。
2. 设置页填写 Clash 订阅 URL、确认 mihomo 路径与工作目录，点 保存 → 刷新。
3. 列表出现 http://127.0.0.1:21001 起的多路入口后，可用 curl 验出口是否不同：

curl -x http://127.0.0.1:21001 https://api.ip.sb/ip
curl -x http://127.0.0.1:21002 https://api.ip.sb/ip

1. 帐户页导入或编辑时，为每个 xchina 帐户绑定不同节点。
2. 将 任务并行（worker_slots）调到需要的路数（例如 5），并保持合理的请求间隔，避免单出口打满。

订阅需为含 proxies: 的 Clash / Mihomo YAML（或 base64 包装的同格式）。刷新时默认排除名称含「剩余 / 重置 / 到期 / 官网 / 套餐」的信息节点；节点数受 mihomo_max_listeners 限制（默认 10）。

⁠Docker

镜像支持 linux/amd64 与 linux/arm64，pull latest 时 Docker 会按机器架构自动选择。镜像默认：BIND=0.0.0.0:3030、CONFIG_PATH=/xtools/config/config.yaml、WEB_DIR=/app/web、MIHOMO_PATH=/usr/local/bin/mihomo。下载目录、代理、Mihomo 工作目录等走 config.yaml（设置页可改）。compose 只需填数据库和管理员。镜像已内置 mihomo。已发布：wannayoung/xtools⁠。

docker compose pull
docker compose up -d
# 或本地构建：docker compose up -d --build

换机器时改 docker-compose.yml 里的 volumes 和 MYSQL_* / ADMIN_*。

⁠仓库结构

├── crates/xchina-core   # 登录、Cookie、HTML 解析、资源抓取（从桌面端拷贝，独立演进）
├── crates/xtools        # Axum API、SeaORM、worker、静态资源、Mihomo 编排
├── web                  # Vue 控制台
├── docker-compose.yml
├── Dockerfile
└── config.example.yaml

⁠配置

持久化文件是 YAML（config.yaml），首次启动会自动生成 jwt_secret / encryption_key。数据库和管理员不写进 YAML。

必填环境变量：

• MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE
• ADMIN_USERNAME、ADMIN_PASSWORD

可选环境变量（不填则用默认值 / YAML）：

• BIND = 0.0.0.0:3030
• CONFIG_PATH = /xtools/config/config.yaml
• WEB_DIR = /app/web
• JWT_SECRET / ENCRYPTION_KEY（空则自动生成并写回 YAML）
• WORKER_SLOTS
• MIHOMO_PATH

下载目录、代理、站点、ffmpeg、Clash 订阅、mihomo 工作目录 / 端口 / 节点上限、无图模式等均在 config.yaml / 设置页 配置，不通过环境变量覆盖。

Docker 宿主机下载路径只通过 compose volumes 映射到容器内 download_dir（默认 /xtools/downloads）。

控制台设置页会覆盖上述运行时项并写回 YAML。

密码不要长期明文存放：登录成功后日常只用加密 Cookie；若勾选「记住密码」，失效时才用加密密码自动重登。