シンボリックリンクで切り替えるデプロイ — すぐ戻せる公開手順

サーバーに新しい版を置くとき、いまのファイルを上書きしていませんか。上書きの途中でアクセスが来ると、古いファイルと新しいファイルが混ざった状態が見えてしまいます。問題が出たときに、すぐ前の版へ戻すのも大変です。この記事では、シンボリックリンクを切り替えて公開するやり方を、PHP(Laravel)のアプリを例にまとめます。

考え方:置いてから、指す先を変える

公開するたびに、新しいフォルダへまるごと置きます。準備がすべて終わってから、Web サーバーが見ている current というリンクの指す先だけを、新しいフォルダへ切り替えます。

  • 切り替えはリンク1本なので、一瞬で終わる
  • 前の版のフォルダは残っているので、戻すときはリンクを戻すだけ
  • 準備の途中で失敗しても、公開中のサイトには影響しない

Capistrano や Deployer といったデプロイツールも、内側ではほぼ同じしくみを使っています。まずは手作業で流れをつかんでおくと、ツールを使うときにも何が起きているか分かりやすくなります。

フォルダの構成

/var/www/app/
├── releases/
│   ├── 20261020-1500/
│   └── 20261022-1030/
├── shared/
│   ├── .env
│   └── storage/
└── current -> releases/20261022-1030
  • releases/ — 公開した版ごとのフォルダ。名前は日時にしておくと並べやすい
  • shared/ — 版をまたいで残したいもの。設定ファイル(.env)、アップロードされたファイル、ログなど
  • current — いま公開している版を指すリンク。Web サーバーのドキュメントルートは current/public にする

公開の手順

新しい版を置いてから切り替えるまでを、順番に見ていきます。

APP=/var/www/app
REL=$APP/releases/$(date +%Y%m%d-%H%M)

# 1. 新しい版を置く
git clone --depth 1 --branch main [email protected]:me/app.git "$REL"

# 2. 版をまたぐものをつなぐ
ln -s $APP/shared/.env "$REL/.env"
rm -rf "$REL/storage" && ln -s $APP/shared/storage "$REL/storage"

# 3. 依存とキャッシュ
cd "$REL"
composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 4. データベース(必要なときだけ。先にバックアップを)
php artisan migrate --force

# 5. 切り替え
ln -s "$REL" $APP/current_tmp
mv -Tf $APP/current_tmp $APP/current

最後の切り替えは、ln -sfn で直接上書きするより、いったん別名でリンクを作ってから mv -T で置きかえるほうが安全です。ln -sfn は「古いリンクを消して、新しく作る」の2段階になるため、ほんの一瞬だけリンクがない時間ができます。mv による置きかえは、名前の付けかえが一度に行われます。【要確認:mv -T は GNU coreutils の機能。macOS など BSD 系では使えない】

切り替えたあとに忘れがちなこと

PHP の OPcache や、パスを覚えておくキャッシュ(realpath キャッシュ)が、古いフォルダを指したまま残ることがあります。切り替えたあとは PHP-FPM を reload しておくと確実です。

sudo systemctl reload php-fpm

Nginx を使っているときは、PHP に渡すパスを、リンクをたどったあとの実際のパスにしておくと、キャッシュの食いちがいが起きにくくなります。

fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;

【要確認:PHP-FPM のサービス名はディストリビューションや PHP のバージョンによってちがう(例:php8.3-fpm)】

戻すとき(ロールバック)

問題が見つかったら、ひとつ前の版へリンクを戻します。次の例は、いま公開している版がいちばん新しいときの書き方です。

PREV=$(ls -1d /var/www/app/releases/* | sort | tail -n 2 | head -n 1)
ln -s "$PREV" /var/www/app/current_tmp
mv -Tf /var/www/app/current_tmp /var/www/app/current
sudo systemctl reload php-fpm

ここで気をつけたいのが、データベースは戻らないことです。新しい版でテーブルの列を消したり、名前を変えたりしていると、前の版に戻したとたんに動かなくなります。マイグレーションは「列を足す」だけにとどめ、古いコードからも使える形にしておくと、戻すときに困りません。列を消すのは、次の版以降に分けて行います。

古い版の片づけ

版のフォルダは公開のたびに増えるので、新しいものをいくつか残して消します。

cd /var/www/app/releases
ls -1d */ | sort | head -n -5 | xargs -r rm -rf --

新しい5つを残して、それより古いものを消す例です。消す前に xargs の手前までを実行して、対象の一覧を目で確かめておくと安心です。【要確認:head -n -5 は GNU 版の書き方】

よくあるつまずき

  • アップロードした画像が消えた — storage が各版の中にあると、切り替えた瞬間に前の版へ置き去りになる。版をまたぐものは、かならず shared/ へ
  • 切り替えたのに古い画面のまま — OPcache が古いパスを覚えていることが多い。PHP-FPM の reload と、Nginx の $realpath_root を確認
  • キューやスケジューラーが古いコードで動き続ける — 常駐するワーカーは切り替えに気づかないので、php artisan queue:restart などで入れかえる
  • 権限エラー — 新しい版のフォルダの持ち主や、SELinux のラベルが前の版とちがっていないか確かめる

まとめ

  • 新しい版は別フォルダに置き、準備が終わってから current のリンクを切り替える
  • 設定やアップロードは shared/ に置いて、各版からリンクする
  • 切り替えは別名で作ってから mv -T。そのあと PHP-FPM を reload
  • データベースは戻らないので、マイグレーションは古いコードでも動く形に

最初は手順が多く見えますが、一度シェルスクリプトにまとめてしまえば、公開も戻すのもコマンドひとつになります。

シェアする

Xでシェア
ほかの記事も読んでみてねブログの一覧へ

← ブログ一覧へ