bangumi

把 bgm.tv（bangumi）的官方 jsonlines dump 装入 SQLite，同时提供命令行查询和 REST API。

• 单 binary：bangumi（Rust + axum + sqlx）
• 工具链：Rust nightly（由 rust-toolchain.toml 固定）
• 数据来源：官方 bgm.tv 每月初发布的 jsonlines 备份

安装

cargo build --release
# 产物：target/release/bangumi

如果 bangumi 已在 PATH 中，本文档直接用 bangumi 代替 ./target/release/bangumi。

数据库路径

优先级	方式	示例
最高	--db <路径> 或 BANGUMI_DB 环境变量	bangumi --db /tmp/test.db import
次之	DATABASE_URL 环境变量（SQLite URL）	DATABASE_URL="sqlite:///tmp/test.db?mode=ro"
默认	~/.config/bangumi/bangumi.db	自动创建

注意：设了 BANGUMI_DB 时 DATABASE_URL 不会生效（clap 把 BANGUMI_DB 作为 --db 的默认值传入）。

日志级别通过 RUST_LOG 控制，默认 info,sqlx=warn。

导入数据（import）

bangumi import                    # 从当前目录读取 jsonlines
bangumi import --dump /path/to    # 从指定目录读取
bangumi import --dry-run          # 只看文件清单，不写库
bangumi import --batch 1000       # 每个文件每批提交的行数

⚠️ 警告：import 会将数据导入同目录临时数据库，校验通过后原子替换目标数据库。目标数据库必须停止使用；正式库只会在完整导入、FK 检查和 integrity_check 全部成功后替换。

需要的文件

以下 jsonlines 文件放在同一目录下；必须存在 subject.jsonlines，其余文件缺失时自动跳过：

文件	对应表
subject.jsonlines	条目（动画/书籍/游戏/音乐/三次元）
episode.jsonlines	集数
character.jsonlines	角色
person.jsonlines	人物
subject-characters.jsonlines	条目 ↔ 角色关联
subject-persons.jsonlines	条目 ↔ STAFF 关联
subject-relations.jsonlines	条目间关联（续作/前作等）
person-characters.jsonlines	人物 ↔ 角色关联
person-relations.jsonlines	人物间关联

文件名中的关联表用连字符（subject-characters.jsonlines），不是下划线。

导入遇到 JSON 解析错误、外键错误或完整性检查失败会终止并返回非零状态；临时数据库会被清理，原数据库保持不变。

启动 HTTP 服务（serve）

bangumi serve                     # 默认监听 127.0.0.1:8080
BIND=0.0.0.0:8080 bangumi serve    # 明确需要远程访问时自定义地址
DATABASE_URL="sqlite:///path/to/db?mode=ro" bangumi serve  # 只读模式

写接口默认禁用。设置 `BANGUMI_WRITE_TOKEN` 后，POST/PATCH/DELETE 需要发送
`Authorization: Bearer <token>`。仅设置 `CORS_ORIGIN` 时启用该单一来源的 CORS；默认不启用 CORS。

## CLI 查询

所有命令输出 **pretty JSON**。

```bash
# 统计
bangumi stats

# 条目（subject）
bangumi subjects get 8
bangumi subjects list --type 1 --query 进击的巨人 --limit 5 --sort score --order desc
bangumi subjects list --type 1 --date-from 2024 --min-score 8
bangumi subjects list --tag 科幻

# 关联数据
bangumi subjects episodes   8
bangumi subjects characters 8
bangumi subjects persons    8 --position 1
bangumi subjects relations  8

# 集数
bangumi episodes list --subject-id 8 --limit 3
bangumi episodes get 522

# 角色
bangumi characters get 1
bangumi characters subjects 1

# 人物
bangumi persons get 1
bangumi persons subjects 1 --position 2004
bangumi persons characters 1

subject 查询参数

参数	说明
--type	1=书籍 2=动画 3=音乐 4=游戏 6=三次元
--query	关键词，匹配 name / name_cn（LIKE %q%）
--tag	标签名（精确匹配）
--min-score	最低评分
--date-from / --date-to	日期区间（YYYY/YYYY-MM/YYYY-MM-DD）
--nsfw	仅 NSFW
--sort	name / date / score / rank / id（默认 id）
--order	asc / desc（默认 desc）
--page	页码（默认 1）
--limit	每页条数，1–200（默认 20）

返回格式：

{
  "items": [ ... ],
  "page": 1,
  "limit": 20,
  "total": 652164
}

写操作

bangumi subjects create --type 1 --name Demo --name-cn 测试
bangumi subjects update 123 --summary hello
bangumi subjects delete 123

更新 nullable 字段时可使用 --clear-summary、--clear-name-cn、--clear-infobox、--clear-date 或 --clear-score 显式写入 null。

HTTP API

所有响应 JSON，根路径 /api/v1。

Method	Path	说明
GET	/healthz	健康检查
GET	/api/v1/meta/stats	表行数统计 + schema 版本
GET	/api/v1/subjects	条目列表（分页 + 过滤）
GET	/api/v1/subjects/{id}	单个条目（含 tags / meta_tags）
POST	/api/v1/subjects	新建条目
PATCH	/api/v1/subjects/{id}	局部更新
DELETE	/api/v1/subjects/{id}	删除条目
GET	/api/v1/subjects/{id}/episodes	该条目所有集
GET	/api/v1/subjects/{id}/characters	角色列表
GET	/api/v1/subjects/{id}/persons?position=	STAFF（常用 position: 1 监督 4 系列构成 100 原作 2004 主演）
GET	/api/v1/subjects/{id}/relations	关联条目
GET	/api/v1/episodes?subject_id=&type=0&page=1&limit=50	集数列表
GET	/api/v1/episodes/{id}	单集
GET	/api/v1/characters/{id}	角色
GET	/api/v1/characters/{id}/subjects	角色出现的所有条目
GET	/api/v1/persons/{id}	人物
GET	/api/v1/persons/{id}/subjects	人物参与的作品
GET	/api/v1/persons/{id}/characters	人物配音的角色

CLI 子命令与 HTTP 端点一一对应，共用同一套 handler。

常见问题

• 导入慢？ 瓶颈在 SQLite 序列化 JSON，全量约 70–100 秒。
• 中文搜不到？ bangumi 把中文标题放 name_cn，原语言（多半日文）放 name。--query 同时搜两个字段。