Dify OpenAI 兼容插件与 Caddy 配置实战指南

这是一份为您整理好的完整 Markdown 文档。您可以直接将其复制并保存为 `Dify-Caddy-Tutorial.md` 或放入您的 MkDocs 博客中作为技术沉淀。

***

# Dify OpenAI 兼容插件与 Caddy 配置实战指南

## 📝 背景与解决目标

在将 Dify 的工作流（通过 `OpenAI Compatible Dify App` 插件）接入第三方 AI 客户端（如 Cherry Studio）时，常会遇到以下痛点：

**路径强制补全冲突**：客户端往往会强制在 API 地址后加上 `/v1/chat/completions`，而 Dify 插件的真实路由不需要 `/v1`，导致请求直接返回 `404 Not Found`。

**解决方案**：利用 Caddy 作为反向代理中间件，暴露 HTTP（80端口）以绕过证书检查，并使用 `handle_path` 指令自动抹除多余的 `/v1/` 路径。

---

## ⚙️ 步骤一：配置 Caddy 反向代理

通过修改 Caddyfile，我们在 443 (HTTPS) 和 80 (HTTP) 端口同时配置路径重写逻辑。

编辑您的 `/etc/caddy/Caddyfile` 文件，修改为以下内容：

```caddyfile
{
    auto_https off
}

# 提取通用转发逻辑为片段（Snippet），方便复用
(dify_proxy_logic) {
    # 使用正则表达式匹配路径：/e/<任意ID>/v1/<后续路径>
    @dify_v1 {
        path_regexp match_id ^/e/([^/]+)/v1/(.*)$
    }
    
    # 将匹配到的请求重写为：/e/<提取的ID>/<后续路径>
    handle @dify_v1 {
        rewrite * /e/{re.match_id.1}/{re.match_id.2}
        reverse_proxy localhost:8002
    }

# 其他常规请求（如原本就不带 /v1 的请求）直接转发
    reverse_proxy localhost:8002
}

:443 {
    tls /etc/caddy/certs/cert.pem /etc/caddy/certs/key.pem
    import dify_proxy_logic
}

:80 {
    import dify_proxy_logic
}
```

**使配置生效：**
在终端执行以下命令重载 Caddy 服务：
```bash
caddy reload --config /etc/caddy/Caddyfile
```

---

## 💻 步骤二：Cherry Studio 客户端接入

在 Cherry Studio 中，进入 **设置 -> 模型服务商 -> OpenAI 兼容**，严格按照以下参数进行填写：

### 1. 核心连接参数

---

## 🔍 原理解析：数据请求流向

当您在 Cherry Studio 中发送消息时，整个数据流转如下：

1. **客户端发出请求**：Cherry Studio 强制将路径补全为：
   `POST http://10.10.3.51/e/k4zc8qkmogbpe3rw/v1/chat/completions`
2. **Caddy 拦截与重写**：Caddy (80 端口) 接收到请求，匹配到 `handle_path` 规则。它将 `/v1/` 切除，并将剩余的 `chat/completions` 重新拼接到基础路径后。
3. **转发至 Dify**：Caddy 将修改后的请求转发给本机的 Dify 容器 (8002 端口)。此时真实的请求路径已变为：
   `POST http://localhost:8002/e/k4zc8qkmogbpe3rw/chat/completions`
4. **响应返回**：Dify OpenAI 兼容插件完美识别路径，执行内部工作流并返回结果给客户端。

> **提示**：这套架构彻底抹平了不同第三方 AI 客户端的路径格式差异，无论是接入 ChatNextWeb、Cursor 还是 Cherry Studio，都可以实现无缝对接。