自分にとってのキラープラグインと言えるRedmine Knowledgebase。
これをRedmine 5.1に導入する際に恐ろしくハマったので、解決したときのメモです。
なお、本件の解決にはGoogle Gemini Advanced(2.5 Pro preview)の助けが必要でした。
環境
- Ubuntu 24.04
- Redmine 5.1.x
- Apache 2.4で稼働
- Ruby 3.2.x (本手順は Ruby 3.2.3 で確認)
- Rails 6.1.x (本手順は Rails 6.1.7.10 で確認)
- データベース: MySQL 8.0 (他のデータベースでも同様の問題が発生する可能性があります)
- プラグインソース: alexbevi/redmine_knowledgebase
盛大にハマった結果で得た手順
- DBのバックアップを取得します。
- プラグインのインストールを行います。
- マイグレーションエラーに対応します。
- マイグレーションの成功を確認します。
- Redmine（Webサービス）を再起動します。
- プラグインのインストールと動作確認を行います。
バックアップを取得します。
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ユーザのものです。
環境が許すなら、VPSのスナップショットのようにシステム全体のバックアップを取ることを強く推奨します。
プラグインのインストール
cd /path/to/redmine/root/directory/plugins && pwd
筆者環境/home/www-data/redmine/plugins
sudo -u www-data git clone https://github.com/alexbevi/redmine_knowledgebase
Redmineの実行ユーザでgit cloneとした方が、後にsudo chownする手間が省けます。
ls -l redmine_knowledgebase
ファイル一式があることと、ファイル群の所有者がwww-data(Redmineの実行ユーザ)であることを確認します。
cd /path/to/redmine/root/directory/plugins && pwd
筆者環境/home/www-data/redmine/
sudo -u www-data bundle install
初回マイグレーション実行 (エラー発生との対処)
以下のコマンドでプラグインのマイグレーションを実行します。このとき、壮大にハマったので、AIの力を借りて（というよりもほぼその指示に従って）解決しました。
sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production --trace
マイグレーションエラーの修正
エラーが発生した場合は、以下の手順で関連ファイルを修正し、その都度上記 redmine:plugins:migrate コマンドを再実行してください。
修正箇所1: 20121205100143_add_versioning.rb ファイルの対応
このマイグレーションでは、以下の2つのエラーが連続して発生する可能性があります。
Mysql2::Error: Duplicate column name 'version_comments' (in kb_articles table)ArgumentError: wrong number of arguments (given 2, expected 1) (in KbArticle.create_versioned_table 内部の create_table 呼び出し)
対象ファイルA: plugins/redmine_knowledgebase/db/migrate/20121205100143_add_versioning.rb
以下に従って修正していきます。
- 修正前の
class AddVersioning ... end の内容(主要部分):
class AddVersioning < ActiveRecord::Migration
def self.up
KbArticle.create_versioned_table
add_column :kb_articles, :version_comments, :string, :limit => 255, :default => ""
end
def self.down
remove_column :kb_articles, :version_comments
KbArticle.drop_versioned_table
end
end
- 修正後の
class AddVersioning ... end の内容:
class AddVersioning < ActiveRecord::Migration[6.1] # Rails 6.1 互換にする
def self.up
# kb_article_versions テーブルが存在しない場合のみ作成
unless ActiveRecord::Base.connection.table_exists?(:kb_article_versions)
if defined?(KbArticle) && KbArticle.respond_to?(:create_versioned_table)
KbArticle.create_versioned_table # この呼び出しは次の acts/versioned.rb の修正が必要
else
# このエラーは通常発生しないはずだが、念のため
raise "Cannot create kb_article_versions: KbArticle model or create_versioned_table method is not available."
end
end
# kb_articles テーブルに version_comments カラムが存在しない場合のみ追加
unless column_exists?(:kb_articles, :version_comments)
add_column :kb_articles, :version_comments, :string, :limit => 255, :default => ""
end
end
def self.down
if column_exists?(:kb_articles, :version_comments)
remove_column :kb_articles, :version_comments
end
if ActiveRecord::Base.connection.table_exists?(:kb_article_versions)
if defined?(KbArticle) && KbArticle.respond_to?(:drop_versioned_table)
KbArticle.drop_versioned_table
end
end
end
end
対象ファイルB: plugins/redmine_knowledgebase/lib/active_record/acts/versioned.rb
KbArticle.create_versioned_table が内部で呼び出す create_table で ArgumentError が発生します。このファイルを修正します。
- 修正対象箇所 (ファイル内の
create_versioned_table メソッドの中、通常503行目あたり):
# 修正前
self.connection.create_table(versioned_table_name, create_table_options) do |t|
Ruby
# 修正後 (create_table_options の前に ** を追加)
self.connection.create_table(versioned_table_name, **create_table_options) do |t|
上記AとBの両ファイルを修正後、再度以下を実行しましたが、エラーが発生しました。
sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production --trace
修正箇所2: 20150326093122_add_taggings_counter_cache_to_tags.rb ファイルの対応
次のエラーとして NameError: uninitialized constant ...::RedmineCrm が発生する可能性があります。
対象ファイル: plugins/redmine_knowledgebase/db/migrate/20150326093122_add_taggings_counter_cache_to_tags.rb
- 修正前の
class AddTaggingsCounterCacheToTags ... end の内容(主要部分):
class AddTaggingsCounterCacheToTags < Rails.version < '5.1' ? ActiveRecord::Migration : ActiveRecord::Migration[4.2] # 古い形式
def self.up
RedmineCrm::Tag.reset_column_information
# ... (RedmineCrm::Tag を参照するコードが続く) ...
end
def self.down
# ... (関連する可能性のある remove_column など) ...
end
end
- 修正後の
class AddTaggingsCounterCacheToTags ... end の内容:
(Redmine Crmプラグインを使用していない場合、関連処理をスキップします)
class AddTaggingsCounterCacheToTags < ActiveRecord::Migration[6.1] # Rails 6.1 互換にする
def self.up
puts "INFO: Skipping 'up' method in 20150326093122_add_taggings_counter_cache_to_tags.rb due to missing RedmineCrm module or intentional skip."
# 元の RedmineCrm::Tag に関連する処理は全てコメントアウトまたは削除
end
def self.down
puts "INFO: Skipping 'down' method in 20150326093122_add_taggings_counter_cache_to_tags.rb."
# 元の remove_column 処理なども、up で対応する処理を行わないためコメントアウトまたは削除
end
end
上記ファイルを修正後、更に以下を実行します。
sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production --trace
これらの手順で、ようやく、
- コンソールにエラーメッセージが出ないこと
db:schema:dumpがログに出力されること
を確認しました。
マイグレーション完了の確認
念のため、
mysql -u root -p
としてMySQLコンソールにログイン。
USE DATABASE redmine;
(自分が使っているRedmineのDBを指定します)
kb_article_versionsテーブルの確認
SHOW TABLES LIKE 'kb_article_versions';
DESCRIBE kb_article_versions;
DESCRIBE kb_articles;
それぞれ、テーブルが作成されていること、kb_articles テーブルに version_comments カラムが存在すること、および content カラムの型が変更されていること（ChangeColumnArticleToLongText マイグレーションによる）を確認します。
Redmineの再起動
ここではWebサービス(Apache)の再起動を前提とします。
systemctl status apache2.service
active(running)を確認します。
sudo systemctl restart apache2.service
systemctl status apache2.service
active(running)を確認します。
プラグインの動作確認
Redmineにログインし、ナレッジベースプラグインの各機能
- 記事の作成
- 編集
- 表示
- バージョン管理
- ファイル添付
などが正常に動作するか確認してください。
注意点:
- 上記の手順は、特定のバージョンの組み合わせで発生した問題への対処法です。プラグインやRedmineのバージョンが異なる場合は、別の問題が発生したり、異なる修正が必要になる場合があります。
- 途中でマイグレーションが認識されなくなるなどの不可解な問題が発生した場合は、一度プラグインディレクトリを削除し、データベースをリストア（または関連テーブルを手動削除）、再度GitHubからクリーンにクローンし直してから上記手順を開始すると、問題が解消されることがあります。
おまけ：切り戻し手順
この手順で成功したとはいえ、失敗はつきものです。そのため、以下に切り戻し手順を記します。
通常の切り戻し
ディレクトリ移動
cd /path/to/redmine/root/directory/plugins && pwd
筆者環境/home/www-data/redmine/
プラグインアンインストール
sudo -u www-data bundle exec rake redmine:plugins:migrate NAME=redmine_knowledgebase VERSION=0 RAILS_ENV=production
ディレクトリ削除
sudo rm plugins/redmine_knowledgebase -Rf
Webサービス再起動
systemctl status apache2.service
active(running)を確認します。
sudo systemctl restart apache2.service
systemctl status apache2.service
active(running)を確認します。
それでもダメだった切り戻し（DBリストア)
cd /hoge && pwd
mysql -h localhost -u redmine -p redmine < redmine_backup.$(date +%Y%m%d).sql
パスワードはredmineインストール時に設定したDBユーザのものです
systemctl status apache2.service
active(running)を確認します。
sudo systemctl restart apache2.service
systemctl status apache2.service
active(running)を確認します。
再起動後、復旧しているかを確認します。
