Security Permissions

Tauri 安全与权限管理

Tauri 2.x 安全模型

Tauri 2.x 引入了 Capabilities 系统,取代了 v1 的 allowlist。每个 API 和插件功能都需要显式声明权限。

capabilities/
└── default.json          # 主窗口默认权限

当前项目权限配置

基础结构

// src-tauri/capabilities/default.json
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "主窗口默认权限",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "opener:default",
    "store:default",
    "log:default"
  ]
}

当前已启用的权限

推荐权限配置（按需启用）

以下是常见桌面应用的推荐权限组合，根据项目需要选择性启用：

完整权限清单（按需添加）

核心权限

文件系统

对话框

系统交互

Opener

网络与更新

存储与日志

项目权限添加指南

当需要新功能时，按以下步骤添加权限：

1. 安装对应插件

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-fs = "2"

pnpm add @tauri-apps/plugin-fs

2. 注册插件

// src-tauri/src/lib.rs
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_fs::init())    // 添加这行
        .invoke_handler(tauri::generate_handler![...])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

3. 声明权限

// src-tauri/capabilities/default.json
{
  "permissions": [
    "core:default",
    "opener:default",
    "store:default",
    "log:default",
    "fs:default",              // 新增
    "fs:allow-read-text-file"  // 新增
  ]
}

高级权限: 作用域控制

当需要限制文件访问范围时：

{
  "identifier": "fs-scoped",
  "permissions": [
    {
      "identifier": "fs:allow-read-text-file",
      "allow": [{ "path": "$APPDATA/**" }]
    },
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$APPDATA/**" }]
    }
  ]
}

Opener 路径作用域

打开本地路径时，建议使用 scope 限制可访问范围：

{
  "identifier": "opener:allow-open-path",
  "allow": [{ "path": "**" }]
}

注意："path": "**" 允许打开任意路径。生产环境应限制为 $APPDATA/** 或特定目录。

路径变量

多窗口差异化权限

如果应用有多个窗口，可以为不同窗口配置不同权限。

通配符匹配动态窗口

windows 字段支持通配符 *，适用于动态创建的窗口：

// default.json - 覆盖所有窗口
{
  "identifier": "default",
  "windows": ["main", "editor-*", "viewer-*"],
  "permissions": [
    "core:default",
    "core:window:allow-start-dragging",
    "core:window:allow-minimize",
    "core:window:allow-maximize",
    "core:window:allow-toggle-maximize",
    "core:window:allow-close",
    "opener:default",
    "store:default",
    "log:default"
  ]
}

说明："editor-*" 会匹配所有以 editor- 开头的窗口标签（如 editor-1、editor-abc），适用于运行时通过 WebviewWindowBuilder 动态创建的窗口。

按窗口角色配置不同权限

// admin-capability.json - 管理窗口（高权限）
{
  "identifier": "admin",
  "windows": ["admin-*"],
  "permissions": [
    "core:default",
    "fs:default",
    "shell:default",
    "dialog:default"
  ]
}

// viewer-capability.json - 查看窗口（低权限）
{
  "identifier": "viewer",
  "windows": ["viewer-*"],
  "permissions": [
    "core:default"
  ]
}

典型多窗口权限组合

CSP(内容安全策略)

// tauri.conf.json
{
  "app": {
    "security": {
      "csp": "default-src 'self'; img-src 'self' asset: https://asset.localhost; style-src 'unsafe-inline' 'self'"
    }
  }
}

安全最佳实践

1. 最小权限原则

只声明实际需要的权限，不要添加"可能用到"的权限。

// ❌ 不好：添加不需要的权限
{
  "permissions": ["core:default", "fs:default", "http:default", "websocket:default"]
}

// ✅ 好：只添加当前需要的权限
{
  "permissions": [
    "core:default",
    "opener:default",
    "store:default",
    "log:default"
  ]
}

2. 无边框窗口权限

core:default 包含 core:window:default，但不含 core:window:allow-start-dragging。无边框窗口必须显式声明：

{
  "permissions": [
    "core:default",
    "core:window:allow-start-dragging",
    "core:window:allow-minimize",
    "core:window:allow-maximize",
    "core:window:allow-toggle-maximize",
    "core:window:allow-close"
  ]
}

3. 作用域限制

文件操作限制在特定目录：

{
  "identifier": "fs:allow-read-text-file",
  "allow": [{ "path": "$APPDATA/**" }]
}

4. 不暴露敏感操作

加密/密钥等放在 Rust 侧，不要通过 Command 暴露给前端。

5. Command 验证

在 Rust Command 中验证输入参数：

#[tauri::command]
pub fn read_file(path: String) -> Result<String, String> {
    // 验证路径安全性
    if path.contains("..") {
        return Err("不允许访问父目录".into());
    }
    // ...
}

6. 不信任前端数据

前端发来的数据在 Rust 侧重新验证：

#[tauri::command]
pub fn delete_user(id: i64) -> Result<(), String> {
    // 验证 ID 有效性
    if id <= 0 {
        return Err("无效的用户 ID".into());
    }
    // 检查权限
    // ...
}

排查权限问题

常见错误