社区数据通用使用说明

更新记录

2026-08-04：API Key 与文档入口前移

• 客户控制台首页新增“API 接入”，可直接生成、复制、查看和撤销 API Key。
• 控制台明确展示 Base URL https://redditdate.top，调用时需在请求头加入 X-API-Key。
• 控制台及各客户工作台顶部均新增“API 文档”，可打开 https://redditdate.top/docs 查看和测试公开接口。
• 完整密钥只在创建时显示一次，请立即保存；不要把 Key 放入公开网址、聊天记录或前端代码。

2026-08-02：密码重置和后台管理入口修复

• 修复密码重置邮件打开后没有显示新密码表单的问题；已经发送但仍在有效期内的链接也可以继续使用。
• 管理员后台恢复任务、客户四类资源、邮箱、账号安全和交付文件管理；该页面仅供内部管理员使用。
• 本次修复不修改客户已有任务、数据、额度或下载文件。

2026-08-02：客户控制台与业务工作台拆分

• 客户控制台现在集中展示实时数据、大额历史、关键词监测和评论草稿的资源与运行摘要。
• 实时数据和大额历史已使用独立工作台；创建、暂停、恢复、续跑、下载等操作方式保持不变。
• 关键词监测和评论草稿助手与其他业务页面使用同一套产品导航。
• 邮箱、密码和通知偏好统一放入“账号设置”；API Key 也可从控制台首页直接管理。
• 评论草稿助手展示独立草稿次数；实时数据、大额历史、关键词社区和草稿次数仍为四类互不通用的资源。
• 本次页面调整不修改已有任务、数据、额度、下载文件或后台采集方式。

2026-08-01：客户控制台结构优化

• 客户控制台将默认展示业务总览，集中查看实时数据、大额历史、评论草稿和关键词监测的可用资源。
• “普通数据”在当前客户界面中统一称为“实时数据”，额度数值和已有使用量不会因此发生变化。
• 客户总览不再单独展示普通套餐名称和计费方式，只展示各功能实际可用数值和状态。
• 普通历史回溯将从客户控制台隐藏；已有任务、历史下载和后台能力不会删除，大额历史继续作为客户可用的历史数据产品。
• 实时数据、大额历史、关键词监测和评论草稿助手分别进入对应工作台，控制台主要承担账号与业务总览。

2026-08-01：账号邮箱设置与安全规则优化

• 未设置邮箱的账号可以在“账号设置”中首次填写邮箱并发送验证邮件。
• 验证前可以修正误填邮箱并重新发送；验证成功后邮箱会锁定，页面只显示脱敏地址。
• 已验证邮箱如需更换，请联系客服处理；更换后必须重新完成验证。
• 只有已验证邮箱才能用于找回密码以及接收任务、额度和关键词等业务通知。

2026-08-01：任务暂停原因与关键词到期状态优化

• 实时采集任务会明确显示“已手动暂停”“数据额度不足，已暂停”“账号已停用”或“任务暂时暂停”，并提供对应的下一步操作。
• 客户页面只显示业务状态，不展示后台数据读取方式、技术错误码或内部错误详情。
• 手动暂停的任务可以恢复；额度不足暂停的任务在增加普通数据额度后可以恢复，已有数据不会删除。
• 客户控制台和关键词页面都会显示关键词套餐档位、到期时间和剩余天数。
• 关键词套餐到期后，所有单条监测统一显示“套餐已到期”，不会继续显示为运行中；原任务和历史命中仍会保留。

2026-08-01：关键词监测增加有效期

• 体验档支持 1 个社区，有效期为 7 天。
• 基础 5 个、专业 20 个和定制 50 个社区档位，有效期均为 30 天。
• 有效期从管理员开通或续费设置档位时开始计算；再次设置档位会重新计算有效期。
• 到期后关键词监测会停止后台扫描，不能新建或恢复监测；已有命中记录仍会保留。
• 关键词监测页面会显示具体到期时间和到期状态。

2026-08-01：实时定时采集完整性与共享增量优化

• 定时采集改为按社区和发布时间增量读取，不再只查看每轮最新 25 条帖子；数据较多时会自动分页并从断点继续。
• 多个客户采集同一社区时，系统只执行一次公共数据读取，但各采集器仍保持自己的周期、普通数据额度和交付进度。
• 帖子与评论分别保存进度，正常扫描保留短时间重叠并按 Reddit ID 去重；排队和 Worker 重启不会从头重复采集。
• 评论按社区增量读取，仅向已经采集对应帖子的任务交付；评论上限按每个帖子累计计算。
• 系统同时限制后台读取请求数量，其余社区会排队继续；采集器数量不限制为两个，排队不会跳过游标范围内的数据。
• 实时采集继续消耗普通数据额度，不消耗大额历史额度；只有实际新增交付的帖子和评论计入用量。
• 社区不存在、私有或不可访问时任务会停止并显示原因；暂时无法读取数据时会保留断点并自动延迟重试。
• 暂时无法读取数据后会暂停请求并逐步延长重试间隔，不会因任务已经到期而持续循环请求。
• 社区名称只能使用 Reddit 合法名称，不能把带空格的搜索词或关键词填写到社区字段。

2026-07-24：关键词监测采集稳定性优化

• 同一社区现在只采集一次，再供订阅该社区的不同关键词监测共同使用，减少重复请求和服务器压力。
• 帖子和评论分别按进度增量读取；正常扫描只保留约 5 分钟重叠并自动去重，不会每轮重复扫描最近数小时。
• 评论监测不再依赖“最新帖子列表”，旧帖子出现的新评论也可以进入社区评论增量流。
• 暂时无法读取数据时不会跳过该段进度，系统会保留断点并稍后继续；不会为了少量异常长期执行大范围重复补扫。
• 社区采集和后台读取均设置较低并发及单轮分页上限，积压内容会分轮继续，避免瞬时占用过多服务器资源。
• 关键词监测使用独立的“社区额度”，不会扣除普通数据额度；额度按全部运行中监测所涉及的社区去重计算。
• 社区额度提供体验 1 个、基础 5 个、专业 20 个和定制 50 个档位；多个任务重复监测同一社区只占 1 个额度。
• 暂停监测可以释放对应社区额度；社区额度不足时不能创建或恢复超额任务。
• 监测通知时间会受到公开内容进入系统的时间和用户选择的扫描间隔影响，不属于秒级实时提醒。

2026-07-24：大额历史任务排队优化

• 后台现在每 10 秒检查一次大额历史任务队列；有空闲处理位置时，新的等待任务会自动开始。
• 多个客户提交任务时，最多仍同时处理两个任务；更多任务会继续排队，避免服务器负载过高。
• 同一客户仍只能有一个等待中或运行中的大额任务，额度、文件和断点续跑规则不变。

2026-07-22：大额历史额度中断提示与断点续跑

• 大额历史任务因额度用完而提前停止时，会显示“部分完成 · 额度已用完”，不再显示为完整完成。
• 已成功生成的数据仍可下载；增加大额历史额度后，可以在原任务上点击“继续抓取”，系统会从未完成分区的断点继续。
• 续跑只会扣除新获取的数据，不会重复扣除第一次已经交付的数据。
• 直接调用大额历史分页 API 时，额度不足一整页会先返回剩余额度允许的数据，并通过 next_cursor、incomplete 和 stop_reason 提示继续位置。
• 额度为 0 时，API 返回 402 和错误码 BULK_HISTORY_QUOTA_EXHAUSTED；增加额度后使用之前保存的 next_cursor 继续。
• 历史评论暂时无法读取时系统会自动有限重试；持续无法读取会返回明确的暂时错误。

2026-07-12：关键词监测开发预览

• 新增 Reddit 关键词监测，可选择多个社区，并同时监测新帖子和评论。
• 支持完整单词、包含任一、包含全部、排除词和排除作者，降低误报。
• 同一内容在同一监测中只会记录一次；页面可查看上下文并跳转 Reddit 原文。
• 关键词监测用于发现新出现的公开内容，不承诺覆盖已删除、接口未返回或扫描窗口之外的全部内容。

2026-07-08：账号按额度使用与大额历史自助下载

• 账号业务权限改为按额度使用，不再因基础套餐日期到期而阻止实时数据、历史回溯、大额历史或评论草稿功能。
• 不同功能仍使用各自额度：普通数据额度用于实时数据、采集任务、历史回溯和普通导出；大额历史额度用于大额历史分页和下载任务；草稿次数用于评论草稿助手。
• 客户控制台新增大额历史下载任务入口，可选择社区、日期范围和内容类型，任务完成后会生成下载页面。

2026-07-06：大额历史额度包调整

• 大额历史额度包调整为 40 元 / 100 万条，适合按较小数据量灵活开通。
• 已有客户的大额历史余额不会自动重算；后续新增额度按新规格追加。

2026-07-05：邮件通知能力接入

• 系统开始接入 Resend 邮件发送通道，用于后续注册验证、修改密码验证、任务通知和额度预警。
• 邮件 API Key 只保存在服务器环境变量中，不会写入网页或公开代码。

2026-07-03：控制台显示与任务状态体验优化

• 控制台中文显示和页面结构已优化，任务、额度和下载信息更容易查看。
• 管理员可以更快查看大额历史任务、历史回溯任务和定时采集任务的状态。

2026-07-03：大额历史下载任务支持多客户并行

• 大额历史下载任务现在最多支持两个客户任务同时生成，减少排队等待时间。
• 更多任务会继续排队，系统会控制整体并发，避免因请求过多导致失败率升高。

2026-07-03：大额历史下载任务稳定性优化

• 大额历史下载任务会按数据类型和月份拆分生成压缩文件，适合更大时间范围的数据交付。
• 后台任务支持分区并行处理，整体等待时间会更短。
• 如果个别月份暂时无法读取，系统会继续处理其他月份；已成功生成的文件仍可下载，失败信息会写入任务状态。
• 系统会自动识别长时间没有进展的运行中任务，避免旧任务一直占用队列。
• 任务状态新增更新时间，便于判断任务是否仍在正常生成。

一、适用范围

本说明适用于按社区及时间范围交付的公开帖子、评论和评论回复数据。具体社区名称、起止时间、记录数量、文件大小和文件校验值，应以对应订单的下载页面或交付清单为准。

二、交付文件组成

根据订单规模，文件可能按数据类型、年份或月份拆分。常见结构如下：

manifest.json通常包含社区、时间范围、帖子数、评论数、文件大小、生成时间和SHA-256校验值。大型订单采用分片交付时，各分片均可独立下载和解压。

三、NDJSON与gzip格式

默认交付格式为NDJSON + gzip。gzip用于压缩；NDJSON表示每一行均为一个独立JSON对象，而不是由方括号包裹的JSON数组。

{"id":"abc123","title":"First post","selftext":"Post body"}
{"id":"def456","title":"Second post","selftext":"Another body"}

NDJSON可以流式读取，适合从数万条到上亿条的不同规模。处理大型文件时，不应一次性将全部记录载入内存。

四、文件完整性校验

下载后应使用交付清单中的SHA-256值校验文件。校验一致，表示文件在下载过程中未发生损坏或截断。

Windows PowerShell

Get-FileHash .\posts.ndjson.gz -Algorithm SHA256
Get-FileHash .\comments.ndjson.gz -Algorithm SHA256

Linux / macOS

sha256sum posts.ndjson.gz comments.ndjson.gz

分片订单应逐个校验文件。若校验值不一致，应重新下载对应分片，无须重新下载全部数据。

五、主要字段说明

帖子常用字段

评论常用字段

实际记录可能包含更多原始字段。不同年代、不同对象类型和不同归档状态下，部分字段可能缺失或为null，使用程序时应采用容错读取方式。

六、帖子、评论与回复的关联

帖子和评论通常分文件保存，但可通过ID完整还原所属关系和评论树。

1. 将评论的link_id去掉t3_前缀，即得到所属帖子的id。
2. parent_id以t3_开头时，该评论为直接回复帖子的一级评论。
3. parent_id以t1_开头时，去掉前缀后得到父评论的id。

由于删除或归档缺失，个别评论可能无法找到父评论。此类记录仍可通过link_id归入对应帖子，并标记为“父节点缺失”。

七、使用Python流式读取

以下代码可直接读取压缩文件，无须预先解压：

import gzip
import json

def read_ndjson_gzip(filename):
    with gzip.open(filename, "rt", encoding="utf-8") as source:
        for line in source:
            line = line.strip()
            if line:
                yield json.loads(line)

for post in read_ndjson_gzip("posts.ndjson.gz"):
    print(post.get("id"), post.get("title"))

关联帖子与评论

posts = {
    post["id"]: post
    for post in read_ndjson_gzip("posts.ndjson.gz")
}

for comment in read_ndjson_gzip("comments.ndjson.gz"):
    post_id = (comment.get("link_id") or "").removeprefix("t3_")
    post = posts.get(post_id)
    if post:
        print(post["title"], comment.get("body"))

转换UTC时间

from datetime import datetime, timezone

value = datetime.fromtimestamp(record["created_utc"], timezone.utc)
print(value.isoformat())

八、转换为CSV或Excel

NDJSON可以转换为CSV。建议仅选择业务需要的字段，避免将大量嵌套媒体结构直接写入单元格。

import csv, gzip, json

fields = ["id", "link_id", "parent_id", "author", "body", "score", "created_utc"]

with gzip.open("comments.ndjson.gz", "rt", encoding="utf-8") as source, \
     open("comments.csv", "w", newline="", encoding="utf-8-sig") as target:
    writer = csv.DictWriter(target, fieldnames=fields)
    writer.writeheader()
    for line in source:
        record = json.loads(line)
        writer.writerow({field: record.get(field) for field in fields})

Excel单个工作表最多约104万行，单元格文本长度也有限。超过该规模时，应按年月拆分CSV，或优先使用Parquet、DuckDB及数据库工具。CSV适合查看和交换，不适合表达嵌套媒体结构及完整评论树。

九、用于AI、检索与数据分析

交付数据可用于主题分析、情感分析、内容分类、社区趋势研究、RAG检索、动态示例库及经审核的模型训练。用于“根据帖子生成评论”时，可将帖子标题和正文作为输入，将符合条件的评论作为输出。

建议的训练前处理

• 剔除空内容、[deleted]、[removed]、机器人广告和重复记录。
• 根据长度、得分、层级、语言及人工质量标准筛选评论。
• 删除邮箱、电话、地址、账号等非必要个人信息。
• 按帖子ID划分训练集、验证集和测试集，防止同一讨论串跨集合泄漏。
• 保留原始ID用于内部去重，但不应将用户名作为模型学习目标。
• 高得分仅代表社区互动表现，不等同于事实正确或专业可靠。

{
  "instruction": "Write a relevant response to the community post.",
  "input": {"title": "...", "body": "..."},
  "output": "Selected and reviewed comment",
  "metadata": {"post_id": "...", "comment_id": "...", "score": 10}
}

十、图片、视频及外部链接

除非订单另有约定，数据文件通常只保存媒体URL、缩略图和结构化媒体字段，不包含图片或视频文件本身。可重点检查url、thumbnail、media和secure_media。

历史链接可能已经失效、跳转或改变内容。批量下载媒体会显著增加存储与流量成本，并可能受到第三方网站规则限制，因此不建议在未确认授权和需求的情况下自动下载全部媒体。

十一、数据质量与统计差异

• score、ups和num_comments为归档时记录，不保证等于当前页面数值。
• 帖子的num_comments可能与实际交付评论数不同，原因包括删除、不可访问、归档缺失和统计口径差异。
• 作者为[deleted]并不必然表示正文同时被删除。
• 部分记录可能缺少可选字段；程序应使用record.get("field")等容错方式读取。
• 历史链接和媒体资源可能失效。
• 大型分片订单应以所有分片记录数之和为交付总量，并使用清单校验，避免重复导入。

邮件通知

平台会通过邮件发送账号注册验证、密码重置、任务完成、真正需要处理的任务失败和额度预警。请确保账号邮箱可正常收信，并将 RedditDate 发信地址加入可信发件人。

公开 API 文档只展示数据读取、历史归档、采集和导出接口；注册、邮箱验证、密码重置和评论助手等操作请在网页控制台完成。

部分分片失败但最终已有可下载文件的任务，会按完成任务处理，不会发送失败通知。临时数据读取波动、无新数据或系统已自动处理的问题也不会作为客户失败邮件发送。

邮件中的操作链接应只在本人发起注册、登录或密码修改时点击。如收到非本人操作邮件，请及时联系管理员处理。

十二、隐私、安全与合规使用

数据使用方应根据其所在地区、应用场景和数据处理目的，自行评估适用的服务条款、著作权、隐私、个人信息保护及行业监管要求。

• 不得利用数据骚扰、跟踪、歧视或识别特定自然人。
• 不建议公开再发布包含用户名和敏感自述的完整数据副本。
• 用于模型训练或公开研究前，应进行去标识化、敏感信息清理和必要的风险评估。
• 下载链接及文件应仅提供给获得授权的人员，并在项目结束后按约定删除。
• 对删除请求、内容权利主张和安全事件，应建立相应的响应与处置流程。

本说明提供技术使用指引，不构成法律、医学、金融或其他专业意见。