ARTICLE · 1148733
别再到处找 AI 工具了!Dify v1.17.1 手把手安装 + 实战,30 分钟拥有自己的智能体
想拥有一个能聊天、能联网、能操作文件、还能按流程自动干活的 AI 智能体，但又不想被各种商业产品按月割韭菜？ 开源界最火的 AI 应用开发平台 Dify 刚发布了 v1.17.1。这篇文章不讲虚的，从「为什么装」到「怎么装」再到「怎么用得顺手」，一步步带你跑通，最后还附上老司机才知道的避坑技巧。
建议先收藏，照着做一遍你就回不去了。
一、Dify 是什么？为什么值得装 v1.17.1？
Dify 是一个开源的 LLM 应用开发平台，你可以把它理解成「AI 应用界的乐高」：
可视化拖拽就能搭聊天机器人、RAG 知识库问答、复杂工作流； 内置 Agent 智能体，能调用工具、执行代码、联网搜索； 支持几乎所有主流模型（OpenAI、Claude、Gemini，以及国内各大模型和本地 Ollama）； 提供 API，做好的应用可以直接嵌进你的产品里。
而 v1.17.1（2026-09-10 发布） 是一次「表面补丁、内功大涨」的版本。它没有花里胡哨的大功能，却把最影响实际体验的几块硬骨头啃了下来：
🔐 知识库 API Key 可以绑定单个知识库了。以前一个 Key 能横扫整个工作区的所有知识库，现在可以做到最小权限，对接外部系统更安全； 📊 修好了一堆「悄悄污染数据」的文档解析 Bug：CSV 里的 00123不会再被变成123.0，空单元格不会变成nan，Notion 富文本、Excel 引号、URL 直读 PDF、网页抓取全部更可靠；🖱️ 工作流支持键盘方向键移动节点（按住 Shift 大步移动），多节点排版效率高很多； ✅ 人工确认（Human Input）工作流大量修复，表单提交后不再卡死，并且能正确放进循环 / 迭代节点里； 🧩 插件市场全新改版，上线了创作者主页，找插件更方便。
一句话总结：如果你要认真做 RAG 或 Agent，这个版本的「数据准确性」和「安全性」是质的提升，强烈建议升级 / 新装。
⚠️ 特别提醒（老用户必看）：如果你之前用的是 Dify 自带的 Weaviate 向量库，这次升级千万别直接
pull完就重启！自带 Weaviate 从1.27.0一口气跨到了1.39.2，中间隔了 12 个小版本，必须逐段升级，跳级可能永久损坏向量索引。全新安装、用外部 Weaviate 或其他向量库的同学不受影响。具体见文末第六节。
二、安装前准备
Dify 官方最推荐、对新手最友好的方式是 Docker Compose 一键部署。
1. 硬件要求
2. 软件要求
安装完成后，先确认 Compose 版本满足要求：
docker compose version
# 需要 >= 2.24.0
还会用到
git、curl、jq，一般系统自带；若提示 command not found，用包管理器装上即可。
三、正式安装（全新部署，5 条命令搞定）
第 1 步：克隆指定版本源码
直接拉取 v1.17.1 这个 tag：
git clone --branch 1.17.1 https://github.com/langgenius/dify.git
如果你想要「永远拉最新稳定版」的写法（可选）：
git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
第 2 步：进入 docker 目录
cd dify/docker
第 3 步：准备环境变量配置
cp .env.example .env
这一步会生成核心配置文件 .env。学习阶段用默认值就能跑起来，先不用改。
第 4 步：启动所有容器
docker compose up -d
首次启动会自动拉取镜像，需要耐心等几分钟。起来后会包含这些服务：
7 个核心服务： api、api_websocket、worker、worker_beat、web、plugin_daemon、agent_backend8 个依赖组件： weaviate、db_postgres、redis、nginx、ssrf_proxy、agent_ssrf_proxy、sandbox、local_sandbox
第 5 步：检查运行状态
docker compose ps
除了一次性任务 init_permissions 显示 Exited 属于正常外，其余容器都应该是 Up 或 healthy。
四、初始化账号 & 第一次登录
打开浏览器，访问管理员初始化页面：
本地环境： http://localhost/install服务器环境： http://你的服务器IP/install设置管理员邮箱和密码，完成初始化。
之后正式登录地址：
本地： http://localhost服务器： http://你的服务器IP
登录成功，你就拥有了一个完全属于自己的 Dify！🎉
五、新手学习路径：按这个顺序玩，进步最快
装好只是开始，别在几十个功能里迷路。推荐这条上手路线：
阶段 1：配好一个模型（地基）
进入 设置 → 模型供应商，任选一种：
有 OpenAI / Claude 等官方 Key：填进去即可； 想零成本体验：接入 Ollama 跑本地开源模型，或使用国内提供免费额度的模型供应商。
配好后，建议在「系统模型设置」里指定一个默认的推理模型 / 嵌入模型 / Rerank 模型，后面建应用就不用反复选。
阶段 2：做一个最简单的聊天助手
在首页创建 聊天助手（Chatbot），写一段系统提示词（比如「你是一个简洁的技术顾问」），直接在右侧调试。先感受「提示词 → 效果」的即时反馈。
阶段 3：搭一个知识库问答（RAG，Dify 的看家本领）
进入 知识库，上传几份 PDF / Markdown / CSV 文档； 选择分段方式和嵌入模型，等待索引完成； 在聊天助手里「关联知识库」，再提问——它就只会基于你的资料回答，还会给出引用来源。
💡 v1.17.1 的解析修复对这一步特别有用：产品编码、邮编、订单号这类带前导零的数据现在能被正确读取了。升级后建议把之前受影响的文档重新导入一遍（旧索引不会被自动修复）。
阶段 4：玩工作流 / Chatflow
Chatflow：面向对话场景，适合带知识库、工具调用的客服机器人； 工作流（Workflow）：面向自动化任务，适合「输入 → 多步处理 → 结构化输出」，比如批量总结、内容生成管线。
试着拖入「开始 → LLM → 结束」，再逐步加入知识检索、条件分支、代码节点、HTTP 请求等。
阶段 5：玩转 Agent 智能体
v1.16 起 Dify 把 Agent 提升为一等公民，v1.17 又加入了 E2B 云沙箱、技能（Skills）、环境快照、上下文自动压缩 等能力。你可以创建一个能执行 Shell / 代码、调用技能、联网操作的智能体——这才是目前最接近「AI 员工」的形态。
阶段 6：发布与接入
做好的应用可以：
一键生成公开链接 / 嵌入网页； 通过 API 调用，接进你自己的系统； 用 difyctl 命令行直接触发应用和工作流，方便做自动化。
六、使用技巧 & 避坑指南（老司机精华）
1. 自定义配置：分清两个文件
核心启动参数在 docker/.env，直接编辑；各供应商 / 组件的可选配置模板在 docker/envs/下，把对应.example复制一份、去掉后缀再改。优先级： docker/.env的值高于任何docker/envs/*.env。
改完记得重启生效：
docker compose down
docker compose up -d
2. 生产 / 长期使用前，先改这几个值
SECRET_KEY：务必换成自己的随机密钥，别用默认值：openssl rand -base64 42涉及 Agent 的 PLUGIN_DAEMON_KEY、PLUGIN_DIFY_INNER_API_KEY、DIFY_AGENT_API_TOKEN等也都建议改成随机值；如需调整 Markdown 表单字段名长度，v1.17.1 新增了可配置项 MARKDOWN_FORM_FIELD_NAME_MAX_LENGTH（默认仍为 128）。
3. 升级前永远先备份
cd dify/docker
cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak
cp .env .env.$(date +%s).bak 2>/dev/null || true
tar -cvf volumes-$(date +%s).tgz volumes
4. ⚠️ 自带 Weaviate 的正确升级姿势
这是 v1.17.1 最容易翻车的地方：
适用对象：使用 Dify 自带 Weaviate 的自托管环境； 规则：从 1.27 开始，一个小版本一个小版本地升，每次用该小版本的最新补丁版，正常停止后再继续下一个，直到 1.39.2； Weaviate 官方同样建议「一次只跨一个 minor 版本」，并且升级到 1.26+ 时要先轮询 /cluster/statistics确认synchronized=true再继续；切勿在升级过程中强杀容器，否则可能损坏 HNSW 向量索引。
标准操作顺序（务必先看 Release 页面里 1.17.1 的专属升级指南）：
# 1) 先完成 Weaviate 的分段迁移（按官方文档逐段执行）
# 2) 再切换 Dify 版本
git fetch --tags
git checkout 1.17.1
docker compose down
docker compose up -d
全新安装、外部 Weaviate、或使用 Qdrant / Milvus / pgvector 等其他向量库的同学：可以忽略此条，直接正常安装。
5. 资源不够？关掉用不上的组件
学习环境如果内存紧张，可以在 Compose 里只保留必要服务（如 api、worker、worker_beat、web、plugin_daemon、sandbox + 数据库三件套），或改用更轻量的外部向量库。
6. 日常运维速查
docker compose ps # 查看状态
docker compose logs -f api # 跟踪某个服务日志
docker compose restart api # 重启单个服务
docker compose down # 停止全部
docker compose up -d # 启动全部
七、写在最后
v1.17.1 看起来只是一次小版本更新，但它折射出 Dify 的进化方向：从一个可视化工作流 / RAG 工具，变成一个能部署持久 AI Agent 的完整平台——带工具、能执行代码、有可复用技能、有 RAG、有可观测性，还有越来越细的企业级安全边界。
对普通学习者来说，它依然是目前「门槛最低、上限极高」的 AI 应用平台：一台机器、几条命令，一个下午就能拥有属于自己的智能体。
动手装一遍吧，纸上得来终觉浅。装好后欢迎回来聊聊你用它做了什么有意思的应用 👋
Dify社区群：嗨聊吧
欢迎扫码加入嗨聊吧！