mai
/
ponshu-room-lite
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 31 Wiki Activity
ponshu-room-lite/tools/proxy/REDIS_MIGRATION_GUIDE.md

7.9 KiB
Raw Blame History

Synology Proxy Server - Redis永続化移行ガイド

📋 概要

このガイドでは、Synology NAS上のProxy ServerをIn-Memory方式からRedis永続化方式に移行する手順を説明します。

移行の目的

  • 永続化: Dockerコンテナ再起動後もレート制限カウントが維持される
  • Dokploy対応: 将来のDokploy導入時にそのまま移行可能な構成
  • 複数アプリ対応: ダッシュボードWebシステム等、他プロジェクトでもRedisを共有可能

🛠️ 前提条件

  • Synology NAS（Container Manager インストール済み）
  • 既存のProxy Serverコンテナが稼働中（ponshu-proxy-server）
  • SSH接続可能な環境（または File Station経由のファイル操作）

📂 ステップ1: 既存コンテナの停止と削除

1-1. Container Managerで既存コンテナを停止

  1. Synology DSM → Container Manager を開く
  2. コンテナ タブで ponshu-proxy-server を選択
  3. アクション → 停止 をクリック
  4. 停止後、削除 をクリック（イメージは削除しない）

注意: 既存のレート制限カウントは削除されますが、これは移行の性質上避けられません。

📂 ステップ2: 新しいファイルをSynologyに配置

2-1. File Stationでファイルをアップロード

PC上の tools/proxy/ フォルダから、以下のファイルをSynologyの /docker/ponshu_proxy/ にアップロードします。

アップロード対象:

  • docker-compose.yml ← 新規追加
  • server.js ← 更新版
  • package.json ← 更新版（Redis依存追加）
  • Dockerfile ← 変更なし
  • .env ← 新規作成（次ステップ）

2-2. .env ファイルを作成

File Stationで /docker/ponshu_proxy/.env を新規作成し、以下の内容を記述します。

# Gemini API Key
GEMINI_API_KEY=AIzaSy...（あなたのAPIキー）

# Proxy認証トークン（必須推奨）
PROXY_AUTH_TOKEN=your-secure-token-here

# 1日あたりの解析回数上限
DAILY_LIMIT=50

# Redis接続設定（Docker Compose使用時はデフォルトでOK）
REDIS_HOST=redis
REDIS_PORT=6379

セキュリティ注意:

  • .env ファイルはGit管理しないこと（.gitignore に追加済み）
  • PROXY_AUTH_TOKEN は推測困難な長いランダム文字列を使用

📂 ステップ3: Docker Composeでコンテナ起動

3-1. SSH接続でSynologyにログイン

ssh admin@100.76.7.3

3-2. プロジェクトディレクトリに移動

cd /volume1/docker/ponshu_proxy

3-3. Docker Composeで起動

sudo docker-compose up -d

実行内容:

  • ponshu-redis: Redisコンテナを起動（ポート6379、永続化有効）
  • ponshu-proxy-server: Proxy Serverコンテナを起動（ポート8080、Redis接続）

3-4. 起動確認

sudo docker-compose ps

期待される出力:

NAME                   IMAGE                     STATUS
ponshu-redis           redis:7-alpine            Up (healthy)
ponshu-proxy-server    ponshu_proxy-proxy        Up (healthy)

✅ ステップ4: 動作確認

4-1. ヘルスチェック

curl http://100.76.7.3:8080/health

期待される出力: OK

4-2. Redis接続確認

# Redisコンテナに接続
sudo docker exec -it ponshu-redis redis-cli

# Redis内でコマンド実行
127.0.0.1:6379> PING
PONG

127.0.0.1:6379> KEYS *
(empty array)  # 初回起動時は空

127.0.0.1:6379> exit

4-3. レート制限テスト（Flutter アプリから実行）

Flutter アプリ（lib/secrets.local.dart）で以下を設定:

static const String aiProxyAnalyzeUrl = 'http://100.76.7.3:8080/analyze';
static const bool useProxy = true;
static const String proxyAuthToken = 'your-secure-token-here'; // .envと同じ値

アプリから日本酒ラベル解析を実行し、成功することを確認。

4-4. Redis内のデータ確認

sudo docker exec -it ponshu-redis redis-cli

# 使用状況を確認（device_idは実際のデバイスIDに置き換え）
127.0.0.1:6379> KEYS usage:*
1) "usage:device-123:2026-02-21"

127.0.0.1:6379> GET "usage:device-123:2026-02-21"
"1"  # 1回解析済み

127.0.0.1:6379> TTL "usage:device-123:2026-02-21"
(integer) 43200  # 残り12時間（秒単位）

重要: TTL（有効期限）が設定されていることを確認してください。これにより、翌日0時以降に自動的にリセットされます。

🔄 ステップ5: コンテナ再起動テスト（永続化確認）

5-1. コンテナ再起動

sudo docker-compose restart

5-2. 再起動後のデータ確認

sudo docker exec -it ponshu-redis redis-cli

127.0.0.1:6379> GET "usage:device-123:2026-02-21"
"1"  # 再起動前のカウントが維持されている

成功条件: 再起動後もカウントが保持されていること。

📊 運用上の注意点

ログの確認方法

# Proxy Serverのログ
sudo docker-compose logs -f proxy

# Redisのログ
sudo docker-compose logs -f redis

コンテナの停止・削除

# 停止（データは保持）
sudo docker-compose stop

# 完全削除（データも削除される）
sudo docker-compose down -v

警告: docker-compose down -v を実行すると、Redisのデータボリュームも削除されます。

Redis データのバックアップ

# Redisのデータをダンプ
sudo docker exec ponshu-redis redis-cli SAVE

# ダンプファイルをコピー
sudo docker cp ponshu-redis:/data/dump.rdb /volume1/backups/redis-backup-$(date +%Y%m%d).rdb

🚀 Dokploy移行への準備

この構成はDokploy環境にそのまま移行可能です。

Dokploy移行時の変更点

  1. Gitea連携: Gitea pushで自動デプロイ
  2. 環境変数管理: .env ファイルの代わりにDokployのWeb UIで設定
  3. ドメイン設定: ponshu-proxy.local 等のカスタムドメイン自動割り当て
  4. スケーリング: Docker Swarmで複数ノードに分散可能

移行時期: Week 2（日本酒アプリとダッシュボードを同時にDokployへ移行）

🆘 トラブルシューティング

Q1: Proxy Serverが起動しない（Redis connection failed）

原因: Redisコンテナが起動していない、またはネットワーク設定が誤っている。

解決策:

# Redisの状態確認
sudo docker-compose ps

# Redisが "unhealthy" の場合、ログを確認
sudo docker-compose logs redis

Q2: docker-compose コマンドが見つからない

原因: Synology DSMのバージョンによっては docker compose（スペース）を使用。

解決策:

sudo docker compose up -d  # ハイフンなし

Q3: Flutter アプリから接続できない（認証エラー）

原因: PROXY_AUTH_TOKEN が .env と secrets.local.dart で一致していない。

解決策:

  1. .env の PROXY_AUTH_TOKEN を確認
  2. Flutter の lib/secrets.local.dart の proxyAuthToken を同じ値に設定
  3. Flutter アプリを再起動

✅ 完了チェックリスト

  • 既存コンテナを停止・削除
  • 新しいファイル（docker-compose.yml, 更新版 server.js, package.json）をアップロード
  • .env ファイルを作成（APIキー、認証トークン設定）
  • docker-compose up -d で起動成功
  • curl http://100.76.7.3:8080/health で OK 返却
  • Redis内でデータが保存されることを確認（KEYS usage:*）
  • コンテナ再起動後もデータが維持されることを確認
  • Flutter アプリから解析が成功することを確認

移行完了後は、この手順書を docs/ フォルダに移動してアーカイブしてください。