Skip to content

Commit 7e8ffd2

Browse files
committed
feat(rclone): 简化多 remote 配置为 JSON 列表
现有平铺 env/json 键值难以表达多 remote 结构,改为以 remotes 数组作为主配置,并支持本地 JSON 密钥与环境变量占位符两种落点。PowerShell 与 Node.js 运维入口保持同等语义,文档和示例同步移除 .env 多 remote 配置说明。 Constraint: 不新增依赖,JS 版保留,PowerShell 版继续复用 psutils/src/config 读取标准 JSON Rejected: 继续兼容 RCLONE_REMOTE_NAMES 平铺格式 | 会保留两套 schema 并增加维护成本 Rejected: 用 .env 编号模拟列表 | dotenv 不适合表达 remote 对象列表 Confidence: high Scope-risk: moderate Directive: remote 配置 schema 以 JSON remotes 数组为唯一主入口,不要重新引入平铺 env 多 remote 格式 Tested: Pester RcloneOps.Tests.ps1 Tested: node --test config/service/oss/rclone/rclone-ops.test.mjs Tested: PowerShell/Node 从 rclone.config.example.json 生成 rclone.conf Tested: pnpm qa Tested: pnpm test:pwsh:all Not-tested: 真实 rclone WebUI 启动与远端连通性
1 parent 9a11eb8 commit 7e8ffd2

8 files changed

Lines changed: 1893 additions & 0 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.env.local
2+
rclone.conf
3+
.runtime/
4+
logs/
5+
mounts/
6+
*.log
7+
rclone.config.local.json
Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# rclone 通用运维入口
2+
3+
这个目录提供一套通用 rclone 运维入口,用于从 JSON 主配置生成本地 `rclone.conf`,并统一启动 WebUI/RC、挂载、复制、同步和校验等常用操作。真实密钥只保存在本地 JSON、进程环境变量和生成的 `rclone.conf` 中;示例文件只使用占位符。
4+
5+
## 文件说明
6+
7+
| 文件 | 作用 |
8+
| --- | --- |
9+
| `rclone.config.example.json` | JSON 配置模板,使用 `remotes` 数组表达多个 remote。 |
10+
| `rclone.conf.example` | rclone 配置模板,只包含占位符。 |
11+
| `rclone-ops.ps1` | 推荐使用的 PowerShell 运维脚本,支持配置生成、WebUI/RC、mount、copy、sync、check 等入口。 |
12+
| `rclone-ops.mjs` | 保留的 Node.js 版本,便于对照和跨平台备用。 |
13+
| `.gitignore` | 防止真实配置、运行时日志和挂载目录被提交。 |
14+
15+
## 配置格式
16+
17+
`rclone-ops` 只支持 JSON 主配置,不再用 `.env` 表达 remote 列表,也不兼容旧的 `RCLONE_REMOTE_NAMES` / `RCLONE_REMOTE_<NAME>_<KEY>` 平铺格式。PowerShell 版仍通过仓库的 `psutils/src/config` 读取标准 JSON,rclone 脚本层负责校验 `remotes` schema 与环境变量占位符替换。
18+
19+
核心约定:
20+
21+
1. 顶层必须包含非空 `remotes` 数组。
22+
2. 每个 remote 必须包含 `name``type`
23+
3. remote 对象中除 `name` 外的字段会按原键名写入 `rclone.conf`
24+
4. 字符串值可使用 `${ENV_VAR}` 占位符,从当前进程环境变量读取密钥;缺失变量会直接报错。
25+
26+
示例:
27+
28+
```json
29+
{
30+
"remotes": [
31+
{
32+
"name": "cloud-main",
33+
"type": "s3",
34+
"provider": "Other",
35+
"access_key_id": "${CLOUD_MAIN_ACCESS_KEY_ID}",
36+
"secret_access_key": "${CLOUD_MAIN_SECRET_ACCESS_KEY}",
37+
"endpoint": "https://s3.example.com",
38+
"region": "auto",
39+
"acl": "private"
40+
},
41+
{
42+
"name": "archive",
43+
"type": "s3",
44+
"provider": "Other",
45+
"access_key_id": "REPLACE_ME",
46+
"secret_access_key": "REPLACE_ME",
47+
"endpoint": "http://127.0.0.1:9000",
48+
"force_path_style": "true"
49+
}
50+
]
51+
}
52+
```
53+
54+
## 前置条件
55+
56+
1. 安装 PowerShell 7+。
57+
2. 安装 rclone,并确保 `rclone version` 可执行。
58+
3. 准备 JSON 配置文件:
59+
60+
```bash
61+
cp rclone.config.example.json rclone.config.local.json
62+
# 编辑 rclone.config.local.json,填入真实 remote 配置;该文件已被 .gitignore 忽略。
63+
```
64+
65+
如果使用 `${ENV_VAR}` 占位符,在运行 `init-config` 前导出对应变量:
66+
67+
```bash
68+
export CLOUD_MAIN_ACCESS_KEY_ID='真实 ID'
69+
export CLOUD_MAIN_SECRET_ACCESS_KEY='真实 Secret'
70+
```
71+
72+
## 一键生成本地 rclone.conf
73+
74+
```bash
75+
cd config/service/oss/rclone
76+
pwsh ./rclone-ops.ps1 init-config --source rclone.config.local.json
77+
```
78+
79+
如需覆盖已有本地配置:
80+
81+
```bash
82+
pwsh ./rclone-ops.ps1 init-config --source rclone.config.local.json --overwrite
83+
```
84+
85+
Node.js 版同等命令:
86+
87+
```bash
88+
node rclone-ops.mjs init-config --source rclone.config.local.json --overwrite
89+
```
90+
91+
## 健康检查
92+
93+
```bash
94+
pwsh ./rclone-ops.ps1 doctor
95+
```
96+
97+
该命令会检查:
98+
99+
- `rclone` 是否可执行。
100+
- `rclone.conf` 是否存在。
101+
- 已配置的 remote 名称。
102+
103+
## 启动 WebUI / RC
104+
105+
默认监听 `127.0.0.1:5572`。如果未设置 `RCLONE_RC_PASS`,rclone WebUI 会自动生成临时认证信息;建议日常运维显式设置强密码:
106+
107+
```bash
108+
RCLONE_RC_PASS='强密码' pwsh ./rclone-ops.ps1 webui
109+
```
110+
111+
后台启动且不自动打开浏览器:
112+
113+
```bash
114+
RCLONE_RC_PASS='强密码' pwsh ./rclone-ops.ps1 webui --background --no-open-browser
115+
```
116+
117+
停止后台 WebUI:
118+
119+
```bash
120+
pwsh ./rclone-ops.ps1 stop-webui
121+
```
122+
123+
> 安全提示:rclone WebUI 会启动 remote control API,默认绑定 localhost;如果 `--rc-addr` 绑定公网或局域网地址,应使用 `--rc-user` / `--rc-pass` 等认证方式。默认只绑定本机地址,除非你明确知道风险,不要改成 `0.0.0.0:5572`
124+
125+
## 常用运维命令
126+
127+
列出 remote 根路径:
128+
129+
```bash
130+
pwsh ./rclone-ops.ps1 lsd cloud-main:
131+
pwsh ./rclone-ops.ps1 ls archive:bucket-name/path
132+
```
133+
134+
挂载 remote:
135+
136+
```bash
137+
mkdir -p mounts/cloud-main
138+
pwsh ./rclone-ops.ps1 mount cloud-main: mounts/cloud-main -- --vfs-cache-mode writes
139+
```
140+
141+
后台挂载:
142+
143+
```bash
144+
pwsh ./rclone-ops.ps1 mount cloud-main: mounts/cloud-main --background -- --vfs-cache-mode writes
145+
```
146+
147+
卸载挂载点:
148+
149+
```bash
150+
pwsh ./rclone-ops.ps1 unmount mounts/cloud-main
151+
```
152+
153+
复制对象(不会删除目标端多余文件):
154+
155+
```bash
156+
pwsh ./rclone-ops.ps1 copy ./local-dir cloud-main:bucket-name/path -- --progress
157+
```
158+
159+
同步对象默认 dry-run,避免误删:
160+
161+
```bash
162+
pwsh ./rclone-ops.ps1 sync ./local-dir cloud-main:bucket-name/path -- --progress
163+
```
164+
165+
确认 dry-run 输出后,显式追加 `--run` 才会真实执行:
166+
167+
```bash
168+
pwsh ./rclone-ops.ps1 sync ./local-dir cloud-main:bucket-name/path --run -- --progress
169+
```
170+
171+
校验两端数据:
172+
173+
```bash
174+
pwsh ./rclone-ops.ps1 check ./local-dir cloud-main:bucket-name/path -- --one-way
175+
```
176+
177+
## Node.js 版本
178+
179+
本目录保留 `rclone-ops.mjs`。如果你更希望使用 Node.js 版本,可将上面的 `pwsh ./rclone-ops.ps1` 替换为 `node rclone-ops.mjs`,命令语义保持一致。
180+
181+
## 安全边界
182+
183+
- 不自动删除远端数据。
184+
- `sync` 默认 `--dry-run`,真实同步必须显式传 `--run`
185+
- 不在 README、example 或 Git 中保存真实密钥。
186+
- 不自动安装 rclone;缺失时由 `doctor` 提示。
187+
188+
## 参考
189+
190+
- rclone `rcd` 官方文档:<https://rclone.org/commands/rclone_rcd/>
191+
- rclone GUI 官方文档:<https://rclone.org/gui/>
192+
- rclone RC 官方文档:<https://rclone.org/rc/>

0 commit comments

Comments
 (0)