Komga 隐私策略技术解读:自托管数据本地化与认证活动记录的采集、留存与自动清理

原创2026-10-14 10:29:121,709 阅读
文章标签:后端

Komga 隐私策略技术解读:自托管数据本地化与认证活动记录的采集、留存与自动清理

Komga 是一款自托管(self-hosted)的漫画/电子书媒体服务器,其官方隐私策略(PRIVACY.md)明确了两个核心承诺:所有数据仅存储在本机 SQLite 数据库中、绝不向承载机器之外传输;认证尝试产生的 IP 地址与 User-Agent 仅保留一个月后自动删除。本文将结合仓库源码,逐条拆解这两项隐私承诺背后的实现机制,包括认证活动数据模型的字段构成、本地数据库的存储方式、定时清理任务的调度细节,以及用户通过 REST API 查看自己认证记录的完整方法,帮助你理解自托管场景下 Komga 的数据边界到底在哪里。

一、隐私设计定位:纯自托管,数据不出本机

PRIVACY.md 开篇即给出整个隐私策略的前提:

Komga is a self-hosted application. It does not transmit any data outside the machine hosting it.

这句话可以拆解为两层含义:

  1. 部署形态是自托管:Komga 运行在你自己的服务器/本机上,而不是托管在第三方云服务中,因此不存在"数据上云"的默认行为。
  2. 数据边界是本机:应用运行所需的数据——用户、元数据、阅读进度、认证记录等——全部写入本地数据库文件,由部署者自己掌控。

这一设计在源码中得到了直接印证:Komga 的主数据源通过 jdbc:sqlite: 连接本地 SQLite 文件,见 DataSourcesConfiguration.kt:

val dataSource =
  DataSourceBuilder
    .create()
    .driverClassName("org.sqlite.JDBC")
    .url("jdbc:sqlite:${databaseProps.file}$extraPragmas")
    .type(dataSourceClass)
    .build()

数据库文件路径、连接池大小、WAL 日志模式、busy timeout 等均可通过 komga.database.* 配置项调整(KomgaProperties.kt)。也就是说,隐私策略中"数据存储在本地 SQLite 数据库中"并非抽象承诺,而是架构层面的既定事实:数据库文件就在服务器本机的磁盘上,与外部网络没有数据通道。

二、数据采集范围:只采两类数据

PRIVACY.md 将采集的数据严格划分为两类,除此之外没有其他隐式采集。需要特别注意的是,文档措辞用了 "collected"(采集),其语义是"应用为正常运行而存储的数据",与第三方跟踪式采集有本质区别。

2.1 用户主动提供的信息:邮箱(创建账号必需)

文档原文:

Email address: required to create an account

邮箱是唯一被标记为"用户主动提供"的数据项,且用途明确——创建账号的必填项。源码中的用户创建流程(UserController.kt)调用了 KomgaUserLifecycle.createUser,构造 KomgaUser(email, password, roles = ...),其中 email 是账号实体的必填字段;KomgaUserLifecycle.kt 还会通过 existsByEmailIgnoreCase 做唯一性校验,防止重复注册。

值得补充的一点:Komga 对密码并非明文存储,而是经 passwordEncoder.encode(newPassword) 哈希后入库(KomgaUserLifecycle.kt),这虽然不在 PRIVACY.md 的字面清单中,但从隐私视角看,账号相关数据的"最小化与保护"同样落到了实现层面。

2.2 自动采集的信息:认证连接的 IP 与 User-Agent

文档原文:

IP address and User-Agent of authentication connections: stored in the local database during authentication attempts. That information is automatically deleted after one month.

这是整个隐私策略的技术核心,包含两个要点:采集时机(每次认证尝试)与留存期限(一个月,自动删除)。其实现横跨"事件监听 → 数据建模 → 持久化 → 定时清理"四条链路。

采集时机:每次登录成功与失败

认证活动的写入由 LoginListener.kt 完成。它通过 Spring Security 的事件监听机制,同时处理两类事件:

  • AuthenticationSuccessEvent(登录成功);
  • AbstractAuthenticationFailureEvent(登录失败,其中 AuthenticationFailureProviderNotFoundEvent 会被丢弃,避免同一失败产生重复记录)。

对每次认证尝试,监听器都会组装一条 AuthenticationActivity 记录并写入数据库,包含 IP、User-Agent、成功/失败状态及失败原因。

数据模型:一条记录承载哪些字段

认证活动记录的字段定义见 AuthenticationActivity.kt,可整理为下表:

字段 类型 说明
userId String? 关联用户 ID;失败尝试且无法匹配用户时可能为空
email String? 尝试登录的邮箱(失败时来自 principal 字符串)
apiKeyId String? 使用 API Key 认证时对应的 Key ID
apiKeyComment String? 使用 API Key 认证时的 Key 备注
ip String? 连接来源 IP 地址
userAgent String? 发起认证的客户端 User-Agent
success Boolean 认证是否成功
error String? 失败时的异常信息(成功时为空)
dateTime LocalDateTime 认证发生时间(默认当前时间)
source String? 认证来源类型

其中 source 字段非常能说明 Komga 对"认证连接"的覆盖面,由 LoginListener.kt 根据认证令牌类型判定:

  • Password:用户名/密码登录;
  • RememberMe:记住登录状态;
  • ApiKey:API Key 认证(如第三方客户端接入);
  • OAuth2:<客户端名称>:OAuth2/OIDC 外部身份提供商登录。

也就是说,无论用户通过网页表单、API Key 还是 OAuth2 登录,其认证尝试的 IP 与 User-Agent 都会被记录——这正是文档所称 "during authentication attempts" 的完整范围。

三、数据存储:写入本地 SQLite 的专属表

认证活动数据与 Komga 的其他业务数据一样,落在本地 SQLite 数据库中。其表结构由 Flyway 迁移脚本定义:

持久化层的写入实现位于 AuthenticationActivityDao.kt,通过 jOOQ 将整条记录(含 IP、User-Agent、成功状态等全部字段)插入表中。数据落库后,除非用户主动删除或触发自动清理,否则一直保留在本机数据库中——它不会离开这台机器,这正是 PRIVACY.md 中 "never leaves your machine" 的直接体现。

四、自动清理机制:一个月后自动删除

文档承诺的"自动删除"并非一次性逻辑,而是一个每天运行一次的定时任务,实现位于 AuthenticationActivityCleanupController.kt:

// Run every day
@Scheduled(fixedRate = 86_400_000)
fun cleanup() {
  val olderThan = LocalDateTime.now(ZoneId.of("Z")).minusMonths(1)
  logger.info { "Remove authentication activity older than $olderThan (UTC)" }
  authenticationActivityRepository.deleteOlderThan(olderThan)
}

逐行解读其语义:

  • @Scheduled(fixedRate = 86_400_000):以 86,400,000 毫秒(即 24 小时)为固定周期,每天执行一次清理;
  • LocalDateTime.now(ZoneId.of("Z")).minusMonths(1):以 UTC 时间为基准,计算"一个月前"的时间戳,作为删除阈值;
  • deleteOlderThan(olderThan):删除所有 dateTime 早于该阈值(即超过一个月)的记录。

删除的 SQL 实现见 AuthenticationActivityDao.kt:

override fun deleteOlderThan(dateTime: LocalDateTime) {
  dslRW
    .deleteFrom(aa)
    .where(aa.DATE_TIME.lt(dateTime))
    .execute()
}

这意味着:任何一条认证活动记录(无论成功与否)的"保质期"最多为一个月,超过即被下一次每日清理任务删除。需要留意的是,该任务标注了 @Profile("!test"),即生产环境默认启用、测试环境排除。

除自动清理外,还有一条主动删除路径:当管理员删除某个用户账号时,KomgaUserLifecycle.deleteUser 会在同一事务内调用 authenticationActivityRepository.deleteByUser(user),将该用户的认证活动记录一并删除,避免数据残留。

五、用户如何查看与掌握自己的认证活动数据

隐私不仅关乎"存了什么",也关乎"你能不能看到"。Komga 通过 REST API 将认证活动数据开放给用户自查:

  • GET /api/v2/users/me/authentication-activity:当前登录用户查看自己的认证活动记录(UserController.kt);
  • GET /api/v2/users/authentication-activity:管理员查看全体用户的认证活动记录(UserController.kt);
  • GET /api/v2/users/{id}/authentication-activity/latest:查看某用户最近一次认证活动,可通过 apikey_id 参数按 API Key 过滤(UserController.kt)。

接口默认按 dateTime 降序排列,支持 page/pageSize 分页以及 unpaged 参数,返回的 DTO 字段与数据库记录一一对应,时间戳统一转为 UTC 并格式化为 yyyy-MM-dd'T'HH:mm:ss'Z'(见 AuthenticationActivityDto.kt)。在 Web 界面上,普通用户可通过"账户 → 认证活动"页面(对应前端视图 SelfAuthenticationActivity.vue)直观查看自己的登录历史。这意味着"记录了 IP 与 User-Agent"是完全透明的:任何用户都能看到谁在何时、以何种方式登录过自己的账号。

六、自托管环境下的隐私实践建议

结合 PRIVACY.md 的承诺与源码实现,可以给出几条实操层面的注意事项:

  1. 备份即数据边界:由于所有数据(含认证活动)只存在于本机 SQLite 数据库文件,备份该数据库文件就等于备份全部用户数据;反之,数据库文件的物理安全直接决定了隐私安全,建议部署者按自托管惯例做好文件权限与备份管理。
  2. 一个月留存是上限而非下限:清理任务每 24 小时运行一次,删除的是超过一个月(UTC)的记录;如果你希望更早清除,可以手动调用 DELETE 语义的运维操作或直接清理数据库表,但这不在标准配置项范围内。
  3. 反向代理场景下的 IP 语义:从源码看,IP 取自 Spring Security 的 WebAuthenticationDetails.remoteAddress,User-Agent 取自 UserAgentWebAuthenticationDetails(LoginListener.kt)。如果 Komga 部署在反向代理之后,记录的可能是代理服务器的地址而非客户端真实 IP,这属于自托管部署的通用现象,理解其语义有助于正确解读认证记录。
  4. 隐私条款与实现以当前仓库为准:本文所有结论均来自当前仓库的 PRIVACY.md 与对应源码、迁移脚本;若版本升级,建议以对应版本仓库中的文档与代码为准重新核对数据采集范围与留存策略。

小结

Komga 的隐私策略可以被概括为一句可验证的技术陈述:应用只采集创建账号所需的邮箱与认证连接产生的 IP/User-Agent 两类数据,全部落入本机 SQLite 数据库,认证活动记录在 24 小时周期的定时任务下于一个月后自动清除,且全程无数据外传。从 AuthenticationActivity.kt 的字段设计、LoginListener.kt 的事件采集,到 AuthenticationActivityCleanupController.kt 的定时清理,再到 UserController.kt 的查询接口,整条链路完整闭环、全程可控,这正是自托管应用"数据主权在自己手里"的典型实践。

登录后查看全文
komga