fix: the bug when running command need sudo. 添加特权操作支持，封装sudo命令以简化权限管理

Author: cute-omega

README.md

@@ -450,6 +450,13 @@ npm run electron
   - `os-network-fallback.cjs` 会在 `uv_interface_addresses` 权限受限时返回回环接口，避免 node-ipc 崩溃。
   - 若仍需沙箱，只能在支持 setuid 的环境或 root 下运行。
 
+#### 5）需要特权操作的说明
+
+- 部分操作需要系统管理员权限（例如释放占用端口、修改系统网络设置、在 Windows 上启用 Loopback 等）。
+- 若权限不足，请手动以管理员权限运行相关命令或以管理员身份启动应用；在容器/受限环境中仅能执行当前用户可用的操作。
+- 开发者可在代码中统一通过 `DevSidecar.api.shell.sudo`（核心实现见 `packages/core/src/shell/sudo.js`）封装处理。
+
+
 ### 8.2、开发调试模式启动
 
 运行如下命令即可开发模式启动

packages/core/src/shell/index.js

@@ -8,6 +8,7 @@ const setSystemEnv = require('./scripts/set-system-env')
 const setSystemProxy = require('./scripts/set-system-proxy')
 const setupCa = require('./scripts/setup-ca')
 const shell = require('./shell')
+const sudo = require('./sudo')
 
 module.exports = {
   killByPort,
@@ -19,6 +20,7 @@ module.exports = {
   setSystemProxy,
   enableLoopback,
   extraPath,
+  sudo,
   async exec (cmds, args) {
     return shell.getSystemShell().exec(cmds, args)
   },

packages/core/src/shell/scripts/enable-loopback.js

@@ -2,40 +2,20 @@
  */
 const Shell = require('../shell')
 const extraPath = require('./extra-path')
-const sudoPrompt = require('@vscode/sudo-prompt')
-const log = require('../../utils/util.log.core')
+const sudo = require('../sudo')
 const execute = Shell.execute
 
 const executor = {
-  windows (exec) {
+  windows(exec) {
     const loopbackPath = extraPath.getEnableLoopbackPath()
-    const sudoCommand = [`"${loopbackPath}"`]
+    const sudoCommand = `"${loopbackPath}"`
 
-    const options = {
-      name: 'EnableLoopback',
-    }
-    return new Promise((resolve, reject) => {
-      sudoPrompt.exec(
-        sudoCommand.join(' '),
-        options,
-        (error, _, stderr) => {
-          if (stderr) {
-            log.error(`[sudo-prompt] 发生错误: ${stderr}`)
-          }
-
-          if (error) {
-            reject(error)
-          } else {
-            resolve(undefined)
-          }
-        },
-      )
-    })
+    return sudo(sudoCommand, { name: 'EnableLoopback' })
   },
-  async linux (exec, { port }) {
+  async linux(exec, { port }) {
     throw new Error('不支持此操作')
   },
-  async mac (exec, { port }) {
+  async mac(exec, { port }) {
     throw new Error('不支持此操作')
   },
 }

packages/core/src/shell/scripts/setup-ca.js

@@ -1,19 +1,19 @@
 const Shell = require('../shell')
+const sudo = require('../sudo')
 
 const execute = Shell.execute
 
 const executor = {
-  async windows (exec, { certPath }) {
+  async windows(exec, { certPath }) {
     const cmds = [`start "" "${certPath}"`]
     await exec(cmds, { type: 'cmd' })
     return true
   },
-  async linux (exec, { certPath }) {
-    const cmds = [`sudo cp ${certPath} /usr/local/share/ca-certificates`, 'sudo update-ca-certificates ']
-    await exec(cmds)
+  async linux(exec, { certPath }) {
+    await sudo(`cp ${certPath} /usr/local/share/ca-certificates && update-ca-certificates`, { name: 'DevSidecar CA Install' })
     return true
   },
-  async mac (exec, { certPath }) {
+  async mac(exec, { certPath }) {
     const cmds = [`open "${certPath}"`]
     await exec(cmds, { type: 'cmd' })
     return true

packages/core/src/shell/sudo.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const os = require('node:os')
+const sudoPrompt = require('@vscode/sudo-prompt')
+const log = require('../utils/util.log.core')
+
+function sudo (command, options = {}) {
+  const { name = 'DevSidecar', onStdout, onStderr } = options
+
+  if (!['darwin', 'linux', 'win32'].includes(os.platform())) {
+    return Promise.reject(new Error('Unsupported platform for privileged operations'))
+  }
+
+  return new Promise((resolve, reject) => {
+    sudoPrompt.exec(command, { name }, (error, stdout = '', stderr = '') => {
+      if (stdout && onStdout) onStdout(stdout)
+      if (stderr && onStderr) onStderr(stderr)
+      if (error) {
+        log.error('[sudo] command failed:', command, error)
+        return reject(error)
+      }
+      resolve({ stdout, stderr })
+    })
+  })
+}
+
+module.exports = sudo

packages/gui/src/bridge/api/open-enable-loopback.js

@@ -1,35 +1,17 @@
 /* global __static */
 import DevSidecar from '@docmirror/dev-sidecar'
-import sudoPrompt from '@vscode/sudo-prompt'
 import { join } from 'node:path'
-import log from '../../utils/util.log.gui'
 
 export default {
-  open () {
+  open() {
     const options = {
       name: 'EnableLoopback',
       icns: process.platform === 'darwin' ? join(__static, 'icon.icns') : undefined,
       env: { PARAM: 'VALUE' },
     }
     const exeFile = DevSidecar.api.shell.extraPath.getEnableLoopbackPath()
-    const sudoCommand = [`"${exeFile}"`]
+    const sudoCommand = `"${exeFile}"`
 
-    return new Promise((resolve, reject) => {
-      sudoPrompt.exec(
-        sudoCommand.join(' '),
-        options,
-        (error, _, stderr) => {
-          if (stderr) {
-            log.error(`[sudo-prompt] 发生错误: ${stderr}`)
-          }
-
-          if (error) {
-            reject(error)
-          } else {
-            resolve(undefined)
-          }
-        },
-      )
-    })
+    return DevSidecar.api.shell.sudo(sudoCommand, options)
   },
 }

packages/gui/src/bridge/auto-start/backend.js

@@ -20,8 +20,7 @@ EOF
 `
     await DevSidecar.api.shell.exec(cmd)
   } else {
-    const removeStart = 'sudo rm ~/.config/autostart/dev-sidecar.desktop -rf'
-    await DevSidecar.api.shell.exec(removeStart)
+    await DevSidecar.api.shell.sudo('rm ~/.config/autostart/dev-sidecar.desktop -rf', { name: 'Remove Autostart' })
   }
 }
 export default {