こちらの記事を更に詳細にまとめたものとなります。
概要
様々なプラグインにより機能を追加できるのがRedmineの魅力。
しかしながら、そのプラグイン導入の過程によって予期せぬエラーが起きます。
本記事では、エラーの内容と対処、並びにこれが起きないための運用について筆者の経験を元に書き起こしています。
想定としている読者
- LinuxでRedmineを動かしている
- その管理をしている / 管理を任されている
- プラグインインストール時にエラーが発生している
エラーが起きた環境
| 種別 | 環境1 | 環境2 | 環境3 |
|---|---|---|---|
| OS | Ubuntu 20.04 | CentOS 7 | Ubuntu 22.04 |
| Redmine | 4.2 | 3.3 | 5.0 |
| DB | MySQL 8.3.x | MariaDB 5.5.x | MySQL 8.3.x |
| Ruby | 2.7 | 2.3 | 3.1 |
具体的に何が起こったか？
Case 1. エラー画面が表示され、どこにもアクセスできない。
We're sorry, buty something went wrong.
We've been notified about this issue and we'll take a look at it shortly.
この画面は「やってしまったか」感がとても強いです。
Case 1.の原因
経験上、以下の理由で発生しました。
原因1-1：DBマイグレーションをしていない
プラグインインストール時、DBのマイグレーションを行っていない手順ミスはありがちです。
原因1-1の対処：DBマイグレーションを行う。
こちらはrailsとapacheの手順です。自身の環境に合わせて実施してください。
cd /home/www-data/redmine && pwd
# Redmineのルートディレクトリに移動します。自分の環境に合わせます。
sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production
# RedmineのルートディレクトリでDBマイグレーションを実施します
sudo systemctrl restart apache2.service
# Webサービスを再起動します。原因1-2: プラグイン名とレポジトリが異なる。(バージョン名が付与されている)
view_customizeのように、プラグイン名とレポジトリ名が異なるパターンはあります。
例：
https://github.com/onozaty/redmine-view-customize
と、レポジトリ名はredmine-view-customizeですが、実際のプラグイン名は
view_customizeです。
また、zipを直接入手した場合は、解凍したディレクトリにバージョン名が付与されます。
原因1-2の対処: ディレクトリをリネーム
以下は一例です。
cd /home/www-data/redmine/plugins && pwd
# Redmineのルートディレクトリに移動します。
sudo mv redmine-view-customize view_customize
sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production
# RedmineのルートディレクトリでDBマイグレーションを実施します
sudo systemctrl restart apache2.service
# Webサービスを再起動します。原因1-3: プラグインとRedmineのバージョンが合ってない。
例として:
https://www.redmine.org/plugins/redmine_custom_workflows
- Compatible with Redmine 5.0.x, 4.2.x, 4.1.x.
と書かれているように、古いRedmineのバージョンに合ってないプラグインをインストールしたときに起こりがちです。
また、逆に、プラグインが新しいRedmineに対応していない時にも発生します。
原因1-4: 導入済みのプラグインとコンフリクトを起こしている。
ある種、オープンソースの宿命と言えます。
有志/企業が機能を追加しているので、他のプラグインと同じライブラリを用いていたりDBのテーブルが重複するなどで発生します。
以下のように、メンテナが相性が悪いプラグインを認識している場合はそれに注意すればいいのですが、多数あるプラグイン同士の相性をチェックするのは極めて難しい問題です。
https://github.com/ncoders/redmine_local_avatars
As reported in issue #12, the plugin "mega_calendar" ist not compatible with this plugin due to an issue with the provided users_controller_path.rb file.
原因1-3 / 原因1-4の対処: プラグインのアンインストール
こちらも、rails / apacheでの実施です。自分の環境に合わせて実施してください。
cd /home/www-data/redmine && pwd
# 自分の環境に合わせます。
sudo -u www-data bundle exec rake redmine:plugins:migrate NAME=プラグイン名 VERSION=0 RAILS_ENV=production
# プラグイン名は /plugin/配下にあるディレクトリ名です
cd plugins && pwd
# プラグインが配置されているディレクトリに移動します。
sudo rm -rf プラグイン名
ls -ld /home/www-data/redmine/plugins/プラグイン名
# 削除したディレクトリが存在しないことを確認します
sudo systemctl restart apache2.service上記、プラグインに起因したエラーの大半はDBの再マイグレーションやアンインストールによって解消しますが、これだけで収まらないのがRedmineプラグイン追加/アップデートの恐怖です。
Case 2. 一部の機能が使えない (Internal Error)
Case1.で発生したエラー画面の対処としてDB再マイグレーションやアンインストールを行った後、この事象が起きました。
- ログインはできる
- あるプラグインにアクセスできる
けれども、
- 管理画面に遷移する
- チケット一覧を見ようとする
- 他のプラグインの画面を見ようとする
等で、
Internal Error
An error occured on the page you were trying to access.
If you continue to experience problems please contact your Redmine administrator for assistance.
If you are the Redmine administrator, check your log files for details about the error.
の無慈悲なメッセージが出てきます。特にRedmineをファイルサーバ化するdmsfプラグイン周りで発生しました。
こうなると、
- DBの再マイグレーション
- プラグインアインインストール
でも、今の筆者の知見では修復できませんでした。その場合の対処方法は以下の通りです。
Case 2の対処方法: バックアップしたDBからの切り戻し
この作業は、「エラーを起こす前のDBバックアップデータを持っていないと元に戻すことはできません」
この前提条件がない場合は他の有識者に頼ってください。(少なくとも筆者は持ち合わせていません)
また、以下の環境で復旧を確認しています。
- MySQL 8.0.3系
- Redmine 5.0
- Redmine 4.2
手順
- プラグインアンインストール（実施済みの方は不要です)
cd /home/www-data/redmine && pwd
# 自分の環境に合わせます。
sudo -u www-data bundle exec rake redmine:plugins:migrate NAME=プラグイン名 VERSION=0 RAILS_ENV=production
# プラグイン名は /plugin/配下にあるディレクトリ名です
cd plugins && pwd
# プラグインが配置されているディレクトリに移動します。
sudo rm -rf プラグイン名
ls -ld /home/www-data/redmine/plugins/プラグイン名
# 削除したディレクトリが存在しないことを確認します
sudo systemctl restart apache2.service- バックアップしたDBのレストア
cd /hoge && pwd
# DBデータをバックアップしたディレクトリに移動します。
mysql -h DBホスト -u RedmineのDBユーザ -p RedmineのDB名 < RedmineのDBバックアップ
# 例 mysql -h localhost -u redmine -p redmine < redmine_backup.$(date +%Y%m%d).sql
# この処理で聞かれるパスワードはredmineインストール時に設定したDBユーザのものです
sudo systemctl restart apache2.serviceこの後、元に戻っていれば作業は完了です。
こうならないために
日々のバックアップを取る
これは必須です。最低限、データベースの定期的なバックアップを取り、障害に備えましょう。
参照（『こうなってしまったため』書き起こしました：）
- MySQLによる日次のバックアップ
- MySQLによる日次のバックアップ(暗号化版)
また、作業前に
cd /hoge && pwd
# 任意のバックアップディレクトリに移動します
mysqldump -h localhost -u redmine -p --no-tablespaces --single-transaction redmine > redmine_backup.$(date +%Y%m%d).sql
# それぞれ -h ホスト名 -u redmine -p ユーザ オプション db名です。
# パスワードはredmineインストール時に設定したDBユーザのものです等の、DBバックアップも必要です。
システムごとバックアップを取る
仮想サーバで動かしている、AWSのようなクラウドサービスを利用している場合はスナップショットを取得し、OSごとバックアップするのが後腐れありません。
