FlowiseAI バージョンアップ対応マニュアル

FlowiseAIは、視覚的にAIワークフローを構築できるオープンソースツールとして広く利用されています。新バージョンではパフォーマンス改善やセキュリティ強化、新たなノード機能が追加されており、継続的なアップデートが推奨されます。本記事では、既存環境から最新バージョンへの移行プロセス、特に互換性の問題点とその解決策について詳しく解説します。

事前準備：環境確認とバックアップ

アップデート前に、開発・運用環境が要件を満たしているかを確認してください。

データのバックアップ手順

アップデート前の完全バックアップは必須です。以下のコマンドで必要なファイルとデータベースを保存してください。

# PostgreSQLデータベースのエクスポート
pg_dump -U flowise_user -h localhost flowise_production > backup_flowise_$(date +%Y%m%d).sql

# 環境設定ファイルのコピー
cp packages/server/.env .env.server.bak
cp packages/ui/.env .env.ui.bak

# カスタムコンポーネントのアーカイブ
tar -czf custom-components-$(date +%m%d).tar.gz packages/components/nodes/

アップデート方法（2通り）

方法1：ソースコードからの更新（開発者向け）

# 最新リビジョンの取得
git fetch origin
git checkout main
git pull origin main

# 依存関係の再構築
pnpm clean
pnpm install --prefer-offline

# メモリ制限の設定（ビルド時）
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm run build

# サービス起動
pnpm run start:prod

方法2：Dockerによる更新（本番環境向け）

# docker-compose.yml の例
version: '3.8'
services:
  flowise:
    image: flowiseai/flowise:v3.1.0
    container_name: flowise-app
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/flowise
      - FLOWISE_USERNAME=admin
    volumes:
      - ./custom-nodes:/app/packages/components/nodes/custom

docker-compose down
docker-compose pull
docker-compose up -d --remove-orphans

主な破壊的変更と対応策

1. ノードインターフェースの再設計

v3系でノード定義の型構造が変更されました。従来のinputs/outputsはinputSlots/outputSlotsに置き換えられています。

// 古い形式（v2まで）
interface LegacyNode {
    name: string;
    inputs: Array<{ label: string }>;
    outputs: Array<{ name: string }>;
}

// 新しい形式（v3+）
interface FlowiseNode {
    displayName: string;
    inputAnchors: AnchorConfig[];
    outputAnchors: AnchorConfig[];
    nodeSettings: NodeSettings;
}

既存のカスタムノードを修正する場合は、以下のようにラッパー関数で変換を行うのが効果的です。

function migrateLegacyNode(legacy: LegacyNode): FlowiseNode {
    return {
        displayName: legacy.name,
        inputAnchors: legacy.inputs.map(i => ({
            id: generateId(),
            label: i.label,
            type: 'text'
        })),
        outputAnchors: legacy.outputs.map(o => ({
            id: generateId(),
            name: o.name,
            category: 'output'
        })),
        nodeSettings: { version: '3.0' }
    };
}

2. 認証システムの刷新

v3ではJWTトークンの有効期間が短縮され、リフレッシュトークンの導入が必須になりました。フロントエンド側では、自動ログイン処理の見直しが必要です。

async function handleTokenExpiry() {
    const refreshToken = localStorage.getItem('refresh_token');
    const res = await fetch('/api/v1/auth/refresh', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ refreshToken })
    });
    
    if (res.ok) {
        const { accessToken } = await res.json();
        setAuthToken(accessToken);
    } else {
        redirectToLogin();
    }
}

3. データベーススキーマの移行

TypeORMのマイグレーション機能を利用して、テーブル構造の更新を行います。

# マイグレーションファイルの生成
npx typeorm migration:create -n UpdateNodeSchemaV3

# 実行（指定設定ファイルを使用）
npx typeorm migration:run -f packages/server/ormconfig.prod.json

よくあるトラブルシューティング

• 依存パッケージの競合：
  pnpm install --force を使用してキャッシュを無視して再インストールします。
• ビルド時のメモリ不足：
  環境変数NODE_OPTIONSに--max-old-space-size=4096を設定してください。
• カスタムノードが読み込まれない：
  package.jsonのpeerDependenciesに正しいFlowiseバージョンが記載されているか確認し、パスがpackages/components/nodes/custom/内にあることを確認してください。

アップデート後の検証項目

正常に移行できたかを確認するために、以下のチェックリストを使用してください。

緊急時：ロールバック手順

重大な不具合が発生した場合の復旧手順です。

# サービス停止
pnpm stop

# Git履歴に戻す
git checkout HEAD~1 -- .
git reset --hard

# 依存再インストール
pnpm install

# データベース復元
psql -U user flowise_db < backup_flowise_20241201.sql

# 再起動
pnpm run build && pnpm run start:prod

ベストプラクティス

• ステージング環境で事前にアップデートテストを行う
• CI/CDパイプラインに自動ビルドと基本テストを組み込む
• マイグレーションスクリプトはバージョン管理対象とする
• チーム内で変更点の共有ミーティングを開催する