物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载导读OctoPrint 的系统 API 是 Web 前端与操作系统层交互的桥梁它负责把「关机」「重启」「重启 OctoPrint」这类系统级操作暴露为可编程的 REST 接口。本文以官方文档 docs/api/system.rst 为骨架结合 系统命令实现、SystemCommandManager 与 配置模型 等源码系统讲解 System API 的权限模型、三个核心端点、数据模型以及如何通过config.yaml和插件钩子扩展自己的系统命令。读完本文你将能独立完成系统命令的查询、执行与自定义配置。所有系统操作都需要SYSTEM权限。一、System API 概览与权限模型System API 位于/api/system命名空间下核心端点有三个方法路径作用GET/api/system/commands列出所有已注册的系统命令GET/api/system/commands/source列出指定来源的系统命令POST/api/system/commands/source/action执行一条系统命令权限要求所有端点都必须通过SYSTEM权限校验。在源码中可以看到每个路由都带有Permissions.SYSTEM.require(403)装饰器未授权请求会返回403 Forbidden系统 API 路由定义此外还有no_firstrun_access装饰器即首次运行设置向导尚未完成时这些端点同样不可访问。以 X-Api-Key 或登录会话认证后即可调用。命令来源source目前共有三类coreOctoPrint 自身定义的系统动作关机、重启系统、重启 OctoPrint、安全模式重启custom用户在config.yaml的system.actions中自定义的命令plugin插件通过octoprint.system.additional_commands钩子注册的命令注意当前文档写作时该来源已被实现源码中plugin是有效取值之一详见下文扩展章节。二、列出所有系统命令GET /api/system/commands端点语义该端点返回所有已配置的系统命令响应结构为按来源分组的对象每个来源对应一个 Client command definitions客户端命令定义 列表。请求示例GET /api/system/commands/core HTTP/1.1 Host: example.com X-Api-Key: abcdef...注请求路径末尾的core在该端点下实际会被忽略——无论请求什么路径响应的都是全部来源的命令列表。真正按来源过滤的是下一节的三段式端点。响应示例200 OK{ core: [ { action: shutdown, name: Shutdown, confirm: strongYou are about to shutdown the system./strong/ppThis action may disrupt any ongoing print jobs (depending on your printers controller and general setup that might also apply to prints run directly from your printers internal storage)., source: core, resource: http://example.com/api/system/commands/core/shutdown }, { action: reboot, name: Reboot, confirm: strongYou are about to reboot the system./strong/ppThis action may disrupt any ongoing print jobs (depending on your printers controller and general setup that might also apply to prints run directly from your printers internal storage)., source: core, resource: http://example.com/api/system/commands/core/reboot }, { action: restart, name: Restart OctoPrint, confirm: strongYou are about to restart the OctoPrint server./strong/ppThis action may disrupt any ongoing print jobs (depending on your printers controller and general setup that might also apply to prints run directly from your printers internal storage)., source: core, resource: http://example.com/api/system/commands/core/restart } ], custom: [] }状态码200表示无错误。源码视角响应是如何组装的retrieveSystemCommands 的实现清晰地展示了三个来源的聚合方式return jsonify( core_to_client_specs(_get_core_command_specs()), plugin_to_client_specs(_get_plugin_command_specs()), custom_to_client_specs(_get_custom_command_specs()), )_to_client_specs会对每条命令定义做「瘦身」只保留source、action、name、confirm、fresh_credentials五个字段并通过url_for动态生成resource执行 URL见 源码。这意味着完整命令定义含command命令行本身绝不会通过 API 暴露客户端只能拿到展示与调用所需的最小字段集。从源码看core命令只有在对应命令行已配置时才会出现在响应中_get_core_command_specs会遍历四条核心动作shutdown、reboot、restart、restart_safe凡是没有配置对应命令的都会跳过源码。因此如果你的环境中没有配置重启命令响应里就不会出现restart。三、按来源列出命令GET /api/system/commands/source端点语义该端点只返回指定source下的命令列表参数说明source命令来源目前为core、custom或plugin请求示例GET /api/system/commands/core HTTP/1.1 Host: example.com X-Api-Key: abcdef...响应示例200 OK——直接返回客户端命令定义列表[ { action: shutdown, name: Shutdown, confirm: strongYou are about to shutdown the system./strong/ppThis action may disrupt any ongoing print jobs (depending on your printers controller and general setup that might also apply to prints run directly from your printers internal storage)., source: core, resource: http://example.com/api/system/commands/core/shutdown }, { action: reboot, name: Reboot, confirm: strongYou are about to reboot the system./strong/ppThis action may disrupt any ongoing print jobs (depending on your printers controller and general setup that might also apply to prints run directly from your printers internal storage)., source: core, resource: http://example.com/api/system/commands/core/reboot }, { action: restart, name: Restart OctoPrint, confirm: strongYou are about to restart the OctoPrint server./strong/ppThis action may disrupt any ongoing print jobs (depending on your printers controller and general setup that might also apply to prints run directly from your printers internal storage)., source: core, resource: http://example.com/api/system/commands/core/restart } ]状态码200无错误404如果指定了core、custom、plugin之外的来源。从源码看来源分派逻辑非常直接source core走核心命令source custom走配置命令source plugin走插件钩子命令其余一律abort(404)源码。四、执行系统命令POST /api/system/commands/source/action端点语义执行source中标识为action的系统命令。参数说明source命令来源core或custom插件命令同样适用action命令标识符即其定义中的action字段示例通过核心命令restart重启 OctoPrint该命令仅在服务器重启命令已配置时可用POST /api/system/commands/core/restart HTTP/1.1 Host: example.com X-Api-Key: abcdef...响应HTTP/1.1 204 No Content状态码语义204执行成功无内容返回400试图执行divider菜单分隔符不可执行或请求格式错误404在source下找不到action对应的命令500命令未定义可执行的command、命令返回非零退出码且ignore未设为true或其他内部服务器错误。源码视角完整的执行链路executeSystemCommand 是这条链路的核心其关键步骤值得逐一拆解分隔符拦截command divider直接abort(400)——菜单分隔符只有展示意义永远不能被执行命令解析通过_get_command_spec(source, command)在 core / custom / plugin 三个来源中查找定义找不到则abort(404)命令存在性校验定义中缺少command字段时abort(500)凭证新鲜度如果定义带fresh_credentials: true则调用ensure_credentials_checked_recently()强制要求最近一次凭证校验通过防止「凭证已过期却仍执行高危命令」执行方式分派async: true时把执行丢进一个 daemon 线程后立即返回否则同步阻塞等待结果退出码处理命令通过CommandlineCaller().call(command_spec[command], shellTrue)以 shell 方式执行ignore: true时无论退出码如何都视为成功否则非零退出码会触发500源码。为什么用shellTrue源码注释说得非常直白「we run this with shellTrue since we have to trust whatever our admin configured as command and since we want to allow shell-alike handling here」——即系统命令本来就由管理员配置、必须受信任同时允许管道、重定向等 shell 风格写法。这也意味着配置系统命令的人必须谨慎因为其内容将以 shell 原样执行。值得注意的兼容层旧版的POST /api/system不带/commands仍可用但它只是一个兼容包装会打印弃用警告并把请求转发到/system/commands/custom/action该包装计划在 OctoPrint 3.0.0 中移除源码。新代码应直接使用/api/system/commands/custom/action。五、数据模型客户端命令定义与完整命令定义5.1 List all 响应结构GET /api/system/commands的响应包含两个键均为 0..n 的客户端命令定义列表名称多重性类型说明core0..nList of client command definitionsOctoPrint 定义的所有核心命令custom0..nList of client command definitions在config.yaml中定义的所有自定义命令5.2 客户端命令定义Client command definitions这是完整命令定义经 API 暴露时的受限形态字段如下名称多重性类型说明name1string在 System 菜单中显示的命令名称action1string以编程方式引用该命令的标识符特殊的divider表示菜单中的分隔线confirm0..1string若存在且非空执行前会向用户展示此确认对话框文本source1string命令定义来源coreOctoPrint 自身或custom用户通过config.yaml定义resource1string用于执行该命令的 URL5.3 完整命令定义Command definition完整定义不会通过 API 暴露仅存在于内部。字段如下名称多重性类型说明name1string在 System 菜单中显示的命令名称command1string要执行的完整命令行action1string编程引用标识符divider表示菜单分隔线confirm0..1string执行前展示的确认对话框文本async0..1bool是否异步执行不等待命令结束即响应 HTTP 请求ignore0..1bool是否忽略命令执行返回码source1stringcore或customresource1string用于执行该命令的 URL除上述字段外系统 API 实现 还支持fresh_credentials执行前强制最近凭证校验、debug命令执行时输出包含命令行的调试日志、before执行前回调失败时可中止命令等字段——它们属于内部扩展由自定义命令与插件钩子使用。六、实战在config.yaml中自定义系统命令官方配置文档 docs/configuration/config_yaml.rst 明确指出以下配置用于向 OctoPrint 顶部栏的 System 下拉菜单添加自定义系统命令。6.1 配置模型与默认值system.actions是ActionConfig的列表模型定义见 src/octoprint/schema/config/system.py每个动作的字段字段类型必填说明actionstring是内部使用的动作标识符设为divider可在菜单中生成分隔线namestring条件必填菜单中显示的名称非分隔线动作必须设置commandstring条件必填选中动作时要执行的命令非分隔线动作必须设置asyncbool否默认false是否异步执行confirmstring否执行前展示的可选确认消息fresh_credentialsbool否默认false是否要求执行前进行最近凭证校验默认行为OctoPrint 默认会阻塞等待命令返回以便用退出码展示成功或失败提示对于不会返回的命令如关机应使用async: true。可选地可以添加confirm消息在执行前弹出确认对话框若不希望出现确认框则不要设置该字段。6.2 完整示例以下示例定义了一条 Linux 下的关机命令前提是运行 OctoPrint 的用户已配置免密执行sudosystem: actions: - name: Shutdown action: shutdown command: sudo shutdown -h now confirm: You are about to shutdown the system.添加菜单分隔线system: actions: - action: divider6.3 源码视角自定义命令如何被读取与去重读取_get_custom_command_specs源码遍历settings().get([system, actions])为每条定义补上source: custom遇到action: divider时会自动生成divider_1、divider_2这样的内部标识符以便菜单正确渲染多条分隔线旧版迁移OctoPrint 1.3.0 起引入了迁移逻辑——如果config.yaml中仍把shutdown、reboot、restart定义为自定义系统命令会将其迁移到server.commands下的systemShutdownCommand、systemRestartCommand、serverRestartCommand三个专用配置项并从自定义命令中删除迁移映射见 src/octoprint/settings/init.py。因此核心动作应通过server.commands配置而不是自定义命令核心动作的配置项定义在 server.py 的 CommandsConfigsystemShutdownCommand关机系统、systemRestartCommand重启系统、serverRestartCommand重启 OctoPrint。SystemCommandManagersrc/octoprint/systemcommands/init.py负责从server.commands读取这些命令并以非阻塞方式执行——core 命令的async恒为true正是源于此。七、进阶通过插件钩子扩展系统命令从 OctoPrint 1.7.0 开始插件可以借助octoprint.system.additional_commands钩子向 System 菜单注册命令钩子规范见 docs/plugins/hooks.rst。钩子处理器需返回一个命令定义列表每个定义支持字段多重性类型说明name1string菜单中显示的名称action1string动作标识符仅允许小写 a-z、数字、-与_[a-z0-9-_]command1string要执行的系统命令confirm0..1string执行前的可选确认消息async0..1bool为True时异步执行API 调用在入队后立即返回ignore0..1bool为True时忽略命令及before的执行结果始终返回成功默认Falsedebug0..1bool为True时在日志中输出包含命令行的调试信息谨慎使用默认Falsebefore0..1callable执行command前的可选回调若ignore为 false 且回调失败命令不会执行并返回错误最小示例def get_additional_commands(*args, **kwargs): return [ { name: Just a test, action: test, command: logger This is just a test of an OctoPrint system command from a plugin, before: lambda: print(Hello World!) } ] __plugin_hooks__ { octoprint.system.additional_commands: get_additional_commands }源码视角_get_plugin_command_specs源码通过plugin_manager().get_hooks(octoprint.system.additional_commands)收集所有插件的钩子逐条校验action合法性拒绝空值、divider及不合规字符并为每条命令生成插件名:动作的复合 action 标识符如myplugin:test、标记source: plugin。插件钩子执行时出现的任何异常都会被记录日志并跳过该插件不影响其他插件注册。八、最佳实践与安全注意事项综合文档与源码使用 System API 时有几点值得牢记权限先行所有端点都要求SYSTEM权限且首次运行向导未完成时不可用。集成到第三方客户端时请使用 API Key 或具有 SYSTEM 权限的账号核心动作走专用配置关机、重启、重启 OctoPrint 应通过server.commands的systemShutdownCommand/systemRestartCommand/serverRestartCommand配置自定义命令用于真正的自定义操作高危命令加确认善用confirm字段让用户在执行前明确确认避免误触关机、重启等中断打印的操作不返回的命令用async: true否则 OctoPrint 会一直阻塞等待命令返回导致 API 请求挂起ignore与退出码命令非零退出默认会触发500响应若某些命令的退出码无实际意义设置ignore: true可避免误报shellTrue意味着命令即代码系统命令以 shell 原样执行配置命令的人等同于拥有服务器的 shell 访问权必须严格限定权限与输入来源新代码使用新端点POST /api/system是即将移除的兼容层统一改用POST /api/system/commands/source/action插件 action 命名空间化插件命令的 action 会被自动加前缀为插件名:动作开发插件时无需担心与其他插件冲突。通过本文的端点说明、数据模型拆解、config.yaml配置示例与插件钩子示例你现在可以完整地查询所有系统命令、按来源过滤、安全地执行命令并通过配置或插件把任意系统操作纳入 OctoPrint 的 System 菜单。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐OctoPrint命令注入防护安全执行系统命令OctoPrint命令注入防护安全执行系统命令 1. 命令注入风险与OctoPrint的安全挑战 命令注入是攻击者通过操纵应用输入来执行恶意系统命令的常见攻击物联网后端BabelDOC 高级配置指南一次性解决 PDF 翻译的兼容、扫描与术语难题BabelDOC 高级配置指南一次性解决 PDF 翻译的兼容、扫描与术语难题 BabelDOC 是一款保留原始版式的 PDF 翻译文档翻译工具。本文从输出打人工智能AI 应用NLP计算机视觉ParlAI 命令行完全指南parlai 超级命令、标准脚本与自定义扩展ParlAI 命令行完全指南parlai 超级命令、标准脚本与自定义扩展 导读 本文围绕 ParlAI 官方文档 docs/source/cli_usage.NLP人工智能深度学习上一篇Ease性能优化技巧让你的iOS动画流畅如丝下一篇突破性能瓶颈Apache Kudu后台维护任务全解析与调优指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
