opensource/proxycast

Fork 0

mirror of https://github.com/aiclientproxy/proxycast.git synced 2026-10-24 12:04:22 +08:00

Files

T

coso 4965f6d385 chore: bump version to v0.30.0

2026-01-06 00:26:16 +08:00

5.6 KiB

Raw Blame History

Connect 接入指南

本文档详细介绍中转商如何接入 ProxyCast Connect，实现一键配置功能。

接入流程

Step 1: Fork 仓库

Fork aiclientproxy/connect 仓库到你的 GitHub 账号。

Step 2: 创建配置文件

在 providers/ 目录下创建 {your-id}.json 文件：

{
  "id": "myrelay",
  "name": "我的中转站",
  "description": "稳定、便宜、快速的 AI API 中转服务",
  
  "branding": {
    "logo": "https://myrelay.com/logo.png",
    "color": "#6366f1"
  },
  
  "links": {
    "homepage": "https://myrelay.com",
    "register": "https://myrelay.com/register",
    "recharge": "https://myrelay.com/recharge",
    "docs": "https://docs.myrelay.com",
    "status": "https://status.myrelay.com"
  },
  
  "api": {
    "base_url": "https://api.myrelay.com/v1",
    "protocol": "openai",
    "auth_header": "Authorization",
    "auth_prefix": "Bearer "
  },
  
  "contact": {
    "email": "support@myrelay.com",
    "telegram": "@myrelay"
  },
  
  "features": {
    "streaming": true,
    "models_endpoint": true
  },
  
  "webhook": {
    "callback_url": "https://api.myrelay.com/proxycast/callback",
    "secret": "whsec_xxxxxxxxxxxxxxxx"
  }
}

Step 3: 提交 PR

提交 Pull Request 到主仓库，填写 PR 模板说明你的中转服务。

Step 4: 等待审核

GitHub Actions 会自动验证配置文件，维护者会在 1-3 个工作日内审核。

Step 5: 合并上线

PR 合并后，registry.json 会自动构建，ProxyCast 客户端会自动同步。

配置字段说明

必填字段

字段	说明	示例
`id`	唯一标识，小写字母、数字、连字符	`myrelay`
`name`	显示名称	`我的中转站`
`description`	简短描述，≤100 字	`稳定、便宜、快速的 AI API 中转服务`
`branding.logo`	Logo URL，256x256 PNG	`https://myrelay.com/logo.png`
`links.homepage`	官网地址	`https://myrelay.com`
`api.base_url`	API 地址（必须 HTTPS）	`https://api.myrelay.com/v1`
`api.protocol`	协议类型	`openai` 或 `anthropic`
`contact.email`	联系邮箱	`support@myrelay.com`

可选字段

字段	说明	默认值
`branding.color`	主题色	`#6366f1`
`links.register`	注册页面	-
`links.recharge`	充值页面	-
`links.docs`	文档地址	-
`links.status`	状态页面	-
`api.auth_header`	认证头	`Authorization`
`api.auth_prefix`	认证前缀	`Bearer`
`contact.telegram`	Telegram 联系方式	-
`contact.discord`	Discord 联系方式	-
`features.streaming`	是否支持流式响应	`true`
`features.models_endpoint`	是否提供 /models 端点	`false`
`webhook.callback_url`	统计回调地址	-
`webhook.secret`	回调签名密钥	-

集成方式

方式一：直接链接

最简单的方式，在用户后台放置链接：

<a href="proxycast://connect?relay=myrelay&key=USER_API_KEY">
  一键配置 ProxyCast
</a>

方式二：JavaScript SDK

提供更好的用户体验：

<script src="https://proxycast.dev/sdk/connect.js"></script>

<button onclick="ProxyCast.connect({ relay: 'myrelay', key: userApiKey })">
  一键配置 ProxyCast
</button>

SDK 功能：

自动检测 ProxyCast 是否安装
未安装时显示下载引导
支持回调函数

ProxyCast.connect({
  relay: 'myrelay',
  key: userApiKey,
  name: '我的Key',
  onSuccess: () => {
    showToast('配置成功！');
  },
  onNotInstalled: () => {
    showDownloadModal();
  }
});

方式三：配置文件下载

生成 .proxycast 配置文件供用户下载：

function downloadConfig(apiKey) {
  const config = {
    relay: 'myrelay',
    key: apiKey,
    name: '我的Key'
  };
  
  const blob = new Blob([JSON.stringify(config)], { type: 'application/json' });
  const url = URL.createObjectURL(blob);
  
  const a = document.createElement('a');
  a.href = url;
  a.download = 'myrelay.proxycast';
  a.click();
}

用户双击 .proxycast 文件，ProxyCast 自动打开并导入配置。

Deep Link 参数

proxycast://connect?relay={relay_id}&key={api_key}&name={key_name}&ref={ref_code}

参数	必填	说明
`relay`	✅	中转商 ID（需在 ProxyCast 注册）
`key`	✅	API Key
`name`	❌	Key 名称（默认使用中转商名称）
`ref`	❌	推广码（用于统计）

示例

# 基础用法
proxycast://connect?relay=openrouter&key=sk-or-v1-xxxx

# 带名称
proxycast://connect?relay=siliconflow&key=sk-xxxx&name=硅基流动-主账号

# 带推广码
proxycast://connect?relay=myrelay&key=sk-xxxx&ref=promo2024

品牌素材要求

素材	规格	说明
Logo	256x256 PNG	透明背景，正方形
主题色	HEX 色值	用于 UI 强调色
简介	≤50 字	一句话描述
详细描述	≤200 字	详细介绍

API 要求

中转商的 API 需要满足：

要求	说明
协议兼容	OpenAI 或 Anthropic 协议
HTTPS	必须使用 HTTPS
模型列表	提供 `/models` 端点（可选）
稳定性	99% 以上可用性

审核标准

PR 合并前需满足：

JSON Schema 验证通过
文件名与 id 字段一致
Logo 图片可访问（256x256 PNG）
API 地址使用 HTTPS
官网可访问
联系方式有效

下一步

统计回调 - 配置 Webhook 追踪推广效果

5.6 KiB Raw Blame History Unescape Escape