omnAPP/DOMAIN_CONFIGURATION.md

# 🌐 域名配置指南

## 📍 域名配置位置

域名配置主要在以下文件中：

```
lib/app/common/app_config.dart
├── KRDomain 类 - 域名管理
│   ├── kr_baseDomains - 主域名列表
│   ├── kr_currentDomain - 当前域名
│   ├── kr_backupDomainUrls - 备用域名获取地址
│   └── kr_localBackupDomains - 本地备用域名
└── AppConfig 类 - 应用配置
    └── baseUrl - 动态生成的API地址
```

## 🔧 域名配置详解

### 1. 主域名列表配置

```dart
// 文件: lib/app/common/app_config.dart
class KRDomain {
  // 主域名列表 - 应用会按顺序尝试这些域名
  static List<String> kr_baseDomains = [
    "apicn.bearvpn.top",      // 主域名1
    "apibear.nsdsox.com"      // 主域名2
  ];
}
```

**修改方法：**
1. 将 `"apicn.bearvpn.top"` 替换为您的API服务器域名
2. 将 `"apibear.nsdsox.com"` 替换为您的备用API服务器域名
3. 可以添加更多域名，应用会按顺序尝试

### 2. 当前域名配置

```dart
// 当前使用的域名
static String kr_currentDomain = "apicn.bearvpn.top";
```

**修改方法：**
- 将 `"apicn.bearvpn.top"` 替换为您希望应用启动时使用的默认域名
- 通常设置为 `kr_baseDomains` 列表中的第一个域名

### 3. 备用域名获取地址

```dart
// 备用域名获取地址列表
static List<String> kr_backupDomainUrls = [
  "https://bear-1347601445.cos.ap-guangzhou.myqcloud.com/bear.txt",
  "https://getbr.oss-cn-shanghai.aliyuncs.com/bear.txt",
  "https://gitee.com/karelink/getbr/raw/master/README.en.md",
  "https://configfortrans.oss-cn-guangzhou.aliyuncs.com/bear/bear.txt",
];
```

**修改方法：**
- 将这些URL替换为您自己的备用域名获取地址
- 这些地址应该返回包含可用域名列表的JSON数据
- 格式示例：`["api1.yourcompany.com", "api2.yourcompany.com"]`

### 4. 本地备用域名

```dart
// 本地备用域名列表（当服务器获取的域名都不可用时使用）
static List<String> kr_localBackupDomains = [
  "api.omntech.com",
  "api6.omntech.com", 
  "api7.omntech.com",
  "apicn.bearvpn.top",
  "apibear.nsdsox.com",
];
```

**修改方法：**
- 将这些域名替换为您自己的备用域名
- 这些是最后的兜底方案，当所有其他方式都失败时使用

## 🚀 域名切换机制

### 自动域名切换流程

1. **应用启动时**：使用 `kr_currentDomain` 作为默认域名
2. **主域名检测**：按顺序检测 `kr_baseDomains` 中的域名
3. **备用域名获取**：如果主域名都不可用，从 `kr_backupDomainUrls` 获取新域名
4. **本地备用**：如果备用域名获取失败，使用 `kr_localBackupDomains`
5. **兜底方案**：如果所有域名都失败，使用硬编码的兜底域名

### 域名检测逻辑

```dart
// 域名可用性检测
static Future<bool> kr_checkDomainAvailability(String domain) async {
  // 发送HTTPS请求检测域名是否可用
  // 只要能够连接就认为域名可用（包括404、403等状态码）
}
```

## 📝 配置示例

### 示例1：使用自己的API服务器

```dart
class KRDomain {
  // 主域名列表
  static List<String> kr_baseDomains = [
    "api.yourcompany.com",           // 主API服务器
    "backup-api.yourcompany.com"     // 备用API服务器
  ];
  
  // 当前使用的域名
  static String kr_currentDomain = "api.yourcompany.com";
  
  // 备用域名获取地址
  static List<String> kr_backupDomainUrls = [
    "https://your-cdn.com/domains.json",
    "https://backup-server.com/api/domains"
  ];
  
  // 本地备用域名
  static List<String> kr_localBackupDomains = [
    "api.yourcompany.com",
    "backup-api.yourcompany.com",
    "emergency-api.yourcompany.com"
  ];
}
```

### 示例2：使用多个备用服务器

```dart
class KRDomain {
  // 主域名列表
  static List<String> kr_baseDomains = [
    "api1.yourcompany.com",
    "api2.yourcompany.com", 
    "api3.yourcompany.com"
  ];
  
  // 当前使用的域名
  static String kr_currentDomain = "api1.yourcompany.com";
  
  // 备用域名获取地址
  static List<String> kr_backupDomainUrls = [
    "https://cdn1.yourcompany.com/domains.txt",
    "https://cdn2.yourcompany.com/domains.txt",
    "https://github.com/yourcompany/domains/raw/main/domains.json"
  ];
  
  // 本地备用域名
  static List<String> kr_localBackupDomains = [
    "api1.yourcompany.com",
    "api2.yourcompany.com",
    "api3.yourcompany.com",
    "fallback.yourcompany.com"
  ];
}
```

## 🔍 调试域名配置

### 查看当前域名状态

```dart
// 在应用中使用以下代码查看域名状态
print('当前域名: ${KRDomain.kr_currentDomain}');
print('主域名列表: ${KRDomain.kr_baseDomains}');
print('API地址: ${AppConfig.getInstance().baseUrl}');
```

### 手动触发域名切换

```dart
// 手动触发域名切换
bool success = await KRDomain.kr_triggerFastSwitch();
if (success) {
  print('域名切换成功: ${KRDomain.kr_currentDomain}');
} else {
  print('域名切换失败');
}
```

### 测试域名可用性

```dart
// 测试特定域名的可用性
bool isAvailable = await KRDomain.kr_checkDomainAvailability("api.yourcompany.com");
print('域名可用性: $isAvailable');
```

## ⚠️ 注意事项

1. **域名格式**：确保域名格式正确，不要包含协议前缀（如 `https://`）
2. **备用地址**：备用域名获取地址应该返回有效的JSON格式数据
3. **测试**：修改域名后，建议在测试环境中验证配置是否正确
4. **缓存**：域名检测结果会被缓存，修改后可能需要重启应用
5. **网络**：确保所有配置的域名都能正常访问

## 🆘 常见问题

### Q: 如何添加新的API域名？
A: 在 `kr_baseDomains` 列表中添加新的域名即可。

### Q: 如何修改备用域名获取地址？
A: 修改 `kr_backupDomainUrls` 列表，确保地址返回有效的域名列表JSON。

### Q: 域名切换不生效怎么办？
A: 检查域名格式是否正确，确保域名可以正常访问，必要时重启应用。

### Q: 如何禁用自动域名切换？
A: 将 `kr_baseDomains` 设置为只包含一个域名，并确保该域名始终可用。

---

**💡 提示**: 修改域名配置后，建议运行 `flutter clean && flutter pub get` 重新构建项目。