# Alexa Cookie更新 GUI 運用ドキュメント

> 最終更新: 2026-04-04
> 対象: `/home/akira/develop/windmill_workflow/alexa-api`
> 目的: Alexa Cookie の更新を、ローカル GUI と権限制限付きのサーバー反映で安全に運用する

---

## 1. 何を作ったか

Alexa Cookie の更新作業を、手作業のコマンド列ではなく GUI 中心で進められるようにした。

今回追加・変更したもの:

| ファイル | 役割 |
|---------|------|
| `alexa-api/auth4-core.js` | Amazon 認証と Cookie 取得の共通ロジック |
| `alexa-api/auth4.js` | CLI 版の Cookie 更新ツール。`auth4-core.js` を利用 |
| `alexa-api/auth4-web.js` | ローカルで起動する GUI。Cookie 更新とサーバー反映を行う |
| `alexa-api/alexa-cookie-deploy.sh` | サーバー側の専用反映スクリプト。`/tmp/alexa-api.env` を本番 `.env` に反映し、`docker compose restart` を実行 |
| `alexa-api/alexa-cookie-deploy.sudoers` | `akira` から専用反映スクリプトだけを `sudo` 実行できるようにする sudoers 設定例 |
| `flows/hourly_chime.flow.json` | LINE 通知文面を GUI 手順に合わせて更新 |

この構成にした理由:

- `akira` に広い `sudo` 権限や `windmill` への自由な切り替え権限を与えたくない
- それでも Cookie 更新だけは迷わず再実行できるようにしたい
- そのため「GUI から呼べる専用コマンドだけを sudoers で許可する」構成にした

---

## 2. 全体の流れ

通常運用の流れは以下の通り。

1. ローカルで GUI を起動する
2. ブラウザで Amazon のメールアドレスとパスワードを入力する
3. `alexa-api/.env` の `ALEXA_COOKIE` を更新する
4. GUI からサーバーへ `/tmp/alexa-api.env` を転送する
5. GUI から `sudo /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env` を実行する
6. サーバー側で `.env` 反映と `alexa_api` コンテナ再起動が行われる

---

## 3. 初回セットアップ

このセットアップはサーバーで一度だけ必要。

### 3-1. 専用スクリプトを配置

```bash
scp /home/akira/develop/windmill_workflow/alexa-api/alexa-cookie-deploy.sh keinafarm:/tmp/alexa-cookie-deploy.sh
ssh keinafarm 'sudo install -m 755 /tmp/alexa-cookie-deploy.sh /usr/local/bin/alexa-cookie-deploy.sh'
```

### 3-2. sudoers を配置

```bash
scp /home/akira/develop/windmill_workflow/alexa-api/alexa-cookie-deploy.sudoers keinafarm:/tmp/alexa-cookie-deploy.sudoers
ssh keinafarm 'sudo install -m 440 /tmp/alexa-cookie-deploy.sudoers /etc/sudoers.d/alexa-cookie-deploy'
```

### 3-3. 何が許可されるか

`alexa-cookie-deploy.sudoers` の内容:

```sudoers
akira ALL=(root) NOPASSWD: /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env
```

許可しているのはこれだけ:

- `akira` が root として `/usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env` を実行すること

許可していないもの:

- `windmill` への自由な `su`
- 任意コマンドの `sudo`
- 任意パスへのコピーや任意の Docker 操作

---

## 4. ふだんの使い方

### 4-1. GUI を起動

```bash
cd /home/akira/develop/windmill_workflow/alexa-api
npm run auth:web
```

ブラウザで次を開く:

```text
http://127.0.0.1:3678
```

### 4-2. Cookie を更新

画面上部の「Alexa Cookie 更新」で次を入力する。

- Amazon メールアドレス
- Amazon パスワード

「Cookie を更新する」を押すと、成功時は `alexa-api/.env` が更新される。

### 4-3. サーバーへ反映

画面下部の「サーバー反映」で次を確認する。

- SSH 接続先: `keinafarm`
- リモート一時アップロード先: `/tmp/alexa-api.env`
- 実行する専用コマンド: `sudo /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env`

「サーバーへ反映する」を押すと、内部では次を実行する。

```bash
scp /home/akira/develop/windmill_workflow/alexa-api/.env keinafarm:/tmp/alexa-api.env
ssh keinafarm 'sudo /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env'
```

成功時はログに以下のように表示される。

```text
alexa cookie deployed
Container alexa_api  Restarting
Container alexa_api  Started
反映完了
```

---

## 5. 各ファイルの使い分け

### `auth4-web.js`

通常はこちらを使う。人が毎回コマンドを思い出さなくてよい。

### `auth4.js`

CLI で直接更新したい時のために残してある。基本運用は GUI を推奨。

例:

```bash
cd /home/akira/develop/windmill_workflow/alexa-api
AMAZON_EMAIL="xxx" AMAZON_PASSWORD="xxx" node auth4.js
```

### `auth4-core.js`

直接実行するものではない。CLI 版と GUI 版の共通認証ロジック。

### `alexa-cookie-deploy.sh`

サーバー側で root として動く専用スクリプト。役割は次の3つ。

1. `/tmp/alexa-api.env` に `ALEXA_COOKIE=` があるか確認
2. `/home/claude/alexa-api/.env` を更新
3. `docker compose --env-file /home/claude/alexa-api/.env -f /home/claude/alexa-api/docker-compose.yml restart` を実行

---

## 6. LINE 通知との関係

`flows/hourly_chime.flow.json` の失敗時通知は、この GUI 運用に合わせて更新済み。

通知では次の導線を案内する。

1. `npm run auth:web`
2. `http://127.0.0.1:3678` を開く
3. GUI 上でサーバー反映まで実行する

これにより「あとでどう直すのか分からない」状態になりにくくしている。

---

## 7. トラブルシュート

### `Could not resolve hostname ...`

SSH 接続先の別名が `~/.ssh/config` に存在しない。

今回の環境では使える別名は `keinafarm`。

### `Permission denied` で `/home/claude/alexa-api/.env` に書けない

`scp` で直接 `/home/claude/alexa-api/.env` へ置こうとすると起きる。  
現在は `/tmp/alexa-api.env` に送ってから、専用スクリプトで反映する設計に変更済み。

### `stat /home/claude/alexa-api/.env: permission denied`

旧版の専用スクリプトで、権限不足のユーザーに切り替えて `docker compose` を実行していた時の症状。  
現在の `alexa-cookie-deploy.sh` は root のまま `.env` 反映と再起動を完了する。

### CAPTCHA や MFA が出る

Amazon 側で追加認証が必要。GUI のログに失敗理由が出る。  
この場合は一発で通らない可能性がある。

---

## 8. 関連ファイル

- `docs/30_マスタードキュメント_Alexa_TTS_API編.md`
- `alexa-api/auth4-web.js`
- `alexa-api/auth4.js`
- `alexa-api/auth4-core.js`
- `alexa-api/alexa-cookie-deploy.sh`
- `alexa-api/alexa-cookie-deploy.sudoers`
- `flows/hourly_chime.flow.json`