物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载导读本文以 docs/modules/schema.rst 为线索系统梳理 OctoPrint 2.x 中以 pydantic 模型为核心的octoprint.schema包它既是config.yaml的权威类型定义层也是文件管理、作业状态等 REST API 响应体的数据契约。读完本文你将掌握octoprint.schema.config下二十余个配置子模型的字段含义与默认值、API 与 webcam 数据模型的组织方式以及 settings 子系统如何借助它生成默认配置。一、schema.rst在做什么Sphinx automodule 文档的组织方式docs/modules/schema.rst本身是一个 Sphinx 模块文档占位页它通过automodule指令把octoprint.schema包及其全部子模块的 docstring 自动渲染成 API 参考文档octoprint.schema包级模块导出基础模型基类octoprint.schema.config配置 schema 包以及其下 21 个按主题拆分的子模块access_control、api、appearance、controls、devel、estimation、events、feature、folder、gcode_analysis、plugins、printer_parameters、printer_profiles、scripts、server、slicing、system、temperature、terminalfilters、webcam外加printer_connectionoctoprint.schema.webcam独立的 webcam 描述模型。换句话说该页面渲染后的正文就是这些模块里每个类的字段 docstring。因此要真正读懂这篇文档需要直接对照源码树 src/octoprint/schema这也是本文接下来要做的事。文档还通过:members:与:undoc-members:保证所有公开类、属性都会被收录。二、基础构建块BaseModel与BaseModelExtra整个 schema 体系建立在两个自定义 pydantic 基类之上定义于 src/octoprint/schema/init.pyCONFIG_KWARGS { use_enum_values: True, validate_default: True, use_attribute_docstrings: True, } class BaseModel(PydanticBaseModel): model_config ConfigDict(**CONFIG_KWARGS) class BaseModelExtra(PydanticBaseModel): model_config ConfigDict(extraallow, **CONFIG_KWARGS)三个关键配置项的含义use_enum_valuesTrue枚举字段在序列化时直接使用其值如SameSiteEnum.lax输出为字符串Lax而不是枚举对象本身方便与 YAML 配置对接validate_defaultTrue默认值同样会经过类型校验防止默认值本身越界use_attribute_docstringsTrue属性 docstring 会成为 pydantic 字段描述这正是automodule能渲染出字段说明的来源BaseModelExtra额外开启extraallow允许未知字段存在而不报错——它被用于 API 响应模型中确保向后兼容额外返回的键例如ApiEntryAnalysis、ApiStorageEntry。三、配置 Schema 总览Config聚合根src/octoprint/schema/config/init.py 定义了一个聚合根模型Config它把全部配置子模型按顶层键组装起来结构上与config.yaml的顶层键一一对应顶层键模型类顶层键模型类accessControlAccessControlConfigpluginsPluginsConfigapiApiConfigprinterConnectionPrinterConnectionConfigappearanceAppearanceConfigprinterParametersPrinterParametersConfigcontrolslist[CustomControl \| CustomControlContainer]printerProfilesPrinterProfilesConfigdevelDevelConfigscriptsScriptsConfigestimationEstimationConfigserverServerConfigeventsEventsConfigslicingSlicingConfigfeatureFeatureConfigsystemSystemConfigfolderFolderConfigtemperatureTemperatureConfiggcodeAnalysisGcodeAnalysisConfigterminalFilterslist[TerminalFilterEntry]默认DEFAULT_TERMINAL_FILTERSwebcamWebcamConfig值得注意的是controls与terminalFilters是列表而非嵌套模型terminalFilters的默认值直接取自同模块导出的DEFAULT_TERMINAL_FILTERS常量。顶层配置中还引入了 src/octoprint/schema/config/printer_connection.py注意该文件在 RST 中没有单独列目但属于config包被统一渲染的部分它描述串口连接的自动刷新、自动连接与preferred首选连接默认connectorserial参数port/baudrate均为None。四、server服务端核心配置src/octoprint/schema/config/server.py 是内容最丰富的子模块包含 12 个模型类4.1ServerConfig顶层字段host默认None绑定地址不设置时绑定所有 IPv4/IPv6 接口port默认5000监听端口firstRun默认true首次运行向导开关完成后自动置falsestartOnceInSafeMode默认false下次启动进入安全模式后自动复位ignoreIncompleteStartup默认false忽略不完整启动便于开发secretKeyCookie 加密密钥首次运行随机生成切勿手动修改会令所有登录失效heartbeat默认 15 分钟心跳日志间隔maxSize默认100 * 1024即 100KB非文件上传类请求的体积上限allowFraming默认false是否允许被嵌入 iframeallowedLoginRedirectPaths允许作为登录页重定向目标的路径白名单默认基础上额外包含/、/recovery/、/plugin/appkeys/auth/seenWizards已展示向导及版本的记录通常无需手动维护。4.2 反向代理ReverseProxyConfigreverseProxy子配置用于让 OctoPrint 在 haproxy/nginx/apache 之后生成正确的外部 URL 与客户端 IP。头部配置prefixHeader默认X-Script-Name、schemeHeader默认X-Scheme、hostHeader默认X-Forwarded-Host、serverHeader与portHeader默认None与对应的*Fallback成对出现能收到代理头就用头收不到就回退到手动指定值。此外trustedProxies默认[]信任的代理地址/CIDR 列表trustLocalhostProxies默认true始终把127.0.0.0/8与::1视为可信代理OctoPi 场景默认可用。4.3 上传、磁盘与缓存uploadsUploadsConfigmaxSize默认 1GBnameSuffixname与pathSuffixpath用于流式上传时在内部请求头里携带原始文件名与临时文件路径diskspaceDiskspaceConfigwarning默认 500MB、critical默认 200MB触发不同级别的磁盘空间告警preemptiveCachePreemptiveCacheConfigexceptions为排除的路径列表until默认 7为预缓存配置中未使用条目的保留天数。4.4 在线检查与插件封禁onlineCheckOnlineCheckConfigenabled默认None由设置向导让用户决策、interval默认 15 分钟、host默认1.1.1.1DNS 查询目标、port默认53、name默认octoprint.org域名解析校验目标pluginBlocklistPluginBlocklistConfigenabled默认None同样交给向导、ttl默认 15 分钟、timeout默认 3.05 秒pythonEolCheckPythonEolCheckConfigenabled默认true、ttl默认 24 小时并内置fallback数据如 Python 3.7 于 2023-06-27 EOL、最后支持版本1.11.*在线获取失败时兜底。4.5 Cookie 与会话安全CookiesConfig中secure默认false仅当反向代理做 SSL 终结时才置truesamesite默认Lax。docstring 特别提示如果强制取消 SameSite 设置会带来安全影响——现代浏览器默认按Lax处理除非同时配置Secure标志、显式设置 SameSite 且通过 https 提供服务Lax已知会影响把 OctoPrint 嵌入 iframe 的场景。commandsCommandsConfig则定义了系统关机、系统重启、服务重启命令以及localPipCommand默认自动探测当前 Python 环境的 pip一般无需手动配置。五、accessControl用户、组与认证src/octoprint/schema/config/access_control.py 的AccessControlConfig控制 ACL 体系三个管理器实现userManager默认octoprint.access.users.FilebasedUserManager、groupManager默认octoprint.access.groups.FilebasedGroupManager、permissionManager默认octoprint.access.permissions.PermissionManager存储文件userfile/groupfile默认落在配置目录下的users.yaml/groups.yamlsalt是密码哈希盐docstring 用加粗DO NOT TOUCH!强调修改后现有账号将无法登录自动登录autologinLocal默认falselocalNetworks默认[127.0.0.0/8, ::1/128]autologinAs可让局域网来源自动以指定用户登录同时依赖正确的反向代理头读取客户端 IPX-Forwarded-For前置认证代理trustBasicAuthentication默认false仅当实例被 Basic Auth 完全锁定时才开启、checkBasicAuthenticationPassword默认true、trustedAuthProxiesremoteUserHeader默认REMOTE_USER、trustRemoteGroupsremoteGroupsHeader默认REMOTE_GROUPS与remoteGroupsMapping、addRemoteUsers默认false远程用户不存在时是否自动建档会话与再认证defaultReauthenticationTimeout默认 5 分钟置 0 将关闭危险操作的再认证有安全影响、sessionStaleAfter默认 15无活动会话视为过期并清除。六、appearance界面外观与 UI 组件编排src/octoprint/schema/config/appearance.py 除了name、colorColorEnumred/orange/yellow/green/blue/violet/default、colorTransparent、defaultLanguage默认_default跟随浏览器语言、showFahrenheitAlso、fuzzyTimes、closeModalsWithClick、showInternalFilename之外还有两个独立的子模型componentsComponentConfig由orderComponentOrderConfig和disabledComponentDisabledConfig组成。order定义了 navbar、sidebar、tab、settings、usersettings、wizard、about、generic 八个容器中组件的默认顺序例如 tab 顺序为temperature → control → plugin_gcodeviewer → terminal → timelapsedisabled则按容器列出被禁用的组件被禁用的组件将完全不进入 UI——如果无替代实现可能造成关键功能缺失thumbnailsThumbnailConfig文件列表缩略图filelistEnabled默认 true、filelistScale默认 25% 宽度、filelistAlignment默认 left、filelistPreview默认 false与状态面板缩略图stateEnabled默认 true、stateScale默认 75%。七、controls自定义控件src/octoprint/schema/config/controls.py 定义了controls列表元素的结构用于在控制标签页添加自定义按钮、滑块与信息展示CustomControlname按钮/标签文本、descriptiontooltip、三选一的动作来源command单条 GCODE/commands多条 GCODE/script完整 GCODE 脚本输入参数在模板中以parameter.xxx形式可用、javascript自定义点击行为data指向控件自身、self指向 ControlViewModel、additionalClasses如btn-danger、enabledJS 表达式覆盖默认启用逻辑、inputCustomControlInput列表定义占位符参数、默认值与可选slider滑杆、regextemplate从打印机回传行中提取信息并按 Python Format String 渲染、confirm点击确认文本CustomControlContainerchildren递归嵌套子控件/子容器name为分组标题layoutLayoutEnumvertical/horizontal/horizontal_grid控制排布collapsed决定是否默认折叠CustomControlInputname、parameter在 command 中作占位符、defaultstr/int/float/bool、可选slidermin默认 0、max默认 255、step默认 1。八、feature、folder与功能开关类配置8.1FeatureConfigfeature.py功能开关集中地temperatureGraph、sdSupport、keyboardControl、modelSizeDetection默认 true、pollWatched默认 false依赖 OS 文件系统通知而非主动轮询、rememberFileFolder、printStartConfirmation、printCancelConfirmation、uploadOverwriteConfirmation、fileDeleteConfirmation、enableDragDropUpload均为布尔开关autoUppercaseBlocklist默认[M117,M118,M707,M708]列出终端发送时禁止自动大写的命令g90InfluencesExtruder只影响 GCODE 分析与内置查看器的耗材用量计算enforceReallyUniversalFilenames默认 false可把特殊字符替换为兼容文本notifySuppressedCommandsSuppressionNotificationLevelEnuminfo/warn/never控制被抑制命令的通知级别。8.2FolderConfigfolder.py全部字段为可选绝对路径未设置时回退到 base 目录下的默认文件夹uploads、timelapse、timelapse_tmp、logs、virtualSd、watched、plugins单文件插件目录、slicingProfiles、printerProfiles、scripts、translations、generated、data、uploadtemp上传缓冲目录。8.3 其他功能类子模块estimationestimation.pyPrintTimeEstimationConfig控制打印时间估算——statsWeighingUntil默认 0.5指在打印前 50% 阶段把统计时长与计算估算加权混合validityRange默认 0.15限定假设百分比与实际百分比的可信区间forceDumbFromPercent默认 0.3与forceDumbAfterMin默认 30 分钟决定何时退化为线性估算stableThreshold默认 60 秒为计算估算的稳定判定阈值eventsevents.pyEventSubscription定义事件订阅——event、commandGCODE 或系统命令、typesystem/gcode、enabled、debug替换占位符后记录日志、nameUI 展示名gcodeAnalysisgcode_analysis.pymaxExtruders默认 10、throttle_normalprio默认 0.01s/throttle_highprio默认 0.0s每批 GCODE 行间的节流停顿、throttle_lines默认 100、runAtRunAtEnumnever/idle/always默认 idle 即空闲时分析、bedZ默认 0.0床面 Z 位置temperaturetemperature.py内置 ABS210/100与 PLA180/60两个快速预热profilescutoff默认 30 分钟为温度数据截断窗口sendAutomatically默认 false与sendAutomaticallyAfter默认 1 秒控制 UI 改温后是否自动下发terminalfiltersterminalfilters.pyTerminalFilterEntry由nameregex组成DEFAULT_TERMINAL_FILTERS预置了抑制 M105 温度、M27 SD 状态、M114 位置、wait 响应与 busy: processing 五条正则。九、webcam与 timelapseWebcamConfigwebcam.py核心字段webcamEnabled/timelapseEnabled默认 true分别控制 UI 中的摄像头画面与快照式延时摄影ffmpeg默认None不设置则禁用延时摄影、ffmpegThreads默认 1、ffmpegVideoCodec默认libx264、bitrate默认10000k直接传给 ffmpeg、watermark默认 true是否叠加 created with OctoPrint 水印ffmpegCommandline支持占位符ffmpeg/fps/input/videocodec/threads/bitrate/containerformat/filters/outputffmpegThumbnailCommandline支持ffmpeg/input/outputtimelapseTimelapseConfigtypeoff/zchange/timed、fps默认 25、postRoll默认 0片尾追加秒数zchange 重复末帧、timed 继续拍摄、renderAfterPrintoff/always/success/failure默认 always、optionstimed 的interval/capturePostRollzchange 的retractionZHopcleanTmpAfterDays默认 7、renderAfterPrintDelay默认 0 秒、defaultWebcam/snapshotWebcam默认classic。独立的 octoprint.schema.webcam 定义了通用 webcam 描述模型WebcamCompatibilitystreamTimeout、streamRatio16:9/4:3、streamWebrtcIceServers默认 Google STUN、cacheBuster、必填stream与snapshotURL、snapshotTimeout、snapshotSslValidation与Webcamname、displayName、canSnapshot、snapshotDisplay、flipH/flipV/rotate90等画面变换选项。十、scripts、system、slicing与其余配置子模块scripts.gcodescripts.pyGcodeScriptsConfig定义了打印生命周期各阶段的钩子脚本——afterPrinterConnected、beforePrinterDisconnected、beforePrintStarted、afterPrintCancelled、afterPrintDone、beforePrintPaused、afterPrintResumed、beforeToolChange、afterToolChange以及可复用的snippets内置disable_hotends与disable_bed两个 Jinja2 片段取消打印的默认脚本会调用它们来关加热、停电机、关风扇systemsystem.pySystemConfig.actions是系统菜单动作列表ActionConfig含action内部标识divider可生成分隔线、name、command、asyncYAML 中写作async模型字段为async_ alias、confirm确认提示、fresh_credentials是否要求重新验证凭据slicingslicing.pyenabled默认 true、defaultSlicer、defaultProfilesslicer 标识 → profile 标识映射apiapi.pyallowCrossOrigin默认 false与apps应用密钥映射pluginsplugins.py注意其字段在 YAML 中使用下划线别名——disabledalias_disabled已安装但被禁用的插件标识、forced_compatiblealias_forcedCompatible仅开发用、sorting_orderalias_sortingOrder钩子排序覆盖、flagsalias_flagsprinterParametersprinter_parameters.py目前仅pauseTriggers暂停触发 GCODE 列表printerProfilesprinter_profiles.pydefault默认打印机 profile 名称。十一、API 数据模型octoprint.schema.apiRST 虽未单列但octoprint.schema包还包含api/files.py与api/job.py两个 API 响应契约模块api/files.pyApiEntryAnalysis打印区域/行程包围盒、尺寸、预估时间、分工具的耗材用量filament、ApiEntryStatistics按 printer profile 的平均/末次打印时长、ApiStorageEntry/ApiStorageFolder/ApiStorageFile存储条目name、display、origin、path等、ApiAddedEntry、ApiStorageUsage、UploadResponse以及带_pre_2_0_0后缀的兼容模型api/job.pyApiJobResponsejobprogressstateerror、ApiJobInfofile、estimatedPrintTime、filament、user、ApiProgressInfo——其中printTimeLeftOrigin枚举了估算来源linear、analysis、estimate、average、mixed-analysis、mixed-average、printer可据此判断 UI 上剩余时间可信度。十二、与 Settings 子系统的集成默认配置从何而来octoprint.schema.config并非纸上谈兵——src/octoprint/settings/init.py 直接消费它from octoprint.schema.config import DEFAULT_TERMINAL_FILTERS, Config ... # FIXME This is a temporary solution to get the default settings from the pydantic model. _config Config() default_settings _config.model_dump(by_aliasTrue)源码注释明确说明默认设置现在直接由 pydantic 模型实例化后model_dump(by_aliasTrue)生成by_aliasTrue保证_disabled、async这类别名在 YAML 中按别名输出。这意味着config.yaml中所有默认值都以这些模型字段的默认值为准两者天然一致模型校验在配置加载链路中承担类型约束职责新增配置项时只需在对应 schema 子模块中声明字段默认配置与文档即同步生成。若想验证字段与 YAML 的对应关系可对照 docs/configuration/config_yaml.rst 查看完整的config.yaml参考。一个最小化的 YAML 片段示例对应上文模型字段如下server: host: 0.0.0.0 port: 5000 reverseProxy: trustedProxies: [] trustLocalhostProxies: true uploads: maxSize: 1073741824 accessControl: autologinLocal: false localNetworks: - 127.0.0.0/8 - ::1/128 feature: temperatureGraph: true sdSupport: true temperature: profiles: - name: ABS extruder: 210 bed: 100 - name: PLA extruder: 180 bed: 60 plugins: _disabled: [] webcam: webcamEnabled: true timelapse: type: off fps: 25十三、小结与深入阅读octoprint.schema是 OctoPrint 2.x 配置与数据契约的单一事实来源BaseModel/BaseModelExtra提供统一校验与序列化行为config.Config聚合全部配置子模型并直接生成默认设置api与webcam子包则约束 REST 响应与摄像头描述。后续可继续阅读docs/modules/index.rstInternal Modules 总览与 docs/modules/settings.rst设置子系统文档docs/configuration/config_yaml.rst完整配置参考各配置子模块源码server.py、access_control.py、appearance.py、controls.py、webcam.py 等配置消费端src/octoprint/settings/init.py 与配置测试 tests/settings/test_settings.py。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐Taskfile Schema 3 完整参考Task 构建工具的配置体系与字段全解析Taskfile Schema 3 完整参考Task 构建工具的配置体系与字段全解析 Taskfile 是 Task 这一跨平台构建工具的核心配置文件通常命构建工具开发工具CLISpaceX-API Dragon 数据模型全解v4 /dragons Schema 字段结构、源码实现与查询实践SpaceX API Dragon 数据模型全解v4 /dragons Schema 字段结构、源码实现与查询实践 本指南以 docs/dragons/v4/后端API设计SpaceX-API Payload 数据模型详解Payload Schema 字段结构与轨道根数存储机制SpaceX API Payload 数据模型详解Payload Schema 字段结构与轨道根数存储机制 本文档基于 SpaceX API 开源仓库中 do后端API设计上一篇从零开始Windows虚拟摇杆驱动vJoy的完整使用指南下一篇Unity Mod Manager终极指南5分钟掌握所有Unity游戏模组管理技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
