zclaw_openfang/docs/features/06-tauri-backend/00-backend-integration.md

OpenFang 集成 (OpenFang Integration)

分类: Tauri 后端 优先级: P0 - 决定性 成熟度: L4 - 生产 最后更新: 2026-03-16

---

一、功能概述

1.1 基本信息

OpenFang 集成模块是 Tauri 后端的核心，负责与 OpenFang Rust 运行时的本地集成，包括进程管理、配置读写、设备配对等。

属性	值
分类	Tauri 后端
优先级	P0
成熟度	L4
依赖	Tauri Runtime

1.2 相关文件

文件	路径	用途
核心实现	desktop/src-tauri/src/lib.rs	OpenFang 命令 (1043行)
Viking 命令	desktop/src-tauri/src/viking_commands.rs	OpenViking sidecar
服务器管理	desktop/src-tauri/src/viking_server.rs	本地服务器
安全存储	desktop/src-tauri/src/secure_storage.rs	Keyring 集成

---

二、设计初衷

2.1 问题背景

用户痛点:

1. 需要手动启动 OpenFang 运行时
2. 配置文件分散难以管理
3. 跨平台兼容性问题

系统缺失能力:

• 缺乏本地运行时管理
• 缺乏统一的配置接口
• 缺乏进程监控能力

为什么需要: Tauri 后端提供了原生系统集成能力，让用户无需关心运行时的启动和管理。

2.2 设计目标

1. 自动发现: 自动找到 OpenFang 运行时
2. 生命周期管理: 启动、停止、重启
3. 配置管理: TOML 配置读写
4. 进程监控: 状态和日志查看

2.3 运行时发现优先级

1. 环境变量 ZCLAW_OPENFANG_BIN
2. Tauri 资源目录中的捆绑运行时
3. 系统 PATH 中的 openfang 命令

2.4 设计约束

• 安全约束: 配置文件需要验证
• 性能约束: 进程操作不能阻塞 UI
• 兼容性约束: Windows/macOS/Linux 统一接口

---

三、技术设计

3.1 核心命令

#[tauri::command]
fn openfang_status(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_start(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_stop(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_restart(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_local_auth(app: AppHandle) -> Result<GatewayAuth, String>

#[tauri::command]
fn openfang_prepare_for_tauri(app: AppHandle) -> Result<(), String>

#[tauri::command]
fn openfang_approve_device_pairing(app: AppHandle, device_id: String) -> Result<(), String>

#[tauri::command]
fn openfang_process_list(app: AppHandle) -> Result<ProcessListResponse, String>

#[tauri::command]
fn openfang_process_logs(app: AppHandle, pid: Option<u32>, lines: Option<usize>) -> Result<ProcessLogsResponse, String>

#[tauri::command]
fn openfang_version(app: AppHandle) -> Result<VersionInfo, String>

3.2 状态结构

#[derive(Serialize)]
struct LocalGatewayStatus {
    running: bool,
    port: Option<u16>,
    pid: Option<u32>,
    config_path: Option<String>,
    binary_path: Option<String>,
    service_name: Option<String>,
    error: Option<String>,
}

#[derive(Serialize)]
struct GatewayAuth {
    gateway_token: Option<String>,
    device_public_key: Option<String>,
}

3.3 运行时发现

fn find_openfang_binary(app: &AppHandle) -> Option<PathBuf> {
    // 1. 环境变量
    if let Ok(path) = std::env::var("ZCLAW_OPENFANG_BIN") {
        let path = PathBuf::from(path);
        if path.exists() {
            return Some(path);
        }
    }

    // 2. 捆绑运行时
    if let Some(resource_dir) = app.path().resource_dir().ok() {
        let bundled = resource_dir.join("bin").join("openfang");
        if bundled.exists() {
            return Some(bundled);
        }
    }

    // 3. 系统 PATH
    if let Ok(path) = which::which("openfang") {
        return Some(path);
    }

    None
}

3.4 配置管理

fn read_config(config_path: &Path) -> Result<OpenFangConfig, String> {
    let content = std::fs::read_to_string(config_path)
        .map_err(|e| format!("Failed to read config: {}", e))?;

    let config: OpenFangConfig = toml::from_str(&content)
        .map_err(|e| format!("Failed to parse config: {}", e))?;

    Ok(config)
}

fn write_config(config_path: &Path, config: &OpenFangConfig) -> Result<(), String> {
    let content = toml::to_string_pretty(config)
        .map_err(|e| format!("Failed to serialize config: {}", e))?;

    std::fs::write(config_path, content)
        .map_err(|e| format!("Failed to write config: {}", e))
}

---

四、预期作用

4.1 用户价值

价值类型	描述
便捷体验	一键启动/停止
统一管理	配置集中管理
透明度	进程状态可见

4.2 系统价值

价值类型	描述
架构收益	原生系统集成
可维护性	Rust 代码稳定
可扩展性	易于添加新命令

4.3 成功指标

指标	基线	目标	当前
启动成功率	80%	99%	98%
配置解析成功率	90%	99%	99%
响应时间	-	<1s	500ms

---

五、实际效果

5.1 已实现功能

• 运行时自动发现
• 启动/停止/重启
• TOML 配置读写
• 设备配对审批
• 进程列表查看
• 进程日志查看
• 版本信息获取
• 错误处理

5.2 测试覆盖

• 单元测试: Rust 内置测试
• 集成测试: 包含在前端测试中
• 覆盖率: ~85%

5.3 已知问题

问题	严重程度	状态	计划解决
某些 Linux 发行版路径问题	中	已处理	-

5.4 用户反馈

本地集成体验流畅，无需关心运行时管理。

---

六、演化路线

6.1 短期计划（1-2 周）

• 添加自动更新检查
• 优化错误信息

6.2 中期计划（1-2 月）

• 多实例管理
• 配置备份/恢复

6.3 长期愿景

• 远程 OpenFang 管理
• 集群部署支持

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否需要支持自定义运行时路径？
2. 如何处理运行时升级？

7.2 创意想法

• 运行时健康检查：定期检测运行时状态
• 自动重启：运行时崩溃后自动恢复
• 资源监控：CPU/内存使用追踪

7.3 风险与挑战

• 技术风险: 跨平台兼容性
• 安全风险: 配置文件权限
• 缓解措施: 路径验证，权限检查