Nextcloud occ 常用指令整理

Jason Cheng 發布 2025.06.18 瀏覽 1 次

本文目錄

執行 occ 的方式
系統狀態與檢查
維護模式與升級
資料庫
檔案
背景工作
應用程式
使用者與群組
預設語言與地區
Memories 相簿
Recognize 辨識
結論
參考資料

管理自架的 Nextcloud，很多事情在網頁介面做不到，或做起來很慢：檔案直接放進資料目錄後要重新掃描、升級完要補資料庫索引、背景工作卡住要手動處理、某些 app 只想開給特定群組。這些都要靠 Nextcloud 的命令列工具 occ。

這篇整理我平常維護 Nextcloud 用到的 occ 指令，依用途分類，也把 Memories、Recognize 這兩個相簿相關 app 的指令與遇過的問題一起記下來。

2026/10 補充：本文已依 Nextcloud 33～35 的官方管理手冊與原始碼重新查證，指令在這三個版本都能使用；只在特定版本才有的功能會另外註明。

執行 occ 的方式

occ 放在 Nextcloud 的安裝目錄，必須用網頁伺服器的帳號執行，Debian/Ubuntu 是 www-data。用 root 直接執行會產生權限錯誤的檔案。以下範例的安裝目錄都是 /var/www/nextcloud：

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

如果 PHP CLI 沒有開啟 APCu，而 config.php 的 memcache.local 又設成 APCu，執行 occ 會出現錯誤。可以在 PHP CLI 的 php.ini 加上 apc.enable_cli = 1，或每次執行時帶參數：

sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/occ config:list system

指令很長，可以在 root 的 ~/.bashrc 加一個別名，後面的範例都用這個寫法：

alias occ='sudo -u www-data php /var/www/nextcloud/occ'

occ list 列出全部指令，occ help 指令名稱 查看單一指令的參數。

系統狀態與檢查

# 版本、是否安裝完成、是否在維護模式
occ status

# 給指令稿判斷用：維護模式或需要升級時回傳非 0
occ status -e

# 檢查執行環境的相依套件
occ check

# 執行管理介面「概覽」裡的那些安全與設定檢查（Nextcloud 28 起）
occ setupchecks

# 列出 config.php 的設定，--private 會連密碼等敏感值一起顯示
occ config:list system

# 檢查核心檔案有沒有被改動
occ integrity:check-core

occ setupchecks 在 Nextcloud 35 可以在後面接分類與檢查名稱做篩選；33、34 不支援篩選。官方文件寫的 --class=、--category= 參數並不存在。

維護模式與升級

維護模式

occ maintenance:mode --on
occ maintenance:mode --off

關閉後網頁仍顯示維護中，多半是 OPcache 或 PHP-FPM 還留著舊狀態，重新啟動網頁服務（Apache 或 PHP-FPM）即可。

升級

occ upgrade 只執行資料庫遷移，不會下載新版程式。正確的順序是先更新程式碼，再執行 upgrade：

# 用內建的更新程式下載並替換程式碼
sudo -u www-data php /var/www/nextcloud/updater/updater.phar

# 若手動替換程式碼，再執行資料庫遷移
occ upgrade

升級只能一次跨一個主要版本，例如 33 要先升到 34，再升到 35。

修復與補齊

# 一般修復：清理資料庫、重建快取等
occ maintenance:repair

# 包含耗時的修復，例如 MIME 類型遷移
occ maintenance:repair --include-expensive

# 更新 MIME 類型資料表（新增了副檔名對應後使用）
occ maintenance:mimetype:update-db

# 重新產生 .htaccess（改過網址重寫設定或升級後）
occ maintenance:update:htaccess

升級後管理介面若提示「有 MIME 類型遷移可以執行」，就是要跑 --include-expensive 這一行。檔案很多時會跑很久，建議排在離峰時間。

資料庫

升級後管理介面常會提示缺少索引、欄位或主鍵，依提示補上：

occ db:add-missing-indices
occ db:add-missing-columns
occ db:add-missing-primary-keys

# 先看會做什麼，不實際執行
occ db:add-missing-indices --dry-run

# 檔案快取的 ID 欄位轉成 bigint（大型站台）
occ db:convert-filecache-bigint

Nextcloud 35 另外新增了 occ db:schema:check，可以檢查資料庫結構是否與預期一致。

檔案

重新掃描檔案

檔案若是直接放進資料目錄（例如用 rsync 搬移、在主機上直接複製），Nextcloud 不會知道，要重新掃描：

# 掃描所有使用者
occ files:scan --all

# 只掃描特定使用者（可以一次給多個）
occ files:scan alice bob

# 只掃描某個資料夾，路徑要包含 /使用者/files/
occ files:scan --path="/alice/files/專案資料"

# 只掃描還沒掃描過的檔案
occ files:scan --all --unscanned

# 只掃描這一層，不進入子資料夾
occ files:scan --path="/alice/files/專案資料" --shallow

注意：--all 和使用者名稱不要一起用。--all alice 會掃描所有人，後面的使用者名稱被忽略，所以看起來像「指定使用者沒有用」。要指定使用者就不要加 --all。

appdata 目錄（預覽圖、佈景等 app 資料）不會被一般掃描處理，要另外執行：

occ files:scan-app-data

清理與修復

# 清除檔案快取裡已經沒有對應儲存空間的紀錄
occ files:cleanup

# 修復檔案快取的樹狀結構（先用 --dry-run 看結果）
occ files:repair-tree --dry-run

# 清空所有使用者的垃圾桶
occ trashbin:cleanup --all-users

# 清除所有使用者的舊版本
occ versions:cleanup

files:cleanup 清的是儲存空間已經不存在的快取紀錄（例如外部儲存被移除後留下的），不是「主機上被刪掉的檔案」。檔案在主機上被直接刪除，要用上面的 files:scan 重新掃描，Nextcloud 才會更新。

背景工作

系統排程

Nextcloud 的背景工作建議用系統排程執行，先在管理介面或用指令把模式設成 Cron：

occ background:cron

再用網頁伺服器帳號的 crontab 每 5 分鐘執行一次：

crontab -u www-data -e

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

也可以放在 /etc/cron.d/nextcloud，注意這裡的格式要多一欄執行帳號：

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

手動執行一次確認沒有錯誤：

sudo -u www-data php -f /var/www/nextcloud/cron.php

立即處理背景工作

AI 助理的回應、檔案轉換這類工作都排在背景佇列，cron 每 5 分鐘才處理一次。想讓它們馬上執行，可以開一個常駐的 worker（Nextcloud 30 起）：

# 持續處理佇列中的工作，Ctrl+C 結束
occ background-job:worker

# 只處理指定類別的工作（類別名稱可從 background-job:list 查到）
occ background-job:worker '工作類別名稱'

# 執行 1 小時後自動結束
occ background-job:worker -t 1h

-t 可以寫 30（秒）、30s、10m、2h；--once 只處理一個工作就結束。

查看與手動執行個別工作：

occ background-job:list
occ background-job:execute 工作ID

應用程式

列出、啟用、停用

occ app:list
occ app:list --enabled
occ app:list --disabled

# 只列出非內建的 app
occ app:list --shipped false

occ app:enable contacts
occ app:disable contacts

# 忽略版本相容性限制強制啟用（風險自負）
occ app:enable --force 某個app

--shipped 一定要帶值（true 或 false），只寫 --shipped 會出錯。

限制只有特定群組能使用

用 app:enable 搭配 --groups，可以重複多次：

occ app:enable --groups admin --groups sales files_external

files_external enabled for groups: admin, sales

要注意幾點：

app:disable 沒有 --groups 參數，不能「對某個群組停用」，只能整個停用
要修改可使用的群組，再執行一次 app:enable --groups ...，新的清單會取代原本的清單，不是累加
要取消群組限制、恢復所有人都能用，執行不帶 --groups 的 occ app:enable files_external

所以「讓某個群組只能用少數 app」的做法，是反過來把其他 app 限制給「該群組以外」的群組。例如公司有 staff、admin 兩個群組，Talk-Only 群組只能用 Talk，就把其他非核心 app 都限制給 staff、admin：

for app in $(occ app:list --shipped false --output=json | jq -r '.enabled | keys[]'); do
    [ "$app" = "spreed" ] && continue
    occ app:enable --groups staff --groups admin "$app"
done

app:list --output=json 的 enabled 是「app ID 對應版本」的結構，jq -r '.enabled | keys[]' 取出的就是 app ID。部分核心 app 不允許限制群組，指令會回報錯誤，以實際執行結果為準；建議先在測試環境確認。

使用者與群組

# 列出使用者（--disabled 只列停用的、--info 顯示詳細資料）
occ user:list

# 單一使用者的資訊，包含額度與已使用空間
occ user:info alice

# 新增使用者，密碼從環境變數讀取，避免留在指令歷程
export OC_PASS='your-password'
occ user:add --password-from-env --display-name="Alice" -g staff alice

# 重設密碼
occ user:resetpassword --password-from-env alice

# 停用帳號、查最後登入時間
occ user:disable alice
occ user:lastseen alice

# 把使用者加入群組
occ group:adduser staff alice

用 sudo -u www-data 執行時，環境變數要用 sudo -E 才會帶過去，例如 sudo -E -u www-data php /var/www/nextcloud/occ user:add --password-from-env alice。

設定空間額度

occ user:setting alice files quota 5GB

額度沒有專用的指令，就是設定使用者的 files / quota 值。改完可以用 occ user:info alice 確認。

帳號安全

# 使用者手機遺失，停用他的雙因素驗證（第二個參數是驗證方式，例如 totp）
occ twofactorauth:disable alice totp

# 某個 IP 被暴力破解防護擋住，查詢與解除
occ security:bruteforce:attempts 192.168.1.100
occ security:bruteforce:reset 192.168.1.100

預設語言與地區

在 config/config.php 設定預設的介面語言與地區格式：

  'default_language' => 'zh_TW',
  'default_locale' => 'zh_Hant_TW',
  'default_phone_region' => 'TW',

要強制所有人使用、不讓使用者自己改，改用 force_language、force_locale。

注意語言和地區的代碼不一樣：語言是 zh_TW，地區（日期、數字格式）是 zh_Hant_TW。地區寫成 zh_TW 不會報錯，但 Nextcloud 找不到這個地區，會直接退回 en_US。default_phone_region 是 ISO 國碼 TW，填了之後使用者資料的電話號碼不用加國碼。

也可以用 occ 設定，不必直接改檔案：

occ config:system:set default_language --value=zh_TW
occ config:system:set default_locale --value=zh_Hant_TW
occ config:system:set default_phone_region --value=TW

Memories 相簿

建立索引

# 建立或更新索引
occ memories:index

# 全部重新建立
occ memories:index --force

# 只處理特定使用者
occ memories:index -u alice

匯入地理資料庫

Memories 的「地點」功能要先匯入地名資料庫：

occ memories:places-setup

匯入地名時出現 Incorrect string value

匯入到一半出現這樣的錯誤：

Inserted 235500 / 635189 places (37.1%), Last: Al-Barka
  An exception occurred while executing a query: SQLSTATE[22007]: Invalid datetime
  format: 1366 Incorrect string value: '\xF0\xA5\x95\xA2\xE9\x87...' for column `ne
  xtcloud`.`oc_memories_planet`.`name` at row 1

\xF0 開頭的是 4 位元組的 UTF-8 字元（罕用漢字、表情符號），而資料庫連線用的是只支援 3 位元組的 utf8。我的 MariaDB 有一個強制連線編碼的設定檔，把它改成 utf8mb4（Memories 專案的 issue #951 也是這個解法）：

nano /etc/mysql/conf.d/force_utf8.cnf

# 原本
init_connect='SET NAMES utf8'
# 改為
init_connect='SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci'

systemctl restart mariadb
occ memories:places-setup

如果是 Nextcloud 本身的資料庫還不是 utf8mb4，要依官方的 4 位元組支援說明轉換，Nextcloud 的設定 mysql.utf8mb4 也要是 true。

版本對應

Memories 要配合 Nextcloud 版本安裝：9.x、10.x 支援 Nextcloud 34～35，Nextcloud 33 要用 8.x。從 app 商店安裝會自動挑相容的版本。

Recognize 辨識

# 下載機器學習模型
occ recognize:download-models

# 在背景重新辨識全部檔案
occ recognize:recrawl

# 重新整理人臉分群
occ recognize:cluster-faces

# 清除辨識產生、已經沒有用到的標籤
occ recognize:cleanup-tags

要整個重來還有 recognize:reset-tags、recognize:reset-faces、recognize:reset-face-clusters，執行前請確認，結果無法復原。Recognize 也要配合 Nextcloud 版本：11.x 對應 33、12.x 對應 34、13.x 對應 35。

結論

occ 的指令很多，日常真正會用到的大概就是這幾類：狀態檢查、維護模式與升級、補資料庫索引、重新掃描檔案、背景工作與 app 管理。整理時對照了 Nextcloud 33～35 的文件，原本筆記裡的指令大多仍然可用，需要修正的是 /etc/cron.d 要寫執行帳號、地區代碼要用 zh_Hant_TW，以及 files:scan --all 不能搭配使用者名稱。

另外，Nextcloud 35 的官方 occ 文件拆成應用程式、資料庫、檔案、系統、使用者幾個頁面，舊的 occ_command.html 連結在新版文件已經找不到，查詢時記得選對版本。