kotaemonktem用户管理功能完全指南配置、登录与账号管理实战【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon本文围绕 kotaemon 仓库中ktem扩展的用户管理User Management能力展开详细说明如何通过flowsettings.py开启用户管理、理解管理员账号的初始化机制并完整掌握登录/登出、修改密码以及创建/查看/编辑/删除用户等实战操作同时结合 flowsettings.py 与 libs/ktem/ktem/pages/resources/user.py 等源码剖析其底层实现帮助你为多用户部署场景快速建立身份与权限体系。一、用户管理是什么ktem 的扩展能力在 kotaemon 中ktem以扩展extension的形式提供用户管理能力。所谓扩展意味着该功能默认处于关闭状态只有你在配置中显式开启后应用才会渲染出登录页、账号管理界面等组件。从源码结构看用户管理贯穿整个应用的多个层面入口开关ktem的核心应用类BaseApp在初始化时通过getattr(settings, KH_FEATURE_USER_MANAGEMENT, False)读取开关并据此决定user_id状态变量的默认值——开启时为None未登录关闭时固定为default见 libs/ktem/ktem/app.py界面渲染开启后主界面会新增一个 Welcome 登录 TabChat、Settings 等 Tab 默认隐藏登录成功后才逐一亮出见 libs/ktem/ktem/main.py功能落地登录页、设置页的改密/登出、Resources 页的用户管理 Tab 三个模块协同工作。二、如何开启三个配置项要启用用户管理只需在项目根目录的flowsettings.py中设置以下三个变量配置变量作用说明KH_FEATURE_USER_MANAGEMENT总开关设为True启用用户管理设为False则应用保持单用户模式KH_FEATURE_USER_MANAGEMENT_ADMIN管理员用户名应用首次启动时会用该用户名自动创建一个管理员账号KH_FEATURE_USER_MANAGEMENT_PASSWORD管理员密码与管理员用户名成对出现作为该账号的初始密码在仓库根目录的 flowsettings.py 中这三个变量的读取逻辑如下KH_FEATURE_USER_MANAGEMENT config( KH_FEATURE_USER_MANAGEMENT, defaultTrue, castbool ) KH_USER_CAN_SEE_PUBLIC None KH_FEATURE_USER_MANAGEMENT_ADMIN str( config(KH_FEATURE_USER_MANAGEMENT_ADMIN, defaultadmin) ) KH_FEATURE_USER_MANAGEMENT_PASSWORD str( config(KH_FEATURE_USER_MANAGEMENT_PASSWORD, defaultadmin) )这里有三点值得注意环境变量优先这些值通过decouple.config读取意味着你既可以直接修改flowsettings.py也可以通过同名环境变量如KH_FEATURE_USER_MANAGEMENTFalse在启动时覆盖默认值KH_FEATURE_USER_MANAGEMENT默认TrueADMIN/PASSWORD默认均为admin。出于安全考虑生产环境务必修改默认的管理员密码一处反例仓库中的 launch.sh 在 SSO 演示模式下显式设置KH_FEATURE_USER_MANAGEMENTfalse说明该开关可以在启动脚本层面按部署场景灵活切换。三、首次启动管理员账号的自动创建当你开启用户管理并首次启动应用时管理员账号会被自动写入数据库。这一逻辑位于 libs/ktem/ktem/pages/resources/user.py 的UserManagement.__init__中if hasattr(flowsettings, KH_FEATURE_USER_MANAGEMENT_ADMIN) and hasattr( flowsettings, KH_FEATURE_USER_MANAGEMENT_PASSWORD ): usn flowsettings.KH_FEATURE_USER_MANAGEMENT_ADMIN pwd flowsettings.KH_FEATURE_USER_MANAGEMENT_PASSWORD is_created create_user(usn, pwd) if is_created: gr.Info(fUser {usn} created successfully)底层调用create_user函数同一文件的 第 97-117 行其关键行为包括通过User.username_lower usn.lower()做大小写不敏感的查重账号已存在则不重复创建密码使用SHA-256哈希hashlib.sha256(pwd.encode()).hexdigest()后落库数据库不保存明文管理员账号的admin字段为True这是后续只有管理员能看到用户管理界面的权限基础。账号存储在 SQLite 数据库的user表中表结构由BaseUser定义见 libs/ktem/ktem/db/base_models.pyclass BaseUser(SQLModel): id: str Field(default_factorylambda: uuid.uuid4().hex, primary_keyTrue, indexTrue) username: str Field(uniqueTrue) username_lower: str Field(uniqueTrue) password: str admin: bool Field(defaultFalse)注意表里同时保存了username与username_lower两个字段前者保留用户输入的原样大小写用于展示后者用于统一小写后的唯一性校验与登录查询。四、登录与登出开启用户管理后应用启动会先显示 Welcome 登录页见 libs/ktem/ktem/main.py登录页由LoginPage实现见 libs/ktem/ktem/pages/login.py。4.1 登录流程LoginPage.login的校验逻辑如下hashed_password hashlib.sha256(pwd.encode()).hexdigest() with Session(engine) as session: stmt select(User).where( User.username_lower usn.lower().strip(), User.password hashed_password, ) result session.exec(stmt).all() if result: return result[0].id, , gr.Warning(Invalid username or password) return None, usn, pwd用户名不区分大小写查询时统一转为小写并去除首尾空格密码通过 SHA-256 哈希后与库中记录比对登录成功后返回用户id同时通过前端 JS 将用户名、密码写入浏览器存储实现会话保持下次刷新页面时自动取回凭据完成静默登录登录失败则提示 Invalid username or password。4.2 登录后的界面权限差异登录状态会触发onSignIn公共事件主界面根据当前用户是否为管理员动态调整各 Tab 的可见性见 libs/ktem/ktem/main.py普通用户可见 Chat、Settings、Help 等 Tab看不到 Resources Tab管理员额外可见 Resources Tab内含用户管理入口未登录时仅显示 Welcome 登录 Tab。4.3 登出登出入口位于Settings Tab → User settings点击 Logout 按钮后前端 JS 会从浏览器存储中清除用户名与密码见 libs/ktem/ktem/pages/settings.py随后触发onSignOut事件界面回到登录状态。五、修改密码开启用户管理后Settings Tab 中会多出一个 User settings 子 Tab包含当前登录用户展示、Logout 按钮以及修改密码表单见 libs/ktem/ktem/pages/settings.py。修改密码的后端逻辑change_password第 267-289 行会先复用validate_password校验新密码格式校验通过后用 SHA-256 哈希更新当前用户的password字段并提示 Password changed。5.1 密码强度规则validate_password定义在 libs/ktem/ktem/pages/resources/user.py要求新密码同时满足长度至少8个字符至少包含1个大写字母至少包含1个小写字母至少包含1个数字至少包含1个以下特殊字符^ $ * . [ ] { } ( ) ? - ! # % / \ , : ; | _ ~ 任一条件不满足或两次输入的密码不一致都会返回对应的中文/英文错误提示不会执行更新。六、创建 / 查看 / 编辑 / 删除用户用户管理的完整 CRUD 界面由UserManagement页面提供libs/ktem/ktem/pages/resources/user.py入口在Resources Tab → Users Tab。同时该 Tab 仅在当前用户为管理员时可见见 libs/ktem/ktem/pages/resources/init.py 与 第 61-70 行的toggle_user_management。6.1 界面结构UserManagement.on_building_ui构建了两个子 TabUser list以表格展示所有用户的id、name、admin三列选中某行后展开编辑面板可修改用户名、密码可选、管理员标志并可执行删除带 Confirm delete 二次确认Create user输入用户名、密码、确认密码后点击 Create user 创建新账号页面右侧会同时展示用户名与密码的规则说明。6.2 用户名规则validate_username第 30-48 行规定了用户名格式用户名不区分大小写长度3 到 32个字符只能包含字母、数字和下划线_。6.3 创建用户创建逻辑create_user方法第 286-313 行依次执行校验用户名格式校验密码强度与两次输入一致性查重用户名大小写不敏感重复则提示Username xxx already existsSHA-256 哈希密码后写入User表新建用户默认adminFalse普通用户。6.4 查看用户列表list_users第 315-341 行仅允许管理员查询普通用户调用时返回占位空表管理员则返回全部用户的id、username、admin记录。列表会在登录onSignIn与登出onSignOut事件时自动刷新。6.5 编辑用户save_user第 406-441 行支持修改用户名重新校验格式并排除当前用户自身做唯一性检查密码留空则不改动填写则需通过密码强度校验后重新哈希管理员标志直接更新admin字段。6.6 删除用户delete_user第 443-454 行有一个关键保护不能删除当前登录的自己提示 You cannot delete yourself其余用户确认后直接从数据库删除。七、与 SSO 的配合仓库还预留了 SSO单点登录集成路径。当KH_SSO_ENABLEDTrue时Settings 页的登出按钮替换为gradiologin.LogoutButton见 libs/ktem/ktem/pages/settings.py登录函数会优先尝试通过gradiologin.get_user(request)获取已认证用户见 libs/ktem/ktem/pages/login.py若该用户尚不存在则用其邮箱自动创建普通用户adminFalse。从源码看KH_SSO_ENABLED定义于 flowsettings.py默认False。此外launch.sh 中的演示脚本同时关闭了用户管理并使用 SSO 演示应用说明两者存在互斥/替换关系实际部署时需根据认证方案选择其一。八、常见问题与配置建议1. 修改默认管理员密码默认admin/admin仅适合本地体验。建议在flowsettings.py或环境变量中显式设置强密码后再启动密码规则同 5.1 节。2. 已存在数据库时如何重置管理员管理员账号仅在用户不存在时创建重复启动不会覆盖已有账号。若忘记密码需操作ktem_app_data/user_data/sql.db中的user表更新对应账号的password字段为新的 SHA-256 哈希值再重启应用。3. 普通用户无法看到 Resources这是设计如此——用户管理 Tab 仅对adminTrue的用户开放避免非管理员误操作账号体系。4. 与数据库的关系用户、会话设置等数据统一存放在由 flowsettings.py 指定的 SQLite 数据库sqlite:///{KH_USER_DATA_DIR / sql.db}中模型定义与建表逻辑见 libs/ktem/ktem/db/models.py 与 libs/ktem/ktem/db/base_models.py。九、小结kotaemon 的用户管理扩展为多用户部署提供了完整闭环三个配置项即可开启首次启动自动创建管理员随后即可通过界面完成登录/登出、密码修改与账号 CRUD。其实现上采用 SHA-256 密码哈希、大小写不敏感的唯一用户名、管理员权限隔离等机制逻辑集中在 libs/ktem/ktem/pages/resources/user.py、libs/ktem/ktem/pages/login.py 与 libs/ktem/ktem/pages/settings.py 三个模块中值得作为理解整个 ktem 扩展机制UI 构建、公共事件订阅、权限控制的入门样例进行阅读。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 kotaemon（ktem）用户管理功能完全指南：配置、登录与账号管理实战
kotaemonktem用户管理功能完全指南配置、登录与账号管理实战【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon本文围绕 kotaemon 仓库中ktem扩展的用户管理User Management能力展开详细说明如何通过flowsettings.py开启用户管理、理解管理员账号的初始化机制并完整掌握登录/登出、修改密码以及创建/查看/编辑/删除用户等实战操作同时结合 flowsettings.py 与 libs/ktem/ktem/pages/resources/user.py 等源码剖析其底层实现帮助你为多用户部署场景快速建立身份与权限体系。一、用户管理是什么ktem 的扩展能力在 kotaemon 中ktem以扩展extension的形式提供用户管理能力。所谓扩展意味着该功能默认处于关闭状态只有你在配置中显式开启后应用才会渲染出登录页、账号管理界面等组件。从源码结构看用户管理贯穿整个应用的多个层面入口开关ktem的核心应用类BaseApp在初始化时通过getattr(settings, KH_FEATURE_USER_MANAGEMENT, False)读取开关并据此决定user_id状态变量的默认值——开启时为None未登录关闭时固定为default见 libs/ktem/ktem/app.py界面渲染开启后主界面会新增一个 Welcome 登录 TabChat、Settings 等 Tab 默认隐藏登录成功后才逐一亮出见 libs/ktem/ktem/main.py功能落地登录页、设置页的改密/登出、Resources 页的用户管理 Tab 三个模块协同工作。二、如何开启三个配置项要启用用户管理只需在项目根目录的flowsettings.py中设置以下三个变量配置变量作用说明KH_FEATURE_USER_MANAGEMENT总开关设为True启用用户管理设为False则应用保持单用户模式KH_FEATURE_USER_MANAGEMENT_ADMIN管理员用户名应用首次启动时会用该用户名自动创建一个管理员账号KH_FEATURE_USER_MANAGEMENT_PASSWORD管理员密码与管理员用户名成对出现作为该账号的初始密码在仓库根目录的 flowsettings.py 中这三个变量的读取逻辑如下KH_FEATURE_USER_MANAGEMENT config( KH_FEATURE_USER_MANAGEMENT, defaultTrue, castbool ) KH_USER_CAN_SEE_PUBLIC None KH_FEATURE_USER_MANAGEMENT_ADMIN str( config(KH_FEATURE_USER_MANAGEMENT_ADMIN, defaultadmin) ) KH_FEATURE_USER_MANAGEMENT_PASSWORD str( config(KH_FEATURE_USER_MANAGEMENT_PASSWORD, defaultadmin) )这里有三点值得注意环境变量优先这些值通过decouple.config读取意味着你既可以直接修改flowsettings.py也可以通过同名环境变量如KH_FEATURE_USER_MANAGEMENTFalse在启动时覆盖默认值KH_FEATURE_USER_MANAGEMENT默认TrueADMIN/PASSWORD默认均为admin。出于安全考虑生产环境务必修改默认的管理员密码一处反例仓库中的 launch.sh 在 SSO 演示模式下显式设置KH_FEATURE_USER_MANAGEMENTfalse说明该开关可以在启动脚本层面按部署场景灵活切换。三、首次启动管理员账号的自动创建当你开启用户管理并首次启动应用时管理员账号会被自动写入数据库。这一逻辑位于 libs/ktem/ktem/pages/resources/user.py 的UserManagement.__init__中if hasattr(flowsettings, KH_FEATURE_USER_MANAGEMENT_ADMIN) and hasattr( flowsettings, KH_FEATURE_USER_MANAGEMENT_PASSWORD ): usn flowsettings.KH_FEATURE_USER_MANAGEMENT_ADMIN pwd flowsettings.KH_FEATURE_USER_MANAGEMENT_PASSWORD is_created create_user(usn, pwd) if is_created: gr.Info(fUser {usn} created successfully)底层调用create_user函数同一文件的 第 97-117 行其关键行为包括通过User.username_lower usn.lower()做大小写不敏感的查重账号已存在则不重复创建密码使用SHA-256哈希hashlib.sha256(pwd.encode()).hexdigest()后落库数据库不保存明文管理员账号的admin字段为True这是后续只有管理员能看到用户管理界面的权限基础。账号存储在 SQLite 数据库的user表中表结构由BaseUser定义见 libs/ktem/ktem/db/base_models.pyclass BaseUser(SQLModel): id: str Field(default_factorylambda: uuid.uuid4().hex, primary_keyTrue, indexTrue) username: str Field(uniqueTrue) username_lower: str Field(uniqueTrue) password: str admin: bool Field(defaultFalse)注意表里同时保存了username与username_lower两个字段前者保留用户输入的原样大小写用于展示后者用于统一小写后的唯一性校验与登录查询。四、登录与登出开启用户管理后应用启动会先显示 Welcome 登录页见 libs/ktem/ktem/main.py登录页由LoginPage实现见 libs/ktem/ktem/pages/login.py。4.1 登录流程LoginPage.login的校验逻辑如下hashed_password hashlib.sha256(pwd.encode()).hexdigest() with Session(engine) as session: stmt select(User).where( User.username_lower usn.lower().strip(), User.password hashed_password, ) result session.exec(stmt).all() if result: return result[0].id, , gr.Warning(Invalid username or password) return None, usn, pwd用户名不区分大小写查询时统一转为小写并去除首尾空格密码通过 SHA-256 哈希后与库中记录比对登录成功后返回用户id同时通过前端 JS 将用户名、密码写入浏览器存储实现会话保持下次刷新页面时自动取回凭据完成静默登录登录失败则提示 Invalid username or password。4.2 登录后的界面权限差异登录状态会触发onSignIn公共事件主界面根据当前用户是否为管理员动态调整各 Tab 的可见性见 libs/ktem/ktem/main.py普通用户可见 Chat、Settings、Help 等 Tab看不到 Resources Tab管理员额外可见 Resources Tab内含用户管理入口未登录时仅显示 Welcome 登录 Tab。4.3 登出登出入口位于Settings Tab → User settings点击 Logout 按钮后前端 JS 会从浏览器存储中清除用户名与密码见 libs/ktem/ktem/pages/settings.py随后触发onSignOut事件界面回到登录状态。五、修改密码开启用户管理后Settings Tab 中会多出一个 User settings 子 Tab包含当前登录用户展示、Logout 按钮以及修改密码表单见 libs/ktem/ktem/pages/settings.py。修改密码的后端逻辑change_password第 267-289 行会先复用validate_password校验新密码格式校验通过后用 SHA-256 哈希更新当前用户的password字段并提示 Password changed。5.1 密码强度规则validate_password定义在 libs/ktem/ktem/pages/resources/user.py要求新密码同时满足长度至少8个字符至少包含1个大写字母至少包含1个小写字母至少包含1个数字至少包含1个以下特殊字符^ $ * . [ ] { } ( ) ? - ! # % / \ , : ; | _ ~ 任一条件不满足或两次输入的密码不一致都会返回对应的中文/英文错误提示不会执行更新。六、创建 / 查看 / 编辑 / 删除用户用户管理的完整 CRUD 界面由UserManagement页面提供libs/ktem/ktem/pages/resources/user.py入口在Resources Tab → Users Tab。同时该 Tab 仅在当前用户为管理员时可见见 libs/ktem/ktem/pages/resources/init.py 与 第 61-70 行的toggle_user_management。6.1 界面结构UserManagement.on_building_ui构建了两个子 TabUser list以表格展示所有用户的id、name、admin三列选中某行后展开编辑面板可修改用户名、密码可选、管理员标志并可执行删除带 Confirm delete 二次确认Create user输入用户名、密码、确认密码后点击 Create user 创建新账号页面右侧会同时展示用户名与密码的规则说明。6.2 用户名规则validate_username第 30-48 行规定了用户名格式用户名不区分大小写长度3 到 32个字符只能包含字母、数字和下划线_。6.3 创建用户创建逻辑create_user方法第 286-313 行依次执行校验用户名格式校验密码强度与两次输入一致性查重用户名大小写不敏感重复则提示Username xxx already existsSHA-256 哈希密码后写入User表新建用户默认adminFalse普通用户。6.4 查看用户列表list_users第 315-341 行仅允许管理员查询普通用户调用时返回占位空表管理员则返回全部用户的id、username、admin记录。列表会在登录onSignIn与登出onSignOut事件时自动刷新。6.5 编辑用户save_user第 406-441 行支持修改用户名重新校验格式并排除当前用户自身做唯一性检查密码留空则不改动填写则需通过密码强度校验后重新哈希管理员标志直接更新admin字段。6.6 删除用户delete_user第 443-454 行有一个关键保护不能删除当前登录的自己提示 You cannot delete yourself其余用户确认后直接从数据库删除。七、与 SSO 的配合仓库还预留了 SSO单点登录集成路径。当KH_SSO_ENABLEDTrue时Settings 页的登出按钮替换为gradiologin.LogoutButton见 libs/ktem/ktem/pages/settings.py登录函数会优先尝试通过gradiologin.get_user(request)获取已认证用户见 libs/ktem/ktem/pages/login.py若该用户尚不存在则用其邮箱自动创建普通用户adminFalse。从源码看KH_SSO_ENABLED定义于 flowsettings.py默认False。此外launch.sh 中的演示脚本同时关闭了用户管理并使用 SSO 演示应用说明两者存在互斥/替换关系实际部署时需根据认证方案选择其一。八、常见问题与配置建议1. 修改默认管理员密码默认admin/admin仅适合本地体验。建议在flowsettings.py或环境变量中显式设置强密码后再启动密码规则同 5.1 节。2. 已存在数据库时如何重置管理员管理员账号仅在用户不存在时创建重复启动不会覆盖已有账号。若忘记密码需操作ktem_app_data/user_data/sql.db中的user表更新对应账号的password字段为新的 SHA-256 哈希值再重启应用。3. 普通用户无法看到 Resources这是设计如此——用户管理 Tab 仅对adminTrue的用户开放避免非管理员误操作账号体系。4. 与数据库的关系用户、会话设置等数据统一存放在由 flowsettings.py 指定的 SQLite 数据库sqlite:///{KH_USER_DATA_DIR / sql.db}中模型定义与建表逻辑见 libs/ktem/ktem/db/models.py 与 libs/ktem/ktem/db/base_models.py。九、小结kotaemon 的用户管理扩展为多用户部署提供了完整闭环三个配置项即可开启首次启动自动创建管理员随后即可通过界面完成登录/登出、密码修改与账号 CRUD。其实现上采用 SHA-256 密码哈希、大小写不敏感的唯一用户名、管理员权限隔离等机制逻辑集中在 libs/ktem/ktem/pages/resources/user.py、libs/ktem/ktem/pages/login.py 与 libs/ktem/ktem/pages/settings.py 三个模块中值得作为理解整个 ktem 扩展机制UI 构建、公共事件订阅、权限控制的入门样例进行阅读。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考