局域网远端部署 SOP

适用：经局域网 SSH / 远控在 Windows 机器上部署并让服务长期存活，尤其包含浏览器/扩展/GUI 依赖链路。

已验证关键前置

• 若服务经 SSH 前台启动后“短暂可用又消失”，优先怀疑 SSH 会话结束回收子进程；不要先怀疑代码崩溃。
• 后台化优先顺序：
  1. 复用目标机上已验证可工作的计划任务
  2. 其次新建计划任务/本机脚本
  3. 最后才尝试普通 Start-Process
• GUI/浏览器/扩展相关任务，优先保持在 已验证成功的交互用户会话 中运行；不要想当然切到 SYSTEM。

稳定承载原则

• 远端 PowerShell 中调用计划任务时，schtasks 若报“找不到文件”，优先改用绝对路径：
  • C:\Windows\System32\schtasks.exe
• 本地 → SSH → PowerShell 多层链路下，避免直接拼复杂 /TR；更稳做法：
  • 先把启动逻辑落到远端 .cmd / .ps1
  • 再由计划任务调用该脚本
• 某些依赖用户 profile / 浏览器 profile / 扩展态的任务，即使前台可跑，换成其他用户或 SYSTEM 后会秒失败；应优先复用 与前台验证一致的用户身份。

浏览器/扩展类特殊规则

• 若目标链路依赖浏览器扩展、tab 会话、用户登录态，优先：
  • 找现成的浏览器启动任务
  • 找现成的服务启动任务
  • 按原有组合重新拉起
• 仅看到进程存在不算成功；至少同时验证以下之一：
  • 目标监听端口存在
  • 运行日志出现 tab / bridge 接入
  • 本地健康接口返回 OK
• 若源码显示主服务端口旁还有 port+1 配套监听，需先读源码确认用途，不要把伴随端口误判为异常残留。

排障顺序

1. 先查监听
   • 看目标端口是否真的 LISTENING
2. 再查 PID 归属
   • 把端口映射到具体 PID 和命令行
3. 再查日志
   • 看是启动失败、权限问题、还是会话链路未接入
4. 最后才重启/重跑
   • 没有新信息时不要重复触发同一命令

常见真因（已验证）

• 旧用户残留进程仍在占端口，会让“新任务已运行”看似成功、实际未接管。
• 浏览器扩展实际连接的端口与服务当前监听端口不一致，会表现为服务在跑但会话没恢复。
• 服务本体健康正常时，应以 健康接口 / OpenAPI / 实际路由 为准，不要被其他无关监听端口误导。

精确清理原则

• 禁止无条件杀 python.exe。
• 先找：
  • 端口 → PID
  • PID → 命令行 / 用户归属
• 仅精确结束确认属于旧残留、且正在干扰部署目标的那个进程。

验收标准

满足以下条件才算部署完成：

• 服务由稳定承载方式启动（优先计划任务或已验证交互会话）
• 目标端口监听正常
• 若有健康接口，返回成功
• 若依赖浏览器/扩展，会话已重新接入
• 日志与监听状态一致，无“进程在但链路未通”的假成功

复盘时优先记忆的信息

只记录跨会话仍重要的内容：

• 哪类任务不能脱离交互用户
• 哪类任务必须复用现成计划任务
• 哪类失败根因来自 SSH 会话回收、端口占用、用户身份不一致

不要记录：

• 临时 PID
• 某次会话的瞬时端口占用状态
• 一次性日志片段