Skip to content

🐛 sctl serve 启动失败不再 panic,daemon 在跑却连不上时说清原因 - #21

Merged
CodFrm merged 5 commits into
mainfrom
fix/serve-address-in-use
Nov 13, 2026
Merged

CodFrm merged 5 commits into
mainfrom
fix/serve-address-in-use

Conversation

@CodFrm

@CodFrm CodFrm commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Fixes #20

背景

#20:装了 sctl service 后再手动执行 sctl serve,第二个实例绑定 127.0.0.1:8643 失败,用户看到的是一屏 goroutine 栈,退出码 2。

原因与平台无关:serve 启动时会失败的步骤都放在 cago 组件的 StartCancel 里,而 cago 的 RegistryCancel 把组件启动失败直接 panic,serve 的 RunE 接不到这个错误。顺着排查,同一根因还会在登记表文件损坏、数据目录写不进时触发。另外还有一类同样让人困惑的报错:daemon 明明在跑,客户端却说它没在运行或"还没就绪"。

改动

1. serve 启动失败不再 panic

  • internal/cli/serve.go:先用 control.Address() 解析地址并绑定,再调用新的 daemon.New 准备 daemon,最后才交给 cago。失败时返回退出码 3,原因同时写进日志文件(服务托管时 stderr 没人看);daemon.New 失败时会放开已绑定的地址。
  • internal/daemon/component.go:读登记表、写控制令牌这几步从 StartCancel 挪到 daemon.New(ctx, version, ln),报错带上文件路径;StartCancel 只剩组装 mux 和起 server,不再有失败路径。默认地址只剩 control.Address() 一处,与 service install 固化进服务定义的是同一个来源。抢端口失败的进程也不再先读登记表、补删 pairing.key。
情况 原来 现在(退出码都是 3)
另一个 sctl daemon(如服务起的那个)占着地址 panic: start component error: … bind: …,退出码 2 error: an sctl daemon is already running at 127.0.0.1:8643, so there is nothing to start; sctl statusshows it, andsctl service status tells whether it is the background service
别的程序占着地址,或没有权限 同上 error: cannot listen on 127.0.0.1:8643 (pick another address with --listen-address, or stop the program holding it): listen tcp …
browsers.json / scriptcats.json 损坏 panic: … parse browser registry: … error: cannot start the daemon: <路径>/browsers.json: parse browser registry: …
控制令牌写不进数据目录 panic: … replace target file: … error: cannot start the daemon: write the control token <路径>/control.token: …

退出码保持非零:launchd(SuccessfulExit=false)与 systemd(Restart=on-failure)会继续重试,挡路的前台 daemon 退出或坏文件修好后,服务能自己接上。

2. daemon 在跑却连不上时说清原因

健康检查通过、但本进程的数据目录里读不到控制令牌,几乎总是因为 CLI 与 daemon 用的数据目录不同(--data-dir / SCTL_DATA_DIR)。用户被告知"没在运行"后会再起一个 serve,然后就撞上 #20。

  • internal/client/control/client.go:
    • 读不到令牌时,报 a daemon is running at <地址>, but its control token cannot be read (<原因>); it was probably started with a different --data-dir or SCTL_DATA_DIR,代替原来的 read control token (daemon not ready?)。daemon 先写令牌、再开始回答健康检查,所以"还没就绪"这个猜测从不成立。
    • 令牌被拒(401)时,同样指出令牌文件和数据目录。
  • internal/cli/status.go:只有确实连不上(ErrDaemonUnreachable)时才输出 daemon is not running,退出码 0 不变;其余连接错误退出码 3 并报出原因。-o json 不再输出一份看起来像"没在运行"的空状态。

2b. 端口上有程序在监听却不像 sctl daemon 时,说清楚

#20 的原报告者最后查明,是 Windows 上的 AdGuard 截下了本机连接:端口明明在监听,status 却说 daemon is not running,connect 报 cannot connect to the sctl daemon;卡住的进程又占着端口,后面再起 serve 就报端口被占。

  • internal/client/control/client.go:新增 Probe。健康检查没通过时,再直接连一次地址:

    • 连不上:daemon 是真的没在运行,仍然返回 ErrDaemonUnreachable。
    • 连得上却不回答(被重置、超时、回应不是健康检查的 200):返回包装了 ErrNotSctlDaemon 的错误,内容是 something is listening at <地址> but does not answer as an sctl daemon (<原因>); another program may hold this address, or a proxy or security software may be intercepting local connections: let sctl bypass it, or pick another address with --listen-address。

    判断只看连不连得上,不比对系统错误码,因为 Windows 上拒绝连接的错误码与 syscall.ECONNREFUSED 对不上。Dial 改用它,所以 status、connect 等所有命令都会给出这个说明,退出码 3;Healthy 仍只回答是或否,service 的几处调用不变。另外删去了没有调用方的 Client.Health。

  • internal/cli/serve.go:绑定失败时用同一个判断。占着地址的程序不回答时,报 cannot listen on <地址>: something is listening at …。

3. 入口校验 --listen-address

  • internal/cli/cli.go:--listen-address 在根命令入口校验为 host:port,端口 1–65535(端口 0 会让 serve 随机绑定,客户端无从得知)。原来格式不对时,serve 报的是绑定失败、还提示"换个地址",客户端命令则一律说 daemon 没在运行;现在所有命令都直接报 invalid --listen-address "nonsense": want host:port such as 127.0.0.1:8643 (…)。

4. golangci-lint 排除 e2e/scratch/

docs/verification.md 规定一次性验证脚本放在不进版本库的 e2e/scratch/ 下,但 .golangci.yaml 没有排除这个目录,本地留着的脚本会让 AGENTS.md 要求的提交前命令 golangci-lint run ./... 失败(本机之前留下的 3 个脚本报了 5 个问题),而 CI 上看不到它们。.golangci.yaml 现在把这个目录排除在 linters 和 formatters 之外,docs/development.md 也写明了。已确认:受版本控制的代码照样会被检查,golangci-lint fmt ./... 也不会去改 scratch 下的文件。

测试与文档

  • 新增测试(改前都失败):TestDialSomethingElseListening(client_test.go),TestStatusSomethingElseListening(status_test.go),TestServeAddressInUse 补了一条断言;TestServeAddressInUse、TestServeStartupFailures(internal/cli/serve_test.go),TestStatusDaemonRunningWithoutToken、TestListenAddressValidation(internal/cli/status_test.go),TestDialDaemonRunningWithoutToken、TestUnauthorizedPointsAtDataDir(internal/client/control/client_test.go)。另保留一条正常情况的断言:daemon 确实没在运行时,status 仍报 daemon is not running,退出码 0。
  • docs/mcp.md 的排错表新增一行(AdGuard 等安全软件拦截本地连接时怎么处理);docs/cli.md 的 status 说明,以及 skills/sctl/SKILL.md 的排错条目(agent 遇到这条报错时,应该换数据目录,不要再起一个 daemon)已同步。

验证

  • go build、go vet 通过,go test ./... -race 全部通过,golangci-lint run ./cmd/... ./internal/... 0 issues。

  • 改前的根因单独确认过:在 origin/main 上用一个不重定向输出的一次性测试,serve 绑定失败时不返回错误,而是 panic: start component error: …。

  • 三个平台上用编译出的二进制逐项实测(隔离端口和数据目录):sctl 占着端口、browsers.json 损坏、令牌写不进、daemon 在跑但数据目录不同(缺令牌 / 旧令牌,status、status -o json、connect)、--listen-address 格式不对(nonsense、127.0.0.1:0,serve 与 status)、正常启动与退出、daemon 确实没在运行。全部得到上面表格与说明里的输出,退出码符合预期。

    • macOS 本机。
    • Windows 11 实机,issue 原场景:机器上已装着 sctl service(Task Scheduler \sctl,0.3.0,占着 8643)。服务不重装,只做只读操作:手动 serve 8643,修复前与 issue 输出一致的 panic、退出码 2,修复后报 already running、退出码 3;用另一个数据目录 status,报 a daemon is running at 127.0.0.1:8643, but its control token cannot be read …(修复前这里会说 daemon is not running)。全程原有服务的 control.token 没变,sctl status / sctl service status 正常。
      • 另在 Edge 开着、sctl Browser 与 ScriptCat 都连在这个服务上时复测:手动 serve 报 already running,在线的浏览器实例前后一致,daemon 日志里没有断开或重新握手的记录;新版 CLI 对接 0.3.0 daemon 时,status 与 tabs list 正常。
    • Linux(Debian 12,systemd 用户服务)完整服务流程:
      • service install 之后再手动 serve:报 already running。
      • 另一个数据目录的 status:报数据目录不对。
      • 前台 serve 占着端口时启动服务:服务以退出码 3 失败,每 5 秒重试,前台退出后自动接上。
      • browsers.json 损坏时重启服务:以退出码 3 失败并在日志里写明文件,删掉坏文件后约 3 秒恢复 active/running。
      • 结束后卸载,没有残留。
  • 第 2b 点在 macOS 与 Windows 11(156)上,用修复前后两个二进制对比实测了四种情况:连上就断、接受连接却一直不回答、回 HTTP 502、端口上没有程序。修复前前三种都报 daemon is not running(connect 报 cannot connect);修复后都报 something is listening at … but does not answer as an sctl daemon (…),退出码 3,括号里分别是 EOF 或 wsarecv: …forcibly closed、context deadline exceeded、502 Bad Gateway。serve 撞上一直不回答的程序时,报 cannot listen on …: something is listening at …。端口上没有程序时,仍报 daemon is not running、退出码 0,各测 3 到 5 次耗时都约 0.1 秒,没有变慢。156 上的真实服务(0.3.0,扩展在线)照常,第二个 serve 仍报 already running。

没改的

  • issue 原帖里「端口被 sctl.exe 占着,但 sctl connect 报 cannot connect to the sctl daemon」,报告者已经查明是 AdGuard 截下了本机连接,属于环境问题,sctl 这边改成了第 2b 点那样的说明。把 sctl 加进 AdGuard 的例外,要由用户自己去做,docs/mcp.md 的排错表里写了。
  • 两个 serve 几乎同时启动时,输的那个可能赶在赢家开始服务之前做健康检查,于是报 cannot listen on … 而不是 already running。退出码相同,只是措辞不同。
  • 占着端口的程序如果接受连接却不回应 HTTP,健康检查要等满 2 秒超时,那条报错会晚 2 秒出来。
  • issue 建议的第 2 点已由现有逻辑覆盖:服务未安装但已有 daemon 在跑时,service install 直接拒绝;已安装时先结束旧实例再重新启动。

绑定监听地址从 cago 组件的 StartCancel 挪到 serve 的 RunE:cago 把组件启动失败当 panic,
装了 sctl service 后再手动 sctl serve 只会看到一屏 goroutine 栈。现在绑定失败用健康检查区分:
另一个 sctl daemon 占着时说明它已在运行并指向 sctl status / sctl service status;
别的程序占着时给出原始错误并提示 --listen-address。两种情况退出码 3,原因同时写进日志文件。
- serve 启动失败不再 panic:读登记表、写控制令牌这几步从 cago 组件的 StartCancel 挪到
  daemon.New,在启动 cago 之前做。browsers.json / scriptcats.json 损坏、令牌写不进数据目录时
  报出是哪个文件,退出码 3,并放开已绑定的地址;原因同时写进日志文件。
- 健康检查通过但读不到控制令牌时,不再说 daemon 没在运行或"还没就绪":报 daemon 正在该地址
  运行、令牌文件读不到,多半是 --data-dir / SCTL_DATA_DIR 与 daemon 的不同。sctl status 只在
  确实连不上时才说 daemon is not running(退出码 0),其余连接错误退出码 3;令牌被拒(401)时
  同样指出令牌文件与数据目录。
- --listen-address 在入口校验为 host:port(端口 1–65535),格式不对时所有命令都直接拒绝,
  不再让 serve 报绑定失败、让客户端命令报 daemon 没在运行。
- docs/cli.md 的 status 说明与 sctl skill 的排错条目同步。
@CodFrm CodFrm changed the title 🐛 sctl serve 端口被占时不再 panic:说明是已在运行的 sctl daemon 还是别的程序占着 🐛 sctl serve 启动失败不再 panic,daemon 在跑却连不上时说清原因 Nov 13, 2026
#20 的报告者最后查明是 Windows 上的 AdGuard 截下了本机连接:端口明明在监听,status 却说
daemon is not running,connect 说连不上。健康检查没通过时再直接连一次地址:连不上才是没在运行;
连得上却不回答(被重置、超时、回应不是健康检查的 200),报地址上有程序在监听但不像 sctl daemon,
可能是别的程序占着地址,或本机的代理、安全软件截下了本地连接,退出码 3。serve 绑定失败时用同一个
判断说明占着地址的是什么。只看连不连得上,不比对系统错误码(Windows 的拒绝连接错误码与
syscall.ECONNREFUSED 对不上)。

删去没有调用方的 Client.Health;docs/mcp.md 排错表、docs/cli.md 的 status 说明与 sctl skill 同步。
@CodFrm
CodFrm merged commit 832530a into main Nov 13, 2026
4 checks passed
@CodFrm
CodFrm deleted the fix/serve-address-in-use branch November 13, 2026 08:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Windows11 x64下无法启动服务,报端口占用实际是自己占用,尝试0.3.0和0.4.0均如此,更低版本未试。

1 participant