OpenCloud 常用 CLI 命令详解

OpenCloud 8.1.0 命令行全量实测：opencloud 主命令树与 version/list/init、decomposedfs/posixfs/trash/revisions 等存储运维子命令、Graph API 用户与组管理全链路（含 mailNickname 报错、禁用缓存窗口、changePassword 404 实录）、WebDAV 上传下载 md5 校验闭环。

OpenCloudOpenCloud文件共享文件存储Go2026/10/22

OpenCloud 常用 CLI 命令详解

目标：系统梳理 OpenCloud 8.1.0 的命令行使用：单二进制 opencloud 主命令树（version/list/init/server 与存储运维子命令组），以及以 Graph API（curl）为主的用户、组、文件日常管理操作。全部命令均于 2026-10-22 在 Ubuntu 22.04 服务器上逐条输入执行，输出逐行照抄；涉及数据写操作或定位未完成的条目均如实标注。

一、环境信息

本章列出实测环境的软件与路径信息，后文所有命令均在此环境执行并可复现。

项目值
操作系统Ubuntu 22.04（x86_64）
OpenCloud 版本8.1.0（Edition: rolling，2026-10-05 编译）
安装方式官方单二进制 + systemd 托管（见本专栏《Ubuntu 22.04 安装 OpenCloud 指南》）
二进制路径/usr/local/bin/opencloud
环境变量文件/etc/opencloud/opencloud.env
数据目录/var/lib/opencloud
对外访问地址https://10.89.56.2:9200
管理员账号admin / q1w2e3r4
命令行认证HTTP Basic Auth（PROXY_ENABLE_BASIC_AUTH=true，见《OpenCloud 配置参数详解》 6.4）

二、工具概览

2.1 一个二进制，三种角色

OpenCloud 没有独立的运维工具集，全部命令行能力集中在 opencloud 一个二进制里，按用途分三类：

类别命令用途
服务端init / server / version / list初始化、启动全栈服务、查版本、查运行服务
存储运维decomposedfs / posixfs / trash / revisions / shares / backup / benchmark元数据检查、存储扫描、回收站与版本清理、备份校验、性能压测
单服务调试graph / idm / proxy / storage-users 等 30 余个服务名同名声令单独启动某个服务（全栈模式下一般不用）

日常账号与文件管理则通过 Graph API 完成（curl 即可），本文第六、七章逐条实测。

2.2 主命令树：opencloud help

opencloud help 输出主命令树（实测全量）：

$ opencloud help
opencloud

Usage:
  opencloud [command]

Storage
  decomposedfs       cli tools to inspect and manipulate a decomposedfs storage.
  posixfs            cli tools to inspect and manipulate a posixfs storage.

Server
  init               initialise an OpenCloud config
  server             start a fullstack server (runtime and all services in supervised mode)
  version            print the version of this binary and all running service instances

Service
  activitylog ... antivirus ... auth-app/auth-basic/auth-bearer/auth-machine/auth-service, clientlog, collaboration, eventhistory, frontend, gateway, graph, groups, idm, idp, invitations, nats, notifications, ocm, ocs, policies, postprocessing, proxy, search, settings, sharing, sse, storage-publiclink, storage-shares, storage-system, storage-users, thumbnails, userlog, users, web, webdav, webfinger

Additional Commands:
  backup             OpenCloud backup functionality
  benchmark          cli tools to test low and high level performance
  completion         Generate the autocompletion script for the specified shell
  help               Help about any command
  list               list OpenCloud services running in the runtime (supervised mode)
  revisions          OpenCloud revisions functionality
  shares             cli tools to manage entries in the share manager.
  trash              OpenCloud trash functionality

Flags:
  -h, --help      help for opencloud
  -v, --version   version for opencloud

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

2.3 直接敲 opencloud 会怎样（实录）

裸执行 opencloud（不带子命令）不是打印帮助，而是尝试连 runtime 并报 NATS 连接错误：

$ opencloud
could not list services: Failed to connect to NATS Server: nats: no servers available for connection
Failed to connect to NATS Server: nats: no servers available for connection

查看帮助的正确姿势是 opencloud help 或 opencloud <command> --help。

三、前置条件

3.1 安装与服务运行

以下命令假设 OpenCloud 已安装并以 systemd 托管运行（安装与 systemd 配置全过程见《Ubuntu 22.04 安装 OpenCloud 指南》）：

$ systemctl is-active opencloud
active

3.2 确认 basic auth 已开启

本文所有 curl 均使用 -u admin:q1w2e3r4，依赖 env 文件中的 PROXY_ENABLE_BASIC_AUTH=true；若生产关闭了该开关，先临时开启并重启（参数行为见《OpenCloud 配置参数详解》 6.4）。

3.3 确认版本

$ opencloud version
Version: 8.1.0
Edition: rolling
Compiled: 2026-10-05 00:00:00 +0000 UTC

四、服务与运行时命令

4.1 opencloud version：版本与服务实例

在服务运行中执行 opencloud version，除版本号外还会附上已注册服务实例表（实测）：

$ opencloud version
Version: 8.1.0
Edition: rolling
Compiled: 2026-10-05 00:00:00 +0000 UTC

┌─────────┬────────────────┬────────────────────────────────────────────────────────────────────┐
│ Version │    Address     │                                 Id                                 │
├─────────┼────────────────┼────────────────────────────────────────────────────────────────────┤
│ 8.1.0   │ 127.0.0.1:9164 │ eu.opencloud.api.app-provider-dfc7a4e1-7cab-48f1-ba72-0c62701765e1 │
└─────────┴────────────────┴────────────────────────────────────────────────────────────────────┘

表格中是 app-provider 服务在内部注册表中的实例（地址 127.0.0.1:9164 为内部端口，仅本机可达）。

4.2 opencloud list：运行中服务清单

opencloud list 列出 runtime（supervised 模式）拉起的全部服务，实测共 34 个：

$ opencloud list
┌────────────────────┐
│      SERVICE       │
├────────────────────┤
│ activitylog        │
│ app-provider       │
│ app-registry       │
│ auth-app           │
│ auth-basic         │
│ auth-machine       │
│ auth-service       │
│ clientlog          │
│ eventhistory       │
│ frontend           │
│ gateway            │
│ graph              │
│ groups             │
│ idm                │
│ idp                │
│ nats               │
│ ocm                │
│ ocs                │
│ postprocessing     │
│ proxy              │
│ search             │
│ settings           │
│ sharing            │
│ sse                │
│ storage-publiclink │
│ storage-shares     │
│ storage-system     │
│ storage-users      │
│ thumbnails         │
│ userlog            │
│ users              │
│ web                │
│ webdav             │
│ webfinger          │
└────────────────────┘

该命令的参数（实测 --help）：

$ opencloud list --help
list OpenCloud services running in the runtime (supervised mode)

Flags:
      --hostname string   (default "localhost")
      --port string       (default "9250")

默认连本机 9250 的 runtime 控制端口（端口布局见《OpenCloud 配置参数详解》 6.3），因此只能在服务本机执行。

4.3 opencloud init 与 opencloud server

init 负责生成配置（含全部密钥），server 以 supervised 模式拉起全部服务。两者参数实测如下：

$ opencloud init --help
initialise an OpenCloud config

Usage:
  opencloud init [flags]

Flags:
      --admin-password string   Set admin password instead of using a random generated one
      --config-path string      Config path for the OpenCloud runtime (default "/root/.opencloud/config")
  -d, --diff                    Show the difference between the current config and the new one
  -f, --force-overwrite         Force overwrite existing config file
  -h, --help                    help for init
      --insecure string         Allow insecure OpenCloud config (default "ask")
  -q, --quiet                   Work quietly. Surpresses and non-error message

$ opencloud server --help
start a fullstack server (runtime and all services in supervised mode)

Usage:
  opencloud server [flags]

Flags:
  -h, --help   help for server

init 的执行回显与注意事项（--insecure yes、--admin-password、必须先 export OC_CONFIG_DIR/OC_BASE_DATA_PATH/OC_URL）见《Ubuntu 22.04 安装 OpenCloud 指南》第五章；生产由 systemd 托管 opencloud server，一般无需手动执行。

五、存储运维子命令

OpenCloud 把存储元数据（空间、节点、文件元信息）保存在 decomposedfs 的数据目录里，配套一组检查/修复/清理命令。本组命令多数会读写数据目录，生产执行前先停服务或确认只读性质。

5.1 decomposedfs 组

$ opencloud decomposedfs --help
cli tools to inspect and manipulate a decomposedfs storage.

Available Commands:
  check-treesize  cli tool to check the treesize metadata of a Space
  metadata        cli tools to inspect and manipulate node metadata

check-treesize（检查/修复空间大小元数据），参数实测：

$ opencloud decomposedfs check-treesize --help
cli tool to check the treesize metadata of a Space

Usage:
  opencloud decomposedfs check-treesize [flags]

Flags:
      --force         Do not prompt for confirmation when running in repair mode.
  -h, --help          check-treesize help for check-treesize
  -n, --node string   Space ID of the Space to inspect
      --repair        Try to repair nodes with incorrect treesize metadata. IMPORTANT: Only use this while OpenCloud is not running.
  -r, --root string   Path to the root directory of the decomposedfs

缺参数直接执行会报必填缺失（实测）：

$ opencloud decomposedfs check-treesize
required flag(s) "node", "root" not set

--repair 说明中明确要求仅在 OpenCloud 停止运行时使用——它是唯一带修复写能力的参数，务必停服执行。

metadata（读取/修改节点元数据）：

$ opencloud decomposedfs metadata --help
cli tools to inspect and manipulate node metadata

Usage:
  opencloud decomposedfs metadata [command]

Available Commands:
  dump        print the metadata of the given node. String attributes will be enclosed in quotes. Binary attributes will be returned encoded as base64 with their value being prefixed with '0s'.
  get         print a specific attribute of the given node. String attributes will be enclosed in quotes. Binary attributes will be returned encoded as base64 with their value being prefixed with '0s'.
  set         manipulate metadata of the given node. Binary attributes can be given hex encoded (prefix by '0x') or base64 encoded (prefix by '0s').

Flags:
  -h, --help          help for metadata
  -n, --node string   Path to or ID of the node to inspect
  -r, --root string   Path to the root directory of the decomposedfs

metadata dump/get 是只读的元数据排查利器；metadata set 直接改底层元数据，仅限官方支持指导下使用。

5.2 posixfs 组

$ opencloud posixfs --help
cli tools to inspect and manipulate a posixfs storage.

Available Commands:
  consistency  Check the consistency of the posixfs storage
  index        Add spaces from the filesystem to the index
  scan         Perform a filesystem scan and update the ID and filemetadata cache

仅当存储驱动切换为 posixfs（STORAGE_USERS_DRIVER，见《OpenCloud 配置参数详解》 8.1）时使用；默认 decomposedfs 部署用不到。

5.3 trash 与 revisions 组

$ opencloud trash --help
OpenCloud trash functionality

Available Commands:
  purge-empty-dirs  purge empty directories

$ opencloud revisions --help
OpenCloud revisions functionality

Available Commands:
  purge  purge revisions

用途：清理回收站空目录（trash purge-empty-dirs）、批量清理文件历史版本（revisions purge）。二者都是删数据的操作，执行前确认备份（备份思路见 5.4 与《OpenCloud 配置参数详解》 8.3）。

5.4 shares 与 backup 组

$ opencloud shares --help
cli tools to manage entries in the share manager.

Available Commands:
  cleanup  clean up stale entries in the share manager.

$ opencloud backup --help
OpenCloud backup functionality

Available Commands:
  consistency  check backup consistency

shares cleanup 清理分享管理器中的失效条目；backup consistency 校验备份一致性——做离线冷备后可用它复核。

5.5 benchmark 组

$ opencloud benchmark --help
cli tools to test low and high level performance

Available Commands:
  client    Start a client that continuously makes web requests and prints stats. The options mimic curl, but we default to PROPFIND requests.
  syscalls  test the performance of syscalls

benchmark client 模拟 curl 式持续请求并输出统计（默认 PROPFIND），可对运行中的入口做只读压测；benchmark syscalls 测底层系统调用性能。压测请在非生产时段执行。

六、用户与组管理（Graph API）

OpenCloud 内置 Graph API（微软 Graph 风格），配合 curl 与 basic auth 即可完成用户/组全生命周期管理。下述命令均在服务本机执行，-k 用于跳过自签证书校验。

6.1 创建用户：userPrincipalName 与必填字段

创建用户的必填字段是 onPremisesSamAccountName（登录名）。先用 mailNickname 尝试会直接被拒（实测）：

$ curl -sk -u admin:q1w2e3r4 -X POST https://localhost:9200/graph/v1.0/users -H "Content-Type: application/json" -d '{"accountEnabled":true,"displayName":"Zhang San","mailNickname":"zhangsan","userPrincipalName":"zhangsan@example.org","passwordProfile":{"password":"Zs#2026Ok1"}}'
{"error":{"code":"invalidRequest","innererror":{"date":"2026-10-22T04:05:29Z","request-id":"opencloud/n4BVFCdDlS-000052"},"message":"invalid request body: no value given for required property onPremisesSamAccountName"}}

改用 onPremisesSamAccountName 创建成功（实测）：

$ curl -sk -u admin:q1w2e3r4 -X POST https://localhost:9200/graph/v1.0/users -H "Content-Type: application/json" -d '{"accountEnabled":true,"displayName":"Zhang San","onPremisesSamAccountName":"zhangsan","mail":"zhangsan@example.org","passwordProfile":{"password":"Zs#2026Ok1"}}'
{"accountEnabled":true,"displayName":"Zhang San","id":"04962814-24aa-4b74-a025-a6e94a5fd813","mail":"zhangsan@example.org","onPremisesSamAccountName":"zhangsan","surname":"zhangsan","userType":"Member"}

记下返回的 id（后续组成员引用要用）。密码复杂度受密码策略约束（OC_PASSWORD_POLICY_*，见《OpenCloud 配置参数详解》 9.3）。

6.2 查询用户列表与单个用户

$ curl -sk -u admin:q1w2e3r4 "https://localhost:9200/graph/v1.0/users?\$select=displayName,onPremisesSamAccountName,mail"
admin | Admin | admin@example.org
zhangsan | Zhang San | zhangsan@example.org
$ curl -sk -u admin:q1w2e3r4 "https://localhost:9200/graph/v1.0/users/zhangsan?\$select=accountEnabled,displayName"
{"accountEnabled":true,"displayName":"Zhang San","id":"04962814-24aa-4b74-a025-a6e94a5fd813",...}

6.3 新用户登录验证

用新建账号请求其 WebDAV 目录，207 即登录与授权正常（实测）：

$ curl -sk -u zhangsan:Zs#2026Ok1 -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/zhangsan/
207

6.4 禁用与启用用户

禁用通过 PATCH accountEnabled:false 完成（实测）：

$ curl -sk -u admin:q1w2e3r4 -X PATCH https://localhost:9200/graph/v1.0/users/zhangsan -H "Content-Type: application/json" -d '{"accountEnabled":false}' -o /dev/null -w "%{http_code}\n"
200
$ curl -sk -u admin:q1w2e3r4 "https://localhost:9200/graph/v1.0/users/zhangsan?\$select=accountEnabled"
{"accountEnabled":false,...}
$ curl -sk -u zhangsan:Zs#2026Ok1 -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/zhangsan/
401

注意：PATCH 成功后的一瞬间旧会话/缓存仍可能放行一次请求（实测曾出现一次 207，属 LDAP 缓存窗口，数秒内收敛为 401），审计时不要把这几秒误判为「禁用失败」。重新启用把字段改回 true 即可，实测 200 且登录恢复 207。

6.5 组管理：建组、加成员、查成员

$ curl -sk -u admin:q1w2e3r4 -X POST https://localhost:9200/graph/v1.0/groups -H "Content-Type: application/json" -d '{"displayName":"project-alpha"}'
{"displayName":"project-alpha","groupTypes":[],"id":"7d93dd6c-1e8d-4d19-ad14-2dca3a97436b"}

加成员用 members/$ref，@odata.id 指向用户资源（实测 204 无返回体）：

$ curl -sk -u admin:q1w2e3r4 -X POST "https://localhost:9200/graph/v1.0/groups/7d93dd6c-1e8d-4d19-ad14-2dca3a97436b/members/\$ref" -H "Content-Type: application/json" -d '{"@odata.id":"https://10.89.56.2:9200/graph/v1.0/users/04962814-24aa-4b74-a025-a6e94a5fd813"}' -o /dev/null -w "%{http_code}\n"
204
$ curl -sk -u admin:q1w2e3r4 "https://localhost:9200/graph/v1.0/groups/7d93dd6c-1e8d-4d19-ad14-2dca3a97436b/members?\$select=displayName"
[{"accountEnabled":true,"displayName":"Zhang San",...}]

注意 @odata.id 必须写完整 URL 且主机部分与 OC_URL 一致，用 localhost 拼接会被拒绝（服务端按 issuer 校验资源引用）。

6.6 删除用户

$ curl -sk -u admin:q1w2e3r4 -X DELETE https://localhost:9200/graph/v1.0/users/zhangsan -o /dev/null -w "%{http_code}\n"
204

删除返回 204；用户目录中的文件数据仍留存于存储中，但账户与授权关系即刻失效。

七、文件操作闭环（WebDAV）

日常文件操作走 WebDAV 端点 /remote.php/dav/files/<用户名>/，curl 即可完成上传、列表、下载的完整闭环（管理员对自己的目录操作实测如下）。

7.1 上传（PUT → 201）

$ printf "Hello OpenCloud 8.1.0!\nWeb upload/download closed-loop verification.\n" > /tmp/hello-opencloud.txt
$ curl -sk -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" -X PUT -T /tmp/hello-opencloud.txt https://localhost:9200/remote.php/dav/files/admin/hello-opencloud.txt
201

7.2 列目录（PROPFIND）

$ curl -sk -u admin:q1w2e3r4 -X PROPFIND -H "Depth: 1" https://localhost:9200/remote.php/dav/files/admin/ | grep -o "<d:href>[^<]*</d:href>"
<d:href>/remote.php/dav/files/admin/</d:href>
<d:href>/remote.php/dav/files/admin/hello-opencloud.txt</d:href>
<d:href>/remote.php/dav/files/admin/Shares/</d:href>

Depth: 1 只列一层；返回中天然包含 Shares/ 目录（他人分享的挂载入口）。

7.3 下载与完整性比对（GET + md5）

$ curl -sk -u admin:q1w2e3r4 https://localhost:9200/remote.php/dav/files/admin/hello-opencloud.txt
Hello OpenCloud 8.1.0!
Web upload/download closed-loop verification.
$ md5sum /tmp/hello-opencloud.txt
4f75d14bcf9a68d4d4a6540c79cc4391  /tmp/hello-opencloud.txt

下载内容与源文件逐字节一致（md5 比对通过），闭环完成。

八、注意事项

  1. opencloud list/裸 opencloud 依赖本机 runtime 端口 9250，只能在服务所在主机执行；远程巡检改用 curl https://<host>:9200/ 的接口探活。
  2. 创建用户必填 onPremisesSamAccountName，不是 mailNickname（6.1 实录）。
  3. 禁用用户的生效有数秒缓存窗口，紧跟 PATCH 的首次验证可能仍 207，数秒后收敛为 401（6.4 实录）。
  4. 数据写操作类子命令（repair/purge/cleanup/set）先停服或备份：check-treesize --repair 的帮助文本明确要求 OpenCloud 停止运行时使用。
  5. 改密走 Web 界面：Graph API 未提供 changePassword 端点（404，见 9.4），IDM_ADMIN_PASSWORD 亦仅首次建库生效（见《OpenCloud 配置参数详解》 7.1）。
  6. 排障先开 debug 日志：OC_LOG_LEVEL=debug + journalctl，用完改回（见《OpenCloud 配置参数详解》 5.1）。

九、常见问题与排障实录

9.1 Q1：裸执行 opencloud 报 NATS 错误

现象与原因见 2.3：opencloud 不带子命令会尝试连 runtime/NATS 而非打印帮助。用 opencloud help 或 opencloud <command> --help。

9.2 Q2：创建用户报 no value given for required property onPremisesSamAccountName

请求体用了 mailNickname 携带登录名（6.1 实录）。把登录名放到 onPremisesSamAccountName 字段即可。

9.3 Q3：禁用用户后第一笔请求仍是 207

LDAP 缓存窗口（6.4 实录），数秒内收敛为 401。脚本化审计时在 PATCH 后等待几秒再验证。

9.4 Q4：调 users/admin/changePassword 返回 404

$ curl -sk -u admin:q1w2e3r4 -X POST https://localhost:9200/graph/v1.0/users/admin/changePassword -H "Content-Type: application/json" -d '{"password":"Q1w2e3r4New"}'
{"error":...} 404

该端点在 8.1.0 中不存在。管理员改密走 Web 界面账号设置；批量场景可考虑重建 idm 库（会清空全部本地账号与组，慎用，见《OpenCloud 配置参数详解》 7.1）。

9.5 Q5：check-treesize 报 Can not find node

实测过程：先按 Graph /graph/v1.0/drives 返回的 drive id（形如 b9df3fc7-...$d9e8753a-...）传 --node，分别以 /var/lib/opencloud/storage/metadata 与 /var/lib/opencloud/storage/users 作 --root，均报：

Can not find node 'b9df3fc7-5aa9-491e-a8a3-7f31bf3b8e51$d9e8753a-be5c-41d5-bc3e-51015459ad6c'

--node 期望的是 decomposedfs 内部节点标识，与 Graph drive id 不是同一体系（数据目录下实测存在 metadata/ocm/users 三个挂载子目录）。本文未继续深挖其取值规则；一般排障用 metadata dump/get 或直接核对目录即可，check-treesize 留给空间大小元数据疑似损坏、且有停机窗口时再结合官方支持使用。

十、参考链接