zyc123/Aiapi-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: zyc123:85bae5665f1311bd12f183edf05a24d826472294
Branches Tags
zyc123:main
..
compare: zyc123:73c40ffadcc3f5b053b085d1c761df485a90d84c
Branches Tags
zyc123:main

No commits in common. "85bae5665f1311bd12f183edf05a24d826472294" and "73c40ffadcc3f5b053b085d1c761df485a90d84c" have entirely different histories.
85bae5665f ... 73c40ffadc

3 changed files with 391 additions and 368 deletions
Show Stats Expand all files Collapse all files

1
apps/alma.md
View File

@ -1,4 +1,3 @@
# Alma 客户端配置指南
**功能强大的 AI 编程客户端工具**

276
apps/cherry-studio.md
View File

@ -2,64 +2,60 @@
**全能的 AI 助手桌面客户端**
| 资源 | 地址 |
|------|------|
| 官方网站 | [cherry-ai.com](https://www.cherry-ai.com/) |
| 下载地址 | [cherry-ai.com/download](https://www.cherry-ai.com/download) |
| oneinAI 控制台 | [api.oneinai.com/console/token](https://api.oneinai.com/console/token) |
> **官方网站** ：<https://www.cherry-ai.com/>**下载地址** ：<https://www.cherry-ai.com/download>
## 📋 简介
📋 简介
CherryStudio 是一款功能强大的 AI 助手桌面应用，支持 Claude、Gemini、GPT 等主流 AI 模型，为开发者和用户提供统一的 AI 交互界面。本教程将指导你如何配置 CherryStudio 接入 **oneinAI** 平台。
CherryStudio 是一款功能强大的 AI 助手桌面应用，支持多种主流 AI 模型（Claude、Gemini、GPT 等），为开发者和用户提供统一的 AI 交互界面。本教程将指导你如何配置 CherryStudio 接入 IkunCode 平台。
## ✨ 功能特点
- ✅ **多模型支持**：Claude、Gemini、GPT 等主流 AI 模型
- ✅ **统一界面**：一个应用管理所有 AI 服务
- ✅ **自定义 API**：支持接入自定义 API 提供商
- ✅ **跨平台**：支持 Windows、macOS、Linux
- ✅ **本地优先**：数据存储在本地，保护隐私
- ✅ **丰富功能**：对话管理、模型切换、参数调整等
CherryStudio 提供以下强大功能：
## 📋 配置快速参考
| 模型 | 提供商类型 | API 地址 | 令牌组 |
|------|-----------|---------|--------|
| Claude | `Anthropic` | `https://api.oneinai.com` | Claude 分组 |
| Gemini | `Gemini` | `https://api.oneinai.com/v1beta/models` | Gemini 分组 |
---
* ✅ **多模型支持** ：支持 Claude、Gemini、GPT 等主流 AI 模型
* ✅ **统一界面** ：一个应用管理所有 AI 服务
* ✅ **自定义 API** ：支持接入自定义 API 提供商
* ✅ **跨平台** ：支持 Windows、macOS、Linux
* ✅ **本地优先** ：数据存储在本地，保护隐私
* ✅ **丰富功能** ：对话管理、模型切换、参数调整等
## 🛠️ 安装步骤
### 第一步：下载安装 CherryStudio
1. 访问 [CherryStudio 下载页面](https://www.cherry-ai.com/download)
1. 访问 [CherryStudio 下载页面](<https://www.cherry-ai.com/download>)
2. 根据你的操作系统选择对应的安装包：
- **Windows**：下载 `.exe` 安装程序
- **macOS**：下载 `.dmg` 镜像文件
- **Linux**：下载 `.AppImage` 或 `.deb` 包
* **Windows** ：下载 `.exe` 安装程序
* **macOS** ：下载 `.dmg` 镜像文件
* **Linux** ：下载 `.AppImage` 或 `.deb` 包
3. 下载完成后，按照系统提示完成安装
> 💡 **macOS 用户注意**
> 如果提示"无法打开，因为它来自身份不明的开发者"，请在系统偏好设置 → 安全性与隐私中允许打开。
💡 macOS 用户注意
### 第二步：获取 oneinAI API Key
如果提示"无法打开，因为它来自身份不明的开发者"，请在系统偏好设置 → 安全性与隐私中允许打开。
在配置 CherryStudio 之前，需要先从 oneinAI 平台获取 API Key：
### 第二步：获取 OneinAI API Key
1. 访问 [oneinAI 控制台](https://api.oneinai.com/console/token)
在配置 CherryStudio 之前，需要先从 IkunCode 平台获取 API Key：
1. 访问 [OneinAI 控制台](<https://api.oneinai.com/console/token>)
2. 登录你的账户
3. 根据需要创建对应的令牌组：
- **Claude 模型**：选择 Claude 分组
- **Gemini 模型**：选择 Gemini 分组
4. 保存生成的 API Key（请妥善保管，不要泄露）
* **Claude 模型** ：选择 Claude分组
* **Gemini 模型** ：选择 Gemini分组
![创建 API Key](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio01.png)
![Claude](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio01.png)
> ⚠️ Claude 和 Gemini 的 API Key 必须使用**不同的令牌组**，两者不能通用。
4. 保存生成的 API Key
---
📋 配置快速参考
模型| 提供商类型| API 地址| 令牌组
---|---|---|---
Claude| `Anthropic`| `https://api.oneinai.com/v1/messages`| Claude分组
Gemini| `Gemini`| `https://api.oneinai.com/v1beta/models`| Gemini分组
## 🔧 配置 Claude 模型
@ -71,57 +67,52 @@ CherryStudio 是一款功能强大的 AI 助手桌面应用，支持 Claude、Ge
### 第二步：选择 Claude 模型类型
![Claude 类型选择](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio02.png)
![Claude 类型选择](https://docs.ikuncode.cc/images/apps/CherryStudio/claudeleixing.png)
在模型列表中选择你需要的 Claude 模型。
在模型列表中选择你需要的 Claude 模型
### 第三步：配置 Claude API
在 Claude 配置界面中填写以下信息：
![Claude 配置界面](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio03.png)
![Claude 配置界面](https://docs.ikuncode.cc/images/apps/CherryStudio/claude.png)
**配置参数：**
**配置参数** ：
| 字段 | 填写内容 |
|------|---------|
| 提供商类型 | `Anthropic` |
| API 地址 | `https://api.oneinai.com` |
| API Key | 从 [oneinAI 控制台](https://api.oneinai.com/console/token) 获取的 Claude API Key |
| 模型名称 | 例如 `claude-sonnet-4-6`、`claude-opus-4-5-20251101` |
---
* **提供商类型** ：选择 `Anthropic`
* **API 地址** ：`https://api.oneinai.com`
* **API Key** ：粘贴你从 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 获取的 Claude API Key
* **模型名称** ：输入上一步选择的模型名称（如 `claude-sonnet-4-6`）
## 🔧 配置 Gemini 模型
### 第一步：选择 Gemini 模型类型
![Gemini 类型选择](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio04.png)
![Gemini 类型选择](https://docs.ikuncode.cc/images/apps/CherryStudio/geminileixing.png)
在模型列表中选择你需要的 Gemini 模型：
- **Gemini 3 Flash Preview**：`gemini-3-flash-preview` — 最新版本，速度快，性能优秀（推荐）
- **Gemini 3 Pro Preview**：`gemini-3-pro-preview` — 高性能，适合复杂任务
- **Gemini 2.0 Flash**：快速响应，适合简单对话
* **Gemini 3 Flash Preview** ：`gemini-3-flash-preview` \- 最新版本，速度快，性能优秀（推荐）
* **Gemini 3 Pro Preview** ：`gemini-3-pro-preview` \- 高性能，适合复杂任务
* **Gemini 2.0 Flash** ：快速响应，适合简单对话
⚠️ 注意
* Gemini 和 Claude 需要使用不同的 API Key（不同的令牌组）
* 确保你在 IkunCode 平台创建了对应的令牌组
### 第二步：配置 Gemini API
在 Gemini 配置界面中填写以下信息：
![Gemini 配置界面](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio05.png)
![Gemini 配置界面](https://docs.ikuncode.cc/images/apps/CherryStudio/gemini.png)
**配置参数：**
**配置参数** ：
| 字段 | 填写内容 |
|------|---------|
| 提供商类型 | `Gemini` |
| API 地址 | `https://api.oneinai.com/v1beta/models` |
| API Key | 从 [oneinAI 控制台](https://api.oneinai.com/console/token) 获取的 Gemini API Key |
| 模型名称 | 例如 `gemini-3-flash-preview` |
> ⚠️ **注意**：Gemini 和 Claude 需要使用不同的 API Key（不同的令牌组），确保你在 oneinAI 平台已创建对应的令牌组。
---
* **提供商类型** ：选择 `Gemini`
* **API 地址** ：`https://api.oneinai.com/v1beta/models`
* **API Key** ：粘贴你从 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 获取的 Gemini API Key
* **模型名称** ：输入上一步选择的模型名称（如 `gemini-3-flash-preview`）
## 💬 开始使用
@ -143,140 +134,135 @@ CherryStudio 是一款功能强大的 AI 助手桌面应用，支持 Claude、Ge
CherryStudio 通常支持调整以下参数：
- **Temperature**（温度）：控制回复的随机性（0-1）
- **Max Tokens**（最大令牌数）：控制回复长度
- **Top P**：控制采样范围
* **Temperature** （温度）：控制回复的随机性（0-1）
* **Max Tokens** （最大令牌数）：控制回复长度
* **Top P** ：控制采样范围
> 💡 **参数建议**
> - 编程任务：Temperature `0.2-0.5`（更准确）
> - 创意写作：Temperature `0.7-0.9`（更有创意）
> - 日常对话：Temperature `0.5-0.7`（平衡）
💡 参数建议
---
* 编程任务：Temperature 0.2-0.5（更准确）
* 创意写作：Temperature 0.7-0.9（更有创意）
* 日常对话：Temperature 0.5-0.7（平衡）
## 🎯 最佳实践
### 1. 合理选择模型
### 1\. 合理选择模型
不同任务使用不同模型：
| 任务类型 | 推荐模型 | 模型标识 |
|---------|---------|---------|
| 代码编写 | Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` |
| 快速对话 | Gemini 3 Flash Preview | `gemini-3-flash-preview` |
| 复杂推理 | Claude Opus 4.5 | `claude-opus-4-5-20251101` |
| 多模态（图片） | Gemini 3 Pro Preview | `gemini-3-pro-preview` |
* **代码编写** ：Claude Sonnet 4.5（`claude-sonnet-4-5-20250929`）
* **快速对话** ：Gemini 3 Flash Preview（`gemini-3-flash-preview`）
* **复杂推理** ：Claude Opus 4.5（`claude-opus-4-5-20251101`）
* **多模态任务** ：Gemini 3 Pro Preview（支持图片）
### 2. 管理 API 使用
### 2\. 管理 API 使用
- 定期检查 [oneinAI 控制台](https://api.oneinai.com/console/token) 的余额
- 为不同用途创建不同的 API Key，便于管理和审计
- 避免在公共场合或代码仓库中泄露 API Key
* 定期检查 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 的余额
* 为不同用途创建不同的 API Key
* 避免在公共场合泄露 API Key
### 3. 优化对话体验
### 3\. 优化对话体验
- 使用清晰、具体的提示词
- 合理设置上下文长度，避免过长影响响应速度
- 善用对话历史管理功能，及时归档或清理
---
* 使用清晰的提示词
* 合理设置上下文长度
* 善用对话历史管理功能
## 🔍 与其他客户端的对比
| 特性 | CherryStudio | Alma | Hapi |
|------|:------------:|:----:|:----:|
| 界面类型 | 桌面应用 | 桌面应用 | Web/PWA |
| 多模型支持 | ✅ | ✅ | ✅ |
| 代码编辑 | 部分支持 | ✅ | ✅ |
| 终端集成 | ❌ | ✅ | ✅ |
| 远程访问 | ❌ | ❌ | ✅ |
| 学习曲线 | 低 | 中 | 中 |
特性| CherryStudio| Alma| Hapi
---|---|---|---
界面类型| 桌面应用| 桌面应用| Web/PWA
多模型支持| ✅| ✅| ✅
代码编辑| 部分支持| ✅| ✅
终端集成| ❌| ✅| ✅
远程访问| ❌| ❌| ✅
学习曲线| 低| 中| 中
**选择建议：**
**选择建议** ：
- **纯对话需求**：CherryStudio（界面简洁，易上手）
- **编程开发**：Alma 或 Hapi（功能更强大）
- **远程控制**：Hapi（独有功能）
* **纯对话需求** ：CherryStudio（界面简洁，易上手）
* **编程开发** ：Alma 或 Hapi（功能更强大）
* **远程控制** ：Hapi（独有功能）
---
## ❓ 常见问题
## 常见问题
### 提示 API Key 无效？
**可能原因：**
**可能原因** ：
- API Key 输入错误或前后有空格
- 令牌组选择错误（Claude 的 Key 不能用于 Gemini，反之亦然）
- 账户余额不足
* API Key 输入错误
* 令牌组选择错误（只允许逆向分组的 Key 不能用于 Gemini）
* 余额不足
**解决方法：**
**解决方法** ：
1. 重新复制 API Key，确保完整且无多余空格
2. 在 [oneinAI 控制台](https://api.oneinai.com/console/token) 确认创建了正确的令牌组
1. 检查 API Key 是否完整复制
2. 确认在 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 创建了正确的令牌组（Claude 用 只允许逆向分组，Gemini 用 gemini分组）
3. 查看账户余额是否充足
### 模型列表为空？
**可能原因：**
**可能原因** ：
- Base URL 配置错误
- 网络连接问题
- API Key 权限不足
* Base URL 配置错误
* 网络连接问题
* API Key 权限不足
**解决方法：**
**解决方法** ：
1. 确认 Claude 的 API 地址为 `https://api.oneinai.com`
1. 确认 Claude 的 API 地址为 `https://api.oneinai.com/v1/messages`
2. 确认 Gemini 的 API 地址为 `https://api.oneinai.com/v1beta/models`
3. 检查网络连接是否正常
4. 重新获取 API Key 并确认令牌组权限正确
3. 检查网络连接
4. 重新获取 API Key 并确保令牌组权限正确
### 对话响应速度慢？
**可能原因：**
**可能原因** ：
- 网络延迟
- 选择的模型较大（如 Opus 系列）
- 上下文过长
* 网络延迟
* 选择的模型较大
* 上下文过长
**解决方法：**
**解决方法** ：
1. 检查网络连接质量
2. 尝试使用更快的模型（如 Gemini Flash 或 Claude Haiku）
3. 清理或缩短对话历史
2. 尝试使用更快的模型（如 Gemini Flash）
3. 清理或减少对话历史
### 如何同时使用多个模型？
1. 在设置中分别配置不同的模型提供商
在 CherryStudio 中：
1. 分别配置不同的模型提供商
2. 在新建对话时选择对应的模型
3. 也可以创建多个对话窗口，每个使用不同模型
3. 可以创建多个对话窗口，每个使用不同模型
### 更多问题
- [oneinAI 控制台](https://api.oneinai.com/console/token)
- [oneinAI FAQ](/support/faq)
- [售后支持](/support/after-sales)
- [CherryStudio 官方文档](https://www.cherry-ai.com/)
请查看：
---
* [IkunCode 控制台](<https://api.oneinai.com/console/token>)
* [IkunCode FAQ](</support/faq>)
* [售后支持](</support/after-sales>)
* [CherryStudio 官方文档](<https://www.cherry-ai.com/>)
## ✅ 完成
🎉 **配置完成！现在你可以使用 CherryStudio 愉快地与 AI 对话了！**
**核心要点回顾：**
记住以下要点：
- ✅ Claude 与 Gemini 必须使用**不同的 API Key**（不同令牌组）
- ✅ Claude API 地址：`https://api.oneinai.com`
- ✅ Gemini API 地址：`https://api.oneinai.com/v1beta/models`
- ✅ 根据任务特性选择合适的模型
- ✅ 定期检查 [oneinAI 控制台](https://api.oneinai.com/console/token) 的余额
- ✅ 妥善保管你的 API Key，避免泄露
* ✅ 不同模型使用不同的 API Key（不同令牌组）
* ✅ Claude API 地址：`https://api.oneinai.com/v1/messages`
* ✅ Gemini API 地址：`https://api.oneinai.com/v1beta/models`
* ✅ 根据任务选择合适的模型
* ✅ 定期检查 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 的余额
* ✅ 妥善保管你的 API Key
---
* * *
**相关教程：**
**相关教程** ：
- [Alma 客户端配置](/apps/alma)
- [Hapi 远程控制](/apps/hapi)
- [oneinAI 控制台](https://api.oneinai.com/console/token)
* [Alma 客户端配置](</apps/alma>)
* [Hapi 远程控制](</apps/hapi>)
* [IkunCode 控制台](<https://api.oneinai.com/console/token>)

250
apps/hapi-advanced.md
View File

@ -2,49 +2,50 @@
**没有公网 IP？使用 Cloudflare 优选 IP，打造高速内网穿透通道**
> **适用场景**：已配置 Cloudflare Tunnel，但访问速度慢、延迟高
> **解决方案**：利用 Cloudflare for SaaS + 优选 IP 服务，绕过拥堵节点
> **前置要求**：已完成 [Hapi 基础配置](/apps/hapi)，并拥有两个域名
> **适用场景** ：已配置 Cloudflare Tunnel，但访问速度慢、延迟高 **解决方案** ：利用 Cloudflare for SaaS + 优选 IP 服务，绕过拥堵节点 **前置要求** ：已完成 [Hapi 基础配置](</apps/hapi>)，拥有两个域名
## 📺 视频教程
推荐先观看视频：[没有公网 IP？Cloudflare 优选 IP，高速内网穿透 - 哔哩哔哩](https://www.bilibili.com/video/BV1PPy6YzE5C)
推荐观看
视频完整演示了配置过程，建议先看一遍再上手操作。
[没有公网IP？cloudflare优选IP，高速内网穿透 - 哔哩哔哩](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
## 🎯 你正在解决什么问题
视频详细演示了完整的配置过程，强烈建议先观看视频再进行操作。
## 🎯 你正在解决什么问题？
### 默认 Tunnel 的痛点
直接用 Cloudflare Tunnel 绑定域名时常见以下问题：
当你直接使用 Cloudflare Tunnel 绑定域名时：
- ❌ Cloudflare 分配的 Anycast IP 在国内可能被绕路（绕到美国、欧洲）
- ❌ 运营商 QoS 限速，访问速度慢
- ❌ 延迟高达数百毫秒，严重影响使用体验
* ❌ Cloudflare 分配的 Anycast IP 在国内可能被绕路（绕到美国、欧洲）
* ❌ 运营商 QoS 限速，访问速度慢
* ❌ 延迟高达几百毫秒，严重影响使用体验
![优选 IP 前的访问速度](https://minio.oneinai.com/oneinai/images/docs/hapi/优选前.png)
![优选 IP 前的访问速度](https://docs.ikuncode.cc/images/apps/hapi/%E4%BC%98%E9%80%89%E5%89%8D.png)
### 优选 IP 方案的优势
通过本教程的配置，可以做到：
通过本教程的配置：
- ✅ 强制流量走对国内网络友好的节点（香港、新加坡等）
- ✅ 大幅提升访问速度，延迟降至几十毫秒
- ✅ 完全免费，利用 Cloudflare 企业级功能
- ✅ 稳定性高，自动切换最优路由
* ✅ 强制流量走对国内网络友好的节点（香港、新加坡等）
* ✅ 大幅提升访问速度，延迟降低到几十毫秒
* ✅ 完全免费，利用 Cloudflare 企业级功能
* ✅ 稳定性高，自动切换最优路由
![优选 IP 后的访问速度](https://minio.oneinai.com/oneinai/images/docs/hapi/优选后.png)
![优选 IP 后的访问速度](https://docs.ikuncode.cc/images/apps/hapi/%E4%BC%98%E9%80%89%E5%90%8E.png)
> 🚀 **速度提升对比**
> 从两张对比图可以看到，优选 IP 后访问延迟从数百毫秒降到几十毫秒，页面加载也更顺畅。
🚀 速度提升对比
从上面两张图可以看到，优选 IP 后访问速度得到了**显著提升** ，延迟从几百毫秒降低到几十毫秒，页面加载也更加流畅！
## 🔍 原理解析
### 流量走向链路
当用户访问你的域名时，流量按以下路径流转：
当用户访问你的域名时，流量是这样流转的：
```
用户浏览器
↓
DNS 解析：hapi.justdo.xin
@ -62,19 +63,40 @@ SaaS 路由：hapi.justdo.xin → hapi.ttdk.fun
Cloudflare Tunnel（加密隧道）
↓
你的本地服务器 localhost:3006
```
> 💡 **提示**
> [isp.qzz.io](https://isp.qzz.io/) 在这里充当"智能交警"，根据你的网络环境自动选择最优路线。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
💡 提示
[isp.qzz.io](<https://isp.qzz.io/>) 在这里充当"智能交警"的角色，根据你的网络环境自动选择最优路线。
### 核心技术要点
1. **优选 IP 调度器**：[isp.qzz.io](https://isp.qzz.io/) 会根据用户的运营商（电信/联通/移动），返回当前速度最快、延迟最低的 Cloudflare 官方 CDN 节点 IP。
2. **Cloudflare for SaaS**：通过 Custom Hostnames 功能把"访问域名"和"隧道域名"解耦，实现"走优选 IP 进隧道"。
3. **DNS 链式解析**：通过 CNAME 链把用户请求引导到优选 IP，同时保持 Cloudflare 对域名的正确识别。
1. **优选 IP 调度器** ：[isp.qzz.io](<https://isp.qzz.io/>) 会根据用户的网络环境（电信/联通/移动），返回当前速度最快、延迟最低的 Cloudflare 官方 CDN 节点 IP
> 💡 **关于优选 IP 调度器**
> [isp.qzz.io](https://isp.qzz.io/) 是社区维护的 Cloudflare 优选 IP 调度服务，会自动测速并返回对当前网络环境最优的 Cloudflare CDN 节点。访问该网站可查看更多说明。
2. **Cloudflare for SaaS** ：通过 Custom Hostnames 功能，把"访问域名"和"隧道域名"解耦，实现"走优选 IP 进隧道"
3. **DNS 链式解析** ：通过 CNAME 链，把用户请求引导到优选 IP，同时保持 Cloudflare 对域名的正确识别
💡 关于优选 IP 调度器
[isp.qzz.io](<https://isp.qzz.io/>) 是一个社区维护的 Cloudflare 优选 IP 调度服务，它会自动测速并返回对你当前网络环境最优的 Cloudflare CDN 节点。访问该网站可以查看更多信息和使用说明。
## 🛠️ 配置步骤
@ -86,10 +108,11 @@ Cloudflare Tunnel（加密隧道）
2. **辅助域名** ：用于承载 Cloudflare Tunnel（例如：`ttdk.fun`）
3. 两个域名都需要托管在 Cloudflare
> ⚠️ **重要说明**
> - 主力域名和辅助域名**不能是同一个域名**
> - 辅助域名需要是你自己拥有的，不能用别人的
> - 两个域名都必须在 Cloudflare 上管理
⚠️ 重要说明
* 主力域名和辅助域名**不能是同一个域名**
* 辅助域名需要是你自己拥有的，不能用别人的
* 两个域名都必须在 Cloudflare 上管理
### 第一步：配置 Cloudflare Tunnel（辅助域名）
@ -99,11 +122,11 @@ Cloudflare Tunnel（加密隧道）
2. 进入 **Zero Trust → Access → Tunnels**
3. 创建隧道并安装 cloudflared
4. 配置公共主机名：
- **子域名**：`hapi`
- **域名**：`ttdk.fun`
- **服务**：`http://localhost:3006`
* **子域名** ：`hapi`
* **域名** ：`ttdk.fun`
* **服务** ：`http://localhost:3006`
完成后，你应该可以通过 `hapi.ttdk.fun` 访问 Hapi 服务。
完成后你应该能通过 `hapi.ttdk.fun` 访问你的 Hapi 服务。
### 第二步：启用 Cloudflare for SaaS（辅助域名）
@ -114,134 +137,149 @@ Cloudflare Tunnel（加密隧道）
3. 进入 **SSL/TLS → Custom Hostnames**
4. 点击 **Add Custom Hostname**
5. 填写：
- **Custom Hostname**：`hapi.justdo.xin`（主力域名）
- **Wildcard**：不勾选
* **Custom Hostname** ：`hapi.justdo.xin`（主力域名）
* **Wildcard** ：不勾选
6. 点击 **Add Custom Hostname**
> 💡 **提示**
> 添加后会生成 2 条 TXT 验证记录，先保留页面，下一步会用到。
💡 提示
添加后会生成 2 条 TXT 验证记录，先不着急配置，继续下一步。
### 第三步：配置 DNS 解析（主力域名）
在主力域名（`justdo.xin`）的 DNS 设置中添加以下记录。
在主力域名（`justdo.xin`）的 DNS 设置中添加以下记录：
#### 3.1 添加 SSL 验证记录
把第二步生成的 2 条 TXT 记录添加到主力域名的 DNS：
从第二步中复制 Cloudflare 生成的 2 条 TXT 记录，添加到主力域名的 DNS：
| 类型 | 名称 | 内容 | 代理状态 |
| --- | --- | --- | --- |
| TXT | `_acme-challenge.hapi` | `xxxxxxxxxx`（从 SaaS 页面复制） | 仅限 DNS |
| TXT | `_acme-challenge.hapi` | `yyyyyyyyyy`（从 SaaS 页面复制） | 仅限 DNS |
类型| 名称| 内容| 代理状态
---|---|---|---
TXT| `_acme-challenge.hapi`| `xxxxxxxxxx`（从 SaaS 页面复制）| 仅限 DNS
TXT| `_acme-challenge.hapi`| `yyyyyyyyyy`（从 SaaS 页面复制）| 仅限 DNS
#### 3.2 添加 CNAME 记录
| 类型 | 名称 | 目标 | 代理状态 |
| --- | --- | --- | --- |
| CNAME | `cdn` | `isp.qzz.io` | 仅限 DNS ⚠️ |
| CNAME | `hapi` | `cdn.justdo.xin` | 仅限 DNS ⚠️ |
类型| 名称| 目标| 代理状态
---|---|---|---
CNAME| `cdn`| `isp.qzz.io`| 仅限 DNS ⚠️
CNAME| `hapi`| `cdn.justdo.xin`| 仅限 DNS ⚠️
> 🚨 **关键配置**
> **必须关闭小黄云（代理状态设为「仅限 DNS」）**。
> 一旦开启代理，会导致 DNS 解析链中断，无法触发优选 IP。
🚨 关键配置
**必须关闭小黄云（代理状态设为 "仅限 DNS"）！**
如果开启代理，会导致 DNS 解析链中断，无法触发优选 IP。
### 第四步：配置回退源（辅助域名）
在辅助域名（`ttdk.fun`）的 DNS 设置中：
| 类型 | 名称 | 目标 | 代理状态 |
| --- | --- | --- | --- |
| CNAME | `hapi` | `[你的隧道ID].cfargotunnel.com` | 已代理 ✅ |
类型| 名称| 目标| 代理状态
---|---|---|---
CNAME| `hapi`| `[你的隧道ID].cfargotunnel.com`| 已代理 ✅
> 💡 **提示**
> 这条记录通常在创建 Tunnel 时会自动生成。请确保小黄云为**开启**状态（已代理）。
💡 提示
这条记录通常在创建 Tunnel 时自动生成。确保小黄云是**开启** 状态（已代理）。
### 第五步：等待 SSL 证书生效
1. 回到辅助域名的 **SSL/TLS → Custom Hostnames** 页面
2. 查看 `hapi.justdo.xin` 的状态
3. 等待几分钟，状态变为 **Active（有效）** 即配置成功
3. 等待几分钟，状态变为 **Active（有效）** 即表示配置成功
> ⏳ **耐心等待**
> SSL 证书签发通常需要 5-15 分钟。如超过 30 分钟仍未生效，请检查 TXT 记录是否正确添加。
⏳ 耐心等待
SSL 证书签发通常需要 5-15 分钟，请耐心等待。如果超过 30 分钟仍未生效，检查 TXT 记录是否正确添加。
## ✅ 验证配置
### 测试访问
在浏览器中访问 `https://hapi.justdo.xin`，能正常打开 Hapi 界面即表示配置成功。
在浏览器中访问：`https://hapi.justdo.xin`
如果能正常打开 Hapi 界面，说明配置成功！
### 测试速度提升
使用 ping 或测速工具对比延迟。
使用 ping 或测速工具对比：
**优化前** ：
```bash
bash
ping hapi.ttdk.fun
# 延迟通常 200-500ms
```
1
2
**优化后** ：
```bash
bash
ping hapi.justdo.xin
# 延迟通常 20-100ms
```
1
2
## 🎓 角色分配总结
| 角色 | 域名示例 | 作用 |
| --- | --- | --- |
| **主力域名** | `hapi.justdo.xin` | 最终展示给用户访问的地址 |
| **辅助域名** | `hapi.ttdk.fun` | 承载 Tunnel 的「回退源」，用户不直接感知 |
| **优选 IP 调度器** | [isp.qzz.io](https://isp.qzz.io/) | 像「交警」，告诉流量走哪条不堵的路 |
| **中转域名** | `cdn.justdo.xin` | 作为跳板，把主力域名引向优选 IP 池 |
角色| 域名示例| 作用
---|---|---
**主力域名**| `hapi.justdo.xin`| 你最终展示给用户访问的地址
**辅助域名**| `hapi.ttdk.fun`| 承载 Tunnel 的"回退源"，用户不直接感知
**优选 IP 调度器**| [isp.qzz.io](<https://isp.qzz.io/>)| 像"交警"，告诉流量该走哪条不堵的路
**中转域名**| `cdn.justdo.xin`| 作为跳板，把主力域名引向优选 IP 池
## 🔧 故障排查
### SSL 证书一直显示 Pending
### SSL 证书一直显示 Pending？
**可能原因** ：
- TXT 记录添加错误或未生效
- DNS 传播尚未完成
* TXT 记录添加错误或未生效
* DNS 传播未完成
**解决方法** ：
1. 使用 [DNS 检查工具](https://dnschecker.org/) 验证 TXT 记录
2. 等待 DNS 全球传播（最长 24 小时）
3. 必要时重新添加 Custom Hostname
1. 使用 [DNS 检查工具](<https://dnschecker.org/>) 验证 TXT 记录
2. 等待 DNS 全球传播（最多 24 小时）
3. 重新添加 Custom Hostname
### 访问显示 526 错误
### 访问显示 526 错误？
**可能原因** ：
- 辅助域名的 `hapi` 记录未开启代理（小黄云）
- Tunnel 未正确配置
* 辅助域名的 `hapi` 记录未开启代理（小黄云）
* Tunnel 未正确配置
**解决方法** ：
1. 确认 `hapi.ttdk.fun` 的小黄云为**开启**状态
1. 确保 `hapi.ttdk.fun` 的小黄云是**开启** 状态
2. 检查 Tunnel 是否正常运行
### 访问仍然很慢
### 访问仍然很慢？
**可能原因** ：
- 主力域名的 CNAME 记录开启了代理
- DNS 解析链断裂
* 主力域名的 CNAME 记录开启了代理
* DNS 解析链断裂
**解决方法** ：
1. 确认 `hapi.justdo.xin` 与 `cdn.justdo.xin` 的小黄云均为**关闭**状态
1. 确保 `hapi.justdo.xin` 和 `cdn.justdo.xin` 的小黄云都是**关闭** 状态
2. 使用 `nslookup` 检查 DNS 解析链是否完整
## 🚀 进阶优化
### 自建优选 IP 服务
如果你追求更稳定的体验，可以：
如果你追求极致稳定，可以：
1. 使用 CloudflareSpeedTest 工具本地测速
2. 手动选择最优 IP
@ -251,37 +289,37 @@ ping hapi.justdo.xin
可以针对不同运营商配置不同的优选路径：
- 电信用户：`cdn-ct.yourdomain.com`
- 联通用户：`cdn-cu.yourdomain.com`
- 移动用户：`cdn-cm.yourdomain.com`
* 电信用户：`cdn-ct.yourdomain.com`
* 联通用户：`cdn-cu.yourdomain.com`
* 移动用户：`cdn-cm.yourdomain.com`
通过 DNS 智能解析（GeoDNS），根据用户运营商返回不同的 CNAME 记录。
## 📚 相关资源
- [Cloudflare for SaaS 官方文档](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/)
- [Cloudflare Tunnel 文档](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
- [isp.qzz.io - 优选 IP 调度器](https://isp.qzz.io/)
- [视频教程：Cloudflare 优选 IP 配置](https://www.bilibili.com/video/BV1PPy6YzE5C)
* [Cloudflare for SaaS 官方文档](<https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/>)
* [Cloudflare Tunnel 文档](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/>)
* [isp.qzz.io - 优选 IP 调度器](<https://isp.qzz.io/>)
* [视频教程：cloudflare优选IP配置](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
## ⚠️ 安全提醒
1. 不要泄露 Tunnel 令牌
1. 不要泄露你的 Tunnel 令牌
2. 定期检查 Custom Hostnames 配置
3. [isp.qzz.io](https://isp.qzz.io/) 是社区维护的优选 IP 服务，可靠但非官方，必要时可自建
3. [isp.qzz.io](<https://isp.qzz.io/>) 是社区维护的优选 IP 服务，虽然可靠但非官方服务，你也可以选择自建优选服务
4. 建议配合 Cloudflare Access 限制访问来源
## 💡 总结
通过这套配置，你可以做到：
通过这套配置，你：
- ✅ 不花一分钱
- ✅ 利用 Cloudflare 企业级 SaaS 功能
- ✅ 把原本数百毫秒延迟的内网穿透优化到接近直连的体验
- ✅ 打造一条「高速内网穿透通道」
* ✅ 不花一分钱
* ✅ 利用 Cloudflare 企业级 SaaS 功能
* ✅ 把原本几百毫秒延迟的内网穿透，优化到接近直连的体验
* ✅ 打造了一条"高速内网穿透通道"
这是目前免费方案中，提升 Cloudflare 内网穿透速度的**天花板级别配置**。
这就是目前免费方案中，提升 Cloudflare 内网穿透速度的**天花板级别配置** ！
---
* * *
**下一步**：配置完成后，你就可以在任何地方高速访问 Hapi 服务了 🎉
**下一步** ：配置完成后，你可以愉快地在任何地方高速访问你的 Hapi 服务了！🎉