# ai-disk-gateway

`https://ai.disk.mydns.jp` で公開する LLM ゲートウェイ。
内部の OpenAI 準拠 llama-server を無改変で中継しつつ、APIキーごとのレート制限と
利用可能モデルの制御、キー発行の管理画面を提供する。

## 構成

| モジュール | リポジトリ | ポート |
|-----------|-----------|-------|
| gateway | https://github.com/dmajima/llm-gateway-proxy | 3000 公開 / 3001 control（コンテナ内部のみ） |
| admin | https://github.com/dmajima/llm-gateway-admin | 4000 |

```mermaid
flowchart TB
    C["外部クライアント"] -->|"HTTPS + 発行キー"| AP["Apache 443"]
    AP -->|"/admin/*"| ADM["admin"]
    AP -->|"/* (catch-all)"| GW["gateway"]
    ADM -->|"control API"| GW
    GW -->|"内部キーに差し替え<br/>本文はバイト列のまま"| UP["llama-server<br/>192.168.0.13"]
```

## セットアップ

### 前提

- Ubuntu 系のホスト。sudo がパスワードなしで通ること
- Apache2 が稼働し、対象ドメインの DNS がこのホストへ向いていること
- certbot が導入済みであること
- Docker は未導入でよい。`deploy.sh` が導入する

### 手順

```bash
git clone --recurse-submodules https://github.com/dmajima/ai-disk-gateway.git
cd ai-disk-gateway
cp .env.example .env
```

`.env` に次を設定する。

| 変数 | 内容 |
|---|---|
| `UPSTREAM_API_KEY` | 上流 llama-server の内部キー |
| `CERTBOT_EMAIL` | 証明書の連絡先 |
| `ADMIN_PASSWORD_HASH` | 管理者パスワードの Argon2 ハッシュ |
| `ADMIN_ALLOW_FROM` | 管理画面への接続元制限。空だと全世界へ開放される |

`ADMIN_PASSWORD_HASH` の作り方は `admin/README.md` を参照。

```bash
bash deploy.sh
```

Docker 導入、コンテナ起動、Apache 設定、証明書取得、定期ジョブ設定、疎通確認までを
冪等に実行する。失敗時は Apache の設定を元へ戻す。

## 運用

```bash
# 再デプロイ（証明書はそのまま）
bash deploy.sh --skip-cert

# 疎通確認
bash .deploy/healthcheck.sh

# 手動退避
sudo .deploy/backup.sh

# 監視の手動実行
sudo .deploy/monitor.sh

# 証明書更新の検証
sudo certbot renew --dry-run
```

退避は毎日 4 時 15 分、監視は 10 分ごとに systemd タイマーで自動実行される。
退避先は `/var/backups/ai-disk-gateway/` で、14 日分を保持する。

### 切り戻し

不良リリースを戻す場合はサブモジュール参照を 1 つ前へ戻して再構築する。

```bash
cd gateway && git checkout <前のコミット> && cd ..
git add gateway && git commit -m "chore: gateway を切り戻し"
bash deploy.sh --skip-cert
```

## ドキュメント

| 文書 | 内容 |
|---|---|
| `docs/implementation-plan.md` | 設計の全体像、判断根拠、受入条件 |
| `docs/control-api-contract.md` | gateway と admin の結合点となる API 契約 |
| `CLAUDE.md` | 変更してはならない不変条件を含む開発規約 |

## サブモジュールの扱い

子リポジトリを更新したら、親でも参照を更新してコミットする。

```bash
cd gateway
git add -A && git commit -m "..." && git push
cd ..
git add gateway && git commit -m "chore: gateway のサブモジュール参照を更新"
```