feat(rclone): 支持从 JSON 配置 WebUI 密码

mudssky · mudssky · commit a61f10f91559 · 2026-04-29T21:11:05.000+08:00
WebUI 密码属于 rclone RC 启动参数，不适合作为 remote section 写入生成的 rclone.conf。运维 JSON 增加 webui section，脚本按命令行、环境变量、JSON、默认值的优先级解析 addr/user/pass，并支持 pass 使用环境变量占位符。

Constraint: 不把真实密码写入示例，保留 RCLONE_RC_PASS 注入方式
Rejected: 写入 rclone.conf remote 段 | rc-pass 不是 remote backend 配置
Confidence: high
Scope-risk: narrow
Directive: WebUI/RC 启动参数应放在运维 JSON 的 webui section 或通过 flag/env 注入，不要混入 remote 配置段
Tested: Pester RcloneOps.Tests.ps1
Tested: node --test config/service/oss/rclone/rclone-ops.test.mjs
Tested: pnpm qa
Tested: pnpm test:pwsh:all
Not-tested: 真实 rclone WebUI 交互登录
diff --git a/config/service/oss/rclone/README.md b/config/service/oss/rclone/README.md
@@ -22,6 +22,7 @@
 2. 每个 remote 必须包含 `name` 与 `type`。
 3. remote 对象中除 `name` 外的字段会按原键名写入 `rclone.conf`。
 4. 字符串值可使用 `${ENV_VAR}` 占位符，从当前进程环境变量读取密钥；缺失变量会直接报错。
+5. 可选的 `webui` section 可配置 `addr`、`user`、`pass`，命令行参数与环境变量优先级高于 JSON。
 
 示例：
 
@@ -47,7 +48,12 @@
       "endpoint": "http://127.0.0.1:9000",
       "force_path_style": "true"
     }
-  ]
+  ],
+  "webui": {
+    "addr": "127.0.0.1:5572",
+    "user": "admin",
+    "pass": "${RCLONE_RC_PASS}"
+  }
 }
 ```
 
@@ -104,7 +110,7 @@ pwsh ./rclone-ops.ps1 doctor
 
 默认监听 `127.0.0.1:5572`。不带 `--background` 时是前台运行模式，命令会持续占用当前终端，并把 rclone 日志直接显示在当前终端；可打开 `http://127.0.0.1:5572` 确认状态，按 `Ctrl+C` 停止。后台模式才会把日志写入 `.runtime/logs/webui.log`。
 
-如果未设置 `RCLONE_RC_PASS`，rclone WebUI 会自动生成临时认证信息；建议日常运维显式设置强密码：
+WebUI 密码可以通过三种方式设置，优先级为命令行 `--pass` > 环境变量 `RCLONE_RC_PASS` > JSON `webui.pass`。如果 JSON 中写了 `${RCLONE_RC_PASS}`，运行前需要导出该环境变量；如果三者都未设置，rclone WebUI 会自动生成临时认证信息。
 
 ```bash
 RCLONE_RC_PASS='强密码' pwsh ./rclone-ops.ps1 webui
diff --git a/config/service/oss/rclone/rclone-ops.mjs b/config/service/oss/rclone/rclone-ops.mjs
@@ -127,6 +127,70 @@ export function resolveEnvPlaceholders(value, context = 'config') {
   })
 }
 
+/**
+ * 安全读取可选 JSON 主配置文件。
+ *
+ * @param {string} path 配置文件路径。
+ * @returns {Record<string, unknown>} 文件存在时返回 JSON 顶层配置，否则返回空对象。
+ */
+function readOptionalConfigValues(path) {
+  if (!existsSync(path)) {
+    return {}
+  }
+  return readConfigValues(path)
+}
+
+/**
+ * 读取嵌套 JSON 配置值。
+ *
+ * @param {Record<string, unknown>} values 顶层 JSON 配置对象。
+ * @param {string} section section 名称。
+ * @param {string} name section 内部键名。
+ * @returns {unknown} 命中的配置值；未命中时返回 undefined。
+ */
+function getNestedConfigValue(values, section, name) {
+  const sectionValue = values?.[section]
+  if (!sectionValue || typeof sectionValue !== 'object' || Array.isArray(sectionValue)) {
+    return undefined
+  }
+  return sectionValue[name]
+}
+
+/**
+ * 按 flag、环境变量、JSON 配置、默认值的优先级解析选项。
+ *
+ * @param {Map<string, string|boolean>} flags 命令行 flag 集合。
+ * @param {string} name flag 名称。
+ * @param {string} envName 环境变量名称。
+ * @param {Record<string, unknown>} configValues 顶层 JSON 配置对象。
+ * @param {string} section JSON section 名称。
+ * @param {string} configName JSON section 内部键名。
+ * @param {string} fallback 默认值。
+ * @returns {string} 解析后的字符串值。
+ */
+export function resolveOptionWithConfig(
+  flags,
+  name,
+  envName,
+  configValues,
+  section,
+  configName,
+  fallback,
+) {
+  const flagValue = flags.get(name)
+  if (typeof flagValue === 'string' && flagValue.length > 0) {
+    return flagValue
+  }
+  if (process.env[envName]) {
+    return process.env[envName]
+  }
+  const configValue = getNestedConfigValue(configValues, section, configName)
+  if (configValue !== undefined && String(configValue).length > 0) {
+    return String(resolveEnvPlaceholders(configValue, `${section}.${configName}`))
+  }
+  return fallback
+}
+
 /**
  * 根据 JSON remotes 数组生成 rclone remote 定义。
  *
@@ -361,14 +425,42 @@ function resolveRcloneRuntime(flags) {
  */
 function commandWebui(flags, passthrough) {
   const { binary, configPath } = resolveRcloneRuntime(flags)
-  const rcAddr = resolveOption(flags, 'addr', 'RCLONE_RC_ADDR', DEFAULT_RC_ADDR)
-  const rcUser = resolveOption(flags, 'user', 'RCLONE_RC_USER', DEFAULT_RC_USER)
-  const rcPass = resolveOption(
+  const sourcePath = resolveOption(
+    flags,
+    'source',
+    'RCLONE_SOURCE_CONFIG_PATH',
+    DEFAULT_SOURCE_PATH,
+  )
+  const sourceValues = readOptionalConfigValues(sourcePath)
+  const rcAddr = resolveOptionWithConfig(
+    flags,
+    'addr',
+    'RCLONE_RC_ADDR',
+    sourceValues,
+    'webui',
+    'addr',
+    DEFAULT_RC_ADDR,
+  )
+  const rcPass = resolveOptionWithConfig(
     flags,
     'pass',
     'RCLONE_RC_PASS',
-    process.env.RCLONE_RC_PASS ?? '',
+    sourceValues,
+    'webui',
+    'pass',
+    '',
   )
+  const rcUser = rcPass
+    ? resolveOptionWithConfig(
+        flags,
+        'user',
+        'RCLONE_RC_USER',
+        sourceValues,
+        'webui',
+        'user',
+        DEFAULT_RC_USER,
+      )
+    : ''
   const isBackground = flags.has('background')
   const logFile = resolveOption(
     flags,
diff --git a/config/service/oss/rclone/rclone-ops.ps1 b/config/service/oss/rclone/rclone-ops.ps1
@@ -271,6 +271,146 @@ function Get-RcloneOpsConfigValue {
     return $null
 }
 
+function Get-RcloneOpsOptionalConfigValues {
+    <#
+    .SYNOPSIS
+        读取可选的 rclone JSON 主配置。
+
+    .PARAMETER ConfigPath
+        JSON 配置文件路径；文件不存在时返回空表。
+
+    .OUTPUTS
+        hashtable。存在配置时返回顶层配置键值，否则返回空 hashtable。
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ConfigPath
+    )
+
+    $resolvedPath = if ([System.IO.Path]::IsPathRooted($ConfigPath)) {
+        $ConfigPath
+    }
+    else {
+        Join-Path (Get-Location).Path $ConfigPath
+    }
+
+    if (-not (Test-Path -LiteralPath $resolvedPath -PathType Leaf)) {
+        return @{}
+    }
+
+    return Read-RcloneOpsConfigValues -ConfigPath $ConfigPath
+}
+
+function Get-RcloneOpsNestedConfigValue {
+    <#
+    .SYNOPSIS
+        读取嵌套 JSON 配置值。
+
+    .PARAMETER ConfigValues
+        顶层 JSON 配置键值。
+
+    .PARAMETER Section
+        顶层 section 名称，例如 `webui`。
+
+    .PARAMETER Name
+        section 内部键名。
+
+    .OUTPUTS
+        object。命中的嵌套配置值；未命中时返回 $null。
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [hashtable]$ConfigValues,
+
+        [Parameter(Mandatory = $true)]
+        [string]$Section,
+
+        [Parameter(Mandatory = $true)]
+        [string]$Name
+    )
+
+    $sectionValue = Get-RcloneOpsConfigValue -Values $ConfigValues -Name $Section
+    if ($null -eq $sectionValue) {
+        return $null
+    }
+
+    $sectionTable = ConvertTo-RcloneOpsHashtable -InputObject $sectionValue
+    return Get-RcloneOpsConfigValue -Values $sectionTable -Name $Name
+}
+
+function Get-RcloneOpsOptionWithConfig {
+    <#
+    .SYNOPSIS
+        按 flag、环境变量、JSON 配置、默认值的优先级解析选项。
+
+    .PARAMETER Flags
+        Split-RcloneOpsArguments 返回的 Flags 哈希表。
+
+    .PARAMETER Name
+        命令行 flag 名称，不包含前缀 `--`。
+
+    .PARAMETER EnvName
+        环境变量名称。
+
+    .PARAMETER ConfigValues
+        顶层 JSON 配置键值。
+
+    .PARAMETER Section
+        JSON section 名称。
+
+    .PARAMETER ConfigName
+        JSON section 内部键名。
+
+    .PARAMETER DefaultValue
+        未提供 flag、环境变量与 JSON 配置时使用的默认值。
+
+    .OUTPUTS
+        System.String。解析后的选项值。
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [hashtable]$Flags,
+
+        [Parameter(Mandatory = $true)]
+        [string]$Name,
+
+        [Parameter(Mandatory = $true)]
+        [string]$EnvName,
+
+        [Parameter(Mandatory = $true)]
+        [hashtable]$ConfigValues,
+
+        [Parameter(Mandatory = $true)]
+        [string]$Section,
+
+        [Parameter(Mandatory = $true)]
+        [string]$ConfigName,
+
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string]$DefaultValue
+    )
+
+    if ($Flags.ContainsKey($Name) -and $Flags[$Name] -is [string] -and -not [string]::IsNullOrWhiteSpace($Flags[$Name])) {
+        return [string]$Flags[$Name]
+    }
+
+    $envValue = [Environment]::GetEnvironmentVariable($EnvName, 'Process')
+    if (-not [string]::IsNullOrWhiteSpace($envValue)) {
+        return $envValue
+    }
+
+    $configValue = Get-RcloneOpsNestedConfigValue -ConfigValues $ConfigValues -Section $Section -Name $ConfigName
+    if ($null -ne $configValue -and -not [string]::IsNullOrWhiteSpace([string]$configValue)) {
+        return [string](Resolve-RcloneOpsEnvPlaceholder -Value $configValue -Context "$Section.$ConfigName")
+    }
+
+    return $DefaultValue
+}
+
 function Resolve-RcloneOpsEnvPlaceholder {
     <#
     .SYNOPSIS
@@ -619,11 +759,13 @@ function Start-RcloneOpsWebUi {
         [string[]]$Passthrough
     )
 
+    $sourcePath = Get-RcloneOpsOption -Flags $Flags -Name 'source' -EnvName 'RCLONE_SOURCE_CONFIG_PATH' -DefaultValue $script:DefaultSourcePath
+    $sourceValues = Get-RcloneOpsOptionalConfigValues -ConfigPath $sourcePath
     $rclone = Get-RcloneOpsOption -Flags $Flags -Name 'rclone' -EnvName 'RCLONE_BIN' -DefaultValue 'rclone'
     $configPath = Get-RcloneOpsOption -Flags $Flags -Name 'config' -EnvName 'RCLONE_CONFIG_PATH' -DefaultValue $script:DefaultConfigPath
-    $rcAddr = Get-RcloneOpsOption -Flags $Flags -Name 'addr' -EnvName 'RCLONE_RC_ADDR' -DefaultValue $script:DefaultRcAddr
-    $rcPass = Get-RcloneOpsOption -Flags $Flags -Name 'pass' -EnvName 'RCLONE_RC_PASS' -DefaultValue ''
-    $rcUser = if ($rcPass) { Get-RcloneOpsOption -Flags $Flags -Name 'user' -EnvName 'RCLONE_RC_USER' -DefaultValue $script:DefaultRcUser } else { '' }
+    $rcAddr = Get-RcloneOpsOptionWithConfig -Flags $Flags -Name 'addr' -EnvName 'RCLONE_RC_ADDR' -ConfigValues $sourceValues -Section 'webui' -ConfigName 'addr' -DefaultValue $script:DefaultRcAddr
+    $rcPass = Get-RcloneOpsOptionWithConfig -Flags $Flags -Name 'pass' -EnvName 'RCLONE_RC_PASS' -ConfigValues $sourceValues -Section 'webui' -ConfigName 'pass' -DefaultValue ''
+    $rcUser = if ($rcPass) { Get-RcloneOpsOptionWithConfig -Flags $Flags -Name 'user' -EnvName 'RCLONE_RC_USER' -ConfigValues $sourceValues -Section 'webui' -ConfigName 'user' -DefaultValue $script:DefaultRcUser } else { '' }
     $isBackground = $Flags.ContainsKey('background')
     $logFile = Get-RcloneOpsOption -Flags $Flags -Name 'log-file' -EnvName 'RCLONE_LOG_FILE' -DefaultValue (Join-Path $script:DefaultLogDir 'webui.log')
     if ($isBackground) {
diff --git a/config/service/oss/rclone/rclone-ops.test.mjs b/config/service/oss/rclone/rclone-ops.test.mjs
@@ -6,6 +6,7 @@ import {
   parseArgs,
   renderRcloneConfig,
   resolveEnvPlaceholders,
+  resolveOptionWithConfig,
 } from './rclone-ops.mjs'
 
 describe('rclone-ops JSON 配置生成逻辑', () => {
@@ -80,6 +81,24 @@ describe('rclone-ops JSON 配置生成逻辑', () => {
     assert.throws(() => buildRemoteDefinitions({}), /配置缺少 remotes 数组/)
   })
 
+
+  it('能从 JSON webui section 读取 RC 密码', () => {
+    process.env.RCLONE_RC_PASS = 'json-rc-pass'
+
+    assert.equal(
+      resolveOptionWithConfig(
+        new Map(),
+        'pass',
+        'UNUSED_RCLONE_RC_PASS',
+        { webui: { pass: '${RCLONE_RC_PASS}' } },
+        'webui',
+        'pass',
+        '',
+      ),
+      'json-rc-pass',
+    )
+  })
+
   it('能渲染并重新读取 remote 名称', () => {
     const config = renderRcloneConfig([
       { name: 'cloud-main', type: 's3', provider: 'Other' },
diff --git a/config/service/oss/rclone/rclone.config.example.json b/config/service/oss/rclone/rclone.config.example.json
@@ -21,5 +21,10 @@
       "force_path_style": "true",
       "no_check_bucket": "true"
     }
-  ]
+  ],
+  "webui": {
+    "addr": "127.0.0.1:5572",
+    "user": "admin",
+    "pass": "${RCLONE_RC_PASS}"
+  }
 }
diff --git a/tests/RcloneOps.Tests.ps1 b/tests/RcloneOps.Tests.ps1
@@ -36,7 +36,8 @@ AfterAll {
             'Get-RcloneOpsRemoteName',
             'Read-RcloneOpsConfigValues',
             'Resolve-RcloneOpsEnvPlaceholder',
-            'Split-RcloneOpsArguments'
+            'Split-RcloneOpsArguments',
+            'Get-RcloneOpsOptionWithConfig'
         )) {
         Remove-Item -Path ("Function:\{0}" -f $functionName) -ErrorAction SilentlyContinue
     }
@@ -134,6 +135,22 @@ Describe 'rclone-ops.ps1 JSON 配置生成逻辑' {
         { Read-RcloneOpsConfigValues -ConfigPath $envPath } | Should -Throw 'rclone-ops 仅支持 JSON 主配置*'
     }
 
+
+    It '能从 JSON webui section 读取 RC 密码' {
+        $env:RCLONE_RC_PASS = 'json-rc-pass'
+        $values = @{
+            webui = [pscustomobject]@{
+                addr = '100.64.0.1:5572'
+                user = 'admin'
+                pass = '${RCLONE_RC_PASS}'
+            }
+        }
+
+        $password = Get-RcloneOpsOptionWithConfig -Flags @{} -Name 'pass' -EnvName 'UNUSED_RCLONE_RC_PASS' -ConfigValues $values -Section 'webui' -ConfigName 'pass' -DefaultValue ''
+
+        $password | Should -Be 'json-rc-pass'
+    }
+
     It '能解析透传参数与布尔开关' {
         $parsed = Split-RcloneOpsArguments -ArgumentList @('source', 'dest', '--run', '--', '--progress')
 

Original file line number	Diff line number	Diff line change
`@@ -21,5 +21,10 @@`
`21`	`21`	`"force_path_style": "true",`
`22`	`22`	`"no_check_bucket": "true"`
`23`	`23`	`}`
`24`		`- ]`
	`24`	`+ ],`
	`25`	`+ "webui": {`
	`26`	`+ "addr": "127.0.0.1:5572",`
	`27`	`+ "user": "admin",`
	`28`	`+ "pass": "${RCLONE_RC_PASS}"`
	`29`	`+ }`
`25`	`30`	`}`