rclone-webgui

浏览器端的 rclone 图形界面，使用 Anthropic / Claude 设计语言。

rclone/ 是 github.com/rclone/rclone 的 git submodule，锁定在上游某个 commit，不携带我们的任何改动。所有 webgui 源码、Docker 编排、文档都在本仓库。

项目结构

.
├── webgui/                  # webgui 源码（在父仓库，不在 rclone 子模块里）
│   ├── api/server.py       #   SQLite-backed recurring jobs API / scheduler
│   ├── data/               #   jobs.sqlite 数据目录（不提交）
│   ├── webgui.go           #   Go 子命令源码（仅当自行构建 rclone 时需要）
│   ├── rclone-cmd-all-add-webgui-import.patch  #   注解：把 webgui 注册进 rclone 的 cmd/all
│   └── web/                #   静态前端（rclone rcd 直接服务）
│       ├── index.html
│       └── assets/
├── config/rclone/          # rclone.conf 挂载点（bind mount，不提交）
├── docker-compose.yml      # rclone rcd + jobs-api sidecar
├── DESIGN.md               # UI 设计系统规范
├── CLAUDE.md               # Claude Code 协作指引
└── rclone/                  # submodule → github.com/rclone/rclone，纯净不改动

功能

Remotes 管理 — 在浏览器里创建 / 编辑 / 删除 rclone remote，表单从 /config/providers 动态生成，覆盖全部 70+ 后端的全部选项。
文件浏览 — 面包屑导航 + 文件表格，支持 mkdir / upload / delete / rename / download。
同步任务 — copy / sync / move 异步任务，5 秒轮询进度（速度、 ETA、已传输 / 总量、错误计数）。单次任务和固定循环任务都保存到 SQLite；固定循环任务由 jobs-api sidecar 调度。

OAuth 后端（drive、dropbox、onedrive 等）目前仅显示提示横幅，引导用户在终端跑 rclone config 完成授权。

快速开始

安全提示：默认 Docker 编排使用 --rc-no-auth，RC API 可以读写和删除已配置 remote 上的数据。Compose 文件默认只绑定到 127.0.0.1。不要把 5580 / 5581 直接暴露到 LAN 或公网；需要远程访问时，请先加带认证和 TLS 的反向代理。

# 1. 拉取子模块（rcd 流程用不到，自行构建 rclone 二进制时才需要）
git clone --recurse-submodules <your-fork-url>

# 2. 启动堆栈（无需 build）
docker compose up -d

# 3. 打开 http://localhost:5580

局域网访问

不建议把 5580 / 5581 直接暴露到不受信网络。JOBS_API_ALLOWED_ORIGINS 只限制浏览器 CORS；不带 Origin 的脚本或命令行客户端仍然可以直接调用 jobs-api。需要多人或跨网段访问时，优先用带认证和 TLS 的反向代理保护两个端口。

如果只是在受信局域网临时访问，例如 http://10.0.0.138:5580，需要同时让 rclone 和 jobs-api 两个端口监听这个地址，并把页面 Origin 加进 jobs-api 白名单：

cp .env.example .env
cat > .env <<'EOF'
WEBGUI_BIND_ADDR=10.0.0.138
JOBS_API_BIND_ADDR=10.0.0.138
JOBS_API_ALLOWED_ORIGINS=http://localhost:5580,http://127.0.0.1:5580,http://10.0.0.138:5580
EOF
docker compose up -d

前端页面会从 10.0.0.138:5580 调用 10.0.0.138:5581，所以只改 JOBS_API_ALLOWED_ORIGINS 不够，5581 也必须发布到同一个可访问地址。

架构

Docker 编排包含两个服务：

服务	本机 URL	职责
`rclone`	`http://localhost:5580`	静态前端、RC API、远端文件下载
`jobs-api`	`http://localhost:5581`	SQLite 循环任务 API 和调度器

rclone 容器通过 rclone rcd 同时承担：

职责	URL	配置项
静态前端	`GET /`	`--rc-files=/web`
RC API	`POST /config/`、`/operations/`、`/sync/`、`/job/`	内置
远端文件下载	`GET /<remote>:<path>`	`--rc-serve`

浏览器从静态前端调用 5580 的 RC API，并调用 5581 的 jobs-api 管理固定循环任务。jobs-api 默认只允许 http://localhost:5580 和 http://127.0.0.1:5580 这两个 Origin。反代或改端口时，同时调整 JOBS_API_ALLOWED_ORIGINS。

开发检查

find webgui/web/assets/js -name '*.js' -exec sh -c 'for f; do node --input-type=module --check < "$f" || exit 1; done' sh {} +
python3 -m py_compile webgui/api/server.py
python3 -m unittest discover -s webgui/api -p '*_test.py'
curl -sS http://127.0.0.1:5580/
curl -sS http://127.0.0.1:5581/health

自行构建 rclone（可选）

Docker 编排默认使用官方 rclone/rclone:latest 镜像，配合 rcd 即可。如果你想构建一个内置 webgui 命令的 rclone 二进制（rclone webgui 能像 rclone gui 那样独立运行），可以：

注意：内置 rclone webgui 只启动静态 GUI 和 rclone RC，不会启动 jobs-api sidecar。当前 Jobs 页依赖 jobs-api 的 SQLite 接口，所以完整的单次/循环任务体验请使用 Docker 编排，或自行启动兼容的 jobs-api 并通过 ?jobsApi=<url> 指给前端。

# 1. 把 webgui 源码软链或拷贝到 rclone 子模块的 cmd/ 下
ln -s ../../webgui rclone/cmd/webgui

# 2. 应用注册补丁
cd rclone && git apply ../webgui/rclone-cmd-all-add-webgui-import.patch

# 3. 构建
make

升级 rclone 子模块

cd rclone
git fetch origin
git checkout <new-tag-or-commit>
cd ..
git add rclone
git commit -m "chore: 升级 rclone 至 <new-tag>"

协议

本外层仓库：MIT
rclone/ 子模块：遵循上游 rclone 的 MIT 协议

5.6 KiB Raw Permalink Blame History Unescape Escape