> For the complete documentation index, see [llms.txt](https://docs.ipdunar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipdunar.com/zh/gu-zhang-pai-cha/ssl-errors.md).

# SSL / TLS 错误

ipdunar 是**转发型**代理——对 HTTPS 目标，网关通过 `CONNECT` 打通 TCP 隧道，你的客户端与目标端到端协商 TLS。因此 SSL 错误几乎只有三种：

1. 客户端 CA 证书库过期
2. 目标站点 TLS 配置坏掉
3. 链路中夹了别的 MITM 工具

## 现象：`SSL: CERTIFICATE_VERIFY_FAILED`（Python）

```
requests.exceptions.SSLError: HTTPSConnectionPool(host='example.com', port=443):
  Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(...)))
```

**诊断**

```bash
# 绕过 ipdunar 直接验目标
openssl s_client -connect example.com:443 -servername example.com < /dev/null

# 再走 ipdunar
curl -v --proxy http://USER:PASS@gate.ipdunar.com:7777 https://example.com
```

两边都报同样的证书错——**目标本身坏的**。

**修复**

* **更新 certifi**（Python）：`pip install -U certifi`
* **更新系统 CA 证书库**：`apt update && apt install ca-certificates -y && update-ca-certificates`
* **关闭校验**（仅作为最后手段，且仅用于测试目标）：

  ```python
  requests.get(url, verify=False)
  ```

## 现象：网关返回 `502` + `upstream-tls-error`

```
HTTP/1.1 502
X-Ipdunar-Error-Code: upstream-tls-error
```

目标对 ipdunar 出口 IP 的 TLS 握手失败。常见原因：

* 证书过期
* 缺中间证书
* 要求某 TLS 版本或加密套件，与你本地协商出的不同

TLS 是端到端，所谓"出口 IP"不参与 TLS 谈判——网关只是观察到握手未在规定时间内完成并报告。

**修复**

* 换出口 IP 重试（轮换 session）
* 多 IP 一致失败时，目标本身坏掉，用 `openssl s_client` 确认

## 现象：本地 HTTPS 正常，走代理就挂

最常见：**DNS 解析**。本地解析到家附近的 CDN，而代理解析到另一个（有时配置错的）边缘。

**修复**

* 改用 SOCKS5 + `socks5h://`，让代理统一解析。
* 极少数目标可硬编码已知良好的 DoH ——但会破坏地理定位。

## 现象：日志提示证书有篡改痕迹

ipdunar **绝不**改写上游 TLS。若日志中看到此类迹象，请查链路中**别的** MITM 代理——公司防火墙、忘关的 Charles/mitmproxy、签证书的 VPN 客户端。

## 自签证书目标

ipdunar 帮不上忙——它不重签。客户端需显式信任目标的自签根：`requests.get(..., verify="my-ca.pem")`。

## 排错清单

* [ ] 不走代理直接访问是否成功？
* [ ] Python `certifi` 或系统 CA 库是否最新？
* [ ] `openssl s_client` 是否成功？
* [ ] 链路中是否还有其他 MITM 代理？
* [ ] 换一个出口 IP 是否好转？

全部排查后仍失败请提交工单，附 `X-Ipdunar-Request-Id` 与 `openssl s_client` 输出。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ipdunar.com/zh/gu-zhang-pai-cha/ssl-errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
