Cloudreve 常用 CLI 命令详解

目标：以 Cloudreve 4.19.1（当前最新稳定版）实测环境为基准，系统梳理 cloudreve 单二进制的全部子命令与参数（逐条附真实回显），并覆盖日常运维高频操作——服务管理、升级、数据目录迁移、数据库备份、任务队列处理。全部命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）实测取得。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS x86_64（uname -m → x86_64）
Cloudreve 版本：4.19.1（Commit #a8becb9，Pro=false，2026-10-22 GitHub Releases 最新稳定版）
安装路径：/opt/cloudreve/cloudreve（systemd 服务 cloudreve 托管，安装见《Ubuntu 22.04 安装 Cloudreve 指南》）
配置文件：/opt/cloudreve/data/conf.ini；数据库默认 SQLite /opt/cloudreve/data/cloudreve.db
管理员账号：admin@quzuo.net / q1w2e3r4（API 操作用）
验证方式说明：文中「实测输出」均为命令在服务器上执行的真实回显；带 <服务器IP> 的仅为示例说明，不影响可执行性

二、CLI 工具概览

v4 的 CLI 相比 v3 大幅精简：没有 --version 参数（实测 cloudreve --version 报 unknown flag: --version，版本号以启动日志横幅为准），全部能力收敛为 6 个子命令。顶层帮助全文（cloudreve --help 实测）：

Self-hosted file management and sharing system, supports multiple storage providers.
Complete documentation is available at https://docs.cloudreve.org/

Usage:
  cloudreve [flags]
  cloudreve [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  eject       Eject all embedded static files
  help        Help about any command
  master-key  Master encryption key management
  migrate     Migrate from v3 to v4
  server      Start a Cloudreve server with the given config file

Flags:
  -c, --conf string       Path to the config file (default "/opt/cloudreve/data/conf.ini")
  -h, --help              help for cloudreve
  -w, --use-working-dir   Use working directory, instead of executable directory

Use "cloudreve [command] --help" for more information about a command.

子命令速查：

子命令	用途	本文实测状态
`server`	启动 Cloudreve 服务（默认行为，不带子命令时等效）	实测（systemd ExecStart）
`master-key`	主加密密钥管理（generate/get/rotate）	generate 实测；get/rotate 见 4.2
`eject`	导出内嵌静态文件（前端资源）	实测
`migrate`	v3 → v4 数据迁移	参数实测（迁移执行见注意事项）
`completion`	生成 shell 自动补全脚本	实测
`help`	查看帮助	实测

全局参数（对所有子命令生效）：

参数	默认值（实测）	说明
`-c, --conf`	`/opt/cloudreve/data/conf.ini`（随可执行文件目录变化）	指定配置文件路径；多实例/自定义路径部署必用
`-w, --use-working-dir`	关	改为在「当前工作目录」而非「可执行文件目录」解析相对路径（data 目录、静态文件等）

💡 说明：--conf 默认值是相对可执行文件所在目录的 data/conf.ini。本文环境主程序在 /opt/cloudreve/cloudreve，因此默认配置路径为 /opt/cloudreve/data/conf.ini——这正是官方推荐把主程序固定在一个目录的原因。

三、前置条件

已按《Ubuntu 22.04 安装 Cloudreve 指南》完成安装并至少成功启动过一次（首次启动生成 conf.ini 与数据库）；
有 root/sudo 权限（服务管理与配置修改）；
sqlite3（仅数据库备份小节需要，apt-get install -y sqlite3 实测安装 Setting up sqlite3 (3.37.2-2ubuntu0.8) ...）；
管理员账号（队列管理等 API 操作用）。

四、核心子命令详解

4.1 server：启动服务

server 是核心子命令（不带子命令直接运行 cloudreve 时也是启动服务）。帮助全文实测：

/opt/cloudreve/cloudreve server --help

Start a Cloudreve server with the given config file

Usage:
  cloudreve server [flags]

Flags:
  -h, --help                 help for server
  -l, --license-key string   License key of your Cloudreve Pro

Global Flags:
  -c, --conf string       Path to the config file (default "/opt/cloudreve/data/conf.ini")
  -w, --use-working-dir   Use working directory, instead of executable directory

--license-key 仅 Pro 版需要（社区版忽略）。生产托管形态为 systemd（unit 文件 ExecStart=/opt/cloudreve/cloudreve，等效于 cloudreve server）。手动前台启动用于排障：

systemctl stop cloudreve
/opt/cloudreve/cloudreve

实测输出（节选，正常启动标志）：

   V4.19.1  Commit #a8becb9  Pro=false
================================================
[Info]   2026-10-22 03:57:04 [...] Current running mode: Master.
[Info]   2026-10-22 03:57:04 [...] Listening to ":5212"

排障结束交回 systemd：

systemctl start cloudreve

启动成功验证（实测）：

systemctl is-active cloudreve

active

4.2 master-key：主加密密钥管理

v4 引入文件级加密的主密钥（Master Key）体系，含三个子命令。顶层帮助实测：

Manage master encryption keys for file encryption. Use subcommands to generate, get, or rotate keys.

Usage:
  cloudreve master-key [flags]
  cloudreve master-key [command]

Available Commands:
  generate    Generate a new master encryption key
  get         Get the current master encryption key
  rotate      Rotate the master encryption key

（1）generate：生成新主密钥（实测可用）。

/opt/cloudreve/cloudreve master-key generate

实测输出：

T7vAAmnlxFFoY2XtZy8q+mtVFnmFCteApmbuRgxTRy4=

输出即 32 字节（256 位）密钥的 base64 文本。支持 -o/--output 写入文件（--help 回显：-o, --output string Output master key to file instead of stdout）。该命令只生成不落库，供初始化加密配置或 rotate 时使用。

（2）get：读取当前主密钥。

/opt/cloudreve/cloudreve master-key get

实测输出（本实例未启用加密，且该子命令启动时会执行数据库 schema 检查，当前版本在此路径触发异常）：

[Panic]  2026-10-22 04:27:23 [...] Fatal error in dependency initialization: failed to migrate database: failed applying schema patches: failed to parse required version : Invalid Semantic Version
panic: Fatal error in dependency initialization: failed to migrate database: failed applying schema patches: failed to parse required version : Invalid Semantic Version

⚠️ 排障实录：master-key get 在 4.19.1 社区版实测触发 Invalid Semantic Version panic（schema patch 版本解析异常）。确认要点：①该异常只影响本 CLI 子命令进程，运行中的服务不受影响（实测 systemctl is-active cloudreve → active、Web 仍 200）；②启用加密后应通过管理面板管理密钥而非本子命令；③该报错出现时先核对 settings 表 db_version_4.19.1 键存在（实测 SELECT name FROM settings WHERE name LIKE 'db_version%' → db_version_4.19.1），服务本体健康即无需处理。

（3）rotate：轮换主密钥（高危，帮助实测）。

/opt/cloudreve/cloudreve master-key rotate --help

Rotate the master encryption key by re-encrypting all encrypted file keys with a new master key.
This operation:
1. Retrieves the current master key
2. Loads a new master key from file
3. Re-encrypts all file encryption keys with the new master key
4. Updates the master key in the settings database

Warning: This is a critical operation. Make sure to backup your database before proceeding.

Usage:
  cloudreve master-key rotate [flags]

官方警告明确：轮换会重加密所有文件密钥，执行前必须备份数据库（备份命令见 5.4 节）。本文不执行该操作。

4.3 eject：导出内嵌静态文件

v4 将前端静态资源内嵌在二进制里，eject 把它们导出为磁盘文件，用于自定义前端（改主题/页面）后再以同名文件覆盖加载。实测：

/opt/cloudreve/cloudreve eject

实测输出（首尾节选）：

[Info]   2026-10-22 04:27:23 [...] Ejecting "/opt/cloudreve/data/statics/version.json"...
[Info]   2026-10-22 04:27:23 [...] Ejecting "/opt/cloudreve/data/statics/workbox-e3490c72.js"...
[Info]   2026-10-22 04:27:23 [...] Finish ejecting static resources.

落点验证（导出到「可执行文件目录/data/statics/」）：

ls /opt/cloudreve/data/statics/ | wc -l
ls /opt/cloudreve/data/statics/ | head -8

实测输出：

9
assets
index.html
locales
pdfviewer.html
service-worker.js
static
sw.js
version.json

⚠️ 注意：eject 会按「可执行文件目录/data/statics」落盘（配合 -w 全局参数可改到工作目录）；导出后重启服务加载的是磁盘版静态文件，升级版本后需重新 eject。

4.4 migrate：v3 → v4 数据迁移

帮助全文实测：

Migrate from v3 to v4

Usage:
  cloudreve migrate [flags]

Flags:
      --force-reset      Force reset migration state and start from beginning
  -h, --help             help for migrate
      --v3-conf string   Path to the v3 config file

Global Flags:
  -c, --conf string       Path to the config file (default "/opt/cloudreve/data/conf.ini")
  -w, --use-working-dir   Use working directory, instead of executable directory

两个参数的含义：--v3-conf 指向 v3 的 conf.ini（迁移器据此定位 v3 数据库与存储配置）；--force-reset 强制重置迁移状态从头开始（迁移中断后重跑用）。迁移在 v4 侧执行：新装 4.x 实例后运行 cloudreve migrate --v3-conf /path/to/v3/conf.ini，将 v3 的用户/文件记录/设置导入 v4 数据库；执行前必须完整备份 v3 数据库与文件目录，并停掉 v3 服务。

💡 说明：v3→v4 属跨大版本迁移，文件实体物理布局与数据库结构都有重构，官方建议先在测试环境演练全流程。本文未执行真实迁移（无 v3 生产数据），参数行为以实测帮助输出与官方文档为准。

4.5 completion：shell 自动补全

支持 bash/zsh/fish/powershell 四种 shell。bash 版实测：

/opt/cloudreve/cloudreve completion bash | head -3
/opt/cloudreve/cloudreve completion bash | wc -l

实测输出：

# bash completion V2 for cloudreve                            -*- shell-script -*-

__cloudreve_debug()
{
338

按官方帮助提示启用（bash 永久生效）：

/opt/cloudreve/cloudreve completion bash > /etc/bash_completion.d/cloudreve
source /etc/bash_completion.d/cloudreve

实测输出（无报错即生效，此后输入 cloudreve 双击 Tab 可补全子命令）：

（命令执行无输出，补全脚本加载成功）

五、常用运维操作

5.1 服务管理（systemd）

日常服务操作与回显（实测）：

systemctl start cloudreve     # 启动
systemctl stop cloudreve      # 停止（SIGTERM 优雅退出）
systemctl restart cloudreve   # 重启
systemctl status cloudreve    # 状态
systemctl enable cloudreve    # 开机自启

状态实测：

● cloudreve.service - Cloudreve file management system
     Loaded: loaded (/etc/systemd/system/cloudreve.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 04:03:03 UTC; 5s ago
   Main PID: 3107 (cloudreve)
      Tasks: 15 (limit: 629145)
     Memory: 108.9M

日志查看（journalctl 实测，最近 5 条）：

journalctl -u cloudreve --no-pager -n 5

Oct 22 04:28:01 cloudreve-server systemd[1]: Started Cloudreve file management system.
Oct 22 04:28:19 cloudreve-server systemd[1]: Stopping Cloudreve file management system...
Oct 22 04:28:19 cloudreve-server systemd[1]: cloudreve.service: Deactivated successfully.
Oct 22 04:28:19 cloudreve-server systemd[1]: Stopped Cloudreve file management system.
Oct 22 04:28:19 cloudreve-server systemd[1]: Started Cloudreve file management system.

⚠️ 注意：B1 使用的 unit 配置为 Restart=on-failure，SIGTERM 优雅退出（exit 0）不会自动拉起（实测 kill 后 Active: inactive (dead)、status=0/SUCCESS）——生产需要「被杀也拉起」改为 Restart=always。

5.2 升级操作

小版本升级三步（4.18.0 → 4.19.1 全流程实测记录见《Ubuntu 22.04 安装 Cloudreve 指南》第八章）：

systemctl stop cloudreve
cp /opt/cloudreve/cloudreve /opt/cloudreve/cloudreve-4180-bak   # 备份旧二进制
cp /opt/cloudreve/cloudreve-4.19.1 /opt/cloudreve/cloudreve      # 放入新版二进制（chmod +x）
systemctl start cloudreve

启动日志实测（新版自动做 schema 迁移检查，既有数据跳过）：

   V4.19.1  Commit #a8becb9  Pro=false
[Info]   ... Default storage policy (ID=1) already exists, skip migrating.
[Info]   ... Default admin group (ID=1) already exists, skip migrating.
[Info]   ... Listening to ":5212"

版本确认方式：启动日志横幅 V4.19.1 Commit #a8becb9（CLI 无 --version 参数）。回滚 = 恢复备份的旧二进制与升级前的数据库备份（schema 迁移是前向单向的，不能只换回旧程序）。

5.3 数据目录迁移（SQLite 数据文件改址）

以「把 SQLite 数据库迁移到独立数据分区 /var/lib/cloudreve」为例，实测全流程：

（1）停止服务并复制数据文件：

systemctl stop cloudreve
mkdir -p /var/lib/cloudreve
cp /opt/cloudreve/data/cloudreve.db /var/lib/cloudreve/cloudreve.db

（2）conf.ini 追加 [Database] 段指定新路径：

printf "\n[Database]\nType = sqlite\nDBFile = /var/lib/cloudreve/cloudreve.db\n" >> /opt/cloudreve/data/conf.ini
tail -4 /opt/cloudreve/data/conf.ini

实测输出：


[Database]
Type = sqlite
DBFile = /var/lib/cloudreve/cloudreve.db

（3）启动并验证数据完整（用管理员登录验证）：

systemctl start cloudreve && sleep 6 && systemctl is-active cloudreve
curl -s -X POST http://127.0.0.1:5212/api/v4/session/token \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@quzuo.net","password":"q1w2e3r4"}' \
  | python3 -c "import sys,json;print('login code:',json.load(sys.stdin)['code'])"
ls -la /var/lib/cloudreve/

实测输出：

active
login code: 0
total 496
drwxr-xr-x 2 root root   4096 Oct 22 04:28 .
drwxr-xr-x 1 root root   4096 Oct 22 04:28 ..
-rw-r--r-- 1 root root 495616 Oct 22 04:28 cloudreve.db

login code: 0 说明管理员账号数据完好，迁移成功。uploads 文件目录同理：移动目录后同步修改存储策略的 dir_name_rule（管理面板 → 存储策略）。

5.4 数据库备份与恢复（SQLite）

在线热备份（sqlite3 .backup 命令，服务不停）：

sqlite3 /opt/cloudreve/data/cloudreve.db ".backup /var/lib/cloudreve/backup-test.db"
ls -la /var/lib/cloudreve/backup-test.db

实测输出：

-rw-r--r-- 1 root root 495616 Oct 22 04:28 /var/lib/cloudreve/backup-test.db

恢复（服务停机后覆盖）：

systemctl stop cloudreve
cp /var/lib/cloudreve/backup-test.db /opt/cloudreve/data/cloudreve.db
systemctl start cloudreve

⚠️ 注意：完整备份 = 数据库文件 + 文件实体目录（data/uploads/，或对应对象存储）+ conf.ini，三者版本必须来自同一时点；外接 MySQL/PostgreSQL 部署时改用 mysqldump/pg_dump 等原生工具。

5.5 任务队列查看与清理

v4 的异步任务（缩略图、媒体元数据、离线下载等）走持久化队列，管理走 Web 管理面板或 API（任务本体的增删查见管理面板「任务队列」页）。接口实测：

（1）任务列表（管理端点）：

TOKEN=$(curl -s -X POST http://127.0.0.1:5212/api/v4/session/token \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@quzuo.net","password":"q1w2e3r4"}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['token']['access_token'])")
curl -s -X POST http://127.0.0.1:5212/api/v4/admin/queue \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"page":1,"page_size":10}'

实测输出（空闲实例任务列表为空）：

{"code":0,"data":{"pagination":{"page":0,"page_size":10},"tasks":[]},"msg":""}

（2）队列指标（5 类队列的实时状态）：

curl -s http://127.0.0.1:5212/api/v4/admin/queue/metrics -H "Authorization: Bearer $TOKEN"

实测输出（节选，指标全 0 = 队列空闲）：

{"code":0,"data":[{"name":"media_meta","busy_workers":0,"success_tasks":0,"failure_tasks":0,"submitted_tasks":0,"suspending_tasks":0},{"name":"recycle",...},{"name":"io_intense",...},{"name":"remote_download",...},{"name":"thumb",...}]}

（3）积压清理与单任务处理： 单个失败/卡死任务用 POST /api/v4/admin/queue/:id 查看详情、POST /api/v4/admin/queue/batch/delete 批量删除、POST /api/v4/admin/queue/cleanup 按状态清理（均带 Authorization: Bearer $TOKEN；对应面板按钮为任务队列页的删除/清理）。五类队列的 worker 数、重试与退避参数在管理面板「设置 → 任务队列」调整（键名清单见《Cloudreve 配置参数详解》第五章），调整后即时生效。

六、注意事项

CLI 无版本参数：cloudreve --version/version 均不存在（实测报错），版本以启动日志横幅为准。
-c 默认值跟随可执行文件位置：把二进制移到别的目录跑，默认配置路径也随之变化；固定部署位置或显式 -c 指定。
eject/数据目录按可执行文件目录解析：需要以工作目录为基准时加 -w（多版本共存排查配置来源时常用）。
CLI 子命令会触发数据库 schema 检查：master-key get 等子命令启动即连库执行迁移检查，4.19.1 实测存在 Invalid Semantic Version panic（见 4.2 节排障实录），不影响运行中服务；遇到先核对服务本体健康再处理。
rotate 是高危操作：执行前必须完成数据库备份（4.2 节官方警告原文）。
migrate 之前先演练：v3→v4 迁移前在测试环境完整演练，--force-reset 只重置迁移状态，不代替备份。

七、常见问题（FAQ）

Q1：cloudreve: command not found？ 未把二进制目录加入 PATH 或未用绝对路径。本文统一用绝对路径 /opt/cloudreve/cloudreve；如需全局命令，ln -s /opt/cloudreve/cloudreve /usr/local/bin/cloudreve 后即可直接输入 cloudreve。

Q2：master-key get 报 panic（Invalid Semantic Version）是不是数据库坏了？ 不是。4.19.1 实测该子命令在 schema patch 检查路径存在版本解析异常（4.2 节实录）。验证服务本体：systemctl is-active cloudreve → active、Web 200、登录正常，即无需处理；主密钥管理走管理面板。

Q3：如何确认当前跑的是哪个版本？ 启动日志横幅（journalctl -u cloudreve | grep Commit 可见 V4.19.1 Commit #a8becb9）；或 settings 表 db_version_4.19.1 键名（实测 SELECT name FROM settings WHERE name LIKE 'db_version%'）。

Q4：升级后服务起不来？ 先看 journalctl -u cloudreve -n 50：数据库 schema 迁移失败多为「数据库文件与二进制版本错配」（如旧库 + 新版二进制之外的场景），用升级前的数据库备份恢复后再启动；端口占用报错处理见《Ubuntu 22.04 安装 Cloudreve 指南》常见问题 Q2。

Q5：备份文件恢复后上传的文件找不到了？ 数据库与文件实体必须同时点配套恢复：只恢复 cloudreve.db 而不恢复 uploads/（或对象存储内容）会出现「记录在、实体丢」。核对 5.4 节完整备份三要素。

八、参考链接

官方文档（命令与部署口径）：https://docs.cloudreve.org/ （2026-10-22 查阅）
GitHub Releases：https://github.com/cloudreve/cloudreve/releases （4.19.1 下载与变更记录）
站内关联文档：《Cloudreve 介绍与选型指南》、《Ubuntu 22.04 安装 Cloudreve 指南》、《Cloudreve 配置参数详解》