GROWI.cloud

GROWI.cloud ヘルプ

ヘルプ アップグレードの概要と最新バージョンへの移行

# アップグレードの概要と最新バージョンへの移行

現在ご利用中のバージョンから最新バージョン（v8.0.x）へアップグレードするために必要な作業を、このページにまとめています。

DANGER

Revision（ページの更新履歴）データの重大な不具合があるため、v6.1.0〜v7.0.15 にはアップグレードせず、必ず v7.4.0 以降へ直接アップグレードしてください。 詳細は開発 Wiki の v5.0.0〜v7.0.15 での Revision データマイグレーションバグ (opens new window) を参照してください。

# 目次

# このページの読み方

最新系列では機能・パフォーマンス・セキュリティの改善が継続的に行われ、サポート対象の実行環境も最新化されています。安全に使い続けるため、最新バージョンへのアップグレードを推奨します。

  • GROWI.cloud をご利用の場合は A、OSS 版をセルフホストしている場合は B へ進んでください。もう一方を読む必要はありません。
  • 現在ご利用中のバージョンに関わらず、中間バージョンを経由する必要はありません。最新バージョン（v8.0.x）へ直接アップグレードしてください。
  • A・B の各表では、現在ご利用中のバージョンの列を上から下まで確認し、○ が付いている行の対応を実施してください。
    • ○ は、その列のバージョンから最新バージョンへアップグレードするまでに対応が必要であることを示します。
    • [必須] は、○ が付いていれば無条件で対応が必要な項目です。[該当時] は、○ に加えて行に記載された条件へ当てはまる場合のみ対応します。
    • 具体的な手順は、表からリンクする「C. 手順詳細」にまとめています。

# A. GROWI.cloud をご利用中の場合

# A-1. 現在のバージョンを確認する

# A-2. GROWI.cloud でアップグレード前に実施すること

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[必須] WIP ページの導入・新規ページ作成導線の変更・全文検索の呼び出し方の変更を利用者へ周知 ○ ○ ○ ○ ○
[必須] v5 の仕様変更（子孫ページを含む移動・リネーム・削除、URL のパーマリンク化、UI 変更）を利用者へ周知 ○
[該当時] ファイル保存先に【Owned】AWS を指定している場合: IAM ポリシーに s3:AbortMultipartUpload を追加 ○ ○ ○ ○ ○ ○ ○ ○
[該当時] ファイル保存先に【Owned】AWS を指定している場合: バケットの ACL 無効化・パブリックアクセスブロックへの変更（環境変数 S3_OBJECT_ACL の変更をご希望の場合はお問い合わせください） ○ ○ ○ ○ ○ ○
[該当時] 同時多人数編集（HackMD）を有効にしている場合: ビルトインエディタの同時多人数編集へ移行し、エディタが変わることを利用者へ周知 ○ ○ ○ ○ ○
[該当時] 記法・HTML の仕様変更で既存ページの表示が変わり、本文の書き換えが必要になることを利用者へ周知 ○ ○ ○ ○ ○
[該当時] v3.3 系以前に構築した OSS 版から移行したページデータが残っている場合: 旧形式の添付ファイル URL を書き換え ○ ○ ○ ○
[該当時] カスタム HTML Header 利用時: カスタム Noscript やカスタムスクリプトへ移行 ○ ○
[該当時] Twitter OAuth 2 認証利用時: 別の認証方式へ移行 ○ ○

表に記載のない事項でご不明な点があれば、GROWI.cloud サービスデスク (opens new window) までご連絡ください。

# A-3. GROWI.cloud での GROWI 最新バージョンへのアップグレード

アップグレード前の対応をすべて済ませたうえで、GROWI のバージョンをアップグレードします。アップグレード手順は GROWI.cloud ヘルプページ - バージョン (opens new window) をご覧ください。

  • 手順の概要: アプリ詳細画面で「バージョン」項目の［編集］を押し、対象バージョンを選んで［更新する］を押します。表示される確認画面で内容を確認し「確認しました」にチェックのうえ［変更する］を押すとアップグレードが始まります。アップグレード時にアプリが再起動するため、利用者の少ない時間帯を選んでください。
  • 自動バージョンアップを利用している場合は、自動で最新版へアップグレードされます。特定バージョンで固定している場合は、手動でアップグレードしてください。
  • 〜v4.x をご利用の場合、自動バージョンアップではアップグレードされません。アプリ詳細画面から手動でアップグレードしてください。

DANGER

Revision（ページの更新履歴）データの重大な不具合があるため、v6.1.0〜v7.0.15 にはアップグレードせず、必ず v7.4.0 以降へ直接アップグレードしてください。 詳細は開発 Wiki の v5.0.0〜v7.0.15 での Revision データマイグレーションバグ (opens new window) を参照してください。

# A-4. GROWI.cloud でアップグレード後に実施すること

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[必須] 全文検索インデックスの再構築 ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] 旧 AI 連携機能を利用していた場合: GROWI AI Agent の設定方法で再設定 ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] LOCAL_STRATEGY_ENABLED / SAML_ENABLED 設定時: /login で認証方式の有効・無効状態が期待どおりか再確認 ○ ○ ○ ○ ○ ○ ○
[該当時] 記法・HTML の仕様変更に該当する既存ページの本文を書き換え（GROWI.cloud ではお問い合わせが必要） ○ ○ ○ ○ ○
[該当時] XSS 対策設定を独自にカスタマイズしていた場合: 起動時に既定へリセットされるため再設定 ○ ○
[該当時] v4.5 以前に作成され未変換のページが残っている場合: v5 互換形式へ変換 ○ ○

# B. GROWI OSS 版 をご利用中の場合

# B-1. 現在のバージョンを確認し、バックアップを取得する

現在起動中の GROWI のバージョンは、管理画面のトップページまたはページのフッターで確認できます。

アップグレード前には、必ず MongoDB のバックアップを取得してください。手順は MongoDB のバックアップ/リストア (opens new window) を参照してください（この手順は保存先に AWS S3 を利用します。S3 を利用しない環境では、mongodump で取得したアーカイブを任意の場所へ保存してください）。

# B-2. アップグレード前に実施すること

WARNING

「ミドルウェア」の項目は、GROWI 本体を停止したうえで、本体のアップグレードと同じ作業の中で連続して実施してください。GROWI はバージョンごとに対応するミドルウェアが決まっており、現在ご利用中の GROWI を動かしたまま先にミドルウェアだけをアップグレードすると、非対応の組み合わせで運用することになります。それ以外の分類は事前に実施して構いません。

# ミドルウェア

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[必須] MongoDB を v6.0 以上へアップグレード（メジャーバージョンを飛ばさず段階的に） ○ ○ ○ ○ ○ ○
[該当時] Elasticsearch v7 系以前を利用している場合: v8 系または v9 系へ移行（インデックスは再生成を推奨） ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] MongoDB を standalone 構成で運用している場合: レプリカセット構成へ移行（単一ノードのレプリカセットでも可） ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] ソースからビルド・実行している場合: Node.js を v24 へアップグレード（公式 Docker イメージ利用時は対応不要） ○ ○ ○ ○ ○ ○ ○ ○

# インフラ・ストレージ

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[該当時] S3 互換オブジェクトストレージ利用時: IAM ポリシーに s3:AbortMultipartUpload を追加 ○ ○ ○ ○ ○ ○ ○ ○
[該当時] 公式 Docker イメージ利用時: Docker Hardened Images 化（シェル・パッケージマネージャーを含まない）による運用への影響を確認 ○ ○ ○ ○ ○ ○ ○ ○
[該当時] AWS S3 利用時: バケットの ACL 無効化・パブリックアクセスブロックへの変更と、環境変数 S3_OBJECT_ACL の見直し ○ ○ ○ ○ ○ ○
[該当時] v3.3 系以前に構築し MongoDB GridFS を利用している場合: 旧形式の添付ファイル URL を /attachment/{attachmentId} 形式へ書き換え ○ ○ ○ ○

# 環境変数・設定

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[該当時] アクティブユーザーの多い（おおむね 500 人を超える）大規模環境: MongoDB コネクションプール上限の引き上げを検討 ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] LOCAL_STRATEGY_ENABLED / SAML_ENABLED 設定時: /login で認証方式の実際の有効・無効状態を確認 ○ ○ ○ ○ ○ ○ ○
[該当時] 環境変数 FILE_UPLOAD_DISABLED / DISABLE_LINK_SHARING 設定時: 廃止されたため代替の設定に置き換え ○ ○ ○ ○ ○ ○ ○
[該当時] カスタム HTML Header 利用時: カスタム Noscript やカスタムスクリプトへ移行 ○ ○
[該当時] Twitter OAuth 2 認証利用時: 別の認証方式へ移行 ○ ○
[該当時] nocdn 版イメージ利用時: 統合された公式イメージへ移行 ○ ○

# 自前ビルド運用

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[該当時] ソースから自前でビルドしている場合: ビルドツールの変更（Lerna → Turborepo、yarn v1 → pnpm）に対応 ○ ○ ○ ○ ○ ○

# 廃止機能への対応

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[該当時] HackMD 連携利用時: ビルトインエディタの同時多人数編集へ移行し、HackMD サーバーの縮退を検討 ○ ○ ○ ○ ○
[該当時] Promster 連携で監視している場合: 監視構成を見直し ○ ○ ○ ○ ○

# 利用者への周知

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[必須] WIP ページの導入・新規ページ作成導線の変更・全文検索の呼び出し方の変更を利用者へ周知 ○ ○ ○ ○ ○
[必須] v5 の仕様変更（子孫ページを含む移動・リネーム・削除、URL のパーマリンク化、UI 変更）を利用者へ周知 ○
[該当時] 記法・HTML の仕様変更で既存ページの表示が変わり、本文の書き換えが必要になることを利用者へ周知 ○ ○ ○ ○ ○

# B-3. GROWI 最新バージョンへのアップグレード

アップグレード前の対応をすべて済ませたうえで、GROWI 本体をアップグレードします。あわせて、アップグレード前に MongoDB のバックアップを取得してください（MongoDB のバックアップ/リストア (opens new window)）。

DANGER

Revision（ページの更新履歴）データの重大な不具合があるため、v6.1.0〜v7.0.15 にはアップグレードせず、必ず v7.4.0 以降へ直接アップグレードしてください。 詳細は開発 Wiki の v5.0.0〜v7.0.15 での Revision データマイグレーションバグ (opens new window) を参照してください。

# docker-compose 運用でのアップグレード

growi-docker-compose (opens new window) で運用している場合は、次の手順で進めます。

growi-docker-compose をダウンロードしたフォルダで、コンテナを停止します。

cd growi
docker-compose stop

既存の Docker コンテナと Docker イメージを削除します。イメージのタグ（下記例の growilabs/growi:7）は利用中のバージョンに合わせて読み替えてください。Elasticsearch を移行する場合は、コンテナだけでなく Elasticsearch が使用していた docker volume も削除してください。残っていると、旧バージョンのインデックスデータが原因で起動に失敗します。ボリューム名は docker volume ls で確認でき、既定の compose 構成では <フォルダ名>_es_data になります。

docker-compose rm app mongo elasticsearch
docker rmi growilabs/growi:7
docker volume rm growi_es_data  # Elasticsearch を移行する場合のみ。フォルダ名が growi 以外なら読み替える

最新版を pull し、Docker イメージを作成した後、コンテナを起動します。B-2 で docker-compose.yml を編集している場合、git pull がその変更点と衝突することがあります。その場合は git stash に変更を退避してから git pull を実行し、git stash pop を実行して戻したあと、MongoDB・Elasticsearch のバージョン指定が意図したとおりに残っているか確認してください。あわせて、MongoDB がレプリカセット構成（--replSet と MONGO_URI の ?replicaSet=）で起動する設定になっているかも確認してください。

git pull
docker-compose build
docker-compose up -d

# ソースからのビルド運用でのアップグレード

ソースを自前で取得しビルドして運用している場合は、次の流れで進めます。手順の具体例は Ubuntu Server の GROWI 節 (opens new window) を参照してください（AlmaLinux OS・CentOS でも流れは同様です）。

GROWI サーバーのプロセスを停止した後、リポジトリで最新の安定版タグを確認し、そのタグへ切り替えます。

$ git tag --sort=-version:refname | head -10
# RC がついていない最新の安定版タグを選ぶ（例: v8.0.0）
$ git checkout -b v8.0.0 refs/tags/v8.0.0

依存関係を更新し、ビルドし直します。

$ pnpm install
$ pnpm run app:build

MONGO_URI と ELASTICSEARCH_URI を環境に合わせて指定し、起動を確認します。

$ sudo \
MONGO_URI=mongodb://localhost:27017/growi?replicaSet=rs0 \
ELASTICSEARCH_URI=http://localhost:9200/growi \
npm run app:server

systemd による自動起動の設定は systemd による自動起動 (opens new window) を参照してください。

# B-4. アップグレード後に実施すること

# 設定の再設定

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[必須] 全文検索インデックスの再構築 ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] AI 連携機能を利用していた場合: 旧 AI 連携設定が廃止されたため、GROWI AI Agent の設定方法で再設定 ○ ○ ○ ○ ○ ○ ○ ○ ○
[該当時] LOCAL_STRATEGY_ENABLED / SAML_ENABLED 設定時: /login で認証方式の有効・無効状態が期待どおりか再確認 ○ ○ ○ ○ ○ ○ ○
[該当時] XSS 対策設定を独自にカスタマイズしていた場合: 起動時に既定へリセットされるため再設定（許可属性の記述形式が JSON に変更） ○ ○

# データ・ファイルの移行

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[該当時] FILE_UPLOAD=local 利用時: 添付ファイルを新しい保存先ディレクトリへ移動 ○ ○ ○
[該当時] v4.5 以前に作成され未変換のページが残っている場合: v5 互換形式へ変換（管理ページから公開ページを一括変換、旧形式のプライベートページは各ユーザーが変換） ○ ○

# ページ内容の書き換え

対応内容
現在のバージョン →		 v7.5.x v7.2.x〜v7.4.x v7.1.x v7.0.x v6.3.x v6.1.x〜v6.2.x v6.0.x v5.x 〜v4.x
[該当時] 記法・HTML の仕様変更に該当する既存ページの本文を data-migrations スクリプトで一括書き換え ○ ○ ○ ○ ○

# C. 手順詳細

A・B の表からリンクする、対応ごとの詳細手順です。

# アップグレード前に実施する手順

# Node.js を v24 へアップグレードする

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v7.5（サポート対象の Node.js が v24 系のみに変更）
  • 対応が必要な条件: ソースコードから GROWI をビルド・実行している場合（公式 Docker イメージ利用時は対応不要）
  • 参考: v7.5.x

  1. GROWI v7.5.0 以降がサポートする Node.js は v24 系のみです。v18 系・v20 系のサポートは終了しています。

  2. 現在の Node.js のバージョンを確認します。

    $ node -v

  3. v24 系でない場合は、Node.js を v24 系へアップグレードします。NodeSource のリポジトリを利用する場合の手順は次のとおりです。

    $ cd ~
$ curl -sL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
$ sudo bash nodesource_setup.sh
$ sudo apt -y install nodejs

  4. v7.5.0 では、Node.js v24 で追加された組み込み関数 RegExp.escape() をページパスの処理で利用しています。v18 系・v20 系のままアップグレードすると、この関数が存在しないため、ページの移動・複製などの操作が実行時エラーとなります。GROWI 本体のアップグレード前に必ず対応してください。

  5. 公式 Docker イメージを利用している場合、この対応は不要です。

# 自前ビルドのビルドツールの変更に対応する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v6.1（Lerna → Turborepo）、v7.1（yarn → pnpm）
  • 対応が必要な条件: ソースから自前でビルドしている場合（公式 Docker イメージ利用時は対応不要）
  • 参考: v6.1.x、v7.1.x

  1. v7.1 以降、パッケージマネージャー・タスクランナーが yarn (v1) から pnpm に変わります。v8.0.0 は packageManager: pnpm@11.1.1 を宣言しているため、pnpm 公式サイト (opens new window) を参考に最新版をインストールしてください。

    $ curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=<version> sudo sh -
$ sudo pnpm setup

  2. v6.1 以降、ビルドツールが Lerna から Turborepo (opens new window) に変わります。v8.0.0 は turbo を devDependencies に含むため、pnpm install を実行すれば導入され、グローバルインストールは不要です。

  3. インストールしたバージョンを確認します。

    $ node -v
$ pnpm -v

  4. yarn コマンドで npm script を実行していた箇所は、pnpm run または npm run に書き換えてください。

# MongoDB を v6.0 以上へアップグレードする

  1. 現在の MongoDB のバージョンを確認します。
  2. v6.0 未満の場合は、メジャーバージョンを 1 つずつ順にアップグレードします（例: v4.4 から v6.0 へアップグレードする場合は、先に v5.0 を経由します）。手順は MongoDB のアップグレード (opens new window) を参照してください。
  3. MongoDB v4.4 および v5.0 のサポートは終了しているため、最終的に v6.0 以上にしてください。

# MongoDB をレプリカセット構成へ移行する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v8.0
  • 対応が必要な条件: MongoDB を standalone 構成で運用している場合（GROWI v8.0 以降で必須）
  • 参考: v8.0.x
  1. 現在の MongoDB の構成が standalone か、レプリカセットかを確認します。
  2. GROWI v8.0 以降は MongoDB の change stream を利用するため、レプリカセット構成が必須です。change stream はレプリカセット構成でのみ利用できます。
  3. standalone 構成の場合は、レプリカセット構成へ移行します。単一ノードのレプリカセットでも構いません。
  4. 移行後は、環境変数 MONGO_URI も接続先のレプリカセットを明示する形へ書き換えます。レプリカセット名が rs0 の場合は mongodb://localhost:27017/growi?replicaSet=rs0 のように、クエリパラメータ replicaSet にレプリカセット名を指定します。
  5. growi-docker-compose (opens new window) を利用している場合は、同リポジトリの最新の docker-compose.yml が MongoDB をレプリカセット（rs0）構成で起動し、MONGO_URI にも ?replicaSet=rs0 を設定するようになっています。最新版を取得してください。

# MongoDB コネクションプールの上限を引き上げる

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v8.0
  • 対応が必要な条件: アクティブユーザーの多い（おおむね 500 人を超える）大規模環境
  • 参考: v8.0.x、環境変数 (opens new window)

  1. GROWI v8.0 以降、MongoDB コネクションプールの既定の上限値が、従来より小さい値に変更されます。

  2. アクティブユーザー数や総ページ数、アクセス頻度が高い大規模環境では、既定値のままだと不足する場合があります。

  3. 該当する場合は、次の環境変数で上限・下限を引き上げます。

    環境変数名 説明 既定値
    MONGO_MAX_POOL_SIZE MongoDB コネクションプールの最大接続数 15
    MONGO_MIN_POOL_SIZE MongoDB コネクションプールの最小接続数 2

# Elasticsearch を v8 系または v9 系へ移行する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v8.0（Elasticsearch v7 系のサポート終了）
  • 対応が必要な条件: Elasticsearch v7 系以前を利用している場合
  • 参考: v8.0.x

  1. 利用している Elasticsearch のメジャーバージョンを確認します。GROWI v8.0.x が対応するのは v8 系・v9 系のみです（既定の利用バージョンは v9 系）。

  2. v7 系以前の場合は、v8 系または v9 系の Elasticsearch を新たに用意します。既存のインデックスは引き継がず、新しいインデックスを作成することを推奨します。手順は次のとおりです（docker を利用している場合）。

    1. 利用していた Elasticsearch のコンテナを削除する
    2. Elasticsearch コンテナが使っていた docker volume を削除する
    3. 新バージョンの Elasticsearch コンテナを起動する（GROWI 用のインデックスデータが存在しないことを確認）
    4. GROWI を起動する（起動後、Elasticsearch 管理ページでインデックスを再構築できます）

    オンプレミスの場合は、旧バージョンをアンインストールしたうえで新バージョンを新規インストールし、同様に GROWI 用のインデックスが存在しないことを確認してから GROWI を起動してください。

  3. 環境変数 ELASTICSEARCH_VERSION に、接続先のメジャーバージョン（8 または 9。既定値は 9）を設定します。

  4. Elasticsearch v7 系のまま GROWI v8.0 以降を起動すると、全文検索の初期化に失敗し検索が利用できなくなります（サーバープロセス自体は起動しますが、ログにエラーが出力されます）。必ずアップグレード前に移行してください。

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v7.2
  • 対応が必要な条件: 環境変数 FILE_UPLOAD_DISABLED または DISABLE_LINK_SHARING を設定している場合
  • 参考: v7.2.x
  1. 環境変数 FILE_UPLOAD_DISABLED（ファイルアップロード機能の無効化）は廃止されました。代わりに、環境変数 FILE_UPLOAD に none を設定してください。
  2. 環境変数 DISABLE_LINK_SHARING（シェアリンク機能の無効化）は廃止されました。代わりに、管理画面の「セキュリティ設定」からシェアリンク機能を無効化してください。

# LOCAL_STRATEGY_ENABLED と SAML_ENABLED の実際の状態を確認する

  • 対応タイミング: アップグレード前（設定確認）とアップグレード後（再確認）
  • 変更が入ったバージョン: v7.2
  • 対応が必要な条件: 環境変数 LOCAL_STRATEGY_ENABLED または SAML_ENABLED を設定している場合
  • 参考: v7.2.x

アップグレード前:

  1. 環境変数 LOCAL_STRATEGY_ENABLED と SAML_ENABLED を設定しているかを確認します。どちらも設定していない場合、この対応は不要です。
  2. 設定している場合は、プライベートブラウザ等で /login にアクセスし、ID/Pass 認証・SAML 認証の有効・無効状態が期待どおりかを確認します。
  3. 一致していない場合は、以下のいずれかの措置を執ります。
    1. DB の値を優先させる（推奨）: 管理画面の「セキュリティ設定」ページで ON/OFF を切り替えて DB に正しい状態を保存し、環境変数 LOCAL_STRATEGY_ENABLED および SAML_ENABLED を削除してサーバーを再起動します。
    2. 環境変数の値を優先させる: データベースの configs collection から key: 'security:passport-local:isEnabled' のドキュメントを削除します。key: 'security:passport-saml:isEnabled' のドキュメントも同様に削除します。その後サーバーを再起動します。

GROWI.cloud をご利用の場合、環境変数の削除やデータベースの直接操作はお客様側で実施できません。/login の表示が期待と異なる場合は、GROWI.cloud サービスデスク (opens new window) までご連絡ください。

アップグレード後:

  1. 再度 /login にアクセスし、ID/Pass 認証・SAML 認証の有効・無効状態が期待どおりかを確認します。

# AWS S3 バケットの ACL 設定と S3_OBJECT_ACL を見直す

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v7.1
  • 対応が必要な条件: AWS S3 を添付ファイルの保存先に利用している場合
  • 参考: v7.1.x

  1. v7.1.x 以降、ファイルアップロード時のオブジェクト ACL 設定が次のように変わります。

    バージョン ファイルアップロード時の挙動
    v7.0.x 以前 オブジェクト ACL 設定 ACL: 'public-read' を付加するリクエスト
    v7.1.x 以降 オブジェクト ACL を設定しないリクエスト

  2. AWS 公式の S3 のベストプラクティス (opens new window) に沿って、S3 バケットの ACL を無効化し、パブリックアクセスをブロックする設定に変更します。

  3. 環境変数 S3_OBJECT_ACL（既定値 public-read）に public-read を設定している場合は、private に変更するか設定を削除します。

  4. v3.3.0 以前にアップロードされ、次のようにバケット URL を直接参照する形式の添付ファイルは、この変更後にアクセスできなくなる可能性があるため、事前に影響を確認してください。

    https://${AWS bucket name}.s3.amazonaws.com/attachment/5d091f611fe336003eec5bfd/foobar.jpg

  5. S3 バケットの設定を変えずこれまで通りの運用を続けたい場合（非推奨）は、環境変数 S3_OBJECT_ACL=public-read を明示的に設定してください。

# IAM ポリシーに s3:AbortMultipartUpload を追加する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v7.5
  • 対応が必要な条件: S3 互換オブジェクトストレージを利用している場合（GROWI.cloud では、ファイル保存先に【Owned】AWS を指定している場合）
  • 参考: v7.5.x
  1. v7.5.x 以降、S3 へのアップロード方式が単一の PutObject からマルチパートアップロードに変わります（5MB 以下のファイルは PutObject にフォールバックします）。
  2. IAM ポリシーに s3:AbortMultipartUpload 権限を追加します。
  3. CreateMultipartUpload・CompleteMultipartUpload・UploadPart は IAM 上 s3:PutObject に含まれるため、追加が必要なのは s3:AbortMultipartUpload のみです。

# Docker Hardened Images 化による運用への影響を確認する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v7.5
  • 対応が必要な条件: 公式 Docker イメージを利用している場合
  • 参考: v7.5.x
  1. v7.5.x 以降、公式 Docker イメージのベースイメージが Docker Hardened Images (DHI) (opens new window) に変わります。DHI はシェル（sh、bash）やパッケージマネージャーを含みません。
  2. docker exec でコンテナ内部に入って対話的に操作する運用をしていないかを確認します。
  3. 公式イメージをベースに独自のカスタマイズ（追加パッケージのインストール、独自のエントリポイントなど）をしている場合は、アップグレード前に DHI 上で動作するかを確認します。

# 旧形式の添付ファイル URL を書き換える

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v6.3
  • 対応が必要な条件: v3.3 系以前に構築し、MongoDB GridFS で添付ファイルを管理している場合
  • 参考: v6.3.x
  1. v6.3.x で、MongoDB GridFS 用の旧エンドポイント（/attachment/{pageID}/{fileName}）が廃止されます。
  2. Markdown 中にこの形式の URL を含むページがないかを確認します。
  3. 該当する URL を /attachment/{attachmentId} 形式へ書き換えるか、ファイルをアップロードし直します。

# カスタム HTML Header の代替手段に切り替える

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v6.0
  • 対応が必要な条件: カスタム HTML Header を利用している場合
  • 参考: v6.0.x

  1. v6.0 以降、head タグに自由に文字列・タグを挿入できる「カスタム HTML Header」は廃止されます。

  2. 代わりに追加された「カスタム Noscript」、またはカスタムスクリプトへ移行します。

  3. 例えば link タグを追加したい場合は、次のようなカスタムスクリプトで代替できます。

    var link = document.createElement('link');
link.id = 'mylink';
link.rel = 'stylesheet';
link.href = 'https://example.com/mystyles.css';
document.head.appendChild(link);

# Twitter OAuth 2 認証から別の認証方式へ移行する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v6.0
  • 対応が必要な条件: Twitter OAuth 2 認証を利用している場合
  • 参考: v6.0.x
  1. v6.0 以降、Twitter を使った認証機構は廃止されます。
  2. アップグレード前に、ID/Pass 認証や SAML 認証など、別の認証方式へ切り替えてください。

# nocdn 版イメージから公式イメージへ移行する

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v6.0
  • 対応が必要な条件: nocdn 版の Docker イメージを利用している場合
  • 参考: v6.0.x
  1. v6.0 以降、default 版と nocdn 版に分かれていた公式コンテナイメージが 1 本化されます。
  2. nocdn 版を利用している場合は、統合された公式イメージへ移行してください。

# HackMD 連携からビルトインエディタの同時多人数編集へ移行する

  1. v7.0 以降、HackMD と連携して同時多人数編集する機能は廃止されます。
  2. 代わりに、ビルトインエディタでの同時多人数編集の機能に移行します。利用者側の追加設定は不要です。
  3. 運用していた HackMD(CodiMD) サーバーは、縮退（停止・撤去）を検討してください。
  4. GROWI.cloud をご利用の場合、HackMD サーバーの縮退作業は不要です。ただしアップグレード後は HackMD を利用できなくなるため、HackMD 上にのみ存在する編集中の内容を GROWI のページへ保存するよう、事前に利用者へ周知してください（同時多人数編集（HackMD） (opens new window)）。

# Promster による監視構成を見直す

  • 対応タイミング: アップグレード前
  • 変更が入ったバージョン: v7.0
  • 対応が必要な条件: Promster 連携で監視している場合
  • 参考: v7.0.x
  1. v7.0 以降、Promster と連携する機能は廃止されます。
  2. Promster 経由で GROWI を監視している場合は、アップグレード前に監視構成を見直してください。

# 記法と HTML の仕様変更に伴うページ本文の書き換え

  • 対応タイミング: アップグレード前（利用者への周知）とアップグレード後（本文の一括書き換え）
  • 変更が入ったバージョン: v6.0（記法変更）、v6.1（mdcont- プレフィクスの廃止）、v7.0（Bootstrap v4 → v5）
  • 対応が必要な条件: v6.3.x 以前を利用している場合
  • 参考: v6.0.x、v6.1.x、v7.0.x

v6.0 から v7.0 にかけて、Markdown の記法とレンダリング結果が次のように変わりました。現在ご利用中のバージョンより後に入った変更が対象です。

変更が入ったバージョン 変更内容 詳細 MIGRATION_MODULE
v6.0 Draw.io、PlantUML、CSV・TSV によるテーブル描画、GROWI プラグイン記法（$lsx() など）の書式（インデント・前後の空行・引数の括弧）、数式（MathJax から KaTeX へ）、プレゼンテーションのページ区切り、脚注のインライン記法（廃止）、GROWI 独自のページリンク記法（廃止） v6.0.x へのアップグレード v60x
v6.1 アンカーリンクに自動付与されていた mdcont- プレフィクスの廃止 v6.1.x へのアップグレード v61x
v7.0 Bootstrap v4.6 から v5.3 への変更に伴う、Markdown 中の HTML タグの記法変更 v7.0.x へのアップグレード v70x

アップグレード前（利用者への周知）:

  1. 上の表の記法・HTML を使っているページは、アップグレード後にそのままでは意図した表示にならなくなることを利用者へ周知します。
  2. アップグレード後に管理者が一括書き換えを実施する場合は、既存ページの本文そのものが書き換わることも併せて周知してください。
  3. 各変更の具体的な内容は、上の表の「詳細」列のアップグレードガイドを参照してください。

アップグレード後（管理者による一括書き換え）:

  1. GROWI 本体をアップグレードしても、以前の記法で保存されたページの本文は自動では変更されません。
  2. GROWI リポジトリの bin/data-migrations (opens new window) に、ページ本文を一括で書き換えるスクリプトが用意されています。環境変数 MIGRATION_MODULE に上の表の値（v60x、v61x、v70x）を指定して実行します。実行手順は同ディレクトリの README を参照してください。参考ディスカッション: https://github.com/growilabs/growi/discussions/7180 (opens new window)
  3. 書き換えが適用されるのは各ページの最新リビジョンのみで、過去のリビジョンは書き換えられません。
  4. 数式（MathJax から KaTeX へ）、プレゼンテーションのページ区切り、脚注のインライン記法にはスクリプトが用意されていません。該当するページは手動で書き換えてください。

GROWI.cloud をご利用の場合

bin/data-migrations によるページ本文の一括書き換えは、GROWI.cloud の環境ではお客様が実行できません。実行をご希望の場合は GROWI.cloud サービスデスク (opens new window) までご連絡ください。数式・プレゼンテーションのページ区切り・脚注のインライン記法はスクリプトが用意されていないため、手動での書き換えが必要です。

# WIP ページと UI 変更を利用者へ周知する

  • 対応タイミング: アップグレード前（利用者への周知）
  • 変更が入ったバージョン: v7.0
  • 対応が必要な条件: v6.3.x 以前から最新バージョンへアップグレードする場合
  • 参考: v7.0.x
  1. v7.0 以降、編集画面を表示した時点で「無題のページ-1」のような WIP (Work In Progress) ページとして保存されるようになります（v6 までは保存操作をするまでページデータ自体が作成されませんでした）。
  2. 新規作成された WIP ページは、作成から一定期間（既定 48 時間。環境変数 WIP_PAGE_EXPIRATION_SECONDS で変更可能）が経過すると自動削除されます。ページツリーや新規ページ作成モーダルから作成したページも対象です。ただし、新規作成後に一度でもページを更新（WIP としての保存・通常の保存を問わず）した場合は自動削除の対象になりません。
  3. 新規ページ作成ボタンの位置が、画面上部のナビバーから左上のサイドバー内へ移ります。
  4. 全文検索機能を呼び出す場所・使い方が変わります。
  5. これらの変更を、アップグレード前に利用者へ周知してください。

# v5 の仕様変更を利用者へ周知する

  • 対応タイミング: アップグレード前（利用者への周知）
  • 変更が入ったバージョン: v5.0
  • 対応が必要な条件: 〜v4.x から最新バージョンへアップグレードする場合
  • 参考: v5.0.x
  1. v5.0 では、ページ閲覧・遷移時の URL がページパスからパーマリンクへ変わります。
  2. 親ページを移動・リネーム・削除すると、閲覧権限の有無に関わらず配下ページも影響を受けるよう変わります（「リンクを知っている人のみ」設定のページを除きます）。
  3. サイドバーにページツリーが追加されます。
  4. 目次上部にあった更新履歴・添付データ・共有リンク管理などのアイコンが、三点リーダードロップダウン内に移動します。
  5. 利用者向けの周知文の例（そのままコピーして使えます）は、v5.0.x へのアップグレード に掲載しています。

# アップグレード後に実施する手順

# 全文検索インデックスの再構築

  1. GROWI 本体のアップグレード後は、管理画面の Elasticsearch 管理ページ（/admin/search。サイドバーの表示名。以前は「全文検索管理」）でインデックスを再構築します。「ページデータ管理」セクションの［ページデータのインデックスのリビルド］ボタンで実行できます。
  2. インデックスが破損表示になっている場合は、正規化を行うことで、以前のリビルド結果のインデックスを使って検索機能を復旧できます（詳細は 全文検索のセットアップと監査ログのインデックス管理 の「ページデータのインデックスの正規化」を参照）。
  3. 監査ログ機能を有効にしている場合は、同じページの「監査ログのインデックス管理」セクションで監査ログ用インデックスも管理できます。

# GROWI AI Agent の設定をやり直す

  • 対応タイミング: アップグレード後
  • 変更が入ったバージョン: v8.0
  • 対応が必要な条件: 旧 AI 連携機能（ナレッジアシスタントの作成機能・エディターアシスタント）を利用していた場合
  • 参考: v8.0.x、GROWI AI Agent のセットアップと管理
  1. GROWI v8.0 で旧 AI 連携設定は廃止されました。旧設定は自動移行されないため、そのままではアップグレード後に動作しません。
  2. 管理画面の「AI 設定」（/admin/ai）で「AI 機能を有効にする」をオンにするだけでは動作しません。プロバイダの有効化・API キーの設定・モデル登録・デフォルトモデルの選択まで済ませて初めて動作します。
  3. 詳しい設定手順は GROWI AI Agent のセットアップと管理 を参照してください。

# FILE_UPLOAD=local の添付ファイルを新しい保存先へ移動する

  • 対応タイミング: アップグレード後
  • 変更が入ったバージョン: v6.1
  • 対応が必要な条件: 環境変数 FILE_UPLOAD=local（ローカルファイルシステムへの保存）を利用している場合
  • 参考: v6.1.x

  1. v6.1 で app パッケージの場所が変わったことにより、ファイルの保存先が次のように変わります。

    Before After
    /opt/growi/packages/app/public -> /opt/growi/apps/app/public

  2. アップグレード後、既存のファイルを新しい保存先へ移動してください。参考ディスカッション: https://github.com/growilabs/growi/discussions/6086 (opens new window)

# XSS 対策設定を再設定する

  • 対応タイミング: アップグレード後
  • 変更が入ったバージョン: v6.0
  • 対応が必要な条件: XSS 対策設定でカスタムホワイトリストを独自に設定している場合
  • 参考: v6.0.x、マークダウン設定
  1. v6.0 以降、起動時に XSS 対策設定は「おすすめ設定」を選択した状態にリセットされ、過去の設定は引き継がれません。
  2. 「全てのタグを削除」モードは廃止されているため、選択できません。
  3. カスタムホワイトリストを利用していた場合は、管理画面のマークダウン設定（/admin/markdown）から再設定します。入力形式は マークダウン設定 を参照してください。
  4. GROWI v6.0.0〜v7.0.11 では、カスタムホワイトリストに入力した値が正しく反映されません。 不具合自体は v6.0.0 から存在しますが、症状が顕在化するのは v7.0.10 以降で、マークダウン中の HTML タグを正常にレンダリングできなくなります。該当する場合は、次のいずれかで対処してください。
    • おすすめ設定を利用する
    • v7.0.12 以降にアップグレードしたうえでカスタムホワイトリストを選択し、タグ名・タグ属性ともにおすすめ設定の値をインポートして、それをベースに設定を変更する

# 未変換のページを v5 互換形式へ変換する

  • 対応タイミング: アップグレード後
  • 変更が入ったバージョン: v5.0
  • 対応が必要な条件: v4.5 以前に作成され、未変換のページが残っている場合
  • 参考: v5.0.x

  1. v4.5 までに作成されたページは、v5.0 以降でも新しい v5 互換形式には自動変換されません。

  2. 公開（パブリック）ページは、管理ページの操作で一括変換できます。

  3. プライベートページは、ページツリー最下部の「旧形式のプライベートページ」リンク（/_private-legacy-pages）から、閲覧可能なページの一覧の中から対象を選択し、「一括変換」ドロップダウンで変換します。

  4. 変換前後で、次のように挙動が変わります。

    v4.5 以前に作成されたデータ 新しい v5 互換形式のデータ
    ページツリーへの表示 表示されない 表示される
    子孫ページを伴う移動・削除 閲覧可能なページのみ処理 配下の全てのページを処理（ただし新しい v5 互換形式のページに限る）
    子孫ページに設定可能な閲覧権限 全ての種類の権限を設定可能 親ページよりも範囲の狭い権限のみ設定可能

  5. 事前に v5.0.x へのアップグレード の該当箇所を確認してください。

ヘルプ一覧に戻る