Bangumi Vault

用于备份、浏览、导出和保存 Bangumi 收藏的私有 Docker 网页应用

---

• ✨ 功能特性
• 🚀 快速开始
• ⚙️ 配置
• 🐳 服务
• 📁 项目结构
• 🧪 本地开发
• 🔤 自托管字体
• 🔐 安全说明
• 📄 作者与许可

✨ 功能特性

• 私有网页界面 - 自托管 Bangumi 收藏保管库，内置管理员登录；可选「公共模式」对外只读分享。
• Bangumi 同步 - 沿用 Bangumi API 流程，支持最近增量同步与完整同步；可在容器内按 cron 定时自动同步。
• 安全箱 - 完整同步时若远端疑似「吞」掉本地已有条目，不直接删除，而是放入安全箱由你人工裁决。
• 收藏浏览与筛选 - 按收藏状态、类型、标签（我的 / 公共）、标题、吐槽、有无吐槽、NSFW 等筛选；一键清除筛选。
• 条目详情 - 封面 banner、评分、进度、章节格、历史版本、条目资料（游戏引擎/开发商等 infobox）。
• 封面缓存 - 在服务端缓存封面，通过鉴权后的图片路由访问。
• 外观自定义 - 主题明暗 / 跟随系统、强调配色、字体风格、卡片尺寸、动效强度、预览行数、白边粗细等；访客也可本地保存自己的外观偏好。
• 多格式导出 - JSON、CSV、离线 HTML、Word、Excel 和完整 ZIP 备份包，全部由浏览器直接下载。
• PostgreSQL 持久化 - 应用状态、收藏、同步记录、历史、设置与密码哈希存储在独立 PostgreSQL 容器中。
• 自托管网页字体 - 不依赖用户本机字体；中文/日文字体按 unicode-range 分块按需加载。

🚀 快速开始

1. 启动服务

docker compose up -d

默认从镜像仓库拉取 git.stdm.moe/stardream/bangumi-vault:latest；若要从源码构建，编辑 docker-compose.yml（注释掉 image:、取消注释 build: .），再 docker compose up -d --build。

2. 查看初始管理员密码

docker logs bangumi-vault

找到：

Bangumi Vault initial admin password:
...

这个密码只会在新的数据库 volume 首次启动时打印一次。

3. 打开网页

http://localhost:8080

使用 Docker 日志中的密码登录，然后在 设置 中修改管理员密码。

4. 更新版本

docker compose pull
docker compose up -d

Tip

忘记管理员密码？ 密码以哈希存储、无法找回，但可以重置：删除数据库里的密码记录后重启 Web 容器，它会像首次启动一样重新生成并在日志里打印一个新的初始密码。

docker exec -it bangumi-vault-db psql -U bangumi_vault -d bangumi_vault -c "DELETE FROM settings WHERE key='admin_password_hash';"
docker restart bangumi-vault && docker logs bangumi-vault

登录后到 设置 里改成你自己的密码。

⚙️ 配置

默认 docker-compose.yml 不需要 .env 文件即可运行。

变量	默认值	必填	说明
PORT	3000	否	容器内 Web 服务端口
DATABASE_URL	compose 内置值	是	PostgreSQL 连接字符串
BANGUMI_VAULT_FILES_DIR	/data/files	否	封面缓存和日志文件目录

Warning

compose 文件中的 PostgreSQL 账号密码适合私有本地部署。若要暴露到可信内网之外，请修改 POSTGRES_PASSWORD 和 DATABASE_URL。

空数据库首次启动时，应用会生成初始管理员密码并只在 Docker 日志中打印一次。登录后请立即修改。

🐳 服务

compose 默认启动两个容器：

容器	镜像	用途
bangumi-vault	由本仓库构建	Node.js Web 服务、静态 UI、认证 API、封面缓存处理、定时同步
bangumi-vault-db	postgres:16-alpine	持久化 PostgreSQL 数据库

持久化数据使用本地路径挂载：

路径	用途
./data/postgres	PostgreSQL 数据
./data/files	Web 容器使用的缓存封面和日志

📁 项目结构

AKI-Bangumi-Vault/
├── app/                     # 前端：原生 ES 模块，无构建步骤
│   ├── BangumiVault.html    # 单页 UI 入口
│   ├── css/
│   │   ├── styles.css       # 全部样式
│   │   └── fonts.css        # 自托管字体 @font-face（由脚本生成）
│   ├── fonts/               # 自托管 woff2 字体（按 unicode-range 分块）
│   └── js/                  # 按职责拆分的模块
│       ├── core.js          # 状态、设置、外观、IndexedDB、API、infobox 预取
│       ├── model.js         # 数据归一化、筛选、排序、封面取址
│       ├── view.js          # 卡片/侧栏/详情/统计渲染
│       ├── cron.js          # 定时同步可视化编辑器
│       ├── sync.js          # 设置读写、同步触发与进度
│       ├── covers.js        # 封面缓存
│       ├── exports.js       # JSON/CSV/HTML/Word/Excel/ZIP 导出
│       └── main.js          # 事件绑定与启动
├── server/                  # Node 24 HTTP 服务（CommonJS，唯一依赖 pg）
│   ├── index.js             # 入口：建库、初始管理员密码、启动服务、容器内定时同步
│   ├── routes.js            # 请求处理：静态资源（/js /css /fonts）+ 全部 API
│   ├── store.js             # PostgreSQL 存储、表结构与迁移（含历史独立表）
│   ├── auth.js              # 会话鉴权、密码哈希
│   ├── http.js              # HTTP 辅助、MIME、gzip、缓存
│   ├── bgm.js               # Bangumi API 客户端
│   ├── sync.js              # 同步流程（最近/完整、安全箱判定）
│   ├── normalize.js         # 条目数据归一化
│   ├── covers.js            # 封面下载与缓存
│   └── constants.js         # 常量
├── tools/
│   └── fetch-fonts.mjs      # 从 jsDelivr 抓取字体并生成 app/fonts + css/fonts.css
├── .gitea/workflows/
│   └── docker-publish.yml   # Gitea Actions：构建并推送 Docker 镜像
├── docker-compose.yml       # Web + PostgreSQL 服务定义
├── Dockerfile               # Web 容器镜像
├── package.json             # Node 脚本与依赖
├── package-lock.json        # npm 锁定文件
├── README.md                # 本文档（简体中文）
└── LICENSE                  # MIT License

本项目为纯 Web 版本（由上游 Electron 单文件版本派生）：Electron 桌面运行时、启动脚本、旧构建资源等均已移除。

🧪 本地开发

前置条件

• Node.js 24 或更高版本
• PostgreSQL 16 或兼容版本

安装依赖：

npm install

设置 PostgreSQL 连接字符串：

set DATABASE_URL=postgres://bangumi_vault:bangumi_vault@localhost:5432/bangumi_vault

运行检查并启动：

npm run check
npm start

打开：

http://localhost:3000

🔤 自托管字体

5 种字体风格（系统默认 Inter、圆润 Nunito / M PLUS Rounded、日系 Noto Sans JP、文楷 LXGW WenKai Screen、等宽 JetBrains Mono）全部自托管，不依赖用户本机已装字体。@font-face 定义在 app/css/fonts.css，woff2 文件位于 app/fonts/<字体>/，由服务端 /fonts/* 公共路由提供；CJK 按 unicode-range 分块、浏览器只下载用到的字块。

重新抓取 / 更新字体（从 jsDelivr 下载并重新生成 fonts.css）：

node tools/fetch-fonts.mjs

🔐 安全说明

• 管理员密码以 PBKDF2-SHA256 哈希形式存储在 PostgreSQL 中。
• 只有数据库中不存在管理员密码哈希时，才会打印初始管理员密码；这是初始化行为，不会以明文形式持久化保存。
• 会话 Cookie 使用 HTTP-only，由服务端自动生成并持久化在数据库中的随机密钥签名。
• 公共模式下，访客只读浏览，管理操作（同步/导出/导入/缓存/设置保存等）在前端与服务端双重隔离。
• Bangumi Access Token 由用户填写，仅用于访问 Bangumi API；界面中不回显、不可复制。
• 不要公开 Docker 日志、截图、备份、导出文件或数据库转储，因为其中可能包含 token 或私有收藏数据。
• 报告安全问题时，请不要包含真实 token 或真实备份数据。

📄 作者与许可

本项目派生自原项目并在其基础上二次开发：

• 原仓库：AKISATO57/AKI-Bangumi-Vault
• 原作者：AKISATO (@AKISATO57)

本项目是用于个人 Bangumi 收藏备份的独立第三方工具，与 Bangumi 官方无从属、背书或正式关联关系。

Copyright (c) 2026 AKISATO.

本项目基于 MIT License 发布。贡献内容默认以相同许可发布。

---