Add graceful SCUM stop, restart, and version update flow

SCUM 停止/重启/更新以前只有“结束进程”这一条路，插件没有声明任何优雅关闭方式，平台也没有把停止后重新启动串起来。现在插件声明自己的关闭脚本，run 先执行它，平台在停止或更新成功后再自动拉起服务。 run: - lifecycle stop 支持插件声明的 gracefulStop（可执行文件、参数、环境、超时、 fallback=report|terminate）；关闭命令超时且声明 report 时任务失败，不再默默杀进程。 - 新增 steam.update 依赖探针：调用 steamcmd +app_info_print 获取公开分支 buildid，与本地 steamapps/appmanifest_<appid>.acf 的 buildid 比较，输出 installed/latest/update=yes|no|unknown。 platform: - 新增 POST /api/v1/server-instances/{id}/restart 与 /update。 - restart 派发插件 stop 动作（走优雅关闭），终态成功后入队 start 作业。 - update 派发插件 install 动作；插件在更新前必须先优雅关闭 SCUM，关闭失败直接拒绝 SteamCMD 更新，成功后平台再拉起服务。 - 依赖检查输入带上插件声明的服务器安装根目录，供 steam.update 读取 appmanifest。 plugin (SCUM server plugin 0.1.16): - bin/scum-stop.cmd：解析已声明的可执行文件路径，定位同路径正在运行的 SCUMServer.exe，通过本地 RCON 公告并发送关闭命令，等待进程自行退出；不再使用 taskkill。 - bin/scum-rcon.ps1：插件自有的 Source RCON 客户端，从 UE4SS mod config.ini 读取密码/端口，密钥不离开本机。 - actions/stop.json 声明 gracefulStop；actions/install.json 更新前先执行同一关闭脚本。 platform_web: - 服务器详情新增“重启”按钮和“SCUM 版本更新”面板；点“检查更新”查询公开分支版本，只有检测到更新时“更新版本”按钮才会置为可用并高亮，点击后先确认再派发更新任务。
2026-09-15 13:30:15 +08:00
parent 4ea27bda6a
commit 05f5a97ba9
39 changed files with 1197 additions and 56 deletions
@@ -534,3 +534,214 @@ func claimAndCompleteLifecycleJobForServer(t *testing.T, svc *CoreService, sessi
 		t.Fatalf("complete lifecycle job %s: %v", capability, err)
 	}
 }
+
+func TestCoreServiceRestartLifecycleQueuesDeclaredStopThenStart(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "lifecycle-operator", DisplayName: "Lifecycle Operator", Email: "lifecycle-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-restart")
+
+	restarted, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{
+		ServerInstanceID:      instance.ID,
+		ExpectedConfigVersion: instance.ConfigVersion,
+		IdempotencyKey:        "idem-restart",
+	})
+	if err != nil {
+		t.Fatalf("restart lifecycle workflow: %v", err)
+	}
+	if restarted.Action != domain.ServerLifecycleActionRestart || restarted.Job.Capability != domain.LifecycleCapabilityStop || restarted.Job.TargetKey != "actions/stop.json" {
+		t.Fatalf("expected restart to queue the plugin-declared stop action, got %+v", restarted)
+	}
+	if restarted.Job.ExecutionInput.LifecycleOperation != string(domain.ServerLifecycleActionRestart) {
+		t.Fatalf("expected restart intent on the queued job, got %+v", restarted.Job.ExecutionInput)
+	}
+	if _, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart); ok {
+		t.Fatal("restart must not queue a start job before the declared stop result lands")
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStop, domain.JobStateSucceeded)
+	stopped, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get stopped instance: %v", err)
+	}
+	if stopped.State != domain.ServerInstanceStateStopped {
+		t.Fatalf("expected graceful stop result to project stopped, got %+v", stopped)
+	}
+
+	startJob, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart)
+	if !ok {
+		t.Fatal("expected a follow-up start job after the graceful stop succeeded")
+	}
+	if startJob.TargetKey != "actions/start.json" || startJob.ExecutionInput.LifecycleOperation != string(domain.ServerLifecycleActionStart) || startJob.IdempotencyKey != "idem-restart:start" {
+		t.Fatalf("unexpected follow-up start job: %+v", startJob)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStart, domain.JobStateSucceeded)
+	running, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get restarted instance: %v", err)
+	}
+	if running.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected restart to return the server to running, got %+v", running)
+	}
+}
+
+func TestCoreServiceUpdateLifecycleQueuesInstallThenStart(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "update-operator", DisplayName: "Update Operator", Email: "update-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-update")
+
+	updated, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{
+		ServerInstanceID:      instance.ID,
+		ExpectedConfigVersion: instance.ConfigVersion,
+		IdempotencyKey:        "idem-update",
+	})
+	if err != nil {
+		t.Fatalf("update lifecycle workflow: %v", err)
+	}
+	if updated.Action != domain.ServerLifecycleActionUpdate || updated.Job.Capability != domain.LifecycleCapabilityInstall || updated.Job.TargetKey != "actions/install.json" {
+		t.Fatalf("expected update to queue the plugin-declared install action, got %+v", updated)
+	}
+	if updated.Job.ExecutionInput.LifecycleOperation != string(domain.ServerLifecycleActionUpdate) {
+		t.Fatalf("expected update intent on the queued job, got %+v", updated.Job.ExecutionInput)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityInstall, domain.JobStateSucceeded)
+	startJob, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart)
+	if !ok {
+		t.Fatal("expected a follow-up start job after the game update succeeded")
+	}
+	if startJob.IdempotencyKey != "idem-update:start" {
+		t.Fatalf("unexpected follow-up start job: %+v", startJob)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStart, domain.JobStateSucceeded)
+	running, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get updated instance: %v", err)
+	}
+	if running.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected update to start the server again, got %+v", running)
+	}
+}
+
+func TestCoreServiceRestartAndUpdateRespectLifecycleState(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "state-operator", DisplayName: "State Operator", Email: "state-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	if _, err := svc.CreateServerInstanceWorkflow(domain.ServerLifecycleCreate{ID: "server-installing", PluginID: "server.scum", RunEndpointID: "run-local", Name: "SCUM installing", IdempotencyKey: "installing-create", ProfileKey: "local"}); err != nil {
+		t.Fatalf("create installing instance: %v", err)
+	}
+	installing, err := svc.GetServerInstance("server-installing")
+	if err != nil {
+		t.Fatalf("get installing instance: %v", err)
+	}
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: installing.ID, ExpectedConfigVersion: installing.ConfigVersion, IdempotencyKey: "idem-restart-installing"}); err == nil || !strings.Contains(err.Error(), "cannot restart") {
+		t.Fatalf("expected restart state rejection, got %v", err)
+	}
+	if _, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: installing.ID, ExpectedConfigVersion: installing.ConfigVersion, IdempotencyKey: "idem-update-installing"}); err == nil || !strings.Contains(err.Error(), "cannot update") {
+		t.Fatalf("expected update state rejection, got %v", err)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, installing.ID, domain.LifecycleCapabilityInstall, domain.JobStateSucceeded)
+	ready, err := svc.GetServerInstance(installing.ID)
+	if err != nil {
+		t.Fatalf("get ready instance: %v", err)
+	}
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: ready.ID, ExpectedConfigVersion: ready.ConfigVersion, IdempotencyKey: "idem-restart-ready"}); err == nil || !strings.Contains(err.Error(), "cannot restart") {
+		t.Fatalf("expected ready state restart rejection, got %v", err)
+	}
+	if _, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: ready.ID, ExpectedConfigVersion: ready.ConfigVersion, IdempotencyKey: "idem-update-ready"}); err != nil {
+		t.Fatalf("ready server should accept a game update dispatch: %v", err)
+	}
+}
+
+func TestCoreServiceFailedGracefulStopDoesNotStartServer(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "failure-operator", DisplayName: "Failure Operator", Email: "failure-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-restart-failure")
+
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: instance.ID, ExpectedConfigVersion: instance.ConfigVersion, IdempotencyKey: "idem-restart-failure"}); err != nil {
+		t.Fatalf("restart lifecycle workflow: %v", err)
+	}
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStop, domain.JobStateFailed)
+	if _, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart); ok {
+		t.Fatal("a failed graceful stop must not queue a start job")
+	}
+	failed, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get failed instance: %v", err)
+	}
+	if failed.State != domain.ServerInstanceStateFailed {
+		t.Fatalf("expected failed stop to project failed, got %+v", failed)
+	}
+}
+
+func TestCoreServiceRestartAndUpdateRequireEndpointCapabilities(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "capability-operator", DisplayName: "Capability Operator", Email: "capability-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-capability")
+
+	endpoint, err := svc.store.RunEndpoints().Get("run-local")
+	if err != nil {
+		t.Fatalf("get lifecycle endpoint: %v", err)
+	}
+	remaining := make([]string, 0, len(endpoint.Capabilities))
+	for _, capability := range endpoint.Capabilities {
+		if capability != domain.LifecycleCapabilityStop && capability != domain.LifecycleCapabilityInstall {
+			remaining = append(remaining, capability)
+		}
+	}
+	endpoint.Capabilities = remaining
+	if err := svc.store.RunEndpoints().Update(endpoint); err != nil {
+		t.Fatalf("remove lifecycle capabilities: %v", err)
+	}
+
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: instance.ID, ExpectedConfigVersion: instance.ConfigVersion, IdempotencyKey: "idem-restart-capability"}); err == nil || !strings.Contains(err.Error(), domain.LifecycleCapabilityStop) {
+		t.Fatalf("expected missing stop capability rejection, got %v", err)
+	}
+	if _, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: instance.ID, ExpectedConfigVersion: instance.ConfigVersion, IdempotencyKey: "idem-update-capability"}); err == nil || !strings.Contains(err.Error(), domain.LifecycleCapabilityInstall) {
+		t.Fatalf("expected missing install capability rejection, got %v", err)
+	}
+}
+
+func runningLifecycleInstanceForTest(t *testing.T, svc *CoreService, runSession string, id string) domain.ServerInstance {
+	t.Helper()
+	if _, err := svc.CreateServerInstanceWorkflow(domain.ServerLifecycleCreate{ID: id, PluginID: "server.scum", RunEndpointID: "run-local", Name: "SCUM " + id, IdempotencyKey: id + "-create", ProfileKey: "local"}); err != nil {
+		t.Fatalf("create lifecycle workflow: %v", err)
+	}
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, id, domain.LifecycleCapabilityInstall, domain.JobStateSucceeded)
+	ready, err := svc.GetServerInstance(id)
+	if err != nil {
+		t.Fatalf("get ready instance: %v", err)
+	}
+	if _, err := svc.StartServerInstance(domain.ServerLifecycleCommand{ServerInstanceID: id, ExpectedConfigVersion: ready.ConfigVersion, IdempotencyKey: id + "-start"}); err != nil {
+		t.Fatalf("start lifecycle workflow: %v", err)
+	}
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, id, domain.LifecycleCapabilityStart, domain.JobStateSucceeded)
+	running, err := svc.GetServerInstance(id)
+	if err != nil {
+		t.Fatalf("get running instance: %v", err)
+	}
+	if running.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected running instance, got %+v", running)
+	}
+	return running
+}
+
+func queuedLifecycleJob(t *testing.T, svc *CoreService, serverInstanceID string, capability string) (domain.Job, bool) {
+	t.Helper()
+	jobs, err := svc.store.Jobs().List(domain.JobFilter{ServerInstanceID: serverInstanceID, State: domain.JobStateQueued})
+	if err != nil {
+		t.Fatalf("list jobs: %v", err)
+	}
+	for _, job := range jobs {
+		if job.Capability == capability {
+			return job, true
+		}
+	}
+	return domain.Job{}, false
+}