Client/omnAPP
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

新增文档
Some checks failed
Build Windows / build (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Rust 2025-09-23 16:33:58 +08:00
parent 877b18a70f
commit 866938abab
4 changed files with 1049 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

300
CONFIGURATION_GUIDE.md Normal file
View File

@ -0,0 +1,300 @@
# BearVPN 配置修改指南
## 🎯 快速开始
在开始开发之前，您需要修改以下关键配置文件以适配您的项目。
## 📋 必须修改的配置
### 1. 🏷️ 应用基本信息
#### **pubspec.yaml** - 项目基础配置
```yaml
# 位置: /pubspec.yaml
name: bearvpn # 修改为您的应用名称
description: A VPN application # 修改为您的应用描述
version: 1.0.0+1 # 修改版本号
```
#### **应用显示名称**
- **iOS**: `/ios/Runner/Info.plist` → `CFBundleDisplayName`
- **macOS**: `/macos/Runner/Configs/AppInfo.xcconfig` → `PRODUCT_NAME`
- **Android**: `/android/app/src/main/res/values/strings.xml` → `app_name`
- **Web**: `/web/index.html` → `<title>` 标签
### 2. 🆔 包标识符 (Bundle ID)
#### **iOS 配置**
```bash
# 文件: /ios/Base.xcconfig
BASE_BUNDLE_IDENTIFIER=com.yourcompany.yourapp
# 文件: /ios/Runner/Info.plist
<key>CFBundleIdentifier</key>
<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
```
#### **macOS 配置**
```bash
# 文件: /macos/Runner/Configs/AppInfo.xcconfig
PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.yourapp
```
#### **Android 配置**
```gradle
// 文件: /android/app/build.gradle
android {
defaultConfig {
applicationId "com.yourcompany.yourapp"
}
}
```
### 3. 🔐 签名和证书配置
#### **iOS 签名配置**
```bash
# 文件: ios_signing_config.sh
export APPLE_ID="your-apple-id@example.com" # 您的 Apple ID
export APPLE_PASSWORD="your-app-specific-password" # App 专用密码
export TEAM_ID="YOUR_TEAM_ID" # 您的团队 ID
export BUNDLE_ID="com.yourcompany.yourapp" # 包标识符
export SIGNING_IDENTITY="Mac Developer: Your Name (YOUR_TEAM_ID)"
export DISTRIBUTION_IDENTITY="Developer ID Application: Your Name (YOUR_TEAM_ID)"
```
#### **macOS 签名配置**
```bash
# 文件: macos_signing_config.sh
export APPLE_ID="your-apple-id@example.com" # 您的 Apple ID
export APPLE_PASSWORD="your-app-specific-password" # App 专用密码
export TEAM_ID="YOUR_TEAM_ID" # 您的团队 ID
export SIGNING_IDENTITY="Developer ID Application: Your Company Name (YOUR_TEAM_ID)"
```
### 4. 🎨 应用图标和资源
#### **应用图标位置**
```
assets/images/logo.svg # 主 Logo
ios/Runner/Assets.xcassets/AppIcon.appiconset/ # iOS 图标
macos/Runner/Assets.xcassets/AppIcon.appiconset/ # macOS 图标
android/app/src/main/res/mipmap-*/ # Android 图标
web/icons/ # Web 图标
```
#### **图标尺寸要求**
- **iOS**: 20x20, 29x29, 40x40, 58x58, 60x60, 76x76, 80x80, 87x87, 120x120, 152x152, 167x167, 180x180, 1024x1024
- **Android**: 48x48, 72x72, 96x96, 144x144, 192x192, 512x512
- **macOS**: 16x16, 32x32, 64x64, 128x128, 256x256, 512x512, 1024x1024
### 5. 🌍 多语言配置
#### **添加新语言**
1. 在 `assets/translations/` 目录下创建新的 JSON 文件
2. 文件命名格式: `strings_[语言代码].i18n.json`
3. 在 `lib/app/utils/` 中添加语言支持
#### **修改现有翻译**
```json
// 文件: assets/translations/strings_zh.i18n.json
{
"appName": "您的应用名称",
"welcome": "欢迎使用",
// ... 其他翻译
}
```
### 6. 🔧 构建配置
#### **Android 构建配置**
```gradle
// 文件: /android/app/build.gradle
android {
compileSdk 34 // 编译 SDK 版本
defaultConfig {
applicationId "com.yourcompany.yourapp"
minSdkVersion 21 // 最低支持版本
targetSdkVersion 34 // 目标版本
versionCode 1 // 版本代码
versionName "1.0.0" // 版本名称
}
}
```
#### **iOS 构建配置**
```bash
# 文件: /ios/Runner/Info.plist
<key>CFBundleShortVersionString</key>
<string>1.0.0</string> # 版本号
<key>CFBundleVersion</key>
<string>1</string> # 构建号
```
### 7. 🌐 网络配置
#### **域名配置** ⭐ 重要
```dart
// 文件: lib/app/common/app_config.dart
class KRDomain {
// 主域名列表 - 修改这里来更改API服务器域名
static List<String> kr_baseDomains = [
"apicn.bearvpn.top", // 主域名1
"apibear.nsdsox.com" // 主域名2
];
// 当前使用的域名
static String kr_currentDomain = "apicn.bearvpn.top";
// 备用域名获取地址列表
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",
];
// 本地备用域名列表（当服务器获取的域名都不可用时使用）
static List<String> kr_localBackupDomains = [
"api.omntech.com",
"api6.omntech.com",
"api7.omntech.com",
"apicn.bearvpn.top",
"apibear.nsdsox.com",
];
}
```
#### **API 端点配置**
```dart
// 文件: lib/app/services/api_service/api.dart
// API 路径定义，通常不需要修改
abstract class Api {
static const String kr_isRegister = "/v1/app/auth/check";
static const String kr_register = "/v1/app/auth/register";
static const String kr_login = "/v1/app/auth/login";
// ... 其他API路径
}
```
#### **VPN 服务器配置**
```dart
// 文件: lib/app/services/singbox_imp/kr_sing_box_imp.dart
// 修改服务器配置和连接参数
```
## 🚀 部署配置
### 1. **iOS App Store 部署**
```bash
# 1. 配置签名
source ios_signing_config.sh
# 2. 构建 App Store 版本
./build_ios_appstore.sh
# 3. 上传到 App Store Connect
xcrun altool --upload-app -f BearVPN.ipa -u $APPLE_ID -p $APPLE_PASSWORD
```
### 2. **macOS 公证和分发**
```bash
# 1. 配置签名
source macos_signing_config.sh
# 2. 构建和签名
./sign_and_package.sh
# 3. 公证
./notarize_only.sh
# 4. 装订票据
xcrun stapler staple BearVPN-1.0.0-macOS-Signed.dmg
```
### 3. **Android 发布**
```bash
# 1. 生成签名密钥
keytool -genkey -v -keystore android/app/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload
# 2. 配置签名
# 编辑 android/key.properties
storePassword=your_store_password
keyPassword=your_key_password
keyAlias=upload
storeFile=upload-keystore.jks
# 3. 构建发布版本
flutter build apk --release
```
## 🔍 调试配置
### 1. **日志配置**
```dart
// 文件: lib/app/utils/kr_log_util.dart
class KRLogUtil {
static const bool DEBUG = true; // 生产环境设为 false
// ... 日志配置
}
```
### 2. **网络调试**
```bash
# 使用调试脚本
./debug_connection.sh
./test_connection.sh
```
## 📱 平台特定配置
### **iOS 权限配置**
```xml
<!-- 文件: /ios/Runner/Info.plist -->
<key>NSCameraUsageDescription</key>
<string>需要相机权限以支持拍照功能</string>
<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限以支持语音消息功能</string>
```
### **Android 权限配置**
```xml
<!-- 文件: /android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```
### **macOS 权限配置**
```xml
<!-- 文件: /macos/Runner/DebugProfile.entitlements -->
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.network.server</key>
<true/>
```
## ⚠️ 重要注意事项
1. **敏感信息**: 所有敏感信息已替换为占位符，使用前必须修改
2. **证书管理**: 确保所有签名证书有效且未过期
3. **版本同步**: 更新版本时同步修改所有平台的版本号
4. **测试**: 在发布前在所有目标平台进行充分测试
5. **备份**: 修改配置前建议备份原始文件
## 🆘 常见问题
### Q: 如何获取 Apple Developer 证书？
A: 登录 [Apple Developer Portal](https://developer.apple.com)，在 Certificates 部分创建新的证书。
### Q: 如何获取 App 专用密码？
A: 登录 [Apple ID 管理页面](https://appleid.apple.com)，在 App-Specific Passwords 部分生成。
### Q: 如何修改应用图标？
A: 替换对应平台的图标文件，确保尺寸符合要求。
### Q: 如何添加新的语言支持？
A: 在 `assets/translations/` 目录下添加新的 JSON 文件，并在代码中添加语言支持。
---
**配置完成后，请运行 `flutter clean && flutter pub get` 重新构建项目。**

219
DOMAIN_CONFIGURATION.md Normal file
View File

@ -0,0 +1,219 @@
# 🌐 域名配置指南
## 📍 域名配置位置
域名配置主要在以下文件中：
```
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` 重新构建项目。

343
PROJECT_STRUCTURE.md Normal file
View File

@ -0,0 +1,343 @@
# BearVPN 项目结构说明
## 📁 项目概览
这是一个基于 Flutter 的跨平台 VPN 应用项目，支持 iOS、macOS、Android、Windows、Linux 和 Web 平台。
## 🗂️ 目录结构
```
OmnAPP/
├── 📱 核心源代码
│ ├── lib/ # Dart 源代码目录
│ │ ├── main.dart # 应用入口点
│ │ ├── app/ # 应用核心模块
│ │ │ ├── modules/ # 功能模块
│ │ │ │ ├── kr_home/ # 首页模块
│ │ │ │ ├── kr_user_info/ # 用户信息模块
│ │ │ │ ├── kr_setting/ # 设置模块
│ │ │ │ ├── kr_statistics/ # 统计模块
│ │ │ │ ├── kr_webview/ # WebView 模块
│ │ │ │ └── kr_splash/ # 启动页模块
│ │ │ ├── services/ # 服务层
│ │ │ ├── routes/ # 路由配置
│ │ │ ├── themes/ # 主题配置
│ │ │ ├── utils/ # 工具类
│ │ │ └── widgets/ # 通用组件
│ │ ├── core/ # 核心功能
│ │ ├── features/ # 功能特性
│ │ ├── singbox/ # SingBox 集成
│ │ └── utils/ # 工具函数
│ │
│ ├── assets/ # 资源文件
│ │ ├── images/ # 图片资源
│ │ ├── fonts/ # 字体文件
│ │ └── translations/ # 多语言文件
│ │
│ └── libcore/ # 核心库文件
│ └── bin/ # 二进制文件
│
├── 🍎 iOS 平台
│ ├── ios/
│ │ ├── Runner/ # iOS 应用配置
│ │ │ ├── Info.plist # 应用信息配置
│ │ │ └── Assets.xcassets/ # 应用图标和资源
│ │ ├── PacketTunnel/ # 网络扩展
│ │ ├── Flutter/ # Flutter 配置
│ │ └── Podfile # CocoaPods 依赖
│ │
├── 🖥️ macOS 平台
│ ├── macos/
│ │ ├── Runner/ # macOS 应用配置
│ │ │ ├── Configs/ # 配置文件
│ │ │ │ ├── AppInfo.xcconfig # 应用信息
│ │ │ │ ├── Signing.xcconfig # 签名配置
│ │ │ │ ├── Debug.xcconfig # 调试配置
│ │ │ │ └── Release.xcconfig # 发布配置
│ │ │ ├── Info.plist # 应用信息
│ │ │ └── Assets.xcassets/ # 应用图标
│ │ ├── Flutter/ # Flutter 配置
│ │ └── Podfile # CocoaPods 依赖
│ │
├── 🤖 Android 平台
│ ├── android/
│ │ ├── app/
│ │ │ ├── src/main/
│ │ │ │ ├── AndroidManifest.xml # Android 清单文件
│ │ │ │ ├── kotlin/ # Kotlin 代码
│ │ │ │ └── res/ # Android 资源
│ │ │ └── build.gradle # 应用构建配置
│ │ ├── build.gradle # 项目构建配置
│ │ └── gradle.properties # Gradle 属性
│ │
├── 🪟 Windows 平台
│ ├── windows/
│ │ ├── runner/ # Windows 应用配置
│ │ └── CMakeLists.txt # CMake 配置
│ │
├── 🐧 Linux 平台
│ ├── linux/
│ │ ├── runner/ # Linux 应用配置
│ │ └── CMakeLists.txt # CMake 配置
│ │
├── 🌐 Web 平台
│ ├── web/
│ │ ├── index.html # Web 入口文件
│ │ ├── manifest.json # Web 应用清单
│ │ └── icons/ # Web 图标
│ │
├── 🔧 构建脚本
│ ├── build_ios.sh # iOS 构建脚本
│ ├── build_ios_appstore.sh # iOS App Store 构建
│ ├── build_ios_dmg.sh # iOS DMG 打包
│ ├── build_macos_dmg.sh # macOS DMG 打包
│ ├── build_macos_simple.sh # macOS 简单构建
│ ├── create_dmg.sh # DMG 创建脚本
│ └── create_dmg_with_installer.sh # 带安装脚本的 DMG
│ │
├── 🔐 签名和公证脚本
│ ├── ios_signing_config.sh # iOS 签名配置
│ ├── macos_signing_config.sh # macOS 签名配置
│ ├── sign_and_package.sh # 签名和打包
│ ├── sign_and_notarize.sh # 签名和公证
│ ├── notarize_only.sh # 仅公证脚本
│ ├── notarize_async.sh # 异步公证
│ ├── complete_notarization.sh # 完成公证
│ └── check_notarization_status.sh # 检查公证状态
│ │
├── 🛠️ 工具脚本
│ ├── debug_connection.sh # 连接调试
│ ├── test_connection.sh # 连接测试
│ ├── install_bearvpn.sh # 安装脚本
│ ├── get_team_id.sh # 获取团队 ID
│ └── update_team_id.sh # 更新团队 ID
│ │
└── 📄 配置文件
├── pubspec.yaml # Flutter 项目配置
├── analysis_options.yaml # Dart 分析配置
├── .gitignore # Git 忽略文件
├── README.md # 项目说明
└── PROJECT_STRUCTURE.md # 项目结构说明（本文件）
```
## ⚙️ 重要配置文件说明
### 🔧 核心配置
#### 1. **pubspec.yaml** - Flutter 项目配置
```yaml
# 位置: /pubspec.yaml
# 用途: 定义项目依赖、版本、资源等
# 修改内容:
name: your_app_name # 应用名称
description: Your app description # 应用描述
version: 1.0.0+1 # 版本号
dependencies: # 依赖包
flutter: sdk: '>=3.19.0' # Flutter SDK 版本
```
#### 2. **main.dart** - 应用入口
```dart
// 位置: /lib/main.dart
// 用途: 应用启动入口，初始化配置
// 修改内容: 应用初始化逻辑、全局配置
```
#### 3. **app_config.dart** - 域名和网络配置 ⭐ 重要
```dart
// 位置: /lib/app/common/app_config.dart
// 用途: API 域名、网络配置、应用配置
// 修改内容:
class KRDomain {
// 主域名列表 - 修改这里来更改API服务器域名
static List<String> kr_baseDomains = [
"apicn.bearvpn.top", // 主域名1
"apibear.nsdsox.com" // 主域名2
];
// 当前使用的域名
static String kr_currentDomain = "apicn.bearvpn.top";
// 备用域名获取地址列表
static List<String> kr_backupDomainUrls = [
"https://your-backup-server.com/domains.txt",
// 更多备用地址...
];
}
```
### 🍎 iOS 配置
#### 1. **Info.plist** - iOS 应用信息
```xml
<!-- 位置: /ios/Runner/Info.plist -->
<!-- 用途: iOS 应用基本信息和权限 -->
<!-- 修改内容: -->
<key>CFBundleDisplayName</key>
<string>Your App Name</string> <!-- 应用显示名称 -->
<key>CFBundleIdentifier</key>
<string>com.yourcompany.yourapp</string> <!-- 包标识符 -->
```
#### 2. **Base.xcconfig** - iOS 基础配置
```bash
# 位置: /ios/Base.xcconfig
# 用途: iOS 构建基础配置
# 修改内容:
BASE_BUNDLE_IDENTIFIER=com.yourcompany.yourapp # 包标识符
```
### 🖥️ macOS 配置
#### 1. **AppInfo.xcconfig** - macOS 应用信息
```bash
# 位置: /macos/Runner/Configs/AppInfo.xcconfig
# 用途: macOS 应用基本信息
# 修改内容:
PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.yourapp # 包标识符
PRODUCT_NAME = Your App Name # 应用名称
```
#### 2. **Signing.xcconfig** - macOS 签名配置
```bash
# 位置: /macos/Runner/Configs/Signing.xcconfig
# 用途: macOS 代码签名配置
# 修改内容:
CODE_SIGN_IDENTITY = Developer ID Application: Your Company Name (XXXXXXXXXX)
DEVELOPMENT_TEAM = XXXXXXXXXX
```
### 🤖 Android 配置
#### 1. **build.gradle** - Android 构建配置
```gradle
// 位置: /android/app/build.gradle
// 用途: Android 应用构建配置
// 修改内容:
android {
compileSdk 34 // 编译 SDK 版本
defaultConfig {
applicationId "com.yourcompany.yourapp" // 应用 ID
minSdkVersion 21 // 最低 SDK 版本
targetSdkVersion 34 // 目标 SDK 版本
}
}
```
#### 2. **AndroidManifest.xml** - Android 清单文件
```xml
<!-- 位置: /android/app/src/main/AndroidManifest.xml -->
<!-- 用途: Android 应用权限和组件声明 -->
<!-- 修改内容: -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.yourcompany.yourapp"> <!-- 包名 -->
```
### 🌐 Web 配置
#### 1. **index.html** - Web 入口文件
```html
<!-- 位置: /web/index.html -->
<!-- 用途: Web 应用入口页面 -->
<!-- 修改内容: -->
<title>Your App Name</title> <!-- 页面标题 -->
```
#### 2. **manifest.json** - Web 应用清单
```json
// 位置: /web/manifest.json
// 用途: Web 应用 PWA 配置
// 修改内容:
{
"name": "Your App Name", // 应用名称
"short_name": "YourApp", // 短名称
"start_url": "/", // 启动 URL
"display": "standalone" // 显示模式
}
```
## 🔐 签名和公证配置
### 1. **iOS 签名配置**
```bash
# 文件: ios_signing_config.sh
# 用途: iOS 应用签名配置
# 修改内容:
export APPLE_ID="your-apple-id@example.com" # Apple ID
export APPLE_PASSWORD="your-app-specific-password" # App 专用密码
export TEAM_ID="YOUR_TEAM_ID" # 团队 ID
export BUNDLE_ID="com.yourcompany.yourapp" # 包标识符
```
### 2. **macOS 签名配置**
```bash
# 文件: macos_signing_config.sh
# 用途: macOS 应用签名配置
# 修改内容:
export APPLE_ID="your-apple-id@example.com" # Apple ID
export APPLE_PASSWORD="your-app-specific-password" # App 专用密码
export TEAM_ID="YOUR_TEAM_ID" # 团队 ID
export SIGNING_IDENTITY="Developer ID Application: Your Name (YOUR_TEAM_ID)"
```
## 🌍 多语言配置
### 翻译文件位置
```
assets/translations/
├── strings_zh.i18n.json # 简体中文
├── strings_zh_Hant.i18n.json # 繁体中文
├── strings_en.i18n.json # 英文
├── strings_ja.i18n.json # 日文
├── strings_es.i18n.json # 西班牙文
├── strings_ru.i18n.json # 俄文
└── strings_et.i18n.json # 爱沙尼亚文
```
## 🚀 构建和部署
### 1. **Flutter 构建命令**
```bash
# 构建所有平台
flutter build apk # Android APK
flutter build ios # iOS
flutter build macos # macOS
flutter build windows # Windows
flutter build linux # Linux
flutter build web # Web
```
### 2. **使用构建脚本**
```bash
# iOS 构建
./build_ios.sh
# macOS 构建
./build_macos_simple.sh
# 签名和打包
./sign_and_package.sh
# 公证
./notarize_only.sh
```
## 📝 开发注意事项
1. **敏感信息**: 所有敏感信息已替换为占位符，使用前请修改为实际值
2. **包标识符**: 确保所有平台的包标识符一致
3. **签名证书**: 需要有效的 Apple Developer 证书
4. **版本管理**: 更新版本时同步修改所有配置文件
5. **多语言**: 添加新语言时更新所有翻译文件
## 🔗 相关文档
- [Flutter 官方文档](https://flutter.dev/docs)
- [iOS 开发指南](https://developer.apple.com/ios/)
- [macOS 开发指南](https://developer.apple.com/macos/)
- [Android 开发指南](https://developer.android.com/)
- [Web 开发指南](https://web.dev/)
---
**最后更新**: 2024年9月23日

187
QUICK_REFERENCE.md Normal file
View File

@ -0,0 +1,187 @@
# BearVPN 快速参考
## 🚀 快速开始
### 1. 克隆项目后立即修改
```bash
# 1. 修改应用名称
# 文件: pubspec.yaml
name: your_app_name
# 2. 修改包标识符
# iOS: ios/Base.xcconfig
BASE_BUNDLE_IDENTIFIER=com.yourcompany.yourapp
# macOS: macos/Runner/Configs/AppInfo.xcconfig
PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.yourapp
# Android: android/app/build.gradle
applicationId "com.yourcompany.yourapp"
# 3. 配置签名信息
# 文件: ios_signing_config.sh 和 macos_signing_config.sh
export APPLE_ID="your-apple-id@example.com"
export TEAM_ID="YOUR_TEAM_ID"
```
## 📁 关键文件位置
| 配置项 | 文件位置 | 说明 |
|--------|----------|------|
| 应用名称 | `pubspec.yaml` | 项目基础配置 |
| **API 域名** | `lib/app/common/app_config.dart` | **API 服务器域名** |
| iOS 包名 | `ios/Base.xcconfig` | iOS 包标识符 |
| macOS 包名 | `macos/Runner/Configs/AppInfo.xcconfig` | macOS 包标识符 |
| Android 包名 | `android/app/build.gradle` | Android 应用 ID |
| iOS 签名 | `ios_signing_config.sh` | iOS 签名配置 |
| macOS 签名 | `macos_signing_config.sh` | macOS 签名配置 |
| 多语言 | `assets/translations/` | 翻译文件目录 |
| 应用图标 | `assets/images/logo.svg` | 主 Logo |
## 🔧 常用命令
### Flutter 命令
```bash
# 安装依赖
flutter pub get
# 清理项目
flutter clean
# 构建各平台
flutter build apk # Android
flutter build ios # iOS
flutter build macos # macOS
flutter build windows # Windows
flutter build web # Web
```
### 构建脚本
```bash
# iOS 构建
./build_ios.sh
# macOS 构建
./build_macos_simple.sh
# 签名和打包
./sign_and_package.sh
# 公证
./notarize_only.sh
```
## 🎨 图标尺寸
| 平台 | 尺寸 | 位置 |
|------|------|------|
| iOS | 1024x1024 | `ios/Runner/Assets.xcassets/AppIcon.appiconset/` |
| macOS | 1024x1024 | `macos/Runner/Assets.xcassets/AppIcon.appiconset/` |
| Android | 512x512 | `android/app/src/main/res/mipmap-xxxhdpi/` |
| Web | 512x512 | `web/icons/Icon-512.png` |
## 🌍 支持的语言
- 🇨🇳 简体中文 (`strings_zh.i18n.json`)
- 🇹🇼 繁体中文 (`strings_zh_Hant.i18n.json`)
- 🇺🇸 英文 (`strings_en.i18n.json`)
- 🇯🇵 日文 (`strings_ja.i18n.json`)
- 🇪🇸 西班牙文 (`strings_es.i18n.json`)
- 🇷🇺 俄文 (`strings_ru.i18n.json`)
- 🇪🇪 爱沙尼亚文 (`strings_et.i18n.json`)
## ⚠️ 必须修改的占位符
| 占位符 | 说明 | 文件位置 |
|--------|------|----------|
| `apicn.bearvpn.top` | **API 主域名** | `lib/app/common/app_config.dart` |
| `apibear.nsdsox.com` | **API 备用域名** | `lib/app/common/app_config.dart` |
| `xxxxxxxx@example.com` | Apple ID | 所有签名脚本 |
| `xxxxxxxxxxxxxxxx` | App 专用密码 | 所有签名脚本 |
| `XXXXXXXXXX` | Team ID | 所有签名脚本 |
| `Your Company Name` | 公司名称 | 签名配置 |
| `Your Name` | 开发者姓名 | 签名配置 |
| `com.yourcompany.yourapp` | 包标识符 | 所有平台配置 |
## 🌐 域名配置详解
### 修改 API 服务器域名
```dart
// 文件: lib/app/common/app_config.dart
class KRDomain {
// 1. 修改主域名列表
static List<String> kr_baseDomains = [
"your-api-domain.com", // 替换为您的API域名
"backup-api-domain.com" // 备用API域名
];
// 2. 修改当前使用的域名
static String kr_currentDomain = "your-api-domain.com";
// 3. 修改备用域名获取地址（可选）
static List<String> kr_backupDomainUrls = [
"https://your-backup-server.com/domains.txt",
// 添加更多备用地址
];
// 4. 修改本地备用域名（可选）
static List<String> kr_localBackupDomains = [
"api.yourcompany.com",
"backup.yourcompany.com",
// 添加更多本地备用域名
];
}
```
### 域名配置说明
- **主域名列表**: 应用会按顺序尝试这些域名
- **当前域名**: 应用启动时使用的默认域名
- **备用域名地址**: 当主域名都不可用时，从这些地址获取新的域名列表
- **本地备用域名**: 最后的兜底方案，当所有其他方式都失败时使用
## 🔐 签名流程
### iOS 签名
1. 修改 `ios_signing_config.sh`
2. 运行 `source ios_signing_config.sh`
3. 运行 `./build_ios.sh`
### macOS 签名
1. 修改 `macos_signing_config.sh`
2. 运行 `source macos_signing_config.sh`
3. 运行 `./sign_and_package.sh`
## 📱 平台支持
| 平台 | 状态 | 构建脚本 |
|------|------|----------|
| iOS | ✅ | `build_ios.sh` |
| macOS | ✅ | `build_macos_simple.sh` |
| Android | ✅ | `flutter build apk` |
| Windows | ✅ | `flutter build windows` |
| Linux | ✅ | `flutter build linux` |
| Web | ✅ | `flutter build web` |
## 🆘 故障排除
### 常见问题
1. **签名失败**: 检查证书是否有效
2. **构建失败**: 运行 `flutter clean && flutter pub get`
3. **公证失败**: 检查 Apple ID 和密码
4. **图标不显示**: 检查图标文件路径和尺寸
### 调试命令
```bash
# 检查连接
./debug_connection.sh
# 测试连接
./test_connection.sh
# 检查公证状态
./check_notarization_status.sh
```
---
**💡 提示**: 修改配置后记得运行 `flutter clean && flutter pub get` 重新构建项目。