👉 点击展开：Docker 部署完整指南
方式一：使用 docker compose（推荐）
-
创建项目目录和配置:
# 克隆项目到本地
git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar
💡 说明：Docker 部署需要的关键目录结构如下：
当前目录/
├── config/
│ ├── config.yaml # 核心功能配置（必需）
│ ├── frequency_words.txt # 关键词配置（必需）
│ ├── timeline.yaml # 时间线配置
│ ├── ai_analysis_prompt.txt # AI 分析提示词（可选）
│ ├── ai_translation_prompt.txt # AI 翻译提示词（可选）
│ ├── ai_interests.txt # AI 兴趣过滤配置（可选）
│ ├── ai_filter/ # AI 过滤相关提示词
│ │ ├── prompt.txt
│ │ ├── extract_prompt.txt
│ │ └── update_tags_prompt.txt
│ └── custom/ # 用户自定义配置（可选）
│ ├── ai/ # 自定义 AI 提示词
│ └── keyword/ # 自定义关键词文件
└── docker/
├── .env # 敏感信息 + Docker 特有配置
└── docker-compose.yml # Docker Compose 编排文件
-
配置文件说明:
配置分工原则（v4.6.0 优化）：
💡 分工要点：
- 功能行为 → 改
config.yaml（如开启/关闭某个平台、调整推送模式）
- 关注内容 → 改
frequency_words.txt（如添加新的关注关键词）
- AI 输出风格 → 改
ai_analysis_prompt.txt 或 ai_translation_prompt.txt
- 密钥与凭证 → 改
docker/.env（API Key、Webhook URL 等敏感信息统一放这里）
- 个性化扩展 → 使用
config/custom/ 目录，避免直接修改默认配置被升级覆盖
💡 配置修改生效：修改 config.yaml 后，执行 docker compose up -d 重启容器即可生效
⚙️ 环境变量覆盖机制（v3.0.5+）
.env 文件中的环境变量会覆盖 config.yaml 中的对应配置：
配置优先级：环境变量 > config.yaml
使用方法：
- 修改
.env 文件，填写需要的配置
- 或在 NAS/群晖 Docker 管理界面的"环境变量"中直接添加
- 重启容器后生效：
docker compose up -d
-
启动服务:
选项 A：启动所有服务（推送 + AI 分析）
# 拉取最新镜像
docker compose pull
# 启动所有服务（trendradar + trendradar-mcp）
docker compose up -d
选项 B：仅启动新闻推送服务
# 只启动 trendradar（定时抓取和推送）
docker compose pull trendradar
docker compose up -d trendradar
选项 C：仅启动 MCP AI 分析服务
# 只启动 trendradar-mcp（提供 AI 分析接口）
docker compose pull trendradar-mcp
docker compose up -d trendradar-mcp
💡 提示：
- 大多数用户只需启动
trendradar 即可实现新闻推送功能
- 只有需要使用 ChatGPT/Gemini 进行 AI 对话分析时，才需启动
trendradar-mcp
- 两个服务相互独立，可根据需求灵活组合
-
查看运行状态:
# 查看新闻推送服务日志
docker logs -f trendradar
# 查看 MCP AI 分析服务日志
docker logs -f trendradar-mcp
# 查看所有容器状态
docker ps | grep trendradar
# 停止特定服务
docker compose stop trendradar # 停止推送服务
docker compose stop trendradar-mcp # 停止 MCP 服务
方式二：本地构建（开发者选项）
如果需要自定义修改代码或构建自己的镜像：
# 克隆项目
git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar
# 修改配置文件
vim config/config.yaml
vim config/frequency_words.txt
# 使用构建版本的 docker compose
cd docker
cp docker-compose-build.yml docker-compose.yml
构建并启动服务：
# 选项 A：构建并启动所有服务
docker compose build
docker compose up -d
# 选项 B：仅构建并启动新闻推送服务
docker compose build trendradar
docker compose up -d trendradar
# 选项 C：仅构建并启动 MCP AI 分析服务
docker compose build trendradar-mcp
docker compose up -d trendradar-mcp
💡 架构参数说明：
镜像更新
# 方式一：手动更新（爬虫 + MCP 镜像）
docker pull wantcat/trendradar:latest
docker pull wantcat/trendradar-mcp:latest
docker compose down
docker compose up -d
# 方式二：使用 docker compose 更新
docker compose pull
docker compose up -d
可用镜像：
服务管理命令
# 查看运行状态
docker exec -it trendradar python manage.py status
# 手动执行一次爬虫
docker exec -it trendradar python manage.py run
# 查看实时日志
docker exec -it trendradar python manage.py logs
# 显示当前配置
docker exec -it trendradar python manage.py config
# 显示输出文件
docker exec -it trendradar python manage.py files
# Web 服务器管理（用于浏览器访问生成的报告）
docker exec -it trendradar python manage.py start_webserver # 启动 Web 服务器
docker exec -it trendradar python manage.py stop_webserver # 停止 Web 服务器
docker exec -it trendradar python manage.py webserver_status # 查看 Web 服务器状态
# 查看帮助信息
docker exec -it trendradar python manage.py help
# 重启容器
docker restart trendradar
# 停止容器
docker stop trendradar
# 删除容器（保留数据）
docker rm trendradar
💡 Web 服务器说明：
- cron 模式下自动启动，通过浏览器访问
http://localhost:8080 查看最新报告
- 通过目录导航访问历史报告（如：
http://localhost:8080/2025-xx-xx/）
- 端口可在
.env 文件中配置 WEBSERVER_PORT 参数
- 手动停止：
docker exec -it trendradar python manage.py stop_webserver
- 手动启动：
docker exec -it trendradar python manage.py start_webserver
- 安全提示：仅提供静态文件访问，限制在 output 目录，只绑定本地访问
数据持久化
生成的报告和数据默认保存在 ./output 目录下，即使容器重启或删除，数据也会保留。
📊 网页版报告访问路径：
TrendRadar 生成的当日汇总 HTML 报告会同时保存到两个位置：
本地访问示例：
# 方式 1：通过 Web 服务器访问（推荐，Docker 环境）
# 1. 启动 Web 服务器
docker exec -it trendradar python manage.py start_webserver
# 2. 在浏览器访问
http://localhost:8080 # 访问最新报告（默认 index.html）
http://localhost:8080/html/2025-xx-xx/ # 访问指定日期的报告
# 方式 2：直接打开文件（本地环境）
open ./output/index.html # macOS
start ./output/index.html # Windows
xdg-open ./output/index.html # Linux
# 方式 3：访问历史归档
open ./output/html/2025-xx-xx/当日汇总.html
为什么有两个 index.html？
output/index.html：Docker Volume 挂载到宿主机，本地可直接打开index.html：GitHub Actions 推送到仓库，GitHub Pages 自动部署
💡 提示：两个文件内容完全相同，选择任意一个访问即可。
故障排查
# 检查容器状态
docker inspect trendradar
# 查看容器日志
docker logs --tail 100 trendradar
# 进入容器调试
docker exec -it trendradar /bin/bash
# 验证配置文件
docker exec -it trendradar ls -la /app/config/
MCP 服务部署（AI 分析功能）
如果需要使用 AI 分析功能，可以部署独立的 MCP 服务容器。
架构说明：
flowchart TB
subgraph trendradar["trendradar"]
A1[定时抓取新闻]
A2[推送通知]
end
subgraph trendradar-mcp["trendradar-mcp"]
B1[127.0.0.1:3333]
B2[AI 分析接口]
end
subgraph shared["共享卷"]
C1["config/ (ro)"]
C2["output/ (ro)"]
end
trendradar --> shared
trendradar-mcp --> shared
快速启动：
如果已按照 方式一：使用 docker compose 完成部署，只需启动 MCP 服务：
cd TrendRadar/docker
docker compose up -d trendradar-mcp
# 查看运行状态
docker ps | grep trendradar-mcp
单独启动 MCP 服务（不使用 docker compose）：
# Linux/Mac
docker run -d --name trendradar-mcp \
-p 127.0.0.1:3333:3333 \
-v $(pwd)/config:/app/config:ro \
-v $(pwd)/output:/app/output:ro \
-e TZ=Asia/Shanghai \
wantcat/trendradar-mcp:latest
# Windows PowerShell
docker run -d --name trendradar-mcp `
-p 127.0.0.1:3333:3333 `
-v ${PWD}/config:/app/config:ro `
-v ${PWD}/output:/app/output:ro `
-e TZ=Asia/Shanghai `
wantcat/trendradar-mcp:latest
⚠️ 注意：单独运行时，确保当前目录下有 config/ 和 output/ 文件夹，且包含配置文件和新闻数据。
验证服务：
# 检查 MCP 服务健康状态
curl http://127.0.0.1:3333/mcp
# 查看 MCP 服务日志
docker logs -f trendradar-mcp
在 AI 客户端中配置：
MCP 服务启动后，根据不同客户端进行配置：
Cherry Studio（推荐，GUI 配置）：
- 设置 → MCP 服务器 → 添加
- 类型：
streamableHttp
- URL：
http://127.0.0.1:3333/mcp
Claude Desktop / Cline（JSON 配置）：
{
"mcpServers": {
"trendradar": {
"url": "http://127.0.0.1:3333/mcp",
"type": "streamableHttp"
}
}
}
💡 提示：MCP 服务仅监听本地端口（127.0.0.1），确保安全性。如需远程访问，请自行配置反向代理和认证。
