buff/client-tauri/API_CONFIG_GUIDE.md

🔗 API地址配置指南

📋 配置概述

Client-Tauri客户端支持灵活的API地址配置，可以根据不同环境（开发/测试/生产）自动切换后端服务地址。

⚙️ 自动配置（推荐方式）

默认配置

客户端首次运行时会自动创建默认配置文件：

{
  "api": {
    "base_url": "http://localhost:8000",
    "timeout": 30,
    "software_code": "buff-xp-steam-sh"
  },
  "security": {
    "encryption_enabled": true,
    "key_rotation_days": 10,
    "heartbeat_interval": 30
  }
}

配置文件位置

• Windows: %APPDATA%\BuffClient\config.json
• macOS: ~/Library/Application Support/BuffClient/config.json
• Linux: ~/.local/share/BuffClient/config.json

🔧 配置参数说明

API配置

参数	类型	默认值	说明
base_url	string	"http://localhost:8000"	后端API服务器地址
timeout	number	30	请求超时时间（秒）
software_code	string	"buff-xp-steam-sh"	软件标识码（与后端约定）

安全配置

参数	类型	默认值	说明
encryption_enabled	boolean	true	是否启用数据加密
key_rotation_days	number	10	密钥轮换周期（天）
heartbeat_interval	number	30	心跳检测间隔（秒）

🚀 配置方法

方法1：自动生成（推荐）

# 首次运行客户端，会自动创建默认配置
npm run tauri:dev
# 或
npm run tauri:build

方法2：手动创建配置文件

# Windows
mkdir "%APPDATA%\BuffClient"
copy "default-config.json" "%APPDATA%\BuffClient\config.json"

# macOS
mkdir -p "~/Library/Application Support/BuffClient"
cp "default-config.json" "~/Library/Application Support/BuffClient/config.json"

# Linux
mkdir -p "~/.local/share/BuffClient"
cp "default-config.json" "~/.local/share/BuffClient/config.json"

方法3：运行时修改（推荐用于生产环境）

// 在前端界面中调用
await window.__TAURI__.invoke('update_api_url', {
  newUrl: 'https://your-production-api.com'
});

🌍 不同环境的配置示例

开发环境

{
  "api": {
    "base_url": "http://localhost:8000",
    "timeout": 30,
    "software_code": "buff-xp-steam-sh"
  }
}

测试环境

{
  "api": {
    "base_url": "http://test-api.example.com",
    "timeout": 60,
    "software_code": "buff-xp-steam-sh"
  }
}

生产环境

{
  "api": {
    "base_url": "https://api.buff-client.com",
    "timeout": 30,
    "software_code": "buff-xp-steam-sh"
  }
}

🔍 验证配置

检查配置文件

# 查看当前配置
cat "$(配置文件路径)/config.json"

测试API连接

# 启动客户端，查看日志输出
npm run tauri:dev

前端验证

// 获取当前API配置
const config = await window.__TAURI__.invoke('get_app_config');
console.log('当前API地址:', config.api.base_url);

⚠️ 注意事项

1. HTTPS推荐: 生产环境建议使用HTTPS
2. 备份配置: 修改配置前建议备份原文件
3. 权限问题: 确保配置文件目录有写入权限
4. 热重载: 修改配置后需要重启客户端生效

🛠️ 故障排除

配置文件不存在

# 手动创建配置目录并复制默认配置
mkdir -p "$(配置目录)"
cp "default-config.json" "$(配置目录)/config.json"

配置格式错误

# 验证JSON格式
cat config.json | python -m json.tool

API连接失败

1. 检查 base_url 是否正确
2. 确认后端服务是否运行
3. 查看客户端日志了解详细错误

📞 技术支持

如果配置过程中遇到问题，请：

1. 检查配置文件格式是否正确
2. 确认后端API服务是否可访问
3. 查看客户端日志获取错误详情