Dify新手入门安装保姆级教程：从下载到首次运行

关键配置：新手最容易忽略的几项设置

第一是访问地址。若仅在本机使用，可保持本地地址；若需通过浏览器从其他设备访问，应将控制台地址和服务地址设置为服务器的域名或 IP 加端口。地址配置不正确时，常见表现是页面能打开，但应用调用、文件预览或接口回调异常。

第二是端口占用。Dify 默认会占用 Web 服务、数据库、缓存等多个端口。如果本机已有其他服务占用相同端口，启动时可能失败。遇到这种情况，不要盲目关闭系统进程，先用端口查看命令确认占用来源，再修改 compose 文件或环境变量中的映射端口。

第三是密钥和密码。测试环境可先使用模板值，但正式使用前必须修改默认密钥、数据库密码及相关凭据。尤其是部署在可被外部访问的服务器时，默认配置会增加被扫描和误用的风险。建议严格控制 .env 文件的权限，不要上传到公开仓库，也不要截图传播。

启动服务：从命令到首次运行

配置完成后，在 docker 目录中执行 docker compose up -d 命令。该命令会在后台拉取镜像并启动多个服务，包括接口服务、前端页面、数据库、缓存、队列任务等。首次启动的耗时取决于网络与机器性能，镜像较多时等待几分钟属正常现象。启动过程中不要频繁中断命令，也不要同时修改配置文件，以免造成状态混乱。

启动后，可执行 docker compose ps 查看服务状态。如果大部分服务显示 running 或 healthy，说明基础组件已正常运行。随后在浏览器中访问配置好的地址，例如本地部署通常为 http://localhost/install 或对应端口页面。首次进入时，Dify 会引导创建管理员账号。建议使用专门的管理邮箱和强密码，避免与其他普通测试账号混用。

完成初始化后进入控制台，新手可先创建一个最简单的聊天应用。进入模型配置页面，添加模型提供方，填入密钥或接口信息，再回到应用中选择模型并进行测试。若能正常返回内容，说明 Dify 从安装、初始化到模型调用的主流程已成功跑通。

首次创建应用：用最小路径验证安装成功

新手不要一开始就配置复杂的知识库和多节点工作流，建议先用最小路径验证环境。操作顺序可为：创建应用，选择聊天助手类型；填写应用名称；在提示词区域写入清晰的角色说明；选择已配置的模型；点击调试窗口发送一句测试问题。此流程能同时验证前端页面、后端接口、模型连接及日志记录是否正常。

如需测试知识库功能，可先上传少量普通文档，观察解析、分段、索引和召回结果。文档测试建议使用无敏感内容的样例文件，不要直接上传客户资料、合同原件或内部名单等高危数据。知识库效果与文档结构、分段策略及嵌入模型质量相关，不能仅凭一次回答判断平台是否可用。

常见问题与排查方法

问题一：页面打不开。优先检查容器是否启动、端口是否正确、浏览器访问地址是否与配置一致。若部署在服务器上，还需确认安全组或防火墙是否放行对应端口。不能仅看命令是否执行成功，必须结合 docker compose ps 和容器日志进行判断。

问题二：容器反复重启。常见原因包括内存不足、端口冲突、环境变量配置错误、镜像版本不匹配等。可使用 docker compose logs 服务名 查看日志。新手排查时建议一次只修改一个变量，改完重启观察，避免多项改动叠加后难以定位问题。

问题三：模型配置后无法回答。检查密钥是否有效、模型名称是否填写正确、账户额度或服务状态是否正常、接口地址能否访问。有些模型服务区分聊天模型、嵌入模型和重排模型，若配置到错误位置也会导致应用无法运行。

问题四：上传文件失败或知识库无结果。检查文件大小限制、存储配置、后台任务队列是否正常，以及文档格式是否受支持。若解析时间较长，可先查看任务日志，避免重复上传大量文件导致任务堆积。

升级、备份与回滚建议

Dify 版本更新较快，新手切勿在没有备份的情况下直接升级。升级前至少备份 .env 文件、数据库数据、上传文件目录及自定义配置。若使用 Docker 部署，建议记录当前镜像版本和 compose 文件内容。生产环境中，最好先在测试环境验证新版本，再安排低峰时段进行升级。

升级的一般思路为：停止服务，备份数据，拉取新代码或更新镜像，检查环境变量模板是否新增配置，合并必要参数，再启动服务并观察日志。不要简单覆盖 .env 文件，这可能导致原有密码、访问地址或存储配置丢失。若升级后出现严重问题，应优先根据备份恢复数据和旧版本配置，而非在故障环境中连续尝试不确定的操作。

安全边界：哪些操作不建议执行

在将 Dify 暴露给多人使用前，需明确安全边界。不要使用默认密码，不要将管理后台直接开放给不相关人员，也不要在应用提示词或环境变量中写入高敏感密钥。团队使用时，应区分管理员、开发者和普通使用者的权限，定期清理不用的应用和密钥。

在数据方面，不建议将未脱敏的个人信息、商业机密或受合规约束的材料直接上传至测试环境。如需接入企业知识库，应先确认数据授权、访问范围、日志保留策略及模型服务的数据处理规则。此外，AI 应用输出也需人工复核，尤其在用于客服、合同摘要、医疗健康、财务分析等严肃场景时，不能将生成结果直接当作最终结论发布。

实用建议：帮助新手少踩坑

第一，先跑通本地最小示例，再进行复杂部署。安装、模型配置、知识库、工作流应分阶段完成。第二，保留安装记录，包括系统版本、Dify 版本、启动命令及修改过的配置项，这能在后续排错时节省大量时间。第三，养成查看日志的习惯，Dify 的许多问题都能在容器日志中找到明确线索。第四，正式使用前做好备份和权限规划，不要等到数据丢失或访问异常时才补救。

总体来看，Dify 的安装门槛并不高，关键在于理解它由多个服务共同组成，且需要外部或本地模型能力配合。只要按照“准备环境、下载配置、启动服务、初始化账号、接入模型、创建应用、验证日志”的流程操作，新手也能稳定完成首次运行，并为后续构建更复杂的 AI 应用打下坚实基础。