637 lines
15 KiB
Markdown
637 lines
15 KiB
Markdown
# UUVPN API 端点配置指南
|
|
|
|
本文档详细说明如何配置 UUVPN 的 API 端点,包括 Android 和 iOS 平台的配置方法。
|
|
|
|
---
|
|
|
|
## 目录
|
|
|
|
- [API 配置概述](#api-配置概述)
|
|
- [配置字段说明](#配置字段说明)
|
|
- [Android 配置方法](#android-配置方法)
|
|
- [iOS 配置方法](#ios-配置方法)
|
|
- [测试与验证](#测试与验证)
|
|
- [常见问题](#常见问题)
|
|
|
|
---
|
|
|
|
## API 配置概述
|
|
|
|
UUVPN 需要配置一个远程 API 端点,用于获取服务器配置信息。该配置采用 JSON 格式,包含 V2Board 面板的 API 地址、支付链接、客服支持等信息。
|
|
|
|
### 配置 URL 格式
|
|
|
|
```
|
|
https://your-domain.com/api/config.php
|
|
```
|
|
|
|
### 配置返回格式
|
|
|
|
```json
|
|
{
|
|
"baseURL": "https://api.0008.uk/api/v1/",
|
|
"baseDYURL": "https://api.gooapis.com/api/vpnnodes.php",
|
|
"mainregisterURL": "https://lelian.app/#/register?code=",
|
|
"paymentURL": "https://your-payment-gateway.com/pay",
|
|
"telegramurl": "https://t.me/fastlink",
|
|
"kefuurl": "https://gooapis.com/fastlink/",
|
|
"websiteURL": "https://gooapis.com/fastlink/",
|
|
"crisptoken": "5546c6ea-4b1e-41bc-80e4-4b6648cbca76",
|
|
"banners": [
|
|
"https://image.gooapis.com/api/images/12-11-56.png",
|
|
"https://image.gooapis.com/api/images/12-44-57.png",
|
|
"https://image.gooapis.com/api/images/12-47-03.png"
|
|
],
|
|
"message": "OK",
|
|
"code": 1
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 配置字段说明
|
|
|
|
### 1. baseURL
|
|
|
|
- **类型**: String
|
|
- **必填**: 是
|
|
- **描述**: V2Board 面板的主要 API 端点
|
|
- **示例**: `https://api.0008.uk/api/v1/`
|
|
- **用途**: 所有与 V2Board 服务器的 API 请求都将基于此 URL,包括:
|
|
- 用户登录/注册
|
|
- 获取节点列表
|
|
- 获取订阅信息
|
|
- 用户信息管理
|
|
|
|
### 2. baseDYURL
|
|
|
|
- **类型**: String
|
|
- **必填**: 是
|
|
- **描述**: VPN 节点测试端点
|
|
- **示例**: `https://api.gooapis.com/api/vpnnodes.php`
|
|
- **用途**: 用于测试 VPN 节点的连通性和速度,通常用于应用内的节点测速功能
|
|
|
|
### 3. mainregisterURL
|
|
|
|
- **类型**: String
|
|
- **必填**: 是
|
|
- **描述**: 用户注册页面 URL(带邀请码参数)
|
|
- **示例**: `https://lelian.app/#/register?code=`
|
|
- **用途**: 引导用户注册,支持邀请码系统
|
|
- **注意**: URL 末尾需要保留 `code=` 参数,应用会自动填充邀请码
|
|
|
|
### 4. paymentURL
|
|
|
|
- **类型**: String
|
|
- **必填**: 是
|
|
- **描述**: 支付网关 URL
|
|
- **示例**: `https://your-payment-gateway.com/pay`
|
|
- **用途**:
|
|
- **正常模式** (URL 长度 > 3): 显示外部支付选项,启用订阅功能
|
|
- **审核模式** (URL 长度 ≤ 3): 隐藏外部支付,遵守 App Store 指南
|
|
- **iOS 重要说明**:
|
|
- 正常值: `https://payment.example.com/pay` (显示支付功能)
|
|
- 审核值: `xxx` 或 `xx` (隐藏支付功能,用于 App Store 审核)
|
|
|
|
### 5. telegramurl
|
|
|
|
- **类型**: String
|
|
- **必填**: 否
|
|
- **描述**: Telegram 支持频道/群组链接
|
|
- **示例**: `https://t.me/fastlink`
|
|
- **用途**: 提供用户 Telegram 客服支持入口
|
|
|
|
### 6. kefuurl
|
|
|
|
- **类型**: String
|
|
- **必填**: 否
|
|
- **描述**: 在线客服页面 URL
|
|
- **示例**: `https://gooapis.com/fastlink/`
|
|
- **用途**: 提供网页版在线客服入口
|
|
|
|
### 7. websiteURL
|
|
|
|
- **类型**: String
|
|
- **必填**: 否
|
|
- **描述**: 官方网站 URL
|
|
- **示例**: `https://gooapis.com/fastlink/`
|
|
- **用途**: 应用内关于页面或官网链接
|
|
|
|
### 8. crisptoken
|
|
|
|
- **类型**: String
|
|
- **必填**: 否
|
|
- **描述**: Crisp 聊天服务认证令牌
|
|
- **示例**: `5546c6ea-4b1e-41bc-80e4-4b6648cbca76`
|
|
- **用途**: 集成 Crisp 实时聊天功能
|
|
- **获取方式**: 在 [Crisp 官网](https://crisp.chat/) 注册后获取
|
|
|
|
### 9. banners
|
|
|
|
- **类型**: Array of Strings
|
|
- **必填**: 否
|
|
- **描述**: 首页横幅图片 URL 数组
|
|
- **示例**:
|
|
```json
|
|
[
|
|
"https://image.gooapis.com/api/images/12-11-56.png",
|
|
"https://image.gooapis.com/api/images/12-44-57.png"
|
|
]
|
|
```
|
|
- **用途**: 应用首页轮播图展示
|
|
- **建议尺寸**: 750x300 像素
|
|
- **格式支持**: PNG, JPG, WebP
|
|
|
|
### 10. message
|
|
|
|
- **类型**: String
|
|
- **必填**: 是
|
|
- **描述**: API 响应状态消息
|
|
- **示例**: `OK`
|
|
- **用途**: 标识配置请求是否成功
|
|
|
|
### 11. code
|
|
|
|
- **类型**: Integer
|
|
- **必填**: 是
|
|
- **描述**: API 响应状态码
|
|
- **示例**: `1` (成功) 或 `0` (失败)
|
|
- **用途**: 应用根据此字段判断配置是否有效
|
|
|
|
---
|
|
|
|
## Android 配置方法
|
|
|
|
### 方法一: 修改配置文件 (推荐)
|
|
|
|
1. **定位配置文件**
|
|
|
|
在 Android 项目中找到以下文件:
|
|
```
|
|
Android-kotlin-Code/app/src/main/java/com/xxx/xxx/config/ApiConfig.kt
|
|
```
|
|
|
|
2. **修改配置 URL**
|
|
|
|
找到 `configURL` 或类似的配置常量:
|
|
```kotlin
|
|
const val CONFIG_URL = "https://your-domain.com/api/config.php"
|
|
```
|
|
|
|
3. **重新编译 APK**
|
|
|
|
```bash
|
|
./gradlew app:assembleMeta-AlphaRelease
|
|
```
|
|
|
|
### 方法二: 动态配置
|
|
|
|
如果支持动态配置,可以在应用启动时请求配置 URL:
|
|
|
|
```kotlin
|
|
// 在 Application 或 MainActivity 中
|
|
ConfigManager.init(this, "https://your-domain.com/api/config.php")
|
|
```
|
|
|
|
### Android API 请求示例
|
|
|
|
```kotlin
|
|
// ApiService.kt
|
|
interface ApiService {
|
|
@GET
|
|
suspend fun getConfig(@Url url: String): Response<ConfigResponse>
|
|
}
|
|
|
|
data class ConfigResponse(
|
|
val baseURL: String,
|
|
val baseDYURL: String,
|
|
val mainregisterURL: String,
|
|
val paymentURL: String,
|
|
val telegramurl: String,
|
|
val kefuurl: String,
|
|
val websiteURL: String,
|
|
val crisptoken: String,
|
|
val banners: List<String>,
|
|
val message: String,
|
|
val code: Int
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## iOS 配置方法
|
|
|
|
### 方法一: 修改 StoreManager.swift (推荐)
|
|
|
|
1. **定位配置文件**
|
|
|
|
在 iOS 项目中找到:
|
|
```
|
|
iOS-SwiftUI-Code/ApplicationLibrary/Service/StoreManager.swift
|
|
```
|
|
|
|
2. **修改配置 URL**
|
|
|
|
找到 `configURL` 常量并修改:
|
|
```swift
|
|
public let configURL = "https://your-domain.com/api/config.php"
|
|
```
|
|
|
|
3. **重新编译应用**
|
|
|
|
在 Xcode 中按 `Cmd + B` 编译项目
|
|
|
|
### 方法二: 使用 Info.plist
|
|
|
|
1. **在 Info.plist 中添加配置**
|
|
|
|
```xml
|
|
<key>ConfigURL</key>
|
|
<string>https://your-domain.com/api/config.php</string>
|
|
```
|
|
|
|
2. **在代码中读取**
|
|
|
|
```swift
|
|
if let configURL = Bundle.main.infoDictionary?["ConfigURL"] as? String {
|
|
// 使用配置 URL
|
|
}
|
|
```
|
|
|
|
### iOS 网络请求示例
|
|
|
|
```swift
|
|
// StoreManager.swift
|
|
func fetchConfig() async throws -> ConfigResponse {
|
|
guard let url = URL(string: configURL) else {
|
|
throw URLError(.badURL)
|
|
}
|
|
|
|
var request = URLRequest(url: url)
|
|
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
|
|
request.addValue(Bundle.main.bundleIdentifier ?? "", forHTTPHeaderField: "bid")
|
|
request.addValue(appVersion, forHTTPHeaderField: "appver")
|
|
|
|
let (data, _) = try await URLSession.shared.data(for: request)
|
|
return try JSONDecoder().decode(ConfigResponse.self, from: data)
|
|
}
|
|
|
|
// 数据模型
|
|
struct ConfigResponse: Codable {
|
|
let baseURL: String
|
|
let baseDYURL: String
|
|
let mainregisterURL: String
|
|
let paymentURL: String
|
|
let telegramurl: String
|
|
let kefuurl: String
|
|
let websiteURL: String
|
|
let crisptoken: String
|
|
let banners: [String]
|
|
let message: String
|
|
let code: Int
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 测试与验证
|
|
|
|
### 测试配置地址
|
|
|
|
项目提供了测试配置地址供开发调试使用:
|
|
|
|
```
|
|
https://vungles.com/api/test/config
|
|
```
|
|
|
|
**测试账号**:
|
|
- 邮箱: `binance3980@gmail.com`
|
|
- 密码: `Tinkl123`
|
|
|
|
### 验证配置是否正确
|
|
|
|
1. **浏览器测试**
|
|
|
|
在浏览器中访问你的配置 URL,确认返回正确的 JSON 格式
|
|
|
|
2. **Postman 测试**
|
|
|
|
使用 Postman 发送 GET 请求,验证响应内容
|
|
|
|
3. **应用内测试**
|
|
|
|
- 启动应用
|
|
- 检查是否能正常加载首页横幅图
|
|
- 测试登录/注册功能
|
|
- 验证节点列表加载
|
|
|
|
### 错误排查
|
|
|
|
如果配置加载失败:
|
|
|
|
1. **检查 URL 是否正确**
|
|
```
|
|
https://your-domain.com/api/config.php
|
|
```
|
|
|
|
2. **检查 HTTPS 证书**
|
|
- 确保证书有效且未过期
|
|
- 使用可信 CA 签发的证书
|
|
|
|
3. **检查 JSON 格式**
|
|
- 使用 JSON 格式化工具验证
|
|
- 确保所有必填字段都存在
|
|
|
|
4. **检查 CORS 配置** (Web 端)
|
|
- 服务器需要配置正确的 CORS 头
|
|
|
|
---
|
|
|
|
## 部署配置服务器
|
|
|
|
### 方案一: 静态 JSON 文件 (推荐)
|
|
|
|
将配置 JSON 存储在 CDN 或对象存储服务:
|
|
|
|
1. **创建配置文件**
|
|
|
|
创建 `config.json`:
|
|
```json
|
|
{
|
|
"baseURL": "https://api.yourdomain.com/api/v1/",
|
|
"baseDYURL": "https://api.yourdomain.com/api/vpnnodes.php",
|
|
"mainregisterURL": "https://yourdomain.com/#/register?code=",
|
|
"paymentURL": "https://pay.yourdomain.com/",
|
|
"telegramurl": "https://t.me/yourchannel",
|
|
"kefuurl": "https://yourdomain.com/support/",
|
|
"websiteURL": "https://yourdomain.com/",
|
|
"crisptoken": "your-crisp-token",
|
|
"banners": [
|
|
"https://cdn.yourdomain.com/banner1.png"
|
|
],
|
|
"message": "OK",
|
|
"code": 1
|
|
}
|
|
```
|
|
|
|
2. **上传到对象存储**
|
|
|
|
- 阿里云 OSS
|
|
- 腾讯云 COS
|
|
- AWS S3
|
|
- Cloudflare R2
|
|
|
|
3. **启用 HTTPS**
|
|
|
|
确保存储桶启用 HTTPS 访问
|
|
|
|
### 方案二: 动态 API 接口
|
|
|
|
使用后端服务动态返回配置:
|
|
|
|
**PHP 示例**:
|
|
```php
|
|
<?php
|
|
// config.php
|
|
header('Content-Type: application/json');
|
|
|
|
$config = [
|
|
'baseURL' => 'https://api.yourdomain.com/api/v1/',
|
|
'baseDYURL' => 'https://api.yourdomain.com/api/vpnnodes.php',
|
|
'mainregisterURL' => 'https://yourdomain.com/#/register?code=',
|
|
'paymentURL' => 'https://pay.yourdomain.com/',
|
|
'telegramurl' => 'https://t.me/yourchannel',
|
|
'kefuurl' => 'https://yourdomain.com/support/',
|
|
'websiteURL' => 'https://yourdomain.com/',
|
|
'crisptoken' => 'your-crisp-token',
|
|
'banners' => [
|
|
'https://cdn.yourdomain.com/banner1.png',
|
|
'https://cdn.yourdomain.com/banner2.png'
|
|
],
|
|
'message' => 'OK',
|
|
'code' => 1
|
|
];
|
|
|
|
echo json_encode($config, JSON_PRETTY_PRINT);
|
|
?>
|
|
```
|
|
|
|
**Node.js 示例**:
|
|
```javascript
|
|
// config.js
|
|
const express = require('express');
|
|
const app = express();
|
|
|
|
app.get('/api/config', (req, res) => {
|
|
res.json({
|
|
baseURL: 'https://api.yourdomain.com/api/v1/',
|
|
baseDYURL: 'https://api.yourdomain.com/api/vpnnodes.php',
|
|
mainregisterURL: 'https://yourdomain.com/#/register?code=',
|
|
paymentURL: 'https://pay.yourdomain.com/',
|
|
telegramurl: 'https://t.me/yourchannel',
|
|
kefuurl: 'https://yourdomain.com/support/',
|
|
websiteURL: 'https://yourdomain.com/',
|
|
crisptoken: 'your-crisp-token',
|
|
banners: [
|
|
'https://cdn.yourdomain.com/banner1.png'
|
|
],
|
|
message: 'OK',
|
|
code: 1
|
|
});
|
|
});
|
|
|
|
app.listen(3000, () => {
|
|
console.log('Config server running on port 3000');
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 安全建议
|
|
|
|
### 1. 使用 HTTPS
|
|
|
|
- 所有 API 端点必须使用 HTTPS
|
|
- 使用可信 CA 签发的 SSL 证书
|
|
- 禁用 HTTP 访问
|
|
|
|
### 2. 请求验证
|
|
|
|
在请求头中添加验证信息:
|
|
|
|
```kotlin
|
|
// Android
|
|
request.addHeader("bid", BuildConfig.APPLICATION_ID)
|
|
request.addHeader("appver", BuildConfig.VERSION_NAME)
|
|
request.addHeader("device", android.os.Build.MODEL)
|
|
```
|
|
|
|
```swift
|
|
// iOS
|
|
request.addValue(Bundle.main.bundleIdentifier ?? "", forHTTPHeaderField: "bid")
|
|
request.addValue(appVersion, forHTTPHeaderField: "appver")
|
|
request.addValue(UIDevice.current.model, forHTTPHeaderField: "device")
|
|
```
|
|
|
|
### 3. 服务器端验证
|
|
|
|
在服务器端验证请求来源:
|
|
|
|
```php
|
|
<?php
|
|
$bid = $_SERVER['HTTP_BID'] ?? '';
|
|
$appver = $_SERVER['HTTP_APPVER'] ?? '';
|
|
|
|
// 验证 Bundle ID
|
|
$allowedBids = ['com.yourcompany.uuvpn', 'com.yourcompany.uuvpn.dev'];
|
|
if (!in_array($bid, $allowedBids)) {
|
|
http_response_code(403);
|
|
exit(json_encode(['code' => 0, 'message' => 'Unauthorized']));
|
|
}
|
|
|
|
// 返回配置
|
|
// ...
|
|
?>
|
|
```
|
|
|
|
### 4. 敏感信息保护
|
|
|
|
- 不要在配置文件中存储密钥或密码
|
|
- 使用 token 而非明文密码
|
|
- 定期更新 Crisp token
|
|
|
|
---
|
|
|
|
## iOS App Store 审核配置
|
|
|
|
### 审核模式配置
|
|
|
|
iOS 应用提交 App Store 审核时,需要隐藏外部支付链接:
|
|
|
|
```json
|
|
{
|
|
"baseURL": "https://api.yourdomain.com/api/v1/",
|
|
"baseDYURL": "https://api.yourdomain.com/api/vpnnodes.php",
|
|
"mainregisterURL": "https://yourdomain.com/#/register?code=",
|
|
"paymentURL": "xx",
|
|
"telegramurl": "https://t.me/yourchannel",
|
|
"kefuurl": "https://yourdomain.com/support/",
|
|
"websiteURL": "https://yourdomain.com/",
|
|
"crisptoken": "your-crisp-token",
|
|
"banners": [],
|
|
"message": "OK",
|
|
"code": 1
|
|
}
|
|
```
|
|
|
|
**关键点**:
|
|
- `paymentURL` 设置为 `"xx"` 或 `"xxx"` (长度 ≤ 3)
|
|
- `banners` 设置为空数组,避免显示包含支付信息的横幅
|
|
|
|
### 审核通过后配置
|
|
|
|
审核通过后,将配置改回正常模式:
|
|
|
|
```json
|
|
{
|
|
"paymentURL": "https://pay.yourdomain.com/",
|
|
"banners": [
|
|
"https://cdn.yourdomain.com/banner1.png"
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 常见问题
|
|
|
|
### Q1: 修改配置后应用没有更新怎么办?
|
|
|
|
**A**: 清除应用缓存或重新安装应用
|
|
|
|
**Android**:
|
|
```bash
|
|
adb shell pm clear com.yourcompany.uuvpn
|
|
```
|
|
|
|
**iOS**: 卸载重装应用
|
|
|
|
### Q2: 配置请求超时怎么办?
|
|
|
|
**A**: 检查以下内容:
|
|
- 服务器是否正常运行
|
|
- HTTPS 证书是否有效
|
|
- 网络连接是否正常
|
|
- 考虑使用 CDN 加速
|
|
|
|
### Q3: 如何在不重新编译的情况下更改配置?
|
|
|
|
**A**: 配置是从远程 URL 动态获取的,只需修改服务器端的配置 JSON 即可,应用会在下次启动时自动获取最新配置
|
|
|
|
### Q4: 能否使用多个配置 URL?
|
|
|
|
**A**: 可以,通过在不同的编译变体中使用不同的配置 URL:
|
|
|
|
**Android**:
|
|
```kotlin
|
|
object ApiConfig {
|
|
val CONFIG_URL = when (BuildConfig.BUILD_TYPE) {
|
|
"debug" -> "https://dev.yourdomain.com/api/config.php"
|
|
"release" -> "https://yourdomain.com/api/config.php"
|
|
else -> "https://yourdomain.com/api/config.php"
|
|
}
|
|
}
|
|
```
|
|
|
|
**iOS**:
|
|
```swift
|
|
#if DEBUG
|
|
let configURL = "https://dev.yourdomain.com/api/config.php"
|
|
#else
|
|
let configURL = "https://yourdomain.com/api/config.php"
|
|
#endif
|
|
```
|
|
|
|
### Q5: 配置加载失败应用会崩溃吗?
|
|
|
|
**A**: 不会,应用应该有默认配置作为后备:
|
|
|
|
```kotlin
|
|
// Android
|
|
fun getConfig(): ConfigResponse {
|
|
return try {
|
|
apiService.getConfig(configURL)
|
|
} catch (e: Exception) {
|
|
// 返回默认配置
|
|
getDefaultConfig()
|
|
}
|
|
}
|
|
```
|
|
|
|
```swift
|
|
// iOS
|
|
func loadConfig() async {
|
|
do {
|
|
config = try await fetchConfig()
|
|
} catch {
|
|
// 使用默认配置
|
|
config = getDefaultConfig()
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 总结
|
|
|
|
配置 API 端点是 UUVPN 应用的核心步骤,正确的配置能确保应用正常工作:
|
|
|
|
1. ✅ 准备好 V2Board 服务器
|
|
2. ✅ 创建配置 JSON 文件
|
|
3. ✅ 部署到 HTTPS 服务器
|
|
4. ✅ 在应用中配置 URL
|
|
5. ✅ 测试验证配置
|
|
6. ✅ 针对iOS审核特殊处理
|
|
|
|
如有问题,请参考 [GitHub Issues](https://github.com/nicolastinkl/UUVPN/issues) 或联系技术支持。
|