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自托管书签管理应用v0.33.0 的官方 FAQ 文档docs/versioned_docs/version-v0.33.0/06-administration/02-FAQ.md系统讲解 Karakeep 实例的用户管理三大核心场景普通用户忘记密码后如何由管理员重置、管理员自身忘记密码时如何通过数据库直改恢复访问以及关闭开放注册后如何继续为新成员创建账号。读完本文你将能独立完成 Karakeep 用户体系的日常运维并理解其背后的角色机制与密码存储原理。用户角色与权限机制Karakeep 的用户角色体系非常简单只有两种角色admin与user。在数据库层面角色存储在users表的role字段中其定义为text(role, { enum: [admin, user] }).default(user)见 packages/db/schema.ts即默认注册的用户角色是user。第一个注册的用户会自动被提升为管理员这是 FAQ 明确说明的默认行为。从源码看这一逻辑实现在 packages/trpc/models/users.ts 的User.createRaw中创建用户时若未显式指定角色代码会统计当前用户总数userCount 0时自动赋予admin角色。这意味着首次部署 Karakeep 后谁先完成注册谁就天然获得管理员权限。管理员拥有的权限远超普通用户他们可以查看Users List中的全部用户、重置任意用户密码、变更用户角色、在注册关闭时创建新账号还可以通过 packages/trpc/routers/admin.ts 中adminUsersProcedure保护的一组管理接口执行书签重爬、全文索引重建、向量嵌入重新生成、配额调整等运维操作。普通用户则只能通过User Settings管理自己的资料与偏好。场景一普通用户忘记密码如果你是普通用户非管理员且忘记了自己的密码你没有自助找回的通道正确的做法是联系实例的管理员由管理员在管理后台为你重置密码。管理员的操作路径如下登录后进入Admin Settings管理设置页面在Users List用户列表中找到目标用户在Actions操作列中找到重置密码按钮输入一个新密码并点击Reset重置重置完成后该用户即可使用新密码登录出于安全考虑用户登录后可以再到自己的User Settings中把密码改成只有自己知道的新密码这样管理员也不会知晓最终密码。从源码层面看这一步对应 packages/trpc/routers/admin.ts 中的resetPassword接口它会调用generatePasswordSalt()生成一个 32 字节随机十六进制盐randomBytes(32).toString(hex)再通过hashPassword(input.newPassword, newSalt)对“新密码 盐”做 bcrypt 哈希成本因子BCRYPT_SALT_ROUNDS 10最后把哈希与盐一并写入users表的password、salt字段。值得注意的两个实现细节见 packages/trpc/auth.ts盐salt是密码哈希的组成部分。Karakeep 的密码存储策略是bcrypt.hash(password salt, 10)而不是直接哈希密码本身。因此在任何场景下重置密码都必须同时写入新的salt单独更新password字段会导致校验永远失败。管理员不能重置自己的密码。源码中resetPassword接口会先检查ctx.user.id input.userId若管理员试图重置自己的密码会直接抛出BAD_REQUEST。这正是 FAQ 单独为“管理员忘记密码”准备独立方案见下一节的原因。场景二管理员忘记密码数据库直改方案如果忘记密码的是管理员本人情况就特殊了——因为重置密码的入口在管理后台里而管理员自己进不去普通用户又没有权限替他操作。此时唯一的出路是直接修改数据库。FAQ 给出的完整步骤如下准备一个数据库连接工具Linux 上可使用sqlite3命令行工具安装命令为apt-get install sqlite3具体命令取决于你的发行版包管理器CentOS/RHEL 系对应yum install sqlite3或dnf install sqlite3Windows 上可以使用带图形界面的工具例如dbeaver停止 Karakeep。数据库直改必须在服务停止的状态下进行避免运行中的进程覆盖写入或锁库连接到db.db数据库文件。该文件位于你挂载到 Docker 容器的data目录中Docker 部署时容器内路径固定为/data见 docker/docker-compose.yml 中的DATA_DIR: /data注释说明。本地数据目录下执行sqlite3 db.db即可进入交互式 SQL 环境或用 dbeaver 在数据目录中定位该文件后打开连接执行 UPDATE 语句重置密码update user set password$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa, salt where emailYOUR_EMAIL_HERE;请务必将命令中的YOUR_EMAIL_HERE替换为你自己的注册邮箱。执行成功后你的账号密码即为adminadmin重启 Karakeep用你的邮箱和密码adminadmin登录然后立即到User Settings中把密码改成你自己的新密码。这条 SQL 背后的密码学原理这条命令之所以可用是因为它写入的是一个预先生成的合法 bcrypt 哈希$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa。其中$2a$表示 bcrypt 算法版本Karakeep 使用的bcryptjs兼容$2a$格式$10$表示成本因子为 10与源码中BCRYPT_SALT_ROUNDS 10完全一致其余部分为 bcrypt 的盐值与 60 字节哈希结果。同时命令把salt置为空字符串。这与 packages/trpc/auth.ts 中hashPassword的实现bcrypt.hash(password (salt ?? ), 10)以及登录时的校验逻辑bcrypt.compare(password user.salt, user.password)完全对应当salt时实际参与哈希的输入就是adminadmin本身因此能通过校验。理解了这一点你甚至可以生成自己的 bcrypt 哈希成本因子 10、拼接自己的盐替换掉命令中的默认值从而跳过“先用 adminadmin 登录再改密”的中间步骤。实操提示SQL 语句在大多数 shell 中需要用单引号包裹整体再传给sqlite3形如sqlite3 db.db update user set ...注意内部字符串引号的转义交互模式下直接粘贴即可数据库直改是高危操作请先备份db.db文件再执行若你使用的是非 Docker 的裸机部署方式data目录位于你的安装目录下db.db的定位方式相同此方法对普通用户同样有效但正常流程下优先走管理后台重置直改数据库仅作为管理员失联等极端场景的兜底。场景三将普通用户提升为管理员当你需要把管理权限授予第二个或更多用户时进入Admin Settings页面在Users List中找到目标用户在Actions列中找到修改角色Role的按钮将角色改为Admin点击Change确认。重要新管理员必须退出登录并重新登录新角色才会生效。这是因为 Karakeep 在登录时才会从数据库读取用户信息包括role字段并写入会话已存在的会话不会自动刷新角色。从实现看这一操作对应 packages/trpc/routers/admin.ts 的updateUser接口。它有一个保护性限制ctx.user.id input.userId时抛出Cannot update own user即管理员不能通过该接口修改自己的角色防止误操作把自己降级或有人越权提升自己——尽管该接口本身已受adminUsersProcedure权限保护。除角色外updateUser还支持修改书签配额bookmarkQuota、存储配额storageQuota和浏览器爬取开关browserCrawlingEnabled这些字段均可在管理后台的同一页面维护。场景四注册关闭后如何添加新用户许多自托管者会在部署稳定后关闭开放注册通过signups_disabled配置以避免陌生人不请自来。此时新成员无法自助注册但管理员依然可以随时手动创建账号进入Admin Settings页面打开Users List点击Create User按钮填写用户信息姓名、邮箱、初始密码等管理员可同时指定其角色与配额点击create提交创建完成后新用户即可凭这些凭据直接登录。源码层面packages/trpc/routers/users.ts 的create路由面向开放注册与 packages/trpc/routers/admin.ts 的createUser路由面向管理员最终都收敛到User.create/User.createRaw见 packages/trpc/models/users.ts。区别在于管理员创建用户时可显式传入roleuser或admin而开放注册流程不传角色走“首个用户自动成为管理员”的默认逻辑。此外User.createRaw在邮箱重复时会捕获SQLITE_CONSTRAINT_UNIQUE并返回Email is already taken错误所以你无需担心重复创建。安全建议与延伸阅读及时改密无论是管理员重置还是数据库直改恢复访问后的第一件事都应是到User Settings修改密码避免临时密码如adminadmin长期有效账号口令与非口令并存从 packages/trpc/auth.ts 的validatePassword实现可以看到Karakeep 还支持 OAuth 等非密码登录方式这类账号没有password字段无法用上述数据库方案重置只能通过管理后台或直接编辑数据库password字段处理登录接口自带防探测设计源码中对不存在的用户、无密码的账号也会执行一次“假”bcrypt 比较DUMMY_PASSWORD_HASH以抹平响应时间差异、防止通过时序差异探测邮箱是否注册——这提醒我们在运维中不要过度依赖错误提示判断账号状态更多安全基线请阅读 01-security-considerations.md故障排查参考 05-troubleshooting.md数据库迁移见 06-server-migration.mdDocker 部署方式详见 01-docker.md。小结Karakeep 的用户管理设计围绕“管理员可控、权限可追溯”展开管理员通过Admin Settings的Users List完成密码重置、角色变更与账号创建当管理员自身失能时db.db数据库直改是唯一的兜底通道其关键在于理解password salt的 bcrypt 哈希结构。掌握以上四个场景你就能完整驾驭一个自托管 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创作声明：本文部分内容由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自托管书签管理应用v0.33.0 的官方 FAQ 文档docs/versioned_docs/version-v0.33.0/06-administration/02-FAQ.md系统讲解 Karakeep 实例的用户管理三大核心场景普通用户忘记密码后如何由管理员重置、管理员自身忘记密码时如何通过数据库直改恢复访问以及关闭开放注册后如何继续为新成员创建账号。读完本文你将能独立完成 Karakeep 用户体系的日常运维并理解其背后的角色机制与密码存储原理。用户角色与权限机制Karakeep 的用户角色体系非常简单只有两种角色admin与user。在数据库层面角色存储在users表的role字段中其定义为text(role, { enum: [admin, user] }).default(user)见 packages/db/schema.ts即默认注册的用户角色是user。第一个注册的用户会自动被提升为管理员这是 FAQ 明确说明的默认行为。从源码看这一逻辑实现在 packages/trpc/models/users.ts 的User.createRaw中创建用户时若未显式指定角色代码会统计当前用户总数userCount 0时自动赋予admin角色。这意味着首次部署 Karakeep 后谁先完成注册谁就天然获得管理员权限。管理员拥有的权限远超普通用户他们可以查看Users List中的全部用户、重置任意用户密码、变更用户角色、在注册关闭时创建新账号还可以通过 packages/trpc/routers/admin.ts 中adminUsersProcedure保护的一组管理接口执行书签重爬、全文索引重建、向量嵌入重新生成、配额调整等运维操作。普通用户则只能通过User Settings管理自己的资料与偏好。场景一普通用户忘记密码如果你是普通用户非管理员且忘记了自己的密码你没有自助找回的通道正确的做法是联系实例的管理员由管理员在管理后台为你重置密码。管理员的操作路径如下登录后进入Admin Settings管理设置页面在Users List用户列表中找到目标用户在Actions操作列中找到重置密码按钮输入一个新密码并点击Reset重置重置完成后该用户即可使用新密码登录出于安全考虑用户登录后可以再到自己的User Settings中把密码改成只有自己知道的新密码这样管理员也不会知晓最终密码。从源码层面看这一步对应 packages/trpc/routers/admin.ts 中的resetPassword接口它会调用generatePasswordSalt()生成一个 32 字节随机十六进制盐randomBytes(32).toString(hex)再通过hashPassword(input.newPassword, newSalt)对“新密码 盐”做 bcrypt 哈希成本因子BCRYPT_SALT_ROUNDS 10最后把哈希与盐一并写入users表的password、salt字段。值得注意的两个实现细节见 packages/trpc/auth.ts盐salt是密码哈希的组成部分。Karakeep 的密码存储策略是bcrypt.hash(password salt, 10)而不是直接哈希密码本身。因此在任何场景下重置密码都必须同时写入新的salt单独更新password字段会导致校验永远失败。管理员不能重置自己的密码。源码中resetPassword接口会先检查ctx.user.id input.userId若管理员试图重置自己的密码会直接抛出BAD_REQUEST。这正是 FAQ 单独为“管理员忘记密码”准备独立方案见下一节的原因。场景二管理员忘记密码数据库直改方案如果忘记密码的是管理员本人情况就特殊了——因为重置密码的入口在管理后台里而管理员自己进不去普通用户又没有权限替他操作。此时唯一的出路是直接修改数据库。FAQ 给出的完整步骤如下准备一个数据库连接工具Linux 上可使用sqlite3命令行工具安装命令为apt-get install sqlite3具体命令取决于你的发行版包管理器CentOS/RHEL 系对应yum install sqlite3或dnf install sqlite3Windows 上可以使用带图形界面的工具例如dbeaver停止 Karakeep。数据库直改必须在服务停止的状态下进行避免运行中的进程覆盖写入或锁库连接到db.db数据库文件。该文件位于你挂载到 Docker 容器的data目录中Docker 部署时容器内路径固定为/data见 docker/docker-compose.yml 中的DATA_DIR: /data注释说明。本地数据目录下执行sqlite3 db.db即可进入交互式 SQL 环境或用 dbeaver 在数据目录中定位该文件后打开连接执行 UPDATE 语句重置密码update user set password$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa, salt where emailYOUR_EMAIL_HERE;请务必将命令中的YOUR_EMAIL_HERE替换为你自己的注册邮箱。执行成功后你的账号密码即为adminadmin重启 Karakeep用你的邮箱和密码adminadmin登录然后立即到User Settings中把密码改成你自己的新密码。这条 SQL 背后的密码学原理这条命令之所以可用是因为它写入的是一个预先生成的合法 bcrypt 哈希$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa。其中$2a$表示 bcrypt 算法版本Karakeep 使用的bcryptjs兼容$2a$格式$10$表示成本因子为 10与源码中BCRYPT_SALT_ROUNDS 10完全一致其余部分为 bcrypt 的盐值与 60 字节哈希结果。同时命令把salt置为空字符串。这与 packages/trpc/auth.ts 中hashPassword的实现bcrypt.hash(password (salt ?? ), 10)以及登录时的校验逻辑bcrypt.compare(password user.salt, user.password)完全对应当salt时实际参与哈希的输入就是adminadmin本身因此能通过校验。理解了这一点你甚至可以生成自己的 bcrypt 哈希成本因子 10、拼接自己的盐替换掉命令中的默认值从而跳过“先用 adminadmin 登录再改密”的中间步骤。实操提示SQL 语句在大多数 shell 中需要用单引号包裹整体再传给sqlite3形如sqlite3 db.db update user set ...注意内部字符串引号的转义交互模式下直接粘贴即可数据库直改是高危操作请先备份db.db文件再执行若你使用的是非 Docker 的裸机部署方式data目录位于你的安装目录下db.db的定位方式相同此方法对普通用户同样有效但正常流程下优先走管理后台重置直改数据库仅作为管理员失联等极端场景的兜底。场景三将普通用户提升为管理员当你需要把管理权限授予第二个或更多用户时进入Admin Settings页面在Users List中找到目标用户在Actions列中找到修改角色Role的按钮将角色改为Admin点击Change确认。重要新管理员必须退出登录并重新登录新角色才会生效。这是因为 Karakeep 在登录时才会从数据库读取用户信息包括role字段并写入会话已存在的会话不会自动刷新角色。从实现看这一操作对应 packages/trpc/routers/admin.ts 的updateUser接口。它有一个保护性限制ctx.user.id input.userId时抛出Cannot update own user即管理员不能通过该接口修改自己的角色防止误操作把自己降级或有人越权提升自己——尽管该接口本身已受adminUsersProcedure权限保护。除角色外updateUser还支持修改书签配额bookmarkQuota、存储配额storageQuota和浏览器爬取开关browserCrawlingEnabled这些字段均可在管理后台的同一页面维护。场景四注册关闭后如何添加新用户许多自托管者会在部署稳定后关闭开放注册通过signups_disabled配置以避免陌生人不请自来。此时新成员无法自助注册但管理员依然可以随时手动创建账号进入Admin Settings页面打开Users List点击Create User按钮填写用户信息姓名、邮箱、初始密码等管理员可同时指定其角色与配额点击create提交创建完成后新用户即可凭这些凭据直接登录。源码层面packages/trpc/routers/users.ts 的create路由面向开放注册与 packages/trpc/routers/admin.ts 的createUser路由面向管理员最终都收敛到User.create/User.createRaw见 packages/trpc/models/users.ts。区别在于管理员创建用户时可显式传入roleuser或admin而开放注册流程不传角色走“首个用户自动成为管理员”的默认逻辑。此外User.createRaw在邮箱重复时会捕获SQLITE_CONSTRAINT_UNIQUE并返回Email is already taken错误所以你无需担心重复创建。安全建议与延伸阅读及时改密无论是管理员重置还是数据库直改恢复访问后的第一件事都应是到User Settings修改密码避免临时密码如adminadmin长期有效账号口令与非口令并存从 packages/trpc/auth.ts 的validatePassword实现可以看到Karakeep 还支持 OAuth 等非密码登录方式这类账号没有password字段无法用上述数据库方案重置只能通过管理后台或直接编辑数据库password字段处理登录接口自带防探测设计源码中对不存在的用户、无密码的账号也会执行一次“假”bcrypt 比较DUMMY_PASSWORD_HASH以抹平响应时间差异、防止通过时序差异探测邮箱是否注册——这提醒我们在运维中不要过度依赖错误提示判断账号状态更多安全基线请阅读 01-security-considerations.md故障排查参考 05-troubleshooting.md数据库迁移见 06-server-migration.mdDocker 部署方式详见 01-docker.md。小结Karakeep 的用户管理设计围绕“管理员可控、权限可追溯”展开管理员通过Admin Settings的Users List完成密码重置、角色变更与账号创建当管理员自身失能时db.db数据库直改是唯一的兜底通道其关键在于理解password salt的 bcrypt 哈希结构。掌握以上四个场景你就能完整驾驭一个自托管 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考