152 lines
5.6 KiB
Markdown
152 lines
5.6 KiB
Markdown
# rclone-webgui
|
||
|
||
浏览器端的 rclone 图形界面，使用 Anthropic / Claude 设计语言。
|
||
|
||
`rclone/` 是 [github.com/rclone/rclone](https://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 的反向代理。
|
||
|
||
```bash
|
||
# 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 白名单：
|
||
|
||
```bash
|
||
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`。
|
||
|
||
## 开发检查
|
||
|
||
```bash
|
||
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>` 指给前端。
|
||
|
||
```bash
|
||
# 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 子模块
|
||
|
||
```bash
|
||
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](https://github.com/rclone/rclone)
|
||
的 MIT 协议
|