12 KiB

Raw Blame History

Tauri 安全配置详细指南

基于 Tauri CLI Schema v2.6.2 的完整安全配置说明文档

📋 目录

SecurityConfig 安全配置
CSP 内容安全策略
AssetProtocol 资源协议
最佳实践建议
常见配置示例

SecurityConfig 安全配置

📖 概述

SecurityConfig 是 Tauri 应用程序的核心安全配置对象，控制着应用的安全策略、内容安全策略(CSP)、资源访问协议等关键安全特性。

🔧 配置结构

{
  "app": {
    "security": {
      "csp": "...",
      "devCsp": "...",
      "assetProtocol": {...},
      "dangerousDisableAssetCspModification": false,
      "freezePrototype": false,
      "pattern": {...},
      "capabilities": [...],
      "headers": {...}
    }
  }
}

CSP 内容安全策略

📖 定义

Content Security Policy (CSP) 是一个重要的安全层，用于检测和减轻某些类型的攻击，包括跨站脚本 (XSS) 和数据注入攻击。

🔧 配置选项

1. `csp` - 生产环境CSP

{
  "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'"
}

类型: string | object | null 默认值: null 用途:

定义生产环境下的内容安全策略
如果未设置 devCsp，开发环境也会使用此配置
控制哪些资源可以被加载和执行

2. `devCsp` - 开发环境CSP

{
  "devCsp": "default-src 'self' 'unsafe-eval'; script-src 'self' 'unsafe-inline'"
}

类型: string | object | null 默认值: null 用途:

专门用于开发环境的CSP配置
通常比生产环境更宽松，允许热重载等开发工具

📝 CSP 指令说明

字符串格式

{
  "csp": "default-src 'self'; img-src 'self' data: asset: http://asset.localhost; media-src 'self' asset: http://asset.localhost"
}

对象格式

{
  "csp": {
    "default-src": ["'self'"],
    "img-src": ["'self'", "data:", "asset:", "http://asset.localhost"],
    "media-src": ["'self'", "asset:", "http://asset.localhost"],
    "script-src": ["'self'", "'unsafe-inline'"],
    "style-src": ["'self'", "'unsafe-inline'"]
  }
}

🎯 常用CSP指令

指令	说明	示例值
`default-src`	默认源策略	`'self'`
`script-src`	JavaScript源	`'self' 'unsafe-inline'`
`style-src`	CSS样式源	`'self' 'unsafe-inline'`
`img-src`	图片源	`'self' data: asset:`
`media-src`	媒体源	`'self' asset:`
`connect-src`	连接源	`'self' ipc: http://ipc.localhost`
`font-src`	字体源	`'self' data:`

AssetProtocol 资源协议

📖 定义

AssetProtocol 配置控制 Tauri 的自定义资源协议，允许前端安全地访问本地文件系统资源。

🔧 配置结构

{
  "assetProtocol": {
    "enable": true,
    "scope": ["**"]
  }
}

1. `enable` - 启用资源协议

类型: boolean 默认值: false 用途:

控制是否启用 asset:// 协议
启用后可以通过 convertFileSrc() 访问本地文件

2. `scope` - 访问范围

类型: string[] 默认值: [] 用途:

定义资源协议可以访问的文件路径范围
使用 glob 模式匹配路径
空数组表示禁止访问任何文件

📝 Scope 配置示例

允许访问所有文件 (⚠️ 不推荐)

{
  "scope": ["**"]
}

限制访问特定目录

{
  "scope": [
    "$APPDATA/myapp/**",
    "$RESOURCE/**",
    "/Users/*/Documents/myapp/**"
  ]
}

使用环境变量

{
  "scope": [
    "$HOME/.myapp/**",
    "$TEMP/myapp-cache/**"
  ]
}

高级安全配置

1. `dangerousDisableAssetCspModification`

类型: boolean | string[] 默认值: false 用途: 禁用 Tauri 的 CSP 自动注入

{
  "dangerousDisableAssetCspModification": false
}

⚠️ 警告: 只有在完全理解安全影响时才禁用此功能

禁用所有CSP修改

{
  "dangerousDisableAssetCspModification": true
}

禁用特定指令的修改

{
  "dangerousDisableAssetCspModification": ["script-src", "style-src"]
}

2. `freezePrototype`

类型: boolean 默认值: false 用途: 冻结 Object.prototype 以防止原型污染攻击

{
  "freezePrototype": true
}

3. `pattern` - 安全模式

类型: object 用途: 定义应用的安全模式

Brownfield 模式 (默认)

{
  "pattern": {
    "use": "brownfield"
  }
}

Isolation 模式 (推荐)

{
  "pattern": {
    "use": "isolation",
    "options": {
      "dir": "../dist-isolation"
    }
  }
}

最佳实践建议

🔒 安全级别配置

高安全级别 (推荐生产环境)

{
  "security": {
    "csp": "default-src 'self'; img-src 'self' asset: data:; media-src 'self' asset:; script-src 'self'; style-src 'self' 'unsafe-inline'",
    "assetProtocol": {
      "enable": true,
      "scope": ["$APPDATA/myapp/**", "$RESOURCE/**"]
    },
    "freezePrototype": true,
    "pattern": {
      "use": "isolation",
      "options": {
        "dir": "../dist-isolation"
      }
    }
  }
}

中等安全级别 (开发友好)

{
  "security": {
    "csp": "default-src 'self'; img-src 'self' asset: data: http://asset.localhost; media-src 'self' asset: http://asset.localhost; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'",
    "devCsp": "default-src 'self' 'unsafe-eval'; img-src 'self' asset: data: http://asset.localhost; media-src 'self' asset: http://asset.localhost; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'",
    "assetProtocol": {
      "enable": true,
      "scope": ["**"]
    },
    "freezePrototype": false
  }
}

🎯 针对不同场景的配置

媒体应用 (视频/音频)

{
  "security": {
    "csp": {
      "default-src": ["'self'"],
      "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"],
      "media-src": ["'self'", "asset:", "http://asset.localhost"],
      "video-src": ["'self'", "asset:", "http://asset.localhost"],
      "script-src": ["'self'", "'unsafe-inline'"],
      "style-src": ["'self'", "'unsafe-inline'"],
      "connect-src": ["'self'", "ipc:", "http://ipc.localhost"]
    },
    "assetProtocol": {
      "enable": true,
      "scope": ["$HOME/Videos/**", "$HOME/Music/**", "$APPDATA/myapp/**"]
    }
  }
}

文件管理应用

{
  "security": {
    "csp": "default-src 'self'; img-src 'self' asset: data: http://asset.localhost; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' ipc: http://ipc.localhost",
    "assetProtocol": {
      "enable": true,
      "scope": ["$HOME/**", "$DESKTOP/**", "$DOCUMENT/**"]
    }
  }
}

🚨 安全注意事项

1. CSP 配置

❌ 避免使用 'unsafe-eval' 在生产环境
❌ 谨慎使用 'unsafe-inline'
✅ 优先使用 nonce 或 hash 值
✅ 定期审查和更新 CSP 策略

2. AssetProtocol 配置

❌ 避免使用 ["**"] 作为 scope
✅ 限制访问范围到必要的目录
✅ 使用环境变量定义路径
✅ 定期审查文件访问权限

3. 开发 vs 生产

开发环境可以适当放宽限制
生产环境必须严格控制安全策略
使用 devCsp 区分开发和生产配置

🔧 故障排除指南

常见CSP错误及解决方案

1. 视频/音频无法播放

错误: Refused to load media from 'asset://...' because it violates CSP

解决方案:

{
  "csp": {
    "media-src": ["'self'", "asset:", "http://asset.localhost"],
    "video-src": ["'self'", "asset:", "http://asset.localhost"]
  }
}

2. 图片无法显示

错误: Refused to load image from 'asset://...' because it violates CSP

解决方案:

{
  "csp": {
    "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"]
  }
}

3. 内联样式被阻止

错误: Refused to apply inline style because it violates CSP

解决方案:

{
  "csp": {
    "style-src": ["'self'", "'unsafe-inline'"]
  }
}

AssetProtocol 故障排除

1. 文件访问被拒绝

错误: Asset protocol access denied

检查项目:

确认 assetProtocol.enable 为 true
检查文件路径是否在 scope 范围内
验证文件是否存在且有读取权限

2. Windows 路径问题

问题: Windows 绝对路径无法访问

解决方案:

{
  "assetProtocol": {
    "enable": true,
    "scope": [
      "C:\\Users\\**",
      "$APPDATA\\**",
      "$LOCALAPPDATA\\**"
    ]
  }
}

📊 配置验证工具

1. CSP 验证

使用浏览器开发者工具检查 CSP 违规:

// 在控制台中检查 CSP 策略
console.log(document.querySelector('meta[http-equiv="Content-Security-Policy"]').content);

2. AssetProtocol 测试

// 测试资源协议是否工作
import { convertFileSrc } from '@tauri-apps/api/core';

const testPath = '/path/to/test/file.txt';
const assetUrl = convertFileSrc(testPath);
console.log('Asset URL:', assetUrl);

// 测试文件访问
fetch(assetUrl)
  .then(response => response.text())
  .then(data => console.log('File content:', data))
  .catch(error => console.error('Access denied:', error));

🎯 完整配置示例

视频编辑应用配置

{
  "app": {
    "security": {
      "csp": {
        "default-src": ["'self'"],
        "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"],
        "media-src": ["'self'", "asset:", "http://asset.localhost"],
        "video-src": ["'self'", "asset:", "http://asset.localhost"],
        "script-src": ["'self'", "'unsafe-inline'"],
        "style-src": ["'self'", "'unsafe-inline'"],
        "connect-src": ["'self'", "ipc:", "http://ipc.localhost"],
        "font-src": ["'self'", "data:"]
      },
      "devCsp": {
        "default-src": ["'self'", "'unsafe-eval'"],
        "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"],
        "media-src": ["'self'", "asset:", "http://asset.localhost"],
        "video-src": ["'self'", "asset:", "http://asset.localhost"],
        "script-src": ["'self'", "'unsafe-inline'", "'unsafe-eval'"],
        "style-src": ["'self'", "'unsafe-inline'"],
        "connect-src": ["'self'", "ipc:", "http://ipc.localhost", "ws:", "wss:"],
        "font-src": ["'self'", "data:"]
      },
      "assetProtocol": {
        "enable": true,
        "scope": [
          "$HOME/Videos/**",
          "$HOME/Movies/**",
          "$DESKTOP/**",
          "$DOCUMENT/**",
          "$APPDATA/mixvideo/**",
          "$TEMP/mixvideo/**"
        ]
      },
      "freezePrototype": false,
      "dangerousDisableAssetCspModification": false
    }
  }
}

文件管理器配置

{
  "app": {
    "security": {
      "csp": "default-src 'self'; img-src 'self' asset: data: http://asset.localhost; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' ipc: http://ipc.localhost",
      "assetProtocol": {
        "enable": true,
        "scope": [
          "$HOME/**",
          "$DESKTOP/**",
          "$DOCUMENT/**",
          "$DOWNLOAD/**",
          "C:\\**",
          "/Users/**",
          "/home/**"
        ]
      },
      "freezePrototype": true
    }
  }
}

📚 参考资源

最后更新: 2025-01-11 基于 Tauri CLI Schema v2.6.2

12 KiB Raw Blame History

Tauri 安全配置详细指南

📋 目录

SecurityConfig 安全配置

📖 概述

🔧 配置结构

CSP 内容安全策略

📖 定义

🔧 配置选项

1. csp - 生产环境CSP

2. devCsp - 开发环境CSP

📝 CSP 指令说明

字符串格式

对象格式

🎯 常用CSP指令

AssetProtocol 资源协议

📖 定义

🔧 配置结构

1. enable - 启用资源协议

2. scope - 访问范围

📝 Scope 配置示例

允许访问所有文件 (⚠️ 不推荐)

限制访问特定目录

使用环境变量

高级安全配置

1. dangerousDisableAssetCspModification

禁用所有CSP修改

禁用特定指令的修改

2. freezePrototype

3. pattern - 安全模式

Brownfield 模式 (默认)

Isolation 模式 (推荐)

最佳实践建议

🔒 安全级别配置

高安全级别 (推荐生产环境)

中等安全级别 (开发友好)

🎯 针对不同场景的配置

媒体应用 (视频/音频)

文件管理应用

🚨 安全注意事项

1. CSP 配置

2. AssetProtocol 配置

3. 开发 vs 生产

🔧 故障排除指南

常见CSP错误及解决方案

1. 视频/音频无法播放

2. 图片无法显示

3. 内联样式被阻止

AssetProtocol 故障排除

1. 文件访问被拒绝

2. Windows 路径问题

📊 配置验证工具

1. CSP 验证

2. AssetProtocol 测试

🎯 完整配置示例

视频编辑应用配置

文件管理器配置

📚 参考资源

12 KiB

Raw Blame History

1. `csp` - 生产环境CSP

2. `devCsp` - 开发环境CSP

1. `enable` - 启用资源协议

2. `scope` - 访问范围

1. `dangerousDisableAssetCspModification`

2. `freezePrototype`

3. `pattern` - 安全模式