Karakeep 自托管用户管理实战密码重置、管理员授权与禁用注册后的用户创建【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder本指南聚焦 Karakeep原 Hoarder自托管部署中的用户管理三大高频问题忘记密码时如何恢复、如何将普通用户提升为管理员以及在关闭公开注册后如何继续创建新账号。文章以 v0.30.0 版本的官方 FAQ 为骨架结合仓库内packages/trpc的路由与模型实现带你既会照着操作也明白每一步背后的存储与鉴权原理。背景Karakeep 的用户角色与密码存储模型在进入具体操作前先理解 Karakeep 的用户体系这能帮助你判断该走哪条恢复路径用户表user中通过role字段区分admin与user两种角色role为空的用户按普通用户对待相关定义见 schema.ts密码并非明文存储而是通过 bcrypt 加盐哈希后写入password字段盐值保存在独立的salt字段中哈希逻辑见 auth.ts注册/重置时调用的校验函数validatePassword会执行bcrypt.compare(password salt, user.password)也就是说最终校验的是密码 盐拼接后的哈希结果见 auth.ts。理解这一点后就不难明白官方 FAQ 提供的那条 SQL 之所以把salt清空就是为了让明文密码 空盐能够匹配上预设的 bcrypt 哈希。忘记密码普通用户的恢复路径如果你不是管理员Karakeep 的恢复流程是找管理员帮你重置而不是自行处理登录任意管理员账号进入Admin Settings管理设置页面在Users List用户列表中找到目标用户在Actions操作列中点击重置密码按钮输入新密码并点击Reset重置新密码即刻生效用户可以立即登录出于隐私考虑登录后可在User Settings用户设置中再次修改密码这样管理员也并不知道你最终使用的密码。这条路径背后的接口是管理端 tRPC 路由adminAppRouter.resetPassword其实现位于 routers/admin.ts。值得注意的源码细节是管理员不能重置自己的密码——如果ctx.user.id input.userId接口会直接抛出BAD_REQUESTCannot reset own password这正是为什么管理员忘记密码必须走下面的数据库方案。此外重置时会调用generatePasswordSalt()生成新的 32 字节随机盐并用hashPassword(input.newPassword, newSalt)重新哈希后写入数据库整个过程是服务端标准的安全实践。忘记密码管理员直接改数据库的完整步骤如果你自己就是唯一的管理员且已经无法登录就只能绕过应用层直接修改 SQLite 数据库。Karakeep 的数据库文件为db.db存放在数据目录中在 Docker 部署下该目录对应容器内挂载的/data见 docker-compose.yml 中的data:/data卷映射DATA_DIR环境变量即指向此目录说明见 环境变量文档。完整操作流程如下准备数据库工具Linux 下可用sqlite3例如 Debian/Ubuntu 系执行apt-get install sqlite3具体命令取决于你的包管理器Windows 下可使用图形化工具例如dbeaver。停止 Karakeep 服务必须先在数据目录中停掉应用避免运行中的进程在修改期间向数据库写入数据。连接数据库在数据目录中执行sqlite3 db.db或用dbeaver通过 UI 定位到 data 目录下的db.db文件并连接。执行密码更新 SQL运行以下语句务必把YOUR_EMAIL_HERE替换成你自己的邮箱update user set password$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa, salt where emailYOUR_EMAIL_HERE;这条语句做了两件事将password字段替换为预生成的 bcrypt 哈希同时把salt置为空字符串。根据 auth.ts 的哈希规则该哈希对应的明文密码为adminadmin。重启 Karakeep用你的邮箱和密码adminadmin登录。登录成功后立即改密进入User Settings把密码修改为任意你想要的强密码完成整个恢复流程。原理说明为什么这条 SQL 能生效从源码看密码校验链路是bcrypt.compare(password (user.salt ?? ), user.password)auth.ts。SQL 将salt置空后校验等式退化为bcrypt.compare(adminadmin, $2a$10$5u40XUq/...)而该哈希正是adminadmin在成本因子 10 下的 bcrypt 结果BCRYPT_SALT_ROUNDS 10见 auth.ts因此登录成功。这也解释了为什么不能只改password而不动salt——盐不匹配时同样的哈希无法通过校验。添加另一位管理员Karakeep 的管理员机制有一个默认行为第一个注册的用户会自动被提升为管理员。这一逻辑可以在用户模型的createRaw方法中找到依据创建用户时若表中用户数为 0则角色被设置为admin见 models/users.ts。如果你想授予其他用户管理员权限以管理员身份进入Admin Settings页面在Users List中找到目标用户在Actions列点击修改角色Role的按钮将角色改为Admin并点击Change更改该用户需要退出登录并重新登录新的角色才会生效。角色变更由管理路由adminAppRouter.updateUser完成源码位于 routers/admin.ts。该接口同样禁止修改自己的角色Cannot update own user并且支持在同一个接口里调整用户的bookmarkQuota、storageQuota、browserCrawlingEnabled等配额与权限字段管理员面板的角色按钮只是其中一种用法。禁用公开注册后如何添加新用户很多自托管部署会在配置中关闭公开注册仅保留内部成员使用。此时普通用户无法自行注册但管理员随时可以通过后台创建账号进入Admin Settings页面切换到Users List点击Create User创建用户按钮填写用户信息姓名、邮箱、初始密码等点击create创建新用户即可使用该凭据登录。对应的后台接口是adminAppRouter.createUser见 routers/admin.ts它最终调用User.create完成落库models/users.ts。源码层面有两点值得注意若部署时开启了邮箱验证auth.emailVerificationRequired配置项创建用户时会顺带生成验证令牌并发送验证邮件新用户在完成邮箱验证前登录能力会受限创建时邮箱字段具有唯一约束若邮箱已被占用底层会抛出SQLITE_CONSTRAINT_UNIQUE并被转换为 Email is already taken 的友好错误models/users.ts因此你无法通过该入口为已存在用户创建重复账号。安全注意事项与最佳实践结合官方 FAQ 与源码实现以下是几个容易被忽略的关键点数据库直改密码后必须立刻改密adminadmin是公开文档中公开的默认值任何能接触数据库或日志的人都可能尝试用它登录恢复成功后第一步永远是去User Settings修改密码修改数据库前务必停服SQLite 在同一进程写入时若被外部工具并发修改可能造成锁冲突或数据损坏且应用内存中可能缓存了旧的用户状态不要重置自己的密码应用层接口管理员重置、角色变更均禁止操作自身账号这是刻意的安全设计防止管理员误操作锁死唯一管理员也提醒你提前为团队配置至少两个管理员账号角色变更需要重新登录权限在会话建立时即已确定提升角色后让对方重新登录才能确保新权限在 Web 端、移动端与 API 会话中一致生效若开启了 OAuth 登录部分账号可能没有本地密码password字段为空这类账号在 validatePassword 中会直接拒绝密码登录应走正常的 OAuth 流程而非数据库改密。总结Karakeep 的用户管理在设计上区分了应用层操作与数据库兜底两级恢复手段普通用户密码丢失由管理员在后台一键重置唯一管理员密码丢失则通过 sqlite 直改user表完成。同时角色提升与账号创建都集中在Admin Settings中配合首用户自动成为管理员的默认策略单管理员自托管也能顺畅地把权限与账号管理交接出去。理解了 bcrypt 加盐哈希与user表字段结构你就能在遇到类似问题时举一反三安全地完成各类恢复操作。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Karakeep 自托管用户管理实战：密码重置、管理员授权与禁用注册后的用户创建
Karakeep 自托管用户管理实战密码重置、管理员授权与禁用注册后的用户创建【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder本指南聚焦 Karakeep原 Hoarder自托管部署中的用户管理三大高频问题忘记密码时如何恢复、如何将普通用户提升为管理员以及在关闭公开注册后如何继续创建新账号。文章以 v0.30.0 版本的官方 FAQ 为骨架结合仓库内packages/trpc的路由与模型实现带你既会照着操作也明白每一步背后的存储与鉴权原理。背景Karakeep 的用户角色与密码存储模型在进入具体操作前先理解 Karakeep 的用户体系这能帮助你判断该走哪条恢复路径用户表user中通过role字段区分admin与user两种角色role为空的用户按普通用户对待相关定义见 schema.ts密码并非明文存储而是通过 bcrypt 加盐哈希后写入password字段盐值保存在独立的salt字段中哈希逻辑见 auth.ts注册/重置时调用的校验函数validatePassword会执行bcrypt.compare(password salt, user.password)也就是说最终校验的是密码 盐拼接后的哈希结果见 auth.ts。理解这一点后就不难明白官方 FAQ 提供的那条 SQL 之所以把salt清空就是为了让明文密码 空盐能够匹配上预设的 bcrypt 哈希。忘记密码普通用户的恢复路径如果你不是管理员Karakeep 的恢复流程是找管理员帮你重置而不是自行处理登录任意管理员账号进入Admin Settings管理设置页面在Users List用户列表中找到目标用户在Actions操作列中点击重置密码按钮输入新密码并点击Reset重置新密码即刻生效用户可以立即登录出于隐私考虑登录后可在User Settings用户设置中再次修改密码这样管理员也并不知道你最终使用的密码。这条路径背后的接口是管理端 tRPC 路由adminAppRouter.resetPassword其实现位于 routers/admin.ts。值得注意的源码细节是管理员不能重置自己的密码——如果ctx.user.id input.userId接口会直接抛出BAD_REQUESTCannot reset own password这正是为什么管理员忘记密码必须走下面的数据库方案。此外重置时会调用generatePasswordSalt()生成新的 32 字节随机盐并用hashPassword(input.newPassword, newSalt)重新哈希后写入数据库整个过程是服务端标准的安全实践。忘记密码管理员直接改数据库的完整步骤如果你自己就是唯一的管理员且已经无法登录就只能绕过应用层直接修改 SQLite 数据库。Karakeep 的数据库文件为db.db存放在数据目录中在 Docker 部署下该目录对应容器内挂载的/data见 docker-compose.yml 中的data:/data卷映射DATA_DIR环境变量即指向此目录说明见 环境变量文档。完整操作流程如下准备数据库工具Linux 下可用sqlite3例如 Debian/Ubuntu 系执行apt-get install sqlite3具体命令取决于你的包管理器Windows 下可使用图形化工具例如dbeaver。停止 Karakeep 服务必须先在数据目录中停掉应用避免运行中的进程在修改期间向数据库写入数据。连接数据库在数据目录中执行sqlite3 db.db或用dbeaver通过 UI 定位到 data 目录下的db.db文件并连接。执行密码更新 SQL运行以下语句务必把YOUR_EMAIL_HERE替换成你自己的邮箱update user set password$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa, salt where emailYOUR_EMAIL_HERE;这条语句做了两件事将password字段替换为预生成的 bcrypt 哈希同时把salt置为空字符串。根据 auth.ts 的哈希规则该哈希对应的明文密码为adminadmin。重启 Karakeep用你的邮箱和密码adminadmin登录。登录成功后立即改密进入User Settings把密码修改为任意你想要的强密码完成整个恢复流程。原理说明为什么这条 SQL 能生效从源码看密码校验链路是bcrypt.compare(password (user.salt ?? ), user.password)auth.ts。SQL 将salt置空后校验等式退化为bcrypt.compare(adminadmin, $2a$10$5u40XUq/...)而该哈希正是adminadmin在成本因子 10 下的 bcrypt 结果BCRYPT_SALT_ROUNDS 10见 auth.ts因此登录成功。这也解释了为什么不能只改password而不动salt——盐不匹配时同样的哈希无法通过校验。添加另一位管理员Karakeep 的管理员机制有一个默认行为第一个注册的用户会自动被提升为管理员。这一逻辑可以在用户模型的createRaw方法中找到依据创建用户时若表中用户数为 0则角色被设置为admin见 models/users.ts。如果你想授予其他用户管理员权限以管理员身份进入Admin Settings页面在Users List中找到目标用户在Actions列点击修改角色Role的按钮将角色改为Admin并点击Change更改该用户需要退出登录并重新登录新的角色才会生效。角色变更由管理路由adminAppRouter.updateUser完成源码位于 routers/admin.ts。该接口同样禁止修改自己的角色Cannot update own user并且支持在同一个接口里调整用户的bookmarkQuota、storageQuota、browserCrawlingEnabled等配额与权限字段管理员面板的角色按钮只是其中一种用法。禁用公开注册后如何添加新用户很多自托管部署会在配置中关闭公开注册仅保留内部成员使用。此时普通用户无法自行注册但管理员随时可以通过后台创建账号进入Admin Settings页面切换到Users List点击Create User创建用户按钮填写用户信息姓名、邮箱、初始密码等点击create创建新用户即可使用该凭据登录。对应的后台接口是adminAppRouter.createUser见 routers/admin.ts它最终调用User.create完成落库models/users.ts。源码层面有两点值得注意若部署时开启了邮箱验证auth.emailVerificationRequired配置项创建用户时会顺带生成验证令牌并发送验证邮件新用户在完成邮箱验证前登录能力会受限创建时邮箱字段具有唯一约束若邮箱已被占用底层会抛出SQLITE_CONSTRAINT_UNIQUE并被转换为 Email is already taken 的友好错误models/users.ts因此你无法通过该入口为已存在用户创建重复账号。安全注意事项与最佳实践结合官方 FAQ 与源码实现以下是几个容易被忽略的关键点数据库直改密码后必须立刻改密adminadmin是公开文档中公开的默认值任何能接触数据库或日志的人都可能尝试用它登录恢复成功后第一步永远是去User Settings修改密码修改数据库前务必停服SQLite 在同一进程写入时若被外部工具并发修改可能造成锁冲突或数据损坏且应用内存中可能缓存了旧的用户状态不要重置自己的密码应用层接口管理员重置、角色变更均禁止操作自身账号这是刻意的安全设计防止管理员误操作锁死唯一管理员也提醒你提前为团队配置至少两个管理员账号角色变更需要重新登录权限在会话建立时即已确定提升角色后让对方重新登录才能确保新权限在 Web 端、移动端与 API 会话中一致生效若开启了 OAuth 登录部分账号可能没有本地密码password字段为空这类账号在 validatePassword 中会直接拒绝密码登录应走正常的 OAuth 流程而非数据库改密。总结Karakeep 的用户管理在设计上区分了应用层操作与数据库兜底两级恢复手段普通用户密码丢失由管理员在后台一键重置唯一管理员密码丢失则通过 sqlite 直改user表完成。同时角色提升与账号创建都集中在Admin Settings中配合首用户自动成为管理员的默认策略单管理员自托管也能顺畅地把权限与账号管理交接出去。理解了 bcrypt 加盐哈希与user表字段结构你就能在遇到类似问题时举一反三安全地完成各类恢复操作。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考