Komga数据库权限问题排查与解决方案

问题背景

Komga是一款优秀的漫画和电子书管理服务，在使用Docker部署时可能会遇到数据库权限问题。本文详细分析了一个典型的SQLite数据库只读错误案例，并提供了完整的解决方案。

错误现象

用户在使用Komga时突然遇到服务无法启动的问题，查看日志发现以下关键错误信息：

Caused by: org.sqlite.SQLiteException: [SQLITE_READONLY] Attempt to write a readonly database (attempt to write a readonly database)

这个错误表明Komga无法写入SQLite数据库文件，通常是由于文件系统权限配置不当导致的。

根本原因分析

经过深入排查，发现该问题由两个因素共同导致：

1. 文件权限问题：Docker容器内的用户(UID 998)对挂载的数据库文件没有写入权限
2. 端口映射错误：用户配置了错误的容器端口映射(9080:8080)，而Komga实际监听的是25600端口

解决方案

第一步：修复文件权限

1. 确保挂载的目录和文件具有正确的所有权和权限
2. 建议手动创建必要的目录结构：

   mkdir -p /path/to/config
   touch /path/to/config/database.sqlite
   mkdir -p /path/to/data
   

3. 设置正确的权限：

   chown -R 998:100 /path/to/config /path/to/data
   chmod -R 755 /path/to/config /path/to/data
   

第二步：修正端口映射

在docker-compose.yml中，正确的端口映射应该是：

ports:
  - 9080:25600

第三步：完整配置示例

以下是经过验证的正确配置示例：

version: '3.3'
services:
  komga:
    image: gotson/komga
    container_name: komga
    volumes:
      - /path/to/config:/config
      - /path/to/data:/data
      - /path/to/comics:/comics
    ports:
      - 9080:25600
    user: "998:100"
    restart: unless-stopped

预防措施

1. 定期检查Docker挂载卷的权限设置
2. 在更新Komga版本时，注意查看官方文档是否有配置变更
3. 使用docker-compose config命令验证配置文件语法
4. 监控日志文件，及时发现潜在问题

总结

Komga的数据库权限问题通常源于不正确的文件系统权限或配置错误。通过正确设置文件权限和端口映射，可以确保服务稳定运行。建议用户在部署前仔细阅读官方文档，并遵循最佳实践进行配置。