> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 网络、代理与连接排查

> 按网络、地址、鉴权、模型和请求体的顺序定位连接失败。

“连接失败”可能发生在本地网络、代理、DNS、TLS、接口地址、鉴权或上游模型。按从近到远的顺序检查，避免一次修改多个配置。

## 排查顺序

```text theme={null}
你的应用 → 本地网络/代理 → DNS/TLS → APIONE 网关 → 模型线路
```

### 1. 检查域名与 HTTPS

API 请求应发往 `https://api.apione.ai`。控制台 `https://apione.ai/zh/app` 用于管理账户，不是 API Base URL。

```bash theme={null}
curl -I --connect-timeout 10 https://api.apione.ai
```

只要能建立 TLS 并返回 HTTP 响应，就说明基础网络已经到达网关；状态码不一定是 200。

### 2. 用模型列表验证鉴权

```bash theme={null}
curl -sS --connect-timeout 10 --max-time 30 \
  https://api.apione.ai/v1/models \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"
```

模型列表成功后，再测试具体生成接口。这样可以把网络/Key 问题与模型参数问题分开。

### 3. 比较 cURL 与客户端

如果 cURL 成功而客户端失败，检查客户端实际发送的 Base URL、代理、环境变量和协议。特别注意重复 `/v1`、自动追加端点、旧配置缓存和系统代理未被客户端继承。

## 常见现象

| 现象 | 可能位置 | 检查 |
| - | - | - |
| DNS 解析失败 | DNS、本地网络 | 系统 DNS、企业网络、域名拼写 |
| 连接超时 | 代理、防火墙、路由 | 代理规则、出口策略、连接超时 |
| TLS/证书错误 | 系统时间、证书链、中间代理 | 系统时间、根证书、HTTPS 检查设备 |
| 返回 HTML | 地址错误或被登录页接管 | 是否误用控制台网址 |
| 401/403 | Key、权限、代理剥离请求头 | Key 状态和 `Authorization` 头 |
| 404 | Base URL 与端点拼接错误 | `/v1` 是否重复或缺失 |
| 429 | 并发、额度或上游限流 | `Retry-After`、并发和控制台用量 |

## 代理注意事项

* 明确代理是系统级、终端级还是仅浏览器扩展。
* 不要把 API Key 写进代理 URL、公开日志或截图。
* 企业 HTTPS 检查可能替换证书；应由网络管理员提供合规证书，不要长期关闭证书校验。
* 分流规则改变后，重新启动实际发请求的客户端。

## 收集诊断信息

向支持提交：发生时间和时区、域名与端点、客户端版本、网络环境、HTTP 状态、脱敏错误、请求 ID。不要提交完整 Key、Cookie、完整提示词或原始客户文件。

下一步：[错误码与排查](https://apione.ai/docs/support/errors.md)、[地址与鉴权](https://apione.ai/docs/api/overview.md)、[请求跟踪](https://apione.ai/docs/api/request-reliability.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.