grimmory-self-hosted-library by aradotso/trending-skills
npx skills add https://github.com/aradotso/trending-skills --skill grimmory-self-hosted-library由 ara.so 提供的技能 — Daily 2026 技能集合。
Grimmory 是一款自托管应用程序(BookLore 的继任者),用于管理您的整个图书收藏。它支持 EPUB、PDF、MOBI、AZW/AZW3 和漫画(CBZ/CBR/CB7)格式,内置浏览器阅读器、注释功能、Kobo/OPDS 同步、KOReader 进度同步、元数据增强和多用户支持。
.env 文件# 应用程序
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC
# 数据库
DATABASE_URL=jdbc:mariadb://mariadb:3306/grimmory
DB_USER=grimmory
DB_PASSWORD=${DB_PASSWORD}
# 存储:LOCAL(默认)或 NETWORK
DISK_TYPE=LOCAL
# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
MYSQL_DATABASE=grimmory
docker-compose.yml 文件services:
grimmory:
image: grimmory/grimmory:latest
# 备选注册表:ghcr.io/grimmory-tools/grimmory:latest
container_name: grimmory
environment:
- USER_ID=${APP_USER_ID}
- GROUP_ID=${APP_GROUP_ID}
- TZ=${TZ}
- DATABASE_URL=${DATABASE_URL}
- DATABASE_USERNAME=${DB_USER}
- DATABASE_PASSWORD=${DB_PASSWORD}
- DISK_TYPE=${DISK_TYPE}
depends_on:
mariadb:
condition: service_healthy
ports:
- "6060:6060"
volumes:
- ./data:/app/data
- ./books:/books
- ./bookdrop:/bookdrop
healthcheck:
test: wget -q -O - http://localhost:6060/api/v1/healthcheck
interval: 60s
retries: 5
start_period: 60s
timeout: 10s
restart: unless-stopped
mariadb:
image: lscr.io/linuxserver/mariadb:11.4.5
container_name: mariadb
environment:
- PUID=${DB_USER_ID}
- PGID=${DB_GROUP_ID}
- TZ=${TZ}
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
- MYSQL_DATABASE=${MYSQL_DATABASE}
- MYSQL_USER=${DB_USER}
- MYSQL_PASSWORD=${DB_PASSWORD}
volumes:
- ./mariadb/config:/config
restart: unless-stopped
healthcheck:
test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
interval: 5s
timeout: 5s
retries: 10
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
docker compose up -d
# 查看日志
docker compose logs -f grimmory
# 检查健康状态
curl http://localhost:6060/api/v1/healthcheck
打开 http://localhost:6060 并创建您的管理员账户。
./data/ # 应用程序数据、缩略图、用户配置
./books/ # 您的图书文件(挂载在 /books)
./bookdrop/ # 自动导入的放置区(挂载在 /bookdrop)
./mariadb/ # MariaDB 数据
| 变量 | 描述 | 默认值 |
|---|---|---|
USER_ID | 应用程序进程的用户 ID | 1000 |
GROUP_ID | 应用程序进程的组 ID | 1000 |
TZ | 时区字符串 | Etc/UTC |
DATABASE_URL | JDBC 连接字符串 | 必需 |
DATABASE_USERNAME | 数据库用户名 | 必需 |
DATABASE_PASSWORD | 数据库密码 | 必需 |
DISK_TYPE | LOCAL 或 NETWORK | LOCAL |
| 类别 | 格式 |
|---|---|
| 电子书 | EPUB, MOBI, AZW, AZW3 |
| 文档 | |
| 漫画 | CBZ, CBR, CB7 |
将文件放入主机的 ./bookdrop/ 目录。Grimmory 会监视该文件夹,从 Google Books 和 Open Library 提取元数据,并将图书加入待审核队列。
./bookdrop/
my-novel.epub ← 放在这里
another-book.pdf ← 放在这里
流程:
/bookdrop 目录需要在 docker-compose.yml 中进行卷映射:
volumes:
- ./bookdrop:/bookdrop
对于 NFS、SMB 或其他网络挂载的文件系统,请设置 DISK_TYPE=NETWORK。这将禁用破坏性的用户界面操作(删除、移动、重命名),以保护共享挂载,同时保持阅读、元数据和同步功能完全可用。
# .env
DISK_TYPE=NETWORK
Grimmory 是一个 Java 应用程序(Spring Boot + MariaDB)。在贡献或扩展时:
src/main/java/
com/grimmory/
config/ # Spring 配置类
controller/ # REST API 控制器
service/ # 业务逻辑
repository/ # JPA 仓库
model/ # JPA 实体
dto/ # 数据传输对象
所有端点都在 /api/v1/ 下:
# 健康检查
GET http://localhost:6060/api/v1/healthcheck
# 图书
GET http://localhost:6060/api/v1/books
GET http://localhost:6060/api/v1/books/{id}
POST http://localhost:6060/api/v1/books
PUT http://localhost:6060/api/v1/books/{id}
DELETE http://localhost:6060/api/v1/books/{id}
# 书架
GET http://localhost:6060/api/v1/shelves
POST http://localhost:6060/api/v1/shelves
# OPDS 目录(用于兼容的阅读器应用)
GET http://localhost:6060/opds
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
public class GrimmoryClient {
private final OkHttpClient http = new OkHttpClient();
private final ObjectMapper mapper = new ObjectMapper();
private final String baseUrl;
private final String token;
public GrimmoryClient(String baseUrl, String token) {
this.baseUrl = baseUrl;
this.token = token;
}
public String getBooks() throws Exception {
Request request = new Request.Builder()
.url(baseUrl + "/api/v1/books")
.header("Authorization", "Bearer " + token)
.build();
try (Response response = http.newCall(request).execute()) {
return response.body().string();
}
}
}
@RestController
@RequestMapping("/api/v1/books")
@RequiredArgsConstructor
public class BookController {
private final BookService bookService;
@GetMapping
public ResponseEntity<Page<BookDto>> getAllBooks(
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size,
@RequestParam(required = false) String search) {
return ResponseEntity.ok(bookService.findAll(page, size, search));
}
@GetMapping("/{id}")
public ResponseEntity<BookDto> getBook(@PathVariable Long id) {
return ResponseEntity.ok(bookService.findById(id));
}
@PostMapping
public ResponseEntity<BookDto> createBook(@RequestBody @Valid CreateBookRequest request) {
return ResponseEntity.status(HttpStatus.CREATED)
.body(bookService.create(request));
}
@PutMapping("/{id}/metadata")
public ResponseEntity<BookDto> updateMetadata(
@PathVariable Long id,
@RequestBody @Valid UpdateMetadataRequest request) {
return ResponseEntity.ok(bookService.updateMetadata(id, request));
}
}
@Entity
@Table(name = "books")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Book {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false)
private String title;
private String author;
private String isbn;
private String format; // EPUB, PDF, CBZ, etc.
@Column(name = "file_path")
private String filePath;
@Column(name = "cover_path")
private String coverPath;
@Column(name = "reading_progress")
private Double readingProgress;
@ManyToMany
@JoinTable(
name = "book_shelf",
joinColumns = @JoinColumn(name = "book_id"),
inverseJoinColumns = @JoinColumn(name = "shelf_id")
)
private Set<Shelf> shelves = new HashSet<>();
@CreationTimestamp
private LocalDateTime createdAt;
@UpdateTimestamp
private LocalDateTime updatedAt;
}
@Service
@RequiredArgsConstructor
public class MetadataService {
private final GoogleBooksClient googleBooksClient;
private final OpenLibraryClient openLibraryClient;
private final BookRepository bookRepository;
public BookDto enrichMetadata(Long bookId) {
Book book = bookRepository.findById(bookId)
.orElseThrow(() -> new BookNotFoundException(bookId));
// 首先尝试 Google Books
Optional<BookMetadata> metadata = googleBooksClient.search(book.getTitle(), book.getAuthor());
// 回退到 Open Library
if (metadata.isEmpty()) {
metadata = openLibraryClient.search(book.getIsbn());
}
metadata.ifPresent(m -> {
book.setDescription(m.getDescription());
book.setCoverUrl(m.getCoverUrl());
book.setPublisher(m.getPublisher());
book.setPublishedDate(m.getPublishedDate());
bookRepository.save(book);
});
return BookDto.from(book);
}
}
使用以下地址连接任何兼容 OPDS 的阅读器应用(Kybook、Chunky、Moon+ Reader 等):
http://<您的服务器地址>:6060/opds
提示时,使用您的 Grimmory 用户名和密码进行身份验证。
从 http://localhost:6060 的管理面板创建用户。每个用户都有独立隔离的书架、阅读进度和偏好设置。
通过环境变量配置(有关 OIDC 特定变量,如 OIDC_ISSUER_URI、OIDC_CLIENT_ID、OIDC_CLIENT_SECRET,请参阅完整文档 https://grimmory.org/docs/getting-started)。
# 克隆仓库
git clone https://github.com/grimmory-tools/grimmory.git
cd grimmory
# 使用 Maven 构建
./mvnw clean package -DskipTests
# 或在本地构建 Docker 镜像
docker build -t grimmory:local .
# 在 docker-compose.yml 中使用本地构建
# 注释掉 'image' 并取消注释 'build: .'
# 启动服务
docker compose up -d
# 停止服务
docker compose down
# 查看应用日志
docker compose logs -f grimmory
# 查看数据库日志
docker compose logs -f mariadb
# 仅重启应用
docker compose restart grimmory
# 拉取最新镜像并重新部署
docker compose pull && docker compose up -d
# 在容器内打开 shell
docker exec -it grimmory /bin/bash
# 数据库 shell
docker exec -it mariadb mariadb -u grimmory -p grimmory
# 检查 MariaDB 健康状态
docker compose ps mariadb
# 应显示 "healthy"。如果没有:
docker compose logs mariadb
# 确保 DATABASE_URL 主机名与服务名称匹配:mariadb:3306
# 验证文件权限 — UID/GID 必须与 APP_USER_ID/APP_GROUP_ID 匹配
ls -la ./bookdrop/
# 检查应用日志中的检测事件
docker compose logs -f grimmory | grep -i bookdrop
# 设置所有权以匹配 APP_USER_ID / APP_GROUP_ID
sudo chown -R 1000:1000 ./books ./data ./bookdrop
# 确认端口 6060 可以从您的设备访问
curl http://<主机IP>:6060/api/v1/healthcheck
# 如果在远程服务器上,请检查防火墙规则
MariaDB 和 Grimmory 一起至少需要约 512 MB 内存。对于大型库(10k+ 图书),请分配 1–2 GB。
Google Books 和 Open Library 要求容器具有出站互联网访问权限。验证 DNS 和网络:
docker exec -it grimmory curl -s "https://www.googleapis.com/books/v1/volumes?q=test"
在提交拉取请求之前:
CONTRIBUTING.md 中的后端和前端约定# 提交前运行测试
./mvnw test
# 检查代码风格
./mvnw checkstyle:check
ghcr.io/grimmory-tools/grimmory每周安装次数
227
仓库
GitHub 星标数
10
首次出现
6 天前
安全审计
安装于
github-copilot226
codex226
warp226
amp226
cline226
kimi-cli226
Skill by ara.so — Daily 2026 Skills collection.
Grimmory is a self-hosted application (successor to BookLore) for managing your entire book collection. It supports EPUBs, PDFs, MOBIs, AZW/AZW3, and comics (CBZ/CBR/CB7), with a built-in browser reader, annotations, Kobo/OPDS sync, KOReader progress sync, metadata enrichment, and multi-user support.
.env# Application
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC
# Database
DATABASE_URL=jdbc:mariadb://mariadb:3306/grimmory
DB_USER=grimmory
DB_PASSWORD=${DB_PASSWORD}
# Storage: LOCAL (default) or NETWORK
DISK_TYPE=LOCAL
# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
MYSQL_DATABASE=grimmory
docker-compose.ymlservices:
grimmory:
image: grimmory/grimmory:latest
# Alternative registry: ghcr.io/grimmory-tools/grimmory:latest
container_name: grimmory
environment:
- USER_ID=${APP_USER_ID}
- GROUP_ID=${APP_GROUP_ID}
- TZ=${TZ}
- DATABASE_URL=${DATABASE_URL}
- DATABASE_USERNAME=${DB_USER}
- DATABASE_PASSWORD=${DB_PASSWORD}
- DISK_TYPE=${DISK_TYPE}
depends_on:
mariadb:
condition: service_healthy
ports:
- "6060:6060"
volumes:
- ./data:/app/data
- ./books:/books
- ./bookdrop:/bookdrop
healthcheck:
test: wget -q -O - http://localhost:6060/api/v1/healthcheck
interval: 60s
retries: 5
start_period: 60s
timeout: 10s
restart: unless-stopped
mariadb:
image: lscr.io/linuxserver/mariadb:11.4.5
container_name: mariadb
environment:
- PUID=${DB_USER_ID}
- PGID=${DB_GROUP_ID}
- TZ=${TZ}
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
- MYSQL_DATABASE=${MYSQL_DATABASE}
- MYSQL_USER=${DB_USER}
- MYSQL_PASSWORD=${DB_PASSWORD}
volumes:
- ./mariadb/config:/config
restart: unless-stopped
healthcheck:
test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
interval: 5s
timeout: 5s
retries: 10
docker compose up -d
# View logs
docker compose logs -f grimmory
# Check health
curl http://localhost:6060/api/v1/healthcheck
Open http://localhost:6060 and create your admin account.
./data/ # App data, thumbnails, user config
./books/ # Your book files (mounted at /books)
./bookdrop/ # Drop-zone for auto-import (mounted at /bookdrop)
./mariadb/ # MariaDB data
| Variable | Description | Default |
|---|---|---|
USER_ID | UID for the app process | 1000 |
GROUP_ID | GID for the app process | 1000 |
TZ | Timezone string | Etc/UTC |
DATABASE_URL |
| Category | Formats |
|---|---|
| eBooks | EPUB, MOBI, AZW, AZW3 |
| Documents | |
| Comics | CBZ, CBR, CB7 |
Drop files into ./bookdrop/ on your host. Grimmory watches the folder, extracts metadata from Google Books and Open Library, and queues books for review.
./bookdrop/
my-novel.epub ← dropped here
another-book.pdf ← dropped here
Flow:
/bookdrop continuouslyVolume mapping required in docker-compose.yml:
volumes:
- ./bookdrop:/bookdrop
For NFS, SMB, or other network-mounted filesystems, set DISK_TYPE=NETWORK. This disables destructive UI operations (delete, move, rename) to protect shared mounts while keeping reading, metadata, and sync fully functional.
# .env
DISK_TYPE=NETWORK
Grimmory is a Java application (Spring Boot + MariaDB). When contributing or extending:
src/main/java/
com/grimmory/
config/ # Spring configuration classes
controller/ # REST API controllers
service/ # Business logic
repository/ # JPA repositories
model/ # JPA entities
dto/ # Data transfer objects
All endpoints are under /api/v1/:
# Health check
GET http://localhost:6060/api/v1/healthcheck
# Books
GET http://localhost:6060/api/v1/books
GET http://localhost:6060/api/v1/books/{id}
POST http://localhost:6060/api/v1/books
PUT http://localhost:6060/api/v1/books/{id}
DELETE http://localhost:6060/api/v1/books/{id}
# Shelves
GET http://localhost:6060/api/v1/shelves
POST http://localhost:6060/api/v1/shelves
# OPDS catalog (for compatible reader apps)
GET http://localhost:6060/opds
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
public class GrimmoryClient {
private final OkHttpClient http = new OkHttpClient();
private final ObjectMapper mapper = new ObjectMapper();
private final String baseUrl;
private final String token;
public GrimmoryClient(String baseUrl, String token) {
this.baseUrl = baseUrl;
this.token = token;
}
public String getBooks() throws Exception {
Request request = new Request.Builder()
.url(baseUrl + "/api/v1/books")
.header("Authorization", "Bearer " + token)
.build();
try (Response response = http.newCall(request).execute()) {
return response.body().string();
}
}
}
@RestController
@RequestMapping("/api/v1/books")
@RequiredArgsConstructor
public class BookController {
private final BookService bookService;
@GetMapping
public ResponseEntity<Page<BookDto>> getAllBooks(
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size,
@RequestParam(required = false) String search) {
return ResponseEntity.ok(bookService.findAll(page, size, search));
}
@GetMapping("/{id}")
public ResponseEntity<BookDto> getBook(@PathVariable Long id) {
return ResponseEntity.ok(bookService.findById(id));
}
@PostMapping
public ResponseEntity<BookDto> createBook(@RequestBody @Valid CreateBookRequest request) {
return ResponseEntity.status(HttpStatus.CREATED)
.body(bookService.create(request));
}
@PutMapping("/{id}/metadata")
public ResponseEntity<BookDto> updateMetadata(
@PathVariable Long id,
@RequestBody @Valid UpdateMetadataRequest request) {
return ResponseEntity.ok(bookService.updateMetadata(id, request));
}
}
@Entity
@Table(name = "books")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Book {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false)
private String title;
private String author;
private String isbn;
private String format; // EPUB, PDF, CBZ, etc.
@Column(name = "file_path")
private String filePath;
@Column(name = "cover_path")
private String coverPath;
@Column(name = "reading_progress")
private Double readingProgress;
@ManyToMany
@JoinTable(
name = "book_shelf",
joinColumns = @JoinColumn(name = "book_id"),
inverseJoinColumns = @JoinColumn(name = "shelf_id")
)
private Set<Shelf> shelves = new HashSet<>();
@CreationTimestamp
private LocalDateTime createdAt;
@UpdateTimestamp
private LocalDateTime updatedAt;
}
@Service
@RequiredArgsConstructor
public class MetadataService {
private final GoogleBooksClient googleBooksClient;
private final OpenLibraryClient openLibraryClient;
private final BookRepository bookRepository;
public BookDto enrichMetadata(Long bookId) {
Book book = bookRepository.findById(bookId)
.orElseThrow(() -> new BookNotFoundException(bookId));
// Try Google Books first
Optional<BookMetadata> metadata = googleBooksClient.search(book.getTitle(), book.getAuthor());
// Fall back to Open Library
if (metadata.isEmpty()) {
metadata = openLibraryClient.search(book.getIsbn());
}
metadata.ifPresent(m -> {
book.setDescription(m.getDescription());
book.setCoverUrl(m.getCoverUrl());
book.setPublisher(m.getPublisher());
book.setPublishedDate(m.getPublishedDate());
bookRepository.save(book);
});
return BookDto.from(book);
}
}
Connect any OPDS-compatible reader app (Kybook, Chunky, Moon+ Reader, etc.) using:
http://<your-host>:6060/opds
Authenticate with your Grimmory username and password when prompted.
Create users from the admin panel at http://localhost:6060. Each user has isolated shelves, reading progress, and preferences.
Configure via environment variables (refer to full documentation at https://grimmory.org/docs/getting-started for OIDC-specific variables such as OIDC_ISSUER_URI, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET).
# Clone the repository
git clone https://github.com/grimmory-tools/grimmory.git
cd grimmory
# Build with Maven
./mvnw clean package -DskipTests
# Or build Docker image locally
docker build -t grimmory:local .
# Use local build in docker-compose.yml
# Comment out 'image' and uncomment 'build: .'
# Start services
docker compose up -d
# Stop services
docker compose down
# View app logs
docker compose logs -f grimmory
# View DB logs
docker compose logs -f mariadb
# Restart only the app
docker compose restart grimmory
# Pull latest image and redeploy
docker compose pull && docker compose up -d
# Open a shell inside the container
docker exec -it grimmory /bin/bash
# Database shell
docker exec -it mariadb mariadb -u grimmory -p grimmory
# Check MariaDB health
docker compose ps mariadb
# Should show "healthy". If not:
docker compose logs mariadb
# Ensure DATABASE_URL host matches the service name: mariadb:3306
# Verify file permissions — UID/GID must match APP_USER_ID/APP_GROUP_ID
ls -la ./bookdrop/
# Check app logs for detection events
docker compose logs -f grimmory | grep -i bookdrop
# Set ownership to match APP_USER_ID / APP_GROUP_ID
sudo chown -R 1000:1000 ./books ./data ./bookdrop
# Confirm port 6060 is reachable from your device
curl http://<host-ip>:6060/api/v1/healthcheck
# Check firewall rules if on a remote server
MariaDB and Grimmory together require at minimum ~512 MB RAM. For large libraries (10k+ books), allocate 1–2 GB.
Google Books and Open Library require outbound internet access from the container. Verify DNS and network:
docker exec -it grimmory curl -s "https://www.googleapis.com/books/v1/volumes?q=test"
Before opening a pull request:
CONTRIBUTING.md# Run tests before submitting
./mvnw test
# Check code style
./mvnw checkstyle:check
ghcr.io/grimmory-tools/grimmoryWeekly Installs
227
Repository
GitHub Stars
10
First Seen
6 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
github-copilot226
codex226
warp226
amp226
cline226
kimi-cli226
客户调研技能指南:多源调研方法、来源优先级与答案置信度评估
524 周安装
| JDBC connection string |
| required |
DATABASE_USERNAME | DB username | required |
DATABASE_PASSWORD | DB password | required |
DISK_TYPE | LOCAL or NETWORK | LOCAL |