Repository navigation
🐛 sctl serve 启动失败不再 panic,daemon 在跑却连不上时说清原因 - #21
Merged
Merged
Conversation
绑定监听地址从 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 的排错条目同步。
#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 同步。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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启动失败不再 panicinternal/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。panic: start component error: … bind: …,退出码 2error: an sctl daemon is already running at 127.0.0.1:8643, so there is nothing to start;sctl statusshows it, andsctl service statustells whether it is the background serviceerror: 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 先写令牌、再开始回答健康检查,所以"还没就绪"这个猜测从不成立。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。健康检查没通过时,再直接连一次地址:ErrDaemonUnreachable。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-addressinternal/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 确实没在运行。全部得到上面表格与说明里的输出,退出码符合预期。sctl service(Task Scheduler\sctl,0.3.0,占着 8643)。服务不重装,只做只读操作:手动serve8643,修复前与 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正常。serve报already running,在线的浏览器实例前后一致,daemon 日志里没有断开或重新握手的记录;新版 CLI 对接 0.3.0 daemon 时,status与tabs list正常。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。没改的
sctl connect报cannot connect to the sctl daemon」,报告者已经查明是 AdGuard 截下了本机连接,属于环境问题,sctl 这边改成了第 2b 点那样的说明。把 sctl 加进 AdGuard 的例外,要由用户自己去做,docs/mcp.md的排错表里写了。serve几乎同时启动时,输的那个可能赶在赢家开始服务之前做健康检查,于是报cannot listen on …而不是already running。退出码相同,只是措辞不同。service install直接拒绝;已安装时先结束旧实例再重新启动。