先交代一下背景。我是在帮团队搭建内部 LLM 应用平台时接触到的 Dify从社区版 1.9 一路用到 1.10中间经历了从“能跑就行”到“要扛住生产流量”的完整转变过程。这篇手册不是把官方 README 复述一遍而是把我在企业级 Docker Compose 部署中实际验证过的方案、踩过的坑、调过的参数全部整理出来希望能帮你少走弯路。Dify 是开源的 LLM 应用开发平台核心价值是把模型接入、知识库、Agent 编排、工作流、API 管理这些东西拧成一套可视化体系。对于企业团队来说它解决的核心问题是不需要每个项目都从头写一遍模型适配层和对话管理逻辑直接用一套平台去承接不同业务的 LLM 应用需求。适合的人群很明确——企业内部做 AI 平台建设的技术负责人、需要快速搭建 LLM 应用的开发团队、以及给客户交付私有化部署方案的实施工程师。1. 部署前的整体设计与环境规划1.1 Dify 部署形态选择为什么先用 Docker ComposeDify 官方提供了几种部署方式Docker Compose、Kubernetes、以及单机二进制方式。企业级场景下我建议第一选择仍然是 Docker Compose原因很实际。Kubernetes 部署虽然弹性好但引入了 Operator、Ingress、PV/PVC 等一系列额外概念对于一个通常只需要 2~4 台机器承载的平台来说运维复杂度不成比例。而且 Dify 自身的服务组件数量不算多Compose 方式完全能覆盖大多数生产场景。单机二进制方式又过于简略很难处理依赖组件的生命周期管理。Docker Compose 的优势在于三点一是声明式定义所有服务版本清晰可追溯二是升级回滚方便改个镜像 tag 就能完成版本切换三是排障直观docker compose logs一条命令看全部服务日志。对于中小团队来说这是性价比最高的方案。1.2 服务器选型与基础环境要求先说硬件底线。我实测下来Dify 平台自身的资源消耗不算夸张但真正的资源黑洞是模型推理和文档解析。如果只是部署 Dify 平台 接入云端 API 模型比如 DeepSeek API、通义 APICPU 8 核、内存 16G、磁盘 100G 基本够用。如果要接入 Ollama 或本地部署 DeepSeek 这类开源模型那就要把推理资源单独算。7B 模型量化版大约要吃 6~8G 显存或内存13B 模型建议单独准备一张 24G 显存的卡或者至少 32G 内存的纯 CPU 推理节点。这个时候我强烈建议模型推理服务独立部署在另一台机器上Dify 通过 API 地址去调用避免平台服务和推理互相抢占资源导致整体卡顿。磁盘方面别抠门Dify 的向量化数据、文档解析中间产物、PostgreSQL 数据都会持续增长。建议数据盘至少 200G并单独挂载。操作系统我用的 Ubuntu 22.04 和 CentOS 7.9 都验证过。这里要特别提醒如果你还在用 CentOS 7内核版本老旧Docker 新版兼容性差建议尽早迁移到 RockyLinux 9 或 Ubuntu 22.04 以上版本。1.3 Docker 与 Docker Compose 的安装细节很多人在这一步就卡住了尤其是报docker: unknown command: docker compose这类错误。原因很简单Docker 20.10 以上版本才内置 Compose V2 插件老版本只有独立的docker-compose命令。正确安装方式分两步。第一步安装 Docker Engine使用官方源或清华镜像源都可以安装后执行systemctl enable --now docker确保开机自启。第二步安装 Compose 插件sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完验证docker --version docker compose version如果输出显示Docker version 24.x和Docker Compose version v2.x说明环境没问题。这里有个经验老项目习惯用docker-compose带连字符的命令新装环境直接统一用docker compose空格形式避免两套命令混用造成的配置不一致。网络环境差的机器记得配置 Docker daemon 的镜像加速器编辑/etc/docker/daemon.json{ registry-mirrors: [https://docker.m.daocloud.io] }改完重启 Docker。这一步能省下大量拉镜像的时间。2. Docker Compose 部署方案的核心架构与配置2.1 Dify 容器服务组成与职责拆解Dify 的 Docker Compose 部署包含一批核心服务理解每个服务的作用后面排障才不会慌。服务名职责关键点apiDify 后端 API 服务业务核心处理对话、工作流、知识库请求worker异步任务队列消费者负责文档处理、向量化、Agent 执行等耗时任务web前端界面Nginx 托管静态页面同时做 API 反向代理postgres元数据库存储用户、应用配置、对话记录等结构化数据redis缓存与消息队列配合 worker 做任务分发和状态缓存weaviate向量数据库存储知识库文档向量支持语义检索ssrf_proxy安全代理防止服务端请求伪造保护内部网络nginx接入网关统一入口转发到 web 和 apisandbox代码执行沙箱运行用户自定义 Python 代码隔离执行环境我特别想强调两个容易忽略的服务。第一个是sandbox它涉及安全边界如果业务里有用户自定义代码执行的场景一定保持沙箱服务运行不能随意关闭。第二个是ssrf_proxy它保护的是你的内网安全如果某个模型 API 或工具插件访问异常先检查这个代理配置。2.2 安装与基础启动流程部署前先准备好项目目录和配置文件。用 git 拉取官方部署仓库的好处是可以直接拿到官方维护的 compose 文件和环境变量模板git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env然后编辑.env这是整个部署流程里最重要的文件。先看几个刚需参数SECRET_KEY用于加密敏感信息必须改成随机字符串可以用openssl rand -base64 42生成。POSTGRES_PASSWORD数据库密码同样必须改。EXPOSE_NGINX_PORT外部访问端口默认 80。INIT_PASSWORD管理员初始密码首次登录前修改。CONSOLE_API_URL和APP_API_URL如果走自定义域名和 HTTPS需要改成实际对外地址。改完后启动docker compose up -d首次启动要拉取镜像并初始化数据库耗时较长建议用docker compose logs -f api观察初始化进度。启动完成后访问http://服务器IP按照引导创建管理员账号。2.3 .env 关键参数深入解读很多人部署完能登录就以为结束了实际上对于企业级场景你还需要关注下面几组参数。第一组是服务资源配置。社区版 1.9 之后compose 文件支持通过环境变量控制服务资源限制比如.env中# 限制服务内存使用 API_MEMCACHED_MAX_MEMORY128 WORKER_CONCURRENCY4WORKER_CONCURRENCY值得单独说。它控制 worker 进程的并发数默认值偏保守。如果你的知识库里有大量文档需要向量化或者工作流任务很密集可以适当调大例如 8 或 12但要注意内存占用会同步上升。第二组是存储路径。默认情况下所有数据都存在 Docker volume 里路径不好管理。我建议在.env中显式指定数据目录# 自定义数据持久化目录 DIFY_DATA_DIR/data/dify然后修改 compose 文件的 volume 映射把数据落到宿主机固定路径。这样做的好处是备份、迁移、排查磁盘空间都更方便。企业场景千万不要把数据全放在默认 volume 里一旦 Docker 重装数据恢复会非常痛苦。第三组是日志配置。如果接入方有日志采集系统可以在 compose 文件中为每个服务增加 logging 配置logging: driver: json-file options: max-size: 20m max-file: 5这套配置防止容器日志无限增长打爆磁盘我在生产环境被这个问题坑过一次日志文件涨到几十个 G磁盘告警才发现。2.4 升级与回滚的完整操作流程Dify 社区版迭代很快从 1.9 升级到 1.10 引入了多租户等特性升级操作本身并不复杂但要做对顺序。先备份这是老生常谈但每次都有团队跳过。备份三个东西PostgreSQL 数据库、向量数据库数据、.env配置文件。PostgreSQL 备份命令docker compose exec postgres pg_dump -U dify dify dify_backup_$(date %Y%m%d).sqlWeaviate 备份可以直接备份数据目录或者用官方提供的导出工具。.env文件直接复制一份留存。然后替换镜像版本。因为用 git 拉取的仓库直接拉新代码git pull origin main docker compose pull docker compose up -d升级后需要执行数据库迁移Dify 的 api 容器启动时会自动做 migration观察日志确认迁移成功再放流量进来。回滚操作正好相反把.env和 compose 文件恢复旧版docker compose up -d拉起旧镜像。前提是旧镜像 tag 还在本地所以升级前不要执行docker image prune。3. 大模型接入与知识库流水线配置3.1 本地模型接入Ollama 与 DeepSeek 本地部署企业内网场景经常不能直接调用云端模型 API因此本地模型接入是 Dify 部署的高频需求。Dify 对模型供应商做了统一抽象无论是 OpenAI 兼容接口、Ollama、还是 Xinference、LocalAI通过模型供应商页面配置 Base URL 和 API Key 即可。Ollama 接入 Dify 是主流方式。假设你已经在一台有 GPU 的服务器上部署了 Ollama比如192.168.1.50:11434在 Dify 后台添加 Ollama 供应商时填入模型名称llama3.1:8b或你实际拉取的模型名Base URLhttp://192.168.1.50:11434模型类型选择对话助手或文本生成这里有个最容易踩的坑Ollama 默认只监听127.0.0.1跨机器访问必须在 Ollama 的 systemd 服务或启动命令中设置OLLAMA_HOST0.0.0.0否则 Dify 会报连接拒绝。DeepSeek 本地部署思路类似。DeepSeek 开源模型可以通过 Ollama 或 vLLM 部署Dify 接入时如果部署服务提供了 OpenAI 兼容接口直接选 OpenAI-API-compatible 供应商填接口地址和模型名称即可。实测用 vLLM 部署 DeepSeek-R1-Distill 系列并发能力和响应速度都明显优于 Ollama。本地模型接入后的验证建议先在 Dify 的模型供应商页面点“测试”连通后再创建应用测试对话。如果测试报An error occurred during credentials validation先查网络连通性再查接口路径和鉴权头最后看 Dify api 容器日志。这三个方向能覆盖九成以上的接入问题。3.2 模型网关与多模型调度当企业同时接了云端 API、本地 Ollama、私有化部署的模型服务统一管理多个供应商变得尤为重要。Dify 本身支持配置多个供应商并在不同应用里按需选择模型。但我更建议的实践是把 Dify 接入一个统一的 LLM 网关由网关负责路由、限流、密钥管理。常见的开源网关方案包括 one-api 和 new-api它们暴露一个 OpenAI 兼容接口内部可以转发到不同后端。Dify 只配一个供应商就能调度多个模型。这套架构的好处非常明显Dify 侧不需要逐个配置供应商应用切换模型只需改模型名称网关还能在模型挂了时自动切换备胎避免整条链路因单一模型故障而中断。3.3 知识库配置与文档处理管线知识库是 Dify 在 LLM 应用中使用频率最高的能力之一。涉及“LLM wiki 知识库”这个场景时核心管线是这样的上传文档 → 文档解析 → 分段清洗 → 向量化 → 写入向量数据库 → 查询时语义检索。文档解析是整个流程的第一道关卡。Dify 在社区版中解析 PDF、Word 等格式时依赖Unstructured服务如果部署时没有启用对应服务上传文档会报unstructured api url is not configured for doc file processing。解决方法是修改.envUNSTRUCTURED_API_URLhttp://unstructured:8000并确认 compose 文件中启用了 unstructured 服务。分段策略直接影响 RAG 的检索效果。我实际测试后的建议是普通文本按固定 token 分段500~800 token 一档。技术文档优先用 markdown 标题分段避免切断代码块和表格。问答对格式单独设置分段保证问答完整。向量化模型的选择要跟知识库语言强相关。中文知识库建议用bge-m3或text2vec-large-chinese英文场景用text-embedding-3-small即可。设置不当会出现“能检索到但答非所问”的现象多半是向量化模型和查询语言不匹配导致的。4. 生产环境稳定运行与安全加固4.1 HTTPS 与 SSL 配置企业部署必须上 HTTPSDify 自带的 Nginx 默认监听 80 端口要挂 SSL 证书改造下配置。先把证书文件放到宿主机比如/data/certs目录下。然后修改docker/nginx/conf.d/default.conf增加 HTTPS server 块server { listen 443 ssl; server_name dify.example.com; ssl_certificate /etc/nginx/certs/dify.example.com.pem; ssl_certificate_key /etc/nginx/certs/dify.example.com.key; client_max_body_size 50M; location / { proxy_pass http://web:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }同时需要把证书目录挂载进 nginx 容器。修改 compose 文件中 nginx 服务的 volumes添加- /data/certs:/etc/nginx/certs:ro重启生效docker compose up -d nginx配置完成后登录 Dify 控制台把后台的访问地址更新为 FastGPT 风格的完整 HTTPS 地址。很多人配置完 HTTPS 后遇到dify ssl 错误通常是两个原因证书链不完整或者容器内没有重新加载配置。证书链问题用openssl s_client -connect 域名:443验证容器配置问题重启 nginx 即可。4.2 数据库与备份策略企业级部署必须建立备份制度。Dify 的状态数据主要集中在 PostgreSQL向量数据在 Weaviate这两个是备份重点。PostgreSQL 我建议每日凌晨全量备份用 cron 调度0 2 * * * docker compose -f /data/dify/docker-compose.yaml exec -T postgres pg_dump -U dify dify | gzip /data/backup/dify_$(date \%Y\%m\%d).sql.gz保留最近 14 天的备份避免磁盘被历史备份占满。Weaviate 的备份稍微特殊。如果数据量不大直接备份数据目录文件如果数据量大用它的备份 API 导出到本地文件。实际教训是向量数据库的备份比想象中更重要知识库重新向量化的成本很高动辄几小时甚至几天。备份完成后至少每月做一次恢复演练。我见过太多团队备份文件一箩筐真到恢复的时候发现备份脚本早就失效了。4.3 多租户与权限管理社区版 1.10 带来了多租户能力这对企业内部按部门、按项目隔离应用非常有价值。开启多租户之后每个租户有独立的空间、独立的成员管理、独立的资源配额。我建议的实践是平台管理员负责全局配置各业务团队在各自租户内创建应用。这样做既避免了应用混乱也方便按租户统计模型调用量和费用。此外企业场景建议开启 SSO 登录。Dify 支持 OIDC 和 SAML 集成在企业已有统一认证体系的情况下务必接上否则员工离职后账号无法自动回收会留下安全隐患。5. 常见问题排查与避坑实录5.1 部署与运行中的高频错误汇总我把这段时间遇到的典型问题整理成了一张速查表方便你直接对照处理。症状原因处理方法docker: unknown command: docker compose缺少 Compose 插件安装 docker-compose-pluginAn error occurred during credentials validation模型 API 地址或鉴权配置不对检查 Base URL、API Key、供应商配置unstructured api url is not configured文档解析服务未开启启用在 .env 中配置 UNSTRUCTURED_API_URLSSL 证书报错证书链不完整或未重新加载检查证书链重启 nginx 容器上传大文件报 413Nginx 请求体大小限制修改 client_max_body_size对话响应慢本地模型推理瓶颈或 worker 并发不足调大 WORKER_CONCURRENCY独立部署模型服务知识库检索效果差分段策略或向量模型不合适调整分段策略更换适配中文的向量模型5.2 日志分析与性能排查思路Dify 服务组件多排查问题建议按下面顺序推进。先看接入层。外部请求进来先到 nginx再转发到 web 和 api。用docker compose logs nginx看请求状态码分布如果大面积 502说明后端服务挂了或负载过高。再看业务层。api 服务日志里会有每个请求的处理链路由报错信息通常直接指向问题组件。如果某个知识库请求反复超时去查 worker 日志向量化或文档解析任务可能堆积了。最后看资源层。用docker stats实时看各容器 CPU、内存占用。redis容器内存涨得飞快说明缓存命中率有问题或者存在大 keypostgresCPU 飙高多半是慢查询开启慢查询日志定位具体 SQL。性能排查有一个思维误区是“加机器就完事”。实际上很多问题出在 worker 并发和 DDos 服务资源配置上先把配置调优再做扩容否则资源加了照样跑不动。5.3 磁盘管理与清理策略容器化部署最容易被忽视的就是磁盘占用。Dify 体系里几个磁盘消耗大户容器日志文件json-file 驱动默认不限制大小。PostgreSQL 数据文件和 WAL 日志。文档解析的临时文件。旧版本镜像。建议每周做一次清理# 清理停止的容器和悬空镜像 docker container prune -f docker image prune -f # 清理 Docker 构建缓存 docker builder prune -f同时用df -h和du -sh /var/lib/docker定期观察磁盘增长趋势建立磁盘用量告警。我上次踩坑就是日志文件暴涨直接把数据盘写满整个平台服务全部拒绝连接。6. 部署之后稳定运营比什么都重要写到最后分享几条我在多套生产环境里总结出来的运营体会。第一部署完成只是起点持续的版本跟进和备份演练才是重点。Dify 每月都有功能更新和安全补丁建议每两个月评估一次升级不要几年不升也不要新版一出就盲目升。第二模型层面的熔断机制很关键。Dify 本身支持模型供应商健康检查与错误重试建议在多个模型之间设置主备路由。实际操作中我给线上环境配了双供应商方案主供应商超时或报错后自动切到备用供应商业务侧基本无感这个设计多次救了我。第三监控大盘越早越好。Dify 提供了一定的后台统计能力但对于企业运营来说把 api 日志、模型调用量、token 消耗、访问延迟接入 Prometheus Grafana 才是标准化方案。有了数据后续做容量规划、成本分摊才不是拍脑袋。如果这篇手册能帮你顺利把 Dify 跑起来并且跑得稳那这篇文章的价值就达到了。等你在实际部署中碰到新的问题欢迎回来对照着这篇文章再翻一翻大概率能找到方向。