daily-news-app/執行步驟.md

每日報導 APP - 執行步驟指南

本文檔提供系統的詳細執行步驟，包含本地開發和生產部署兩種方式。

---

📋 前置需求

系統需求

• 作業系統：Linux / macOS / Windows
• Python：3.11 或以上版本
• Docker：20.10 或以上版本（使用 Docker 部署時）
• Docker Compose：2.0 或以上版本（使用 Docker 部署時）
• MySQL：8.0 或以上版本（生產環境，或使用 Docker 時自動安裝）

必要帳號與 API Key

• LLM API Key（三選一）：
  • Google Gemini API Key
  • OpenAI API Key
  • 或使用 Ollama（本地部署，無需 API Key）
• Digitimes 帳號（如需抓取 Digitimes 新聞）
• SMTP 設定（如需發送 Email 通知）

---

🚀 方式一：本地開發環境

步驟 1：環境準備

1.1 複製專案（如尚未複製）

# 如果專案在 Git 倉庫
git clone <repository-url>
cd daily-news-app

# 或直接進入專案目錄
cd /Users/peelerwu/Documents/AICoding/daily-news-app

1.2 建立 Python 虛擬環境

# 建立虛擬環境
python3 -m venv venv

# 啟動虛擬環境
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

1.3 安裝 Python 依賴套件

pip install -r requirements.txt

步驟 2：環境變數設定

2.1 建立 .env 檔案

# 複製範例檔案（如果存在）
cp .env.example .env

# 或手動建立
touch .env

2.2 編輯 .env 檔案

使用文字編輯器開啟 .env，填入以下設定：

# ============================================
# 應用程式設定
# ============================================
APP_ENV=development
DEBUG=true
SECRET_KEY=your-secret-key-here-min-32-chars-change-in-production
JWT_SECRET_KEY=your-jwt-secret-key-here-min-32-chars-change-in-production

# ============================================
# 資料庫設定（開發環境可使用 SQLite）
# ============================================
# 選項 1：使用 SQLite（簡單，適合開發）
DB_HOST=sqlite
DB_NAME=daily_news_app

# 選項 2：使用 MySQL（需先啟動 MySQL）
# DB_HOST=localhost
# DB_PORT=3306
# DB_NAME=daily_news_app
# DB_USER=root
# DB_PASSWORD=your-mysql-password

# ============================================
# LLM 設定（選擇一個）
# ============================================
# 選項 1：使用 Gemini（推薦，費用較低）
LLM_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-api-key-here
GEMINI_MODEL=gemini-1.5-pro

# 選項 2：使用 OpenAI
# LLM_PROVIDER=openai
# OPENAI_API_KEY=your-openai-api-key-here
# OPENAI_MODEL=gpt-4o

# 選項 3：使用 Ollama（本地部署）
# LLM_PROVIDER=ollama
# OLLAMA_ENDPOINT=http://localhost:11434
# OLLAMA_MODEL=llama3

# ============================================
# SMTP 設定（Email 通知，選填）
# ============================================
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_FROM_EMAIL=noreply@example.com
SMTP_FROM_NAME=每日報導系統

# ============================================
# LDAP/AD 設定（選填，如需企業認證）
# ============================================
LDAP_SERVER=ldap.example.com
LDAP_PORT=389
LDAP_BASE_DN=DC=example,DC=com
LDAP_BIND_DN=
LDAP_BIND_PASSWORD=

# ============================================
# Digitimes 帳號（選填，如需抓取 Digitimes）
# ============================================
DIGITIMES_USERNAME=your-digitimes-username
DIGITIMES_PASSWORD=your-digitimes-password

# ============================================
# 其他設定
# ============================================
CORS_ORIGINS=["http://localhost:3000","http://localhost:8000"]

2.3 產生強隨機密鑰（生產環境必做）

# 使用 Python 產生
python3 -c "import secrets; print('SECRET_KEY=' + secrets.token_urlsafe(32)); print('JWT_SECRET_KEY=' + secrets.token_urlsafe(32))"

將產生的密鑰填入 .env 檔案。

步驟 3：資料庫初始化

3.1 使用 SQLite（開發環境推薦）

# 執行初始化腳本
python scripts/init_db_sqlite.py

這會自動建立 SQLite 資料庫檔案 daily_news_app.db 並建立所有資料表。

3.2 使用 MySQL（如需）

# 1. 確保 MySQL 服務已啟動
# macOS (Homebrew):
brew services start mysql
# Linux:
sudo systemctl start mysql
# Windows: 從服務管理員啟動 MySQL

# 2. 建立資料庫
mysql -u root -p
CREATE DATABASE daily_news_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

# 3. 執行初始化 SQL
mysql -u root -p daily_news_app < scripts/init.sql

步驟 4：啟動應用程式

4.1 使用啟動腳本（推薦）

python run.py

4.2 或使用 uvicorn 直接啟動

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

4.3 驗證啟動成功

開啟瀏覽器訪問：

• API 文件：http://127.0.0.1:8000/docs
• 健康檢查：http://127.0.0.1:8000/health
• 根路徑：http://127.0.0.1:8000/

步驟 5：初始化資料（可選）

如果需要建立預設用戶或測試資料：

# 進入 Python 互動環境
python

# 執行初始化（範例）
from app.db.session import SessionLocal
from app.models.user import User, Role
from app.core.security import get_password_hash

db = SessionLocal()
# 建立管理員用戶
admin_role = db.query(Role).filter(Role.code == "admin").first()
if admin_role:
    admin_user = User(
        username="admin",
        password_hash=get_password_hash("admin123"),
        display_name="系統管理員",
        email="admin@example.com",
        auth_type="local",
        role_id=admin_role.id,
        is_active=True
    )
    db.add(admin_user)
    db.commit()
db.close()

---

🐳 方式二：Docker 部署（生產環境推薦）

步驟 1：環境準備

1.1 確認 Docker 已安裝

docker --version
docker-compose --version

1.2 建立 .env 檔案

在專案根目錄建立 .env 檔案，內容參考「方式一」的步驟 2.2，但需調整以下設定：

# 生產環境設定
APP_ENV=production
DEBUG=false

# 資料庫設定（Docker Compose 會自動建立 MySQL）
DB_HOST=mysql
DB_PORT=3306
DB_NAME=daily_news_app
DB_USER=root
DB_PASSWORD=your-strong-mysql-password-here

# 必須使用強隨機密鑰
SECRET_KEY=your-strong-secret-key-min-32-chars
JWT_SECRET_KEY=your-strong-jwt-secret-key-min-32-chars

# 其他設定與方式一相同

步驟 2：啟動服務

2.1 使用 Docker Compose 啟動

# 啟動所有服務（應用程式 + MySQL）
docker-compose up -d

# 查看日誌
docker-compose logs -f app

# 查看所有服務狀態
docker-compose ps

2.2 使用 Ollama（可選，本地 LLM）

# 啟動包含 Ollama 的服務
docker-compose --profile ollama up -d

# 下載模型
docker exec -it daily-news-ollama ollama pull llama3

步驟 3：資料庫初始化

3.1 等待 MySQL 就緒

# 檢查 MySQL 健康狀態
docker-compose ps mysql

3.2 執行初始化 SQL

# 方法 1：使用 docker exec
docker exec -i daily-news-mysql mysql -uroot -p${DB_PASSWORD} daily_news_app < scripts/init.sql

# 方法 2：進入容器執行
docker exec -it daily-news-mysql bash
mysql -uroot -p
# 輸入密碼後
USE daily_news_app;
SOURCE /docker-entrypoint-initdb.d/init.sql;
EXIT;

注意：如果 docker-compose.yml 中已設定 init.sql 掛載，MySQL 容器啟動時會自動執行。

步驟 4：驗證部署

# 檢查應用程式健康狀態
curl http://localhost:8000/health

# 查看應用程式日誌
docker-compose logs -f app

步驟 5：存取系統

• API 文件：http://localhost:8000/docs（生產環境可能已關閉）
• 健康檢查：http://localhost:8000/health
• API 端點：http://localhost:8000/api/v1

---

🔧 常用操作

查看日誌

# 本地開發
tail -f logs/app.log

# Docker
docker-compose logs -f app

停止服務

# 本地開發
# 按 Ctrl+C 停止

# Docker
docker-compose down

# 停止並刪除資料（謹慎使用）
docker-compose down -v

重啟服務

# Docker
docker-compose restart app

# 或重新建立
docker-compose up -d --force-recreate app

進入容器

# 進入應用程式容器
docker exec -it daily-news-app bash

# 進入 MySQL 容器
docker exec -it daily-news-mysql bash

資料庫備份

# MySQL 備份
docker exec daily-news-mysql mysqldump -uroot -p${DB_PASSWORD} daily_news_app > backup_$(date +%Y%m%d).sql

# SQLite 備份
cp daily_news_app.db backup_$(date +%Y%m%d).db

資料庫還原

# MySQL 還原
docker exec -i daily-news-mysql mysql -uroot -p${DB_PASSWORD} daily_news_app < backup_20240101.sql

---

🧪 測試系統

1. 測試 API 端點

# 健康檢查
curl http://localhost:8000/health

# 登入（需先建立用戶）
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

2. 測試新聞抓取

# 進入容器或虛擬環境
python

# 執行測試
from app.services.crawler_service import CrawlerService
crawler = CrawlerService()
# 測試抓取（需先設定新聞來源）

3. 測試 LLM 摘要

# 進入容器或虛擬環境
python

# 執行測試
from app.services.llm_service import LLMService
llm = LLMService()
# 測試摘要生成

---

⚠️ 常見問題

問題 1：資料庫連線失敗

症狀：啟動時出現資料庫連線錯誤

解決方法：

1. 檢查 .env 中的資料庫設定是否正確
2. 確認 MySQL 服務已啟動（本地開發）
3. 確認 Docker 容器中的 MySQL 已就緒（Docker 部署）
4. 檢查防火牆設定

問題 2：LLM API 呼叫失敗

症狀：生成摘要時出現 API 錯誤

解決方法：

1. 檢查 API Key 是否正確設定
2. 檢查 API Key 是否有足夠額度
3. 檢查網路連線
4. 查看日誌了解詳細錯誤

問題 3：Email 發送失敗

症狀：通知無法發送

解決方法：

1. 檢查 SMTP 設定是否正確
2. 檢查 SMTP 伺服器是否需要 TLS/SSL
3. 檢查防火牆是否阻擋 SMTP 埠號
4. 查看 notification_logs 表了解錯誤詳情

問題 4：新聞抓取失敗

症狀：定時抓取沒有執行或失敗

解決方法：

1. 檢查排程服務是否正常啟動
2. 檢查新聞來源設定是否正確
3. 檢查 Digitimes 帳號是否有效（如需）
4. 查看 crawl_jobs 表了解錯誤詳情

問題 5：權限錯誤

症狀：無法執行某些操作

解決方法：

1. 檢查用戶角色是否正確
2. 檢查 JWT Token 是否有效
3. 檢查 API 端點的權限設定

---

📝 後續設定

1. 建立初始用戶

使用 API 或直接操作資料庫建立管理員用戶。

2. 設定新聞來源

在系統設定中配置新聞來源（Digitimes、經濟日報、工商時報）。

3. 建立群組

建立產業別或議題群組，並設定關鍵字。

4. 設定排程

確認排程服務正常運作，每日定時抓取和生成報告。

5. 測試完整流程

1. 手動觸發新聞抓取
2. 檢查新聞是否正確匹配到群組
3. 生成測試報告
4. 測試 Email 通知

---

🔗 相關資源

• API 文件：http://localhost:8000/docs
• 專案 README：README.md
• 系統解析：系統解析.md
• 系統設計文檔：daily-news-SDD.md

---

📞 支援

如有問題，請聯繫 IT 部門或查看專案文檔。