投研帮我去年第一次在本地跑Dify时，其实没想太多，就是想做一个自己的知识库助手，把一堆企业文档丢进去，让同事用自然语言问答案。结果部署过程碰了一鼻子灰，光是把Docker环境配好就折腾了两天，后面接模型、配向量库又踩了好几个坑。后来复盘才发现，很多问题其实在部署之前就能规避——所谓“前期准备”，比真正执行docker compose up要重要得多。
这篇文章就围绕Dify本地部署的前期准备和完整过程展开，把我实际操作中的思路、配置、坑位、排查方法都倒出来。无论你是想用Dify搭企业知识库、做Agent工作流，还是单纯想在本地把大模型跑起来做个玩具，这份经验应该都能帮你省下不少时间。
1. 先想清楚：本地部署Dify到底在解决什么问题
1.1 为什么不用在线版，非要折腾本地
Dify官方有云服务，注册完就能用，界面和社区版基本一致，知识库、工作流、Agent这些功能都不缺。那为什么还有大量团队要自己做本地部署？我当时的需求就三条：数据不出内网、隐私受控、能深度定制。
在企业场景里，知识库里的文档往往涉及内部制度、产品方案、客户信息，这些东西扔到外部平台，合规上就过不去。本地部署的第一个价值就是数据主权：所有数据都存在你自己的服务器上，API请求的出入流量完全由你控制。
另一个很多人容易忽略的点是“可定制性”。在线版虽然功能齐全，但插件、环境变量、底层镜像、嵌入模型这些层面基本不可动。本地部署之后，你可以调整Dify的worker数量、换掉默认的向量数据库、接入你自己微调过的模型、甚至改动前端代码重新打包。这种自由度，在线版给不了。
1.2 本地部署的适用场景与理性预期
先泼一盆冷水：如果你只是个人图新鲜想试一下Dify，直接跑官方Docker Compose就够了；但如果你是给团队做工具，或者要长期维护一个稳定的知识库服务，那部署本质上是“运维工作”，不是一个晚上能搞完的。
我的建议是，本地部署前先回答三个问题：
- 数据量有多大？文档是几十份还是几十万份？这决定了向量数据库的选择和磁盘规划。
- 模型从哪里来？有GPU吗？还是准备调用云API？这一条直接影响Dify里“模型供应商”的配置方式。
- 服务要几人在线用？这决定了你要不要调整Docker Compose里的资源配额和并发参数。
不要抱着“先部署起来再说”的心态。Dify一旦接了知识库和工作流，后续迁移成本不低。前期想清楚，后面会顺畅很多。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 硬件与环境准备：照着抄的配置清单
2.1 CPU、内存、磁盘的底线和推荐配置
Dify本体吃内存不低。官方建议的最低配置是2核4G，但这个数字只够“启动起来”，实际用起来会很勉强。我自己的经验是：4核8G是舒服的起步线，16G以上才敢跑本地小模型。
为什么这么吃资源？Dify的Docker Compose会拉起一堆服务：API服务（含Celery worker）、Web前端（Nginx）、PostgreSQL数据库、Redis缓存、向量数据库Weaviate（或Qdrant）、Sandbox代码执行沙箱，如果开了SSRF保护还要一个Proxy。这是一整套微服务架构，每个容器都得占内存，单纯跑Dify本体就差不多要3~4G内存。
如果你打算用Ollama接本地模型，内存需求还要再往上加。Llama 3 8B量化版跑起来需要6~8G内存（如果走CPU推理），QWen 7B之类的模型也差不多。想用GPU推理，那显存就是另一笔账了。
磁盘方面，Docker镜像+数据卷+向量库索引，50G起步比较稳妥。如果知识库文档量大，建议单独挂一个数据盘。
2.2 操作系统的选择和Docker环境安装
Debian/Ubuntu系的Linux系统是最顺手的。CentOS 7如果内核版本太老，Docker跑容器会遇到兼容性问题，我建议直接用Ubuntu 20.04以上版本。
Docker安装这块，官方脚本一条命令就能搞定：
bash复制curl -fsSL https://get.docker.com | bash -s docker
装完记得把当前用户加入docker组，避免每次敲命令都要sudo：
bash复制sudo usermod -aG docker $USER
newgrp docker
Docker Compose现在默认是Docker的插件，验证一下版本：
bash复制docker compose version
如果显示的是version 2.x，那就没问题。网上很多老教程还让你单独装docker-compose，其实那是Python写的旧版，功能上和原生插件有差异，没必要绕弯。
2.3 网络、镜像加速和端口规划
这一步经常被忽略，但恰恰是部署卡壳的高发区。Dify的镜像都托管在Docker Hub，有些环境拉取速度很慢，甚至直接超时。
配置镜像加速器，常见的做法是修改/etc/docker/daemon.json：
json复制{
"registry-mirrors": ["https://docker.m.daocloud.io"]
}
改完重启Docker：sudo systemctl restart docker。
端口规划也要提前想好。Dify默认会用80端口暴露Web界面，如果你服务器上已经跑了Nginx或其他服务，端口就会冲突。我实际部署时就把Web端口改成了8088，这需要改.env文件里的EXPOSE_NGINX_PORT。MySQL（如果启用）、Redis、PostgreSQL的端口在Compose文件里默认映射出来，如果不希望外部访问数据库，可以考虑去掉宿主机的端口映射，只让容器间内网通信。
3. Docker Compose方式部署：完整步骤复盘
3.1 获取项目文件与版本选择
Dify官方提供了Docker Compose部署方式，在GitHub仓库（langgenius/dify）的docker目录下。有两种获取方式：直接git clone整个仓库，或者只下载docker文件夹。
我当时用的是git clone，图的是后续升级方便：
bash复制git clone https://github.com/langgenius/dify.git
cd dify/docker
这里有个关键点：**不要直接用master/main分支的最新代码，要去选稳定版本。**Dify社区版迭代很快，有时候main分支会引入还没全量测试的功能，部署完遇到奇奇怪怪的问题，排查起来很头疼。建议在GitHub的Release页面找一个最新的稳定版tag，然后checkout：
bash复制git checkout 1.10.0
版本选择上多说两句。老版本（比如0.6、0.7）的配置文件结构和现在差别很大，**不建议参考网上那些旧教程里的.env配置，一定要以当前版本的.env.example文件为准。**你可以在docker目录下看到.env.example，这是所有配置的蓝本。
3.2 环境变量配置：逐项解读关键项
复制环境变量文件：
bash复制cp .env.example .env
打开.env，有一堆配置项，刚上手会有点懵。但真正需要关心的其实没几个，剩下的大多保持默认即可。
首先是SECRET_KEY，这个必须自己改成一个随机字符串，用来做应用加密和会话签名。可以用命令行生成：
bash复制openssl rand -base64 42
然后填进去。如果你挂到公网，SECRET_KEY还用默认值，那等于把门锁钥匙放在门口垫子下面。
接着是POSTGRES_PASSWORD和DB_PASSWORD，数据库密码默认是个弱口令，改成强密码。
然后是VECTOR_STORE，这个决定知识库用什么向量数据库。默认是weaviate。如果你有特殊需求（比如已经维护了一套Milvus集群），可以改成milvus，但需要在Compose文件里额外加服务。对绝大多数场景，直接用默认的weaviate就够，别为了炫技自己乱换。
如果你不希望Dify默认使用外部网络请求转发（有些内网环境没外网，或出于安全考虑），可以把SSRF_PROXY_HTTP_URL和SSRF_PROXY_HTTPS_URL留空或注释掉，但代价是自定义工具、HTTP请求节点的防SSRF能力会变弱。我个人的做法是内网环境就关掉，公网环境必须开着。
3.3 启动服务与验证部署结果
关键配置改完后，启动：
bash复制docker compose up -d
第一次启动会拉取一堆镜像，时间取决于网络。启动完成后：
bash复制docker compose ps
正常情况下，你会看到api、worker、web、db、redis、weaviate、sandbox这些服务都处于Up状态。其中api容器是最复杂的，它内部同时跑着API进程和Celery worker两个进程，用docker logs dify-api-1能看到日志输出。
访问http://服务器IP:80（或你改的端口），看到初始化页面就说明部署成功。
如果页面打不开，先排查Nginx容器是否正常，再确认防火墙规则。最简单的方法是先在服务器本机curl localhost:80试试，如果本机能通而外部不通，问题基本上在云安全组或系统防火墙（ufw/firewalld），不用怀疑Dify配置。
4. 第一次登录后的初始化配置：模型接入是重头戏
4.1 管理员账号初始化
浏览器打开Dify后，第一步是创建管理员账号。这里有个细节：**Dify不会自动生成默认密码，第一个注册的账号就是管理员。**所以不要在还没设置好的时候就随便注册测试号，后面清理起来很麻烦。
创建完管理员，进入主界面，你会看到一个工作台。这时系统会引导你设置“模型供应商”。这一步跳过也没关系，后面随时可以在“设置->模型供应商”里配置。
4.2 接入本地模型：用Ollama跑通全链路
本地模型接入是很多人部署Dify的直接动机。系统里最常用的本地推理引擎是Ollama。
Ollama装好后，要确认两个前提：Ollama服务监听的端口是11434，而且能被Dify容器访问到。这里有个常见的坑：Dify容器和Ollama不是同一个进程，容器内的localhost和宿主机不是一回事。
Docker容器访问宿主机需要用host.docker.internal作为宿主机地址。在Dify的模型供应商设置里，填入Ollama的API Base URL，应该是：
code复制http://host.docker.internal:11434
注意，不是http://localhost:11434，也不是http://127.0.0.1:11434。
你在宿主机上先测试Ollama的连通性：
bash复制curl http://localhost:11434/api/tags
如果返回了模型列表的JSON，说明Ollama本身没问题。然后拉一个模型，比如：
bash复制ollama pull qwen2.5:7b
回到Dify模型供应商页面，填上模型名称、API Base URL，然后点击“测试”。如果你看到绿色勾选提示，恭喜，本地模型链路已经通了。
4.3 接入云端模型API：DeepSeek、OpenAI等供应商配置
没有GPU资源的话，接云API是最省事的选择。Dify内置了大量模型供应商，DeepSeek、OpenAI、通义千问、Moonshot等都有现成入口。
以DeepSeek为例，到DeepSeek开放平台申请API Key，然后在Dify的模型供应商页面找到DeepSeek，填入Key，点击保存。系统会自动拉取模型列表，选择deepseek-chat作为对话模型即可。
这里有几个注意点：
- 不同供应商的刷新机制不同，DeepSeek和OpenAI都是实时扣费，配置错了会在后续使用中浪费账户余额，建议先选一个便宜的模型测试。
- Dify里每个供应商可以配置多个模型，会优先使用你标注的“默认”模型。
- 云端API和本地模型可以并存，比如用云端模型做复杂推理，用本地模型做基础问答。这种混搭在Dify里就是多配几个供应商的事。
我自己的实践是：一台8G内存的小服务器跑Ollama的qwen2.5:3b做入门实验，同时接上DeepSeek API处理正式任务。测试下来，两种模型互不干扰，切换也很方便。
5. 部署过程中我踩过的坑与排查思路
5.1 端口冲突导致的启动失败
我第一次部署就遇到80端口被占。服务器上原本有个Nginx，80端口被监听，Dify的web容器起不来。
排查链路：
bash复制netstat -tlnp | grep :80
看到进程ID后，ps -ef | grep <pid>定位到是Nginx。解决方式有两种：停掉旧服务，或者给Dify换个端口。考虑到旧服务不能停，我选择在.env里改：
code复制EXPOSE_NGINX_PORT=8088
然后重启：
bash复制docker compose down
docker compose up -d
端口冲突本身不难解决，但注意一定要在.env里改系统的对外端口，不要去改Compose文件里的nginx容器端口映射，否则升级时重置配置会很痛苦。
5.2 Docker容器一直Restarting，日志里全是报错
容器反复重启的根子往往是依赖服务没起来。Dify的api容器依赖PostgreSQL和Redis，如果数据库容器初始化失败，api容器就会进入Restarting死循环。
排查方法：
bash复制docker compose logs db
docker compose logs redis
最常见的失败原因是PostgreSQL的数据目录权限不对，或者数据库密码配置不一致。.env里的POSTGRES_PASSWORD和Compose文件里的DB_PASSWORD要一致，如果只改了一处，API就会连不上数据库。
另一个隐蔽问题是内存不足。Dify同时启动Weaviate和PostgreSQL，内存压力很大，容器会被OOM Killer杀掉。用dmesg | tail -20查看内核日志，如果看到oom-kill字样，那就得加内存，或者先只启动核心服务：
bash复制docker compose up -d api web db redis
等系统稳定了再把向量库加进来。
5.3 知识库上传文档后，索引一直建立失败
这个坑在知识库搭建时特别容易炸。Dify处理文档流程是：上传文件 -> 提取文本 -> 切分 -> 生成向量 -> 存入向量库。任何一步出问题，索引状态都会停在“等待处理”或直接报错。
常见原因有：
- 向量数据库没起来：
docker compose ps里看weaviate是否正常监听端口。 - Embedding模型没配好：Dify生成知识库向量时必须调用一个嵌入模型，如果模型供应商里没配置Embedding模型，或者API Key过期，索引进度就会卡住。
- 文档格式问题：扫描版PDF没有文字图层，提取出来是空白。这种情况只能先用OCR工具把PDF转成文本，再上传。
排错时先点进“知识库 -> 文档 -> 查看错误信息”，Dify会显示具体的失败日志，比瞎猜要快得多。我遇到过一次非常典型的：Embedding模型配置的是Ollama的本地模型，但Ollama当时没开，向量生成请求超时，索引就失败了。把Ollama拉起来重新触发索引，问题马上消失。
5.4 版本升级的备份策略
Dify社区版更新频率快，不要盲目升级。我建议升级前做两件事：备份数据库和备份向量库。
最简单的方法是用docker compose的volume机制，直接把数据目录拷贝出来：
bash复制cp -r /var/lib/docker/volumes/dify_postgres_data /backup/postgres_data
cp -r /var/lib/docker/volumes/dify_weaviate_data /backup/weaviate_data
升级时先拉最新代码，再拉新镜像：
bash复制git pull
git checkout <新版本tag>
docker compose down
docker compose pull
docker compose up -d
升级后如果页面报数据库版本不兼容，不要慌，先看docker compose logs db。大部分版本升级Dify都会自动执行数据库迁移，但极少数大版本需要手动执行迁移命令，具体看官方Release说明。我的原则是：大版本升级前，一定先在一台测试机器上演练一遍，确认没问题再动生产环境。
6. 部署完成后的初始优化建议
6.1 多租户环境的开启与边界
Dify社区版1.10之后引入了多租户能力，可以一个实例服务多个团队。在.env里有相关配置可以开。但多租户意味着权限隔离、资源配额、独立模型供应商配置这些都需要规划，不是简单打个开关的事。如果团队不大（比如公司内部几十人），我更倾向于先跑单租户，等部门规模上来再迁移。
6.2 工作流和知识库流水线的初步印证
部署完成、模型接通之后，我第一次真正觉得Dify“有用”，是把知识库和工作流串起来那一刻。当时搭了一个很基础的客服助手：用户提问 -> 在知识库做向量检索 -> 把检索结果拼进Prompt -> 交给大模型生成回答。这个流程在Dify里就是拖拽节点的事，不写一行代码。
但这里有个被很多人忽略的细节：**知识库检索结果的质量，直接决定最终回答的质量。**Dify默认的检索模式和TopK参数，在通用场景下可用，但在专业领域往往需要调试。你不妨先从TOP_K=3开始，把召回的片段打印出来看一眼，再决定要不要调整Embedding模型或切分策略。
6.3 资源监控与日常维护习惯
部署完成不是终点。Dify作为一个常驻服务，CPU、内存、磁盘都需要适度关注。我习惯用两个命令看状态：
bash复制docker stats
df -h
docker stats能看到每个容器的实时资源占用，df -h看磁盘余量。跑一段时间之后，Docker日志文件和知识库向量索引会逐步增大，定期docker system prune清理无用的docker资源是必要的——但注意，这个命令会清理停止的容器和未使用的镜像，不要随便在生产环境跑。
如果你想让Dify稳定跑几个月不重启，建议把docker compose up -d和几个常用容器单独设置成systemd服务，这样服务器重启后Dify能自动恢复。这一步在公众号文章里很少见到，但实际运维时价值非常大。
我个人最终把Dify固定在一台Ubuntu服务器上，4核8G，每天同步一次企业内部文档，通过工作流定时触发索引更新。跑了几个月，除了偶尔模型API超时，整体非常稳定。如果你准备开始本地部署，我最大的建议就是：花半天时间把环境准备和.env配置啃透，别急着启动容器——前期准备做到位，后面真正遇到问题的时候，你才知道该去哪里翻日志、改什么参数、怎么不影响业务地恢复服务。这比任何一键部署脚本都管用。