debug

domain-api/app/services/worker_control_service.py

@@ -51,6 +51,28 @@ def _run_systemctl(
     return _run_shell(["sudo", "-n", *systemctl_command], timeout=timeout)
 
 
+def normalize_systemctl_error(raw_message: str, *, service_name: str = "") -> str:
+    message = str(raw_message or "").strip()
+    normalized_service_name = str(service_name or "").strip()
+    if not message:
+        target = normalized_service_name or "目标服务"
+        return f"{target} 控制失败，未返回可用错误信息"
+
+    lowered = message.lower()
+    if "sudo: a password is required" in lowered or "authentication is required" in lowered:
+        target = normalized_service_name or "systemd 服务"
+        return f"{target} 控制失败：当前运行用户没有免密 systemctl 权限，请为 API 进程授予对应 sudo/systemd 权限"
+    if "unit " in lowered and " could not be found" in lowered:
+        target = normalized_service_name or "目标服务"
+        return f"{target} 控制失败：systemd 中未找到该服务，请检查服务名配置是否正确"
+    if "access denied" in lowered or "permission denied" in lowered:
+        target = normalized_service_name or "systemd 服务"
+        return f"{target} 控制失败：权限不足，请检查当前 API 进程用户是否具备 systemctl 控制权限"
+    if "host is down" in lowered or "failed to connect to bus" in lowered:
+        return "systemctl 调用失败：当前环境未接入可用的 systemd/dbus，请确认部署方式与 worker_mode 是否匹配"
+    return message
+
+
 def _parse_systemd_timestamp(raw_timestamp: str) -> str:
     raw_timestamp = (raw_timestamp or "").strip()
     if not raw_timestamp:
@@ -206,7 +228,7 @@ def start_worker() -> tuple[bool, str]:
     if worker_mode == "linux-systemd":
         result = _run_systemctl(["start", service_name], timeout=30)
         if result.returncode != 0:
-            return False, (result.stderr or result.stdout or "启动 Linux Worker 失败").strip()
+            return False, normalize_systemctl_error(result.stderr or result.stdout or "启动 Linux Worker 失败", service_name=service_name)
         return True, f"Linux Worker 启动命令已发送: {service_name}"
 
     if os.name != "nt":
@@ -234,7 +256,7 @@ def stop_worker() -> tuple[bool, str]:
     if worker_mode == "linux-systemd":
         result = _run_systemctl(["stop", service_name], timeout=30)
         if result.returncode != 0:
-            return False, (result.stderr or result.stdout or "停止 Linux Worker 失败").strip()
+            return False, normalize_systemctl_error(result.stderr or result.stdout or "停止 Linux Worker 失败", service_name=service_name)
         return True, f"Linux Worker 停止命令已发送: {service_name}"
 
     if os.name != "nt":