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

# Ponshu Room Proxy Server (Redis永続化対応)

Gemini APIキーを隠蔽し、デバイスごとの利用制限（レート制限）を管理するプロキシサーバー。

## 🎯 機能

- **APIキー保護**: クライアントアプリにAPIキーを含めず、プロキシサーバーのみが保持
- **レート制限**: デバイスIDごとに1日あたりのリクエスト数を制限
- **Redis永続化**: Dockerコンテナ再起動後もカウントを維持
- **認証**: Bearer Token認証（オプション）
- **Dokploy対応**: 将来のDokploy移行に対応した構成

---

## 🚀 クイックスタート（Synology NAS）

### 1. 環境変数ファイル作成

```bash
cp .env.example .env
```

`.env` を編集してAPIキーと認証トークンを設定:

```env
GEMINI_API_KEY=AIzaSy...（あなたのAPIキー）
PROXY_AUTH_TOKEN=$(openssl rand -hex 32)  # ランダム生成推奨
DAILY_LIMIT=50
```

### 2. Docker Composeで起動

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

### 3. 動作確認

```bash
curl http://localhost:8080/health
# 期待される出力: OK
```

---

## 📊 Redis データ確認

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

# 使用状況確認
KEYS usage:*
GET "usage:device-123:2026-02-21"
TTL "usage:device-123:2026-02-21"
```

---

## 🔄 運用コマンド

```bash
# ログ確認
docker-compose logs -f proxy

# 再起動
docker-compose restart

# 停止
docker-compose stop

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

---

## 📚 ドキュメント

- **移行ガイド**: [REDIS_MIGRATION_GUIDE.md](REDIS_MIGRATION_GUIDE.md) - In-MemoryからRedis永続化への移行手順
- **セットアップガイド**: [../../docs/SYNOLOGY_PROXY_SETUP.md](../../docs/SYNOLOGY_PROXY_SETUP.md) - 初回構築手順（旧版・参考用）

---

## 🏗️ アーキテクチャ

```
Flutter App (Client)
    ↓ HTTP POST /analyze
    ↓ Authorization: Bearer <token>
Proxy Server (Node.js/Express)
    ↓ Rate Limit Check (Redis)
    ↓ Gemini API Call
Gemini 2.5 Flash API
```

---

## 🔐 セキュリティ

- `.env` ファイルは **Git管理しない**（`.gitignore`に追加済み）
- `PROXY_AUTH_TOKEN` は **長いランダム文字列** を使用
- 外部公開する場合は **リバースプロキシ + HTTPS** 推奨

---

## 📝 環境変数

| 変数名 | 説明 | デフォルト |
|--------|------|-----------|
| `GEMINI_API_KEY` | Gemini APIキー（必須） | なし |
| `PROXY_AUTH_TOKEN` | Bearer Token認証（推奨） | なし（認証無効） |
| `DAILY_LIMIT` | 1日あたりのリクエスト上限 | 50 |
| `REDIS_HOST` | Redisホスト名 | `redis` |
| `REDIS_PORT` | Redisポート | `6379` |
| `PORT` | Proxy Serverポート | `8080` |

---

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

### Q: `Redis connection failed`

**解決策**: Redisコンテナが起動していることを確認

```bash
docker-compose ps
# ponshu-redis が "Up (healthy)" になっているか確認
```

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

**解決策**:
1. `.env` の `PROXY_AUTH_TOKEN` を確認
2. Flutter の `lib/secrets.local.dart` で同じトークンを設定
3. Synology NASのIPアドレス（`100.76.7.3`）が正しいか確認

---

**Last Updated**: 2026-02-21