stock-info-crawler/README.md

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

🚀 快速開始

1. 建立專案目錄

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 檔案：

# 基本設定
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. 啟動服務

# 使用 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 指令

基本操作

# 建構映像
docker-compose build

# 啟動服務
docker-compose up -d

# 停止服務
docker-compose down

# 重啟服務
docker-compose restart

# 查看日誌
docker-compose logs -f

# 進入容器
docker-compose exec barrons-crawler 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 端點：

健康檢查

curl http://localhost:8080/health

回應：{"status": "healthy", "timestamp": "2024-01-15T10:30:00"}

查看統計資料

curl http://localhost:8080/stats

回應：

{
  "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
}

手動觸發檢查

curl http://localhost:8080/check

📊 監控和警報

健康檢查

Docker 容器包含自動健康檢查：

• 每30秒檢查一次
• 3次失敗後標記為不健康
• 可用於自動重啟策略

日誌監控

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

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

資料備份

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

🐛 故障排除

常見問題

1. 無法獲取網頁內容

   # 檢查網路連線
   docker-compose exec barrons-crawler curl -I https://www.barrons.com
   

2. 電子郵件發送失敗

   • 檢查 Gmail 應用程式密碼是否正確
   • 確認兩步驟驗證已開啟
   • 檢查防火牆設定

3. 解析內容失敗

   • 網頁結構可能已變更
   • 檢查日誌中的錯誤訊息
   • 可能需要更新解析邏輯

4. 容器無法啟動

   # 檢查詳細錯誤
   docker-compose logs barrons-crawler
   
   # 檢查磁碟空間
   df -h
   
   # 檢查埠口占用
   netstat -tlnp | grep 8080
   

調試模式

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

🔒 安全建議

1. 不要在代碼中硬編碼密碼

   • 使用 .env 檔案或 Docker secrets
   • 將 .env 加入 .gitignore

2. 定期更新依賴

   # 更新基礎映像
   docker-compose pull
   docker-compose up -d
   

3. 監控資源使用

   # 查看容器資源使用
   docker stats barrons-crawler
   

4. 網路安全

   • 使用反向代理（如 Nginx）
   • 設定適當的防火牆規則
   • 啟用 HTTPS（如果對外開放）

📈 擴展功能

多實例部署

# docker-compose.yml
services:
  barrons-crawler-1:
    # ... 設定
  barrons-crawler-2:
    # ... 設定
    environment:
      - CHECK_INTERVAL=600  # 不同檢查間隔

與其他服務整合

# 加入資料庫
  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. 遵守網站使用條款