Dify 在 Windows 11 上自托管:一步步接入 QCode(13 张截图)

在 Windows 11 上用 Docker Desktop 跑起 Dify,并把 QCode 接成 OpenAI 兼容模型:13 张带编号的截图,从安装到收到第一条回复。

更新于 2026-11-23

需要 API Key? 前往注册 →端点与 Base URL →

本页目录

一句话答案:在 Dify 里打开 Integrations → Model Provider,安装 OpenAI-API-compatible 插件,然后点 Add Model,填入接入地址 https://api.qcode.cc/openai/v1、模型名 gpt-6.2-sol、你的 cr_ 密钥,补全模式选 Chat。

项目 填写
要安装的集成 OpenAI-API-compatible
API Base URL https://api.qcode.cc/openai/v1
模型名(Model Name) gpt-6.2-sol
模型类型 / 补全模式 LLM / Chat
API 密钥 cr_xxxxxxxx

核对于 2026-11-22 · Dify 1.20.0 · Windows 11

照着下面 13 张截图在 Windows 11 电脑上做一遍,最后你就能在 Dify 里用上 QCode:Studio 里有一个 Chatbot 应用,能回答你的第一条消息。Dify 本身不需要任何模型厂商账号 —— 这里唯一的凭证就是一把 QCode API 密钥。

  • 适用系统:Windows 10 / 11(64 位),装有 Docker Desktop 和 WSL 2;截图演示的是 Windows 11
  • 软件版本:Dify 社区版 1.20.0 + OpenAI-API-compatible 插件 0.0.87
  • 截图更新于:2026-11
  • 预计用时:约 25 分钟,另外还要算上第一次下载 Docker 镜像的时间
  • 需要准备:一把 cr_ 开头的 QCode API 密钥

在开始第一张截图之前,先确认你已经具备这些:

  • 一台 64 位、能上网打开网页的 Windows 10 或 11 电脑,至少给 Docker 留出 2 个 CPU 核心和 4 GiB 内存
  • 一个浏览器 —— Edge 或 Chrome —— 因为 Dify 没有桌面应用;整个教程都在浏览器标签页里完成
  • 一个能登录的 Dify 实例:你自己在 http://localhost:8080 上用 Docker Compose 部署的那一个,或者 cloud.dify.ai 上的 Dify Cloud
  • 从控制台复制好的 QCode API 密钥(cr_xxxxxxxx);这是唯一不能跳过的一项。还没有账号?先注册,在定价页选一个方案,再到控制台创建密钥。

下载与安装 Dify

Dify 是 Web 服务,所以 Dify 界面没有 Windows 安装包。你要么在浏览器里打开 Dify Cloud,要么用 Docker Compose 在本机跑同一套界面。两条路最后都会落到下面步骤用的同一个 Model Provider 页面。按你所在的位置选对应的标签页:

打开 dify.ai 走 Cloud 路线:界面就在 cloud.dify.ai,电脑上什么都不用装。

如果想把界面放在自己机器上,就打开 docs.dify.ai 上的官方 Docker Compose 指南,配合 Docker Desktop 照着做。先从 docker.com 装好 Docker Desktop。如果页面加载慢或者下载卡住,等一分钟再重新开始 —— 页面和安装包由同一个主机提供,过一会儿重试通常两个问题都解决了。

打开 dify.ai 走 Cloud 路线:在 cloud.dify.ai 注册,整个教程都在浏览器里完成。

要做本地部署,就打开 docs.dify.ai 上的官方 Docker Compose 指南,从 docker.com 安装 Docker Desktop(Windows,x64),接受协议并保持 Use WSL 2 后端。安装程序需要管理员权限,通常还会要求重启。这个指南的仓库里也有 GitHub Releases,其中 Windows 文件 difyctl-v1.20.0-windows-x64.exe 是给管理员用的命令行工具 —— 它不是 Dify 界面,所以别指望双击后会开窗口。docker compose up -d 之后,界面在 http://localhost:8080。

先看一遍系统需求页

在下载任何东西之前,先打开官方的 Docker Compose 指南。① 页面标题确认你打开的就是 Docker Compose 自托管页;② 先决条件区块列出了这台机器必须具备的条件:至少 2 个 CPU 核心、4 GiB 内存,以及 Docker Compose 本身。

官方 Dify Docker Compose 自托管指南,顶部是页面标题,下方是硬件与软件先决条件区块

做对了你会看到:① Docker Compose 安装页的标题,② 先决条件列表里 CPU、内存和 Docker Compose 那几行能在一屏内看清。

卡住了?页面显示的是别的安装方式

Dify 把 Docker Compose 和 Kubernetes 并列写在文档里,搜索结果有时会落到 Kubernetes 那一页。滚到页面顶部,确认地址里带 docker-compose,那才是本教程要走的路线。

安装 Docker Desktop

Dify 在 Windows 上跑在容器里,所以要先装 Docker Desktop。在 docker.com 上点 ① Download Docker Desktop,运行下载下来的 Docker Desktop Installer.exe,接受协议,并保持选中 Use WSL 2 后端。安装程序会请求管理员权限,通常还会提示重启,照做即可。

官方 Docker Desktop 下载页,页面上是 Download Docker Desktop 按钮

做对了你会看到:下载从 ① 的按钮开始;装好之后通知区域出现鲸鱼图标,状态是 Engine running。

卡住了?Windows 弹出“Windows 已保护你的电脑”

点 More info,再点 Run anyway。SmartScreen 对那些它见得不够多的安装包会弹这个框;这个文件就是刚才 ① 按钮下载下来的。

登录你的 Dify 实例

在浏览器里打开 http://localhost:8080。第一次访问会跳到 /install 页面,用邮箱和密码创建管理员账号;之后再访问就直接进登录页。在 ① 里填邮箱和密码,然后点 ② Sign in。

自托管 Dify 实例的登录页,包含邮箱、密码输入框和 Sign in 按钮

做对了你会看到:① 两个输入框都填好了,密码显示为一串圆点;② Sign in 变成蓝色;点下去之后进入 Dify 首页,左上角显示工作区名称。

卡住了?浏览器提示无法访问此网站

容器还没起来。打开 Docker Desktop,等状态变成 Engine running,然后在 Dify 源码目录里执行 docker compose up -d,再刷新页面。第一次启动要拉好几个镜像,会慢一会儿。

打开 Integrations

登录之后进入 Dify 首页。整套导航都在左侧一列自上而下排列:Home、Studio、Agents、Knowledge、Contacts、Skills、Integrations、Marketplace。点 ① Integrations,Dify 会直接带你进 Model Provider。

Dify 首页,左侧是导航栏,Integrations 一项被高亮

做对了你会看到:① 左侧的 Integrations 高亮,后面的页面标题是 Model Provider,顶部有一个 Search models... 搜索框。

搜索 OpenAI-API-compatible 提供商

Model Provider 列出了 Dify 能对接的所有集成。点 ① Search models... 搜索框,输入 OpenAI-API-compatible。② 匹配的卡片会出现在列表里,上面有蓝色的 Install 按钮。

Model Provider 页面,搜索框里输入了 OpenAI-API-compatible,下面列出匹配的提供商卡片

做对了你会看到:① 搜索框里是你的文字,② 一张名为 OpenAI-API-compatible 的卡片和它的 Install 按钮 —— 不是 OpenAI,那是另一个插件。

卡住了?搜索没有任何结果

只输入 OpenAI,再把列表往下滚。安装插件需要工作区拥有者或管理员权限,普通成员账号可能看得到卡片却没有 Install 按钮。装完之后先刷新页面,再重新搜索。

确认安装插件

在卡片上点 Install 不会立刻安装,而是弹出标题为 Install Integration 的对话框。核对对话框里的名字,然后点对话框底部 ① Install。Dify 随后会从它的 Marketplace 下载插件,需要几秒钟。

Install Integration 确认对话框,底部是蓝色的 Install 按钮

做对了你会看到:① 对话框自己关闭,OpenAI-API-compatible 卡片移动到 Configuration required 分组里。

卡住了?对话框一直转圈然后失败

插件是从 marketplace.dify.ai 拉的。换个标签页打开这个地址看看通不通;在公司网络或代理后面下载可能被拦掉,换一个网络重试通常就好了。

打开 Add model 对话框

装好的插件现在位于 Configuration required 下面,并带一行说明 Set up api-key or add model to use。点这张卡片右侧的 ① Add Model,QCode 的地址和密钥就是在这里填。

Configuration required 下的 OpenAI-API-compatible 卡片,右侧是 Add Model 按钮

做对了你会看到:① Add Model,点开后是一个名为 Add model 的对话框,上面有 Model Name、Model Type 和 API Key。

填模型名并选类型

在 ① Model Name 里输入 gpt-6.2-sol —— 这是 QCode 的模型 ID,必须一字不差地照抄。打开 ② Model Type 选 LLM。然后点 API Key 输入框,把 cr_ 开头的密钥粘贴进去;对话框会用圆点把它遮住。

Add model 对话框上半部分,Model Name 填了 gpt-6.2-sol,Model Type 是 LLM,API Key 输入框显示为圆点

需要 API Key?

还没有 QCode 账号的话,先注册。不想买月付套餐的话,先在按量包页面买一个包,然后到控制台创建密钥。把 cr_ 开头那一整串复制回来,粘到 cr_xxxxxxxx 的位置即可。

做对了你会看到:① gpt-6.2-sol 一字不差,② 类型字段是 LLM,API Key 里是一行圆点 —— 都不带引号。

填 QCode 的接入地址和补全模式

在对话框里往下滚。把 https://api.qcode.cc/openai/v1 填进 ① API Base URL —— 整条路径都要写进这个字段,包括 /openai/v1,末尾不带斜杠,也不要加 /chat/completions。② Completion mode 保持 Chat,然后点 ③ Add 保存并校验密钥。

Add model 对话框下半部分,API Base URL 里是 QCode 接入地址,Completion mode 是 Chat,旁边是 Add 按钮

做对了你会看到:① 地址以 /openai/v1 结尾,② 选中了 Chat,③ Add 关闭对话框而且没有红色报错行。

卡住了?保存时报 401 或 404

401 说明密钥被截断了,或者带了空格、引号 —— 回控制台重新复制,把整个字段重敲一遍。404 说明地址多写或少写了路径;必须正好是 https://api.qcode.cc/openai/v1。

确认模型已启用

点过 Add 之后,插件就离开了 Configuration required。点卡片下面的 Show Models 展开模型列表:① 出现 gpt-6.2-sol LLM CHAT 这一行,右侧的开关是打开的。然后点页面右上方工具栏里的 ② Default Models。

展开的 Show Models 列表,gpt-6.2-sol LLM CHAT 一行已启用,右上方是 Default Models 按钮

做对了你会看到:① 一行模型记录,写着 gpt-6.2-sol、LLM 和 CHAT,右侧开关已打开;② Default Models 是右上角的蓝色按钮。

把它设为默认系统模型

Default Model Settings 会以对话框形式弹出。第一行是 ① System Reasoning Model:打开它,在列表里选 gpt-6.2-sol,然后点 ② Save。

Default Model Settings 对话框,System Reasoning Model 已选择 gpt-6.2-sol,旁边是 Save 按钮

做对了你会看到:① System Reasoning Model 一行显示 gpt-6.2-sol;点 ② Save 之后,页面顶部的黄色提示条 Configure a default system model to run applications 会消失。

卡住了?这一行提示模型列表是空的

列表为空说明插件里还没有启用的模型 —— 退回上一步展开 Show Models,确认开关是打开的。在那个列表里被关掉的模型不会出现在这里。

创建一个 Chatbot 应用

打开左栏的 Studio,点 Create from Blank。一开始只提供 Workflow 和 Chatflow;点 MORE BASIC APP TYPES 展开其余类型,选 ① Chatbot。在 ② App name 里输入 QCode Assistant,然后点 ③ Create。

Studio 的 Create from Blank 卡片,已展开 MORE BASIC APP TYPES,选中 Chatbot 类型,应用名是 QCode Assistant,旁边是 Create 按钮

做对了你会看到:① 选中后 Chatbot 带蓝色边框,② 名称字段里是 QCode Assistant,③ Create 打开新建的应用。

卡住了?没有 Chatbot 这个选项

Chatbot 默认是折叠起来的:点两张卡片下面的 MORE BASIC APP TYPES,Chatbot、Agent 和 Text Generator 就会出来。另外确认当前页面是 Studio 而不是 Agents。

发第一条消息并检查回复

创建应用后会打开 Orchestrate 页面。① 顶部的模型选择器已经显示 gpt-6.2-sol CHAT。在 Debug & Preview 底部 ③ 的 Talk to Bot 输入框里输入 Hello! Please introduce yourself in one sentence.,按 Send;② 回答会流式写进上面的面板。

Orchestrate 页面,页头是 gpt-6.2-sol CHAT,下方是 Talk to Bot 输入框,Debug and Preview 里有一条流式回复

做对了你会看到:① 页头显示 gpt-6.2-sol CHAT,③ 输入框里是你的那句话,② 一段简短的英文回答逐词出现 —— 不是 401、404 或“找不到模型”的报错。

卡住了?回答一直不开始

再打开 Default Model Settings,确认 System Reasoning Model 里仍然是 gpt-6.2-sol;在保存默认模型之前创建的应用启动时是没有模型的。如果回复是红色的,说明密钥或地址写错了 —— 见下面的常见报错。

验证是否成功

下面四条全部对上,就说明配置完成了:

  • Model Provider 的已安装集成里列着 OpenAI-API-compatible,并且在 Show Models 里启用了 gpt-6.2-sol。
  • Default Model Settings 里 System Reasoning Model 显示的是 gpt-6.2-sol,而不是空行。
  • QCode Assistant 能在 Debug & Preview 里回答,回复是流式到达的,而不是 401、404 或“找不到模型”。
  • 关掉浏览器标签页再打开 Dify,模型、默认设置和应用都还在。

全部完成

你已经把 QCode 接进了 Dify,并且有一个 Chatbot 应用通过它在回答。接下来可以:

常见报错

报错原文 原因 怎么办
Set up api-key or add model to use 插件已经装好,但还没往里加模型,所以 Dify 没有可选项 打开 Model Provider,在 OpenAI-API-compatible 卡片上点 Add Model,把四个字段都填好
Configure a default system model to run applications 有模型,但没选默认模型,新建应用启动时就没有模型 点右上角的 Default Models,把 System Reasoning Model 设成 gpt-6.2-sol,再点 Save
401 密钥已经到 QCode 但被拒绝:复制时带了空格、引号,或者只复制了一部分,也可能所属套餐已经结束 回控制台重新复制 cr_ 密钥,原样粘进 API Key,不要多加任何字符,并在控制台确认套餐状态
404 地址多写或少写了路径,QCode 收到的是它不提供的请求 API Base URL 必须正好是 https://api.qcode.cc/openai/v1 —— 末尾不带斜杠,也不带 /chat/completions

常见问题

需要 Dify 账号,还是 Anthropic、OpenAI 账号?

不需要任何模型厂商账号。Dify Cloud 要的是 Dify 账号;自托管实例要的是你在 /install 页面创建的管理员账号。两种情况里,真正到模型这一端的密钥都是你的 QCode cr_ 密钥,本教程没有任何一步要求登录 Anthropic 或 OpenAI。

列表里为什么找不到 OpenAI-API-compatible?

通常是三种原因:搜索框里还留着更长的词(只输入 OpenAI,再往下滚)、插件已经装过所以从页面的 Marketplace 部分移走了、或者这个账号不是工作区拥有者或管理员,而安装插件需要该权限。重新搜索之前先刷新一次页面。

模型名为什么必须是 gpt-6.2-sol?

Model Name 不是标签 —— Dify 会把这个字符串当作模型 ID 发给 QCode。QCode 的模型 ID 必须与 QCode 文档里列出的写法完全一致,所以 gpt-6.2-sol 能用,GPT 6.2 Sol 不行。同一个接入点提供的其他 ID 也填在同一个字段里,比如 gpt-6.2-astra。

在 Dify 里能通过 QCode 用 Claude 模型吗?

可以,走 Dify 自带的 Anthropic 集成,把 OpenAI 兼容地址换成 Anthropic 兼容地址 https://api.qcode.cc/api。那里的 QCode 默认模型是 claude-opus-5-5。本页 13 张截图走的是 OpenAI-API-compatible 插件,因为这是本教程完整覆盖的路线;Anthropic 地址可以当作以后要用的选项。

密钥到期后会怎样?

取决于你买的是什么。个人套餐附带的密钥不能续期 —— 需要重新开通套餐、创建一把新密钥,再粘贴到 API Key 字段里。按量包的密钥在再买一个包之后就会恢复:同一把密钥继续可用,Dify 里什么都不用改。

Dify 重启后会保留模型设置吗?

会。模型、它们的密钥以及默认模型都存在 Dify 数据库里,而不是浏览器会话里,所以退出登录或重启容器都不会把它们清掉。只有删除数据卷才会清空,而那同时也会删掉管理员账号和所有应用。

补全模式该选 Chat 还是 Completion?

用 Chat。QCode 在这个接入点上提供的是 chat-completions 系列模型,而 Completion 期望的是 prompt-completion 接口,这些模型并不提供。这里选错会直接在 Add 时报错,而不是等到应用里才暴露。

该用哪些模型

同一把 QCode 密钥可以使用多个厂商的模型,模型 ID 填进 Model Name。挑一个,其余字段保持不变。

模型 协议与地址 适用场景
gpt-6.2-sol OpenAI 兼容 —— https://api.qcode.cc/openai/v1 本教程的默认选择:日常对话、写作、代码问题
gpt-6.2-astra OpenAI 兼容 —— https://api.qcode.cc/openai/v1 GPT 系列更高一档,用于最难的 Agent 任务
claude-opus-5-5 Anthropic 兼容 —— https://api.qcode.cc/api Claude 旗舰,用于长推理和大规模重构
claude-haiku-5-5 Anthropic 兼容 —— https://api.qcode.cc/api 轻量 Claude,用于快速、便宜的回答

把 claude-* 的 ID 发到 OpenAI 兼容接入点会被拒绝,把 gpt-* 的 ID 发到 Anthropic 接入点同样会被拒绝 —— 模型家族必须和地址匹配。最新的 ID 列表在控制台里。

地址是怎么用的

API Base URL 是基地址,不是完整的请求路径。Dify 会保留 /openai/v1 这一段,自己再拼上 chat/completions,所以这个字段必须停在 /v1。

字段 值 说明
API Base URL https://api.qcode.cc/openai/v1 保留 /openai/v1,末尾不带斜杠
Dify 实际请求的地址 https://api.qcode.cc/openai/v1/chat/completions 由上面的字段自动拼出来 —— 不用手输
Model Name gpt-6.2-sol 该接入点上提供的任意模型 ID
Model Type LLM 负责应答聊天请求的类型
Completion mode Chat 不是 Completion
API Key cr_xxxxxxxx 与模型存在一起,所以只需填一次

备用接入点

如果默认主机在你的网络里很慢或者不通,只换域名,地址其余部分保持不变:

接入点 OpenAI 兼容基地址 Anthropic 兼容基地址
默认 https://api.qcode.cc/openai/v1 https://api.qcode.cc/api
亚洲 https://asia.qcode.cc/openai/v1 https://asia.qcode.cc/api
北美与欧洲 https://us.qcode.cc/openai/v1 https://us.qcode.cc/api

两个备用主机接受同一把密钥和同样的路径。如果换了主机,就在模型卡片上改 API Base URL,再点一次 Add 校验。完整说明见接入点与 API 路径。

自托管注意事项

  • Windows 需要 Docker Desktop 加 WSL 2。 Dify 仓库是一组服务,而不是一个双击就能运行的程序;Docker Desktop 负责把它们跑起来,指南要求至少 2 个 CPU 核心和 4 GiB 内存。
  • 源码放在 Linux 文件系统里。 Dify 目录放在 WSL 2 里而不是 C:\ 上时,性能和文件权限的表现都更好。
  • 第一次启动很慢。 首次启动要拉好几个容器镜像,在 API 容器报告就绪之前页面一直是空白。之后的启动只要几秒。
  • http://localhost:8080 是界面,不是 API。 Dify 本身不需要为浏览器下载任何东西;这个端口由容器提供。
  • Dify 界面语言和浏览器无关。 它是在账号菜单的 Preferences → General → Display Language 里切换的;本教程使用英文界面,所以这里每个标签都和截图一致。

相关文档

开始使用 QCode

一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models

企业团队版 →