物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载导读本文围绕 OctoPrint JavaScript Client Library 的访问控制access组件展开系统讲解如何通过OctoPrintClient.access.permissions、OctoPrintClient.access.users与OctoPrintClient.access.groups三个子模块在前端脚本或第三方客户端中完成权限查询、用户与用户组管理、密码与 API Key 维护、用户个性化设置读写等操作。读完本文你将掌握 access 组件全部 API 方法及参数语义、底层 REST 端点映射、权限校验机制与常见错误处理并能在自己的 OctoPrint 插件或外部客户端中直接落地使用。组件定位与前置条件access组件是 OctoPrint JS Client Library 中与「访问控制」REST API 对应的客户端封装。组件对应的源文档为 docs/jsclientlib/access.rst其底层 HTTP 端点定义于 docs/api/access.rst服务端实现位于 src/octoprint/server/api/access.py。权限前提文档开头即给出重要提示本组件的大多数方法要求调用方持有的 API TokenX-Api-Key或浏览器会话具备管理员权限或者该会话恰好对应待操作的用户本身部分方法则严格需要管理员权限。具体到每个方法本文会在相应小节标注权限要求。从源码看权限校验在服务端通过装饰器强制执行。以 src/octoprint/server/api/access.py 为例用户与用户组的大部分写操作使用Permissions.ADMIN.require(403)非管理员直接返回 403写操作POST / PUT / DELETE额外叠加require_credentials_checked_recently即要求“凭据已在近期验证过”recent credentials check防止借用长期有效的会话进行敏感操作读取用户记录、修改密码、读写个人设置等接口则采用“当前用户等于目标用户或拥有 ADMIN 权限”二选一的判定逻辑。权限对象模型位于 src/octoprint/access/permissions.pyOctoPrintPermission通过as_dict()暴露key、name、dangerous、default_groups、description与needs字段PermissionsMetaClass将注册的权限统一收集到Permissions.permissions字典并支持Permissions.all()与Permissions.filter()遍历。/api/access/permissions端点正是用Permissions.all()枚举后逐个as_dict()输出见 src/octoprint/server/api/access.py 的get_permissions。引入方式access属于按需加载的组件。按 docs/jsclientlib/index.rst 的说明可以通过 webassets 一次性引入完整客户端{% assets js_client %}script typetext/javascript src{{ ASSET_URL }}/script{% endassets %}或只引入单个组件文件注意不要遗漏base组件其余所有组件都依赖它script typetext/javascript src{{ url_for(static, filenamejs/app/client/base.js) }}/script script typetext/javascript src{{ url_for(static, filenamejs/app/client/access.js) }}/script同时必须保证 jQuery$与 lodash_可用组件源码 src/octoprint/static/js/app/client/access.js 依赖这两个全局对象script src{{ url_for(static, filenamejs/lib/jquery/jquery.min.js) }}/script script src{{ url_for(static, filenamejs/lib/lodash.min.js) }}/script引入完成后全局变量OctoPrintOctoPrintClient的实例即包含OctoPrint.access命名空间其内部结构在 src/octoprint/static/js/app/client/access.js 末尾组装var OctoPrintAccessClient function (base) { this.base base; this.permissions new OctoPrintAccessPermissionsClient(this); this.groups new OctoPrintAccessGroupsClient(this); this.users new OctoPrintAccessUsersClient(this); }; OctoPrintClient.registerComponent(access, OctoPrintAccessClient);OctoPrintClient.registerComponent见 src/octoprint/static/js/app/client/base.js会把组件懒加载挂到客户端原型上因此OctoPrint.access.permissions、OctoPrint.access.users、OctoPrint.access.groups均可直接访问。OctoPrintClient.access.permissions权限清单查询permissions.list(opts)获取系统内全部已注册权限的列表。参数optsobject请求的附加选项如自定义 headers、超时等返回值jQuery Promiseresolve 后携带权限列表响应。实现位于 src/octoprint/static/js/app/client/access.js 的OctoPrintAccessPermissionsClient.prototype.list内部仅调用this.base.get(api/access/permissions)。底层 REST 端点为GET /api/access/permissions见 docs/api/access.rst 的 “List all permissions” 小节服务端get_permissions返回形如{permissions: [ ... ]}的 JSON每个元素包含key、name、dangerous、default_groups、description、needs等字段由 src/octoprint/access/permissions.py 的OctoPrintPermission.as_dict定义。典型用法OctoPrint.access.permissions.list() .done(function (response) { console.log(response.permissions); });OctoPrintClient.access.users用户管理users子组件把用户相关的全部 REST 操作封装为 9 个方法统一以api/access/users为基地址见 src/octoprint/static/js/app/client/access.js 的OctoPrintAccessUsersClient。下方列出方法签名、权限要求、底层端点与典型示例。users.list(opts)获取所有已注册用户的列表。需要管理员权限底层端点GET /api/access/users服务端在 src/octoprint/server/api/access.py 的get_users中对每个用户调用as_dict()若近期未验证过凭据返回的用户记录中apikey会被置为null这是刻意的安全行为。OctoPrint.access.users.list() .done(function (response) { console.log(response.users); });用户记录的数据结构由 src/octoprint/access/users.py 的User.as_dict定义包含name、active布尔、permissions权限 key 列表、groups用户组 key 列表、needs、apikey、settings、has_password。users.get(name, opts)获取指定用户的信息。参数namestring用户名底层端点GET /api/access/users/username权限SETTINGS权限或登录身份即该用户本人服务端逻辑见 src/octoprint/server/api/access.py 的get_usercurrent_user.get_name() username or current_user.has_permission(Permissions.ADMIN)未知用户返回 404无权限返回 403。OctoPrint.access.users.get(user1) .done(function (user) { console.log(user.name, user.active, user.permissions); });users.add(user, opts)新增用户。需要管理员权限参数userobject新用户数据底层端点POST /api/access/users客户端前置校验见 src/octoprint/static/js/app/client/access.jsuser.name与user.password必须存在否则抛出InvalidArgumentError客户端自动构造的请求体name、password、groups缺省为[]、permissions缺省为[]、active缺省为true!!user.active强转布尔服务端add_user要求请求体包含name、password、active缺失时返回 400用户名重复返回 409用户名非法返回 400成功时返回用户列表响应与users.list相同结构。OctoPrint.access.users.add({ name: newuser, password: s3cr3t, active: true, groups: [users], permissions: [] }).done(function (response) { console.log(response.users); });users.update(name, active, permissions, groups, opts)更新既有用户。需要管理员权限参数namestring用户名、activebool新的激活状态、permissionslist权限 key 列表、groupslist用户组 key 列表、optsobject底层端点PUT /api/access/users/username客户端通过putJson提交{active: !!active, groups: groups, permissions: permissions}服务端update_user按请求体中出现的字段分别调用change_user_groups、change_user_permissions、change_user_activation见 src/octoprint/server/api/access.py未知用户返回 404。兼容性说明重要源码中保留了对旧参数顺序(name, active, admin, permissions, groups, opts)的兼容逻辑——当第三个参数permissions的类型是 boolean 时会将其视为旧的admin标志把所有参数左移一位并打印弃用警告if (typeof permissions boolean) { // old parameter order: name, active, *admin*, permissions, groups, opts console.log( Calling OctoPrint.access.users.update with admin flag is deprecated and will be removed in OctoPrint 3.0.0. Use permissions or groups instead. ); permissions groups; groups opts; opts arguments.length 6 ? arguments[5] : {}; }因此应始终使用新的五参数形式不要依赖旧的 admin 布尔标志。OctoPrint.access.users.update(newuser, true, [ADMIN], [admins]) .done(function (response) { /* ... */ });users.delete(name, opts)删除既有用户。需要管理员权限底层端点DELETE /api/access/users/username服务端remove_user中若目标用户即当前登录用户返回 400“You cannot delete yourself”未知用户返回 404成功时返回用户列表响应。OctoPrint.access.users.delete(newuser) .done(function (response) { /* ... */ });users.changePassword(name, password, oldpw, opts)修改指定用户的密码。参数namestring、passwordstring新密码、oldpwstring旧密码可选但大多数情况下必需、optsobject底层端点PUT /api/access/users/username/password客户端实现有一个便捷行为若第三个参数传入的是 object即调用者省略了oldpw直接传opts会自动把参数移位if (_.isObject(oldpw)) { opts oldpw; oldpw undefined; }请求体为{password: newPassword}仅在提供oldpw时才附加current: oldpw服务端规则见 docs/api/access.rst 与change_password_for_user拥有SETTINGS权限或登录身份即目标用户没有管理员权限时请求体必须包含current当前密码且服务端会校验其正确性若current被提供即使调用方有管理员权限也会一并校验典型错误码400缺password或必需的current、403无权限 / 非本人 / 凭据未近期验证 / 当前密码不匹配、404未知用户。// 用户本人修改自己的密码 OctoPrint.access.users.changePassword(user1, newpass, oldpass); // 管理员为他人改密不提供旧密码 OctoPrint.access.users.changePassword(user2, newpass);users.generateApiKey(name, opts)为用户生成重置新的个人 API Key。底层端点POST /api/access/users/username/apikey权限SETTINGS权限或登录身份即目标用户且要求近期凭据校验服务端generate_apikey_for_user无需请求体响应 JSON 中通过apikey属性返回新生成的 keyjsonify({apikey: apikey})生成逻辑在 src/octoprint/access/users.py 的generate_api_key。OctoPrint.access.users.generateApiKey(user1) .done(function (response) { console.log(New API key:, response.apikey); });users.resetApiKey(name, opts)将用户的个人 API Key 重置为未设置状态。底层端点DELETE /api/access/users/username/apikey权限同上SETTINGS权限或登录身份即目标用户且要求近期凭据校验成功后返回SUCCESS204 语义对应服务端delete_apikey_for_user调用的delete_api_key见 src/octoprint/access/users.py。OctoPrint.access.users.resetApiKey(user1);users.getSettings(name, opts)获取指定用户的个人设置。底层端点GET /api/access/users/username/settings权限SETTINGS权限或登录身份即目标用户服务端get_settings_for_user返回userManager.get_all_user_settings(username)未知用户返回 404无权限返回 403返回的 JSON 对象即该用户的个性化设置可能为空对象。OctoPrint.access.users.getSettings(user1) .done(function (settings) { /* ... */ });users.saveSettings(name, settings, opts)保存/更新指定用户的个人设置。参数settingsobject允许只传部分设置服务端会将其与现有设置合并merge而非整体覆盖底层端点PATCH /api/access/users/username/settingsPATCH 语义天然支持部分更新客户端通过patchJson提交settings settings || {}保证空对象合法权限SETTINGS权限或登录身份即目标用户当操作者是管理员非本人时服务端要求近期凭据校验成功后返回SUCCESS。OctoPrint.access.users.saveSettings(user1, { theme: dark }) .done(function () { /* 已合并保存 */ });OctoPrintClient.access.groups用户组管理groups子组件对应api/access/groups端点见 src/octoprint/static/js/app/client/access.js 的OctoPrintAccessGroupsClient。用户组group用于批量授予权限组内可包含权限列表、子组subgroups以及是否作为新用户默认组default。服务端模型在 src/octoprint/access/groups.py内置了admin、users、guest、readonly等默认组_init_defaults其中users组默认对新建用户生效。groups.list(opts)获取所有已注册用户组的列表。底层端点GET /api/access/groups返回{groups: [ ... ]}服务端get_groups对groupManager.groups逐个调用as_dict()权限SETTINGS权限见 docs/api/access.rst。OctoPrint.access.groups.list() .done(function (response) { console.log(response.groups); });groups.get(key, opts)获取指定用户组的信息。参数keystring用户组 ID注意是key而非显示名称底层端点GET /api/access/groups/key服务端get_group通过groupManager.find_group(key)查找未知组返回 404客户端前置校验key必须设置否则抛出InvalidArgumentError。OctoPrint.access.groups.get(admins) .done(function (group) { console.log(group); });groups.add(group, opts)新增用户组。需要管理员权限参数groupobject要求至少包含key与name还支持description、permissions、subgroups以及default布尔标志客户端前置校验group.key与group.name缺一不可否则抛出InvalidArgumentError请求体字段见客户端add实现与 REST 数据模型完全对应docs/api/access.rst 的 “Group registration request” 表字段必填类型说明key是string用户组标识符name是string用户组显示名称description否string可读描述缺省为空串permissions是string 列表分配给该组的权限 key 列表subgroups否string 列表作为子组的用户组 key 列表default否boolean是否将新用户默认加入该组缺省 false服务端add_group缺少key/name/permissions/subgroups任一字段返回 400组 key 已存在或存在循环子组引用CyclicSubgroupReference返回 409成功时返回组列表响应。OctoPrint.access.groups.add({ key: operators, name: Operators, description: Machine operators, permissions: [PRINT, MONITOR_TERMINAL], subgroups: [users], default: false }).done(function (response) { /* ... */ });groups.update(group, opts)更新既有用户组通过group.key标识目标组。需要管理员权限参数groupobject必须包含key只会更新以下字段description、permissions、subgroups、defaultkey与name不参与更新客户端在组装请求体时description若未在group中定义则置为空串group.hasOwnProperty(description) ? group.description : permissions、subgroups、default原样传递底层端点PUT /api/access/groups/key服务端update_groupdefault字段按valid_boolean_trues解析为布尔组不可修改GroupCantBeChanged如内置组返回 403未知组返回 404循环子组引用返回 409成功时返回组列表响应。OctoPrint.access.groups.update({ key: operators, description: Machine operators (updated), permissions: [PRINT, MONITOR_TERMINAL, FILES_DOWNLOAD], subgroups: [users], default: false }).done(function (response) { /* ... */ });groups.delete(key, opts)删除用户组。需要管理员权限参数keystring用户组 ID底层端点DELETE /api/access/groups/key服务端remove_group未知组返回 404组不可移除GroupUnremovable如内置组返回 403成功时返回组列表响应。OctoPrint.access.groups.delete(operators) .done(function (response) { /* ... */ });底层请求机制与 Promise 使用要点access组件的全部方法都基于 src/octoprint/static/js/app/client/base.js 提供的 HTTP 原语get(url, opts)GET对应groups.list、users.get等postJson(url, data, opts)POST Content-Type: application/json请求体经JSON.stringifyundefined 值会被替换为 null对应groups.add、users.add、users.generateApiKeyputJson(url, data, opts)PUT JSON对应groups.update、users.update、users.changePasswordpatchJson(url, data, opts)PATCH JSON对应users.saveSettingsdelete(url, opts)DELETE对应groups.delete、users.delete、users.resetApiKey。所有方法都返回 jQuery Promise可链式使用.done()、.fail()、.always()。鉴权头由getRequestHeaders统一注入设置了OctoPrint.options.apikey时发送X-Api-Key未设置时视为浏览器上下文对非 GET/HEAD/OPTIONS 方法自动附加X-CSRF-Token从csrf_tokencookie 读取跨域请求除外。因此无论是通过OctoPrint.options.apikey携带管理员 API Key还是依赖登录会话 CSRF Token上述方法都能正常工作。客户端参数校验通过OctoPrintClient.InvalidArgumentErrorcreateCustomException(InvalidArgumentError)定义于 src/octoprint/static/js/app/client/base.js抛出例如users.add缺用户名/密码、groups.add缺 key/name、所有按 key/name 定位的方法缺标识符时都会触发。完整示例面向多服务器的用户管理以下示例演示如何实例化独立客户端并组合使用 access 组件的方法参考 docs/jsclientlib/index.rst 的多客户端模式var client new OctoPrintClient({ baseurl: http://octopi.local/, apikey: ADMIN_API_KEY }); client.access.users.list() .fail(function (xhr) { if (xhr.status 403) { console.error(需要管理员权限或近期凭据校验); } }) .done(function (response) { // 过滤出当前激活的用户 var activeUsers response.users.filter(function (u) { return u.active; }); console.log(activeUsers); }); client.access.groups.add({ key: engineers, name: Engineers, permissions: [PRINT], subgroups: [users], default: false }).done(function () { console.log(组已创建); });权限、安全与错误处理速查综合 docs/api/access.rst、src/octoprint/server/api/access.py 与 src/octoprint/static/js/app/client/access.js整理各方法的权限与典型错误如下方法权限要求底层端点典型错误permissions.list无特殊要求GET/api/access/permissions—users.listADMINGET/api/access/users403users.getADMIN 或本人GET/api/access/users/name403 / 404users.addADMINPOST/api/access/users400 / 409users.updateADMINPUT/api/access/users/name400 / 404users.deleteADMINDELETE/api/access/users/name400删除自己/ 404users.changePasswordADMIN 或本人本人需currentPUT/api/access/users/name/password400 / 403 / 404users.generateApiKeyADMIN 或本人 近期凭据POST/api/access/users/name/apikey403 / 404users.resetApiKeyADMIN 或本人 近期凭据DELETE/api/access/users/name/apikey403 / 404users.getSettingsADMIN 或本人GET/api/access/users/name/settings403 / 404users.saveSettingsADMIN 或本人管理员需近期凭据PATCH/api/access/users/name/settings403 / 404groups.listSETTINGSGET/api/access/groups403groups.getSETTINGSGET/api/access/groups/key404groups.addADMIN 近期凭据POST/api/access/groups400 / 409groups.updateADMIN 近期凭据PUT/api/access/groups/key403 / 404 / 409groups.deleteADMIN 近期凭据DELETE/api/access/groups/key403 / 404几个值得注意的安全细节近期凭据校验用户组写操作以及管理员代他人执行改密、API Key、设置等操作时服务端强制要求近期凭据校验require_credentials_checked_recently/ensure_credentials_checked_recently见 src/octoprint/server/api/access.py从而避免会话被长期借用后直接执行敏感操作。API Key 脱敏users.list与users.get在凭据未近期验证时返回记录中的apikey一律置为null见get_users/get_user防止敏感信息泄露。内置组保护admin、users、guest、readonly等默认组受GroupCantBeChanged/GroupUnremovable保护删除或修改会分别收到 403。循环子组引用groups.add/groups.update若形成循环子组关系服务端返回 409客户端应捕获该错误并向用户提示。删除自身限制users.delete不允许删除当前登录用户服务端返回 400。扩展阅读与相关资源组件文档索引docs/jsclientlib/index.rst含客户端库的引入方式、OctoPrint全局实例与多客户端用法底层 REST API 完整文档docs/api/access.rst端点、数据模型、错误码客户端实现源码src/octoprint/static/js/app/client/access.js客户端基础组件请求原语与参数校验src/octoprint/static/js/app/client/base.js服务端 REST 实现src/octoprint/server/api/access.py权限模型src/octoprint/access/permissions.py用户模型src/octoprint/access/users.py用户组模型src/octoprint/access/groups.py第三方客户端授权工作流可参考内置的 Application Key 插件文档docs/bundledplugins/appkeys.rst它为外部客户端补充了额外的 JS Client Library 方法与本文的 API Key 机制互补。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐如何用Automated YouTube Channel打造24/7自动运行的YouTube频道终极指南如何用Automated YouTube Channel打造24/7自动运行的YouTube频道终极指南 Automated YouTube Channel是物联网后端GitHub_Trending/ma/machine-learning-for-trading中的协整检验配对交易策略开发GitHub_Trending/ma/machine learning for trading中的协整检验配对交易策略开发 GitHub_Trending/m示例工程金融科技机器学习人工智能深度学习如何通过802.1X认证实现网络访问控制完整指南如何通过802.1X认证实现网络访问控制完整指南 802.1X认证是IEEE制定的端口网络访问控制PNAC标准通过为有线和无线网络提供设备身份验证机制网络安全渗透测试密码学上一篇猫抓插件完整指南3步玩转浏览器资源嗅探网页视频下载不再求人下一篇FastAPI BackgroundTasks API 参考响应发出后调度后台任务的声明式用法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OctoPrint JS Client Library 访问控制模块（OctoPrintClient.access）完整指南
物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载导读本文围绕 OctoPrint JavaScript Client Library 的访问控制access组件展开系统讲解如何通过OctoPrintClient.access.permissions、OctoPrintClient.access.users与OctoPrintClient.access.groups三个子模块在前端脚本或第三方客户端中完成权限查询、用户与用户组管理、密码与 API Key 维护、用户个性化设置读写等操作。读完本文你将掌握 access 组件全部 API 方法及参数语义、底层 REST 端点映射、权限校验机制与常见错误处理并能在自己的 OctoPrint 插件或外部客户端中直接落地使用。组件定位与前置条件access组件是 OctoPrint JS Client Library 中与「访问控制」REST API 对应的客户端封装。组件对应的源文档为 docs/jsclientlib/access.rst其底层 HTTP 端点定义于 docs/api/access.rst服务端实现位于 src/octoprint/server/api/access.py。权限前提文档开头即给出重要提示本组件的大多数方法要求调用方持有的 API TokenX-Api-Key或浏览器会话具备管理员权限或者该会话恰好对应待操作的用户本身部分方法则严格需要管理员权限。具体到每个方法本文会在相应小节标注权限要求。从源码看权限校验在服务端通过装饰器强制执行。以 src/octoprint/server/api/access.py 为例用户与用户组的大部分写操作使用Permissions.ADMIN.require(403)非管理员直接返回 403写操作POST / PUT / DELETE额外叠加require_credentials_checked_recently即要求“凭据已在近期验证过”recent credentials check防止借用长期有效的会话进行敏感操作读取用户记录、修改密码、读写个人设置等接口则采用“当前用户等于目标用户或拥有 ADMIN 权限”二选一的判定逻辑。权限对象模型位于 src/octoprint/access/permissions.pyOctoPrintPermission通过as_dict()暴露key、name、dangerous、default_groups、description与needs字段PermissionsMetaClass将注册的权限统一收集到Permissions.permissions字典并支持Permissions.all()与Permissions.filter()遍历。/api/access/permissions端点正是用Permissions.all()枚举后逐个as_dict()输出见 src/octoprint/server/api/access.py 的get_permissions。引入方式access属于按需加载的组件。按 docs/jsclientlib/index.rst 的说明可以通过 webassets 一次性引入完整客户端{% assets js_client %}script typetext/javascript src{{ ASSET_URL }}/script{% endassets %}或只引入单个组件文件注意不要遗漏base组件其余所有组件都依赖它script typetext/javascript src{{ url_for(static, filenamejs/app/client/base.js) }}/script script typetext/javascript src{{ url_for(static, filenamejs/app/client/access.js) }}/script同时必须保证 jQuery$与 lodash_可用组件源码 src/octoprint/static/js/app/client/access.js 依赖这两个全局对象script src{{ url_for(static, filenamejs/lib/jquery/jquery.min.js) }}/script script src{{ url_for(static, filenamejs/lib/lodash.min.js) }}/script引入完成后全局变量OctoPrintOctoPrintClient的实例即包含OctoPrint.access命名空间其内部结构在 src/octoprint/static/js/app/client/access.js 末尾组装var OctoPrintAccessClient function (base) { this.base base; this.permissions new OctoPrintAccessPermissionsClient(this); this.groups new OctoPrintAccessGroupsClient(this); this.users new OctoPrintAccessUsersClient(this); }; OctoPrintClient.registerComponent(access, OctoPrintAccessClient);OctoPrintClient.registerComponent见 src/octoprint/static/js/app/client/base.js会把组件懒加载挂到客户端原型上因此OctoPrint.access.permissions、OctoPrint.access.users、OctoPrint.access.groups均可直接访问。OctoPrintClient.access.permissions权限清单查询permissions.list(opts)获取系统内全部已注册权限的列表。参数optsobject请求的附加选项如自定义 headers、超时等返回值jQuery Promiseresolve 后携带权限列表响应。实现位于 src/octoprint/static/js/app/client/access.js 的OctoPrintAccessPermissionsClient.prototype.list内部仅调用this.base.get(api/access/permissions)。底层 REST 端点为GET /api/access/permissions见 docs/api/access.rst 的 “List all permissions” 小节服务端get_permissions返回形如{permissions: [ ... ]}的 JSON每个元素包含key、name、dangerous、default_groups、description、needs等字段由 src/octoprint/access/permissions.py 的OctoPrintPermission.as_dict定义。典型用法OctoPrint.access.permissions.list() .done(function (response) { console.log(response.permissions); });OctoPrintClient.access.users用户管理users子组件把用户相关的全部 REST 操作封装为 9 个方法统一以api/access/users为基地址见 src/octoprint/static/js/app/client/access.js 的OctoPrintAccessUsersClient。下方列出方法签名、权限要求、底层端点与典型示例。users.list(opts)获取所有已注册用户的列表。需要管理员权限底层端点GET /api/access/users服务端在 src/octoprint/server/api/access.py 的get_users中对每个用户调用as_dict()若近期未验证过凭据返回的用户记录中apikey会被置为null这是刻意的安全行为。OctoPrint.access.users.list() .done(function (response) { console.log(response.users); });用户记录的数据结构由 src/octoprint/access/users.py 的User.as_dict定义包含name、active布尔、permissions权限 key 列表、groups用户组 key 列表、needs、apikey、settings、has_password。users.get(name, opts)获取指定用户的信息。参数namestring用户名底层端点GET /api/access/users/username权限SETTINGS权限或登录身份即该用户本人服务端逻辑见 src/octoprint/server/api/access.py 的get_usercurrent_user.get_name() username or current_user.has_permission(Permissions.ADMIN)未知用户返回 404无权限返回 403。OctoPrint.access.users.get(user1) .done(function (user) { console.log(user.name, user.active, user.permissions); });users.add(user, opts)新增用户。需要管理员权限参数userobject新用户数据底层端点POST /api/access/users客户端前置校验见 src/octoprint/static/js/app/client/access.jsuser.name与user.password必须存在否则抛出InvalidArgumentError客户端自动构造的请求体name、password、groups缺省为[]、permissions缺省为[]、active缺省为true!!user.active强转布尔服务端add_user要求请求体包含name、password、active缺失时返回 400用户名重复返回 409用户名非法返回 400成功时返回用户列表响应与users.list相同结构。OctoPrint.access.users.add({ name: newuser, password: s3cr3t, active: true, groups: [users], permissions: [] }).done(function (response) { console.log(response.users); });users.update(name, active, permissions, groups, opts)更新既有用户。需要管理员权限参数namestring用户名、activebool新的激活状态、permissionslist权限 key 列表、groupslist用户组 key 列表、optsobject底层端点PUT /api/access/users/username客户端通过putJson提交{active: !!active, groups: groups, permissions: permissions}服务端update_user按请求体中出现的字段分别调用change_user_groups、change_user_permissions、change_user_activation见 src/octoprint/server/api/access.py未知用户返回 404。兼容性说明重要源码中保留了对旧参数顺序(name, active, admin, permissions, groups, opts)的兼容逻辑——当第三个参数permissions的类型是 boolean 时会将其视为旧的admin标志把所有参数左移一位并打印弃用警告if (typeof permissions boolean) { // old parameter order: name, active, *admin*, permissions, groups, opts console.log( Calling OctoPrint.access.users.update with admin flag is deprecated and will be removed in OctoPrint 3.0.0. Use permissions or groups instead. ); permissions groups; groups opts; opts arguments.length 6 ? arguments[5] : {}; }因此应始终使用新的五参数形式不要依赖旧的 admin 布尔标志。OctoPrint.access.users.update(newuser, true, [ADMIN], [admins]) .done(function (response) { /* ... */ });users.delete(name, opts)删除既有用户。需要管理员权限底层端点DELETE /api/access/users/username服务端remove_user中若目标用户即当前登录用户返回 400“You cannot delete yourself”未知用户返回 404成功时返回用户列表响应。OctoPrint.access.users.delete(newuser) .done(function (response) { /* ... */ });users.changePassword(name, password, oldpw, opts)修改指定用户的密码。参数namestring、passwordstring新密码、oldpwstring旧密码可选但大多数情况下必需、optsobject底层端点PUT /api/access/users/username/password客户端实现有一个便捷行为若第三个参数传入的是 object即调用者省略了oldpw直接传opts会自动把参数移位if (_.isObject(oldpw)) { opts oldpw; oldpw undefined; }请求体为{password: newPassword}仅在提供oldpw时才附加current: oldpw服务端规则见 docs/api/access.rst 与change_password_for_user拥有SETTINGS权限或登录身份即目标用户没有管理员权限时请求体必须包含current当前密码且服务端会校验其正确性若current被提供即使调用方有管理员权限也会一并校验典型错误码400缺password或必需的current、403无权限 / 非本人 / 凭据未近期验证 / 当前密码不匹配、404未知用户。// 用户本人修改自己的密码 OctoPrint.access.users.changePassword(user1, newpass, oldpass); // 管理员为他人改密不提供旧密码 OctoPrint.access.users.changePassword(user2, newpass);users.generateApiKey(name, opts)为用户生成重置新的个人 API Key。底层端点POST /api/access/users/username/apikey权限SETTINGS权限或登录身份即目标用户且要求近期凭据校验服务端generate_apikey_for_user无需请求体响应 JSON 中通过apikey属性返回新生成的 keyjsonify({apikey: apikey})生成逻辑在 src/octoprint/access/users.py 的generate_api_key。OctoPrint.access.users.generateApiKey(user1) .done(function (response) { console.log(New API key:, response.apikey); });users.resetApiKey(name, opts)将用户的个人 API Key 重置为未设置状态。底层端点DELETE /api/access/users/username/apikey权限同上SETTINGS权限或登录身份即目标用户且要求近期凭据校验成功后返回SUCCESS204 语义对应服务端delete_apikey_for_user调用的delete_api_key见 src/octoprint/access/users.py。OctoPrint.access.users.resetApiKey(user1);users.getSettings(name, opts)获取指定用户的个人设置。底层端点GET /api/access/users/username/settings权限SETTINGS权限或登录身份即目标用户服务端get_settings_for_user返回userManager.get_all_user_settings(username)未知用户返回 404无权限返回 403返回的 JSON 对象即该用户的个性化设置可能为空对象。OctoPrint.access.users.getSettings(user1) .done(function (settings) { /* ... */ });users.saveSettings(name, settings, opts)保存/更新指定用户的个人设置。参数settingsobject允许只传部分设置服务端会将其与现有设置合并merge而非整体覆盖底层端点PATCH /api/access/users/username/settingsPATCH 语义天然支持部分更新客户端通过patchJson提交settings settings || {}保证空对象合法权限SETTINGS权限或登录身份即目标用户当操作者是管理员非本人时服务端要求近期凭据校验成功后返回SUCCESS。OctoPrint.access.users.saveSettings(user1, { theme: dark }) .done(function () { /* 已合并保存 */ });OctoPrintClient.access.groups用户组管理groups子组件对应api/access/groups端点见 src/octoprint/static/js/app/client/access.js 的OctoPrintAccessGroupsClient。用户组group用于批量授予权限组内可包含权限列表、子组subgroups以及是否作为新用户默认组default。服务端模型在 src/octoprint/access/groups.py内置了admin、users、guest、readonly等默认组_init_defaults其中users组默认对新建用户生效。groups.list(opts)获取所有已注册用户组的列表。底层端点GET /api/access/groups返回{groups: [ ... ]}服务端get_groups对groupManager.groups逐个调用as_dict()权限SETTINGS权限见 docs/api/access.rst。OctoPrint.access.groups.list() .done(function (response) { console.log(response.groups); });groups.get(key, opts)获取指定用户组的信息。参数keystring用户组 ID注意是key而非显示名称底层端点GET /api/access/groups/key服务端get_group通过groupManager.find_group(key)查找未知组返回 404客户端前置校验key必须设置否则抛出InvalidArgumentError。OctoPrint.access.groups.get(admins) .done(function (group) { console.log(group); });groups.add(group, opts)新增用户组。需要管理员权限参数groupobject要求至少包含key与name还支持description、permissions、subgroups以及default布尔标志客户端前置校验group.key与group.name缺一不可否则抛出InvalidArgumentError请求体字段见客户端add实现与 REST 数据模型完全对应docs/api/access.rst 的 “Group registration request” 表字段必填类型说明key是string用户组标识符name是string用户组显示名称description否string可读描述缺省为空串permissions是string 列表分配给该组的权限 key 列表subgroups否string 列表作为子组的用户组 key 列表default否boolean是否将新用户默认加入该组缺省 false服务端add_group缺少key/name/permissions/subgroups任一字段返回 400组 key 已存在或存在循环子组引用CyclicSubgroupReference返回 409成功时返回组列表响应。OctoPrint.access.groups.add({ key: operators, name: Operators, description: Machine operators, permissions: [PRINT, MONITOR_TERMINAL], subgroups: [users], default: false }).done(function (response) { /* ... */ });groups.update(group, opts)更新既有用户组通过group.key标识目标组。需要管理员权限参数groupobject必须包含key只会更新以下字段description、permissions、subgroups、defaultkey与name不参与更新客户端在组装请求体时description若未在group中定义则置为空串group.hasOwnProperty(description) ? group.description : permissions、subgroups、default原样传递底层端点PUT /api/access/groups/key服务端update_groupdefault字段按valid_boolean_trues解析为布尔组不可修改GroupCantBeChanged如内置组返回 403未知组返回 404循环子组引用返回 409成功时返回组列表响应。OctoPrint.access.groups.update({ key: operators, description: Machine operators (updated), permissions: [PRINT, MONITOR_TERMINAL, FILES_DOWNLOAD], subgroups: [users], default: false }).done(function (response) { /* ... */ });groups.delete(key, opts)删除用户组。需要管理员权限参数keystring用户组 ID底层端点DELETE /api/access/groups/key服务端remove_group未知组返回 404组不可移除GroupUnremovable如内置组返回 403成功时返回组列表响应。OctoPrint.access.groups.delete(operators) .done(function (response) { /* ... */ });底层请求机制与 Promise 使用要点access组件的全部方法都基于 src/octoprint/static/js/app/client/base.js 提供的 HTTP 原语get(url, opts)GET对应groups.list、users.get等postJson(url, data, opts)POST Content-Type: application/json请求体经JSON.stringifyundefined 值会被替换为 null对应groups.add、users.add、users.generateApiKeyputJson(url, data, opts)PUT JSON对应groups.update、users.update、users.changePasswordpatchJson(url, data, opts)PATCH JSON对应users.saveSettingsdelete(url, opts)DELETE对应groups.delete、users.delete、users.resetApiKey。所有方法都返回 jQuery Promise可链式使用.done()、.fail()、.always()。鉴权头由getRequestHeaders统一注入设置了OctoPrint.options.apikey时发送X-Api-Key未设置时视为浏览器上下文对非 GET/HEAD/OPTIONS 方法自动附加X-CSRF-Token从csrf_tokencookie 读取跨域请求除外。因此无论是通过OctoPrint.options.apikey携带管理员 API Key还是依赖登录会话 CSRF Token上述方法都能正常工作。客户端参数校验通过OctoPrintClient.InvalidArgumentErrorcreateCustomException(InvalidArgumentError)定义于 src/octoprint/static/js/app/client/base.js抛出例如users.add缺用户名/密码、groups.add缺 key/name、所有按 key/name 定位的方法缺标识符时都会触发。完整示例面向多服务器的用户管理以下示例演示如何实例化独立客户端并组合使用 access 组件的方法参考 docs/jsclientlib/index.rst 的多客户端模式var client new OctoPrintClient({ baseurl: http://octopi.local/, apikey: ADMIN_API_KEY }); client.access.users.list() .fail(function (xhr) { if (xhr.status 403) { console.error(需要管理员权限或近期凭据校验); } }) .done(function (response) { // 过滤出当前激活的用户 var activeUsers response.users.filter(function (u) { return u.active; }); console.log(activeUsers); }); client.access.groups.add({ key: engineers, name: Engineers, permissions: [PRINT], subgroups: [users], default: false }).done(function () { console.log(组已创建); });权限、安全与错误处理速查综合 docs/api/access.rst、src/octoprint/server/api/access.py 与 src/octoprint/static/js/app/client/access.js整理各方法的权限与典型错误如下方法权限要求底层端点典型错误permissions.list无特殊要求GET/api/access/permissions—users.listADMINGET/api/access/users403users.getADMIN 或本人GET/api/access/users/name403 / 404users.addADMINPOST/api/access/users400 / 409users.updateADMINPUT/api/access/users/name400 / 404users.deleteADMINDELETE/api/access/users/name400删除自己/ 404users.changePasswordADMIN 或本人本人需currentPUT/api/access/users/name/password400 / 403 / 404users.generateApiKeyADMIN 或本人 近期凭据POST/api/access/users/name/apikey403 / 404users.resetApiKeyADMIN 或本人 近期凭据DELETE/api/access/users/name/apikey403 / 404users.getSettingsADMIN 或本人GET/api/access/users/name/settings403 / 404users.saveSettingsADMIN 或本人管理员需近期凭据PATCH/api/access/users/name/settings403 / 404groups.listSETTINGSGET/api/access/groups403groups.getSETTINGSGET/api/access/groups/key404groups.addADMIN 近期凭据POST/api/access/groups400 / 409groups.updateADMIN 近期凭据PUT/api/access/groups/key403 / 404 / 409groups.deleteADMIN 近期凭据DELETE/api/access/groups/key403 / 404几个值得注意的安全细节近期凭据校验用户组写操作以及管理员代他人执行改密、API Key、设置等操作时服务端强制要求近期凭据校验require_credentials_checked_recently/ensure_credentials_checked_recently见 src/octoprint/server/api/access.py从而避免会话被长期借用后直接执行敏感操作。API Key 脱敏users.list与users.get在凭据未近期验证时返回记录中的apikey一律置为null见get_users/get_user防止敏感信息泄露。内置组保护admin、users、guest、readonly等默认组受GroupCantBeChanged/GroupUnremovable保护删除或修改会分别收到 403。循环子组引用groups.add/groups.update若形成循环子组关系服务端返回 409客户端应捕获该错误并向用户提示。删除自身限制users.delete不允许删除当前登录用户服务端返回 400。扩展阅读与相关资源组件文档索引docs/jsclientlib/index.rst含客户端库的引入方式、OctoPrint全局实例与多客户端用法底层 REST API 完整文档docs/api/access.rst端点、数据模型、错误码客户端实现源码src/octoprint/static/js/app/client/access.js客户端基础组件请求原语与参数校验src/octoprint/static/js/app/client/base.js服务端 REST 实现src/octoprint/server/api/access.py权限模型src/octoprint/access/permissions.py用户模型src/octoprint/access/users.py用户组模型src/octoprint/access/groups.py第三方客户端授权工作流可参考内置的 Application Key 插件文档docs/bundledplugins/appkeys.rst它为外部客户端补充了额外的 JS Client Library 方法与本文的 API Key 机制互补。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐如何用Automated YouTube Channel打造24/7自动运行的YouTube频道终极指南如何用Automated YouTube Channel打造24/7自动运行的YouTube频道终极指南 Automated YouTube Channel是物联网后端GitHub_Trending/ma/machine-learning-for-trading中的协整检验配对交易策略开发GitHub_Trending/ma/machine learning for trading中的协整检验配对交易策略开发 GitHub_Trending/m示例工程金融科技机器学习人工智能深度学习如何通过802.1X认证实现网络访问控制完整指南如何通过802.1X认证实现网络访问控制完整指南 802.1X认证是IEEE制定的端口网络访问控制PNAC标准通过为有线和无线网络提供设备身份验证机制网络安全渗透测试密码学上一篇猫抓插件完整指南3步玩转浏览器资源嗅探网页视频下载不再求人下一篇FastAPI BackgroundTasks API 参考响应发出后调度后台任务的声明式用法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
