Dify 本地工作流跑通后我用 cpolar 给团队开了一个临时验收入口Dify 在本机跑起来不难真正麻烦的是验收。你在浏览器里已经能点通工作流API 也能 curl 成功但产品、测试、后端同事看不到你的本地页面。截图只能证明“我这里能跑”不能证明“团队能按真实流程验收”。我的做法很简单Dify 继续跑在本机 Docker 里只把 Web 页面或 API 端口通过 cpolar 开一个短时 HTTPS 地址。团队拿到链接后直接验收应用表单、工作流节点、知识库引用、API Key 调用和错误日志。验收结束关闭 cpolar公网入口马上失效。这篇只做一个工程闭环本地 Dify 可运行、最小工作流可调用、cpolar 临时 HTTPS 可验收、安全边界说清楚。适用场景这套流程用在这些场景里很顺手AI 应用还在内测阶段不想为了半小时验收单独买云服务器和域名Dify 工作流已经在本地调通需要产品同事亲自填表验证输出后端同事要用 HTTPS 地址联调 Dify API而不是看你贴一段 curl 结果测试同事要复现异常输入、超时、空参数、知识库无命中等边界公司内网机器能跑 Docker但外部团队成员临时访问不到验收数据已经脱敏只开放测试应用和测试 token这里的重点不是“把 Dify 长期挂到公网”而是“给团队一个短时间、可回收、能真实操作的验收入口”。最终效果跑完以后你会得到三类地址Dify 本地控制台http://127.0.0.1Dify 本地 APIhttp://127.0.0.1/v1/workflows/runcpolar 临时 HTTPS形如https://xxxx.cpolar.top团队验收时的访问链路是这样同事浏览器 / 后端服务 | | HTTPS v cpolar 临时公网地址 | | 隧道转发 v 本机 Docker 里的 Dify Web / API产品同事打开 HTTPS 页面验收应用交互后端同事用同一个 HTTPS 域名调用/v1/workflows/run你在本机看 Dify 控制台、容器日志和调用记录。验收结束后按CtrlC停掉 cpolar或者执行docker compose down停掉 Dify。外部链接随即失效。环境准备本文命令以 macOS / Linux 终端为例。Windows 用户在 WSL2 里执行也能跑通。需要准备这些东西DockerDocker Compose v2Gitcpolar 客户端和 authtoken一个可用的模型供应商配置比如 OpenAI 兼容接口、通义、智谱、硅基流动或者本地 Ollama先检查 Dockerdocker --version docker compose version检查 Gitgit --version准备一个工作目录mkdir -p ~/dify-local-acceptance cd ~/dify-local-acceptance如果你准备用本地 Ollama 给 Dify 提供模型先确认 Ollama 能访问curl http://127.0.0.1:11434/api/tags如果你用云端模型供应商手里要有测试 Key。这里强调“测试 Key”不要把生产 Key 拿来做验收。Docker 启动 DifyDify 官方仓库已经准备好 Docker Compose 配置直接拉代码启动。cd ~/dify-local-acceptance git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d第一次启动会拉取多个镜像耗时和网络有关。启动后查看容器状态docker compose ps正常情况下能看到api、worker、web、db、redis、nginx等服务处于运行状态。再看一下端口docker compose ps nginx默认配置会通过 nginx 暴露 Web 入口本机访问open http://127.0.0.1Linux 服务器上没有open命令可以用curl -I http://127.0.0.1第一次打开 Dify会进入初始化页面。创建管理员账号后进入控制台。如果页面打不开先看 nginx 和 api 日志docker compose logs --tail100 nginx docker compose logs --tail100 api配置模型供应商进入 Dify 控制台后打开设置 - 模型供应商填入你的测试模型配置。如果使用 OpenAI 兼容接口通常需要这些字段API Key: 你的测试 Key API Base: https://你的模型服务地址/v1 Model: 例如 gpt-4o-mini、qwen-plus、deepseek-chat如果使用本地 OllamaDify 容器内访问宿主机不能直接写127.0.0.1。Docker Desktop 通常使用http://host.docker.internal:11434Linux 环境可以查宿主机网关ip route | awk /default/ {print $3}假设输出是172.17.0.1Ollama 地址就填http://172.17.0.1:11434配置完成后在 Dify 里点一次模型测试。测试通过再继续创建工作流。创建最小工作流和 API这里不做复杂 Agent也不接真实业务系统。我们只做一个最小工作流用来验证 Dify 的“表单输入 - LLM 处理 - 结果输出 - API 调用”。在 Dify 控制台里按这个路径创建工作室 - 创建空白应用 - 工作流应用名称可以写团队验收 Demo工作流节点按下面配置Start 节点新增一个输入变量变量名question 类型段落文本 必填是 标签验收问题新增 LLM 节点提示词写成这样你是一个企业内部 AI 应用验收助手。 请基于用户输入的问题输出三部分内容 1. 你理解到的需求 2. 需要补充确认的信息 3. 可执行的下一步动作 用户问题{{question}}模型选择前面已经配置好的测试模型。新增 End 节点输出变量选择 LLM 节点的文本结果例如answer LLM.text保存并运行一次输入我们要验收一个客服机器人重点看知识库命中和 API 调用稳定性。如果页面返回了结构化结果说明最小工作流已经跑通。接着发布应用进入 API 访问页面创建一个测试 API Key。为了后面命令统一把 Key 写入环境变量export DIFY_API_KEYapp-你的测试APIKey本地 API 调用命令如下curl -sS http://127.0.0.1/v1/workflows/run \ -H Authorization: Bearer ${DIFY_API_KEY} \ -H Content-Type: application/json \ -d { inputs: { question: 请帮我检查这个工作流是否满足团队验收要求 }, response_mode: blocking, user: acceptance-user-001 } | python3 -m json.tool返回里能看到data.outputs说明 API 也通了。如果你的 Dify 配置了非 80 端口把命令里的http://127.0.0.1换成实际本地地址。用 cpolar 开临时 HTTPS 验收入口本地页面和 API 都通了下一步就是把同一个入口临时给团队访问。安装 cpolar。macOS 可以用 Homebrewbrew tap probezy/core brew install cpolarLinux 可以使用官方安装脚本curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash配置 authtokencpolar authtoken 你的_cpolar_authtokenDify 默认通过本机 80 端口访问所以直接开 HTTP 隧道cpolar http 80终端里会出现一个 HTTPS 地址形如https://abcd-1234.cpolar.top把这个地址发给团队产品同事可以直接打开页面验收应用。后端同事调用 API 时把本地地址替换成 cpolar HTTPS 地址export DIFY_PUBLIC_URLhttps://abcd-1234.cpolar.top export DIFY_API_KEYapp-你的测试APIKey curl -sS ${DIFY_PUBLIC_URL}/v1/workflows/run \ -H Authorization: Bearer ${DIFY_API_KEY} \ -H Content-Type: application/json \ -d { inputs: { question: 通过 cpolar HTTPS 调用 Dify 工作流验证 API 是否可用 }, response_mode: blocking, user: acceptance-user-remote-001 } | python3 -m json.tool如果返回结构和本地一致公网 HTTPS 到本地 Dify 的链路就跑通了。团队验收时我会把测试项拆成下面几类验收项操作方式通过标准页面访问浏览器打开 cpolar HTTPSDify 页面可打开登录正常工作流输入填写question后运行输出包含需求理解、补充信息、下一步动作API 调用curl 调用/v1/workflows/run返回data.outputs异常输入传空字符串、超长文本Dify 有明确报错或可控输出日志排查查看容器日志错误能定位到 api、worker 或模型供应商看日志的命令cd ~/dify-local-acceptance/dify/docker docker compose logs -f api worker nginx安全边界要提前画清楚cpolar 解决的是“临时可访问”不是替你做完整生产安全体系。Dify 里经常有提示词、知识库、API Key、调用日志这些东西不能随便暴露。我会按这几个边界执行只开放测试应用不开放真实业务应用只使用脱敏输入不上传客户原始文档、合同、订单、手机号API Key 使用测试 Key验收后立即删除或轮换Dify 管理员账号使用强密码验收账号只给必要权限cpolar 只在验收窗口内运行不后台常驻不把 cpolar 链接发到公开群、论坛、工单截图里不开放数据库、Redis、对象存储、模型服务端口日志里出现 token、手机号、邮箱时验收后清理对应记录如果团队只需要验收 API就不要让所有人都登录控制台。直接给 API 文档、测试 Key 和验收用例即可。如果团队只需要看页面就不要把 API Key 发到多人群里。权限越少事故面越小。常见问题和排错1. Dify 容器启动失败先看容器状态cd ~/dify-local-acceptance/dify/docker docker compose ps再看失败服务日志docker compose logs --tail200 api docker compose logs --tail200 worker docker compose logs --tail200 db端口被占用时nginx 会起不来。检查 80 端口sudo lsof -iTCP:80 -sTCP:LISTEN如果本机已有 Nginx 或 Apache 占用 80编辑dify/docker/.env里的外部端口配置把 Dify 映射到另一个端口例如8080然后重启docker compose down docker compose up -d之后本地访问改成http://127.0.0.1:8080cpolar 命令也改成cpolar http 80802. 模型供应商测试失败先确认 Dify 容器能访问模型地址。以 OpenAI 兼容接口为例docker compose exec api sh -lc python - PY import urllib.request urlhttps://api.openai.com/v1/models requrllib.request.Request(url, headers{Authorization:Bearer YOUR_TEST_KEY}) try: print(urllib.request.urlopen(req, timeout10).status) except Exception as e: print(type(e).__name__, e) PY把YOUR_TEST_KEY换成测试 Key。这里能返回状态码说明容器出网没问题。401 代表 Key 或权限错误超时代表网络或代理问题。本地 Ollama 访问失败时重点检查地址不要写成容器内的127.0.0.1。Docker 容器里的127.0.0.1指向容器自己不是宿主机。3. API 返回 401401 基本就是认证问题。按顺序查echo $DIFY_API_KEY确认 Header 写法Authorization: Bearer app-xxxx再确认这个 Key 属于当前工作流应用不是另一个应用的 Key。Dify 的应用 Key 之间不能混用。4. 工作流页面能跑API 没输出检查请求体里的变量名是否和 Start 节点一致。Start 节点变量叫questioncurl 里就必须写inputs: { question: 你的问题 }如果写成query、text、promptDify 收不到预期变量输出就会异常。再检查 End 节点是否把 LLM 节点结果映射到了输出变量。没有 End 输出API 返回里就看不到想要的字段。5. cpolar 地址能打开页面但 API 调用超时先在本机调用一次curl -sS http://127.0.0.1/v1/workflows/run \ -H Authorization: Bearer ${DIFY_API_KEY} \ -H Content-Type: application/json \ -d {inputs:{question:本机 API 测试},response_mode:blocking,user:local-test}本机也慢就看 Dify 和模型供应商。公网慢本机快就看 cpolar 终端输出和网络链路。长输出工作流可以把响应模式改成 streaming但团队验收早期用 blocking 更容易定位问题。6. 知识库检索为空本文的最小工作流没有接知识库。如果你在正式验收里接了知识库按这几个点查文档是否完成索引检索节点是否接在 LLM 前面LLM 提示词里是否引用检索结果变量查询词是否和文档内容同一语言或同一术语文档是否过度脱敏导致关键词全被替换排查时用一段短文档做基准例如只放 5 条 FAQ。短文档能命中再换大文档。验收结束后关闭公网入口验收最容易被忽略的一步就是收口。cpolar 是前台运行时在终端按CtrlC外部 HTTPS 地址就会失效。如果你用的是后台服务方式运行 cpolar按你的系统停止服务。Linux 常见命令是sudo systemctl stop cpolar然后处理 Dify 里的测试凭据删除或轮换本次验收用的 Dify API Key删除临时测试账号清理包含敏感字段的调用日志移除脱敏不彻底的知识库文件把验收结论记录到团队文档里如果 Dify 本地环境也要停掉cd ~/dify-local-acceptance/dify/docker docker compose down保留数据但停服务用上面这个命令就够。连数据卷也清掉会删除数据库和上传文件这个动作要单独确认docker compose down -v写在最后Dify 的价值不只是“本地能打开一个 AI 应用”更关键的是让团队能围绕真实输入、真实工作流、真实 API 做验收。cpolar 在这里扮演的是临时通道本地继续本地Docker 继续 Docker只在需要验收的时间窗打开 HTTPS 入口。它不会把你的本地 Demo 变成生产系统也不该承担生产网关的职责。我的习惯是验收前准备脱敏数据和测试 Key验收中盯住日志和异常输入验收后关闭隧道并回收凭据。这个流程跑顺以后本地 AI 应用从“我这里能跑”到“团队验收通过”中间就少了很多扯皮。
