存储配置

TrendRadar 会根据你的部署方式自动选择合适的存储后端。大多数情况下你无需手动配置，只有使用 GitHub Actions 部署时才需要额外设置云端存储。

存储后端自动选择

部署环境	存储位置	说明
Docker / 本地部署	本地磁盘	数据存储在 output/ 目录中，开箱即用
GitHub Actions	云端存储	Actions 运行环境在每次执行后销毁，必须配置云端存储以持久化数据

本地存储（SQLite）

Docker 部署和本地部署默认使用本地 SQLite 存储。数据保存在 output/ 目录中，无需任何额外配置。

output 目录结构

output/ 目录中的文件各有不同用途：

SQLite 数据库：存储新闻数据、排名轨迹、RSS 条目、AI 分析结果等核心运行数据
HTML 报告：用于邮件推送和网页查看的可视化报告文件
TXT 快照：纯文本格式的数据快照，用于调试和排查问题

适用场景

如果你使用 Docker 或本地方式部署 TrendRadar，数据会自动保存到本地磁盘，这部分内容可以直接跳过。以下云端存储配置仅适用于 GitHub Actions 用户。

远程 S3 存储（GitHub Actions 用户）

GitHub Actions 的运行环境在每次执行后会被销毁，因此需要配置兼容 S3 协议的云端存储来保存数据。推荐使用 Cloudflare R2，免费额度完全够用。

需要配置的 Secrets

在你的 GitHub 仓库中，进入 Settings > Secrets and variables > Actions，添加以下 Secrets：

Secret 名称	填写内容	必填	说明
`STORAGE_BACKEND`	remote	必填	存储后端类型，填写 remote 即可
`S3_BUCKET_NAME`	你的存储桶名称	必填	例如 trendradar-data
`S3_ACCESS_KEY_ID`	你的 Access Key ID	必填	在创建 API Token 时获取
`S3_SECRET_ACCESS_KEY`	你的 Secret Access Key	必填	在创建 API Token 时获取（仅显示一次）
`S3_ENDPOINT_URL`	你的 R2 端点 URL	必填	格式：https://[account-id].r2.cloudflarestorage.com
`S3_REGION`	auto	可选	可选，默认值为 "auto"，一般无需修改

Cloudflare R2 配置指南

关于 R2 费用

Cloudflare R2 需要绑定支付方式（仅用于身份验证，不会产生费用）。支持双币信用卡或 PayPal。 R2 的免费额度为每月 10GB 存储空间，对于 TrendRadar 项目来说完全够用。

登录你的 Cloudflare 账户，在左侧菜单中找到并点击 R2 Object Storage。

创建存储桶

点击 Overview > Create Bucket，输入存储桶名称（例如 trendradar-data），然后点击创建。

获取端点 URL

返回 Overview 页面，向下滚动到 Account Details 部分，找到 S3 API 地址。这个地址就是你的 S3_ENDPOINT_URL：

https://[your-account-id].r2.cloudflarestorage.com

创建 API Token

在 Account Details 区域，点击 Manage（R2 API Tokens）进入 Token 管理页面。点击 Create Account API Token：

给 Token 起一个名称（例如 trendradar）
权限选择：Admin Read and Write
指定存储桶：选择你刚才创建的存储桶
点击 Create

保存密钥

请立即复制并妥善保存

创建成功后页面会显示 Access Key ID 和 Secret Access Key。这两个值仅在创建时显示一次，关闭页面后将无法再次查看。如果忘记保存，只能删除旧 Token 重新创建。

其他 S3 兼容服务商

除 Cloudflare R2 外，TrendRadar 还支持其他 S3 兼容的存储服务。以下是常用服务商的端点 URL 格式：

服务商	S3_ENDPOINT_URL 格式	说明
Cloudflare R2	`https://<account-id>.r2.cloudflarestorage.com`	推荐，免费额度充足
阿里云 OSS	`https://oss-cn-<region>.aliyuncs.com`	将 <region> 替换为实际地域，如 hangzhou、shanghai
腾讯云 COS	`https://cos.ap-<region>.myqcloud.com`	将 <region> 替换为实际地域，如 guangzhou、beijing
AWS S3	`https://s3.<region>.amazonaws.com`	将 <region> 替换为实际区域，如 us-east-1

数据保留策略

你可以在 config/config.yaml 中配置本地和云端数据的保留天数：

storage:
  local:
    retention_days: 0     # 保留天数（默认 0，即永久保留。设为 30 则只保留最近 30 天）
  remote:
    retention_days: 0     # 保留天数（默认 0，即永久保留）

保留策略说明

超过保留天数的数据会在下次运行时自动清理。如果你希望永久保留所有数据，将 retention_days 设为 0 即可（这也是默认值）。云端存储建议根据免费额度合理设置保留天数，避免超出存储限制。

数据拉取（MCP Server 场景）

如果你使用 MCP Server 在本地与远程数据交互，可以配置启动时自动从远程同步数据到本地：

storage:
  pull:
    enabled: false    # 是否启用启动时自动拉取（true=启用, false=关闭）
    days: 7           # 拉取最近 N 天的数据

使用场景

此功能主要用于 MCP Server 场景：远程存储的数据在启动时自动拉取到本地，方便本地分析和查询。默认关闭，按需开启即可。

时区设置

数据的时间戳与时区设置相关。你可以在 config/config.yaml 中调整时区：

app:
  timezone: "Asia/Shanghai"  # 默认中国时间

如果你在其他时区使用，修改为对应的时区标识即可（例如 America/New_York、Europe/London 等）。