Nextcloudアップデート手順と失敗時の対処

管理者

2日前

自前運用のNextcloudを安全にNextcloud アップデートしたいときは、手順そのものより「要件確認・バックアップ・失敗時の切り分け」の準備が成否を分けます。

本記事は公式ドキュメントを優先し、Ubuntu＋Apache＋PHP-FPM＋www-data想定の実行可能なコマンドで、Web/CLI Updater・手動更新・occ upgrade・よくあるトラブルまでまとめます。
新規インストール手順は扱いません。

構築自体は関連記事「UbuntuにNextCloudをインストールしてクラウドストレージ構築」を参照してください。

ポイント

公式が明記しているのは「メジャーバージョンを飛ばせない」「ダウングレードは非サポート」です。
権限やPHP拡張の直し方は、公式の確認項目と一般的なLinux運用知識を分けて書きます。

前提環境とこの記事の範囲

想定環境は次のとおりです。

OS: Ubuntu（LTS想定）
Webサーバー: Apache 2.4
PHP: PHP-FPM（実行ユーザーは www-data）
導入方式: 公式アーカイブ（zip / tar.bz2）ベース
インストール先の例: /var/www/nextcloud

Snap・Docker・AIO・パッケージ版は、配布元の更新手順を優先してください。
アーカイブ導入向けの全体像は公式の「How to upgrade」にあります。

Nextcloudのシステム要件を先に確認する

アップデート前に、移行先バージョンのSystem requirementsを確認します。
要件はリリースごとに変わるため、古い記事の数値をそのまま使わないでください。
執筆時点の stable ドキュメント（Nextcloud 35 系）では、おおよそ次の方向性です。

項目	公式ドキュメント上の目安
OS	64bit。Ubuntu 26.04 LTS（推奨）/ 24.04 LTS など
Webサーバー	Apache 2.4（mod_php または php-fpm）/ nginx＋php-fpm
PHP	8.3 / 8.4 / 8.5（推奨）
DB	MariaDB / PostgreSQL 推奨。SQLite は検証・極小用途向け
メモリ	プロセスあたり最低128MB、推奨512MB。Built-in Updater 利用時は最低256MB

本番ではユーザー数・アプリ数・同時接続で必要メモリが大きく変わります。
DBは InnoDB、READ COMMITTED、BINLOG_FORMAT=ROW など、MySQL/MariaDB向けの条件も公式に記載されています。

PHPバージョンとNextcloudの互換性

PHP要件はNextcloudのメジャーごとに変わります。
たとえば Nextcloud 35 では PHP 8.2 サポートが外れ、最低が 8.3 です（公式の Upgrade to Nextcloud 35）。
必要なPHP拡張はPreparing PHPを参照してください。
必須例として curl、DOM、GD、mbstring、xml、zip、zlib、posix などがあります。
CLI Updater（updater.phar）には phar も必要です。

# 現在のPHPバージョン
php -v

# 拡張の有無確認（例: curl）
php -m | grep -i curl

# Ubuntuで不足拡張を入れる例（PHPバージョンは環境に合わせて変更）
sudo apt update
sudo apt install php8.3-curl php8.3-gd php8.3-mbstring php8.3-xml php8.3-zip php8.3-mysql php8.3-intl php8.3-bcmath

# Apache + PHP-FPM なら両方再読込
sudo systemctl reload php8.3-fpm
sudo systemctl reload apache2

CLIの php と PHP-FPM で読み込む拡張が違うことがあります。
Web側だけ失敗する場合は、FPM用のモジュールも確認してください（一般的なLinux運用の注意点です）。
メジャー更新の前後では、Critical changesと各バージョンの Release Notes（例: Upgrade to Nextcloud 35、Changelog）を必ず読んでください。

アップデート前のバックアップと確認事項

Built-in Updaterは、コードの一部バックアップは作ってもDBとdataディレクトリはバックアップしません（公式の警告）。
更新前に自分でバックアップしてください。
公式のBackupでは、次を保持対象としています。

config フォルダ
カスタムアプリフォルダ（使っている場合）
data フォルダ
テーマフォルダ
データベース

cd /var/www/nextcloud

# メンテナンスモードON（バックアップ前）
sudo -E -u www-data php occ maintenance:mode --on

# ディレクトリ退避例（公式のrsync例に近い形）
sudo rsync -Aavx /var/www/nextcloud/ /var/backups/nextcloud-dirbkp_$(date +%Y%m%d)/

# MariaDB例（接続情報は環境に合わせて変更）
sudo mariadb-dump --single-transaction -u nextcloud -p nextcloud \
  > /var/backups/nextcloud-sqlbkp_$(date +%Y%m%d).bak

あわせて次を確認します。

移行先のシステム要件・PHP・DBを満たしているか
現在メジャーの最新ポイントリリースへ先に上げられるか
サードパーティアプリを一時無効化できるか（公式推奨）
ディスク空き容量（Updaterのダウンロード・展開分）
Critical Changes / Release Notes を読んだか

# 状態確認
sudo -E -u www-data php occ status

# サードパーティアプリを無効化する例（アプリIDは環境で異なる）
sudo -E -u www-data php occ app:list
sudo -E -u www-data php occ app:disable some_third_party_app

メジャーバージョンを飛ばせない／ダウングレードは非サポート

公式のアップグレード方針は次のとおりです。

You cannot skip major releases. … Downgrading is not supported and risks corrupting your data!
引用：How to upgrade – Nextcloud Administration Manual

手順の要点は次です。

次のメジャーへ行く前に、現在メジャーの最新ポイントリリースへ上げる
その後、次のメジャーの最新ポイントリリースへ上げる
例: 18.0.5 → 18.0.11 → 19.0.5 → 20.0.2
27→28は可、27→29は不可（手動アップグレードの公式警告）

メジャー更新後はバックグラウンド移行が残ることがあります。
連続して次のメジャーへ進む前に、cron.php を数回実行して移行を進めてください（公式手順）。

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

ダウングレードしたい場合も、公式は「古い版へ戻す」ではなく、新規インストール＋バックアップ復元を求めています。
問題が起きたら、先にフォーラムやサポートで復旧手段を確認してください。

メンテナンスモードの使い方

maintenance:mode はログイン中セッションをロックし、新規ログインも止めます。
アップデートや切り分けで使います。
Built-in Updaterはコード差し替え前に自動でONにします。

cd /var/www/nextcloud

# ON
sudo -E -u www-data php occ maintenance:mode --on

# OFF
sudo -E -u www-data php occ maintenance:mode --off

config/config.php の "maintenance" => true でも切り替えできます。
作業後は必ず false に戻してください。

Built-in Updater（Web版／CLI版）

アーカイブ導入では、多くの場合 Built-in Updater が最短です。
Updaterがやるのはコード差し替えまでです。
DB・アプリの移行は、その後の occ upgrade（またはWebのアップグレード画面）で行います。

CLI版Updater（推奨しやすい）

Webのタイムアウトを避けたい自前サーバーでは、CLI版が扱いやすいです。

cd /var/www/nextcloud

# 対話実行
sudo -E -u www-data php updater/updater.phar

# 非対話（利用可能な更新を入れ、occ upgradeまで進める）
sudo -E -u www-data php updater/updater.phar --no-interaction

失敗したステップで止まった場合は、原因を直して同じコマンドを再実行します。
公式どおり、成功済みステップはやり直さず、失敗ステップから再開します。
ログは data 配下の updater.log です。

Web版Updater

管理画面の Overview（Version）から「Open updater」で開始します。
途中でブラウザを閉じても、実行中ステップは進むことがあります。
次のステップへ進むには、Updater画面を再度開いて続きから実行します。
最後に「Keep maintenance mode active?」と聞かれたら、CLIで occ upgrade する場合はONのままにします。

手動アップデートの手順

Web Updaterが不安定で、CLI Updaterも使えない環境向けがUpgrade manuallyです。
流れの要約は次です。

バックアップ取得、サードパーティアプリ無効化
Changelogから対象版アーカイブを、インストール外の空ディレクトリへ取得
展開する
Webサーバー停止、必要なら cron を一時コメントアウト
現行ディレクトリを nextcloud-old などにリネーム
新しい nextcloud を元の場所へ配置
config/config.php をコピー。data が配下にあるなら data も移す
追加アプリ・テーマを必要に応じて引き継ぐ
所有者・権限を整え、Webサーバー再起動
occ upgrade を実行

# 作業例（パス・バージョンは環境に合わせて変更）
cd /tmp
wget https://download.nextcloud.com/server/releases/nextcloud-XX.Y.Z.tar.bz2
tar -xjf nextcloud-XX.Y.Z.tar.bz2

sudo systemctl stop apache2
# PHP-FPMも止めたい場合
sudo systemctl stop php8.3-fpm

sudo mv /var/www/nextcloud /var/www/nextcloud-old
sudo mv /tmp/nextcloud /var/www/nextcloud

sudo cp /var/www/nextcloud-old/config/config.php /var/www/nextcloud/config/config.php

# data が nextcloud 配下にある場合のみ
sudo mv /var/www/nextcloud-old/data /var/www/nextcloud/data

# 所有者・権限（公式例）
sudo chown -R www-data:www-data /var/www/nextcloud
sudo find /var/www/nextcloud/ -type d -exec chmod 750 {} \;
sudo find /var/www/nextcloud/ -type f -exec chmod 640 {} \;

sudo systemctl start php8.3-fpm
sudo systemctl start apache2

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

注意

rm -rf で現行ディレクトリを消す運用は危険です。
公式手順は「リネームして退避」が基本です。
削除する場合でも、config と data を残したこと、バックアップが取れたことを確認してからにしてください。

occ upgrade の使い方

occ upgrade は、新しいコードを置いたあとでDBスキーマとアプリを更新するコマンドです。
必ず Nextcloud インストールディレクトリ内で、HTTPユーザー（Ubuntuでは www-data）として実行します。

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

UpdaterのCLIで「occ upgrade を実行しますか？」に No と答えても、後から同じコマンドを実行すれば続行できます。
更新後に管理画面のセットアップチェックで指摘される場合は、公式が推奨する追加コマンドも実行します。

sudo -E -u www-data php occ db:add-missing-columns
sudo -E -u www-data php occ db:add-missing-indices
sudo -E -u www-data php occ db:add-missing-primary-keys

成功後はメンテナンスモードをOFFにし、無効化したアプリを必要なものだけ再有効化します。

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

アップデート失敗時の復旧とトラブルシューティング

ここからは、公式が示す確認項目と、自前サーバーでよく見るLinux側の直し方を分けます。

まず見る場所（公式）

datadirectory/updater.log（Built-in Updaterの詳細ログ）
Nextcloud本体ログ（通常は data 配下の nextcloud.log）
Webタイムアウトが疑わしいなら Web Updater をやめ、CLIへ切り替える

Webアップグレードで固まった場合、公式はいったんメンテナンスをOFFにしてからCLIで再実行する例を示しています。

cd /var/www/nextcloud
sudo -E -u www-data php occ maintenance:mode --off
sudo -E -u www-data php occ upgrade

# うまくいかない場合
sudo -E -u www-data php occ maintenance:repair

権限・所有者の不整合

公式Updaterは「書き込み可能なファイルがあるか」を検査します。
失敗時は、ディレクトリ全体が www-data 所有か、Updater作業ディレクトリへ書けるかを確認します。

# 所有者確認
sudo ls -ld /var/www/nextcloud /var/www/nextcloud/config /var/www/nextcloud/data

# 直し方の例（手動アップグレード公式と同じ考え方）
sudo chown -R www-data:www-data /var/www/nextcloud
sudo find /var/www/nextcloud/ -type d -exec chmod 750 {} \;
sudo find /var/www/nextcloud/ -type f -exec chmod 640 {} \;

rootで occ やUpdaterを動かすと、以後の書き込み権限が壊れやすいです。
常に sudo -E -u www-data を使ってください（一般的な運用ルール）。

PHP拡張不足（curl など）

公式の必須モジュールが欠けていると、Updaterや occ が途中で止まります。

php -m | grep -iE 'curl|gd|mbstring|xml|zip|pdo_mysql|intl|phar'
sudo apt install php8.3-curl php8.3-xml php8.3-mbstring php8.3-zip php8.3-gd php8.3-mysql
sudo systemctl reload php8.3-fpm
sudo systemctl reload apache2

Updaterの途中停止

公式どおり、失敗原因を直してから同じUpdaterを再実行します。
バックアップステップが重い場合、CLIでは --no-backup でコードバックアップを省略できます。
ただし data/DB のバックアップ代替にはなりません。

sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar --no-backup

余計なファイル／ディレクトリ

公式Updaterは「想定外のファイルがないか」を検査します。
インストール直下に作業用zip、バックアップコピー、古いテーマ残骸などがあると止まりやすいです。
不要物を消す前に、名前を変えて退避するのが安全です。

# 確認例
sudo ls -la /var/www/nextcloud

# 危険な削除の例（実行前に中身を必ず確認）
# sudo rm -rf /var/www/nextcloud/some-unexpected-dir
#
# 注意: パスを誤ると config / data を消します。
# 迷ったら rm せず mv で /var/backups へ退避してください。

version.php 欠落・不完全な差し替え

version.php は現行バージョン判定に使われます。
手動差し替えの途中で欠けたり、Updaterが中断してエントリポイントだけ残ったりすると、バージョン不一致で occ upgrade が失敗します。

# 存在確認
sudo -u www-data test -f /var/www/nextcloud/version.php && echo OK || echo MISSING
sudo -u www-data head -n 20 /var/www/nextcloud/version.php

# 状態確認
cd /var/www/nextcloud
sudo -E -u www-data php occ status

欠落時は、同じバージョンの公式アーカイブから不足ファイルを戻すか、退避した nextcloud-old／バックアップから復旧してやり直します。
不完全な状態でメジャーを飛ばして上書きしないでください。

どうしても戻せないとき

公式方針では、ダウングレードではなくバックアップからの復元が正攻法です。
ディレクトリ退避とDBダンプがあるなら、サービスを止めてから両方を戻し、メンテナンスをOFFにして状態を確認します。
復元手順の詳細は公式の Restoring backup を参照してください。

まとめ

Nextcloud アップデートは、「移行先要件の確認 → バックアップ → 1メジャーずつ更新 → occ upgrade → 失敗時はログと権限・PHP拡張から切り分け」の順が安定します。
Built-in Updaterは便利ですが DB/data は守ってくれないため、更新前バックアップは省略しないでください。
メジャー飛ばしとダウングレードは公式非サポートです。
困ったときは公式のアップグレード文書と Critical Changes を先に確認し、それでも解けないときだけフォーラムへログ付きで相談するのが近道です。

Original:https://minory.org/nextcloud-upgrade.html
Source:minory
Author:管理者