节点自动升级功能之前的版本

2026-03-02 23:42:55 +08:00
parent 2a76d1773d
commit 853897a6f8
29 changed files with 1063 additions and 81 deletions
--- a/集成文档（Android）.md
+++ b/集成文档（Android）.md
@@ -0,0 +1,165 @@
+# HTTPDNS SDK 集成文档（Android）
+
+## 1. 版本与依赖
+
+- SDK 模块：`EdgeHttpDNS/sdk/android/httpdns-sdk`
+- `minSdkVersion`：19
+- `targetSdkVersion`：33
+- `compileSdk`：33
+
+将发布包中的 `jar/aar` 放到应用模块 `libs/`，在 `app/build.gradle` 中添加：
+
+```gradle
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+}
+```
+
+## 2. SNI 行为说明（关键）
+
+当前 SDK 行为与代码一致：
+
+1. `/resolve` 请求链路（SDK -> 你的 HTTPDNS 服务域名）
+- 走域名 HTTPS
+- 默认 TLS 行为（会带 SNI）
+
+2. 业务请求链路（拿到 CDN IP 后发起业务 HTTPS）
+- 使用 `HttpDnsHttpAdapter`：按 IP 建连，`Host` 保留原域名，并清空 SNI（No-SNI）
+
+## 3. 初始化 SDK（推荐用 V1 客户端）
+
+### Kotlin
+
+```kotlin
+import com.new.sdk.android.httpdns.HttpDnsV1Client
+import com.new.sdk.android.httpdns.HttpDnsService
+
+val service: HttpDnsService = HttpDnsV1Client.init(
+    context = applicationContext,
+    appId = "your-app-id",
+    primaryServiceHost = "httpdns.example.com",
+    backupServiceHost = "httpdns-backup.example.com", // 可空字符串
+    servicePort = 443,
+    signSecret = "your-sign-secret" // 可空字符串
+)
+```
+
+### Java
+
+```java
+import com.new.sdk.android.httpdns.HttpDnsService;
+import com.new.sdk.android.httpdns.HttpDnsV1Client;
+
+HttpDnsService service = HttpDnsV1Client.init(
+        getApplicationContext(),
+        "your-app-id",
+        "httpdns.example.com",
+        "httpdns-backup.example.com", // 可传 ""
+        443,
+        "your-sign-secret" // 可传 ""
+);
+```
+
+## 4. 解析域名获取 CDN IP
+
+### Kotlin
+
+```kotlin
+import com.new.sdk.android.httpdns.HTTPDNSResult
+
+val result: HTTPDNSResult = HttpDnsV1Client.resolveHost(
+    service = service,
+    host = "api.example.com",
+    qtype = "A",   // "A" 或 "AAAA"
+    cip = null      // 可选，客户端 IP 透传
+)
+
+val ips = result.ips ?: emptyArray()
+```
+
+### Java
+
+```java
+import com.new.sdk.android.httpdns.HTTPDNSResult;
+
+HTTPDNSResult result = HttpDnsV1Client.resolveHost(
+        service,
+        "api.example.com",
+        "A",
+        null
+);
+
+String[] ips = result.getIps();
+```
+
+## 5. 业务请求接入方式
+
+#使用 `HttpDnsHttpAdapter`（IP 直连 + No-SNI）
+
+业务请求侧做“隐匿 SNI”。该适配器仅支持 HTTPS URL。
+
+```kotlin
+import com.new.sdk.android.httpdns.HttpDnsV1Client
+import com.new.sdk.android.httpdns.network.HttpDnsAdapterOptions
+import com.new.sdk.android.httpdns.network.HttpDnsAdapterRequest
+
+val adapter = HttpDnsV1Client.buildHttpClientAdapter(
+    service,
+    HttpDnsAdapterOptions.Builder()
+        .setConnectTimeoutMillis(3000)
+        .setReadTimeoutMillis(5000)
+        .setRequestIpType(com.new.sdk.android.httpdns.RequestIpType.auto)
+        .build()
+)
+
+val req = HttpDnsAdapterRequest(
+    "GET",
+    "https://api.example.com/path?x=1"
+)
+
+val resp = adapter.execute(req)
+val code = resp.statusCode
+val bodyBytes = resp.body
+val usedIp = resp.usedIp
+```
+
+## 6. 预解析与常用接口
+
+```kotlin
+service.setPreResolveHosts(listOf("api.example.com", "img.example.com"))
+
+val r1 = service.getHttpDnsResultForHostSync("api.example.com", com.new.sdk.android.httpdns.RequestIpType.auto)
+val r2 = service.getHttpDnsResultForHostSyncNonBlocking("api.example.com", com.new.sdk.android.httpdns.RequestIpType.auto)
+```
+
+- `Sync`：允许阻塞等待刷新结果（上限受 timeout 等配置影响）
+- `NonBlocking`：快速返回当前可用缓存/结果，不阻塞等待
+
+## 7. 验证建议
+
+1. 验证 `/resolve`
+- 抓包看目标应为 `https://<serviceHost>:<servicePort>/resolve...`
+
+2. 验证业务请求（若使用 `HttpDnsHttpAdapter`）
+- 目标地址应是 CDN IP
+- HTTP `Host` 应为原域名
+- TLS ClientHello 不应携带 SNI（No-SNI）
+
+## 8. 混淆配置
+
+```proguard
+-keep class com.new.sdk.android.** { *; }
+```
+
+## 9. 常见问题
+
+1. HTTPDNS 没生效
+- 检查是否真正使用了 SDK 返回 IP（或用了 `HttpDnsHttpAdapter`）
+- 检查失败回退逻辑是否总是直接走了系统 DNS
+
+2. 使用 `HttpDnsHttpAdapter` 仍失败
+- 只支持 HTTPS URL
+
+3. 线上不要开启不安全证书
+- `HttpDnsAdapterOptions.Builder#setAllowInsecureCertificatesForDebugOnly(true)` 仅限调试环境