From 2469c7452dc9c6dc4ee7cf78f0e8eba662b96885 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= Date: Thu, 12 Nov 2026 16:00:53 +0800 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=90=9B=20sctl=20serve=20=E7=AB=AF?= =?UTF-8?q?=E5=8F=A3=E8=A2=AB=E5=8D=A0=E6=97=B6=E4=B8=8D=E5=86=8D=20panic?= =?UTF-8?q?=EF=BC=9A=E8=AF=B4=E6=98=8E=E6=98=AF=E5=B7=B2=E5=9C=A8=E8=BF=90?= =?UTF-8?q?=E8=A1=8C=E7=9A=84=20sctl=20daemon=20=E8=BF=98=E6=98=AF?= =?UTF-8?q?=E5=88=AB=E7=9A=84=E7=A8=8B=E5=BA=8F=E5=8D=A0=E7=9D=80=20(#20)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 绑定监听地址从 cago 组件的 StartCancel 挪到 serve 的 RunE:cago 把组件启动失败当 panic, 装了 sctl service 后再手动 sctl serve 只会看到一屏 goroutine 栈。现在绑定失败用健康检查区分: 另一个 sctl daemon 占着时说明它已在运行并指向 sctl status / sctl service status; 别的程序占着时给出原始错误并提示 --listen-address。两种情况退出码 3,原因同时写进日志文件。 --- internal/cli/serve.go | 28 +++++++++++++++++- internal/cli/serve_test.go | 55 ++++++++++++++++++++++++++++++++++++ internal/daemon/component.go | 26 ++++------------- 3 files changed, 88 insertions(+), 21 deletions(-) create mode 100644 internal/cli/serve_test.go diff --git a/internal/cli/serve.go b/internal/cli/serve.go index d694b07..2c9c207 100644 --- a/internal/cli/serve.go +++ b/internal/cli/serve.go @@ -2,6 +2,8 @@ package cli import ( "context" + "fmt" + "net" "github.com/cago-frame/cago" "github.com/cago-frame/cago/configs" @@ -10,6 +12,7 @@ import ( "github.com/spf13/cobra" "go.uber.org/zap" + "github.com/scriptscat/sctl/internal/client/control" "github.com/scriptscat/sctl/internal/daemon" ) @@ -35,8 +38,19 @@ func newServeCmd() *cobra.Command { return err } logger.Ctx(ctx).Info("starting sctl serve", zap.String("version", Version)) + address, err := control.Address() + if err != nil { + return err + } + // 在 cago 启动组件之前绑定:组件启动失败在 cago 里是 panic,用户只会看到一屏 goroutine 栈。 + ln, err := net.Listen("tcp", address) + if err != nil { + // 服务管理器托管时 stderr 没人看,原因要落进日志文件。 + logger.Ctx(ctx).Error("failed to bind the listen address", zap.String("address", address), zap.Error(err)) + return listenError(ctx, address, err) + } return cago.New(ctx, cfg). - RegistryCancel(daemon.Component(Version, listenAddress)). + RegistryCancel(daemon.Component(Version, ln)). Start() }, } @@ -46,6 +60,18 @@ func newServeCmd() *cobra.Command { return cmd } +// listenError 说明 serve 为什么绑定不了地址。能回答健康检查的是另一个 sctl daemon——装了 sctl service 后 +// 它多半就是服务起的那个,用户要的 daemon 其实已经在跑了。 +func listenError(ctx context.Context, address string, err error) error { + if control.Healthy(ctx) { + return &ExitError{Code: exitError, Message: fmt.Sprintf( + "an sctl daemon is already running at %s, so there is nothing to start; `sctl status` shows it, and `sctl service status` tells whether it is the background service", + address)} + } + return &ExitError{Code: exitError, Message: fmt.Sprintf( + "%v; free that address or pick another with --listen-address", err)} +} + // emptyConfigSource 是一个「无任何键」的 cago 配置源:所有 Scan 保持零值并返回 nil, // sctl 的公开配置全部来自 CLI 参数,这里只为 cago 生命周期提供空配置源。 type emptyConfigSource struct{} diff --git a/internal/cli/serve_test.go b/internal/cli/serve_test.go new file mode 100644 index 0000000..1a1cd1e --- /dev/null +++ b/internal/cli/serve_test.go @@ -0,0 +1,55 @@ +package cli + +import ( + "net" + "os" + "strings" + "testing" + + . "github.com/smartystreets/goconvey/convey" + + "github.com/scriptscat/sctl/internal/client/control" +) + +func TestServeAddressInUse(t *testing.T) { + Convey("sctl serve 绑定不了监听地址", t, func() { + Convey("占着地址的是另一个 sctl daemon(比如 sctl service 起的那个)时,退出码 3,说明已在运行并指向 status / service", func() { + stubDaemon(t, control.CallResult{}) + address := os.Getenv("SCTL_BRIDGE_ADDR") + + code, _, errOut, err := runCLIResult(strings.NewReader(""), "serve") + + So(code, ShouldEqual, exitError) + So(errOut, ShouldNotContainSubstring, "panic") + So(err.Error(), ShouldContainSubstring, "already running at "+address) + So(err.Error(), ShouldContainSubstring, "sctl status") + So(err.Error(), ShouldContainSubstring, "sctl service status") + }) + + Convey("占着地址的不是 sctl 时,退出码 3,给出地址与原始错误,并提示换 --listen-address", func() { + ln, err := net.Listen("tcp", "127.0.0.1:0") + So(err, ShouldBeNil) + t.Cleanup(func() { _ = ln.Close() }) + // 不说 HTTP 的程序:连上就断,健康检查立刻失败而不是等到超时。 + go func() { + for { + conn, err := ln.Accept() + if err != nil { + return + } + _ = conn.Close() + } + }() + t.Setenv("SCTL_BRIDGE_ADDR", ln.Addr().String()) + t.Setenv("SCTL_DATA_DIR", t.TempDir()) + + code, _, errOut, err := runCLIResult(strings.NewReader(""), "serve") + + So(code, ShouldEqual, exitError) + So(errOut, ShouldNotContainSubstring, "panic") + So(err.Error(), ShouldNotContainSubstring, "already running") + So(err.Error(), ShouldContainSubstring, ln.Addr().String()) + So(err.Error(), ShouldContainSubstring, "--listen-address") + }) + }) +} diff --git a/internal/daemon/component.go b/internal/daemon/component.go index 3cb0144..b3d0116 100644 --- a/internal/daemon/component.go +++ b/internal/daemon/component.go @@ -7,7 +7,6 @@ package daemon import ( "context" - "fmt" "net" "net/http" @@ -26,19 +25,19 @@ import ( "github.com/scriptscat/sctl/internal/pkg/protocol" ) -// daemonComponent 实现 cago 的 ComponentCancel:Start 拉起 WS server, +// daemonComponent 实现 cago 的 ComponentCancel:Start 在已绑定的 listener 上拉起 WS server, // server 意外退出时通过 cancel 终止整个应用。 type daemonComponent struct { version string - address string srv *bridge.Server listener net.Listener } // Component 返回桥接 daemon 组件,注册到 cago 应用(用 RegistryCancel)。 -// version 注入 hello 消息的 daemonVersion。 -func Component(version, address string) *daemonComponent { - return &daemonComponent{version: version, address: address} +// version 注入 hello 消息的 daemonVersion。ln 由调用方先绑定好:cago 把组件启动失败当作 panic, +// 而地址被占是用户常遇到的情况,要由 serve 在启动组件前报成能看懂的错误。 +func Component(version string, ln net.Listener) *daemonComponent { + return &daemonComponent{version: version, listener: ln} } func (b *daemonComponent) Start(ctx context.Context, cfg *configs.Config) error { @@ -51,9 +50,6 @@ func (b *daemonComponent) StartCancel(ctx context.Context, cancel context.Cancel logger.Ctx(ctx).Error("failed to load the embedded protocol", zap.Error(err)) return err } - if b.address == "" { - b.address = defaultAddress(p.Transport.DefaultPort) - } keys := store.NewKeyStore(paths.KeyFile()) browsers, err := store.LoadBrowserRegistry(paths.BrowsersFile()) if err != nil { @@ -71,13 +67,7 @@ func (b *daemonComponent) StartCancel(ctx context.Context, cancel context.Cancel logger.Ctx(ctx).Warn("failed to retire a pairing.key left over from a ScriptCat takeover", zap.Error(err)) } - // 同步 net.Listen 使绑定失败在启动阶段即暴露(cago 会 panic,符合 fail-fast 约定)。 - ln, err := net.Listen("tcp", b.address) - if err != nil { - logger.Ctx(ctx).Error("failed to bind the websocket listener", zap.String("address", b.address), zap.Error(err)) - return err - } - b.listener = ln + ln := b.listener logger.Ctx(ctx).Info("bridge daemon is listening", zap.String("address", ln.Addr().String()), zap.String("jsonrpc", p.JSONRPCVersion)) // 绑定成功后(端口竞态胜出者才走到这里)再生成并落盘控制令牌,避免失败方覆盖胜出者的令牌。 @@ -126,7 +116,3 @@ func (b *daemonComponent) StartCancel(ctx context.Context, cancel context.Cancel func (b *daemonComponent) CloseHandle() { logger.Default().Info("bridge daemon stopped") } - -func defaultAddress(port int) string { - return fmt.Sprintf("127.0.0.1:%d", port) -} From 900ad42478bd776371c28654e6459a3af6bf0b53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= Date: Thu, 12 Nov 2026 16:04:48 +0800 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=92=AC=20sctl=20serve=20=E7=BB=91?= =?UTF-8?q?=E5=AE=9A=E5=A4=B1=E8=B4=A5=E6=97=B6=E5=85=88=E7=BB=99=E6=8F=90?= =?UTF-8?q?=E7=A4=BA=E5=86=8D=E9=99=84=E5=8E=9F=E5=A7=8B=E9=94=99=E8=AF=AF?= =?UTF-8?q?=EF=BC=9AWindows=20=E7=9A=84=E7=B3=BB=E7=BB=9F=E9=94=99?= =?UTF-8?q?=E8=AF=AF=E6=96=87=E5=AD=97=E8=87=AA=E5=B8=A6=E5=8F=A5=E5=8F=B7?= =?UTF-8?q?=EF=BC=8C=E6=8E=A5=E5=9C=A8=E5=90=8E=E9=9D=A2=E8=AF=BB=E8=B5=B7?= =?UTF-8?q?=E6=9D=A5=E6=98=AF=E6=96=AD=E7=9A=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- internal/cli/serve.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/internal/cli/serve.go b/internal/cli/serve.go index 2c9c207..01afddf 100644 --- a/internal/cli/serve.go +++ b/internal/cli/serve.go @@ -68,8 +68,9 @@ func listenError(ctx context.Context, address string, err error) error { "an sctl daemon is already running at %s, so there is nothing to start; `sctl status` shows it, and `sctl service status` tells whether it is the background service", address)} } + // 原始错误放最后:Windows 的系统错误文字自带句号结尾,后面再接提示读起来是断的。 return &ExitError{Code: exitError, Message: fmt.Sprintf( - "%v; free that address or pick another with --listen-address", err)} + "cannot listen on %s (free it or pick another address with --listen-address): %v", address, err)} } // emptyConfigSource 是一个「无任何键」的 cago 配置源:所有 Scan 保持零值并返回 nil, From f7a8aa8086aa2c8ec8dfabbdb9dcbe5ed087a079 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= Date: Fri, 13 Nov 2026 11:08:02 +0800 Subject: [PATCH 3/5] =?UTF-8?q?=F0=9F=90=9B=20serve=20=E5=85=B6=E4=BD=99?= =?UTF-8?q?=E5=90=AF=E5=8A=A8=E5=A4=B1=E8=B4=A5=E4=B8=8D=E5=86=8D=20panic?= =?UTF-8?q?=EF=BC=8Cdaemon=20=E5=9C=A8=E8=B7=91=E5=8D=B4=E8=AF=BB=E4=B8=8D?= =?UTF-8?q?=E5=88=B0=E4=BB=A4=E7=89=8C=E6=97=B6=E8=AF=B4=E6=B8=85=E6=98=AF?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E7=9B=AE=E5=BD=95=E4=B8=8D=E5=AF=B9=EF=BC=8C?= =?UTF-8?q?=E5=85=A5=E5=8F=A3=E6=A0=A1=E9=AA=8C=20--listen-address?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 的排错条目同步。 --- docs/cli.md | 2 +- internal/cli/cli.go | 26 +++++++++++ internal/cli/serve.go | 12 ++++- internal/cli/serve_test.go | 57 ++++++++++++++++++++++++ internal/cli/status.go | 7 ++- internal/cli/status_test.go | 61 ++++++++++++++++++++++++++ internal/client/control/client.go | 14 ++++-- internal/client/control/client_test.go | 48 ++++++++++++++++++++ internal/client/control/token.go | 2 +- internal/daemon/component.go | 52 ++++++++++------------ skills/sctl/SKILL.md | 3 ++ 11 files changed, 247 insertions(+), 37 deletions(-) create mode 100644 internal/cli/status_test.go diff --git a/docs/cli.md b/docs/cli.md index 128bbc4..a73dff3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -15,7 +15,7 @@ command line can use the skill in [`../skills/sctl/`](../skills/sctl/SKILL.md). | `sctl service install\|uninstall\|start\|stop\|restart\|enable\|disable\|status` | Run `sctl serve` in the background as a user service; see [Background service](#background-service-sctl-service). | | `sctl connect` | Open a one-time enrollment window for ScriptCat or sctl Browser. | | `sctl mcp [--name