refactor: 统一将 Nitro 相关命名更新为 Sidecar

- 将文档中所有关于 Nitro Server 的表述统一更新为 Sidecar Server，以准确反映当前架构中后端服务的命名和职责。 - 更新进程管理名称与相关函数调用，将 Nitro 相关的组件和操作统一替换为 Sidecar，以反映当前模块的正确命名和功能。 - 将 Nitro 相关的进程管理功能重命名为 Sidecar，更新结构体、函数和日志信息以反映新的命名和功能，确保进程启动、状态管理和清理逻辑正确指向新的 Sidecar 进程。
2026-01-16 23:06:53 +08:00
parent 0479a89905
commit d2a70b5a26
3 changed files with 38 additions and 38 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,8 +6,8 @@

 - **项目类型**: Tauri v2 桌面应用（轻量级壳子）
 - **后端**: Rust (Edition 2021)
- **架构**: Sidecar 模式 - Nitro Server 承载主要业务逻辑
- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Nitro 处理
+- **架构**: Sidecar 模式 - Sidecar Server 承载主要业务逻辑
+- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar Server 处理
 - **异步运行时**: Tokio
 - **Rust 版本**: 1.92.0+

@@ -18,7 +18,7 @@
 # 开发模式运行 (带 hot-reload)
 cargo tauri dev

-# 仅运行 Rust 二进制 (不推荐，需要手动启动 Nitro)
+# 仅运行 Rust 二进制 (不推荐，需要手动启动 Sidecar Server)
 cargo run
 ```

@@ -85,9 +85,9 @@ tauri-shell/
 │   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
 │   ├── commands/
 │   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
-│   └── sidecar.rs       # Nitro 进程管理 (启动、端口扫描、清理)
+│   └── sidecar.rs       # Sidecar Server 进程管理 (启动、端口扫描、清理)
 ├── binaries/            # Sidecar 二进制文件
-│   └── nitro-server-*   # Nitro Server 可执行文件
+│   └── nitro-server-*   # Sidecar Server 可执行文件 (示例: nitro-server)
 ├── capabilities/        # Tauri v2 权限配置
 │   └── default.json
 ├── icons/               # 应用图标资源
@@ -128,12 +128,12 @@ use tauri::*;

 ```rust
 // ✅ 推荐
-struct NitroProcess(Mutex<Option<CommandChild>>);
+struct SidecarProcess(Mutex<Option<CommandChild>>);
 const DEFAULT_PORT: u16 = 3000;
 async fn find_available_port(start: u16) -> u16 { }

 // ❌ 避免
-struct nitro_process { }
+struct sidecar_process { }
 const defaultPort: u16 = 3000;
 ```

@@ -176,8 +176,8 @@ let sidecar = app_handle
 let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");

 // 日志记录
-eprintln!("✗ Nitro 服务器启动失败");
-println!("✓ Nitro 服务器启动成功！");
+eprintln!("✗ Sidecar Server 启动失败");
+println!("✓ Sidecar Server 启动成功！");

 // ❌ 避免
 let data = read_file().unwrap();  // 无上下文信息
@@ -214,8 +214,8 @@ tauri::async_runtime::spawn(async move {

 ```rust
 // ✅ 推荐
-// 全局状态：存储 Nitro 进程句柄
-struct NitroProcess(Mutex<Option<CommandChild>>);
+// 全局状态：存储 Sidecar Server 进程句柄
+struct SidecarProcess(Mutex<Option<CommandChild>>);

 // 检查端口是否可用
 async fn is_port_available(port: u16) -> bool { }
@@ -234,7 +234,7 @@ async fn is_port_available(port: u16) -> bool { }
 mod commands;
 mod sidecar;

-use sidecar::NitroProcess;
+use sidecar::SidecarProcess;

 // 注册命令时使用模块路径
 .invoke_handler(tauri::generate_handler![commands::greet])
@@ -264,13 +264,13 @@ fn greet(name: &str) -> String {
 - 使用 `Mutex` 或 `RwLock` 保证线程安全

 ```rust
-struct NitroProcess(Mutex<Option<CommandChild>>);
+struct SidecarProcess(Mutex<Option<CommandChild>>);

 // 注册状态
-app.manage(NitroProcess(Mutex::new(None)));
+app.manage(SidecarProcess(Mutex::new(None)));

 // 访问状态
-if let Some(state) = app_handle.try_state::<NitroProcess>() {
+if let Some(state) = app_handle.try_state::<SidecarProcess>() {
    *state.0.lock().unwrap() = Some(child);
 }
 ```
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,7 +4,7 @@ use tauri::Manager;
 mod commands;
 mod sidecar;

-use sidecar::NitroProcess;
+use sidecar::SidecarProcess;

 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
@@ -13,11 +13,11 @@ pub fn run() {
        .plugin(tauri_plugin_shell::init())
        .setup(|app| {
            // 注册全局状态
-            app.manage(NitroProcess(std::sync::Mutex::new(None)));
+            app.manage(SidecarProcess(std::sync::Mutex::new(None)));

-            // 启动 Nitro Sidecar 进程
+            // 启动 Sidecar Server 进程
            let app_handle = app.handle().clone();
-            sidecar::spawn_nitro_sidecar(app_handle);
+            sidecar::spawn_sidecar(app_handle);

            Ok(())
        })
@@ -25,10 +25,10 @@ pub fn run() {
        .build(tauri::generate_context!())
        .expect("error while building tauri application")
        .run(|app_handle, event| {
-            // 监听应用退出事件，清理 Nitro 进程
+            // 监听应用退出事件，清理 Sidecar Server 进程
            match event {
                tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
-                    sidecar::cleanup_nitro_process(app_handle);
+                    sidecar::cleanup_sidecar_process(app_handle);
                }
                _ => {}
            }
--- a/src/sidecar.rs
+++ b/src/sidecar.rs
@@ -5,8 +5,8 @@ use tauri::Manager;
 use tauri_plugin_shell::process::{CommandChild, CommandEvent};
 use tauri_plugin_shell::ShellExt;

-// 全局状态：存储 Nitro 进程句柄
-pub struct NitroProcess(pub Mutex<Option<CommandChild>>);
+// 全局状态：存储 Sidecar 进程句柄
+pub struct SidecarProcess(pub Mutex<Option<CommandChild>>);

 // 检查端口是否可用
 async fn is_port_available(port: u16) -> bool {
@@ -25,8 +25,8 @@ async fn find_available_port(start: u16) -> u16 {
    start // 回退到起始端口
 }

-/// 启动 Nitro Sidecar 进程并创建主窗口
-pub fn spawn_nitro_sidecar(app_handle: tauri::AppHandle) {
+/// 启动 Sidecar 进程并创建主窗口
+pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
    tauri::async_runtime::spawn(async move {
        // 查找可用端口
        let port = find_available_port(3000).await;
@@ -35,14 +35,14 @@ pub fn spawn_nitro_sidecar(app_handle: tauri::AppHandle) {
        // 启动 sidecar
        let sidecar = app_handle
            .shell()
-            .sidecar("nitro-server")
-            .expect("无法找到 nitro-server sidecar")
+            .sidecar("server")
+            .expect("无法找到 server")
            .env("NITRO_PORT", port.to_string());

        let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");

        // 保存进程句柄到全局状态
-        if let Some(state) = app_handle.try_state::<NitroProcess>() {
+        if let Some(state) = app_handle.try_state::<SidecarProcess>() {
            *state.0.lock().unwrap() = Some(child);
        }

@@ -54,12 +54,12 @@ pub fn spawn_nitro_sidecar(app_handle: tauri::AppHandle) {
        while let Some(event) = rx.recv().await {
            if let CommandEvent::Stdout(line) = event {
                let output = String::from_utf8_lossy(&line);
-                println!("Nitro: {}", output);
+                println!("Sidecar: {}", output);

                // 检测服务器启动成功的标志
                if output.contains("Listening on:") || output.contains("localhost") {
                    server_ready = true;
-                    println!("✓ Nitro 服务器启动成功！");
+                    println!("✓ Sidecar 启动成功！");

                    // 创建主窗口
                    let url = format!("http://localhost:{}", port);
@@ -68,7 +68,7 @@ pub fn spawn_nitro_sidecar(app_handle: tauri::AppHandle) {
                        "main",
                        tauri::WebviewUrl::External(url.parse().unwrap()),
                    )
-                    .title("Nitro Application")
+                    .title("Tauri Application")
                    .inner_size(1200.0, 800.0)
                    .center()
                    .build()
@@ -80,26 +80,26 @@ pub fn spawn_nitro_sidecar(app_handle: tauri::AppHandle) {

            // 超时检查
            if start_time.elapsed() > timeout {
-                eprintln!("✗ 启动超时：Nitro 服务器未能在 5 秒内启动");
+                eprintln!("✗ 启动超时：Sidecar 未能在 5 秒内启动");
                break;
            }
        }

        if !server_ready {
-            eprintln!("✗ Nitro 服务器启动失败");
+            eprintln!("✗ Sidecar 启动失败");
            std::process::exit(1);
        }
    });
 }

-/// 清理 Nitro 进程 (在应用退出时调用)
-pub fn cleanup_nitro_process(app_handle: &tauri::AppHandle) {
-    println!("应用退出，正在清理 Nitro 进程...");
-    if let Some(state) = app_handle.try_state::<NitroProcess>() {
+/// 清理 Sidecar 进程 (在应用退出时调用)
+pub fn cleanup_sidecar_process(app_handle: &tauri::AppHandle) {
+    println!("应用退出，正在清理 Sidecar 进程...");
+    if let Some(state) = app_handle.try_state::<SidecarProcess>() {
        if let Ok(mut process) = state.0.lock() {
            if let Some(child) = process.take() {
                let _ = child.kill();
-                println!("✓ Nitro 进程已终止");
+                println!("✓ Sidecar 进程已终止");
            }
        }
    }