最近接了个挺有意思的需求团队想在扣子COZE上搭业务智能体底下的模型统一换成DeepSeek但环境是Windows又要走Docker Desktop一个都不能少。一开始我也被安装扣子COZE这个说法带偏了动手之后才想明白扣子本身是个云端PaaS根本没有Windows安装包这回事。真正需要在本机用Docker Desktop部署的是一个承接DeepSeek密钥的模型网关同时把扣子智能体的模型调用切到这个网关上。这篇文章会完整走一遍Windows下Docker Desktop从装不上到跑通、One-API网关部署、DeepSeek渠道配置、扣子模型挂接、端到端对话验证、以及后期稳定运行的经验。不管你是想熟悉Docker Desktop的Windows落地还是想把扣子智能体接到DeepSeek上这套流程都可以直接抄。1. 先理清角色扣子平台、DeepSeek、Docker Desktop各管哪一环很多教程标题喜欢写安装COZE但真动手之前务必先搞明白这条链路里每个组件的实际位置。否则你会花大量时间去搜一个根本不存在的东西或者把Docker Desktop折腾好之后发现跟扣子一点关系都没有。1.1 扣子COZE到底是什么为什么本地没有安装包扣子是字节跳动旗下的一站式AI智能体开发平台官方说法叫扣子空间也好、叫AI Bot构建平台也罢本质都是SaaS服务。你通过浏览器访问扣子控制台在网页上搭建工作流、创建知识库、编排智能体这些动作全部发生在云端。这就意味着扣子没有Windows客户端也没有官方Docker镜像它不是一个能装到你本机跑起来的软件。任何告诉你用Docker安装扣子的说法要么是在说扣子的某个周边组件要么是在说另一套本地Agent框架。那这篇文章为什么还要用Docker Desktop因为我们要部署的是模型网关。扣子智能体默认用平台自带的模型但你可以配置成调用外部模型外部模型接口通常是OpenAI兼容格式。为了让扣子安全稳定地调到DeepSeek就要先把DeepSeek的API Key托管在一个网关服务里这个网关才是在本机用Docker跑起来的东西。1.2 DeepSeek的模型服务从哪里来DeepSeek和OpenAI一样对外提供API服务。你注册账号、充值、拿到API Key之后就能通过https://api.deepseek.com这个地址调用大模型。关键点在于DeepSeek的接口兼容OpenAI的调用格式。这带来的好处是几乎所有支持OpenAI格式的网关、平台、Agent框架都能直接填DeepSeek的地址和Key来使用。这也为后面扣子接入DeepSeek提供了可能——只要网关能统一转发扣子那边就不用关心真正的模型厂商是谁。DeepSeek官方API的基础参数整理如下项目值Base URLhttps://api.deepseek.comOpenAI兼容地址为https://api.deepseek.com/v1模型名deepseek-chat对话/deepseek-reasoner推理API格式OpenAI Chat Completions密钥类型Bearer Token提示deepseek-reasoner是推理模型适合复杂逻辑任务但响应时间明显比deepseek-chat长。如果只是做普通对话智能体用deepseek-chat就够了。1.3 Docker Desktop在本方案里真正承担的任务在我们这套链路里Docker Desktop的作用是跑一个叫One-API的开源网关。它的核心能力就三件事把DeepSeek的API Key统一托管不用到处明文填写提供统一的OpenAI兼容出口所有第三方平台包括扣子只认这个网关地址记录每次调用的Token消耗、请求日志方便排查问题用Docker Desktop而不是直接裸跑One-API理由也很实际环境隔离、一键启停、不污染Windows的系统环境后续想升级网关版本一条命令重新拉镜像即可。Windows上做这类中间件部署Docker Desktop是最省心的方案。1.4 整体调用链路图用文字描述一下最终效果你看完就知道每一步在干嘛了用户在扣子平台创建的智能体发起对话请求 ↓ 扣子云端根据模型配置把请求发到指定Base URL ↓ Base URL指向你部署的One-API网关 ↓ One-API收到请求做鉴权校验Token、查渠道DeepSeek配置 ↓ One-API转发请求到 https://api.deepseek.com ↓ DeepSeek返回结果One-API记录日志原路回传给扣子这里有一个所有初学者都会忽略的点扣子在云端网关在本地Windows两者之间必须网络互通。扣子没法直接访问你电脑上的localhost:3000所以生产环境要把网关暴露到公网或者直接部署到一台有公网IP的服务器上。本地Docker Desktop更多承担的是开发调试和流程验证的角色这点后面细说。2. Windows环境准备虚拟化、WSL2与Docker Desktop安装的连环坑Windows上装Docker Desktop卡住的概率远比你想象的高。大部分报错都集中在虚拟化没有开启、WSL2内核版本不对、Hyper-V冲突这几类。这一章把完整链路捋一遍每步都解释为什么避免你装到一半去网上翻各种过时教程。2.1 确认CPU虚拟化是否开启任务管理器检查Docker Desktop在Windows上跑容器底层依赖虚拟化技术。要么走Hyper-V要么走WSL2后端两者都需要CPU虚拟化指令VT-x或AMD-V处于开启状态。打开任务管理器切到性能标签点CPU看右下角的虚拟化字段。如果显示已启用继续下一步如果显示已禁用需要重启电脑进BIOS开启。各品牌主板BIOS里虚拟化开关的位置大同小异常见路径如下IntelAdvanced → CPU Configuration →Intel Virtualization Technology→ EnabledAMDAdvanced → CPU Configuration →SVM Mode→ Enabled部分笔记本Security → Virtualization →Intel VT-x / AMD-V→ Enabled开启之后进系统再验证一次确认虚拟化状态变成已启用再往后走。这一步不做Docker Desktop启动时会直接报Virtualization support was not detected那是浪费时间最多的一个坑。2.2 安装WSL2的正确顺序Docker Desktop官方推荐使用WSL2后端原因很简单启动快、内存占用比Hyper-V虚拟机小、和Windows文件系统集成更好。安装WSL2的坑多半出在顺序上。正确做法是用管理员权限打开PowerShell先装WSL本身再设置默认版本为2最后装内核更新包。分开跑三条命令# 安装WSL并默认启用WSL2 wsl --install # 查看当前WSL版本 wsl -l -v如果是老系统wsl --install可能不支持那就分步执行先启用适用于Linux的Windows子系统和虚拟机平台两个Windows功能重启后再安装WSL2内核更新包最后执行wsl --set-default-version 2。提示装完wsl --install后如果提示操作成功完成需要重启务必重启一次再装Docker Desktop。否则Docker识别不到WSL内核照样报错。2.3 Docker Desktop安装与设置要点从Docker官网下载Docker Desktop for Windows安装包双击安装。安装过程中会问使用哪种后端选Use WSL 2 instead of Hyper-V。安装完成后打开Docker Desktop的设置界面在Resources → WSL Integration里确认要集成的是哪个发行版。如果你只是跑容器默认的docker-desktop发行版就够了如果你后面想在WSL终端里直接敲docker命令再把对应的Linux发行版开关打开。这套组合下的配置建议配置项建议值原因CPUs4核以上One-API转发本身不吃资源但网关日志和并发请求需要一点余量Memory4GB以上只跑One-API的话2GB就够但给多一点能避免OOMSwap1GB内存峰值保护Disk image size默认即可One-API镜像不到1GB设置里最容易被忽略的是NAT网络和端口映射。Docker Desktop默认会自动映射容器端口到宿主机但如果你装了防火墙软件或者公司电脑有网络策略3000端口可能没法从外部访问。这个在后面的网络排查章节专门说。2.4 最常见的启动失败报错与修复Docker Desktop启动失败报错信息千奇百怪但根因高度集中。把最高频的三种列出来你可以对着排查。报错一Virtualization support was not detected排查看这里任务管理器确认虚拟化是否已启用BIOS里是否开了VT-x/SVMWindows功能里虚拟机平台和Hyper-V是否都勾选报错二Docker Engine stopped / WSL kernel version too low一般是WSL2内核太旧。在PowerShell执行wsl --update更新完成后重启Docker Desktop。报错三端口被占用One-API默认监听3000端口。如果Windows上有其他程序比如开发用的前端调试服务已经占用了3000需要换端口。确认方法netstat -ano | findstr :3000有PID就说明端口被占可以改One-API的映射端口比如8080:3000。这章节提到的方法没有高深操作但每一步都踩得踏实能让你把基础环境一次弄好。3. 部署One-API网关统一托管DeepSeek Key的中间服务环境准备好之后真正的重头戏来了。One-API是目前很主流的大模型API网关部署方式简单、社区活跃也支持DeepSeek这种OpenAI兼容渠道。用它管DeepSeek Key后续扣子那边就不用直接接触真实密钥。3.1 为什么选One-API而不是直接在扣子里填DeepSeek地址我见过很多人的第一反应是DeepSeek本身就有公网API扣子里直接用官方地址不就行了干嘛多此一举装网关这个问题要分场景回答。如果你只是自己试一次确实不需要网关但如果你是团队协作、公司项目、或者准备把智能体接到实际业务里直接在业务平台里明文配置DeepSeek Key有几个隐患员工账号离职、平台权限泄露Key就跟着泄露而DeepSeek的Key一旦泄漏可能被外部刷量产生费用团队里多个人、多个智能体共用同一个Key出问题了很难定位谁在调用想统计每个应用/每个智能体的Token消耗官方控制台只能看全局没法细粒度拆分One-API解决的就是这三件事密钥托管、调用隔离、日志审计。扣子那边只需要知道网关的地址和网关生成的TokenDeepSeek真实Key永远不会暴露给任何使用端。3.2 编写docker-compose.yml启动网关在Windows本地随意找一个工作目录新建一个文件夹比如one-api在里面创建docker-compose.yml。内容如下version: 3 services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SQL_DSNoneapi:oneapi123tcp(db:3306)/oneapi depends_on: - db volumes: - ./data:/data db: image: mysql:8.0 container_name: one-api-mysql restart: always environment: - MYSQL_ROOT_PASSWORDroot123 - MYSQL_DATABASEoneapi - MYSQL_USERoneapi - MYSQL_PASSWORDoneapi123 volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306注意上面用的是默认的SQLite配置我简化一下One-API支持SQLite作为默认数据存储不需要额外部署MySQL。第一次使用建议用SQLite简单直接减少故障点。简化后的配置是这样的version: 3 services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai volumes: - ./data:/data提示最新版本的One-API镜像名可能变为ghcr.io/songquanpeng/one-api如果拉取justsong/one-api:latest失败用docker pull ghcr.io/songquanpeng/one-api:latest拉取后替换镜像名即可。配置里的./data目录用于持久化数据后面你创建的渠道、令牌、日志都存在这里。容器删了也没关系数据不会丢。在one-api目录下打开终端执行docker compose up -d首次启动会拉镜像可能等几分钟。启动完成后浏览器访问http://localhost:3000看到登录页就说明网关起来了。默认管理员账号是root密码是123456。第一次登录后会强制修改管理员密码按提示走就行。3.3 首次登录、创建渠道、添加DeepSeek配置登录One-API后台后界面是英文可以点右上角头像在通用设置里把语言切为中文后续操作更顺。添加DeepSeek渠道的路径是渠道 → 新建渠道。关键参数如下配置项填什么说明类型OpenAIDeepSeek接口兼容OpenAI格式选这个即可名称deepseek-main识别的名字随便写Base URLhttps://api.deepseek.comDeepSeek官方接口地址模型deepseek-chat,deepseek-reasoner用逗号分隔多个模型写在一起API Key你的DeepSeek Key以sk-开头的真实密钥填完点击提交。注意模型这一栏必须填准确。DeepSeek官方模型名就是deepseek-chat和deepseek-reasoner不要自作主张改成别的。填错的话后面扣子调用时网关会报model not found。3.4 创建令牌并验证网关转发链路渠道配置好之后还需要创建一个令牌这个令牌就是扣子那边要用的密钥。路径是令牌 → 新建令牌。名字随便写比如coze-access过期时间建议选永不过期或按需设置额度留空即可。提交之后会得到一个形如sk-xxxxxxxx的令牌字符串这个值保存好后面配置扣子要用。验证转发链路是否通畅这一步很关键。在Windows终端执行curl http://localhost:3000/v1/chat/completions \ -H Authorization: Bearer sk-你的令牌 \ -H Content-Type: application/json \ -d {\model\: \deepseek-chat\, \messages\: [{\role\: \user\, \content\: \你好\}]}如果返回一段包含choices和content的JSON说明One-API成功把请求转发给了DeepSeek。如果报401或404优先检查令牌和模型名是否正确。这一步验证通过后网关层面的工作就完成了。接下来要做的是怎么让扣子用上这个网关。4. 在扣子COZE中配置DeepSeek模型把本地网关挂接上去扣子平台上的模型配置入口在不同版本里位置会有一点差异但大方向都是进入某个智能体的编辑页在模型选择区域找到自定义模型或添加模型服务然后填网关地址。4.1 扣子平台的自定义模型入口登录扣子平台国内版www.coze.cn进入工作台新建或打开一个智能体。在智能体编排页面左侧能看到模型的设置区域默认选中的是豆包各版本模型。这里注意找**添加模型、自定义模型或者管理模型**的入口不同界面版本名称不完全一样。我这边实操的时候入口藏在模型下拉框的最底部有一个添加自定义模型OpenAI兼容的选项。点进去会让你填三样东西模型名称填写deepseek-chatBase URL填写网关的调用地址API Key填写在One-API里生成的令牌4.2 配置模型名称、Base URL与API Key这里要特别强调一下网关地址到底该填什么这是最容易出错的地方。如果你只是本机测试扣子看不到你电脑上的localhost所以你不能填http://localhost:3000/v1。你需要一个网络可达的地址。方案分两种第一种Docker Desktop部署在Windows同时把网关映射到内网IP先打开PowerShell查看本机内网IPipconfig找到IPv4 地址比如192.168.1.100。那么扣子里Base URL填http://192.168.1.100:3000/v1前提是Windows防火墙允许外部设备访问3000端口且扣子所在网络能访问到这台机器。如果扣子和Windows在同一个局域网比如公司内网部署这个方案可行。第二种在云服务器上用Docker部署One-APIWindows Docker Desktop负责开发调试生产用的网关放在有公网IP的云服务器上。服务器上装好Docker后执行同样的docker compose up -d然后把防火墙开放3000端口Base URL填http://服务器公网IP:3000/v1这是扣子云端真正能访问到的地址。国内云服务器记得在安全组里放行3000端口。API Key就是你在One-API后台创建的令牌例如sk-coze123456。4.3 模型权限与可用范围说明配置完成之后扣子智能体的模型列表里会出现deepseek-chat这个选项。选中它智能体的对话请求就会走你的网关转发给DeepSeek。这里有个现象需要提前解释你在One-API里创建的令牌可以选择绑定某个渠道、某个用户也可以不绑定。如果不做任何绑定这个令牌可以使用网关里所有渠道的所有模型。安全起见我创建令牌时习惯在额度一栏设一个限制比如$10防止有人拿这个令牌刷爆费用。5. 端到端实战搭一个智能体测试DeepSeek是否真正生效配置完成不等于能用端到端跑通才算数。这一步我会带你搭一个最简单的测试智能体并告诉你如何通过网关日志确认请求真的经过了你部署的服务。5.1 新建智能体并绑定自定义模型在扣子平台点击创建智能体名称随便填比如DeepSeek测试Bot。进入编排界面后在右侧模型区域选择刚才添加的deepseek-chat。如果换模型时报错最常见的提示是Invalid API key或Connection error。前者说明One-API令牌没配对后者说明扣子访问不到网关地址。这俩怎么排查后面专门说。5.2 对话测试与网关日志对照在扣子的预览窗口里发一句话比如帮我写一段Python快排代码。如果DeepSeek正常响应预览区会出现完整回答。此时去One-API后台的日志页面能看到一条新记录包含请求时间、模型名、Token用量、耗时。日志存在就说明链路通了。如果再严谨一点可以对比一下日志里的提交Token数和扣子界面显示的字数大致能算出一轮对话的消耗。日常使用这个功能用来做成本核算很方便。5.3 常见失败场景排查端到端调用失败无外乎下面几个原因按出现频率排序现象原因处理方案扣子提示Connection error扣子访问不到网关地址用http://公网IP:3000/v1确认安全组/防火墙放开3000端口提示Invalid API keyOne-API令牌错误去One-API后台复制完整令牌注意不要带多余空格提示Model Not Found模型名不匹配确认填的是deepseek-chat不是deepseek或DeepSeek-Chat提示Rate Limit / Quota ExceededOne-API令牌额度用完检查令牌额度设置改成不限或调大网关日志有请求但DeepSeek超时服务器出网不稳定在服务器上直接curl DeepSeek官方接口测试连通性超时问题时最常见的真实情况是云服务器访问DeepSeek的延迟高或者网络策略拦截。可以先在服务器上执行curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer sk-你的DeepSeek真实Key能返回模型列表说明出网正常问题只在上层转发。6. 稳定运行经验Windows宿主机、Docker与扣子的长期配合要点环境跑通只是第一步。真正让人头疼的是后面日常使用中的稳定性问题。这章的内容是我实际跑了几个星期之后沉淀下来的经验每一条都踩过坑。6.1 Docker Desktop的资源配额调整只跑One-API一个容器的话Docker Desktop默认的2GB内存配置是够用的。但如果你同一台机器上还跑了其他容器比如数据库、CMS、爬虫内存占用就会变得紧张。建议在Docker Desktop设置里把内存调到4GB以上并且把资源 → 高级里的Swap开到1GB。Docker Desktop在Windows上走的WSL2方案内存是动态分配的设置上限高一点不会导致Windows变卡只在容器真正需要时才占用。另外打开Docker Desktop的设置把启动时自动启动Docker Engine勾上。Windows重启之后One-API容器会自动跟着恢复不用每次手动点开Docker Desktop。这个细节能帮你省掉很多远程维护的麻烦。6.2 防火墙与网络访问控制One-API监听3000端口这个端口要暴露给扣子使用但也要防止被无关人员扫描到。如果你把网关部署在云服务器上安全组里白名单式放行扣子出口IP而不是对全网开放3000端口。如果你不确定扣子的出口IP段可以保守一点用一个复杂的API Key并且开启One-API的令牌IP限制功能只允许特定IP使用这个令牌。Windows本地调试时防火墙会弹窗询问是否允许Docker Desktop Backend监听端口要选择允许。如果之前误点了取消去Windows安全中心 → 防火墙和网络保护 → 允许应用通过防火墙里把Docker相关项改为允许。6.3 密钥管理与网关安全One-API后台的root管理员密码务必改成一个高强度密码。这个密码一旦泄露攻击者能拿到你配置的所有模型密钥包括DeepSeek真实Key。我个人的做法是管理员密码用密码管理器生成20位以上随机串DeepSeek真实Key只在One-API渠道配置里出现一次之后谁都不给给扣子用的令牌单独创建设置额度上限每季度轮换一次DeepSeek真实Key换Key时只在One-API后台改扣子那边不用动这样即使扣子那边的令牌泄露了别人也只是用你的网关转发请求顶多消耗令牌额度拿不到真实Key。最后再说一个很实用的经验One-API支持在令牌里设置模型指定也就是某个令牌只能用deepseek-chat另一个令牌可以用deepseek-reasoner。如果你开发环境和生产环境用同一个网关建议给每个环境建不同的令牌并限定模型范围。这样万一某个人误发了昂贵模型的调用费用只算在他自己头上不会牵连整个团队。这套Windows Docker Desktop COZE DeepSeek的组合装下来本质就是两件事先把Docker Desktop在Windows上伺候服帖再用One-API把DeepSeek的调用能力安全地暴露给扣子。流程不复杂但每个环节都有不少前置条件和隐含坑按着上面的节奏走能少走很多弯路。
最近接了个挺有意思的需求团队想在扣子COZE上搭业务智能体底下的模型统一换成DeepSeek但环境是Windows又要走Docker Desktop一个都不能少。一开始我也被安装扣子COZE这个说法带偏了动手之后才想明白扣子本身是个云端PaaS根本没有Windows安装包这回事。真正需要在本机用Docker Desktop部署的是一个承接DeepSeek密钥的模型网关同时把扣子智能体的模型调用切到这个网关上。这篇文章会完整走一遍Windows下Docker Desktop从装不上到跑通、One-API网关部署、DeepSeek渠道配置、扣子模型挂接、端到端对话验证、以及后期稳定运行的经验。不管你是想熟悉Docker Desktop的Windows落地还是想把扣子智能体接到DeepSeek上这套流程都可以直接抄。1. 先理清角色扣子平台、DeepSeek、Docker Desktop各管哪一环很多教程标题喜欢写安装COZE但真动手之前务必先搞明白这条链路里每个组件的实际位置。否则你会花大量时间去搜一个根本不存在的东西或者把Docker Desktop折腾好之后发现跟扣子一点关系都没有。1.1 扣子COZE到底是什么为什么本地没有安装包扣子是字节跳动旗下的一站式AI智能体开发平台官方说法叫扣子空间也好、叫AI Bot构建平台也罢本质都是SaaS服务。你通过浏览器访问扣子控制台在网页上搭建工作流、创建知识库、编排智能体这些动作全部发生在云端。这就意味着扣子没有Windows客户端也没有官方Docker镜像它不是一个能装到你本机跑起来的软件。任何告诉你用Docker安装扣子的说法要么是在说扣子的某个周边组件要么是在说另一套本地Agent框架。那这篇文章为什么还要用Docker Desktop因为我们要部署的是模型网关。扣子智能体默认用平台自带的模型但你可以配置成调用外部模型外部模型接口通常是OpenAI兼容格式。为了让扣子安全稳定地调到DeepSeek就要先把DeepSeek的API Key托管在一个网关服务里这个网关才是在本机用Docker跑起来的东西。1.2 DeepSeek的模型服务从哪里来DeepSeek和OpenAI一样对外提供API服务。你注册账号、充值、拿到API Key之后就能通过https://api.deepseek.com这个地址调用大模型。关键点在于DeepSeek的接口兼容OpenAI的调用格式。这带来的好处是几乎所有支持OpenAI格式的网关、平台、Agent框架都能直接填DeepSeek的地址和Key来使用。这也为后面扣子接入DeepSeek提供了可能——只要网关能统一转发扣子那边就不用关心真正的模型厂商是谁。DeepSeek官方API的基础参数整理如下项目值Base URLhttps://api.deepseek.comOpenAI兼容地址为https://api.deepseek.com/v1模型名deepseek-chat对话/deepseek-reasoner推理API格式OpenAI Chat Completions密钥类型Bearer Token提示deepseek-reasoner是推理模型适合复杂逻辑任务但响应时间明显比deepseek-chat长。如果只是做普通对话智能体用deepseek-chat就够了。1.3 Docker Desktop在本方案里真正承担的任务在我们这套链路里Docker Desktop的作用是跑一个叫One-API的开源网关。它的核心能力就三件事把DeepSeek的API Key统一托管不用到处明文填写提供统一的OpenAI兼容出口所有第三方平台包括扣子只认这个网关地址记录每次调用的Token消耗、请求日志方便排查问题用Docker Desktop而不是直接裸跑One-API理由也很实际环境隔离、一键启停、不污染Windows的系统环境后续想升级网关版本一条命令重新拉镜像即可。Windows上做这类中间件部署Docker Desktop是最省心的方案。1.4 整体调用链路图用文字描述一下最终效果你看完就知道每一步在干嘛了用户在扣子平台创建的智能体发起对话请求 ↓ 扣子云端根据模型配置把请求发到指定Base URL ↓ Base URL指向你部署的One-API网关 ↓ One-API收到请求做鉴权校验Token、查渠道DeepSeek配置 ↓ One-API转发请求到 https://api.deepseek.com ↓ DeepSeek返回结果One-API记录日志原路回传给扣子这里有一个所有初学者都会忽略的点扣子在云端网关在本地Windows两者之间必须网络互通。扣子没法直接访问你电脑上的localhost:3000所以生产环境要把网关暴露到公网或者直接部署到一台有公网IP的服务器上。本地Docker Desktop更多承担的是开发调试和流程验证的角色这点后面细说。2. Windows环境准备虚拟化、WSL2与Docker Desktop安装的连环坑Windows上装Docker Desktop卡住的概率远比你想象的高。大部分报错都集中在虚拟化没有开启、WSL2内核版本不对、Hyper-V冲突这几类。这一章把完整链路捋一遍每步都解释为什么避免你装到一半去网上翻各种过时教程。2.1 确认CPU虚拟化是否开启任务管理器检查Docker Desktop在Windows上跑容器底层依赖虚拟化技术。要么走Hyper-V要么走WSL2后端两者都需要CPU虚拟化指令VT-x或AMD-V处于开启状态。打开任务管理器切到性能标签点CPU看右下角的虚拟化字段。如果显示已启用继续下一步如果显示已禁用需要重启电脑进BIOS开启。各品牌主板BIOS里虚拟化开关的位置大同小异常见路径如下IntelAdvanced → CPU Configuration →Intel Virtualization Technology→ EnabledAMDAdvanced → CPU Configuration →SVM Mode→ Enabled部分笔记本Security → Virtualization →Intel VT-x / AMD-V→ Enabled开启之后进系统再验证一次确认虚拟化状态变成已启用再往后走。这一步不做Docker Desktop启动时会直接报Virtualization support was not detected那是浪费时间最多的一个坑。2.2 安装WSL2的正确顺序Docker Desktop官方推荐使用WSL2后端原因很简单启动快、内存占用比Hyper-V虚拟机小、和Windows文件系统集成更好。安装WSL2的坑多半出在顺序上。正确做法是用管理员权限打开PowerShell先装WSL本身再设置默认版本为2最后装内核更新包。分开跑三条命令# 安装WSL并默认启用WSL2 wsl --install # 查看当前WSL版本 wsl -l -v如果是老系统wsl --install可能不支持那就分步执行先启用适用于Linux的Windows子系统和虚拟机平台两个Windows功能重启后再安装WSL2内核更新包最后执行wsl --set-default-version 2。提示装完wsl --install后如果提示操作成功完成需要重启务必重启一次再装Docker Desktop。否则Docker识别不到WSL内核照样报错。2.3 Docker Desktop安装与设置要点从Docker官网下载Docker Desktop for Windows安装包双击安装。安装过程中会问使用哪种后端选Use WSL 2 instead of Hyper-V。安装完成后打开Docker Desktop的设置界面在Resources → WSL Integration里确认要集成的是哪个发行版。如果你只是跑容器默认的docker-desktop发行版就够了如果你后面想在WSL终端里直接敲docker命令再把对应的Linux发行版开关打开。这套组合下的配置建议配置项建议值原因CPUs4核以上One-API转发本身不吃资源但网关日志和并发请求需要一点余量Memory4GB以上只跑One-API的话2GB就够但给多一点能避免OOMSwap1GB内存峰值保护Disk image size默认即可One-API镜像不到1GB设置里最容易被忽略的是NAT网络和端口映射。Docker Desktop默认会自动映射容器端口到宿主机但如果你装了防火墙软件或者公司电脑有网络策略3000端口可能没法从外部访问。这个在后面的网络排查章节专门说。2.4 最常见的启动失败报错与修复Docker Desktop启动失败报错信息千奇百怪但根因高度集中。把最高频的三种列出来你可以对着排查。报错一Virtualization support was not detected排查看这里任务管理器确认虚拟化是否已启用BIOS里是否开了VT-x/SVMWindows功能里虚拟机平台和Hyper-V是否都勾选报错二Docker Engine stopped / WSL kernel version too low一般是WSL2内核太旧。在PowerShell执行wsl --update更新完成后重启Docker Desktop。报错三端口被占用One-API默认监听3000端口。如果Windows上有其他程序比如开发用的前端调试服务已经占用了3000需要换端口。确认方法netstat -ano | findstr :3000有PID就说明端口被占可以改One-API的映射端口比如8080:3000。这章节提到的方法没有高深操作但每一步都踩得踏实能让你把基础环境一次弄好。3. 部署One-API网关统一托管DeepSeek Key的中间服务环境准备好之后真正的重头戏来了。One-API是目前很主流的大模型API网关部署方式简单、社区活跃也支持DeepSeek这种OpenAI兼容渠道。用它管DeepSeek Key后续扣子那边就不用直接接触真实密钥。3.1 为什么选One-API而不是直接在扣子里填DeepSeek地址我见过很多人的第一反应是DeepSeek本身就有公网API扣子里直接用官方地址不就行了干嘛多此一举装网关这个问题要分场景回答。如果你只是自己试一次确实不需要网关但如果你是团队协作、公司项目、或者准备把智能体接到实际业务里直接在业务平台里明文配置DeepSeek Key有几个隐患员工账号离职、平台权限泄露Key就跟着泄露而DeepSeek的Key一旦泄漏可能被外部刷量产生费用团队里多个人、多个智能体共用同一个Key出问题了很难定位谁在调用想统计每个应用/每个智能体的Token消耗官方控制台只能看全局没法细粒度拆分One-API解决的就是这三件事密钥托管、调用隔离、日志审计。扣子那边只需要知道网关的地址和网关生成的TokenDeepSeek真实Key永远不会暴露给任何使用端。3.2 编写docker-compose.yml启动网关在Windows本地随意找一个工作目录新建一个文件夹比如one-api在里面创建docker-compose.yml。内容如下version: 3 services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SQL_DSNoneapi:oneapi123tcp(db:3306)/oneapi depends_on: - db volumes: - ./data:/data db: image: mysql:8.0 container_name: one-api-mysql restart: always environment: - MYSQL_ROOT_PASSWORDroot123 - MYSQL_DATABASEoneapi - MYSQL_USERoneapi - MYSQL_PASSWORDoneapi123 volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306注意上面用的是默认的SQLite配置我简化一下One-API支持SQLite作为默认数据存储不需要额外部署MySQL。第一次使用建议用SQLite简单直接减少故障点。简化后的配置是这样的version: 3 services: one-api: image: justsong/one-api:latest container_name: one-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai volumes: - ./data:/data提示最新版本的One-API镜像名可能变为ghcr.io/songquanpeng/one-api如果拉取justsong/one-api:latest失败用docker pull ghcr.io/songquanpeng/one-api:latest拉取后替换镜像名即可。配置里的./data目录用于持久化数据后面你创建的渠道、令牌、日志都存在这里。容器删了也没关系数据不会丢。在one-api目录下打开终端执行docker compose up -d首次启动会拉镜像可能等几分钟。启动完成后浏览器访问http://localhost:3000看到登录页就说明网关起来了。默认管理员账号是root密码是123456。第一次登录后会强制修改管理员密码按提示走就行。3.3 首次登录、创建渠道、添加DeepSeek配置登录One-API后台后界面是英文可以点右上角头像在通用设置里把语言切为中文后续操作更顺。添加DeepSeek渠道的路径是渠道 → 新建渠道。关键参数如下配置项填什么说明类型OpenAIDeepSeek接口兼容OpenAI格式选这个即可名称deepseek-main识别的名字随便写Base URLhttps://api.deepseek.comDeepSeek官方接口地址模型deepseek-chat,deepseek-reasoner用逗号分隔多个模型写在一起API Key你的DeepSeek Key以sk-开头的真实密钥填完点击提交。注意模型这一栏必须填准确。DeepSeek官方模型名就是deepseek-chat和deepseek-reasoner不要自作主张改成别的。填错的话后面扣子调用时网关会报model not found。3.4 创建令牌并验证网关转发链路渠道配置好之后还需要创建一个令牌这个令牌就是扣子那边要用的密钥。路径是令牌 → 新建令牌。名字随便写比如coze-access过期时间建议选永不过期或按需设置额度留空即可。提交之后会得到一个形如sk-xxxxxxxx的令牌字符串这个值保存好后面配置扣子要用。验证转发链路是否通畅这一步很关键。在Windows终端执行curl http://localhost:3000/v1/chat/completions \ -H Authorization: Bearer sk-你的令牌 \ -H Content-Type: application/json \ -d {\model\: \deepseek-chat\, \messages\: [{\role\: \user\, \content\: \你好\}]}如果返回一段包含choices和content的JSON说明One-API成功把请求转发给了DeepSeek。如果报401或404优先检查令牌和模型名是否正确。这一步验证通过后网关层面的工作就完成了。接下来要做的是怎么让扣子用上这个网关。4. 在扣子COZE中配置DeepSeek模型把本地网关挂接上去扣子平台上的模型配置入口在不同版本里位置会有一点差异但大方向都是进入某个智能体的编辑页在模型选择区域找到自定义模型或添加模型服务然后填网关地址。4.1 扣子平台的自定义模型入口登录扣子平台国内版www.coze.cn进入工作台新建或打开一个智能体。在智能体编排页面左侧能看到模型的设置区域默认选中的是豆包各版本模型。这里注意找**添加模型、自定义模型或者管理模型**的入口不同界面版本名称不完全一样。我这边实操的时候入口藏在模型下拉框的最底部有一个添加自定义模型OpenAI兼容的选项。点进去会让你填三样东西模型名称填写deepseek-chatBase URL填写网关的调用地址API Key填写在One-API里生成的令牌4.2 配置模型名称、Base URL与API Key这里要特别强调一下网关地址到底该填什么这是最容易出错的地方。如果你只是本机测试扣子看不到你电脑上的localhost所以你不能填http://localhost:3000/v1。你需要一个网络可达的地址。方案分两种第一种Docker Desktop部署在Windows同时把网关映射到内网IP先打开PowerShell查看本机内网IPipconfig找到IPv4 地址比如192.168.1.100。那么扣子里Base URL填http://192.168.1.100:3000/v1前提是Windows防火墙允许外部设备访问3000端口且扣子所在网络能访问到这台机器。如果扣子和Windows在同一个局域网比如公司内网部署这个方案可行。第二种在云服务器上用Docker部署One-APIWindows Docker Desktop负责开发调试生产用的网关放在有公网IP的云服务器上。服务器上装好Docker后执行同样的docker compose up -d然后把防火墙开放3000端口Base URL填http://服务器公网IP:3000/v1这是扣子云端真正能访问到的地址。国内云服务器记得在安全组里放行3000端口。API Key就是你在One-API后台创建的令牌例如sk-coze123456。4.3 模型权限与可用范围说明配置完成之后扣子智能体的模型列表里会出现deepseek-chat这个选项。选中它智能体的对话请求就会走你的网关转发给DeepSeek。这里有个现象需要提前解释你在One-API里创建的令牌可以选择绑定某个渠道、某个用户也可以不绑定。如果不做任何绑定这个令牌可以使用网关里所有渠道的所有模型。安全起见我创建令牌时习惯在额度一栏设一个限制比如$10防止有人拿这个令牌刷爆费用。5. 端到端实战搭一个智能体测试DeepSeek是否真正生效配置完成不等于能用端到端跑通才算数。这一步我会带你搭一个最简单的测试智能体并告诉你如何通过网关日志确认请求真的经过了你部署的服务。5.1 新建智能体并绑定自定义模型在扣子平台点击创建智能体名称随便填比如DeepSeek测试Bot。进入编排界面后在右侧模型区域选择刚才添加的deepseek-chat。如果换模型时报错最常见的提示是Invalid API key或Connection error。前者说明One-API令牌没配对后者说明扣子访问不到网关地址。这俩怎么排查后面专门说。5.2 对话测试与网关日志对照在扣子的预览窗口里发一句话比如帮我写一段Python快排代码。如果DeepSeek正常响应预览区会出现完整回答。此时去One-API后台的日志页面能看到一条新记录包含请求时间、模型名、Token用量、耗时。日志存在就说明链路通了。如果再严谨一点可以对比一下日志里的提交Token数和扣子界面显示的字数大致能算出一轮对话的消耗。日常使用这个功能用来做成本核算很方便。5.3 常见失败场景排查端到端调用失败无外乎下面几个原因按出现频率排序现象原因处理方案扣子提示Connection error扣子访问不到网关地址用http://公网IP:3000/v1确认安全组/防火墙放开3000端口提示Invalid API keyOne-API令牌错误去One-API后台复制完整令牌注意不要带多余空格提示Model Not Found模型名不匹配确认填的是deepseek-chat不是deepseek或DeepSeek-Chat提示Rate Limit / Quota ExceededOne-API令牌额度用完检查令牌额度设置改成不限或调大网关日志有请求但DeepSeek超时服务器出网不稳定在服务器上直接curl DeepSeek官方接口测试连通性超时问题时最常见的真实情况是云服务器访问DeepSeek的延迟高或者网络策略拦截。可以先在服务器上执行curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer sk-你的DeepSeek真实Key能返回模型列表说明出网正常问题只在上层转发。6. 稳定运行经验Windows宿主机、Docker与扣子的长期配合要点环境跑通只是第一步。真正让人头疼的是后面日常使用中的稳定性问题。这章的内容是我实际跑了几个星期之后沉淀下来的经验每一条都踩过坑。6.1 Docker Desktop的资源配额调整只跑One-API一个容器的话Docker Desktop默认的2GB内存配置是够用的。但如果你同一台机器上还跑了其他容器比如数据库、CMS、爬虫内存占用就会变得紧张。建议在Docker Desktop设置里把内存调到4GB以上并且把资源 → 高级里的Swap开到1GB。Docker Desktop在Windows上走的WSL2方案内存是动态分配的设置上限高一点不会导致Windows变卡只在容器真正需要时才占用。另外打开Docker Desktop的设置把启动时自动启动Docker Engine勾上。Windows重启之后One-API容器会自动跟着恢复不用每次手动点开Docker Desktop。这个细节能帮你省掉很多远程维护的麻烦。6.2 防火墙与网络访问控制One-API监听3000端口这个端口要暴露给扣子使用但也要防止被无关人员扫描到。如果你把网关部署在云服务器上安全组里白名单式放行扣子出口IP而不是对全网开放3000端口。如果你不确定扣子的出口IP段可以保守一点用一个复杂的API Key并且开启One-API的令牌IP限制功能只允许特定IP使用这个令牌。Windows本地调试时防火墙会弹窗询问是否允许Docker Desktop Backend监听端口要选择允许。如果之前误点了取消去Windows安全中心 → 防火墙和网络保护 → 允许应用通过防火墙里把Docker相关项改为允许。6.3 密钥管理与网关安全One-API后台的root管理员密码务必改成一个高强度密码。这个密码一旦泄露攻击者能拿到你配置的所有模型密钥包括DeepSeek真实Key。我个人的做法是管理员密码用密码管理器生成20位以上随机串DeepSeek真实Key只在One-API渠道配置里出现一次之后谁都不给给扣子用的令牌单独创建设置额度上限每季度轮换一次DeepSeek真实Key换Key时只在One-API后台改扣子那边不用动这样即使扣子那边的令牌泄露了别人也只是用你的网关转发请求顶多消耗令牌额度拿不到真实Key。最后再说一个很实用的经验One-API支持在令牌里设置模型指定也就是某个令牌只能用deepseek-chat另一个令牌可以用deepseek-reasoner。如果你开发环境和生产环境用同一个网关建议给每个环境建不同的令牌并限定模型范围。这样万一某个人误发了昂贵模型的调用费用只算在他自己头上不会牵连整个团队。这套Windows Docker Desktop COZE DeepSeek的组合装下来本质就是两件事先把Docker Desktop在Windows上伺候服帖再用One-API把DeepSeek的调用能力安全地暴露给扣子。流程不复杂但每个环节都有不少前置条件和隐含坑按着上面的节奏走能少走很多弯路。
