使用Curxy代理连接Cursor与本地Ollama：解决云端无法访问localhost的AI编程方案-平芜编程栈

1. 项目概述：为什么我们需要一个本地AI的“传声筒”

如果你和我一样，是个重度依赖 Cursor 编辑器，同时又对本地大模型（比如 Ollama）情有独钟的开发者，那你一定遇到过这个让人挠头的困境：Cursor 的 AI 补全功能，理论上可以配置成本地端点，但实际操作时，请求总是石沉大海。这背后的原因，其实是一个典型的网络架构问题。Cursor 编辑器本身运行在你的电脑上，但它内部的 AI 请求逻辑，是先发往 Cursor 的官方云端服务器，再由云端服务器转发到你配置的端点（比如http://localhost:11434）。问题就出在这里——Cursor 的云端服务器，怎么可能访问到你个人电脑上localhost这个地址呢？这就像你让一个远在千里之外的朋友，去你卧室书桌上拿本书一样，他根本找不到门。

curxy这个项目，就是为了解决这个“最后一公里”的通信问题而生的。它的名字很直白，就是Cursor和Proxy的组合。本质上，它是一个用 Deno 和 Hono 框架编写的轻量级代理服务器。它的核心工作，就是在公网上建立一个“中转站”。你本地的 Cursor 编辑器将请求发给这个位于公网的“中转站”，然后“中转站”再将请求无缝转发到你本地运行的 Ollama 服务器，最后把 Ollama 的响应原路返回给 Cursor。这样一来，就巧妙地绕过了“云端服务器无法访问 localhost”的限制。

简单来说，curxy就是为你本地的 Ollama 模型在公网上开了一个专属的“热线电话”，让 Cursor 的云端服务能够通过这个号码，顺利联系上你家里的“AI大脑”。这对于注重隐私、希望完全在本地处理代码生成与对话、或者单纯想免费使用开源模型的开发者来说，是一个极其优雅的解决方案。

2. 核心原理与架构拆解

2.1 网络请求的“三角恋”与代理的“媒人”角色

要理解curxy的价值，我们得先看清没有它时的“三角恋”困局。标准的 Cursor + Ollama 配置期望的路径是：Cursor客户端 -> Ollama本地服务。但现实是，Cursor 为了统一管理和提供部分增值服务，插入了一个“第三者”：Cursor客户端 -> Cursor云端服务器 -> Ollama本地服务。这个“第三者”（Cursor云端）成了沟通的阻塞点。

curxy的聪明之处在于，它没有尝试去改变 Cursor 或 Ollama 的任何一方，而是自己扮演了一个“媒人”或者说“接线员”的角色。它部署在一个双方都能访问的位置（通过 Cloudflare Tunnel 暴露到公网），从而重构了通信链路：Cursor客户端 -> Cursor云端服务器 -> Curxy公网代理 -> Ollama本地服务。在这个链条里，Curxy 对 Cursor 云端来说，就是一个标准的 OpenAI API 兼容端点；对后端的 Ollama 来说，它又是一个普通的 HTTP 客户端。它负责协议转换、请求转发和响应回传。

2.2 技术栈选择：为什么是 Deno + Hono？

作者选择了 Deno 和 Hono 来构建这个代理，这是一个非常贴合项目需求的、现代且高效的技术组合。

Deno 的优势：
- 内置安全性与简化部署：Deno 默认安全，需要显式授权才能访问网络或文件系统（虽然curxy用了-A全权标志，但在生产观念上这是个好基础）。更重要的是，Deno 的jsr:包管理器使得分发和运行这个工具变得极其简单，一行deno run命令即可，无需处理复杂的npm install或依赖冲突。
- 单文件可执行性：虽然项目有源码，但通过 JSR 发布后，用户感觉上就是在运行一个“脚本”，降低了使用门槛，符合这类工具类项目“开箱即用”的定位。
- 现代 TypeScript 原生支持：保证了代码的健壮性和开发体验。
Hono 框架的优势：
- 轻量级与高性能：Hono 是一个为边缘计算设计的超轻量级 Web 框架，其路由和中间件系统非常高效。对于curxy这样一个功能聚焦（主要是请求转发）的代理服务器来说，Hono 足够小巧，没有不必要的开销。
- 优异的兼容性：Hono 能轻松创建符合 OpenAI API 格式的端点，方便将 Ollama 的响应“包装”成 Cursor 云端期望的格式。
- 云原生友好：Hono 本身在 Cloudflare Workers 等环境运行良好，这与curxy利用 Cloudflare Tunnel 暴露服务的思路一脉相承。

这个技术栈的选择，体现了作者对“工具”的深刻理解：用最合适的、最简洁的技术，快速可靠地解决一个明确的问题，同时为使用者提供近乎零配置的体验。

2.3 安全考量的双刃剑：OPENAI_API_KEY 的作用

项目文档中提到，可以通过设置OPENAI_API_KEY环境变量来限制对代理服务器的访问。这是一个重要的安全特性，但我们需要正确理解其工作原理。

它不是用来调用 OpenAI 官方 API 的。实际上，这个“API Key”在curxy这里被用作一个简单的共享密钥认证。当你在服务端设置了OPENAI_API_KEY=your_secret_token后，curxy会在其接收到的请求头中检查Authorization: Bearer your_secret_token字段。只有携带了正确 Token 的请求才会被转发给 Ollama。

这意味着什么？

好处：防止任何人拿到你的 Curxy 公网 URL 后，都能免费使用你的 Ollama 算力和模型。这在共享服务器或对安全有要求的环境下是必要的。
需要注意的地方：在 Cursor 编辑器里配置时，你需要在 “OpenAI API Key” 字段填写的，同样是这个你自己定义的your_secret_token，而不是一个真正的 OpenAI Key。这可能会造成一些混淆，因为字段名是“OpenAI API Key”，但实际功能是“Curxy 代理访问密钥”。

注意：这个密钥以明文形式在 Cursor 配置界面填写，并通过网络传输。虽然通信过程可能经过 HTTPS 加密，但请务必意识到，它不是一个高强度的身份验证机制，更适合用于防止非授权的偶然访问，而非对抗恶意攻击。对于更高安全需求，应考虑在 Curxy 前部署更完善的反向代理和认证层。

3. 从零开始的详细配置与实操指南

3.1 环境准备：确保基石稳固

在启动curxy之前，我们需要确保两个核心依赖已经就绪。

1. 安装并运行 OllamaOllama 是本项目的 AI 引擎，必须首先安装并运行。

访问官网：前往 Ollama 官网，根据你的操作系统（Windows/macOS/Linux）下载并安装。
拉取模型：安装完成后，打开终端，拉取你需要的模型。例如，拉取目前社区非常流行的qwen2.5-coder模型：
```
ollama pull qwen2.5-coder:7b
```
验证服务：运行ollama serve或在安装后直接启动 Ollama 应用。默认情况下，Ollama 的 API 服务会运行在http://127.0.0.1:11434。你可以在浏览器中访问http://127.0.0.1:11434/api/tags来验证，如果返回了已安装的模型列表 JSON，说明服务正常。

2. 安装 DenoDeno 是运行curxy的 JavaScript/TypeScript 运行时。

推荐安装方法：使用官方的一键安装脚本，这是最通用和简单的方式。

# MacOS 或 Linux curl -fsSL https://deno.land/install.sh | sh # Windows (PowerShell) irm https://deno.land/install.ps1 | iex

验证安装：安装完成后，重启你的终端，运行deno --version。如果能看到版本号信息，说明安装成功。Deno 的可执行文件通常会自动添加到系统路径中。

3.2 启动 Curxy 代理服务器

环境就绪后，启动curxy本身非常简单。打开一个新的终端窗口（确保 Ollama 的服务在另一个窗口或后台运行）。

基础启动命令：

deno run -A jsr:@ryoppippi/curxy

deno run： Deno 执行命令。
-A：这是一个宽松的权限标志，等同于--allow-all，授予脚本所有权限（网络、环境变量等）。对于这种需要创建 HTTP 服务器和隧道的工具，这是最方便的方式。
jsr:@ryoppippi/curxy：直接从 JSR (JavaScript Registry) 包仓库拉取并运行curxy的最新版本。

执行命令后，终端会输出类似以下信息：

Listening on http://127.0.0.1:62192/ ◐ Starting cloudflared tunnel to http://127.0.0.1:62192 Server running at: https://remaining-chen-composition-dressed.trycloudflare.com

这里有两个关键地址：

http://127.0.0.1:62192：这是curxy在你本地机器上启动的代理服务器地址。这个地址只对你本机可见。
https://...trycloudflare.com：这是通过 Cloudflare Tunnel 服务为你本地服务器生成的一个临时的、公开可访问的 HTTPS 网址。这个网址就是我们要填入 Cursor 的“通行证”。

带访问控制的启动命令：如果你担心公网 URL 被他人滥用，可以设置访问密钥：

OPENAI_API_KEY=my_super_secret_token_123 deno run -A jsr:@ryoppippi/curxy

请将my_super_secret_token_123替换为你自己设定的任意复杂字符串。记住这个字符串，稍后需要在 Cursor 中配置。

3.3 配置 Cursor 编辑器

这是最关键的一步，我们需要告诉 Cursor 使用我们刚刚搭建的代理通道。

打开 Cursor 设置：在 Cursor 编辑器中，通过菜单栏或快捷键 (Cmd + ,或Ctrl + ,) 打开设置。
进入 AI 设置：在设置侧边栏找到“AI”选项并点击。
配置自定义模型：
- Override OpenAI Base URL：将curxy启动后给出的那个https://...trycloudflare.com网址，在后面加上/v1，然后完整地粘贴到这个输入框中。例如：https://remaining-chen-composition-dressed.trycloudflare.com/v1。这个/v1路径是 OpenAI 兼容 API 的标准入口，curxy会在此监听请求。
- OpenAI API Key：
  - 如果你启动curxy时没有设置OPENAI_API_KEY，那么 Cursor 中的这个字段可以留空。
  - 如果你启动时设置了OPENAI_API_KEY（如my_super_secret_token_123），那么你必须在这里填写完全相同的字符串。
- Model Names：在这里添加你想要在 Cursor 中使用的 Ollama 模型名称。这里的名称必须与你在 Ollama 中拉取和运行的模型名称完全一致。例如，如果你拉取了qwen2.5-coder:7b，这里就添加qwen2.5-coder:7b。你可以添加多个模型，用逗号分隔，如qwen2.5-coder:7b, llama3.2:3b。添加后，这些模型会出现在 Cursor 的模型选择下拉列表中。
保存并测试：保存设置。现在，你可以尝试在 Cursor 中触发 AI 补全（例如，写一段注释后按Cmd+K），或者在 Chat 界面选择你刚配置的模型并提问。如果一切正常，Cursor 的状态栏会显示正在使用你配置的模型，并很快给出响应。

3.4 配置过程图解与要点回顾

为了更直观，我们可以将整个数据流总结如下：

+-------------------+ 请求 (含API Key) +---------------------------+ 转发请求 +-------------------+ | | --------------------> | | -------------> | | | Cursor 编辑器 | | Cursor 云端服务器 | | Curxy 代理 | | (你的电脑) | <-------------------- | (cursor.com) | <------------- | (公网URL) | | | 返回AI结果 | | 返回结果 | | +-------------------+ +---------------------------+ +-------------------+ | | 本地HTTP请求 v +-------------------+ | | | Ollama 服务 | | (localhost:11434)| | | +-------------------+

实操要点回顾：

顺序很重要：先启动 Ollama，再启动curxy，最后配置 Cursor。
URL 格式：Cursor 中填写的 URL 必须是https://...trycloudflare.com/v1，别忘了/v1。
模型名严格一致：Cursor 中 “Model Names” 填写的名字，必须是你用ollama pull下载的模型全名。
密钥匹配：如果设置了OPENAI_API_KEY，Cursor 中的 API Key 必须与之完全相同。
隧道是临时的：Cloudflare Tunnel 提供的免费.trycloudflare.com域名是临时的，每次重启curxy都会变化。这意味着你每次重启服务后，都需要去 Cursor 设置里更新 URL。对于长期使用，可以考虑更稳定的隧道方案（如配置自定义域名）。

4. 高级用法、问题排查与优化建议

4.1 提升稳定性和便利性：超越临时隧道

每次重启都改配置显然太麻烦，也不利于团队共享配置。我们可以通过几种方式优化：

方案一：使用固定子域名（Cloudflare Tunnel 高级功能）如果你拥有一个自己的域名，并且将其 DNS 托管在 Cloudflare，可以使用cloudflared隧道创建具有固定子域名的隧道。这需要你安装并配置cloudflared客户端，并创建隧道配置文件。虽然步骤稍多，但能获得一个像curxy.yourdomain.com这样的固定地址，一劳永逸。

方案二：在内网服务器部署（团队使用）如果你和同事都在同一个内网，可以将curxy和 Ollama 部署在一台内网服务器上，然后通过内网穿透或路由器端口映射，提供一个稳定的内网 IP 或域名。这样，整个团队都可以在 Cursor 中配置同一个地址，共享强大的本地模型。

方案三：使用反向代理（如 Nginx/Caddy）在运行curxy的服务器前部署一个反向代理（如 Nginx），可以带来诸多好处：

固定端口和域名：将curxy运行在固定端口（如 3000），用 Nginx 代理到https://ai.yourdomain.com/v1。
增强安全：在 Nginx 层配置更严格的 HTTPS、访问日志、速率限制甚至更复杂的认证。
负载均衡：如果你有多台运行 Ollama 的机器，Nginx 可以做负载均衡。

4.2 常见问题与排查清单

即使按照步骤操作，也可能会遇到问题。下面是一个快速排查指南：

问题现象	可能原因	排查步骤
Cursor 提示 “Failed to fetch” 或 “API Error”	1. Curxy 服务未运行 2. Cursor 中配置的 URL 错误 3. 网络问题导致 Cloudflare 隧道不通	1. 检查运行`curxy`的终端是否在运行，有无报错。 2. 核对 Cursor 中 URL 是否为`curxy`输出的完整`https://.../v1`格式。 3. 尝试在浏览器中直接访问该 URL，看是否能打开（可能会返回 JSON 错误，这正常，说明服务可达）。
Cursor 提示 “Invalid API Key”	1. 服务端设置了`OPENAI_API_KEY`但客户端未填或填错 2. 客户端填了 Key 但服务端未设置	1. 确认启动`curxy`的命令中是否包含`OPENAI_API_KEY=xxx`。 2. 确认 Cursor 中 “OpenAI API Key” 字段填写的值与启动命令中的`xxx`完全一致（注意空格和大小写）。
Cursor 中看不到配置的模型	1. “Model Names” 填写错误 2. Ollama 中未拉取对应模型 3. Curxy 无法连接到 Ollama	1. 在终端运行`ollama list`，确认模型名称，并确保 Cursor 中填写的是完全相同的名字。 2. 检查运行`curxy`的终端有无连接 Ollama 失败的错误日志。确保 Ollama 服务 (`ollama serve`) 正在运行。
AI 响应速度极慢或超时	1. 模型首次加载需要时间 2. Cloudflare 隧道网络延迟 3. 本地机器资源（CPU/内存）不足	1. 首次使用某个模型时，Ollama 需要加载模型到内存，等待1-2分钟是正常的。 2. 后续请求仍然很慢，可能是隧道节点问题。尝试重启`curxy`获取新的隧道地址。 3. 检查任务管理器，确认内存是否充足。大模型需要大量内存。
连接频繁断开	Cloudflare 免费隧道的不稳定性	这是免费`.trycloudflare.com`域名的已知问题。对于生产级使用，强烈建议采用“固定子域名”或“内网部署”方案。

一个实用的调试技巧：在启动curxy时，可以添加-L info或-L debug标志来获取更详细的日志，帮助定位问题。

deno run -A jsr:@ryoppippi/curxy -L debug

4.3 性能调优与模型选择建议

curxy本身非常轻量，性能瓶颈主要在于 Ollama 模型推理和网络延迟。

模型选择：对于代码补全这种需要低延迟的任务，建议选择参数量适中、针对代码优化的模型。例如qwen2.5-coder:7b、deepseek-coder:6.7b、codellama:7b都是不错的选择。更大的模型（如 34B, 70B）虽然能力更强，但加载和推理速度慢，可能影响编码体验。
Ollama 参数调整：运行 Ollama 时，可以通过环境变量或启动参数限制其使用的 CPU 线程数和 GPU 层数，以平衡性能与系统资源。例如OLLAMA_NUM_PARALLEL=2可以限制并行请求数。
保持 Curxy 和 Ollama 在同一主机：这是最理想的部署方式，可以消除代理与 AI 引擎之间的网络延迟。避免将curxy放在一台机器，而 Ollama 放在另一台机器，除非它们之间的内网连接速度极快。

5. 深入探索：理解 Curxy 的工作机制与扩展可能

5.1 拆解 Curxy 的请求转发逻辑

虽然我们只是使用者，但了解curxy内部如何处理请求，能帮助我们在遇到复杂问题时更好地分析和解决。简单来说，curxy主要做了以下几件事：

创建 HTTP 服务器：使用 Hono 框架，在本地一个随机端口（如 62192）启动一个 Web 服务器。
监听/v1端点：它会在/v1/chat/completions等路径上监听 POST 请求，这些路径是 OpenAI API 的标准格式，Cursor 云端服务器正是向这些端点发送请求。
请求头处理与认证：检查传入请求的Authorization头，如果服务端设置了OPENAI_API_KEY，则会验证其是否匹配。同时，它可能会对请求头进行一些清洗或修改，以适配 Ollama 的 API。
请求体转换与转发：将收到的 JSON 请求体（遵循 OpenAI 格式）进行必要的字段映射，转换成 Ollama API 能够理解的格式。例如，将model参数映射为 Ollama 的模型名，将messages数组进行格式转换。
调用 Ollama API：向http://localhost:11434/api/chat（或/api/generate）发送转换后的 HTTP 请求。
响应流处理：Ollama 的响应通常是流式的（streaming）。curxy需要正确地将这个流接收下来，并按照 OpenAI 的流式响应格式（Server-Sent Events）重新包装，再传回给最初的请求方（Cursor 云端服务器）。
启动隧道：通过调用cloudflared，将本地的http://127.0.0.1:62192服务暴露到一个公网可访问的 HTTPS 地址。

这个过程确保了协议之间的兼容性，让原本只懂 OpenAI API 的 Cursor 云端，能够与提供类似但不同 API 的 Ollama 进行对话。

5.2 潜在的扩展与自定义方向

curxy项目本身简洁专注，但它的架构为我们打开了一些自定义的可能性。如果你懂一些 TypeScript/JavaScript，可以克隆其源码进行修改。

支持其他本地 AI 后端：理论上，你可以修改curxy的转发逻辑，让它不仅支持 Ollama，还能支持其他提供 HTTP API 的本地推理引擎，如lmstudio、text-generation-webui等。核心是写好不同 API 之间的请求/响应转换器。
添加中间件功能：利用 Hono 的中间件系统，你可以轻松添加日志记录、请求过滤、响应缓存、甚至简单的提示词（prompt）预处理功能。例如，在所有代码补全请求前，自动添加一个“你是一名资深程序员”的系统提示。
修改隧道提供商：如果你不想用 Cloudflare Tunnel，可以修改代码，集成ngrok、localhost.run或其他内网穿透工具。

当然，对于绝大多数用户来说，直接使用 JSR 上的版本已经足够完美。curxy的价值在于它精准地命中了一个痛点，并用最小可行产品（MVP）的方式优雅地解决了它，没有一丝多余的设计。这种“简单即美”的哲学，正是优秀工具软件的标志。