admin/UUVPN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5b044334ee262df529c39e21142d15e7a0d962cd
UUVPN/API配置指南.md
T

15 KiB
Raw Blame History

UUVPN API 端点配置指南

本文档详细说明如何配置 UUVPN 的 API 端点,包括 Android 和 iOS 平台的配置方法。

目录

API 配置概述

UUVPN 需要配置一个远程 API 端点,用于获取服务器配置信息。该配置采用 JSON 格式,包含 V2Board 面板的 API 地址、支付链接、客服支持等信息。

配置 URL 格式

https://your-domain.com/api/config.php

配置返回格式

{
  "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 官网 注册后获取

9. banners

  • 类型: Array of Strings
  • 必填: 否
  • 描述: 首页横幅图片 URL 数组
  • 示例: 
    [
  "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 或类似的配置常量:

    const val CONFIG_URL = "https://your-domain.com/api/config.php"

  3. 重新编译 APK

    ./gradlew app:assembleMeta-AlphaRelease

方法二: 动态配置

如果支持动态配置,可以在应用启动时请求配置 URL:

// 在 Application 或 MainActivity 中
ConfigManager.init(this, "https://your-domain.com/api/config.php")

Android API 请求示例

// 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 常量并修改:

    public let configURL = "https://your-domain.com/api/config.php"

  3. 重新编译应用

    在 Xcode 中按 Cmd + B 编译项目

方法二: 使用 Info.plist

  1. 在 Info.plist 中添加配置

    <key>ConfigURL</key>
<string>https://your-domain.com/api/config.php</string>

  2. 在代码中读取

    if let configURL = Bundle.main.infoDictionary?["ConfigURL"] as? String {
    // 使用配置 URL
}

iOS 网络请求示例

// 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:

    {
  "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
// 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 示例:

// 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. 请求验证

在请求头中添加验证信息:

// Android
request.addHeader("bid", BuildConfig.APPLICATION_ID)
request.addHeader("appver", BuildConfig.VERSION_NAME)
request.addHeader("device", android.os.Build.MODEL)

// iOS
request.addValue(Bundle.main.bundleIdentifier ?? "", forHTTPHeaderField: "bid")
request.addValue(appVersion, forHTTPHeaderField: "appver")
request.addValue(UIDevice.current.model, forHTTPHeaderField: "device")

3. 服务器端验证

在服务器端验证请求来源:

<?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 审核时,需要隐藏外部支付链接:

{
  "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 设置为空数组,避免显示包含支付信息的横幅

审核通过后配置

审核通过后,将配置改回正常模式:

{
  "paymentURL": "https://pay.yourdomain.com/",
  "banners": [
    "https://cdn.yourdomain.com/banner1.png"
  ]
}

常见问题

Q1: 修改配置后应用没有更新怎么办?

A: 清除应用缓存或重新安装应用

Android:

adb shell pm clear com.yourcompany.uuvpn

iOS: 卸载重装应用

Q2: 配置请求超时怎么办?

A: 检查以下内容:

  • 服务器是否正常运行
  • HTTPS 证书是否有效
  • 网络连接是否正常
  • 考虑使用 CDN 加速

Q3: 如何在不重新编译的情况下更改配置?

A: 配置是从远程 URL 动态获取的,只需修改服务器端的配置 JSON 即可,应用会在下次启动时自动获取最新配置

Q4: 能否使用多个配置 URL?

A: 可以,通过在不同的编译变体中使用不同的配置 URL:

Android:

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:

#if DEBUG
let configURL = "https://dev.yourdomain.com/api/config.php"
#else
let configURL = "https://yourdomain.com/api/config.php"
#endif

Q5: 配置加载失败应用会崩溃吗?

A: 不会,应用应该有默认配置作为后备:

// Android
fun getConfig(): ConfigResponse {
    return try {
        apiService.getConfig(configURL)
    } catch (e: Exception) {
        // 返回默认配置
        getDefaultConfig()
    }
}

// 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 或联系技术支持。

Reference in New Issue View Git Blame Copy Permalink