重启与健康检查

当你需要重启开发实例、确认端口归属，或证明代码变更后的后端健康时，使用本页流程。

先选对重启方式

后端有两条路径，默认选 reload：

你改了什么	用哪条	会发生什么
只改了 Python 代码	bash scripts/start.sh reload	零中断。进程收到信号后原地替换自身镜像，PID 不变、终端文件描述符保留，正在运行的编码会话不会被打断。
改了监听端口、虚拟环境或依赖；或进程已卡死	./restart.sh	硬重启。旧进程被终止、新进程以新 PID 启动，其托管的会话会断开，由启动时的自动恢复重连。

改代码时用硬重启不会出错，但会打断正在跑的编码会话——如果那台机器上有长任务，代价是重跑。

# 只改了代码（推荐）
bash scripts/start.sh reload

# 需要硬重启时
./restart.sh

./restart.sh 会加载本地环境、解析 worktree-aware 端口、启动后端，并等待健康检查响应。

硬重启前先确认该实例上没有不能中断的会话：bash scripts/status.sh 可以看到哪个 checkout 拥有哪个端口。

在无头 Linux 服务器上，Docker 和 systemd 有各自的服务管理命令。首次部署和长期运维见 无头 Linux 后端。

多 worktree

主 checkout 通常使用 8888。额外 git worktree 应使用独立端口，避免互相中断本地会话。

bash scripts/status.sh

重启或停止进程前，先确认哪个 checkout 拥有哪个本地实例。

覆盖端口

如果某个 checkout 需要固定端口，在本地环境文件中设置：

JARVIS_PORT=8890

只对当前正在运行的 checkout 使用该端口。不要让独立 worktree 复用主仓库端口。

验证健康状态

重启后调用：

curl http://127.0.0.1:8888/api/v1/health

响应应为 JSON，并包含健康状态和预期版本。

常见失败

现象	可能原因	第一动作
健康检查返回 HTML	API 路径错误	使用 /api/v1/health，不是 /health。
端口已占用	另一个本地实例拥有该端口	运行 bash scripts/status.sh，停止正确 checkout。
前端看起来过期	静态前端产物旧	重建 frontend/ 并硬刷新浏览器。
后端启动但 UI 无法认证	浏览器保存了旧 API 密钥	生成新密钥并粘贴到 UI。

相关页面

• 快速开始
• 无头 Linux 后端
• 排障
• CLI 参考