Nextcloud 常用 CLI 命令详解

目标：把 Nextcloud 33.0.10 的官方命令行工具 occ 按功能组逐条实测——系统状态、维护、应用、用户、文件、数据库、后台任务、config 读写共 8 组命令，每条命令给出真实输入与回显，并沉淀版本差异（33 已移除/更名命令）与排障实录。

一、环境信息

本文实测环境（与部署篇、配置篇同源）：

操作系统：Ubuntu 22.04.5 LTS（x86_64）；
Nextcloud 33.0.10（内部版本号 33.0.10.1），tarball 安装于 /var/www/nextcloud，Web 运行用户 www-data；
对照环境：Snap 版 nextcloud 33.0.10snap2（occ 入口 /snap/bin/nextcloud.occ）；
occ 调用形态：tarball 路径固定为 sudo -u www-data php /var/www/nextcloud/occ（下文示例统一先 cd /var/www/nextcloud 再 sudo -u www-data php occ ...）；
演示账号：管理员 admin（口令 q1w2e3r4）；临时演示用户 testuser（口令 T3stuser#2026，见第七章创建过程）。

二、工具概览

occ（Nextcloud 的 CLI）是 Symfony Console 实现的命令族，覆盖状态、维护、应用、用户、文件、数据库、后台任务与配置读写。直接敲 occ 不带子命令显示版本与用法（实测）：

cd /var/www/nextcloud
sudo -u www-data php occ

Nextcloud 33.0.10

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output

按功能分组的本文实测命令清单：

功能组	命令	用途
系统状态	`status`、`status --output=json`、`check`	安装状态、版本、健康检查
维护	`maintenance:mode`、`maintenance:repair`、`maintenance:update:htaccess`	维护模式、修复、更新 .htaccess
应用	`app:list`、`app:enable`、`app:disable`、`app:update`	应用启停与升级
用户	`user:list`、`user:add`、`user:info`、`user:lastseen`、`user:resetpassword`、`user:delete`	账号全生命周期
文件	`files:scan`、`files:cleanup`	文件索引重扫、孤儿清理
数据库	`db:add-missing-indices`	补建缺失索引
后台任务	`background:cron`、`cron.php`	后台任务模式与调度
配置	`config:system:get/set/delete`、`config:app:get`、`config:list`	参数读写

💡 说明：本文所有命令都在 33.0.10 上逐条跑过。33 相对早期版本有两处命令变动：安装命令 maintenance:install 已整体移除（部署篇 4.9 节有实测报错）；htaccess 更新命令由 maintenance:update-htaccess 更名为 maintenance:update:htaccess（第五章实测对照）。

三、前置条件

已完成安装（occ status 的 installed 为 true）；
occ 必须以 Web 运行用户身份执行：tarball/Apache 环境为 sudo -u www-data php occ ...；用 root 直跑会因数据目录权限产生报错或以错误身份建文件；
Snap 版以 /snap/bin/nextcloud.occ 调用（无需 sudo，snapd 自行处理权限）；
用户组实测需要管理员权限的 occ 环境；后台任务组需要 cron 包（安装步骤见第十章）。

四、系统状态命令组

4.1 occ status：安装与版本状态

sudo -u www-data php occ status

  - installed: true
  - version: 33.0.10.1
  - versionstring: 33.0.10
  - edition:
  - maintenance: false
  - needsDbUpgrade: false
  - productname: Nextcloud
  - extendedSupport: false

逐项说明：installed 是否完成安装；version/versionstring 内部版本号（建表/升级逻辑用）与展示版本；maintenance 维护模式状态；needsDbUpgrade 代码更新后数据库是否待升级。

脚本化取值用 JSON 输出（实测）：

sudo -u www-data php occ status --output=json

{"installed":true,"version":"33.0.10.1","versionstring":"33.0.10","edition":"","maintenance":false,"needsDbUpgrade":false,"productname":"Nextcloud","extendedSupport":false}

4.2 occ check：健康检查

sudo -u www-data php occ check; echo "退出码: $?"

退出码: 0

💡 说明：check 无问题时不输出任何内容、退出码 0；有问题时逐条列出警告（如缺索引、缓存未配置建议）并可能以非零码退出。它是巡检脚本里最合适的「静默健康探测」。

五、维护命令组

5.1 occ maintenance:mode：维护模式开关

开启（实测）：

sudo -u www-data php occ maintenance:mode --on

Maintenance mode enabled

开启期间状态可见（实测，status 的 maintenance 位同步变化，页面端除管理员外全部只读）：

sudo -u www-data php occ config:system:get maintenance

Nextcloud is in maintenance mode, no apps are loaded.
Commands provided by apps are unavailable.
true

⚠️ 注意：维护模式下 occ 自身仍可运行，但应用提供的命令不可用（如 files:*），输出横幅已提示。关闭实测：

sudo -u www-data php occ maintenance:mode --off

Maintenance mode disabled

5.2 occ maintenance:repair：安装修复

对数据库结构、缓存、应用注册表做一致性修复，升级失败或迁移后跑一次（实测输出节选，完整输出约 30+ 行）：

sudo -u www-data php occ maintenance:repair

 - init metadata
 - Switches from default updater server to the customer one if a valid subscription is available
 - Migrate some config values to lazy loading
 - Send an admin notification if monthly report is disabled
 - Force-reset all Text document sessions
 - Initialize migration of background images from dashboard to theming app
 - Add background job to check for backup codes
 - Populating added database structures for workflows

💡 说明：每行是一个修复步骤，幂等可重复执行；正常实例执行一遍不会改变数据。

5.3 occ maintenance:update:htaccess：更新 .htaccess

33 版的正确命令名是 maintenance:update:htaccess（冒号两段）。先看老命令名的实测报错（排障对照）：

sudo -u www-data php occ maintenance:update-htaccess


  Command "maintenance:update-htaccess" is not defined.

  Did you mean one of these?
      maintenance:data-fingerprint

用正确命令名执行（实测）：

sudo -u www-data php occ maintenance:update:htaccess

.htaccess has been updated

适用场景：tarball 升级后、或手工误改了 Web 根下的 .htaccess 之后重新生成。

六、应用管理命令组

6.1 occ app:list：应用清单

sudo -u www-data php occ app:list

实测回显（节选，Enabled: 段前 22 行）：

Enabled:
  - activity: 6.0.0
  - app_api: 33.0.0
  - bruteforcesettings: 6.0.0
  - circles: 33.0.0
  - cloud_federation_api: 1.17.0
  - comments: 1.23.0
  - contactsinteraction: 1.14.1
  - dashboard: 7.13.0
  - dav: 1.36.1
  - federatedfilesharing: 1.23.0
  - federation: 1.23.0
  - files: 2.5.0
  - files_downloadlimit: 5.1.0
  - files_pdfviewer: 6.0.0
  - files_reminders: 1.6.0
  - files_sharing: 1.25.2
  - files_trashbin: 1.23.0
  - files_versions: 1.26.0
  - firstrunwizard: 6.0.0
  - logreader: 6.0.0
  - lookup_server_connector: 1.21.0

完整输出还包含 Disabled: 段。应用名即 occ 操作的 ID（冒号前），版本号跟在后面。

6.2 occ app:disable / app:enable：停用与启用

以内置相册应用 photos 为例（实测）：

sudo -u www-data php occ app:disable photos
sudo -u www-data php occ app:enable photos

photos 6.0.0 disabled
photos 6.0.0 enabled

6.3 occ app:update：应用升级

sudo -u www-data php occ app:update --all

All apps are up-to-date or no updates could be found

💡 说明：--all 批量升级全部已装应用；也可指定单个应用 occ app:update photos。应用来源由 App Store 配置决定，内网隔离环境会得到「无更新」结果。

七、用户管理命令组

7.1 occ user:list：用户清单

sudo -u www-data php occ user:list

  - admin: admin

输出格式为 - 用户ID: 显示名。

7.2 occ user:add：创建用户（含密码策略排障实录）

创建命令会交互式索要密码（输两遍）。在脚本/非交互环境直接执行会发生密码输入错位，实测报错（供对照）：

sudo -u www-data php occ user:add testuser

Enter password:
Confirm password: Passwords did not match!

⚠️ 排障实录一：脚本/自动化场景必须用环境变量方式 --password-from-env（从 OC_PASS 读密码），不要交互。

⚠️ 排障实录二：短口令会被密码策略拒绝。用 8 位演示口令 q1w2e3r4 实测被拒（普通用户最小长度 10 位 + 弱口令库双重校验，注意这不会拦住安装向导里的管理员口令，仅拦后建用户）：

sudo -u www-data env OC_PASS=q1w2e3r4 php occ user:add --password-from-env testuser

Password is among the 1,000,000 most common ones. Please make it unique. Password needs to be at least 10 characters long. Password is present in compromised password list. Please choose a different password.

改用满足策略的口令后创建成功（实测）：

sudo -u www-data env OC_PASS="T3stuser#2026" php occ user:add --password-from-env testuser

The account "testuser" was created successfully

7.3 occ user:info：用户详情

sudo -u www-data php occ user:info testuser

  - user_id: testuser
  - display_name: testuser
  - email:
  - cloud_id: testuser@http://10.89.65.2
  - enabled: true
  - groups:
  - quota: none
  - storage:
  - first_seen: never
  - last_seen: never
  - user_directory: /var/www/nextcloud/data/testuser
  - backend: Database

💡 说明：cloud_id（联邦标识）把实例地址拼进了账号；user_directory 是该用户数据目录；backend: Database 表示本地数据库账号（对接 LDAP 时显示 LDAP）。

7.4 occ user:lastseen：最后登录时间

创建后未登录时（实测）：

sudo -u www-data php occ user:lastseen testuser

testuser has never logged in.

用 testuser 发起一次真实 Web 请求（WebDAV PROPFIND，HTTP 207 即认证成功），再看 lastseen（实测）：

curl -s -o /dev/null -w '%{http_code}\n' -u testuser:T3stuser#2026 -X PROPFIND -H 'Depth: 0' http://10.89.65.2/remote.php/dav/files/testuser/
sudo -u www-data php occ user:lastseen testuser

207
testuser's last login: 2026-10-22 06:07:21 UTC

7.5 occ user:resetpassword：重置密码

同样走 --password-from-env（实测）：

sudo -u www-data env OC_PASS="T3stuser#2027" php occ user:resetpassword --password-from-env testuser

Successfully reset password for testuser

⚠️ 注意：管理员后台「重置密码」生成的链接依赖邮件服务；occ 方式不依赖邮件，是运维改密的可靠通道。密码策略与 user:add 相同（10 位以上、非弱口令库口令）。

7.6 occ user:delete：删除用户

实测（删除后 user:list 只剩 admin）：

sudo -u www-data php occ user:delete testuser
sudo -u www-data php occ user:list

The specified user was deleted
  - admin: admin

⚠️ 注意：user:delete 会移除该用户在 oc_users 的记录，其数据目录按回收站/清理策略处理；删除前若需保留文件，先由管理员把该用户的共享接收过来。

八、文件扫描与清理命令组

8.1 occ files:scan：重扫文件索引

手工往数据目录拷过文件、或从备份恢复数据后，索引与磁盘不一致时重扫（实测）：

sudo -u www-data php occ files:scan --all

+---------+-------+-----+---------+---------+--------+--------------+
| Folders | Files | New | Updated | Removed | Errors | Elapsed time |
+---------+-------+-----+---------+---------+--------+--------------+
| 6       | 65    | 0   | 0       | 0       | 0      | 00:00:00     |
+---------+-------+-----+---------+---------+--------+--------------+

逐列说明：Folders/Files 扫到的目录与文件数；New/Updated/Removed 本轮入库/更新/移除的索引数；Errors 扫描错误数（非 0 时检查文件属主权限）；Elapsed time 耗时。常用变体：occ files:scan admin（单用户）、occ files:scan --path="admin/files"（指定路径）。

8.2 occ files:cleanup：清理孤儿索引

sudo -u www-data php occ files:cleanup

0 orphaned file cache entries deleted
0 orphaned file cache extended entries deleted
0 orphaned mount entries deleted

💡 说明：删除用户/文件后数据库可能残留孤儿记录，cleanup 一次性回收三类孤儿（文件缓存、扩展缓存、挂载点）；本环境刚做过完整扫描所以全是 0。

九、数据库维护命令组

9.1 occ db:add-missing-indices：补建缺失索引

大实例升级后官方强烈建议执行（实测本环境索引齐全，命令无输出、退出码 0）：

sudo -u www-data php occ db:add-missing-indices; echo "退出码: $?"

退出码: 0

⚠️ 注意：有缺失索引时命令会逐条输出 Adding ... index to ... table 并建索引，大表上耗时明显——先开维护模式再执行是标准做法。同类命令还有 db:add-missing-columns（补缺失列）与 db:add-missing-primary-keys（补缺失主键），用法一致。

十、后台任务命令组

10.1 切换后台任务模式：occ background:cron

Nextcloud 后台任务默认 AJAX 模式（用户开着页面才触发）。生产改为 cron 模式（实测）：

sudo -u www-data php occ background:cron

Set mode for background jobs to 'cron'

⚠️ 版本细节（实测）：33 版该模式不落在 config.php 的 backgroundjobs_mode 键，而是存在应用配置 core 下，验证命令是：

sudo -u www-data php occ config:app:get core backgroundjobs_mode

cron

（occ config:system:get backgroundjobs_mode 在本版本读不到值、退出码 1——别被老文档误导。）

10.2 配置系统 crontab

cron 包未装时先安装并启用（实测）：

apt-get install -y cron

Created symlink /etc/systemd/system/multi-user.target.wants/cron.service → /lib/systemd/system/cron.service.

写入 www-data 的 crontab（追加方式，避免覆盖已有条目；实测）：

(sudo -u www-data crontab -l 2>/dev/null || true; echo "*/5 * * * * php -f /var/www/nextcloud/cron.php") | sudo -u www-data crontab -
sudo -u www-data crontab -l

*/5 * * * * php -f /var/www/nextcloud/cron.php

⚠️ 排障实录：追加写 crontab 时如果直接 crontab -l | crontab -，当前无 crontab 的用户会把错误提示文本一起写进去，实测报 -":0: bad minute / errors in crontab file, can't install.。上面 (crontab -l 2>/dev/null || true; ...) 的写法先吞掉空 crontab 的报错再追加，实测成功。

确认 cron 服务在跑（实测）：

systemctl is-active cron

active

10.3 手动触发一次后台任务：php cron.php

配置后立即验证任务可执行（实测无输出、退出码 0）：

sudo -u www-data php /var/www/nextcloud/cron.php; echo "退出码: $?"

退出码: 0

💡 说明：cron.php 由 crontab 每 5 分钟拉起，无输出即正常；任务执行结果在管理后台「基本设置 → 后台任务」有最近执行时间，也可看 data/nextcloud.log。

十一、config 配置读写命令组

sudo -u www-data php occ config:system:get <键>            # 读系统参数（未设置时无输出、退出码 1）
sudo -u www-data php occ config:system:set <键> --value=<值>  # 写系统参数
sudo -u www-data php occ config:system:delete <键>          # 删除参数回到默认
sudo -u www-data php occ config:app:get <应用> <键>         # 读应用参数（如 core backgroundjobs_mode）
sudo -u www-data php occ config:list system                # 全量导出（敏感值脱敏）

典型写读删一轮（实测，以 loglevel 为例）：

sudo -u www-data php occ config:system:set loglevel --value=1
sudo -u www-data php occ config:system:get loglevel
sudo -u www-data php occ config:system:delete loglevel

System config value loglevel set to string 1
1
System config value loglevel deleted

数组型参数（如 trusted_domains）用「键 + 索引」形态（实测）：

sudo -u www-data php occ config:system:set trusted_domains 2 --value=192.168.1.100
sudo -u www-data php occ config:system:delete trusted_domains 2

System config value trusted_domains => 2 set to string 192.168.1.100
System config value trusted_domains => 2 deleted

config 命令族的完整参数语义、脱敏行为与生产模板见《Nextcloud 配置参数详解》第三章与第五章。

十二、注意事项

身份：tarball 环境所有 occ 命令前缀 sudo -u www-data，否则可能以 root 生成 root 属主文件（重扫文件时尤为危险）；
维护窗口：db:add-missing-indices、maintenance:repair、升级类操作前先 maintenance:mode --on，完成再 --off；
密码策略：user:add / user:resetpassword 的口令须 ≥10 位且不在弱口令库，自动化用 OC_PASS + --password-from-env；
33 版命令变动：maintenance:install 已移除、htaccess 命令更名为 maintenance:update:htaccess、后台任务模式存于 config:app:get core——引用老版本教程时逐一核对；
Snap 版差异：命令入口固定 /snap/bin/nextcloud.occ（非登录 Shell 直接敲 nextcloud.occ 会因 PATH 报 command not found，见《Ubuntu 22.04 安装 Nextcloud 指南》5.4 节排障实录），无需 sudo，但数据/配置路径全部在 /var/snap/nextcloud/ 下。

十三、常见问题（FAQ）

Q1：occ 报 Console has to be executed with the user that owns the file config/config.php？ 执行身份不对。tarball 环境加 sudo -u www-data；Snap 环境直接用 /snap/bin/nextcloud.occ。

Q2：occ maintenance:install 报 Command is not defined？ 33 版已移除该命令。tarball 用 Web 向导完成安装；Snap 用 nextcloud.manual-install（部署篇有实测替代流程）。

Q3：occ 无输出但退出码非 0？ 分两类：config:system:get 读未设置参数时「无输出 + 退出码 1」是正常行为；其余命令无输出 + 非 0 一般是异常，加 -v 重跑看堆栈。

Q4：files:scan 后网页里文件重复出现？ 同一文件被多次入库通常是数据目录里出现了 .ocDataTransferFile-* 传输残留，先 files:cleanup 再扫描；扫描期间避免同时从网页上传。

Q5：background:cron 设置后 config:system:get backgroundjobs_mode 读不到？ 33 版存到应用配置了：occ config:app:get core backgroundjobs_mode（第十章实测）。

Q6：user:add 一直提示密码不合格？ 长度 ≥10 且避开常见口令库；报错信息里会把命中的规则都列出来（第七章实录）。

Q7：Snap 环境 occ 与 tarball 的 occ 输出不一致？ Snap 版把 occ 包装成 /snap/bin/nextcloud.occ，命令集与版本对应（33.0.10snap2 同为 33.0.10.1 内核），输出一致；差异主要在数据/配置路径与无需 sudo。

十四、参考链接

官方 occ 说明：docs.nextcloud.com — Using the occ command
occ 命令总表：docs.nextcloud.com — Occ command list
官方后台任务文档：docs.nextcloud.com — Background jobs
33.0.10 发布页：github.com/nextcloud/server/releases/tag/v33.0.10
本组件部署篇：《Ubuntu 22.04 安装 Nextcloud 指南》
本组件配置篇：《Nextcloud 配置参数详解》
本组件认知篇：《Nextcloud 介绍与选型指南》
同类产品命令参考：《Seafile 12.0.14 常用 CLI 命令详解》、《Syncthing 2.1.7 常用 CLI 命令与工具详解》、《ownCloud 介绍与选型指南》