ponshu-room-lite/tools/proxy/REDIS_MIGRATION_GUIDE.md

# 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` を新規作成し、以下の内容を記述します。

```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にログイン

```bash
ssh admin@100.76.7.3
```

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

```bash
cd /volume1/docker/ponshu_proxy
```

### 3-3. Docker Composeで起動

```bash
sudo docker-compose up -d
```

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

### 3-4. 起動確認

```bash
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. ヘルスチェック

```bash
curl http://100.76.7.3:8080/health
```

**期待される出力**: `OK`

### 4-2. Redis接続確認

```bash
# 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`）で以下を設定:

```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内のデータ確認

```bash
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. コンテナ再起動

```bash
sudo docker-compose restart
```

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

```bash
sudo docker exec -it ponshu-redis redis-cli

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

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

---

## 📊 運用上の注意点

### ログの確認方法

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

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

### コンテナの停止・削除

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

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

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

### Redis データのバックアップ

```bash
# 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コンテナが起動していない、またはネットワーク設定が誤っている。

**解決策**:
```bash
# Redisの状態確認
sudo docker-compose ps

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

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

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

**解決策**:
```bash
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/` フォルダに移動してアーカイブしてください。**