Schnellstart

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• README.md
• docker/docker-compose.yml
• docker/entrypoint.sh
• setup-mac.sh
• setup-windows.bat
• mcp_server/server.py
• pyproject.toml
• requirements.txt
• docker/Dockerfile
• setup-windows-en.bat

TrendRadar ist ein leichtgewichtiges, schnell deploybares System zur Aggregation von Nachrichten und Trend-Themen. Das Projekt unterstützt diverse Benachrichtigungskanäle (WeChat, Telegram, DingTalk, Feishu, E-Mail, ntfy, Bark, Slack, Webhook) sowie AI-gestützte Analyse und Filterung. Die Deployment-Optionen umfassen GitHub Actions, GitHub Pages, Docker und MCP-Client-Integration (README.md:1-40).

Die Navigation im Projekt erfolgt über eine strukturierte Schnellübersicht mit Links zu den wichtigsten Abschnitten wie Schnellstart, AI-Analyse, Konfiguration, Docker-Deployment und MCP-Client (README.md:51-66).

Systemanforderungen

Betriebssystem

TrendRadar ist plattformunabhängig und läuft auf macOS, Windows und Linux. Für die lokale Installation wird ein Unix-ähnliches System mit Bash-Unterstützung empfohlen.

Software-Abhängigkeiten

Optionale Abhängigkeiten

• Docker: Für containerisiertes Deployment mit vordefinierten Umgebungsvariablen
• Cherry Studio oder anderer MCP-Client: Für die Nutzung des MCP-Servers

Docker-Deployment (Empfohlener Weg)

Docker bietet die schnellste und isolierteste Methode, um TrendRadar zu betreiben. Die Konfiguration erfolgt über Umgebungsvariablen und Volume-Mounts.

Docker Compose Konfiguration

Die Datei docker/docker-compose.yml definiert zwei Services: trendradar (Hauptanwendung) und trendradar-mcp (MCP-Server). Der Hauptservice verwendet das Image wantcat/trendradar:latest und mountet die Konfiguration schreibgeschützt sowie das Output-Verzeichnis für Ergebnisse (docker/docker-compose.yml:1-60).

yaml
1services:
2  trendradar:
3    image: wantcat/trendradar:latest
4    container_name: trendradar
5    restart: unless-stopped
6    ports:
7      - "127.0.0.1:${WEBSERVER_PORT:-8080}:${WEBSERVER_PORT:-8080}"
8    volumes:
9      - ../config:/app/config:ro
10      - ../output:/app/output
11    environment:
12      - TZ=Asia/Shanghai
13      - ENABLE_WEBSERVER=${ENABLE_WEBSERVER:-false}
14      - WEBSERVER_PORT=${WEBSERVER_PORT:-8080}
15      - CRON_SCHEDULE=${CRON_SCHEDULE:-*/30 * * * *}
16      - RUN_MODE=${RUN_MODE:-cron}
17      - IMMEDIATE_RUN=${IMMEDIATE_RUN:-true}

Umgebungsvariablen

Die wichtigsten Umgebungsvariablen für den Betrieb:

Benachrichtigungskanäle werden über Variablen wie FEISHU_WEBHOOK_URL, TELEGRAM_BOT_TOKEN, DINGTALK_WEBHOOK_URL konfiguriert (docker/docker-compose.yml:14-45).

Docker-Startbefehle

bash
1# Repository klonen
2git clone https://github.com/sansan0/TrendRadar.git
3cd TrendRadar/docker
4
5# Konfigurationsdateien erstellen (falls nicht vorhanden)
6mkdir -p ../config ../output
7
8# Container starten
9docker compose up -d
10
11# Logs anzeigen
12docker compose logs -f trendradar

Entrypoint und Cron-Konfiguration

Das Entrypoint-Skript prüft beim Start, ob die erforderlichen Konfigurationsdateien config.yaml und frequency_words.txt vorhanden sind. Fehlt eine Datei, bricht der Container mit einer Fehlermeldung ab (docker/entrypoint.sh:1-35).

bash
1# Prüfung der Konfigurationsdateien
2if [ ! -f "/app/config/config.yaml" ] || [ ! -f "/app/config/frequency_words.txt" ]; then
3    echo "❌ 配置文件缺失"
4    exit 1
5fi

Im Cron-Modus generiert das Skript eine Crontab-Datei und validiert diese mit supercronic -test. Bei ungültigem Cron-Format wird der Container beendet (docker/entrypoint.sh:18-28).

Lokale Installation (Mac)

Für die lokale Installation auf macOS stellt das Projekt ein automatisches Setup-Skript bereit, das alle Abhängigkeiten installiert.

Setup-Skript ausführen

bash
1# Repository klonen
2git clone https://github.com/sansan0/TrendRadar.git
3cd TrendRadar
4
5# Setup-Skript ausführen
6chmod +x setup-mac.sh
7./setup-mac.sh

UV Package Manager Installation

Das Skript prüft, ob der UV-Package-Manager installiert ist. Falls nicht, wird er automatisch über das offizielle Installationsskript heruntergeladen und installiert (setup-mac.sh:22-58).

bash
1# Automatische UV-Installation
2if ! command -v uv &> /dev/null; then
3    curl -LsSf https://astral.sh/uv/install.sh | sh
4    export PATH="$HOME/.cargo/bin:$PATH"
5fi

Nach erfolgreicher Installation zeigt das Skript die UV-Version an und fährt mit der Installation der Projektabhängigkeiten fort.

Abhängigkeiten installieren

Das Skript führt uv sync aus, um eine virtuelle Umgebung zu erstellen und alle Projektabhängigkeiten zu installieren (setup-mac.sh:61-73).

bash
1# Abhängigkeiten installieren
2uv sync

Konfigurationsprüfung

Nach der Installation prüft das Skript, ob die Konfigurationsdatei config/config.yaml existiert. Bei fehlender Datei wird eine Warnung ausgegeben (setup-mac.sh:76-84).

MCP-Server Konfiguration

Nach erfolgreicher Installation zeigt das Skript Anweisungen zur Konfiguration des MCP-Servers in Cherry Studio an (setup-mac.sh:92-118):

• Name: TrendRadar
• Beschreibung: 新闻热点聚合工具
• Typ: STDIO

Webserver und Watchdog

Der optionale Webserver ermöglicht eine lokale Vorschau der generierten Inhalte. Er kann über die Umgebungsvariable ENABLE_WEBSERVER=true aktiviert werden.

Webserver-Konfiguration

Die Webserver-Umgebungsvariablen in Docker Compose (docker/docker-compose.yml:14-21):

Watchdog-Funktionalität

Der Watchdog überwacht die Gesundheit des Webservers und führt bei Bedarf automatische Reparaturen durch. Im Entrypoint-Skript wird der Watchdog als Hintergrundprozess gestartet (docker/entrypoint.sh:36-57):

bash
1# Webserver starten
2if [ "${ENABLE_WEBSERVER:-false}" = "true" ]; then
3    echo "🌐 启动 Web 服务器..."
4    /usr/local/bin/python manage.py start_webserver
5    
6    # Watchdog im Hintergrund starten
7    if [ "$WEBSERVER_WATCHDOG_ENABLED" = "true" ]; then
8        echo "🔄 启动 Web 服务器 watchdog (间隔: ${WEBSERVER_WATCHDOG_INTERVAL}s)..."
9        (
10            while true; do
11                sleep "$WEBSERVER_WATCHDOG_INTERVAL"
12                /usr/local/bin/python manage.py webserver_autofix
13            done
14        ) &
15    fi
16fi

Port-Binding

Der Webserver wird standardmäßig an 127.0.0.1:8080 gebunden, um externen Zugriff zu verhindern. Für externen Zugriff muss die Port-Konfiguration in docker-compose.yml angepasst werden (docker/docker-compose.yml:7-8).

Laufzeitverifikation

Docker-Container prüfen

bash
1# Container-Status anzeigen
2docker compose ps
3
4# Erwartete Ausgabe:
5# NAME           STATUS    PORTS
6# trendradar     running   127.0.0.1:8080->8080/tcp
7# trendradar-mcp running   127.0.0.1:3333->3333/tcp

Logs überprüfen

bash
1# Logs des Hauptcontainers anzeigen
2docker compose logs trendradar
3
4# Erwartete Ausgabe bei erfolgreichem Start:
5# 📅 生成的crontab内容:
6# */30 * * * * cd /app && /usr/local/bin/python -m trendradar
7# ⏰ 启动supercronic: */30 * * * *

Webserver-Erreichbarkeit

Wenn der Webserver aktiviert ist:

bash
1# Health-Check (Endpoint benötigt Bestätigung)
2curl http://127.0.0.1:8080/
3
4# Erwartete Ausgabe: HTML-Seite oder JSON-Antwort
5# (Benötigt Bestätigung: Welcher Endpoint wird exakt bereitgestellt?)

MCP-Server-Verbindung

Der MCP-Server läuft auf Port 3333 und kann von MCP-Clients wie Cherry Studio erreicht werden (docker/docker-compose.yml:66-67):

bash
1# Port-Verfügbarkeit prüfen
2netstat -an | grep 3333
3
4# Erwartete Ausgabe:
5# tcp  0  0  127.0.0.1:3333  0.0.0.0:*  LISTEN

Häufige Probleme und Lösungen

Problem 1: Fehlende Konfigurationsdateien

Symptom: Container startet nicht mit Fehlermeldung ❌ 配置文件缺失

Ursache: Die Dateien config/config.yaml oder config/frequency_words.txt fehlen.

Lösung:

bash
1# Konfigurationsverzeichnis erstellen
2mkdir -p config
3
4# Beispiel-Konfiguration kopieren (falls vorhanden)
5cp config/config.yaml.example config/config.yaml
6
7# Oder Konfiguration aus dem Repository erstellen
8# (Benötigt Bestätigung: Wo befinden sich Beispiel-Konfigurationen?)

Problem 2: UV-Installation schlägt fehl

Symptom: Setup-Skript bricht mit ❌ [错误] UV 安装失败 ab

Ursache: Netzwerkprobleme oder unzureichende Berechtigungen.

Lösung (setup-mac.sh:40-48):

bash
1# Manuelle Installation
2curl -LsSf https://astral.sh/uv/install.sh | sh
3
4# PATH aktualisieren
5export PATH="$HOME/.cargo/bin:$PATH"
6
7# Installation verifizieren
8uv --version

Problem 3: Cron-Format ungültig

Symptom: Container beendet sich mit ❌ crontab格式验证失败

Ursache: Die Umgebungsvariable CRON_SCHEDULE enthält ein ungültiges Cron-Format.

Lösung:

bash
1# Gültiges Cron-Format verwenden
2export CRON_SCHEDULE="*/30 * * * *"  # Alle 30 Minuten
3
4# Oder in docker-compose.yml:
5environment:
6  - CRON_SCHEDULE=0 */2 * * *  # Alle 2 Stunden

Problem 4: Abhängigkeitsinstallation fehlgeschlagen

Symptom: uv sync schlägt fehl mit Netzwerk- oder Abhängigkeitsfehlern

Lösung (setup-mac.sh:68-73):

bash
1# Netzwerkverbindung prüfen
2ping -c 3 pypi.org
3
4# Cache leeren und erneut versuchen
5uv cache clean
6uv sync --reinstall

Problem 5: Webserver nicht erreichbar

Symptom: curl http://127.0.0.1:8080/ gibt Verbindung abgelehnt zurück

Ursache: Webserver ist nicht aktiviert oder Port ist belegt.

Lösung:

bash
1# Umgebungsvariable setzen
2export ENABLE_WEBSERVER=true
3
4# Port-Belegung prüfen
5lsof -i :8080
6
7# Alternativen Port verwenden
8export WEBSERVER_PORT=8081

Nächste Schritte

Nach erfolgreicher Installation und Verifikation:

1. Konfiguration anpassen: Die Datei config/config.yaml enthält alle Einstellungen für Benachrichtigungskanäle, AI-Analyse und Filterung. Details hierzu finden sich im Abschnitt "Konfiguration" der Projektdokumentation.

2. Benachrichtigungskanäle einrichten: Mindestens einen Benachrichtigungskanal (Telegram, Feishu, E-Mail etc.) konfigurieren, um aggregierte Nachrichten zu empfangen.

3. AI-Funktionen aktivieren: Für AI-gestützte Analyse und Filterung müssen AI_API_KEY, AI_MODEL und AI_API_BASE konfiguriert werden.

4. MCP-Client verbinden: Für die Nutzung mit AI-Assistenten kann der MCP-Server unter 127.0.0.1:3333 in kompatible Clients integriert werden.

5. Datenquelle verstehen: Das Projekt nutzt die API des newsnow Projekts. Bei Docker-Deployment sollte die Abruffrequenz moderat eingestellt werden, um die Drittanbieter-API nicht zu überlasten (README.md:86-91).