<div align="center"><a name="readme-top"></a>

# Bangumi Vault

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

[![][license-shield]][license-link]
[![][node-shield]][node-link]
[![][docker-shield]][docker-link]
[![][postgres-shield]][postgres-link]

</div>

---

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

## ✨ 功能特性

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

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 🚀 快速开始

**1. 启动服务**

```bash
docker compose up -d
```

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

**2. 查看初始管理员密码**

```bash
docker logs bangumi-vault
```

找到：

```text
Bangumi Vault initial admin password:
...
```

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

**3. 打开网页**

```text
http://localhost:8080
```

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

**4. 更新版本**

```bash
docker compose pull
docker compose up -d
```

> [!TIP]
> **忘记管理员密码？** 密码以哈希存储、无法找回，但可以重置：删除数据库里的密码记录后重启 Web 容器，它会像首次启动一样重新生成并在日志里打印一个新的初始密码。
>
> ```bash
> 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
> ```
>
> 登录后到 **设置** 里改成你自己的密码。

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## ⚙️ 配置

默认 `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 日志中打印一次。登录后请立即修改。

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 🐳 服务

compose 默认启动两个容器：

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

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

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

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 📁 项目结构

```text
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 桌面运行时、启动脚本、旧构建资源等均已移除。

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 🧪 本地开发

**前置条件**

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

安装依赖：

```bash
npm install
```

设置 PostgreSQL 连接字符串：

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

运行检查并启动：

```bash
npm run check
npm start
```

打开：

```text
http://localhost:3000
```

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 🔤 自托管字体

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`）：

```bash
node tools/fetch-fonts.mjs
```

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 🔐 安全说明

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

<div align="right">

[![][back-to-top]](#readme-top)

</div>

## 📄 作者与许可

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

- 原仓库：[AKISATO57/AKI-Bangumi-Vault](https://github.com/AKISATO57/AKI-Bangumi-Vault)
- 原作者：**AKISATO** ([@AKISATO57](https://github.com/AKISATO57))

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

Copyright (c) 2026 AKISATO.

本项目基于 [MIT License](./LICENSE) 发布。贡献内容默认以相同许可发布。

<div align="right">

[![][back-to-top]](#readme-top)

</div>

---

<!-- LINK GROUP -->
[back-to-top]: https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square
[license-shield]: https://img.shields.io/badge/license-MIT-white?labelColor=black&style=flat-square
[license-link]: ./LICENSE
[node-shield]: https://img.shields.io/badge/node.js-24-339933?labelColor=black&logo=node.js&logoColor=white&style=flat-square
[node-link]: https://nodejs.org/
[docker-shield]: https://img.shields.io/badge/docker-compose-2496ED?labelColor=black&logo=docker&logoColor=white&style=flat-square
[docker-link]: https://docs.docker.com/compose/
[postgres-shield]: https://img.shields.io/badge/postgres-16-336791?labelColor=black&logo=postgresql&logoColor=white&style=flat-square
[postgres-link]: https://www.postgresql.org/
