ponshu-room-lite/tools/synology/DEPLOYMENT_GUIDE.md

# Synology AI Proxy Server デプロイガイド

## 📋 前提条件

- ✅ Synology NASにDockerがインストールされている
- ✅ Container Managerでgitea環境が稼働している
- ✅ 新しいGoogle AI StudioプロジェクトでAPIキーを取得済み

---

## 🚀 デプロイ手順

### ステップ1: ファイルをSynologyにアップロード

#### 方法A: File Station（推奨・簡単）

1. **Synology DSMにログイン**
   - ブラウザで `http://[SynologyのIP]:5000` にアクセス

2. **File Stationを開く**
   - メインメニュー → File Station

3. **プロジェクトフォルダに移動**
   - `/docker/ponshu-ai-factory/` に移動
   - （もしフォルダ名が違う場合は、Giteaのdocker-compose.ymlがある場所）

4. **新しいファイルをアップロード**
   - `ai-proxy` フォルダを作成
   - 以下のファイルをアップロード：
     - `server.py`
     - `requirements.txt`
     - `README.md`

5. **docker-compose.ymlを更新**
   - 既存の `docker-compose.yml` を新しいバージョンで上書き

6. **.envファイルを作成**
   - `.env.example` を `.env` にコピー
   - `.env` を編集して、`YOUR_GEMINI_API_KEY_HERE` を実際のAPIキーに置き換え

#### 方法B: Git（上級者向け）

```bash
# PCのターミナルから
cd c:\Users\maita\posimai-project\ponshu_room_lite\tools\synology

# Giteaにpush（既にリポジトリがある場合）
git add .
git commit -m "feat: Add AI Proxy Server with rate limiting"
git push origin main

# SynologyにSSH接続
ssh maita@[SynologyのIP]

# プロジェクトフォルダに移動
cd /volume1/docker/ponshu-ai-factory

# Giteaからpull
git pull origin main

# .envファイルを作成
cp .env.example .env
nano .env  # APIキーを設定
```

---

### ステップ2: APIキーの設定

1. **Google AI Studioで新しいプロジェクトを作成**
   - https://aistudio.google.com/ にアクセス
   - 新しいプロジェクトを作成（**Early Accessでない通常プロジェクト**）
   - "Get API key" → "Create API key in new project"
   - APIキーをコピー

2. **Synologyの.envファイルに設定**
   - File Stationで `/docker/ponshu-ai-factory/.env` を編集
   - `GEMINI_API_KEY=実際のAPIキー` に変更
   - 保存

---

### ステップ3: Dockerコンテナを起動

#### Container Managerを使う場合（推奨）

1. **Container Managerを開く**
   - DSMメインメニュー → Container Manager

2. **プロジェクトを停止**
   - 「プロジェクト」タブ
   - 既存の `ponshu-ai-factory` プロジェクトを選択
   - 「停止」をクリック

3. **プロジェクトを再構築**
   - 「アクション」→「ビルド」をクリック
   - 数分待つ（Pythonの依存関係をインストール中）

4. **プロジェクトを起動**
   - 「起動」をクリック

5. **コンテナの状態を確認**
   - 「コンテナ」タブ
   - `ai_proxy` コンテナが「実行中」になっているか確認
   - ログを確認（「ログ」ボタン）して `🚀 AI Proxy Server started` が出ていればOK

#### SSHを使う場合（上級者向け）

```bash
# Synologyにログイン
ssh maita@[SynologyのIP]

# プロジェクトフォルダに移動
cd /volume1/docker/ponshu-ai-factory

# 既存のコンテナを停止
docker-compose down

# 新しいコンテナを起動
docker-compose up -d

# ログを確認
docker logs ai_proxy

# 正常に起動していれば以下が表示される:
# 🚀 AI Proxy Server started
#    Model: gemini-1.5-flash
#    Rate Limit: 10 requests/day
```

---

### ステップ4: 動作確認

#### ブラウザでヘルスチェック

```
http://[SynologyのIP]:8080/health
```

**期待されるレスポンス:**
```json
{
  "status": "healthy",
  "gemini_api_key_configured": true,
  "rate_limit": 10,
  "model": "gemini-1.5-flash"
}
```

---

## 🔧 トラブルシューティング

### コンテナが起動しない

**原因1: .envファイルが見つからない**
- `.env.example` を `.env` にコピーしたか確認
- `.env` に正しいAPIキーが設定されているか確認

**原因2: ポート8080が既に使われている**
```bash
# ポート使用状況を確認
netstat -tuln | grep 8080

# 他のアプリが使っている場合は、docker-compose.ymlのポートを変更
# ports:
#   - "8081:8080"  # 外部8081 → コンテナ内8080
```

**原因3: Pythonの依存関係インストールに失敗**
```bash
# コンテナ内に入ってログ確認
docker exec -it ai_proxy bash
pip install -r requirements.txt
python server.py
```

### APIキーが認識されない

```bash
# 環境変数を確認
docker exec ai_proxy printenv | grep GEMINI

# GEMINI_API_KEY が空の場合は .env ファイルを確認
```

### アプリから接続できない

1. **ネットワーク確認**
   - Synologyとスマホが同じネットワークにいるか
   - ファイアウォールで8080ポートが開いているか

2. **IPアドレス確認**
   ```bash
   # SynologyのIPを確認
   ifconfig | grep inet
   ```

3. **アプリ側のURLを確認**
   - `http://192.168.1.xxx:8080/analyze` のようになっているか
   - `https://` ではなく `http://` を使用

---

## 📊 使用状況の確認

### 特定デバイスの使用状況を確認

```bash
# デバイスIDを取得（アプリのログから）
DEVICE_ID="a1b2c3d4..."  # SHA256ハッシュ

# ブラウザまたはcurlで確認
curl http://[SynologyのIP]:8080/usage/${DEVICE_ID}
```

### 全デバイスの使用状況を確認

```bash
# Synologyにログイン
ssh maita@[SynologyのIP]

# 使用状況ファイルを確認
cat /volume1/docker/ponshu-ai-factory/ai-proxy-data/usage.json
```

**データ形式:**
```json
{
  "a1b2c3d4e5f6...": {
    "2026-01-15": 3,
    "2026-01-14": 7
  },
  "f6e5d4c3b2a1...": {
    "2026-01-15": 10
  }
}
```

---

## 🔐 セキュリティのベストプラクティス

1. **APIキーを絶対にGitにコミットしない**
   - `.env` ファイルは `.gitignore` に追加済み
   - 万が一コミットした場合は即座にAPIキーを再発行

2. **定期的にログをチェック**
   ```bash
   docker logs ai_proxy | tail -50
   ```

3. **不正アクセスの監視**
   - `usage.json` で異常な使用パターンを確認
   - 知らないデバイスIDが大量に出ている場合は要調査

4. **ファイアウォール設定**
   - Synology DSM → コントロールパネル → セキュリティ → ファイアウォール
   - ポート8080はローカルネットワークのみ許可（外部には開放しない）

---

## 📈 次のステップ

1. **アプリ側の実装**
   - `lib/services/gemini_service.dart` をプロキシサーバー経由に変更
   - デバイスID認証の実装

2. **Pro版の準備**
   - `RATE_LIMIT_PER_DAY=999999` で無制限に変更
   - 決済システムと連携

3. **モニタリング**
   - Grafanaなどで使用状況をダッシュボード化
   - アラート設定（異常なリクエスト数など）

---

## 💡 よくある質問

**Q: 1日10回の制限はいつリセットされますか？**
A: 日本時間の0時（サーバー時刻基準）にリセットされます。

**Q: 複数のアプリバージョン（開発版/本番版）で使えますか？**
A: はい。デバイスIDが同じであれば共通のカウントになります。別々にしたい場合は、環境ごとにプロキシサーバーを分けてください。

**Q: Gemini APIのコストは誰が負担しますか？**
A: プロキシサーバーの管理者（あなた）が負担します。gemini-1.5-flashは1日1,500回まで無料なので、10ユーザー×10回/日=100回/日であれば無料枠内です。

**Q: レート制限を超えたらどうなりますか？**
A: アプリに「本日の解析上限に達しました。明日またお試しください」というメッセージが表示されます。サーバーはエラーを返しません。

---

## 🎉 完成！

これでAI Proxyサーバーの構築は完了です。次はアプリ側の実装に進みましょう！