Docker 部署
Docker 是推荐的部署方式之一，适合有服务器或 NAS 的用户。 本指南将引导你通过 Docker 完成 TrendRadar 的部署，无需安装 Python 环境。
当前任务 · Docker
更换部署方式让 TrendRadar 在你的服务器或 NAS 上持续运行，运行数据默认保存在本地。
首次启动前：先配置一个推送渠道
打开左侧的 推送渠道，选择一种接收方式并取得所需的 Webhook、Token 或密钥，再写入
docker/.env 或 config/config.yaml。 配好后回到本页启动容器并发送测试通知。前置条件
请确保你的系统已安装 Docker 和 Docker Compose。如果尚未安装，请参考 Docker 官方文档完成安装。
镜像概览
TrendRadar 提供两个 Docker 镜像，分别对应不同的功能模块：
| 镜像名称 | 用途 | 说明 |
|---|---|---|
wantcat/trendradar | 新闻推送服务 | 定时抓取新闻、关键词匹配、推送通知（必装） |
wantcat/trendradar-mcp | AI 分析服务 | 基于 MCP 协议的 AI 对话分析（可选） |
方法一：Docker Compose 部署（推荐）
Docker Compose 是最便捷的部署方式，可以按需启动核心推送服务或可选的 MCP 服务。 以下步骤先带你完成最小可用的推送流程。
克隆项目
获取最新代码和配置文件
了解目录结构
熟悉各配置文件的作用
编辑配置
根据需求修改配置文件
启动并验证
先运行核心推送服务，确认收到测试通知
1. 克隆项目
打开终端，执行以下命令将项目克隆到本地：
git clone https://github.com/sansan0/TrendRadar.git && cd TrendRadar2. 目录结构
克隆完成后，你会看到以下目录结构。部署时只需关注
config/ 和 docker/ 两个目录：Project/
├── 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 筛选提示词目录
│ └── custom/ # 用户自定义配置
│ ├── ai/ # 自定义 AI 提示词
│ └── keyword/ # 自定义关键词文件
└── docker/
├── .env # 密钥与 Docker 配置（当前为已跟踪文件）
└── docker-compose.yml # Docker Compose 编排文件3. 配置文件说明
每个配置文件负责不同的功能模块，以下是简要说明：
| 文件 | 作用 | 是否必须 |
|---|---|---|
config/config.yaml | 核心配置文件，包含平台选择、推送渠道、AI 设置等所有系统参数 | 必须 |
config/frequency_words.txt | 关键词配置，定义你关注的新闻话题和过滤规则 | 必须 |
config/timeline.yaml | 时间线调度配置，控制每天什么时间执行哪些任务 | 可选 |
docker/.env | 密钥与 Docker 配置；当前文件受版本控制，填写后必须避免提交真实值 | 必须 |
配置文件编辑提示
config.yaml 和 frequency_words.txt 的详细配置说明， 请参考「快速开始」中的配置编辑章节。这里只介绍 Docker 部署特有的内容。4. 环境变量覆盖机制
TrendRadar 支持通过环境变量覆盖
config.yaml 中的配置。 优先级为：环境变量 > config.yaml 文件。这意味着你可以将敏感信息（如 API Key、Webhook URL）放在
docker/.env 文件中， 而不必写入 config.yaml。Docker Compose 会自动读取 .env 文件中的变量。| 环境变量 | 对应配置 | 说明 |
|---|---|---|
WEBSERVER_PORT | - | 内置报告服务器端口，默认 8080 |
FEISHU_WEBHOOK_URL | notification.channels.feishu.webhook_url | 飞书机器人 Webhook 地址 |
AI_ANALYSIS_ENABLED | ai_analysis.enabled | 是否启用 AI 分析功能（true/false） |
AI_API_KEY | ai.api_key | AI 服务的 API Key |
AI_MODEL | ai.model | AI 模型标识（如 deepseek/deepseek-v4-flash） |
S3_ENDPOINT_URL | storage.remote.endpoint_url | S3 兼容存储的 Endpoint 地址 |
S3_ACCESS_KEY_ID | storage.remote.access_key_id | S3 存储的 Access Key |
S3_SECRET_ACCESS_KEY | storage.remote.secret_access_key | S3 存储的 Secret Key |
S3_BUCKET_NAME | storage.remote.bucket_name | S3 存储桶名称 |
CRON_SCHEDULE | - | Docker 定时任务表达式（默认 */30 * * * *，每 30 分钟执行一次） |
RUN_MODE | - | 运行模式：cron（定时循环运行）或 once（运行一次后退出） |
IMMEDIATE_RUN | - | 容器启动时是否立即执行一次（默认 true） |
以上为常用环境变量。完整列表请参考
docker-compose.yml 文件。安全提示
请勿将包含真实密钥的
.env 文件提交到 Git 仓库。 在当前对应版本中，docker/.env 已经是 Git 跟踪文件，.gitignore 不能阻止它继续提交修改。 请优先通过部署平台注入环境变量；若必须本地填写，提交前务必检查 git diff -- docker/.env。5. 启动服务
进入
docker/ 目录，根据你的需求选择启动方式： 第一次只需要新闻抓取与推送，优先选择「仅推送服务」；MCP 是完成基础流程后的可选增强。全部服务（按需）
仅推送服务（推荐首次使用）
仅 MCP 服务
只启动新闻推送服务，不启动 MCP 分析服务：
cd docker
docker compose pull trendradar
docker compose up -d trendradar启动后验证
先执行
docker compose ps 与 docker logs trendradar 检查容器和首次抓取日志。 如果启用了 AI，再执行 docker exec trendradar python -m trendradar --doctor 检查 AI 开关、 API Key 和模型格式；最后执行 docker exec trendradar python -m trendradar --test-notification。 容器显示 running 只代表进程存活，不代表 AI 与通知已经配通。进阶参考：用 Docker Run 启动 MCP
以下命令只启动可选的 MCP 分析服务，不是新闻抓取与推送服务的完整部署命令。 首次部署请使用上方 Docker Compose 流程，避免漏掉持久化、配置和定时运行参数。
docker run -d \
--name trendradar-mcp \
-p 3333:3333 \
-v ./config:/app/config \
wantcat/trendradar-mcp参数说明：
-d：后台运行容器--name trendradar-mcp：为容器设置名称，方便后续管理-p 3333:3333：将容器内 3333 端口映射到宿主机-v ./config:/app/config：将本地配置目录挂载到容器内
推送服务的 docker run 方式
推送服务（trendradar）的 docker run 命令与上面类似， 但需要额外挂载
output 目录用于数据持久化， 并通过 -e 参数传入环境变量。建议使用 Docker Compose 方式，配置更清晰。访问内置报告服务器
TrendRadar 在 cron 模式下会启动内置报告服务器，用于查看生成的网页报告。
默认访问地址：
http://127.0.0.1:8080端口修改：通过
docker/.env 中的 WEBSERVER_PORT 修改。远程访问：Compose 默认绑定服务器自身的
127.0.0.1。在 NAS 或 VPS 上部署时， 你不能在自己电脑上直接打开 localhost:8080；请使用 SSH 隧道或经过访问控制的反向代理，不要直接暴露到公网。常用管理命令
以下是日常管理 TrendRadar 容器时常用的命令。 你可以在终端中直接执行这些命令来管理和监控服务。
配置诊断与连通性测试建议先运行
修改配置后先运行这里的命令；它们不会启动新闻抓取。
环境与配置体检检查配置、AI 参数、存储与输出目录
docker exec -it trendradar python -m trendradar --doctor通知渠道实测向所有有效渠道真实发送一条测试消息
docker exec -it trendradar python -m trendradar --test-notification当前调度状态查看时间段及抓取、分析、推送开关
docker exec -it trendradar python -m trendradar --show-schedule--doctor 会生成 output/meta/doctor_report.json，但只校验 AI 模型、 API Key 和模型格式，不会向模型发送真实请求，因此不能替代 LLM 连通性测试。容器内管理工具
通过镜像内置的 manage.py 查看状态，或手动执行一次任务。
容器运行状态检查 supercronic、配置文件与定时任务
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 服务器
管理容器内用于浏览 output 目录和历史 HTML 报告的静态 Web 服务。
启动报告服务使用 WEBSERVER_PORT 配置的端口提供静态报告
docker exec -it trendradar python manage.py start_webserver停止报告服务停止独立的静态报告进程
docker exec -it trendradar python manage.py stop_webserver查看服务状态显示进程、端口和报告访问地址
docker exec -it trendradar python manage.py webserver_statusDocker 容器操作
使用 Docker 原生命令查看日志、控制容器和更新镜像。
跟踪日志按 Ctrl+C 退出，不会停止容器
docker logs -f trendradar重启容器重新启动抓取服务
docker restart trendradar停止容器停止抓取服务
docker stop trendradar删除已停止容器移除容器本身，不删除已挂载的配置与输出目录
docker rm trendradar更新并重启拉取最新镜像并重新创建服务
cd docker
docker compose pull trendradar
docker compose up -d trendradar数据持久化
TrendRadar 的运行数据（抓取结果、推送历史、HTML 报告等）存储在容器内的
output/ 目录中。重要提示
通过 Docker Compose 部署时，
docker-compose.yml 已经将 output/ 目录挂载到宿主机，数据会自动持久化。 即使删除容器并重新创建，数据也不会丢失。如果使用 docker run 方式部署， 请确保通过 -v 参数挂载 output 目录， 否则删除容器后数据将丢失。如需了解更多关于 S3 兼容存储的远程备份方案，请参考「存储配置」章节。