网硕互联帮助中心【免费下载链接】OctoPrint
OctoPrint is the snappy web interface for your 3D printer!
项目地址：
https://gitcode.com/gh_mirrors/oc/OctoPrint
点击查看 免费下载
GET /api/server 是 OctoPrint 用于查询服务器自身运行状态的只读端点，从 1.5.0 版本开始提供。它返回一个 JSON 对象，包含服务器版本号 version 与安全模式标志 safemode，是监控、告警、自动化脚本判断"OctoPrint 当前是否健康启动"的首选入口。读完本文，你将掌握该端点的请求/响应格式、safemode 三种取值的完整含义与触发链路、以及从 CLI 与配置层面主动控制 Safe Mode 的实战方法。
一、端点概览：功能、版本与权限
GET /api/server 在 docs/api/server.rst 中被正式定义，属于 HTTP API 的只读查询端点：
- 功能：检索服务器状态信息，返回包含版本号与安全模式状态（及原因）的 JSON 对象；
- 引入版本：versionadded:: 1.5.0，即自 OctoPrint 1.5.0 起可用；
- 认证要求：端点由 Permissions.STATUS.require(403) 保护（见 src/octoprint/server/api/init.py），未授权访问将得到 403 Forbidden。这意味着调用方需要具备 API Key（X-Api-Key 请求头）并拥有对应权限；
- 成功状态码：200 OK，且响应 Content-Type: application/json。
在源码中该端点对应的处理器如下（src/octoprint/server/api/init.py）：
@api.route("/server", methods=["GET"])
@Permissions.STATUS.require(403)
def serverStatus():
return jsonify(version=octoprint.server.VERSION, safemode=octoprint.server.safe_mode)
可以看到，实际返回的数据来源于两个全局量：octoprint.server.VERSION（服务器版本）与 octoprint.server.safe_mode（安全模式状态）。与它同组的 /api/version 端点（src/octoprint/server/api/init.py）返回 server、api、text 等字段，二者用途不同：/api/version 偏重版本信息，/api/server 则额外携带了 Safe Mode 状态，这是判断服务器是否"降级启动"的关键信号。
二、请求与响应格式详解
2.1 请求示例
原文档给出的标准请求如下：
GET /api/server HTTP/1.1
Host: example.com
X-Api-Key: abcdef…
要点：
- 方法固定为 GET，路径为 /api/server；
- 必须携带 X-Api-Key 请求头（或通过已认证会话），否则返回 403；
- 无需任何查询参数或请求体。
2.2 响应示例
HTTP/1.1 200 OK
Content-Type: application/json
{
"version": "1.5.0",
"safemode": "incomplete_startup"
}
响应 JSON 仅含两个键：
| version | string | 当前运行的 OctoPrint 服务器版本号，例如 "1.5.0"；取自 octoprint.server.VERSION |
| safemode | string / boolean | Safe Mode 状态。值为 false 表示未启用安全模式；值为 settings、incomplete_startup 或 flag 时，分别表示启用安全模式的不同原因（详见下文） |
从源码看，该 JSON 由 jsonify(version=…, safemode=…) 直接构造（src/octoprint/server/api/init.py），因此字段顺序、命名与文档严格一致，客户端可直接按此契约解析。
2.3 safemode 字段的三种取值
server.rst 明确指出 safemode 的合法取值集合：
三、Safe Mode 的判定逻辑：源码级追踪
GET /api/server 中 safemode 的取值并不是临时拼凑的，而是 OctoPrint 启动流程中计算出的全局状态。下面沿着源码逐一还原三种取值的来源。
3.1 启动时汇总三类来源（src/octoprint/init.py）
OctoPrint 在初始化阶段（init_settings 之后）会做如下判定：
settings_start_once_in_safemode = (
"settings" if settings.getBoolean(["server", "startOnceInSafeMode"]) else None
)
settings_incomplete_startup_safemode = (
"incomplete_startup"
if os.path.exists(os.path.join(settings._basedir, ".incomplete_startup"))
and not settings.getBoolean(["server", "ignoreIncompleteStartup"])
else None
)
safe_mode = (
safe_mode
or settings_start_once_in_safemode
or settings_incomplete_startup_safemode
)
逻辑解读：
- settings 来源：读取配置 server.startOnceInSafeMode，若为 true 则标记为 "settings"；
- incomplete_startup 来源：检查基于目录（basedir）下是否存在 .incomplete_startup 标记文件，且配置 server.ignoreIncompleteStartup 不为 true（该配置为开发场景提供跳过机制），命中则标记为 "incomplete_startup"；
- flag 来源：来自外部传入的 safe_mode 参数（由 CLI 的 –safemode 转换而来，见下文），作为第一优先级被合并。
三者通过逻辑或合并，最终写入 kwargs["safe_mode"]，并最终传递为服务器模块的 safe_mode 全局量（src/octoprint/server/init.py），随后被 serverStatus() 读取并序列化输出。
3.2 .incomplete_startup 标记文件如何产生
服务器启动时会主动"种下"这个标记（src/octoprint/server/init.py）：
def run(self):
incomplete_startup_flag = self._get_incomplete_startup_flag()
if not self._settings.getBoolean(["server", "ignoreIncompleteStartup"]):
try:
incomplete_startup_flag.touch()
except Exception:
self._logger.exception("Could not create startup triggered safemode flag")
…
即在启动流程开始时先创建 .incomplete_startup 标记；当启动成功完成后该标记会被移除，从而形成一个"启动中 → 启动完成"的哨兵机制。若上次启动在完成前异常退出（标记未被清理），下一次启动时第 3.1 节中的 os.path.exists(…) 就会命中，进而自动进入 Safe Mode 并让 GET /api/server 返回 "safemode": "incomplete_startup"。
3.3 startOnceInSafeMode 的一次性消费
服务启动后，Safe Mode 配置会被自动复位（src/octoprint/server/init.py）：
if safe_mode and self._settings.getBoolean(["server", "startOnceInSafeMode"]):
…
self._settings.setBoolean(["server", "startOnceInSafeMode"], False)
同时配置 schema 也对这两个关键开关给出了权威注释（src/octoprint/schema/config/server.py）：
startOnceInSafeMode: bool = False
"""If this option is ``true``, OctoPrint will enable safe mode on the next server start and reset the setting to false"""
ignoreIncompleteStartup: bool = False
"""Set this to ``true`` to make OctoPrint ignore incomplete startups. Helpful for development."""
这印证了："settings" 是一次性触发（next start 生效、随后自动重置），而 "incomplete_startup" 可以被 ignoreIncompleteStartup: true 显式忽略——这是开发者日常调试时常用的豁免开关。
四、如何主动触发 Safe Mode：CLI 与配置两条路径
除了被动响应 .incomplete_startup，运维者也可以主动让 GET /api/server 返回非 false 的 safemode 值。OctoPrint 提供两条路径：
4.1 CLI 命令：octoprint safemode
在 src/octoprint/cli/server.py 中定义了专门的子命令：
octoprint safemode
其实现将配置 server.startOnceInSafeMode 置为 true 并保存：
settings.setBoolean(["server", "startOnceInSafeMode"], True)
settings.save()
click.echo("Safe mode flag set, OctoPrint will start in safe mode on next restart.")
执行后控制台会提示"Safe mode flag set, OctoPrint will start in safe mode on next restart."，即下一次启动时进入 Safe Mode，同时 GET /api/server 将返回 "safemode": "settings"。因为该配置一次性消费，启动完成后会被重置。
4.2 启动参数：–safemode 标志
octoprint serve –safemode（或 octoprint –safemode）会走另一条链路（src/octoprint/cli/server.py）：
safe_mode = "flag" if get_value("safe_mode") else None
该值作为 safe_mode 参数传入 run_server，最终合并进全局状态，使 GET /api/server 返回 "safemode": "flag"。与 "settings" 不同，"flag" 是本次进程级强制启用，不受"一次性重置"逻辑影响。
4.3 配置文件中的直接控制
若希望手工写入配置（例如 config.yaml），对应的片段为：
server:
startOnceInSafeMode: true # 下次启动进入 Safe Mode，随后自动复位
ignoreIncompleteStartup: false # 置 true 可忽略未完成启动检测（开发用）
相关 schema 定义位于 src/octoprint/schema/config/server.py。此外，系统 API 中也存在通过 POST /api/system 类接口写入该配置的路径（src/octoprint/server/api/system.py），可供自动化场景使用。
五、典型应用场景与使用建议
综合以上机制，GET /api/server 的典型应用场景包括：
六、小结
GET /api/server 虽然只返回两个字段，却精准承载了 OctoPrint 最关键的运行健康信号：版本号与 Safe Mode 状态。其 safemode 字段的三种取值 settings、incomplete_startup、flag 分别对应配置一次性触发、上次启动未完成检测、命令行强制启用三条完全不同的链路，均可从 src/octoprint/init.py、src/octoprint/cli/server.py 与 src/octoprint/schema/config/server.py 等源码中得到一一印证。理解了这些内部机制，你就能在自动化脚本、监控面板与故障排障中正确解读该端点返回的每一个值。
赞
【免费下载链接】OctoPrint
OctoPrint is the snappy web interface for your 3D printer!
项目地址：
https://gitcode.com/gh_mirrors/oc/OctoPrint
点击查看 免费下载
相关推荐
clawhub writing-evals 技能详解：用 createAppScope + Zod 设计 Axiom AI 评测的 Flag Schema
SkyWater 130nm开源PDK快速上手实践指南：从零开始构建你的芯片设计环境
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
评论前必须登录！
注册