From 866938abab4d7b4eb2d09af3ae58b64c123f0313 Mon Sep 17 00:00:00 2001 From: Rust Date: Tue, 23 Sep 2025 16:33:58 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONFIGURATION_GUIDE.md | 300 +++++++++++++++++++++++++++++++++++ DOMAIN_CONFIGURATION.md | 219 +++++++++++++++++++++++++ PROJECT_STRUCTURE.md | 343 ++++++++++++++++++++++++++++++++++++++++ QUICK_REFERENCE.md | 187 ++++++++++++++++++++++ 4 files changed, 1049 insertions(+) create mode 100644 CONFIGURATION_GUIDE.md create mode 100644 DOMAIN_CONFIGURATION.md create mode 100644 PROJECT_STRUCTURE.md create mode 100644 QUICK_REFERENCE.md diff --git a/CONFIGURATION_GUIDE.md b/CONFIGURATION_GUIDE.md new file mode 100644 index 0000000..a9210d4 --- /dev/null +++ b/CONFIGURATION_GUIDE.md @@ -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` → `` 标签 + +### 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` 重新构建项目。** diff --git a/DOMAIN_CONFIGURATION.md b/DOMAIN_CONFIGURATION.md new file mode 100644 index 0000000..c1de734 --- /dev/null +++ b/DOMAIN_CONFIGURATION.md @@ -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` 重新构建项目。 diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..f7085fd --- /dev/null +++ b/PROJECT_STRUCTURE.md @@ -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 +``` + +#### 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日 diff --git a/QUICK_REFERENCE.md b/QUICK_REFERENCE.md new file mode 100644 index 0000000..2e1dc59 --- /dev/null +++ b/QUICK_REFERENCE.md @@ -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 kr_baseDomains = [ + "your-api-domain.com", // 替换为您的API域名 + "backup-api-domain.com" // 备用API域名 + ]; + + // 2. 修改当前使用的域名 + static String kr_currentDomain = "your-api-domain.com"; + + // 3. 修改备用域名获取地址（可选） + static List kr_backupDomainUrls = [ + "https://your-backup-server.com/domains.txt", + // 添加更多备用地址 + ]; + + // 4. 修改本地备用域名（可选） + static List 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` 重新构建项目。