企业官网建设流程全解析

简介：适合具备一定编程基础、希望快速上手大模型应用开发的研发人员，以及希望通过低代码方式构建生成式AI应用的非技术背景读者。这份PDF指南以Dify开源平台为主线，讲清从系统环境检查、Docker与Docker Compose安装、Python版本确认，到克隆仓库、配置环境变量、启动服务并完成初始化的完整部署流程，并整理了常见部署问题与排错思路。资源为单文件PDF，压缩包约212KB，便于本地查阅与对照操作。文中还结合智能客服、文档问答等落地场景，演示如何借助可视化界面、RAG引擎和Agent工具提升回答准确性与应用扩展能力。该PDF已有323人学习，内容紧贴实战，适合在部署Dify时作为手边参考。

1. 为什么大模型应用部署最终选了 Dify：一个能跑通全链路的落地底座

大模型应用从 idea 到能 demo，中间隔着两条深沟：一是把模型 API 接进来之后，怎么处理对话记忆、知识库检索、工具调用这些工程问题，二是环境怎么搭才能让应用真正跑起来。Dify 这个平台把这两条沟填了大半——它提供可视化的应用编排界面，内置 RAG、Agent、工作流编排和 Prompt 管理，你只需要准备模型 API 密钥，就能在 Web 界面里把一个大模型应用从零搭起来并启动服务。本指南就是沿着 Dify 部署的真实操作路径：从硬件评估、Docker 环境准备，到 Compose 拉起服务，再到模型接入、应用创建和启动验证，把每条命令背后的原因和踩坑点拆开讲。适合两类人：一类是刚接触大模型应用开发、想在本地快速跑通全流程的初学者；另一类是已经在用其他框架、想评估 Dify 是否适合作为团队落地基座的技术选型者。读完你至少能自己部署一套可用的 Dify 环境，并理解启动服务时到底发生了什么。

2. 环境准备这么才算合格：硬件评估与 Docker 部署底座

2.1 先看硬件账面：Dify 最少需要什么样的机器

很多人在环境准备阶段翻车，不是因为命令敲错，而是机器配置根本没达到下限。Dify 不是单容器应用，它由 API 服务、Worker 进程、Web 前端、PostgreSQL、Redis、Sandbox 等多个组件构成，用 Docker Compose 一次性拉起。组件多，意味着内存吃紧。我实测下来，Dify 全量启动后空闲状态占用大约 2.5GB 到 3.5GB 内存，如果加载了嵌入模型或者知识库索引任务，内存峰值会到 6GB 以上。所以最低配置建议 4 核 CPU、8GB 内存、50GB 可用磁盘，其中磁盘大些没坏处——镜像本身占 3GB 左右，向量数据库、日志、上传文件都会持续增长。如果你只有 2GB 内存的机器，别硬上，后面启动服务时会频繁 OOM，连日志都来不及看。

提示：部署机器的操作系统建议选 Ubuntu 22.04 或 Debian 12，内核版本不要太老，否则 Docker 的 iptables 规则和网络模型会给你上一课。

2.2 补齐 Docker 与 Compose 环境：版本不对，后面全白搭

Dify 官方部署方式以 Docker Compose 为第一优先，版本要求相对明确：Docker Engine 20.10 以上，Docker Compose 插件 v2.0 以上。很多线上教程还在用docker-compose老命令，而新版 Dify 的docker compose.yaml里用了depends_on条件判断和 profile 特性，老版本 Compose 直接不认，报unsupported attribute。所以先确认版本：

docker --version docker compose version

如果 Docker 还没装，用官方脚本装最省事，然后配一下国内镜像加速。这一步很多人忽略，导致后面拉取 Dify 镜像时漫长到怀疑人生：

sudo curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun sudo systemctl enable --now docker sudo tee /etc/docker/daemon.json <<EOF { "registry-mirrors": ["https://docker.m.daocloud.io"] } EOF sudo systemctl restart docker

注意tee那条命令是把镜像加速配置写进 Docker 守护进程配置，写完后必须重启 Docker 才生效。没有这一步，拉langgenius/dify-api这类镜像时，网速会直接决定部署成败。装完确认一下docker compose version输出里有 v2 字样，如果只有docker-compose（带横杠）且版本是 1.x，说明你是旧版二进制，建议升级。我一般会顺手装上bash-completion，这样敲docker compose命令时有自动补全，排查问题时少敲很多字。

2.3 宿主机端口规划： 80 和 443 被占是第一个坑

Dify 默认的.env配置里，Nginx 容器监听 80 和 443 端口，API 服务监听 5000 端口。如果你的主机上已经跑了 Nginx、Apache 或者其他 Web 服务，80 端口冲突会让 Dify 的 Nginx 容器启动失败，表现是docker ps里看到 nginx 容器 Restarting，日志里报bind: address already in use。这时候要么停掉占用进程，要么改 Dify 的端口映射。

sudo lsof -i :80 -i :443 -i :5000 ss -tlnp | grep -E ':80|:443|:5000'

看到输出里有进程在监听，就得在.env里改端口，Dify 的 Compose 文件支持通过环境变量覆盖，一般是在.env里改成NGINX_PORT=18080之类的非特权端口，然后启动。这里有一个数据点供参考：某开发者第一次部署时没查端口，docker compose up 后 Nginx 反复重启，花了半小时才发现是主机上自带的一个监控面板占了 80。所以环境准备阶段把端口占用查清楚，比后面看日志猜原因快得多。

3. 部署 Dify：用 Compose 拉起全组件，每条命令都有讲究

3.1 下载源码与配置 .env：版本锁定比追新重要

Dify 的部署文件在 GitHub 仓库里，推荐的做法是直接 clone 仓库，而不是从 Releases 页面下载压缩包，因为.env.example和docker-compose.yaml之间的版本匹配关系，clone 能保证同步。先用--depth 1浅克隆，避免把整个历史拉下来浪费时间：

git clone --depth 1 https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env

这里dify/docker目录下才是 Compose 编排文件。.env.example是官方给的默认环境变量模板，copy 成.env后，所有配置都以.env为准，Compose 文件通过变量引用读取。.env里必看的关键变量包括：

• SECRET_KEY：API 服务的加密密钥，默认值可以直接用，但生产环境一定改成随机串
• POSTGRES_PASSWORD、REDIS_PASSWORD：数据库密码，默认是弱口令
• DEPLOY_ENV：默认PRODUCTION，别改成DEVELOPMENT，会多跑一堆调试组件
• SANDBOX_SERVICE_PORT：Sandbox 服务端口，默认 8194，一般不用动

检查完这些后，下一步是拉取镜像并启动。注意顺序：先 pull 再 up，因为 up 过程中会创建容器和网络，如果镜像没拉完就 up，部分容器会因镜像不存在而进入等待重试状态。

docker compose pull docker compose up -d

pull将 Dify 镜像仓库里的所有组件镜像拉到本地，up -d才是真正创建网络、卷、容器并后台运行。第一次跑的时候别加--build，除非你改了 Dockerfile 里的内容；平台默认是从镜像仓库拉取预构建镜像，不需要本地构建。启动后等 30 秒到 1 分钟，让数据库完成初始化和迁移。

3.2 验证服务状态：别信 docker ps 的 Up，信 healthcheck

服务启动后第一个动作是看容器状态，但这里有个非常容易误判的点：容器显示Up不等于服务健康。Dify 的 Compose 文件里 api、worker 等容器定义了 healthcheck，对应的是 HTTP 健康检查或 pg_isready 这类数据库探活命令。所以验证要分两步走：

docker compose ps docker compose logs --tail=200 api curl http://localhost/api/health

docker compose ps能看到每个容器的状态和健康程度，正常时 api 容器显示healthy，web 容器显示running。如果 api 一直显示health: starting，说明健康检查没过，多半是数据库还没准备好或者环境变量有误。这时直接看日志：docker compose logs --tail=200 api会输出 API 服务的启动日志，里面有 SQLAlchemy 建表语句和初始化信息。curl http://localhost/api/health是最终验证标准，返回{"status":"ok"}这类 JSON 才说明 API 服务真的起来了。我见过最典型的翻车是人类把docker compose ps里所有容器都显示 Up 当作部署成功，结果浏览器打开 80 端口是空白页，最后发现是 web 容器起来了但 API 没起来，反向代理转发不到后端。所以记住：容器状态只能说进程存活，健康检查才说服务可用。

3.3 数据目录与持久化：Volume 在哪里，后悔药就藏在哪里

Dify 的 Composer 文件里已经为 PostgreSQL、Redis、存储等定义了命名 Volume，数据默认落在 Docker 的 Volume 目录下。这意味着你重装容器或升级镜像时，数据还在 Volume 里，不会丢。但正因为数据在 Volume 里，很多人忽略备份，等真要迁移时才发现找不到数据文件。常见做法是不用 Docker 命名的 Volume，而是改成绑定挂载目录，把数据落到宿主机指定路径，备份和管理都更直观。

mkdir -p /opt/dify/{postgres,redis,storage}

然后编辑docker-compose.yaml，把 db 服务的 volume 从命名卷改成绑定挂载：

db: image: postgres:15-alpine volumes: - /opt/dify/postgres:/var/lib/postgresql/data

同样的思路可以应用到 redis 和 storage。这么做的好处是：以后执行docker compose down甚至docker compose down -v，数据目录都还在宿主机上，不会因为 -v 而清空 Volume。这里给一个直接经验：别轻易执行docker compose down -v，-v是删除 Volume，等于把数据库、Redis 缓存、上传的文件全清掉，没有后悔药。改绑定挂载相当于给自己的数据上了保险。

4. 模型接入与应用编排：从模型供应商配置到 Prompt 编排

4.1 接入模型供应商：大模型应用的“发动机”怎么接

Dify 部署完成只是空壳，没有模型接入，应用编排无从谈起。进入 Dify 后台后，找到「设置」→「模型供应商」，这里列出了 OpenAI、Anthropic、各种国产模型和本地模型服务。接入方式基本一致：填 API Key 和 Base URL。这一节最关键的选择是：按模型类型选供应商，还是按兼容协议选。

常见做法是优先看 Dify 是否原生支持该供应商——原生支持意味着 Dify 已经封装了该模型的特殊参数（比如 Anthropic 的思考模式和 Azure 的 API 版本）。但很多团队的模型是部署在私有网关上的，网关一般提供 OpenAI 兼容接口。这种情况下，在 Dify 里选OpenAI-API-compatible供应商，填网关地址和密钥即可。这里有个参数值得记录：

• API Key：网关分配的密钥，Dify 会加密存储在数据库中
• API Base URL：必须是网关暴露的完整路径，形如https://gw.example.com/v1
• Models：手动添加模型 ID，比如gpt-4o-mini或自部署模型的名称，必须和网关配置一致

配置完后界面会有一个「测试」按钮，点它能直接调模型接口。如果测试失败，先看是不是 Base URL 末尾多了或少了/v1，这是典型低级错误。Dify 对兼容模式的调用路径是拼在 Base URL 后面的，如果你填了https://gw.example.com/v1/chat/completions而网关实际期望https://gw.example.com/v1/chat/completions，一定会 404。正确填法是https://gw.example.com/v1，剩下的路径 Dify 自己拼。

提示：如果团队还没确定用哪家模型，可以在 Dify 里同时配置多家供应商。应用编排时按需切换模型，Dify 默认会记住每个应用当前选中的模型。

4.2 创建第一个应用：Chatflow、Workflow、Agent 选哪个

模型接入完成后，回到应用主页创建应用。Dify 提供了几种应用类型，新手最纠结的是选 Chatflow 还是 Workflow 还是 Agent。我给出一个简单的分流逻辑：

• Chatflow：面向对话交互场景，支持多轮记忆、知识库检索节点、条件分支。适合做客服机器人、AI 助手
• Workflow：面向自动化任务，输入是结构化数据，输出也是一个结果，比如文档分类、内容总结流水线
• Agent：适合需要模型自主决定调用哪些工具的场景，比如查天气、查订单，模型根据用户请求自动选工具

选 Chatflow 创建一个对话应用。进入编排界面后，左侧是节点面板，常见节点包括「开始」「LLM」「知识检索」「问题分类」「条件分支」「直接回复」「结束」。默认编排里有一个开始节点、一个 LLM 节点、一个结束节点，我们需要把中间链路补齐。

4.3 编排一个带知识库的 Chatflow：拖拽背后的数据流逻辑

以一个内部知识库问答助手为例，目标是从已有文档中检索相关内容，再由模型生成回答。先要做的事情是创建知识库：在「知识库」页面新建数据集，上传文档，Dify 会调用嵌入模型将文档切块并向量化。这里有一个关键参数：分段设置。默认的分段长度和分段重叠决定文档被切成多大的块，切得太大，检索召回精度断崖下跌；切得太小，向量化成本高且语义被割裂。我常用的经验值是中文文档分段长度 500 到 800 字符，重叠 100 字符左右。英文文档可以适当放大，按 token 估算 800 到 1000。

然后在 Chatflow 编排里按顺序连接节点：「开始」→「知识检索」→「LLM」→「直接回复」。知识检索节点里选中刚创建的知识库，设置TopK（返回 TopK 条相关结果）为 3 到 5，Score 阈值设为 0.5 左右。这一步的原理：TopK越大召回越多但噪音越大，Score 阈值过低会引入大量不相关内容，过高则容易查不到结果。LLM 节点里，上下文变量选择知识检索节点的输出，这样模型能基于检索到的文档片段生成回答。编排完后右上角点击「预览」，打开调试对话框，提问一个文档里有明确答案的问题，看返回结果是否引用了检索内容。

5. 服务启动与验证过程中的 4 个高频坑点：现象、原因与解法

5.1 网页打不开但容器全在跑：Nginx 代理链路断裂

现象：执行docker compose up -d后所有容器都显示 Up，浏览器访问服务器 IP 却一直转圈或者直接拒绝连接，curl http://localhost返回空响应。

原因：最常见的是 Dify 的 nginx 容器监听在 80 端口，而宿主机防火墙或安全组没有放行 80 端口；另一种可能是 nginx 配置里 proxy_pass 指向的 api 容器名解析失败——如果 Dify 内部的 Docker 网络没建好，Nginx 容器里无法通过api这个主机名解析到 API 服务。

解决：先用curl http://localhost/api/health在宿主机上测，通说明 API 服务正常，问题在防火墙或端口映射；不通则进 nginx 容器测试：docker compose exec nginx curl http://api:5000/api/health，容器内能通而宿主机不通，检查端口映射；容器内都不通，重建网络：docker compose down && docker compose up -d，让 Compose 重建默认网络。

5.2 模型测试一直报 401：密钥和 Base URL 对着看一眼

现象：模型供应商里填好了 Key，测试时返回401 Unauthorized或Authentication Fails。

原因：绝大部分是 Base URL 填错，或者 Key 前后有空格。Dify 的配置文件把密钥存在数据库里，如果从某个文件复制密钥时混入了换行符，Web 界面看不出来，但请求发出去时密钥不干净。

解决：先去模型供应商设置里检查API Base URL，确认是https://.../v1形式，不要带chat/completions后缀；然后重新输入 API Key，确保前后没有空格。如果还报错，打开 Dify api 容器日志：docker compose logs --tail=100 api，日志里会打印实际请求的 URL 和状态码，能直接看到请求发去了哪。

5.3 知识库索引任务卡住：embedding 模型没配上或配额用完

现象：上传文档到知识库后，文档状态一直停留在「处理中」或「索引中」，甚至直接报错。

原因：知识库的向量化需要调用嵌入模型，而嵌入模型需要在「模型供应商」里独立配置。如果你只配置了对话模型，没配置嵌入模型，知识库处理任务会一直等待可用的嵌入模型。另外，部分模型服务商的嵌入模型配额和对话模型配额分开，费用额度用完也会造成卡住。

解决：在模型供应商设置里给同一个供应商添加文本嵌入模型（比如text-embedding-3-small），然后在知识库设置里选择该嵌入模型。改完后再新建一个知识库测试上传——已卡住的文档任务可能要删除重建，不要浪费时间等它自己恢复。

5.4 Sandbox 日志报权限错误：容器内沙箱工具调用失败

现象：编排里接了工具节点，运行时提示 Sandbox 执行失败，日志里有Permission denied或Operation not permitted。

原因：Dify 的代码执行 Sandbox 容器默认以受限权限运行，有些工具依赖系统资源或网络权限，沙箱环境不允许。这个问题在自建部署中比较常见，因为平台版的沙箱已经调优过。

解决：先确认 Sandbox 容器是否正常运行：docker compose ps | grep sandbox，正常则看docker compose logs --tail=100 sandbox。如果报权限相关错误，检查宿主机内核是否开了 seccomp 限制，一般做法是给 sandbox 容器增加privileged: true或补充cap_add。但要清楚这会降低安全性，仅限你自己实验环境用，生产环境不要这么搞。

注意：以上排查顺序遵循一个原则：从外部到内部，从网络层到应用层。先确认端口通不通，再看容器健康状态，最后看应用日志。绝大多数 Dify 部署问题的根因在端口、密钥、Healthcheck 三处。

6. 从本机验证到可维护部署：日志排查习惯与服务启停的进阶操作

Dify 部署跑通之后，真正拉开差距的是日常维护能力。我自己的习惯是给 Dify 的常用操作加一层壳，把启动、停止、看日志、查健康这几个动作封装成 Makefile 命令，减少手敲长命令的机会，也避免团队成员执行docker compose down -v这类危险操作。一个典型的 Makefile 片段长这样：

start: docker compose up -d stop: docker compose down restart: docker compose restart logs: docker compose logs --tail=200 -f health: curl -s http://localhost/api/health | jq .

这里logs命令加了-f参数，是 follow 模式，日志实时滚动，适合启动后观察各容器初始化流程；health命令直接输出 JSON 状态，一眼判断 API 服务是否健康。花几分钟写这么几行，后面每天维护时省下的时间远超投入。

接着是升级流程。Dify 的版本迭代很快，升级的方式是拉取最新代码然后重新拉镜像。但这里有一个值得养成的习惯：升级前手动备份 Postgres 数据库和存储卷。最常见的做法是直接进入容器用 pg_dump 导出：

docker compose exec db pg_dump -U postgres dify > dify_backup_$(date +%Y%m%d).sql

这条命令把整个 Dify 数据库导出为 SQL 文件，存到宿主机当前目录，文件名带日期。恢复时用docker compose exec -T db psql -U postgres dify < dify_backup_xxx.sql导入。存储文件（用户上传的文档、图片）可以打包整个挂载目录。这一套备份在 Dify 大版本升级时几乎是必需品——升级带来的数据库 schema 变更一旦失败，没有备份就真的要从头重建应用了。

最后说一个验证部署是否稳定的技巧：看 Web 容器和 API 容器的健康状态连续性，而非只看某一时刻。正确的做法是连续观察 10 分钟，执行watch -n 10 docker compose ps，watch每 10 秒刷新一次容器状态，如果这期间有容器从 healthy 变成 unhealthy，说明运行不稳定，需要看日志；如果一直稳定，恭喜，这套环境可以放心丢给业务方用。我在多次部署里吃过靠单次检查就宣布成功的亏——有一次 API 容器在凌晨被 OOM Killer 杀掉，第二天同事打开应用才发现白屏。所以我的习惯是部署完至少观察一轮时间周期，确认健康状态稳定后才交接。这类黑匣子问题很难从配置文件直接看出，慢一步上手监控习惯，后面少熬几个夜。希望帮到你。

本文还有配套的精品资源，点击获取