EhTagDb 标签聚合数据库

一个从 E/ExHentai 元数据转储数据库中聚合标签频次与样例画廊的脚本。它会：

• 从原始 api_dump.sqlite 读取 gallery 表
• 过滤失效与过旧数据，统计各命名空间下的标签出现次数
• 为每个标签挑选最近发表的最多 25 个样例（gid/token 列表）
• 生成新的 aggregated.sqlite，并额外统计 dumped 字段的日期分布
• 自动压缩输出为 aggregated.sqlite.gz

从 GitHub Release 下载的 aggregated.sqlite.gz 可直接使用或参考。

环境要求

• Node.js：^22.14.0 或 ^24.3.0
• pnpm：10.14.0

快速开始

1. 安装依赖

   pnpm install

2. 指定原始数据库路径（必做）

   • 打开 src/main.ts，将常量 ORIG_DB_PATH 改为你本地的 api_dump.sqlite 实际路径。

   • 示例：

     const ORIG_DB_PATH = 'D:\\data\\api_dump.sqlite\\api_dump.sqlite';

3. 运行脚本

   pnpm start

   • 进度会按约 1% 一次打印。
   • 结束后，项目根目录会生成：
   • aggregated.sqlite
   • aggregated.sqlite.gz

配置项说明

在 src/main.ts 顶部：

• ORIG_DB_PATH：原始转储数据库路径（必填，本地路径）。
• validDumpedThreshold：有效阈值（Unix 时间戳，脚本中用日期字符串转毫秒/1000 取得）。默认：2025/07/15。

如需更改筛选日期或命名空间，请按需修改并重新运行。

工作原理（聚合逻辑）

• 仅处理 gallery.current_gid IS NULL 的记录。
• 有效记录判定：expunged = 0 且 removed = 0 且 (dumped ?? 0) > validDumpedThreshold。
• 标签解析：原始字段形如 ['tag1','tag2'] 的字符串，脚本会替换引号后以 JSON 解析为数组。
• 统计：
  • 以键 "${namespace}||${tag}" 聚合计数 count。
  • 收集候选样例 { gid, token, posted }。
• 写入：
  • 候选按 posted 降序，取前 25 个，拼接为多行 gid/token 字符串写入。
  • 最终插入新表 tag_aggregate(namespace, tag, count, galleries)。
• 同时统计 dumped 的日期分布，写入表 dumped_distribution(date, count)（来自原始库全部 gallery.dumped 的聚合）。
• 完成后将 aggregated.sqlite gzip 压缩为 aggregated.sqlite.gz。

输出与表结构

• 文件：

  • aggregated.sqlite：聚合后的 SQLite 数据库。
  • aggregated.sqlite.gz：压缩版。

• 表：

  1. tag_aggregate

     • namespace TEXT：命名空间
     • tag TEXT：标签名
     • count INTEGER：标签在有效记录中的出现次数
     • galleries TEXT：最多 25 行，形如 gid/token 的样例（按 posted 新到旧）

  2. dumped_distribution

     • date TEXT：YYYY-MM-DD
     • count INTEGER：该日 dumped 的记录数

查询示例

在任意 SQLite 客户端中（如 DB Browser for SQLite）或脚本中执行：

• 查看出现次数最多的 20 个标签：

  SELECT namespace, tag, count
  FROM tag_aggregate
  ORDER BY count DESC
  LIMIT 20;

• 查看某个标签的样例画廊（示例以 female/sample_tag 为例）：

  SELECT galleries
  FROM tag_aggregate
  WHERE namespace = 'female' AND tag = 'sample_tag';

• 查看 dumped 的日期分布（按日期升序）：

  SELECT date, count
  FROM dumped_distribution
  ORDER BY date ASC;

常见问题

• 运行报错：找不到原始数据库

  • 请确认 src/main.ts 中的 ORIG_DB_PATH 指向存在的 api_dump.sqlite 文件。

• 安装 better-sqlite3 失败

  • 首先确保 Node 版本与预编译版本兼容，并重试安装。
  • 若回退到本地编译，请安装 C++ 构建工具与 Python（Windows 可装「Visual Studio Build Tools」+ Python），然后再次 pnpm install。

• 运行时间较长/内存占用

  • 数据量较大时属正常，脚本会打印进度。建议保证足够的磁盘空间与可用内存。

许可证

GPL-3.0-only