尧图网站建设 
Karakeep 自托管部署用户管理与密码重置实战指南FAQ 精讲【免费下载链接】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 后最常遇到的运维问题几乎都集中在用户管理上管理员忘了密码怎么办、如何给第二个管理员授权、关闭开放注册后如何添加新用户。本文以官方 FAQ 文档为骨架结合仓库源码数据库表结构、认证逻辑、管理端 tRPC 路由与测试用例逐项讲解这些场景的标准操作步骤、底层原理与安全注意事项读完即可独立完成 Karakeep 的用户生命周期管理。一、用户管理与角色模型概览Karakeep 的用户体系包含两种角色user普通用户与admin管理员角色定义在 packages/shared/types/admin.ts 中export const zRoleSchema z.object({ role: z.enum([user, admin]), });对应的数据库表user定义在 packages/db/schema.ts核心字段包括id主键默认由createId()生成email唯一索引登录凭证password可空文本字段OAuth 用户可能没有密码salt密码盐默认空字符串role枚举[admin, user]默认user。值得注意的默认规则第一个注册的用户会被自动提升为管理员。该逻辑位于 packages/trpc/models/users.ts 的createRaw中let userRole input.role; if (!userRole) { const [{ count: userCount }] trx .select({ count: count() }) .from(users) .all(); userRole userCount 0 ? admin : user; }即当用户表中没有任何记录时首个创建的账号角色为admin。这一行为在 packages/trpc/routers/users.test.ts 的first user is admin测试用例中得到验证第一个用户role为admin第二个用户role为user。二、忘记密码怎么办2.1 非管理员用户请管理员重置如果你不是管理员密码重置只能由管理员在管理界面完成打开Admin Settings管理设置页面在Users List用户列表中找到目标用户在Actions列点击重置密码按钮输入新密码并点击Reset新密码即刻生效出于隐私考虑你可以在登录后前往User Settings用户设置再次修改密码这样管理员也无法得知你的新密码。管理员重置密码的后端接口位于 packages/trpc/routers/users.ts其输入校验在 packages/shared/types/admin.ts 中定义export const resetPasswordSchema z .object({ userId: z.string(), newPassword: z.string().min(8).max(PASSWORD_MAX_LENGTH), newPasswordConfirm: z.string(), }) .refine((data) data.newPassword data.newPasswordConfirm, { message: Passwords dont match, path: [newPasswordConfirm], });可以看到新密码有强制约束最短 8 位且必须与确认密码一致否则接口会直接拒绝。重置后服务端会在 packages/trpc/models/users.ts 处以同样的哈希流程写入新密码。2.2 管理员自己忘记密码直接操作数据库如果管理员本人丢失了密码就需要绕过登录流程直接在数据库中重置。官方 FAQ 给出的步骤是准备一个数据库连接工具Linux 上使用sqlite3运行apt-get install sqlite3具体命令依你的包管理器而定Windows 上可使用dbeaver等图形化工具。关闭 Karakeep 服务防止服务运行中数据库文件被占用或缓存不一致。连接数据库文件db.db——它位于你挂载到 Docker 容器的data目录中在data目录下直接运行sqlite3 db.db或通过dbeaver的界面定位并连接该文件。执行 SQL 更新密码update user set password$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa, salt where emailYOUR_EMAIL_HERE;注意把YOUR_EMAIL_HERE替换成你自己的邮箱地址。该命令将你的密码重置为预设值adminadmin。重新启动 Karakeep。使用邮箱地址与密码adminadmin登录然后立即在User Settings中把密码改掉。2.3 密码哈希原理为什么这样一条 SQL 就能生效这条 SQL 之所以能奏效是因为 Karakeep 的密码存储格式是固定的。查看 packages/trpc/auth.tsexport async function hashPassword(password: string, salt: string | null) { return await bcrypt.hash(password (salt ?? ), BCRYPT_SALT_ROUNDS); }密码校验时packages/trpc/auth.ts执行的是const validation await bcrypt.compare( password (user.salt ?? ), user.password, );也就是说最终比较的是密码明文 salt的 bcrypt 哈希。FAQ 中给出的$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa正是adminadmin 空 salt经过 bcryptcost 因子 10计算后的合法哈希因此把password设为该值、salt清空后adminadmin就能通过登录校验。源码中的防御性设计也值得了解当用户不存在或没有密码如纯 OAuth 账号时服务端仍会执行一次针对固定DUMMY_PASSWORD_HASH的 bcrypt 比较见 packages/trpc/auth.ts用以隐藏用户是否存在的信息抵御时序攻击。2.4 安全注意事项务必在操作前关闭 Karakeep并在修改完成后立刻启动服务并登录验证登录成功后第一时间把adminadmin改为强密码该方式直改数据库属于最后手段操作前建议先备份data目录Karakeep 的备份与迁移说明可参考 docs/docs/06-administration/06-server-migration.md从源码可推断packages/shared/types/admin.ts正常的密码策略要求新密码最短 8 位重置后也请遵循这一要求。三、如何添加第二个管理员默认情况下只有第一个注册用户是管理员。要给其他用户授予管理员权限使用管理员账号进入Admin Settings页面在Users List中找到目标用户在Actions列点击修改角色Change Role按钮将角色改为Admin点击Change确认被提升的用户需要先退出登录、再重新登录新的角色才会生效。底层实现上角色修改通过 packages/trpc/routers/users.ts 中的管理端过程完成其更新模型在 packages/shared/types/admin.tsexport const updateUserSchema z.object({ userId: z.string(), role: z.enum([user, admin]).optional(), bookmarkQuota: z.number().int().min(0).nullable().optional(), storageQuota: z.number().int().min(0).nullable().optional(), browserCrawlingEnabled: z.boolean().nullable().optional(), });可以看出管理员的权限远不止改角色还可以调整bookmarkQuota书签配额、storageQuota存储配额、browserCrawlingEnabled是否允许浏览器爬取等管理员专属设置这些字段也同步定义在数据库表user中packages/db/schema.ts。重新登录后角色生效这一现象源于会话建立机制登录时服务端会把用户角色写入会话上下文见 packages/trpc/index.ts 的role: admin | user | null旧会话中缓存的角色不会实时刷新因此需要重新登录。四、关闭注册后如何添加新用户Karakeep 支持通过环境变量DISABLE_SIGNUPS关闭开放注册对应配置解析位于 packages/shared/config.ts 的disableSignups: val.DISABLE_SIGNUPS。当注册关闭后普通用户无法自助注册服务端会在 packages/trpc/routers/users.ts 直接抛出FORBIDDEN错误if ( serverConfig.auth.disableSignups || serverConfig.auth.disablePasswordAuth ) { ... throw new TRPCError({ code: FORBIDDEN, message: Signups are disabled in server config, }); }但管理员随时可以手动创建账号流程如下进入Admin Settings页面打开Users List点击Create User创建用户按钮填写用户信息姓名、邮箱、密码等点击create确认新用户即可直接登录。这一路径走的是users.create的管理端变体创建时在 packages/trpc/models/users.ts 中会生成随机盐并调用hashPassword保存密码同时该接口还支持role参数管理员在创建时即可决定新用户是普通用户还是管理员。五、常见问题排查速查场景推荐处理方式依据普通用户忘记密码管理员在Admin Settings → Users List中重置packages/shared/types/admin.ts管理员忘记密码停服后直连db.db执行 SQL 重置为adminadmin本文 2.2 节需要第二个管理员管理员修改目标用户角色为Admin对方重新登录packages/shared/types/admin.ts关闭注册后加人管理员在Admin Settings中Create Userpackages/trpc/routers/users.ts新密码设置失败检查是否满足最短 8 位且两次输入一致resetPasswordSchema校验六、小结Karakeep 的用户管理机制整体设计得简洁而安全以user/admin双角色为核心首个注册用户自动成为管理员密码采用bcrypt(密码 salt)哈希存储并内置了防时序攻击的 dummy 比较管理端对用户的新增、删除、改密、配额调整都封装为带校验的 tRPC 接口。日常运维中只要遵循本文的流程——忘密码走管理端重置或数据库直改、提权后重新登录、关闭注册后用管理员手工建号——即可平稳应对绝大多数账号问题。若遇到登录、OAuth 或邮箱验证等更复杂的认证配置可继续查阅 docs/docs/03-configuration/01-environment-variables.md 与 docs/docs/02-installation/01-docker.md。【免费下载链接】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 自托管部署用户管理与密码重置实战指南（FAQ 精讲）
Karakeep 自托管部署用户管理与密码重置实战指南FAQ 精讲【免费下载链接】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 后最常遇到的运维问题几乎都集中在用户管理上管理员忘了密码怎么办、如何给第二个管理员授权、关闭开放注册后如何添加新用户。本文以官方 FAQ 文档为骨架结合仓库源码数据库表结构、认证逻辑、管理端 tRPC 路由与测试用例逐项讲解这些场景的标准操作步骤、底层原理与安全注意事项读完即可独立完成 Karakeep 的用户生命周期管理。一、用户管理与角色模型概览Karakeep 的用户体系包含两种角色user普通用户与admin管理员角色定义在 packages/shared/types/admin.ts 中export const zRoleSchema z.object({ role: z.enum([user, admin]), });对应的数据库表user定义在 packages/db/schema.ts核心字段包括id主键默认由createId()生成email唯一索引登录凭证password可空文本字段OAuth 用户可能没有密码salt密码盐默认空字符串role枚举[admin, user]默认user。值得注意的默认规则第一个注册的用户会被自动提升为管理员。该逻辑位于 packages/trpc/models/users.ts 的createRaw中let userRole input.role; if (!userRole) { const [{ count: userCount }] trx .select({ count: count() }) .from(users) .all(); userRole userCount 0 ? admin : user; }即当用户表中没有任何记录时首个创建的账号角色为admin。这一行为在 packages/trpc/routers/users.test.ts 的first user is admin测试用例中得到验证第一个用户role为admin第二个用户role为user。二、忘记密码怎么办2.1 非管理员用户请管理员重置如果你不是管理员密码重置只能由管理员在管理界面完成打开Admin Settings管理设置页面在Users List用户列表中找到目标用户在Actions列点击重置密码按钮输入新密码并点击Reset新密码即刻生效出于隐私考虑你可以在登录后前往User Settings用户设置再次修改密码这样管理员也无法得知你的新密码。管理员重置密码的后端接口位于 packages/trpc/routers/users.ts其输入校验在 packages/shared/types/admin.ts 中定义export const resetPasswordSchema z .object({ userId: z.string(), newPassword: z.string().min(8).max(PASSWORD_MAX_LENGTH), newPasswordConfirm: z.string(), }) .refine((data) data.newPassword data.newPasswordConfirm, { message: Passwords dont match, path: [newPasswordConfirm], });可以看到新密码有强制约束最短 8 位且必须与确认密码一致否则接口会直接拒绝。重置后服务端会在 packages/trpc/models/users.ts 处以同样的哈希流程写入新密码。2.2 管理员自己忘记密码直接操作数据库如果管理员本人丢失了密码就需要绕过登录流程直接在数据库中重置。官方 FAQ 给出的步骤是准备一个数据库连接工具Linux 上使用sqlite3运行apt-get install sqlite3具体命令依你的包管理器而定Windows 上可使用dbeaver等图形化工具。关闭 Karakeep 服务防止服务运行中数据库文件被占用或缓存不一致。连接数据库文件db.db——它位于你挂载到 Docker 容器的data目录中在data目录下直接运行sqlite3 db.db或通过dbeaver的界面定位并连接该文件。执行 SQL 更新密码update user set password$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa, salt where emailYOUR_EMAIL_HERE;注意把YOUR_EMAIL_HERE替换成你自己的邮箱地址。该命令将你的密码重置为预设值adminadmin。重新启动 Karakeep。使用邮箱地址与密码adminadmin登录然后立即在User Settings中把密码改掉。2.3 密码哈希原理为什么这样一条 SQL 就能生效这条 SQL 之所以能奏效是因为 Karakeep 的密码存储格式是固定的。查看 packages/trpc/auth.tsexport async function hashPassword(password: string, salt: string | null) { return await bcrypt.hash(password (salt ?? ), BCRYPT_SALT_ROUNDS); }密码校验时packages/trpc/auth.ts执行的是const validation await bcrypt.compare( password (user.salt ?? ), user.password, );也就是说最终比较的是密码明文 salt的 bcrypt 哈希。FAQ 中给出的$2a$10$5u40XUq/cD/TmLdCOyZ82ePENE6hpkbodJhsp7.e/BgZssUO5DDTa正是adminadmin 空 salt经过 bcryptcost 因子 10计算后的合法哈希因此把password设为该值、salt清空后adminadmin就能通过登录校验。源码中的防御性设计也值得了解当用户不存在或没有密码如纯 OAuth 账号时服务端仍会执行一次针对固定DUMMY_PASSWORD_HASH的 bcrypt 比较见 packages/trpc/auth.ts用以隐藏用户是否存在的信息抵御时序攻击。2.4 安全注意事项务必在操作前关闭 Karakeep并在修改完成后立刻启动服务并登录验证登录成功后第一时间把adminadmin改为强密码该方式直改数据库属于最后手段操作前建议先备份data目录Karakeep 的备份与迁移说明可参考 docs/docs/06-administration/06-server-migration.md从源码可推断packages/shared/types/admin.ts正常的密码策略要求新密码最短 8 位重置后也请遵循这一要求。三、如何添加第二个管理员默认情况下只有第一个注册用户是管理员。要给其他用户授予管理员权限使用管理员账号进入Admin Settings页面在Users List中找到目标用户在Actions列点击修改角色Change Role按钮将角色改为Admin点击Change确认被提升的用户需要先退出登录、再重新登录新的角色才会生效。底层实现上角色修改通过 packages/trpc/routers/users.ts 中的管理端过程完成其更新模型在 packages/shared/types/admin.tsexport const updateUserSchema z.object({ userId: z.string(), role: z.enum([user, admin]).optional(), bookmarkQuota: z.number().int().min(0).nullable().optional(), storageQuota: z.number().int().min(0).nullable().optional(), browserCrawlingEnabled: z.boolean().nullable().optional(), });可以看出管理员的权限远不止改角色还可以调整bookmarkQuota书签配额、storageQuota存储配额、browserCrawlingEnabled是否允许浏览器爬取等管理员专属设置这些字段也同步定义在数据库表user中packages/db/schema.ts。重新登录后角色生效这一现象源于会话建立机制登录时服务端会把用户角色写入会话上下文见 packages/trpc/index.ts 的role: admin | user | null旧会话中缓存的角色不会实时刷新因此需要重新登录。四、关闭注册后如何添加新用户Karakeep 支持通过环境变量DISABLE_SIGNUPS关闭开放注册对应配置解析位于 packages/shared/config.ts 的disableSignups: val.DISABLE_SIGNUPS。当注册关闭后普通用户无法自助注册服务端会在 packages/trpc/routers/users.ts 直接抛出FORBIDDEN错误if ( serverConfig.auth.disableSignups || serverConfig.auth.disablePasswordAuth ) { ... throw new TRPCError({ code: FORBIDDEN, message: Signups are disabled in server config, }); }但管理员随时可以手动创建账号流程如下进入Admin Settings页面打开Users List点击Create User创建用户按钮填写用户信息姓名、邮箱、密码等点击create确认新用户即可直接登录。这一路径走的是users.create的管理端变体创建时在 packages/trpc/models/users.ts 中会生成随机盐并调用hashPassword保存密码同时该接口还支持role参数管理员在创建时即可决定新用户是普通用户还是管理员。五、常见问题排查速查场景推荐处理方式依据普通用户忘记密码管理员在Admin Settings → Users List中重置packages/shared/types/admin.ts管理员忘记密码停服后直连db.db执行 SQL 重置为adminadmin本文 2.2 节需要第二个管理员管理员修改目标用户角色为Admin对方重新登录packages/shared/types/admin.ts关闭注册后加人管理员在Admin Settings中Create Userpackages/trpc/routers/users.ts新密码设置失败检查是否满足最短 8 位且两次输入一致resetPasswordSchema校验六、小结Karakeep 的用户管理机制整体设计得简洁而安全以user/admin双角色为核心首个注册用户自动成为管理员密码采用bcrypt(密码 salt)哈希存储并内置了防时序攻击的 dummy 比较管理端对用户的新增、删除、改密、配额调整都封装为带校验的 tRPC 接口。日常运维中只要遵循本文的流程——忘密码走管理端重置或数据库直改、提权后重新登录、关闭注册后用管理员手工建号——即可平稳应对绝大多数账号问题。若遇到登录、OAuth 或邮箱验证等更复杂的认证配置可继续查阅 docs/docs/03-configuration/01-environment-variables.md 与 docs/docs/02-installation/01-docker.md。【免费下载链接】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），仅供参考