キャッシュ

キャッシュは、ダウンロード済みアーティファクトを管理し、冗長なネットワークトラフィックを回避するDewyの重要なコンポーネントです。 複数のキャッシュストア実装から選択でき、分散環境でのキャッシュ共有も可能です。

概要

キャッシュコンポーネントは、Dewyのデプロイプロセスにおいて以下の重要な役割を担います：

• アーティファクトの保存: ダウンロードしたバイナリファイルの永続化
• バージョン管理: 現在のバージョン情報の記録と管理
• 重複ダウンロード防止: 同一バージョンの再ダウンロードを回避
• 高速デプロイ: ローカルキャッシュからの即座な展開

キャッシュは、KVSインターフェースによって抽象化されており、用途に応じて異なる実装を選択できます。

キャッシュストア実装

ファイルシステム（File）- デフォルト

ローカルファイルシステムにアーティファクトを保存する最も基本的な実装です。

特徴:

• 永続的なデータ保存
• システム再起動後もデータ保持
• シンプルな設定と管理
• アーカイブ展開機能を内蔵

サポートされるアーカイブ形式:

• .tar.gz / .tgz
• .tar.bz2 / .tbz2
• .tar.xz / .txz
• .tar
• .zip

AWS S3

Amazon S3（およびS3互換オブジェクトストレージ）をbackendとする共有キャッシュです。S3 bucketがnode間で共有される真実のソースとなり、各Dewyインスタンスはアーカイブ展開のためのローカルstagingコピーを保持します。

特徴:

• 多数のDewyインスタンス間でキャッシュを共有
• 上流registryへのartifactダウンロードトラフィックを大幅に削減
• registry sourceとして使用しているAWS認証情報をそのまま流用可能
• ローカルstagingにより、展開処理はfile backendと同一

URL形式:

# s3://<region>/<bucket>/<prefix>?<options: endpoint>
dewy server --registry ghr://owner/repo \
  --cache s3://ap-northeast-1/mybucket/myapp -- /opt/myapp/current/myapp

S3互換サービス向けにendpointクエリパラメーターをサポートしています。AWS認証は標準のcredential chain（環境変数、shared config、IAM roleなど）を使用します。

Google Cloud Storage

Google Cloud Storageをbackendとする共有キャッシュです。S3 backendと同じハイブリッドモデル（cloudが真実のソース、ローカルstagingで展開）です。

URL形式:

# gs://<bucket>/<prefix>
dewy server --registry ghr://owner/repo \
  --cache gs://mybucket/myapp -- /opt/myapp/current/myapp

認証はGoogle Cloud標準の方式（GOOGLE_APPLICATION_CREDENTIALS、workload identity、ADC）に従います。

Registry result cache

S3とGCSのcache backendは registry-ttl=<duration> query parameterを受け付けます。指定すると上流registryのレスポンスそのものもキャッシュに保存され、同じprefixを共有するDewyインスタンス間で調停して、TTLウィンドウあたり1台だけが上流registryをpollするようになります。GitHub Releasesのようなrate-limit付きregistryを多数のDewyインスタンスでpollする場合に有効です。

# 30秒のfreshness windowで共有registry-result cacheを有効化
dewy server --registry ghr://owner/repo \
  --cache 's3://ap-northeast-1/mybucket/myapp?registry-ttl=30s' \
  -- /opt/myapp/current/myapp

# GCSでも同様
dewy server --registry ghr://owner/repo \
  --cache 'gs://mybucket/myapp?registry-ttl=30s' \
  -- /opt/myapp/current/myapp

cacheエントリ自体がrefresh lockを兼ねます（If-Match / ifGenerationMatchによるsingle-flight）。上流registry障害時は最後のキャッシュ値を返し続けるため（stale-but-usable）、一時的なregistry障害でクラスタが止まりません。

運用上の注意: stale-but-usableは Dewy.Run() の通常のエラー経路から上流エラーを隠すため、長期障害が設定済みのnotifierに通知されません。dewyログ内の "upstream registry failed; serving stale cache" warningを監視してください。

conditional writeをサポートしないbackend（現状はfile backend）に registry-ttl を設定した場合、Dewyは起動時に "registry-ttl set but cache backend does not support atomic writes; ignoring" warningを出力し、registry-result cacheを有効化せずに動作を続行します。

メモリ（Memory）

インメモリでアーティファクトを管理する高速な実装（予定）。

想定される特徴:

• 高速なアクセス
• 揮発性（再起動でデータ消失）
• メモリ使用量の増加

HashiCorp Consul

分散環境でのキャッシュ共有を実現する実装（予定）。

想定される利点:

• 複数Dewyインスタンス間でのキャッシュ共有
• レジストリへのリクエスト削減
• 分散システムでのレート制限対策

Redis

高性能な分散キャッシュシステムとの連携実装（予定）。

想定される特徴:

• 高速な分散キャッシュ
• TTL設定による自動expiration
• クラスター対応

キャッシュディレクトリ設定

Dewyは、以下の優先順位でキャッシュディレクトリを決定します：

1. DEWY_CACHEDIR 環境変数（最高優先度）

export DEWY_CACHEDIR=/var/cache/dewy
dewy server --registry ghr://owner/repo -- /opt/myapp/current/myapp

2. カレントディレクトリ + .dewy/cache（デフォルト）

# /opt/myapp/.dewy/cache が使用される
cd /opt/myapp
dewy server --registry ghr://owner/repo -- ./current/myapp

3. 一時ディレクトリ（フォールバック）

ディレクトリ作成に失敗した場合、自動的に一時ディレクトリにフォールバックします。

systemdでの設定例

# /etc/systemd/system/dewy.service
[Unit]
Description=Dewy Application Deployment Service
After=network.target

[Service]
Type=simple
User=dewy
Group=dewy
Environment=DEWY_CACHEDIR=/var/cache/dewy
ExecStart=/usr/local/bin/dewy server --registry ghr://myorg/myapp -- /opt/myapp/current/myapp
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

事前にディレクトリとアクセス権を設定：

sudo mkdir -p /var/cache/dewy
sudo chown dewy:dewy /var/cache/dewy
sudo chmod 755 /var/cache/dewy

Docker環境での設定

# 永続ボリュームでキャッシュを保持
docker run -d \
  -e DEWY_CACHEDIR=/app/cache \
  -v /host/dewy-cache:/app/cache \
  dewy:latest server --registry ghr://owner/repo -- /opt/app/current/app

キャッシュキーの仕組み

Dewyは、以下のキー構造でキャッシュを管理します：

currentキー

現在実行中のアプリケーションバージョンを示すspecialキーです。

# ファイルキャッシュの場合
cat /var/cache/dewy/current
# 出力例: v1.2.3--app_linux_amd64.tar.gz

この値は、実際のアーティファクトファイルを参照するキャッシュキーとして使用されます。

アーティファクトキー

バージョンタグとアーティファクト名を組み合わせた形式：

{version}--{artifact_name}

例:

• v1.2.3--myapp_linux_amd64.tar.gz
• v2.0.0-rc.1--myapp_darwin_arm64.zip

パフォーマンス最適化

レート制限対策

複数のDewyインスタンスを運用する場合、以下の戦略でレジストリへのリクエストを削減できます：

# ポーリング間隔を長くする（デフォルト: 10秒）
dewy server --registry ghr://owner/repo \
  --interval 60 -- /opt/myapp/current/myapp

# S3/GCS共有キャッシュにより、各インスタンスが同じartifactを重複ダウンロードしないようにする
dewy server --registry ghr://owner/repo \
  --cache s3://ap-northeast-1/dewy-cache/myapp \
  --interval 30 -- /opt/myapp/current/myapp

補足: 共有キャッシュは上流registryへのartifactダウンロードトラフィックを削減します。各インスタンスのmetadata polling回数自体は減りません（こちらは別レイヤの課題で、registry層でのstale-while-revalidateとして将来対応予定）。

ストレージ管理

# キャッシュサイズの制限（デフォルト: 64MB）
# 現在はファイルキャッシュのディレクトリサイズで判定
du -sh /var/cache/dewy

運用ガイド

トラブルシューティング

キャッシュミスが頻発する場合:

# キャッシュディレクトリの確認
ls -la $DEWY_CACHEDIR

# currentキーの確認
cat $DEWY_CACHEDIR/current

# 権限の確認
ls -la $DEWY_CACHEDIR

権限エラーの場合:

# ディレクトリ権限の修正
sudo chown -R dewy:dewy /var/cache/dewy
sudo chmod -R 755 /var/cache/dewy

ディスク容量不足の場合:

# キャッシュディスクtリの使用量確認
df -h /var/cache/dewy

# 古いキャッシュファイルの手動削除
find /var/cache/dewy -name "v*" -mtime +7 -delete

モニタリング

キャッシュ利用状況の確認:

# キャッシュファイル一覧
ls -la /var/cache/dewy/

# 現在のバージョン確認
cat /var/cache/dewy/current

# ログでキャッシュアクセスを監視
journalctl -u dewy.service -f | grep -i cache

設定例とベストプラクティス

本番環境での推奨設定

# systemd環境
Environment=DEWY_CACHEDIR=/var/cache/dewy

# 適切なポーリング間隔
--interval 30s

# 構造化ログでモニタリング
--log-format json

開発環境での軽量設定

# プロジェクトディレクトリでの実行
cd /path/to/myproject
dewy server --registry ghr://owner/repo \
  --interval 5s \
  --log-format text -- ./current/myapp

高可用性構成での戦略

複数のDewyインスタンスを同じS3/GCS bucketに向けることで、artifactキャッシュを共有できます：

# AWS S3（endpoint optionでS3互換ストレージにも対応）
dewy server --registry ghr://owner/repo \
  --cache s3://ap-northeast-1/dewy-cache/myapp \
  --interval 60 -- /opt/myapp/current/myapp

# Google Cloud Storage
dewy server --registry ghr://owner/repo \
  --cache gs://dewy-cache/myapp \
  --interval 60 -- /opt/myapp/current/myapp

数十〜数百台のインスタンスが同じregistryをpollしても、新しいリリースを最初に検知したインスタンスだけがartifactダウンロードのコストを払い、残りは共有キャッシュから取得します。

関連項目

• アーキテクチャ - Dewyの全体構成とキャッシュの位置づけ
• レジストリ - アーティファクトの取得元設定
• FAQ - キャッシュ関連のよくある質問