Stardream
295 lines
10 KiB
Markdown
295 lines
10 KiB
Markdown
<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/
|