521 lines
12 KiB
Markdown
521 lines
12 KiB
Markdown
# Tauri 安全配置详细指南
|
|
|
|
基于 Tauri CLI Schema v2.6.2 的完整安全配置说明文档
|
|
|
|
## 📋 目录
|
|
|
|
- [SecurityConfig 安全配置](#securityconfig-安全配置)
|
|
- [CSP 内容安全策略](#csp-内容安全策略)
|
|
- [AssetProtocol 资源协议](#assetprotocol-资源协议)
|
|
- [最佳实践建议](#最佳实践建议)
|
|
- [常见配置示例](#常见配置示例)
|
|
|
|
---
|
|
|
|
## SecurityConfig 安全配置
|
|
|
|
### 📖 概述
|
|
`SecurityConfig` 是 Tauri 应用程序的核心安全配置对象，控制着应用的安全策略、内容安全策略(CSP)、资源访问协议等关键安全特性。
|
|
|
|
### 🔧 配置结构
|
|
|
|
```json
|
|
{
|
|
"app": {
|
|
"security": {
|
|
"csp": "...",
|
|
"devCsp": "...",
|
|
"assetProtocol": {...},
|
|
"dangerousDisableAssetCspModification": false,
|
|
"freezePrototype": false,
|
|
"pattern": {...},
|
|
"capabilities": [...],
|
|
"headers": {...}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## CSP 内容安全策略
|
|
|
|
### 📖 定义
|
|
Content Security Policy (CSP) 是一个重要的安全层，用于检测和减轻某些类型的攻击，包括跨站脚本 (XSS) 和数据注入攻击。
|
|
|
|
### 🔧 配置选项
|
|
|
|
#### 1. `csp` - 生产环境CSP
|
|
```json
|
|
{
|
|
"csp": "default-src 'self'; script-src 'self' 'unsafe-inline'"
|
|
}
|
|
```
|
|
|
|
**类型**: `string | object | null`
|
|
**默认值**: `null`
|
|
**用途**:
|
|
- 定义生产环境下的内容安全策略
|
|
- 如果未设置 `devCsp`，开发环境也会使用此配置
|
|
- 控制哪些资源可以被加载和执行
|
|
|
|
#### 2. `devCsp` - 开发环境CSP
|
|
```json
|
|
{
|
|
"devCsp": "default-src 'self' 'unsafe-eval'; script-src 'self' 'unsafe-inline'"
|
|
}
|
|
```
|
|
|
|
**类型**: `string | object | null`
|
|
**默认值**: `null`
|
|
**用途**:
|
|
- 专门用于开发环境的CSP配置
|
|
- 通常比生产环境更宽松，允许热重载等开发工具
|
|
|
|
### 📝 CSP 指令说明
|
|
|
|
#### 字符串格式
|
|
```json
|
|
{
|
|
"csp": "default-src 'self'; img-src 'self' data: asset: http://asset.localhost; media-src 'self' asset: http://asset.localhost"
|
|
}
|
|
```
|
|
|
|
#### 对象格式
|
|
```json
|
|
{
|
|
"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 的自定义资源协议，允许前端安全地访问本地文件系统资源。
|
|
|
|
### 🔧 配置结构
|
|
|
|
```json
|
|
{
|
|
"assetProtocol": {
|
|
"enable": true,
|
|
"scope": ["**"]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 1. `enable` - 启用资源协议
|
|
**类型**: `boolean`
|
|
**默认值**: `false`
|
|
**用途**:
|
|
- 控制是否启用 `asset://` 协议
|
|
- 启用后可以通过 `convertFileSrc()` 访问本地文件
|
|
|
|
#### 2. `scope` - 访问范围
|
|
**类型**: `string[]`
|
|
**默认值**: `[]`
|
|
**用途**:
|
|
- 定义资源协议可以访问的文件路径范围
|
|
- 使用 glob 模式匹配路径
|
|
- 空数组表示禁止访问任何文件
|
|
|
|
### 📝 Scope 配置示例
|
|
|
|
#### 允许访问所有文件 (⚠️ 不推荐)
|
|
```json
|
|
{
|
|
"scope": ["**"]
|
|
}
|
|
```
|
|
|
|
#### 限制访问特定目录
|
|
```json
|
|
{
|
|
"scope": [
|
|
"$APPDATA/myapp/**",
|
|
"$RESOURCE/**",
|
|
"/Users/*/Documents/myapp/**"
|
|
]
|
|
}
|
|
```
|
|
|
|
#### 使用环境变量
|
|
```json
|
|
{
|
|
"scope": [
|
|
"$HOME/.myapp/**",
|
|
"$TEMP/myapp-cache/**"
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 高级安全配置
|
|
|
|
### 1. `dangerousDisableAssetCspModification`
|
|
|
|
**类型**: `boolean | string[]`
|
|
**默认值**: `false`
|
|
**用途**: 禁用 Tauri 的 CSP 自动注入
|
|
|
|
```json
|
|
{
|
|
"dangerousDisableAssetCspModification": false
|
|
}
|
|
```
|
|
|
|
**⚠️ 警告**: 只有在完全理解安全影响时才禁用此功能
|
|
|
|
#### 禁用所有CSP修改
|
|
```json
|
|
{
|
|
"dangerousDisableAssetCspModification": true
|
|
}
|
|
```
|
|
|
|
#### 禁用特定指令的修改
|
|
```json
|
|
{
|
|
"dangerousDisableAssetCspModification": ["script-src", "style-src"]
|
|
}
|
|
```
|
|
|
|
### 2. `freezePrototype`
|
|
|
|
**类型**: `boolean`
|
|
**默认值**: `false`
|
|
**用途**: 冻结 `Object.prototype` 以防止原型污染攻击
|
|
|
|
```json
|
|
{
|
|
"freezePrototype": true
|
|
}
|
|
```
|
|
|
|
### 3. `pattern` - 安全模式
|
|
|
|
**类型**: `object`
|
|
**用途**: 定义应用的安全模式
|
|
|
|
#### Brownfield 模式 (默认)
|
|
```json
|
|
{
|
|
"pattern": {
|
|
"use": "brownfield"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Isolation 模式 (推荐)
|
|
```json
|
|
{
|
|
"pattern": {
|
|
"use": "isolation",
|
|
"options": {
|
|
"dir": "../dist-isolation"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 最佳实践建议
|
|
|
|
### 🔒 安全级别配置
|
|
|
|
#### 高安全级别 (推荐生产环境)
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 中等安全级别 (开发友好)
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
```
|
|
|
|
### 🎯 针对不同场景的配置
|
|
|
|
#### 媒体应用 (视频/音频)
|
|
```json
|
|
{
|
|
"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/**"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 文件管理应用
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
**解决方案**:
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
**解决方案**:
|
|
```json
|
|
{
|
|
"csp": {
|
|
"img-src": ["'self'", "asset:", "data:", "http://asset.localhost"]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 3. 内联样式被阻止
|
|
**错误**: `Refused to apply inline style because it violates CSP`
|
|
|
|
**解决方案**:
|
|
```json
|
|
{
|
|
"csp": {
|
|
"style-src": ["'self'", "'unsafe-inline'"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### AssetProtocol 故障排除
|
|
|
|
#### 1. 文件访问被拒绝
|
|
**错误**: `Asset protocol access denied`
|
|
|
|
**检查项目**:
|
|
- 确认 `assetProtocol.enable` 为 `true`
|
|
- 检查文件路径是否在 `scope` 范围内
|
|
- 验证文件是否存在且有读取权限
|
|
|
|
#### 2. Windows 路径问题
|
|
**问题**: Windows 绝对路径无法访问
|
|
|
|
**解决方案**:
|
|
```json
|
|
{
|
|
"assetProtocol": {
|
|
"enable": true,
|
|
"scope": [
|
|
"C:\\Users\\**",
|
|
"$APPDATA\\**",
|
|
"$LOCALAPPDATA\\**"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 配置验证工具
|
|
|
|
### 1. CSP 验证
|
|
使用浏览器开发者工具检查 CSP 违规:
|
|
```javascript
|
|
// 在控制台中检查 CSP 策略
|
|
console.log(document.querySelector('meta[http-equiv="Content-Security-Policy"]').content);
|
|
```
|
|
|
|
### 2. AssetProtocol 测试
|
|
```javascript
|
|
// 测试资源协议是否工作
|
|
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));
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 完整配置示例
|
|
|
|
### 视频编辑应用配置
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 文件管理器配置
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 参考资源
|
|
|
|
- [Tauri 官方安全文档](https://v2.tauri.app/security/)
|
|
- [MDN CSP 文档](https://developer.mozilla.org/docs/Web/HTTP/CSP)
|
|
- [Tauri 配置参考](https://v2.tauri.app/reference/config/)
|
|
- [CSP 评估工具](https://csp-evaluator.withgoogle.com/)
|
|
|
|
---
|
|
|
|
*最后更新: 2025-01-11*
|
|
*基于 Tauri CLI Schema v2.6.2*
|