Alfresco Community Edition — Upgrade Guide
Alfresco アップグレード手順
v7.4 → v26.x（Ubuntu 22 → 24）
🖥 Hyper-V / Windows Server 2016
📦 Ansible 公式ロール
🐘 PostgreSQL
☀️ Solr（Community版）
⛔ 移行元：Ubuntu 22 + Alfresco 7.4
→
✅ 移行先：Ubuntu 24 + Alfresco 26.x
🔄
本記事について
従来の移行手順（Samba共有フォルダ経由）をrsync over SSHに置き換えています。 WindowsホストでLinuxパーティションを読む際の日本語ファイル名の文字化けを回避し、VM間で直接転送します。
従来の移行手順（Samba共有フォルダ経由）をrsync over SSHに置き換えています。 WindowsホストでLinuxパーティションを読む際の日本語ファイル名の文字化けを回避し、VM間で直接転送します。
目次
1 概要・注意事項
| 項目 | 移行元VM | 移行先VM |
|---|---|---|
| OS | Ubuntu 22.04 Server | Ubuntu 24.04 Server |
| Alfresco | Community 7.4 | Community 26.x |
| インストール方法 | Alfresco公式Ansibleロール | |
| 仮想化基盤 | Hyper-V / Windows Server 2016 | |
| データベース | PostgreSQL | |
| 検索サービス | Solr（Community版） | |
⚠️
ACS 7.4 はサポート終了（End-of-Life）
2026年6月、Alfresco公式Ansibleロールリポジトリにて ACS 7.4 のサポートが正式に削除されました （PR #1407 "Remove ACS 7.4 support and test coverage"）。 移行元として 7.4 を使用している場合は、早期に新バージョンへの移行を検討してください。
2026年6月、Alfresco公式Ansibleロールリポジトリにて ACS 7.4 のサポートが正式に削除されました （PR #1407 "Remove ACS 7.4 support and test coverage"）。 移行元として 7.4 を使用している場合は、早期に新バージョンへの移行を検討してください。
⚠️
Windows経由のファイルコピーは避ける
WindowsホストでLinux（ext4）パーティションを読むと日本語ファイル名が文字化けします。必ずLinux同士（rsync/SSH）で転送してください。
WindowsホストでLinux（ext4）パーティションを読むと日本語ファイル名が文字化けします。必ずLinux同士（rsync/SSH）で転送してください。
2 移行先VMにAlfresco 26.x をインストール
Ubuntu 24.04 ServerにAlfresco公式Ansibleロールで新規インストールします。
リポジトリ取得・Python環境構築
移行先VM
# 公式Ansibleロールをクローン git clone https://github.com/Alfresco/alfresco-ansible-deployment.git cd alfresco-ansible-deployment # Python仮想環境を構築 sudo apt install pipenv python3-venv python3.12 -m venv venv source venv/bin/activate # Ansibleの依存関係をインストール pip3 install pipenv python3.12 -m pipenv install --deploy python3.12 -m pipenv run ansible-galaxy install -r requirements.yml
アクセスURLの設定
アクセスする可能性のあるURLを全て指定します。誤るとファイル操作等ができなくなります。
移行先VM
sudo vi playbooks/group_vars/all.yml
playbooks/group_vars/all.yml
acs_play_known_urls: [ http://サーバーのIPアドレス:8080/share, https://サーバーのIPアドレス:8080/share, https://ドメイン名/share ] acs_play_major_version: 26
Community版向けに検索サービスを設定
初期設定はEnterprise版の検索サービスが選択されているため、Solrに切り替えます。
移行先VM
sudo vi inventory_local.yml
inventory_local.yml（変更箇所）
# Solrを有効化（コメントを解除） search: children: repository: # ← コメント解除 # Enterprise Searchを無効化（コメントアウト） search_enterprise: children: # repository: # ← コメントアウト elasticsearch: children: # repository: # ← コメントアウト
Vaultパスワード生成・インストール実行
移行先VM
# Vaultパスワードを生成 openssl rand -base64 21 > ~/.vault_pass.txt export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass.txt # シークレットを自動生成 pipenv run ansible-playbook \ -e vault_init=encrypted_file playbooks/secrets-init.yml # インストール実行（Community版として指定） pipenv run ansible-playbook playbooks/acs.yml \ -i inventory_local.yml \ -e "acs_play_repository_acs_edition=Community"
3 データ転送の事前準備
🔄
従来手順との変更点
従来のSamba共有フォルダ（
従来のSamba共有フォルダ（
/mnt/smb）経由の転送をrsync over SSHに変更しています。Sambaのセットアップが不要になり、日本語ファイル名の文字化けも回避できます。移行先VM：SSH サーバーの確認
移行先VM
sudo systemctl status ssh # 起動していない場合 sudo apt install openssh-server sudo systemctl enable --now ssh
移行先VM：一時受け取りディレクトリの作成
Alfrescoの管理ディレクトリに直接転送すると権限エラーが発生しやすいため、ホームディレクトリ配下の一時ディレクトリに受け取ります。
移行先VM
mkdir -p ~/alfresco_restore/content mkdir -p ~/alfresco_restore/search-services mkdir -p ~/alfresco_restore/search-services-config mkdir -p ~/alfresco_restore/extension mkdir -p ~/alfresco_restore/web-extension mkdir -p ~/alfresco_restore/messages
移行元VM：Alfrescoの停止
移行元VM
sudo systemctl stop alfresco-content.service sudo systemctl stop alfresco-search.service # 停止確認 sudo systemctl status alfresco-content.service # → inactive (dead) になればOK
screenでセッションを保持する
転送に時間がかかるため、端末を閉じてもサーバー上で継続できるよう screen を使用します。
移行元VM
# screenセッション開始 screen -S alfresco_migrate # デタッチ（セッションを維持したまま端末を閉じる） # Ctrl + A → D # 後で再接続 screen -r alfresco_migrate
4 移行元からデータ転送（rsync）変更
以下のコマンドはすべて移行元VM上で実行します。--omit-dir-timesオプションでディレクトリのタイムスタンプ変更エラーを回避します。rsyncは差分転送のため、中断後に再実行しても続きから再開されます。
コンテンツストア
移行元VM
sudo rsync -avz --progress --omit-dir-times \ /var/opt/alfresco/content-services/content/ \ ユーザー名@移行先VMのIPアドレス:~/alfresco_restore/content/
Solrインデックス・バックアップ
移行元VM
sudo rsync -avz --progress --omit-dir-times \ /var/opt/alfresco/search-services/ \ ユーザー名@移行先VMのIPアドレス:~/alfresco_restore/search-services/
Solrモデル・設定
移行元VM
sudo rsync -avz --progress --omit-dir-times \ /etc/opt/alfresco/search-services/ \ ユーザー名@移行先VMのIPアドレス:~/alfresco_restore/search-services-config/
カスタマイズ設定（カスタムモデルがある場合）
移行元VM
sudo rsync -avz --progress --omit-dir-times \ /etc/opt/alfresco/content-services/classpath/alfresco/extension/ \ ユーザー名@移行先VMのIPアドレス:~/alfresco_restore/extension/ sudo rsync -avz --progress --omit-dir-times \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension/ \ ユーザー名@移行先VMのIPアドレス:~/alfresco_restore/web-extension/ sudo rsync -avz --progress --omit-dir-times \ /etc/opt/alfresco/content-services/classpath/alfresco/messages/ \ ユーザー名@移行先VMのIPアドレス:~/alfresco_restore/messages/
データベースダンプ
移行元VM
# ダンプ作成 su - su - postgres pg_dumpall > /tmp/alfresco_dump exit # 移行先VMへ転送 scp /tmp/alfresco_dump \ ユーザー名@移行先VMのIPアドレス:/tmp/
5 移行先へデータを適用
移行先VMで一時ディレクトリから正式パスへ移動します。
Alfrescoを停止
移行先VM
sudo systemctl stop alfresco-content.service sudo systemctl stop alfresco-search.service
コンテンツストアの差替
移行先VM
# 既存コンテンツを削除 sudo rm -rf /var/opt/alfresco/content-services/content/contentstore sudo rm -rf /var/opt/alfresco/content-services/content/contentstore.deleted # 移行データをコピー sudo cp -a ~/alfresco_restore/content/contentstore \ /var/opt/alfresco/content-services/content/ sudo cp -a ~/alfresco_restore/content/contentstore.deleted \ /var/opt/alfresco/content-services/content/
Solrデータの差替
移行先VM
# 既存Solrインデックスを削除 sudo rm -rf /var/opt/alfresco/search-services/alfresco/index sudo rm -rf /var/opt/alfresco/search-services/archive/index sudo rm -rf /etc/opt/alfresco/search-services/solrhome/alfrescoModels # 移行データをコピー sudo cp -a ~/alfresco_restore/search-services/alfresco/index \ /var/opt/alfresco/search-services/alfresco/ sudo cp -a ~/alfresco_restore/search-services/archive/index \ /var/opt/alfresco/search-services/archive/ sudo cp -a ~/alfresco_restore/search-services-config/solrhome/alfrescoModels \ /etc/opt/alfresco/search-services/solrhome/
権限を修正
移行先VM
sudo chown -hR alfresco:alfresco /var/opt/alfresco/content-services/content/ sudo chown -hR alfresco:alfresco /var/opt/alfresco/search-services/ sudo chown -hR alfresco:alfresco /etc/opt/alfresco/search-services/solrhome/
一時移行データの削除
正式パスへのコピーが完了し、Alfrescoが正常に起動・動作することを確認してから削除します。本番稼働確認後2〜4週間を目安に保持し、問題がなければ削除してください。
| 確認項目 | 確認方法 |
|---|---|
| Alfrescoへのログイン | ブラウザから http://移行先IP:8080/share にアクセス |
| 過去データの閲覧 | 移行前のメール・ドキュメントが参照できること |
| 新着メールの取り込み | getmailが正常に動作していること |
| 検索の動作 | Solrインデックスが有効なこと |
| 数日間の本番運用 | 問題が出ないことを確認 |
移行先VM（本番稼働確認後に実行）
# 一時ディレクトリの容量を確認 du -sh ~/alfresco_restore/ # 一時移行データを削除 rm -rf ~/alfresco_restore/
ℹ️
移行元VMはそのまま保持する
移行先の本番稼働が安定するまで、移行元VM（旧サーバー）は停止したまま保持することを推奨します。万一の際にDBダンプや旧コンテンツストアを参照・復元できる状態を維持するためです。移行元VMの廃棄は、移行先が長期間安定稼働したことを確認してから判断してください。
移行先の本番稼働が安定するまで、移行元VM（旧サーバー）は停止したまま保持することを推奨します。万一の際にDBダンプや旧コンテンツストアを参照・復元できる状態を維持するためです。移行元VMの廃棄は、移行先が長期間安定稼働したことを確認してから判断してください。
6 データベースの移行
移行先VM
# PostgreSQLでDBを再作成 su - su - postgres psql drop database alfresco ; create database alfresco ; \q # ダンプをリストア psql -f /tmp/alfresco_dump exit
PostgreSQLパスワードの確認・設定
alfresco-global.properties の db.password とPostgreSQLの alfresco ユーザーのパスワードを一致させます。
移行先VM
# 設定ファイルのパスワードを確認 sudo grep "db.password" \ /etc/opt/alfresco/content-services/classpath/alfresco-global.properties # PostgreSQLのパスワードを設定ファイルに合わせる su - su - postgres psql ALTER USER alfresco WITH PASSWORD '設定ファイルのdb.password'; \q
⚠️
パスワードが一致しないとAlfresco起動時に
FATAL: password authentication failed for user "alfresco" エラーが発生します。
ℹ️
DBダンプファイルの削除
/tmp/alfresco_dump は本番稼働確認後に削除してください。削除前に容量を確認しておくと安心です。
du -sh /tmp/alfresco_dump && rm -f /tmp/alfresco_dump7 カスタマイズ設定の移行
⚠️
カスタムモデルを移行しないと404エラーが発生します
custom-model-context.xml と モデル定義XML（customModel.xml 等）の両方を配置してください。移行先VM
# カスタムモデルを配置 sudo cp -a ~/alfresco_restore/extension/. \ /etc/opt/alfresco/content-services/classpath/alfresco/extension/ # Share設定を配置 sudo cp -a ~/alfresco_restore/web-extension/. \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension/ # メッセージファイルを配置 sudo cp -a ~/alfresco_restore/messages/. \ /etc/opt/alfresco/content-services/classpath/alfresco/messages/ # 権限を修正 sudo chown -R alfresco:alfresco \ /etc/opt/alfresco/content-services/classpath/alfresco/extension sudo chown -R alfresco:alfresco \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension sudo chown -R alfresco:alfresco \ /etc/opt/alfresco/content-services/classpath/alfresco/messages
配置確認
移行先VM
ls /etc/opt/alfresco/content-services/classpath/alfresco/extension/
# custom-model-context.xml と customModel.xml 等が存在すること
8 Alfresco起動・確認
移行先VM
sudo systemctl start alfresco-content.service
sudo systemctl start alfresco-search.service
# ログで起動確認
tail -f /var/log/alfresco/catalina.out
✅
起動成功の確認ポイント
catalina.outに
catalina.outに
Alfresco started が出力され、ブラウザから http://移行先VMのIP:8080/alfresco にアクセスできれば移行完了です。移行元VMのAlfresco再起動（本番継続）
移行元VM
sudo systemctl start alfresco-content.service sudo systemctl start alfresco-search.service
9 サーバー移行後の WebDAV URL 修正
サーバー移行後、Share の「共有」パネルに表示される WebDAV URL が旧サーバーの IP アドレスのままになる場合があります。
| ファイル | 修正箇所 |
|---|---|
alfresco-global.properties |
alfresco.host が空欄または旧 IP になっている |
share-config-custom.xml |
<repository-url> が旧 IP になっている |
share-config-custom.xml |
CSRFPolicy の <referer>・<origin> が旧 IP になっている |
① alfresco-global.properties の修正
alfresco.host が空欄の場合、WebDAV URL の生成時にデフォルト値として旧 IP が使われることがあります。
移行先VM
sudo grep -E "alfresco.host|alfresco.port|alfresco.protocol" \ /etc/alfresco/alfresco-global.properties
以下のように新サーバーの IP・ポートを明示してください。
/etc/alfresco/alfresco-global.properties（変更箇所）
alfresco.host=新サーバーの IP アドレス
alfresco.port=8080
alfresco.protocol=http
② share-config-custom.xml の修正
WebDAV URL の表示元となる <repository-url> と、CSRF フィルターの <referer>・<origin> に旧 IP が残っていないか確認します。
移行先VM
# 旧 IP が残っているか確認 sudo grep "旧サーバーの IP アドレス" \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension/share-config-custom.xml
旧 IP が検出された場合は sed で一括置換します。
移行先VM
# repository-url のポートが異なる場合は個別に置換 sudo sed -i \ 's|http://旧IP:80/alfresco|http://新IP:8080/alfresco|g' \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension/share-config-custom.xml # referer / origin の旧 IP を一括置換 sudo sed -i \ 's|http://旧IP:8080|http://新IP:8080|g' \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension/share-config-custom.xml # 置換後の確認（何も表示されなければ OK） sudo grep "旧IP" \ /etc/opt/alfresco/content-services/classpath/alfresco/web-extension/share-config-custom.xml
⚠️
<repository-url> のポート番号に注意alfresco-global.properties で alfresco.port=80 のままだった場合、<repository-url> には :80 で記録されていることがあります。sed で置換する際はポート番号まで含めて指定してください。③ Alfresco を再起動して確認
移行先VM
sudo systemctl restart alfresco
# 起動ログを確認
tail -f /var/log/alfresco/catalina.out
Share にログイン後、任意のフォルダ詳細画面の「共有」パネルを開き、WebDAV URL が新サーバーの IP アドレスになっていれば修正完了です。
✅
確認ポイント
「共有」パネルの WebDAV URL が
「共有」パネルの WebDAV URL が
http://新IP:8080/alfresco/webdav/... と表示されれば正常です。10 日本語対応（プレビューフォント・LibreOffice）
Alfresco 26.x + Ubuntu 24.04 環境では、Word・Excel のプレビューで日本語が表示されない場合があります。Transform Service（alfresco-tengine-aio）が内部で使用する LibreOffice に日本語フォントを追加することで解決できます。
ℹ️
Transform Service が使用する LibreOffice のパスは
systemctl cat alfresco-tengine-aio の -DLIBREOFFICE_HOME= で確認できます。本手順では /opt/libreoffice7.2/ を前提としています。① 日本語フォントのインストール
移行先VM
sudo apt install fonts-noto-cjk -y
② LibreOffice のフォントディレクトリに CJK フォントをコピー
移行先VM
sudo cp /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc \ /opt/libreoffice7.2/share/fonts/truetype/ sudo cp /usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc \ /opt/libreoffice7.2/share/fonts/truetype/ sudo cp /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc \ /opt/libreoffice7.2/share/fonts/truetype/ sudo fc-cache -fv /opt/libreoffice7.2/share/fonts/
③ フォント代替設定（fc_local.conf）
Word 文書で使われる游明朝・游ゴシック等を Noto フォントに代替させます。/opt/libreoffice7.2/share/fonts/truetype/fc_local.conf の </fontconfig> 直前に以下を追加します。
/opt/libreoffice7.2/share/fonts/truetype/fc_local.conf（追加箇所）
<!-- Japanese font aliases -->
<alias binding="same">
<family>游明朝</family>
<accept><family>Noto Serif CJK JP</family></accept>
</alias>
<alias binding="same">
<family>Yu Mincho</family>
<accept><family>Noto Serif CJK JP</family></accept>
</alias>
<alias binding="same">
<family>游ゴシック</family>
<accept><family>Noto Sans CJK JP</family></accept>
</alias>
<alias binding="same">
<family>Yu Gothic</family>
<accept><family>Noto Sans CJK JP</family></accept>
</alias>
<alias binding="same">
<family>Meiryo</family>
<accept><family>Noto Sans CJK JP</family></accept>
</alias>
<alias binding="same">
<family>MS Gothic</family>
<accept><family>Noto Sans CJK JP</family></accept>
</alias>
<alias binding="same">
<family>MS Mincho</family>
<accept><family>Noto Serif CJK JP</family></accept>
</alias>
④ Java fallback フォントの設定
Transform Service は Java 21 で動作しています。Java 側にも fallback フォントを追加します。
移行先VM
sudo mkdir -p /opt/openjdk-21.0.9/lib/fonts/fallback sudo ln -sf /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc \ /opt/openjdk-21.0.9/lib/fonts/fallback/ sudo ln -sf /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc \ /opt/openjdk-21.0.9/lib/fonts/fallback/
⑤ LibreOffice の registry に CJK フォント代替を登録
移行先VM
sudo tee /opt/libreoffice7.2/share/registry/cjk-fonts.xcu << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
oor:name="VCL" oor:package="org.openoffice.VCL">
<node oor:name="Fonts">
<node oor:name="FontSubstitutions">
<node oor:name="MS Gothic" oor:op="replace">
<prop oor:name="ReplacementFont"><value>Noto Sans CJK JP</value></prop>
</node>
<node oor:name="MS Mincho" oor:op="replace">
<prop oor:name="ReplacementFont"><value>Noto Serif CJK JP</value></prop>
</node>
<node oor:name="Yu Gothic" oor:op="replace">
<prop oor:name="ReplacementFont"><value>Noto Sans CJK JP</value></prop>
</node>
<node oor:name="Yu Mincho" oor:op="replace">
<prop oor:name="ReplacementFont"><value>Noto Serif CJK JP</value></prop>
</node>
<node oor:name="Meiryo" oor:op="replace">
<prop oor:name="ReplacementFont"><value>Noto Sans CJK JP</value></prop>
</node>
</node>
</node>
</oor:component-data>
EOF
⑥ サービス再起動
移行先VM
sudo systemctl stop alfresco-tengine-aio sudo pkill -u alfresco -f soffice.bin 2>/dev/null || true sudo systemctl start alfresco-tengine-aio sudo systemctl restart alfresco-content.service
✅
再起動後に Word 文書をAlfrescoにアップロードしてプレビューを確認してください。既存ファイルで文字化けが残る場合はブラウザキャッシュをクリア（Ctrl+Shift+Delete）した後に再確認してください。それでも表示されない場合は rendition を削除して再生成します。
rendition の削除と再生成（既存ファイルの文字化け対処）
移行先VM
# ノードIDを指定してrenditionを削除 source /etc/alfresco/credentials FILE_NODE="ノードID" curl -s -u "$ALFRESCO_USER:$ALFRESCO_PASS" -X DELETE \ "$ALFRESCO_HOST/alfresco/api/-default-/public/alfresco/versions/1/nodes/$FILE_NODE/renditions/doclib" # doclib renditionを再生成 curl -s -u "$ALFRESCO_USER:$ALFRESCO_PASS" -X POST \ -H "Content-Type: application/json" \ "$ALFRESCO_HOST/alfresco/api/-default-/public/alfresco/versions/1/nodes/$FILE_NODE/renditions" \ -d '{"id":"doclib"}'
⚠️
pdf rendition は REST API の DELETE で削除されない場合があります。その場合は PostgreSQL で直接ノードを特定して削除してください。
SELECT child.uuid FROM alf_node parent JOIN alf_child_assoc ca ON parent.id = ca.parent_node_id JOIN alf_node child ON ca.child_node_id = child.id JOIN alf_node_properties p ON child.id = p.node_id JOIN alf_qname q ON p.qname_id = q.id WHERE parent.uuid = 'ファイルのノードID' AND q.local_name = 'name' AND p.string_value = 'pdf';
11 トラブルシューティング
カスタムモデルで404エラーが発生する
💡
custom-model-context.xml と モデル定義XML の両方が /etc/opt/alfresco/content-services/classpath/alfresco/extension/ に存在するか確認してください。片方だけでは動作しません。DB認証エラーで起動失敗する
エラーログ
FATAL: password authentication failed for user "alfresco"
💡
alfresco-global.properties の db.password を確認し、PostgreSQLの alfresco ユーザーのパスワードと一致させてください。rsync転送時にPermission deniedが発生する
💡
転送先の親ディレクトリまで含めて
alfresco:alfresco 所有・パーミッション 750 になっていないか確認してください。一時ディレクトリ（~/alfresco_restore/）に転送してから移動する方法が安全です。No space left on deviceが発生する
💡
LVMを使用している場合は
lvextend + resize2fs でディスクを拡張してください。Solrインデックスは省略してAlfresco起動後に管理コンソールから再インデックスを実行する方法も有効です。それでも起動・ログインできない場合（Ansibleで再インストール）
移行先VM
# vars/secrets.ymlを初期化 sudo vi vars/secrets.yml # → 記載内容を全て削除して保存 # アンインストール pipenv run ansible-playbook \ playbooks/platform-cleanup.yml -i inventory_local.yml # Vaultパスワード再作成 openssl rand -base64 21 > ~/.vault_pass.txt export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass.txt pipenv run ansible-playbook \ -e vault_init=encrypted_file playbooks/secrets-init.yml # 再インストール pipenv run ansible-playbook playbooks/acs.yml \ -i inventory_local.yml \ -e "acs_play_repository_acs_edition=Community"
