yotta/EmailToDiscord
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/add-agents-webhook-satellite
EmailToDiscord/README.md
T
yotta d906dc05a9
Validate and publish container image / build (pull_request) Successful in 3m24s
Details
Harborプロジェクトをknative-funcに変更
2026-07-18 09:08:04 +09:00

412 lines
13 KiB
Markdown
Raw Permalink Blame History

# Email Notification Forwarder (Discord / Agents Webhook)
メールサーバーを監視し、新しいメールをDiscordへ通知したり、AgentsのWebhookを通じてエージェントを起動したりするPythonアプリケーションです。Discordのみ、Agents Webhookのみ、または両方を同時に利用できます。
## 🚀 機能
- **メールサーバー監視**: IMAP/IMAPS プロトコルでメールサーバーを監視
- **Discord通知**: 新しいメールが到着したときにDiscordに通知
- **Agents Webhook通知**: メール内容をプロンプトとしてAgentsを起動
- **複数通知先**: DiscordとAgents Webhookへの同時送信に対応
- **環境変数設定**: 設定は全て環境変数で管理
- **Dockerサポート**: コンテナとして簡単にデプロイ可能
- **SSL/TLS対応**: セキュアな接続をサポート
- **エラーハンドリング**: 堅牢なエラー処理とログ出力
## 📋 必要な環境変数
| 変数名 | 説明 | 必須 | デフォルト値 |
|--------|------|------|-------------|
| `EMAIL_USER` | メールアドレス | ✅ | - |
| `EMAIL_PASSWORD` | メールパスワード/アプリパスワード | ✅ | - |
| `DISCORD_WEBHOOK_URL` | Discord Webhook URL | 条件付き | - |
| `WEBHOOK_URL` | AgentsのWebhookエンドポイント | 条件付き | - |
| `WEBHOOK_TOKEN` | ユーザー単位で発行されたWebhookトークン | 条件付き | - |
| `DISCORD_CHANNEL_ID` | エージェントの応答先DiscordチャンネルID | 条件付き | - |
| `WEBHOOK_SOURCE` | Agents上で表示するサービス名 | ❌ | `email-monitor` |
| `IMAP_SERVER` | IMAPサーバーアドレス | ❌ | `imap.gmail.com` |
| `IMAP_PORT` | IMAPポート番号 | ❌ | `993` |
| `USE_SSL` | SSL/TLS使用の有無 | ❌ | `true` |
| `MAILBOX` | 監視するメールボックス | ❌ | `INBOX` |
| `CHECK_INTERVAL` | チェック間隔（秒） | ❌ | `60` |
`DISCORD_WEBHOOK_URL`、またはAgents用の `WEBHOOK_URL` / `WEBHOOK_TOKEN` / `DISCORD_CHANNEL_ID` のいずれか一組が必要です。Agents用の3変数は必ずまとめて設定してください。
## 🔧 セットアップ
### 1. Discord Webhook URLの取得（Discordへ直接通知する場合）
1. Discordでメッセージを送信したいチャンネルを選択
2. チャンネル設定 → 連携サービス → ウェブフック
3. 新しいウェブフックを作成してURLをコピー
### 2. Agents Webhookの設定（Agentsを起動する場合）
Agentsの会話コンテキストに表示される「Webhook エンドポイント（実行時情報）」に従い、現在のユーザー用トークンを取得します。サービスに渡すのは `WEBHOOK_TOKEN` だけです。マスター鍵である `WEBHOOK_SECRET` は絶対に設定しないでください。
```env
WEBHOOK_URL=http://agents-host:8080/webhook
WEBHOOK_TOKEN=<user_id>:<hmac>
DISCORD_CHANNEL_ID=123456789012345678
WEBHOOK_SOURCE=email-monitor
```
メール受信時には、次の形式でAgentsへ送信します。
```http
POST ${WEBHOOK_URL}
Authorization: Bearer ${WEBHOOK_TOKEN}
Content-Type: application/json
{
"source": "email-monitor",
"channel_id": 123456789012345678,
"prompt": "新しいメールを受信しました。..."
}
```
### 3. Gmail用アプリパスワードの作成（Gmailを使用する場合）
1. Googleアカウントの2段階認証を有効にする
2. Googleアカウント設定 → セキュリティ → アプリパスワード
3. メール用のアプリパスワードを生成
### 4. 環境変数の設定
```bash
# .env.exampleをコピーして.envファイルを作成
cp .env.example .env
# .envファイルを編集して実際の値を設定
```
## 🚢 Agents `container_tools` へのデプロイ
`container_tools` はイメージをビルドせず、レジストリからpullして起動します。このリポジトリでは、`main` へのpush時にGitea Actionsが次のイメージをHarborへ公開します。
```text
harbor.mukan.0am.jp/knative-func/email-to-discord:<commit-sha>
harbor.mukan.0am.jp/knative-func/email-to-discord:latest
```
### 1. Gitea Actions Secretsの設定
リポジトリのActions Secretsへ次の2項目を登録します。実際の値をリポジトリやComposeへコミットしないでください。
- `HARBOR_USERNAME`
- `HARBOR_PASSWORD`
Pull Requestではテストステージと実行イメージのビルドだけを行い、`main` へマージされたときだけHarborへpushします。
### 2. デプロイ用Composeの準備
通常の [`docker-compose.yml`](docker-compose.yml) は `container_tools` 用テンプレートです。次の値を実際のデプロイ情報へ置き換えます。
- イメージタグの `latest`（可能ならGitea Actionsが公開したコミットSHAへ変更）
- `REPLACE_WITH_EMAIL_USER`
- `REPLACE_WITH_EMAIL_PASSWORD`
- `REPLACE_WITH_WEBHOOK_URL`
- `REPLACE_WITH_WEBHOOK_TOKEN`
- `REPLACE_WITH_DISCORD_CHANNEL_ID`
Discordへの直接通知も併用する場合だけ、空の `DISCORD_WEBHOOK_URL` に実際のURLを設定します。`WEBHOOK_SECRET` は設定しません。
Agentsの実行時情報にある `WEBHOOK_URL` が `http://127.0.0.1:<port>/webhook` の場合、コンテナ内の `127.0.0.1` はサテライト自身を指すため、`http://host.docker.internal:<port>/webhook` に置き換えてください。ComposeにはLinuxからDockerホストへ到達するための `host-gateway` を設定済みです。
### 3. デプロイ
置換後のCompose全文を、安定した `project_name` とともに `container_tools` へ渡します。デプロイ用Composeには、`container_tools` が禁止する `build`、`container_name`、`env_file`、host bind mountを含めていません。
## 🐳 ローカルDocker Composeでの実行
ローカルでソースからビルドする場合は、デプロイ用とは別の `docker-compose.local.yml` を使用します。
### 1. `.env` の設定
```env
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
# Discordへ直接通知する場合
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL
# Agentsを起動する場合（3項目すべてが必要）
WEBHOOK_URL=http://agents-host:8080/webhook
WEBHOOK_TOKEN=<user_id>:<hmac>
DISCORD_CHANNEL_ID=123456789012345678
```
### 2. コンテナの起動
```bash
# コンテナをビルドして起動
docker compose -f docker-compose.local.yml up --build -d
# ログの確認
docker compose -f docker-compose.local.yml logs -f
# コンテナの停止
docker compose -f docker-compose.local.yml down
```
## 🚀 Linux用シェルスクリプトでの実行
Linux環境では便利なシェルスクリプトを使用できます：
### 1. スクリプトに実行権限を付与
```bash
chmod +x start.sh
```
### 2. 初期セットアップ
```bash
# .envファイルを作成
./start.sh setup
# .envファイルを編集して実際の値を設定
nano .env
```
### 3. よく使用するコマンド
```bash
# Dockerイメージをビルド
./start.sh build
# コンテナを起動
./start.sh start
# リアルタイムでログを表示
./start.sh logs-f
# コンテナの状態を確認
./start.sh status
# コンテナを停止
./start.sh stop
# コンテナを再起動
./start.sh restart
# docker-compose で起動
./start.sh compose-up
# Python直接実行
./start.sh python
# ヘルプを表示
./start.sh help
```
### 4. 利用可能なコマンド一覧
| コマンド | 説明 |
|----------|------|
| `setup` | 初期セットアップ（.envファイル作成） |
| `build` | Dockerイメージをビルド |
| `start` | コンテナを起動 |
| `stop` | コンテナを停止 |
| `restart` | コンテナを再起動 |
| `logs` | ログを表示 |
| `logs-f` | ログをリアルタイム表示 |
| `status` | コンテナの状態を確認 |
| `clean` | 停止済みコンテナとイメージを削除 |
| `compose-up` | docker-compose で起動 |
| `compose-down` | docker-compose で停止 |
| `python` | Python直接実行 |
| `help` | ヘルプを表示 |
## 🪟 Windows用PowerShellスクリプトでの実行
Windows環境では PowerShell スクリプトを使用できます：
### 1. 初期セットアップ
```powershell
# .envファイルを作成
.\start.ps1 setup
# .envファイルを編集して実際の値を設定
notepad .env
```
### 2. よく使用するコマンド
```powershell
# Dockerイメージをビルド
.\start.ps1 build
# コンテナを起動
.\start.ps1 start
# リアルタイムでログを表示
.\start.ps1 logs-f
# コンテナの状態を確認
.\start.ps1 status
# コンテナを停止
.\start.ps1 stop
# ヘルプを表示
.\start.ps1 help
```
## 🔨 Dockerでの直接実行
### 1. イメージのビルド
```bash
docker build -t email-to-discord .
```
### 2. コンテナの実行
```bash
docker run -d \
--name email-monitor \
--restart unless-stopped \
-e EMAIL_USER=your-email@gmail.com \
-e EMAIL_PASSWORD=your-app-password \
-e DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL \
-e WEBHOOK_URL=http://agents-host:8080/webhook \
-e WEBHOOK_TOKEN=<user_id>:<hmac> \
-e DISCORD_CHANNEL_ID=123456789012345678 \
-e CHECK_INTERVAL=60 \
email-to-discord
```
## 🐍 Python直接実行
### 1. 依存関係のインストール
```bash
pip install -r requirements.txt
```
### 2. 環境変数の設定
```bash
# Windowsの場合
set EMAIL_USER=your-email@gmail.com
set EMAIL_PASSWORD=your-app-password
set DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL
# Linux/macOSの場合
export EMAIL_USER=your-email@gmail.com
export EMAIL_PASSWORD=your-app-password
export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL
# Agents Webhookを使う場合
export WEBHOOK_URL=http://agents-host:8080/webhook
export WEBHOOK_TOKEN=<user_id>:<hmac>
export DISCORD_CHANNEL_ID=123456789012345678
```
### 3. アプリケーションの実行
```bash
python app.py
```
## 📧 対応メールプロバイダー
### Gmail
```env
IMAP_SERVER=imap.gmail.com
IMAP_PORT=993
USE_SSL=true
```
### Outlook/Hotmail
```env
IMAP_SERVER=outlook.office365.com
IMAP_PORT=993
USE_SSL=true
```
### Yahoo Mail
```env
IMAP_SERVER=imap.mail.yahoo.com
IMAP_PORT=993
USE_SSL=true
```
### その他のプロバイダー
各プロバイダーのIMAP設定を確認して適切な値を設定してください。
## 📊 ログとモニタリング
アプリケーションは以下の情報をログ出力します：
- 起動/停止メッセージ
- メールサーバー接続状況
- 新しいメールの検出
- Discord・Agents Webhook送信の成功/失敗
- エラー情報
```bash
# Dockerコンテナのログを確認
docker logs email-to-discord-monitor
# リアルタイムでログを監視
docker logs -f email-to-discord-monitor
```
## 🔒 セキュリティ考慮事項
1. **アプリパスワードの使用**: 通常のパスワードではなくアプリ専用パスワードを使用
2. **環境変数での機密情報管理**: パスワードやWebhook URLは環境変数で管理
3. **SSL/TLS接続**: メールサーバーとの通信は暗号化
4. **非rootユーザー**: Dockerコンテナは非rootユーザーで実行
5. **ユーザー単位トークン**: Agents連携には `WEBHOOK_SECRET` ではなく `WEBHOOK_TOKEN` のみを使用
複数の通知先を設定した場合、すべての通知先への送信が成功してからメールを既読にします。いずれかが失敗したメールは未読のままとなり、次回の監視時に再試行されます。
## 🛠️ トラブルシューティング
### メールサーバーに接続できない場合
1. IMAP設定が正しいか確認
2. アプリパスワードが正しく設定されているか確認
3. 2段階認証が有効になっているか確認（Gmail）
4. ファイアウォールの設定を確認
### Discord通知が送信されない場合
1. Webhook URLが正しいか確認
2. Discordサーバーの権限を確認
3. ネットワーク接続を確認
### Agents Webhookが起動しない場合
1. `WEBHOOK_URL` が `/webhook` を含む正しいURLか確認
2. `WEBHOOK_TOKEN` が現在のユーザー用に発行された値か確認
3. `DISCORD_CHANNEL_ID` が数値のチャンネルIDか確認
4. Agents側のWebhookエンドポイントへコンテナから接続できるか確認
### ログの確認方法
```bash
# アプリケーションのログレベルを変更（開発時）
# app.py内のlogging.basicConfig levelをDEBUGに変更
```
## 📝 ライセンス
このプロジェクトはMITライセンスの下で公開されています。
## 🤝 コントリビューション
プルリクエストやイシューの報告を歓迎します。
## 📞 サポート
問題が発生した場合は、GitHubのIssueにて報告してください。
Reference in New Issue View Git Blame Copy Permalink