自分にとってのキラープラグインと言える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

盛大にハマった結果で得た手順¶

1. DBのバックアップを取得します。
2. プラグインのインストールを行います。
3. マイグレーションエラーに対応します。
4. マイグレーションの成功を確認します。
5. Redmine（Webサービス）を再起動します。
6. プラグインのインストールと動作確認を行います。

バックアップを取得します。¶

• 作業ディレクトリに移動

cd /hoge && pwd

任意のバックアップディレクトリに移動します

• mysqldumpによるバックアップ

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のスナップショットのようにシステム全体のバックアップを取ることを強く推奨します。

プラグインのインストール¶

• Redmineのプラグインディレクトリに移動

cd /path/to/redmine/root/directory/plugins && pwd

筆者環境/home/www-data/redmine/plugins

• git clone

sudo -u www-data git clone https://github.com/alexbevi/redmine_knowledgebase

Redmineの実行ユーザでgit cloneとした方が、後にsudo chownする手間が省けます。

• clone確認

ls -l redmine_knowledgebase

ファイル一式があることと、ファイル群の所有者がwww-data(Redmineの実行ユーザ)であることを確認します。

• 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)を確認します。

• Webサービス再起動

sudo systemctl restart apache2.service

• 稼働後確認

systemctl status apache2.service

active(running)を確認します。

プラグインの動作確認¶

Redmineにログインし、ナレッジベースプラグインの各機能

• 記事の作成
• 編集
• 表示
• バージョン管理
• ファイル添付

などが正常に動作するか確認してください。

注意点:¶

• 上記の手順は、特定のバージョンの組み合わせで発生した問題への対処法です。プラグインやRedmineのバージョンが異なる場合は、別の問題が発生したり、異なる修正が必要になる場合があります。
• 途中でマイグレーションが認識されなくなるなどの不可解な問題が発生した場合は、一度プラグインディレクトリを削除し、データベースをリストア（または関連テーブルを手動削除）、再度GitHubからクリーンにクローンし直してから上記手順を開始すると、問題が解消されることがあります。

おまけ：切り戻し手順¶

この手順で成功したとはいえ、失敗はつきものです。そのため、以下に切り戻し手順を記します。

通常の切り戻し¶

ディレクトリ移動¶

• Redmineのルートディレクトリに戻ります。

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)を確認します。

• Webサービス再起動

sudo systemctl restart apache2.service

• 稼働後確認

systemctl status apache2.service

active(running)を確認します。

それでもダメだった切り戻し（DBリストア)¶

• DBをバックアップしたディレクトリに移動

cd /hoge && pwd

• DBリストア

mysql -h localhost -u redmine -p redmine < redmine_backup.$(date +%Y%m%d).sql

パスワードはredmineインストール時に設定したDBユーザのものです

• 稼働前確認

systemctl status apache2.service

active(running)を確認します。

• Webサービス再起動

sudo systemctl restart apache2.service

• 稼働後確認

systemctl status apache2.service

active(running)を確認します。

再起動後、復旧しているかを確認します。