物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载本篇技术指南以 OctoPrint 官方维护的 docs/plugins/deprecations.md 为骨架系统梳理当前仍处于活跃状态的弃用项deprecations与可能造成破坏的行为变更behaviour changes并按目标移除版本2.1.0、2.2.0、3.0.0 及未定版本分类。读完本文你将掌握模板前缀、自动转义、API 保护、设置读写方法、钩子重命名、JS 客户端方法迁移等每一项改动的具体表现、迁移步骤与可运行的代码示例避免你的插件或第三方客户端在 OctoPrint 未来版本中悄然失效。这份清单是 OctoPrint 面向插件作者plugin authors和第三方客户端third party clients的官方红线所有在此列出的内容都要求你现在就采取行动而不是等到对应版本发布后再处理。为什么需要关注这份弃用清单OctoPrint 对插件生态采取先警告、后移除的兼容策略某个接口或行为一旦被弃用会先进入兼容层并记录弃用警告历经多个版本周期后才真正删除。本文档汇总的每一项弃用都标注了引入弃用的版本如1.8.0、1.11.0、2.0.0与计划移除的版本插件作者可据此安排迁移节奏。仓库源码中的实现可以印证这一策略。例如 src/octoprint/util/init.py 中新函数thaw_frozendict是正式实现而旧名称thaw_immutabledict则是通过deprecated(...)装饰器包装出的兼容别名又如 src/octoprint/plugin/core.py 中blacklisted属性被标记为deprecated(blacklisted is deprecated in favor of blocklisted, since2.0.0)后仍返回self.blocklisted。这类包装层 警告日志的模式在下面各节中反复出现识别出这些模式有助于你在自己的代码中尽早排查。OctoPrint 2.1.0 的弃用项与行为变更插件模板必须使用plugin_插件标识符前缀自 OctoPrint 1.8.0 起在插件模板中引入其他模板而不带plugin_插件标识符前缀的做法已被弃用允许其继续工作的兼容层将在 OctoPrint 2.1.0 中移除。如果插件仍在使用不带前缀的模板引入现在就必须修复。需要检查两处代码1. 插件模板中对其他插件模板的引入。例如{% include snippets/my_snippet.jinja2 %}这种写法目前仍会被解析为相对当前插件未来必须改为显式前缀、指向目标插件{% include plugin_some_other_plugin/snippets/my_snippet.jinja2 %}2. 插件自己渲染的模板。例如通过BlueprintPluginmixin 创建的自定义路由中的flask.render_template调用octoprint.plugin.BlueprintPlugin.route(/foo, methods[GET]) def foo_endpoint(self): return flask.make_response( flask.render_template( some_template.jinja2 ) )对于标识符为my_plugin的插件需要改为octoprint.plugin.BlueprintPlugin.route(/foo, methods[GET]) def foo_endpoint(self): return flask.make_response( flask.render_template( plugin_my_plugin/some_template.jinja2 ) )从 src/octoprint/plugin/types.py 的get_template_folder实现可以看到插件模板默认位于插件基目录的templates子目录中OctoPrint 正是基于该目录与插件标识符建立模板命名空间因此前缀化是模板解析规则的核心。弃用自1.8.0TemplatePlugin模板自动转义从 opt-in 转为 opt-out自 OctoPrint 1.11.0 起OctoPrint 支持对全部插件模板强制开启自动转义auto-escaping。在 2.1.0 之前这是 opt-in 模式——插件必须主动告知 OctoPrint 才开启到 2.1.0OctoPrint 将默认对第三方插件也启用自动转义。如果插件实现了TemplatePlugin应先主动 opt-in 并完整测试插件class MyPlugin(octoprint.plugin.TemplatePlugin): # ... def is_template_autoescaped(self): return True仓库中 src/octoprint/plugin/types.py 的is_template_autoescaped默认实现已经返回True其 docstring 明确注明Since OctoPrint 2.1.0 this defaults toTrue这正是文档所述默认行为切换的源码落点。迁移与测试建议如果出现问题理想情况下应在不关闭自动转义的前提下修复仅在个别位置需要从变量输出 HTML 时使用手动转义过滤器|e或按需标记安全的|safe务必只在完全受你控制的代码中使用|safe不要标记任何可能受用户输入影响的变量或输出否则会带来 XSS 风险可参考 OctoPrint 官方社区 FAQ 中关于自动转义的条目见原文档的链接。弃用自1.11.0SimpleApiPlugin端点保护从 opt-in 转为 opt-out自 OctoPrint 1.11.2 起OctoPrint 支持对全部SimpleApiPlugin端点强制基础认证。在 2.1.0 之前这是 opt-in 模式到 2.1.0OctoPrint 将默认保护所有端点。插件作者应先主动 opt-in 并完整测试class MyPlugin(octoprint.plugin.SimpleApiPlugin): # ... def is_api_protected(self): return Truesrc/octoprint/plugin/types.py 中的is_api_protected默认实现同样已返回True并在 docstring 中提醒即使开启了保护OctoPrint 也只检查是否有有效用户登录插件仍应在 API 端点内自行加入针对本插件的权限检查。迁移要点如遇问题优先修复问题而不是关闭保护若因实现原因或预期工作流确实无法开启可显式返回False选择 opt-out并手动为不应完全开放的端点实现认证。弃用自1.11.2移除SettingsViewModel.usersSettingsViewModel.users已不再被 OctoPrint 核心使用将在 2.1.0 移除。如果插件依赖它而不是在自身 view model 中声明对accessViewModel的依赖从而访问accessViewModel.users请按如下步骤迁移在插件的 view model 中添加对accessViewModel的依赖将所有self.settingsViewModel.users或你保存注入的SettingsViewModel实例的参数名替换为self.accessViewModel.users。弃用自2.0.0events.yaml中系统命令事件订阅的shell参数默认值变更在events.yaml中配置的系统命令事件订阅若未显式定义shell参数目前生成的命令调用默认shellTrue。由于这存在安全隐患OctoPrint 2.1.0 将把默认值改为shellFalse。如果事件订阅依赖 shell 行为如 shell 展开、管道、重定向现在就必须显式加上shell: true以免在 2.1.0 中失效# events.yaml 示例显式声明 shell 行为 events: - event: PrintDone command: /path/to/script.sh arg1 arg2 shell: true弃用自2.0.0OctoPrint 2.2.0 的弃用项移除SettingsViewModel中的 webcam 兼容层下列仍存在于SettingsViewModel中的 observable 自 OctoPrint 1.9.0 起已弃用访问时会打印弃用警告将在 2.2.0 中彻底移除替代项如下已弃用的 observable替代项webcam_streamUrlsettings.webcam.streamUrlwebcam_streamRatiosettings.webcam.streamRatiowebcam_streamTimeoutsettings.webcam.streamTimeoutwebcam_streamWebrtcIceServerssettings.webcam.webrtcIceServerswebcam_snapshotUrlsettings.webcam.snapshotUrlwebcam_flipHsettings.webcam.flipHwebcam_flipVsettings.webcam.flipVwebcam_rotate90settings.webcam.rotate90webcam_cacheBustersettings.webcam.cacheBuster弃用自1.9.0移除重命名后的SlicingViewModel.gcodeFilenameSlicingViewModel.gcodeFilename自 2.0.0 起已重命名为SlicingViewModel.destinationFilename旧名称支持将在 OctoPrint 2.2.0 移除。若插件使用该 observable请相应调整。弃用自2.0.0OctoPrint 3.0.0 的弃用项移除重命名后的PluginSettings.(get|set)(Int|Float|Boolean)注入到插件实现中、以self._settings访问的PluginSettings实例上的getInt、getFloat、getBoolean、setInt、setFloat、setBoolean六个方法已被弃用并记录弃用警告长达十年但仍被大量第三方插件重度使用。文档给出的是最终警告插件作者必须切换到长期存在的替代方法get_(int|float|boolean)与set_(int|float|boolean)。实践中就是以下简单的替换self._settings.getInt→self._settings.get_intself._settings.getFloat→self._settings.get_floatself._settings.getBoolean→self._settings.get_booleanself._settings.setInt→self._settings.set_intself._settings.setFloat→self._settings.set_floatself._settings.setBoolean→self._settings.set_boolean从源码看旧方法并未直接消失。例如 src/octoprint/settings/init.py 中的getInt仍实现着完整的取整与min/max边界收敛逻辑int(value)转换失败时记录警告并返回Nonesrc/octoprint/settings/init.py 的setInt则负责写入前的类型转换与边界约束。这些语义在get_int/set_int等新方法中保持一致因此迁移是纯机械的改名操作。OctoPrint 3.0.0 将彻底移除旧版本。弃用自1.2.0移除重命名后的octoprint.users.factory钩子插件钩子octoprint.users.factory自 OctoPrint 2.0.0 起弃用将在 3.0.0 移除其长期替代者是octoprint.access.users.factory。仍实现旧钩子的插件请把注册改为这个可直接替换的新名称。仓库中 src/octoprint/server/init.py 展示了这一兼容逻辑服务器会同时收集octoprint.users.factory与octoprint.access.users.factory两个钩子并对注册了旧钩子的插件打印警告信息提示切换到新名称。另外 src/octoprint/cli/user.py 的 CLI 说明文档也明确将用户管理器来源指向octoprint.access.users.factory钩子。弃用自2.0.0移除OctoPrintClient.access.users.update的admin参数自 2.0.0 起在第三个位置以admin参数调用OctoPrintClient.access.users.update已弃用3.0.0 将不再支持。请改用permissions或groups参数来添加或移除用户账号的管理员权限。完整调用签名可参考 docs/jsclientlib/access.rst 中OctoPrintClient.access.users.update的文档。弃用自2.0.0移除OctoPrintClient.printer上重命名的打印机存储方法OctoPrintClient.printer上的以下方法已重命名issueSdCommand→issueStorageCommandgetSdState→getStorageStateinitSd→initStoragereleaseSd→releaseStoragerefreshSd→ 未重命名但被替代改用OctoPrintClient.files.listForLocation旧名称仍可用但会在浏览器控制台打印弃用警告。若插件或其他客户端使用这些方法请切换到新名称。弃用自2.0.0移除AccessViewModel.isCurrentUser改用AccessViewModel.isUserMyselfAccessViewModel.isCurrentUser已重命名为AccessViewModel.isUserMyself目的是消除旧名称的歧义。请相应替换代码中的用法。弃用自2.0.0移除FilesViewModel上重命名的打印机存储方法FilesViewModel上的以下方法已重命名initSdCard→initPrinterStoragereleaseSdCard→releasePrinterStoragerefreshSdFiles→refreshPrinterStorage旧名称仍可用但会在浏览器控制台打印弃用警告。请切换到新名称。弃用自2.0.0从事件TransferStarted、TransferDone、TransferFailed移除local参数TransferStarted、TransferDone、TransferFailed事件的 payload 目前仍包含local属性自 2.0.0 起它已与path相同并将在 3.0.0 移除。相关事件定义可参考 docs/events/index.rst 中文件处理file handling部分的可用事件列表。弃用自2.0.0移除重命名后的OctoPrintClient.plugins.appkeys.revokeKeyOctoPrintClient.plugins.appkeys.revokeKey已重命名为OctoPrintClient.plugins.appkeys.revokeKeyForApp。旧名称仍可用但会在浏览器控制台打印弃用警告。请切换到新名称。弃用自1.10.0移除POST /api/system兼容包装遗留的POST /api/systemAPI 端点自 1.3.0 起已被POST /api/system/commands/custom/action替代。旧端点目前仍作为兼容包装保留内部重定向到新端点并记录弃用警告将在 3.0.0 移除。若插件或其他客户端仍请求POST /api/system请立即切换到POST /api/system/commands/custom/action。弃用自1.3.0尚未确定移除版本的弃用项以下弃用项尚无明确移除版本但同样要求插件作者尽快迁移。octoprint.printer.standard.Printer即self._printer上的弃用方法已弃用方法替代方案get_connection_options使用ConnectedPrinter.all()并结合返回的ConnectedPrinter实例上的connection_optionsselect_fileset_jobunselect_fileset_job传入Nonefake_ackrepair_communicationget_transport仅当当前连接器恰好是内置 serial connector 时才可用如有使用请通过功能请求反馈用途get_current_connectionconnection_state兼容层仅在当前连接器为内置 serial connector 时可用is_sd_readyis_storage_mountedinit_sd_cardmount_storagerelease_sd_cardunmount_storageget_sd_files通过文件管理器使用printer存储add_sd_file通过文件管理器使用printer存储delete_sd_file通过文件管理器使用printer存储refresh_sd_files通过文件管理器使用printer存储can_modify_file直接对比作业参数与current_job并检查当前打印状态is_current_file直接对比作业参数与current_job弃用自2.0.0迁移示例select_filefrom octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(2): job self._file_manager.create_job(storage, path) self._printer.set_job(job, print_after_selectFalse) else: is_sd storage FileDestinations.SDCARD file_to_select path if is_sd else self._file_manager.path_on_disk(storage, path) self._printer.select_file(file_to_select, sdis_sd, printAfterSelectFalse)迁移示例unselect_filefrom octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(2): self._printer.set_job(None) else: self._printer.unselect_file()迁移示例refresh_sd_files与get_sd_filesfrom octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(2): self._file_manager.list_storage_entries([FileDestinations.PRINTER], force_refreshblocking) else: self._printer.get_sd_files(blockingblocking)迁移示例can_modify_filefrom octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(2): current_job self._printer.current_job is_current_job current_job is not None and current_job.path path and current_job.storage storage return not (is_current_job and (self._printer.is_printing() or self._printer.is_paused())) else: is_sd storage FileDestinations.SDCARD storage_path path if is_sd else self._file_manager.path_on_disk(storage, path) return self._printer.can_modify_file(storage_path, is_sd)迁移示例is_current_filefrom octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(2): current_job self._printer.current_job return current_job is not None and current_job.path path and current_job.storage storage else: is_sd storage FileDestinations.SDCARD storage_path path if is_sd else self._file_manager.path_on_disk(storage, path) return self._printer.is_current_file(storage_path, is_sd)这些示例中使用到的is_octoprint_compatible是 OctoPrint 提供的版本兼容性判断工具实现在 src/octoprint/util/version.py可让插件在迁移期间同时兼容新旧两代 API——这正是官方推荐的渐进式迁移方式。移除对octoprint.util.comm的直接访问octoprint.util.comm模块已迁移到内置插件serial_connector中现在以octoprint.plugins.serial_connector.serial_comm形式存在。直接访问octoprint.util.comm已弃用目前仅保留为从新位置再导出的兼容层。如果插件从octoprint.util.comm导入任何内容请将导入切换到octoprint.plugins.serial_connector.serial_comm。仓库中 src/octoprint/plugins/serial_connector/connector.py 即从.serial_comm导入MachineCom、baudrateList、serialList等核心符号印证了新的模块位置。弃用自2.0.0octoprint.filemanager.FileManager即self._filemanager上的弃用方法list_files→list_storage_entriesget_file→get_storage_entryadd_link→ 无替代remove_link→ 无替代弃用自2.0.0octoprint.filemanager.storage.StorageInterface及所有存储实现上的弃用方法last_modified→get_lastmodifiedget_file→get_storage_entrylist_files→list_storage_entriesadd_link→ 无替代remove_link→ 无替代弃用自2.0.0移除octoprint.server.util.flask.get_remote_address由flask.request.remote_addr替代。弃用自1.10.0octoprint.plugin.PluginInfo.blacklisted重命名为blocklistedoctoprint.plugin.PluginInfo.blacklisted已重命名为octoprint.plugin.PluginInfo.blocklisted请相应调整调用代码。源码中 src/octoprint/plugin/core.py 将状态保存在self.blocklisted属性上而 src/octoprint/plugin/core.py 的旧属性名则通过deprecated(...)包装转发到新属性插件管理器前端也在 pluginmanager.js 等位置统一使用blocklisted字段。弃用自2.0.0octoprint.util.thaw_immutabledict重命名为thaw_frozendictoctoprint.util.thaw_immutabledict已重命名为octoprint.util.thaw_frozendict请相应调整调用代码。源码实现见 src/octoprint/util/init.pythaw_frozendict递归地将冻结的字典解冻为普通字典并深拷贝值旧名称thaw_immutabledict作为兼容别名继续存在。弃用自1.8.0移除serial.*设置兼容覆盖层随着串口通信栈迁移到内置serial_connector插件原先位于serial.*下的所有设置均已迁移。目前一个只读兼容覆盖层会把新设置暴露在旧的serial.*路径下读取会返回当前值并记录弃用警告写入则被静默丢弃。该覆盖层将在未来版本移除。如果插件读写serial.*下的设置请切换到新位置连接参数serial.port→printerConnection.preferred.parameters.portserial.baudrate→printerConnection.preferred.parameters.baudrateserial.autoconnect→printerConnection.autoconnectserial.autorefresh→printerConnection.autorefreshserial.autorefreshInterval→printerConnection.autorefreshInterval被抑制的命令通知serial.notifySuppressedCommands→feature.notifySuppressedCommands校验和与错误处理serial.alwaysSendChecksum/serial.neverSendChecksum→plugins.serial_connector.sendChecksum现在是枚举取值always、never、printingserial.disconnectOnErrors/serial.ignoreErrorsFromFirmware→plugins.serial_connector.errorHandling现在是枚举取值disconnect、ignore、cancel端口与波特率黑名单serial.blacklistedPorts→plugins.serial_connector.blocklistedPortsserial.blacklistedBaudrates→plugins.serial_connector.blocklistedBaudrates其他所有原serial.*设置 →plugins.serial_connector.*键名相同弃用自2.0.0移除Blacklist设置兼容覆盖层包含Blacklist的设置键已重命名为Blocklist。目前一个只读兼容覆盖层会把新设置暴露在旧名称下读取会返回当前值并记录弃用警告写入则被静默丢弃。该覆盖层将在未来版本移除。如果插件读写以下任一设置请切换到新名称feature.autoUppercaseBlacklist→feature.autoUppercaseBlocklistserver.pluginBlacklist→server.pluginBlocklist弃用自2.0.0移除webcam.*设置兼容覆盖层顶层webcam.*设置已被 OctoPrint 1.9.0 引入的新 webcam 系统取代配置现在由实现WebcamProviderPluginmixin 的插件提供。目前一个只读兼容覆盖层会把当前配置的默认 webcam 配置暴露在旧的webcam.*路径下读取会返回当前值并记录弃用警告写入则被静默丢弃。该覆盖层将在未来版本移除。如果插件通过全局设置路径webcam.*读写 webcam 配置请切换到WebcamProviderPluginmixin 提供的方法。弃用自1.9.0迁移路线图按版本分步自查将以上内容整理成可执行的行动清单面向 2.1.0模板引入与渲染全部加plugin_标识符前缀TemplatePlugin先 opt-in 自动转义并修复问题SimpleApiPlugin先 opt-in 端点保护并补充权限检查view model 改用accessViewModel.usersevents.yaml中依赖 shell 行为的事件订阅显式声明shell: true。面向 2.2.0替换SettingsViewModel中的 9 个 webcam observable将SlicingViewModel.gcodeFilename改为destinationFilename。面向 3.0.0完成PluginSettings六个方法的机械改名切换octoprint.users.factory钩子注册移除admin参数、打印机存储方法、isCurrentUser、revokeKey、POST /api/system等 JS 客户端与服务端 API 的旧用法。无确定版本但应尽快处理self._printer与self._filemanager的旧方法、octoprint.util.comm导入、serial.*/Blacklist/webcam.*兼容覆盖层读写、blacklisted/thaw_immutabledict等重命名项。迁移时建议优先使用is_octoprint_compatible见 src/octoprint/util/version.py编写兼容新旧版本的代码路径并密切关注浏览器控制台与服务器日志中打印的弃用警告——它们会精准指出你的插件命中了哪些弃用项。完整插件开发与迁移背景可进一步参考 docs/plugins/hooks.rst、docs/plugins/mixins.rst 以及官方提供的 2.0.0 迁移指南 docs/plugins/migration_2_0_0.md。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐dokku 0.34.0 迁移指南关键移除、行为变更与弃用项深度解读dokku 0.34.0 迁移指南关键移除、行为变更与弃用项深度解读 导读 本文系统梳理 dokku 0.34.0 版本中引入的破坏性变更Removals云原生DevOps后端Spring Boot Admin 4.x 升级完全指南破坏性变更、弃用项与迁移清单Spring Boot Admin 4.x 升级完全指南破坏性变更、弃用项与迁移清单 Spring Boot AdminSBA是监控和管理 Spring后端可观测性指标监控监控大盘MCP 服务PySpark 升级迁移指南从 1.x 到 4.3 的行为变更、弃用与兼容性选项全解析PySpark 升级迁移指南从 1.x 到 4.3 的行为变更、弃用与兼容性选项全解析 PySpark 每次大版本升级都伴随着 Python 依赖版本门槛的提大数据数据分析批处理流处理机器学习图计算上一篇compromise-dates 插件全解析用自然语言解析日期、时间与时长下一篇探索N32G031单片机一站式学习与开发资源包创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考