stock-info-crawler/README.md

# Barron's 股票推薦爬蟲 Docker 部署指南

## 🚀 快速開始

### 1. 建立專案目錄
```bash
mkdir barrons-crawler
cd barrons-crawler
```

### 2. 創建文件結構
```
barrons-crawler/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── enhanced_crawler.py
├── health_check.py
├── .dockerignore
├── .env                    # 環境變數設定檔
├── data/                   # 資料持久化目錄
└── logs/                   # 日誌目錄
```

### 3. 設定環境變數
創建 `.env` 檔案：
```bash
# 基本設定
CHECK_INTERVAL=300
LOG_LEVEL=INFO
ALWAYS_NOTIFY_ON_STARTUP=false  # 啟動後第一次必定寄當前清單

# 電子郵件通知設定（SMTP）
# 對 Gmail：建議使用應用程式密碼
# 對學校/企業信箱：請依管理者提供之 SMTP 主機與加密方式設定
EMAIL_SMTP_SERVER=smtp.gmail.com         # 例：mail.ntust.edu.tw
EMAIL_SMTP_PORT=587                      # starttls 常用 587；ssl 常用 465
EMAIL_SMTP_SECURITY=starttls             # starttls | ssl | none
EMAIL_FROM=your_email@gmail.com          # 例：m10605505@mail.ntust.edu.tw
EMAIL_TO=notification@gmail.com
EMAIL_USERNAME=your_email@gmail.com      # 有些伺服器需填完整信箱
EMAIL_PASSWORD=your_app_specific_password

# Slack Webhook（可選）
WEBHOOK_URL=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

# Discord Webhook（可選）
DISCORD_WEBHOOK=https://discord.com/api/webhooks/YOUR/DISCORD/WEBHOOK
```

### 4. 啟動服務
```bash
# 使用 Docker Compose 啟動
docker-compose up -d

# 查看日誌
docker-compose logs -f barrons-crawler
```

## 📋 詳細設定選項

### 電子郵件設定（SMTP）
1. 若使用 Gmail：
   - 開啟兩步驟驗證
   - 生成應用程式密碼：https://myaccount.google.com/apppasswords
   - 在 `.env` 使用應用程式密碼，而非一般密碼
2. 若使用學校/企業郵件（如 NTUST）：
   - 向管理者確認 SMTP 主機、連接埠與加密方式（starttls 或 ssl）
   - `EMAIL_USERNAME` 可能需要填完整信箱（例如 `m10605505@mail.ntust.edu.tw`）

### 啟動後首次通知行為
- 環境變數 `ALWAYS_NOTIFY_ON_STARTUP`
  - `true/1/yes`：服務啟動完成後，第一次檢查即使沒有新內容也會寄出目前清單；之後只在有更新時寄出
  - `false`（預設）：只有在偵測到新內容時才寄出

### Slack 通知設定
1. 建立 Slack App: https://api.slack.com/apps
2. 創建 Incoming Webhook
3. 複製 Webhook URL 到 `.env` 檔案

### Discord 通知設定
1. 在 Discord 伺服器創建 Webhook
2. 複製 Webhook URL 到 `.env` 檔案

## 🔧 Docker 指令

### 基本操作
```bash
# 建構映像
docker-compose build

# 啟動服務
docker-compose up -d

# 停止服務
docker-compose down

# 重啟服務
docker-compose restart

# 查看日誌
docker-compose logs -f

# 進入容器
docker-compose exec barrons-crawler bash
```

### 維護指令
```bash
# 清理停用的容器
docker system prune

# 更新並重新建構
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# 備份資料
docker cp barrons-crawler:/app/data ./data_backup
```

## 🌐 Web API 端點

爬蟲提供了以下 HTTP 端點：

### 健康檢查
```bash
curl http://localhost:8080/health
```
回應：`{"status": "healthy", "timestamp": "2024-01-15T10:30:00"}`

### 查看統計資料
```bash
curl http://localhost:8080/stats
```
回應：
```json
{
  "start_time": "2024-01-15T10:00:00",
  "total_checks": 24,
  "new_picks_found": 3,
  "last_check": "2024-01-15T10:25:00",
  "last_notification": "2024-01-15T09:45:00",
  "errors": 0
}
```

### 手動觸發檢查
```bash
curl http://localhost:8080/check
```

## 📊 監控和警報

### 健康檢查
Docker 容器包含自動健康檢查：
- 每30秒檢查一次
- 3次失敗後標記為不健康
- 可用於自動重啟策略

### 日誌監控
```bash
# 即時查看日誌
docker-compose logs -f barrons-crawler

# 查看特定時間的日誌
docker-compose logs --since "2024-01-15T10:00:00" barrons-crawler
```

### 資料備份
```bash
# 設定定期備份（加到 crontab）
0 2 * * * docker cp barrons-crawler:/app/data /backup/barrons-$(date +\%Y\%m\%d)
```

## 🐛 故障排除

### 常見問題

1. **無法獲取網頁內容**
   ```bash
   # 檢查網路連線
   docker-compose exec barrons-crawler curl -I https://www.barrons.com
   ```

2. **電子郵件發送失敗**
   - 檢查 Gmail 應用程式密碼是否正確
   - 確認兩步驟驗證已開啟
   - 檢查防火牆設定

3. **解析內容失敗**
   - 網頁結構可能已變更
   - 檢查日誌中的錯誤訊息
   - 可能需要更新解析邏輯

4. **容器無法啟動**
   ```bash
   # 檢查詳細錯誤
   docker-compose logs barrons-crawler
   
   # 檢查磁碟空間
   df -h
   
   # 檢查埠口占用
   netstat -tlnp | grep 8080
   ```

### 調試模式
```yaml
# 在 docker-compose.yml 中添加
environment:
  - LOG_LEVEL=DEBUG
  
# 或者進入容器手動執行
docker-compose exec barrons-crawler python enhanced_crawler.py
```

## 🔒 安全建議

1. **不要在代碼中硬編碼密碼**
   - 使用 `.env` 檔案或 Docker secrets
   - 將 `.env` 加入 `.gitignore`

2. **定期更新依賴**
   ```bash
   # 更新基礎映像
   docker-compose pull
   docker-compose up -d
   ```

3. **監控資源使用**
   ```bash
   # 查看容器資源使用
   docker stats barrons-crawler
   ```

4. **網路安全**
   - 使用反向代理（如 Nginx）
   - 設定適當的防火牆規則
   - 啟用 HTTPS（如果對外開放）

## 📈 擴展功能

### 多實例部署
```yaml
# docker-compose.yml
services:
  barrons-crawler-1:
    # ... 設定
  barrons-crawler-2:
    # ... 設定
    environment:
      - CHECK_INTERVAL=600  # 不同檢查間隔
```

### 與其他服務整合
```yaml
# 加入資料庫
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: barrons
      POSTGRES_USER: crawler
      POSTGRES_PASSWORD: password
```

### 定制通知
可以擴展 `enhanced_crawler.py` 添加：
- Line Notify
- Telegram Bot
- 推播通知
- 簡訊通知

## 🎯 最佳實踐

1. **定期監控日誌**
2. **設定適當的檢查間隔**（避免過於頻繁）
3. **定期備份資料**
4. **監控資源使用情況**
5. **設定適當的通知渠道**
6. **遵守網站使用條款**