# Bangumi Vault
**用于备份、浏览、导出和保存 Bangumi 收藏的私有 Docker 网页应用**
[![][license-shield]][license-link]
[![][node-shield]][node-link]
[![][docker-shield]][docker-link]
[![][postgres-shield]][postgres-link]
[![][back-to-top]](#readme-top)
## 🚀 快速开始
**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
> ```
>
> 登录后到 **设置** 里改成你自己的密码。
[![][back-to-top]](#readme-top)
## ⚙️ 配置
默认 `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 日志中打印一次。登录后请立即修改。
[![][back-to-top]](#readme-top)
## 🐳 服务
compose 默认启动两个容器：
| 容器 | 镜像 | 用途 |
|---|---|---|
| `bangumi-vault` | 由本仓库构建 | Node.js Web 服务、静态 UI、认证 API、封面缓存处理、定时同步 |
| `bangumi-vault-db` | `postgres:16-alpine` | 持久化 PostgreSQL 数据库 |
持久化数据使用本地路径挂载：
| 路径 | 用途 |
|---|---|
| `./data/postgres` | PostgreSQL 数据 |
| `./data/files` | Web 容器使用的缓存封面和日志 |
[![][back-to-top]](#readme-top)
## 📁 项目结构
```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 桌面运行时、启动脚本、旧构建资源等均已移除。
[![][back-to-top]](#readme-top)
## 🧪 本地开发
**前置条件**
- 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
```
[![][back-to-top]](#readme-top)
## 🔤 自托管字体
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
```
[![][back-to-top]](#readme-top)
## 🔐 安全说明
- 管理员密码以 PBKDF2-SHA256 哈希形式存储在 PostgreSQL 中。
- 只有数据库中不存在管理员密码哈希时，才会打印初始管理员密码；这是初始化行为，不会以明文形式持久化保存。
- 会话 Cookie 使用 HTTP-only，由服务端自动生成并持久化在数据库中的随机密钥签名。
- 公共模式下，访客只读浏览，管理操作（同步/导出/导入/缓存/设置保存等）在前端与服务端双重隔离。
- Bangumi Access Token 由用户填写，仅用于访问 Bangumi API；界面中不回显、不可复制。
- 不要公开 Docker 日志、截图、备份、导出文件或数据库转储，因为其中可能包含 token 或私有收藏数据。
- 报告安全问题时，请不要包含真实 token 或真实备份数据。
[![][back-to-top]](#readme-top)
## 📄 作者与许可
本项目派生自原项目并在其基础上二次开发：
- 原仓库：[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) 发布。贡献内容默认以相同许可发布。
[![][back-to-top]](#readme-top)
---
[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/