API 設計 — みーきゅんクラウド (FastAPI)
// API DESIGN — 最終更新: 2026-05-14 / maguro Docker (mikyun-portal:1.1) 稼働中
運用中 Basic API群 (顧客 / 管理 / VPN Engine) 未実装 一部のNC連携API
API 全体構造
顧客 (iPhone / WireGuard 接続中)
↓ https://cloud.k2-o.net/client or https://admin.wan-secure.net/ui
↓
maguro nginx (vhost: cloud.k2-o.net / admin.wan-secure.net)
↓ proxy_pass
↓
Docker mikyun-portal:1.1 (FastAPI :9000)
├─ /client/* 顧客ポータルUI app/client/client_ui.py
├─ /ui/* 管理者UI app/ui_admin.py
└─ HTTP 内部呼出
↓
同コンテナ内 FastAPI :9081 (mikyun_vpn_engine.py)
├─ MariaDB Docker (compose-db-1) : mikyun_cloud
├─ WireGuard host (wg-clients / customers / storage)
└─ QR / conf ファイル生成 → /opt/mikyun/output/
変更点 (2026-05-14): 旧 R640 ホスト直の
mikyun-cloud.service + mikyun-vpn-engine.service から、 maguro Docker (mikyun-portal:1.1) の1コンテナ2ポート構成へ移行。 ホスト側 WG は維持し、 Docker から wg syncconf 等を実行できるよう NET_ADMIN + /etc/wireguard bind mount している。
実装ファイル (maguro / Docker内)
| ファイル (コンテナ内パス) | 役割 | ポート |
|---|---|---|
/app/main.py | FastAPI エントリ + Basic認証ミドルウェア + router include | 9000 |
/app/client/client_ui.py | 顧客向けポータルUI (/client) | 9000 |
/app/ui_admin.py | 管理者向けUI (/ui) | 9000 |
/app/api_users.py | /api/users (Basic認証必須) | 9000 |
/app/mikyun_vpn_engine.py | VPN Engine (契約作成 / IP採番 / WGピア管理 / conf+QR生成) | 9081 |
/app/billing/billing_daily.py | ポイント課金月次バッチ (2026-04-10〜) | — |
ホスト側 bind: /opt/mikyun-portal/ → /app/、 /etc/wireguard/ → /etc/wireguard/ (rw)、 /opt/mikyun/output/ → 同名
顧客向け API (/client)
| Method | Path | 用途 |
|---|---|---|
| GET | /client | ログイン画面 (親端末IP自動認識) |
| POST | /client/login | identity_passphrase 認証 |
| GET | /client/devices/{contract_id} | 端末一覧 + 課金カード |
| POST | /client/add-device/{contract_id} | 子端末追加 |
| POST | /client/pause/{device_id} | 端末一時停止 |
| POST | /client/resume/{device_id} | 停止解除 |
| POST | /client/promote/{device_id} | 子→親 昇格 |
| POST | /client/delete/{device_id} | 子端末削除 (親へ10GB返却) |
| GET | /client/qr/{contract_id}/{device_id} | QR表示 (24h有効を警告) |
| GET | /client/conf/{device_id} | .conf ダウンロード |
管理者 API (/ui)
| Method | Path | 用途 |
|---|---|---|
| GET | /ui/contracts | 契約一覧 (使用量GB列含む) |
| GET / POST | /ui/contracts/new | 新規契約 + 親端末初回発行 |
| GET | /ui/contracts/{contract_id} | 契約詳細 |
| POST | /ui/contracts/{contract_id}/add-child | 子端末追加 |
| POST | /ui/contracts/{contract_id}/promote-parent | 親端末昇格 |
| POST | /ui/contracts/{contract_id}/terminate | 契約解除 (peer削除 + NC完全削除) |
| POST | /ui/devices/{device_id}/pause|resume | 端末停止/復帰 (iptables DROP) |
| GET | /ui/devices/{device_id}/qr|conf | QR / conf 取得 |
| GET | /ui/contracts/{contract_id}/parent-qr | 親端末QR取得 |
| GET | /ui/traffic | トラフィック監視 |
| GET / POST | /ui/notes | 顧客メモ追加/一覧 |
| GET | /ui/billing | 入金管理 (ポイント残高 / warning / suspended) — 2026-04-10〜 |
| GET | /ui/health | 運用ヘルス確認 |
内部 VPN Engine API (:9081)
同一コンテナ内で動作。 顧客ポータル/管理UIから HTTP で呼ぶ。 外部からのアクセスは無し (127.0.0.1 binding)。
| Method | Path | 用途 |
|---|---|---|
| GET | /health | 生存確認 |
| POST | /contracts/create | 契約作成 + 親端末発行 + WGピア + QR + NCユーザー |
| GET | /contracts/list | 契約一覧 |
| GET | /contracts/{contract_id} | 契約詳細 (Basic認証必須、 nc_password 含む) |
| GET | /contracts/{contract_id}/devices | 端末一覧 |
| POST | /devices/add-child | 子端末追加 (IP採番 + ピア追加 + NC任意) |
| POST | /devices/pause | iptables DROP + status=paused |
| POST | /devices/resume | DROP削除 + status=active |
| POST | /devices/promote-parent | 子→親 昇格 (旧親はchild降格) |
| POST | /devices/delete | peer 除去 + wg syncconf + 論理削除 |
| GET | /check-username/{username} | NCユーザー名 使用可否チェック |
IP 採番ロジック
# wg-clients (10.200.0.0/16) を主に使用。 旧 wg0/wg1 (R640) は退役済。 # customer_devices の使用中IP (revoked/expired 以外) を全件取得 # wg-clients サブネットの空き最小番号を割り当て # 予約: 10.200.0.1 (GW)、 10.200.0.254 (内部DNS dnsmasq) # DB 制約: customer_devices.wg_ip UNIQUE で二重防御 # 旧 10.251.0.0/24 (shared subnet) は段階的に 10.200.0.0/16 に統合中 # 業務向け wg-customers (UDP 61001) / wg-storage (UDP 62001) は別サブネット帯
ポイント課金 API (2026-04-10〜)
サブスク廃止 → ポイントプリペイド方式 (1pt=1円) に全面移行済。 詳細は 決済ページ関連 参照。
| Method | Path | 用途 |
|---|---|---|
| POST | /api/points/verify | 契約認証 + 残高返却 (passphrase / 認証なし枠) |
| POST | /api/points/charge | ポイント加算 (Basic認証 / WordPress→maguro) |
| POST | /api/points/adjust | 手動ポイント加減算 |
| GET | /ui/contracts/{id}/billing | 課金情報 + 履歴 |
| POST | /api/billing/init | 課金初期化 (月額自動計算 + next_payment_at設定) |
WireGuard AllowedIPs 設定変更 (2026-04-06)
顧客VPN設定を フルトンネルからスプリットトンネルに変更 した記録。 現在もこの設定。
| 項目 | 旧 | 現行 |
|---|---|---|
| AllowedIPs | 0.0.0.0/0 (全通信VPN) | 10.200.0.0/16 (VPN内部のみ) |
| 5G接続時の挙動 | 5G最適化が効かず iPhone 発熱・電池消耗激しい | 5G最適化が有効 → 電池消耗改善 |
# 変更箇所 (maguro Docker内) /app/mikyun_vpn_engine.py 337行目付近 # 変更前 "AllowedIPs = 0.0.0.0/0\n" # 変更後 "AllowedIPs = 10.200.0.0/16\n" # バックアップ /opt/mikyun-portal/mikyun_vpn_engine.py.backup.split-tunnel-20260406-215731
既存顧客の取扱: 新規発行は自動でスプリットトンネル。 旧
0.0.0.0/0 の発行済 conf は (a) ポータルから再発行、 または (b) 顧客側で手動変更を案内。 管理用 /root/mikyun-cloud/keys/iphone_admin.conf は元々 10.0.0.0/8 で運用。
将来の Nextcloud 連携 API (未実装)
| Method | Path | 用途 |
|---|---|---|
| POST | /internal/nextcloud/users | 契約作成時にNCユーザー作成 (ID/PW/容量割当) — 現状は occ user:add 直叩き |
| PATCH | /internal/nextcloud/users/{contract_id}/quota | 容量同期 (DB ⇔ NC) |
| GET | /internal/nextcloud/users/{contract_id}/usage | 使用量取得 (現状は collect_file_count.py でDBへ書込) |
| POST | /internal/nextcloud/users/{contract_id}/disable | 停止・凍結 (現状は occ user:disable) |
API と DB の対応
| テーブル | 関わる主API |
|---|---|
contracts | /contracts/create, list, detail, terminate |
customer_devices | 端末追加/停止/復帰/昇格/失効/QR再発行 |
admin_logs | 全管理操作の監査ログ |
point_transactions | /api/points/charge, /api/points/adjust, billing_daily |
実装優先順位 (現状)
| # | 機能 | 状態 |
|---|---|---|
| 1 | 契約一覧 / 詳細 / 端末一覧 | 完了 |
| 2 | 子端末追加 | 完了 |
| 3 | pause / resume | 完了 |
| 4 | QR再取得 | 完了 |
| 5 | 親端末昇格 / revoke | 完了 |
| 6 | ポイント課金 / 月次バッチ | 完了 (2026-04-10) |
| 7 | 使用量自動集計 (cron 1h) | 完了 |
| 8 | Nextcloud連携API (内部抽象化) | 未実装 (occ直叩き) |
| 9 | NCパスワード Fernet 暗号化 + Argon2 | 計画中 |
2026-05-14 時点: maguro Docker (
mikyun-portal:1.1) で全エンドポイント稼働中。 旧 R640 ホスト直サービスは退役、 ソースも消去済。 メンテは maguro /opt/mikyun-portal/ 一本化。