戰(zhàn)：Linux服務(wù)器+Docker Compose指南)
開(kāi)頭從一次真實(shí)的部署說(shuō)起。有段時(shí)間我在Linux服務(wù)器上反復(fù)折騰容器應(yīng)用最頭疼的還不是容器本身而是應(yīng)用之間的依賴(lài)關(guān)系、初始化順序、數(shù)據(jù)卷到底應(yīng)該怎么掛。后來(lái)接觸到一個(gè)叫 Dify 的開(kāi)源項(xiàng)目發(fā)現(xiàn)它的定位很有意思不是普通聊天機(jī)器人而是把大模型應(yīng)用開(kāi)發(fā)里的提示詞編排、知識(shí)庫(kù)檢索、Agent 工作流、模型管理等環(huán)節(jié)全部可視化部署形式也是我熟悉的 Docker 容器。于是我用一臺(tái) Linux 服務(wù)器通過(guò) Docker Compose 把整套 Dify 拉起來(lái)前后整理了不少配置細(xì)節(jié)和踩坑記錄今天一次性寫(xiě)出來(lái)。這東西適合誰(shuí)參考如果你正在做 LLM 應(yīng)用的快速原型或者想把企業(yè)內(nèi)部的知識(shí)庫(kù)助手、客服問(wèn)答機(jī)器人落地到自有服務(wù)器又不想從零寫(xiě)編排代碼那么 Dify 就是你需要的平臺(tái)。它本身支持私有化部署數(shù)據(jù)在你自己手里模型 API 可以接各家廠(chǎng)商也可以接本地模型服務(wù)。無(wú)論你是后端開(kāi)發(fā)、運(yùn)維還是產(chǎn)品側(cè)的技術(shù)負(fù)責(zé)人只要熟悉基本 Linux 命令和 Docker 操作照著下面的步驟走基本能在一小時(shí)內(nèi)把整套平臺(tái)跑起來(lái)。1. 整體設(shè)計(jì)思路與部署架構(gòu)拆解1.1 Dify 到底解決了什么問(wèn)題先理解 Dify 在技術(shù)棧里的位置。它屬于大模型應(yīng)用開(kāi)發(fā)平臺(tái)底層還是調(diào)用外部大模型 API 或本地模型服務(wù)但上層把業(yè)務(wù)方最常做的事封裝成了可拖拽、可配置的積木。比如你想做一個(gè)帶知識(shí)庫(kù)的問(wèn)答機(jī)器人傳統(tǒng)做法是寫(xiě)代碼搭向量數(shù)據(jù)庫(kù)、做文檔切片、寫(xiě)召回邏輯、設(shè)計(jì) Prompt 模板、處理會(huì)話(huà)上下文再寫(xiě)一套管理后臺(tái)。用 Dify 之后這些能力以現(xiàn)成模塊的形式出現(xiàn)在界面上你只需要配置知識(shí)庫(kù)來(lái)源、選擇模型、編排工作流即可。從部署者的角度看Dify 不是一個(gè)單體程序而是一組相互協(xié)作的服務(wù)集合。它包含 Web 前端、API 服務(wù)、異步任務(wù) Worker、PostgreSQL 數(shù)據(jù)庫(kù)、Redis 緩存、模型請(qǐng)求代理、安全沙箱等組件。這種架構(gòu)天然適合容器化每個(gè)組件是獨(dú)立鏡像通過(guò) Docker Compose 統(tǒng)一編排啟動(dòng)順序和數(shù)據(jù)卷都在一份配置里定義好。這也是我選擇在 Linux 服務(wù)器上用 Docker 部署的核心理由。1.2 為什么選用 Linux 服務(wù)器加 Docker 組合先說(shuō) Linux 服務(wù)器。Dify 官方提供的部署方式里最順手的其實(shí)就是 Linux 加 Docker Compose。Windows 上雖然有 Docker Desktop但 mount 路徑、權(quán)限、換行符、端口監(jiān)聽(tīng)這些細(xì)節(jié)容易出問(wèn)題macOS 本地跑跑沒(méi)問(wèn)題但長(zhǎng)期作為服務(wù)運(yùn)行還是 Linux 更省心。Linux 環(huán)境下 systemd 管理方便日志清理、開(kāi)機(jī)自啟、防火墻策略都更成熟。再說(shuō) Docker。容器化帶來(lái)的最大好處是可復(fù)現(xiàn)性。同一份 Compose 文件在測(cè)試服務(wù)器上驗(yàn)證過(guò)之后生產(chǎn)環(huán)境直接照搬只要系統(tǒng)版本和端口不沖突結(jié)果基本一樣。另一個(gè)好處是隔離Dify 依賴(lài)的 PostgreSQL 和 Redis 版本是自己要求的如果直接裝在宿主機(jī)上很可能和服務(wù)器里已有的 MySQL、Redis 實(shí)例產(chǎn)生版本沖突。用容器之后每個(gè)依賴(lài)都被隔離在獨(dú)立環(huán)境里升級(jí) Dify 時(shí)只需要換鏡像不需要污染宿主機(jī)環(huán)境。1.3 部署架構(gòu)全景圖這套架構(gòu)可以拆成三層來(lái)看。最外層是接入層一般用 Nginx 或 Caddy 對(duì)外提供 HTTPS 訪(fǎng)問(wèn)中間是 Dify 的核心服務(wù)群包括 API 服務(wù)、Web 前端、Worker 異步任務(wù)、SSRF 代理、Sandbox底層是基礎(chǔ)設(shè)施服務(wù)包括 PostgreSQL 和 Redis以及可選的向量數(shù)據(jù)庫(kù)。需要注意的是生產(chǎn)環(huán)境下千萬(wàn)不要直接把 PostgreSQL 和 Redis 的端口暴露到公網(wǎng)。它們只需要在 Docker 內(nèi)網(wǎng)里被 Dify 各服務(wù)訪(fǎng)問(wèn)即可。對(duì)外真正需要暴露的是 Web 端口和 API 端口建議通過(guò)宿主機(jī)的 Nginx 反代而不是直接把容器端口裸奔出去。2. 部署前的環(huán)境準(zhǔn)備2.1 服務(wù)器配置要求先給出我實(shí)測(cè)過(guò)的配置底線(xiàn)。如果只是測(cè)試環(huán)境2 核 CPU、4G 內(nèi)存、40G 磁盤(pán)基本能跑但體驗(yàn)會(huì)比較緊尤其是首次啟動(dòng)時(shí)多個(gè)容器同時(shí)初始化內(nèi)存可能瞬間沖到 3G 以上。我建議個(gè)人使用或者小團(tuán)隊(duì)試用至少 4 核 8G 內(nèi)存生產(chǎn)環(huán)境最好 8 核 16G 起步磁盤(pán)預(yù)留 100G 以上。為什么磁盤(pán)要留這么多因?yàn)橹R(shí)庫(kù)的文檔解析、向量化、緩存和日志都會(huì)持續(xù)增長(zhǎng)我見(jiàn)過(guò)有人磁盤(pán)寫(xiě)滿(mǎn)直接導(dǎo)致 PostgreSQL 容器異常退出所以磁盤(pán)空間千萬(wàn)別卡線(xiàn)。系統(tǒng)方面主流發(fā)行版都可以官方文檔里常見(jiàn)的是 Ubuntu、Debian、CentOS 這類(lèi)。我自己的服務(wù)器是 Debian 系下面命令也按 Debian 系習(xí)慣來(lái)寫(xiě)。如果你是 CentOS 系把 apt 換成 yum防火墻命令改成 firewalld 即可。2.2 安裝 Docker 與 Compose 插件現(xiàn)在 Docker 新版本默認(rèn)自帶 Compose 插件不需要單獨(dú)安裝 docker-compose 二進(jìn)制。先檢查系統(tǒng)里有沒(méi)有裝過(guò)docker --version docker compose version如果提示找不到命令可以按官方源安裝。以 Debian 系為例幾條核心命令是這樣的sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin安裝完成后把當(dāng)前用戶(hù)加入 docker 組避免每次敲命令都要加 sudosudo usermod -aG docker $USER這一步之后重新登錄 shell 或者執(zhí)行 newgrp docker 生效。我遇到過(guò)很多人在這里跳過(guò)導(dǎo)致后續(xù)所有命令都要用 sudo非常影響操作體驗(yàn)。2.3 端口、目錄與防火墻規(guī)劃安裝 Docker 之前先規(guī)劃好 Dify 對(duì)外服務(wù)的端口。默認(rèn)部署包會(huì)用 80 端口給 Web 和 API但服務(wù)器上如果有 Nginx 或者其他站點(diǎn)占用了 80就會(huì)直接沖突。我建議在 .env 文件里把端口改成自定義值比如 8080 和 8081避免和現(xiàn)有服務(wù)糾纏。數(shù)據(jù)目錄規(guī)劃同樣重要。Dify 的 Compose 文件默認(rèn)把數(shù)據(jù)卷交給 Docker 管理雖然方便但我更推薦在部署前就把整個(gè)目錄掛載路徑想清楚比如統(tǒng)一放在 /opt/dify。后續(xù)做備份時(shí)只需要停掉容器打包對(duì)應(yīng)目錄即可。提前規(guī)劃的好處是后期不用遷移數(shù)據(jù)。防火墻方面Debian 系一般用 ufw 或者 iptables。如果改了端口記得放行對(duì)應(yīng)端口否則容器起來(lái)了外部就是訪(fǎng)問(wèn)不到。這里經(jīng)常有人踩坑明明 curl localhost 有響應(yīng)但瀏覽器打不開(kāi)就是防火墻只放行了 80沒(méi)放行自定義端口。2.4 獲取 Dify 部署文件Dify 社區(qū)版在 GitHub 上直接有部署倉(cāng)庫(kù)里面包含了 docker-compose.yaml、.env.example、相關(guān)配置目錄。獲取方式很簡(jiǎn)單git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env需要注意Dify 迭代速度很快master 分支可能是開(kāi)發(fā)版本。我個(gè)人的習(xí)慣是 checkout 到最新的穩(wěn)定發(fā)布 tag而不是直接用 master。因?yàn)殚_(kāi)發(fā)分支有時(shí)候鏡像 tag 還沒(méi)推送完整啟動(dòng)時(shí)會(huì)出現(xiàn)拉取不到鏡像的詭異報(bào)錯(cuò)。3. 核心配置解析環(huán)境變量與 Compose 文件3.1 .env 環(huán)境變量逐項(xiàng)拆解進(jìn)入 dify/docker 目錄后真正決定部署行為的是 .env 文件。我建議不要直接改 docker-compose.yaml而是把可變參數(shù)都放到 .env 里。這個(gè)文件里最關(guān)鍵的幾個(gè)參數(shù)如下EXPOSE_NGINX_PORT80 EXPOSE_NGINX_SSL_PORT443 NGINX_SERVER_NAMElocalhost POSTGRES_PASSWORDchangeme POSTGRES_DBdify REDIS_PASSWORDchangeme DIFY_PORT8080其中 POSTGRES_PASSWORD 和 REDIS_PASSWORD 一定要改成強(qiáng)密碼。默認(rèn)密碼太簡(jiǎn)單如果端口被誤暴露數(shù)據(jù)庫(kù)等于裸奔。NGINX_SERVER_NAME 在實(shí)際生產(chǎn)環(huán)境里要改成你自己的域名否則后面配 HTTPS 證書(shū)時(shí)會(huì)遇到域名不匹配的問(wèn)題。如果你想調(diào)整向量數(shù)據(jù)庫(kù)比如使用 Weaviate 或 Qdrant也需要在這個(gè)文件里配置。默認(rèn)情況下Dify 使用內(nèi)置的 Weaviate 或者 PostgreSQL 的向量擴(kuò)展具體版本要看部署包的默認(rèn)配置。我自己的經(jīng)驗(yàn)是如果知識(shí)庫(kù)數(shù)據(jù)量不大默認(rèn)配置夠用如果要做大規(guī)模 RAG建議單獨(dú)部署獨(dú)立的向量數(shù)據(jù)庫(kù)再用 Dify 的接入功能連過(guò)去。3.2 docker-compose.yaml 的服務(wù)組成打開(kāi) docker-compose.yaml核心服務(wù)包括api提供給前后端調(diào)用的 API 服務(wù)也就是業(yè)務(wù)邏輯入口worker負(fù)責(zé)執(zhí)行異步任務(wù)比如文檔索引、知識(shí)庫(kù)更新、郵件發(fā)送web前端靜態(tài)資源服務(wù)dbPostgreSQL 數(shù)據(jù)庫(kù)redis緩存與任務(wù)隊(duì)列nginx容器內(nèi)部的反向代理ssrf_proxy防止 SSRF 攻擊的代理服務(wù)sandbox安全執(zhí)行 Agent 代碼的沙箱環(huán)境這里面最容易被忽略的是 ssrf_proxy 和 sandbox。ssrf_proxy 把外部模型 API 的請(qǐng)求做了一層過(guò)濾和代理避免模型插件發(fā)起意外的內(nèi)網(wǎng)請(qǐng)求sandbox 為 Agent 里的代碼執(zhí)行提供隔離環(huán)境。生產(chǎn)環(huán)境不要禁用它們否則會(huì)引入安全隱患。Compose 服務(wù)之間的依賴(lài)關(guān)系是通過(guò) depends_on 控制的。數(shù)據(jù)庫(kù)和 Redis 會(huì)先啟動(dòng)等健康檢查通過(guò)后再啟動(dòng) API 服務(wù)。這里有個(gè)小細(xì)節(jié)健康檢查的間隔和超時(shí)參數(shù)已經(jīng)寫(xiě)在 Compose 里如果服務(wù)器性能較差啟動(dòng)時(shí)間會(huì)拉長(zhǎng)不要看到某個(gè)容器還在 restarting 就急著中斷。3.3 數(shù)據(jù)存儲(chǔ)與持久化策略Dify 的數(shù)據(jù)主要存在 PostgreSQL 中包括用戶(hù)、應(yīng)用、工作流、文檔索引元數(shù)據(jù)等。Redis 里存的是會(huì)話(huà)狀態(tài)和異步任務(wù)隊(duì)列。向量數(shù)據(jù)根據(jù)配置可能存在單獨(dú)向量庫(kù)中默認(rèn)會(huì)在 PostgreSQL 里面。此外上傳的原始文檔、處理后的文檔、圖片、圖標(biāo)等文件會(huì)存放在 API 服務(wù)掛載的 volume 里。部署之前要想清楚三個(gè)持久化點(diǎn)PostgreSQL 數(shù)據(jù)卷Redis 數(shù)據(jù)卷Dify 文件存儲(chǔ)目錄這三個(gè)點(diǎn)做好持久化容器刪掉重來(lái)都不怕丟數(shù)據(jù)。我在服務(wù)器上會(huì)把 Compose 文件里的 volume 定義改成具名卷或者宿主目錄綁定原則是至少確認(rèn)這些卷不會(huì)隨著容器刪除被自動(dòng)清空。Docker 的匿名卷在容器重建后可能殘留但容易混淆不如直接用具名卷清晰。4. 完整部署實(shí)操流程4.1 啟動(dòng)整套服務(wù)配置好 .env 之后執(zhí)行docker compose up -d如果你用的是舊版 docker-compose 命令就執(zhí)行 docker-compose up -d。首次啟動(dòng)會(huì)拉取所有鏡像耗時(shí)取決于網(wǎng)絡(luò)和機(jī)器性能。啟動(dòng)完成后依次檢查各容器狀態(tài)docker compose ps正常時(shí)所有服務(wù)狀態(tài)都應(yīng)該是 Up。如果有容器一直顯示 Restarting 或 unhealthy先不要急著訪(fǎng)問(wèn)看日志找原因。docker compose logs -f api docker compose logs -f db我會(huì)習(xí)慣先檢查 db 和 api 兩個(gè)服務(wù)的日志因?yàn)閿?shù)據(jù)庫(kù)初始化往往是最耗時(shí)的環(huán)節(jié)。等 db 日志里出現(xiàn) ready to accept connections 類(lèi)似信息再確認(rèn) api 日志沒(méi)有報(bào)錯(cuò)這時(shí)候整個(gè)系統(tǒng)基本就緒。4.2 首次訪(fǎng)問(wèn)與管理員賬號(hào)創(chuàng)建打開(kāi)瀏覽器訪(fǎng)問(wèn) http://服務(wù)器IP/install。第一次進(jìn)入會(huì)要求設(shè)置管理員郵箱和密碼。這里我多提醒一句管理員密碼一定要用密碼管理器生成不要圖省事。因?yàn)?Dify 管理后臺(tái)權(quán)限極大可以管理所有用戶(hù)、模型和應(yīng)用密碼泄露等于整套平臺(tái)被人拿捏。安裝完成后登錄后臺(tái)。默認(rèn)首頁(yè)會(huì)引導(dǎo)你創(chuàng)建第一個(gè)應(yīng)用。先別急著接真實(shí)模型可以創(chuàng)建一個(gè)空白應(yīng)用把界面流程熟悉一遍。Dify 的應(yīng)用類(lèi)型包括聊天助手、文本生成應(yīng)用、Agent、工作流還有 Chatflow 和 Workflow 兩種編排模式核心區(qū)別在于一個(gè)是對(duì)話(huà)式流程一個(gè)是純?nèi)蝿?wù)處理流程。4.3 接入模型供應(yīng)商模型配置是部署之后最關(guān)鍵的一步。Dify 在設(shè)置里提供了模型供應(yīng)商管理界面支持配置多種大模型服務(wù)。這里有兩種接法第一種是接第三方云 API直接在界面里填 API Key、模型名稱(chēng)、Base URL 等信息。只要你的模型供應(yīng)商提供 OpenAI 兼容接口Dify 基本都能通過(guò)自定義模型供應(yīng)商方式接入。第二種是自己部署本地模型比如通過(guò)本地推理服務(wù)把模型封裝成兼容接口然后在 Dify 里設(shè)置 Base URL 指向本地服務(wù)。這種方式不需要外網(wǎng)流量數(shù)據(jù)全部留在內(nèi)網(wǎng)適合對(duì)數(shù)據(jù)合規(guī)要求高的場(chǎng)景。配置完成后務(wù)必點(diǎn)擊“測(cè)試”按鈕驗(yàn)證連通性。我見(jiàn)過(guò)不少人配置完模型沒(méi)測(cè)試結(jié)果應(yīng)用創(chuàng)建好之后對(duì)話(huà)時(shí)才發(fā)現(xiàn) Key 配錯(cuò)、模型名寫(xiě)錯(cuò)浪費(fèi)了大量時(shí)間。測(cè)試通過(guò)后再去設(shè)計(jì)應(yīng)用流程效率會(huì)高很多。4.4 通過(guò) Nginx 反代與 HTTPS 配置默認(rèn)部署中外部訪(fǎng)問(wèn)直接走 Docker 內(nèi)置 Nginx 的 80 端口。如果只是內(nèi)網(wǎng)試用這樣足夠了。但生產(chǎn)環(huán)境建議在宿主機(jī)上再套一層 Nginx將所有 HTTP 請(qǐng)求轉(zhuǎn)發(fā)到 Dify 的 Nginx 端口同時(shí)完成 HTTPS 證書(shū)配置。這樣證書(shū)和域名解析都集中在宿主機(jī)管理升級(jí) Dify 時(shí)不需要改動(dòng)證書(shū)路徑。宿主機(jī) Nginx 配置片段大概長(zhǎng)這樣server { listen 443 ssl http2; server_name your-domain.example; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; 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; } }這里有一個(gè)關(guān)鍵配置請(qǐng)求頭必須帶上 X-Forwarded-Proto否則平臺(tái)內(nèi)部生成的回調(diào)地址和文件鏈接可能變成 HTTP導(dǎo)致部分功能異常。另一個(gè)容易忽略的點(diǎn)是 websocket 支持Dify 的部分能力依賴(lài) WebSocket所以 proxy_read_timeout 和 proxy_send_timeout 不要設(shè)得太短建議至少 60s。5. 踩坑記錄與問(wèn)題排查5.1 容器啟動(dòng)失敗端口沖突與內(nèi)存不足最常碰到的啟動(dòng)失敗原因有兩個(gè)端口沖突和內(nèi)存不足。先看端口啟動(dòng)前用 ss -lntp 檢查端口占用如果 80 被占用就會(huì)報(bào) bind: address already in use。解決辦法不是強(qiáng) kill 占用進(jìn)程而是改 .env 里的端口。內(nèi)存不足的表現(xiàn)更隱蔽容器日志里可能只顯示數(shù)據(jù)庫(kù)進(jìn)程被 kill或者出現(xiàn) Memory cgroup out of memory。這時(shí)候用 free -m 看下內(nèi)存如果確實(shí)吃緊建議加 swap 或者升級(jí)配置。我的經(jīng)驗(yàn)是測(cè)試環(huán)境 4G 內(nèi)存跑 Dify 太勉強(qiáng)至少 6G 比較穩(wěn)。5.2 模型 API 調(diào)用超時(shí)與配置報(bào)錯(cuò)模型調(diào)用超時(shí)先排查網(wǎng)絡(luò)路徑。在容器內(nèi)部用 curl 測(cè)試模型 API 的連通性docker exec -it dify-api-1 curl -I https://api.example.com如果容器內(nèi)能通而應(yīng)用提示超時(shí)重點(diǎn)檢查 .env 和模型供應(yīng)商配置里的 Base URL 是否寫(xiě)錯(cuò)。另一個(gè)常見(jiàn)問(wèn)題是模型名寫(xiě)錯(cuò)比如云端模型版本號(hào)更新后舊模型名已經(jīng)不可用但界面里沒(méi)同步更新。每次模型供應(yīng)商更新模型列表后建議到 Dify 后臺(tái)重新拉取一次模型列表并核對(duì)默認(rèn)模型。5.3 知識(shí)庫(kù)文檔處理失敗或檢索結(jié)果為空知識(shí)庫(kù)上傳文檔后需要經(jīng)過(guò)切片、向量化這個(gè)流程由 worker 服務(wù)執(zhí)行。如果上傳文檔后狀態(tài)一直停留在“處理中”先查 worker 日志再?gòu)娜齻€(gè)角度排查第一向量數(shù)據(jù)庫(kù)是否正常連接第二模型供應(yīng)商里配置的 Embedding 模型是否可用第三文檔格式是否被支持。Embedding 模型是最容易被忽略的點(diǎn)。有些模型供應(yīng)商的默認(rèn)模型不支持 Embedding 任務(wù)但你只在對(duì)話(huà)模型里配了 Key沒(méi)有單獨(dú)配置 Embedding 模型知識(shí)庫(kù)就會(huì)始終沒(méi)法完成向量化。配置方式是在模型供應(yīng)商設(shè)置里把 Embedding 類(lèi)型的模型單獨(dú)指定一個(gè)可用模型。5.4 文件上傳失敗與權(quán)限問(wèn)題文件上傳失敗時(shí)如果日志里出現(xiàn) permission denied多半是容器內(nèi)工作目錄對(duì)掛載卷沒(méi)有寫(xiě)權(quán)限。檢查宿主機(jī)掛載目錄的屬主和權(quán)限比如chown -R 1000:1000 /opt/dify/volumes因?yàn)槿萜鲀?nèi) API 服務(wù)通常以 UID 1000 運(yùn)行宿主機(jī)目錄如果歸屬 root容器內(nèi)進(jìn)程可能無(wú)法寫(xiě)入。這個(gè)權(quán)限問(wèn)題我在初次部署時(shí)踩過(guò)后來(lái)統(tǒng)一把 Dify 相關(guān)數(shù)據(jù)目錄的屬主設(shè)置成 1000世界清靜了很多。5.5 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查方向80 端口無(wú)法訪(fǎng)問(wèn)防火墻未放行或端口被占用ss -lntp、ufw status容器一直 restarting內(nèi)存不足或配置里密碼錯(cuò)誤free -m、docker compose logs對(duì)話(huà)報(bào)模型 404模型名寫(xiě)錯(cuò)或模型未部署檢查模型供應(yīng)商測(cè)試按鈕知識(shí)庫(kù)不回復(fù)內(nèi)容Embedding 模型未單獨(dú)配置檢查 embedding 類(lèi)型模型上傳文件失敗掛載目錄權(quán)限不對(duì)chown -R 1000:1000刷新后登錄態(tài)丟失Redis 數(shù)據(jù)卷未持久化檢查 Redis volume 配置6. 運(yùn)維擴(kuò)展與升級(jí)維護(hù)6.1 日常運(yùn)維操作日常最常用的運(yùn)維命令主要是看狀態(tài)、看日志、重啟服務(wù)。docker compose ps docker compose logs -f api docker compose restart api修改 .env 后要讓配置生效一般需要重新創(chuàng)建容器docker compose up -d --force-recreate注意修改鏡像 tag 或環(huán)境變量后直接 docker compose up -d 可能不會(huì)重建容器一定要加 --force-recreate或者先 docker compose down 再 up否則容易出現(xiàn)配置改了但容器還是舊參數(shù)的問(wèn)題。6.2 升級(jí) Dify 版本升級(jí)前先備份。Dify 升級(jí)的基本流程是拉取最新部署倉(cāng)庫(kù)或更新當(dāng)前倉(cāng)庫(kù)查看新增的環(huán)境變量然后重新拉鏡像并啟動(dòng)。git pull docker compose pull docker compose up -d升級(jí)時(shí)最容易出問(wèn)題的是數(shù)據(jù)庫(kù)遷移。新版本可能需要執(zhí)行額外的數(shù)據(jù)庫(kù)遷移官方一般會(huì)在升級(jí)文檔里說(shuō)明。我的建議是小版本升級(jí)可以大膽試大版本升級(jí)前務(wù)必在測(cè)試環(huán)境先跑一遍尤其是跨主版本時(shí)環(huán)境變量名稱(chēng)可能有破壞性變化。6.3 備份與恢復(fù)策略備份至少要覆蓋三塊PostgreSQL、Redis、文件數(shù)據(jù)。PostgreSQL 備份最簡(jiǎn)單的方式是用容器內(nèi)置的 pg_dumpdocker exec -i db容器名 pg_dump -U postgres dify dify_backup.sqlRedis 備份則用持久化文件加上定期拷貝。文件數(shù)據(jù)直接打包對(duì)應(yīng) volume 目錄即可?；謴?fù)的話(huà)先啟動(dòng)一套空環(huán)境再把 SQL 導(dǎo)入數(shù)據(jù)庫(kù)把文件解壓回對(duì)應(yīng)目錄最后重啟服務(wù)。完整恢復(fù)流程可以在測(cè)試機(jī)器上演練一次真到出問(wèn)題時(shí)就不用手忙腳亂。6.4 資源限制與高可用擴(kuò)展如果服務(wù)器上還跑著其他服務(wù)建議給 Dify 容器設(shè)置資源上限防止某個(gè)容器把整臺(tái)機(jī)器拖垮。在 Compose 文件里給服務(wù)加 deploy.resources.limits或者直接在 docker run 時(shí)設(shè)置。例如限制 API 服務(wù)最多使用 2 核和 2G 內(nèi)存deploy: resources: limits: cpus: 2 memory: 2G高可用層面Dify 的 API 服務(wù)和 Worker 其實(shí)都可以橫向擴(kuò)容。數(shù)據(jù)庫(kù)和 Redis 建議已有主從或備份機(jī)制時(shí)再做擴(kuò)容否則只是增加 API 副本數(shù)據(jù)庫(kù)反而成為瓶頸。對(duì)多數(shù)團(tuán)隊(duì)來(lái)說(shuō)先保證備份完整比盲目堆副本更實(shí)在。寫(xiě)到這里我再分享一點(diǎn)個(gè)人體會(huì)。Dify 這套平臺(tái)用 Docker 部署真正麻煩的地方往往不是 Docker 本身而是對(duì)環(huán)境變量的理解、對(duì)數(shù)據(jù)卷的把控、以及對(duì)模型服務(wù)的理解。我第一次部署時(shí)因?yàn)橄胧∈聸](méi)改默認(rèn)密碼結(jié)果第二天發(fā)現(xiàn)有人在嘗試登錄后臺(tái)雖然沒(méi)成功但那種后背發(fā)涼的感覺(jué)至今記得。后來(lái)我養(yǎng)成了幾個(gè)習(xí)慣部署前先把 .env 改成強(qiáng)密碼和自定義端口部署后立刻做一次全量備份升級(jí)前先在測(cè)試環(huán)境驗(yàn)證一遍。這幾點(diǎn)看著簡(jiǎn)單但每一條都能幫你避免一次深夜事故。如果你也在規(guī)劃私有化的大模型應(yīng)用平臺(tái)照著這套思路走至少不會(huì)掉進(jìn)同一個(gè)坑里。 Dify私有化部署實(shí)戰(zhàn)：Linux服務(wù)器+Docker Compose指南
開(kāi)頭從一次真實(shí)的部署說(shuō)起。有段時(shí)間我在Linux服務(wù)器上反復(fù)折騰容器應(yīng)用最頭疼的還不是容器本身而是應(yīng)用之間的依賴(lài)關(guān)系、初始化順序、數(shù)據(jù)卷到底應(yīng)該怎么掛。后來(lái)接觸到一個(gè)叫 Dify 的開(kāi)源項(xiàng)目發(fā)現(xiàn)它的定位很有意思不是普通聊天機(jī)器人而是把大模型應(yīng)用開(kāi)發(fā)里的提示詞編排、知識(shí)庫(kù)檢索、Agent 工作流、模型管理等環(huán)節(jié)全部可視化部署形式也是我熟悉的 Docker 容器。于是我用一臺(tái) Linux 服務(wù)器通過(guò) Docker Compose 把整套 Dify 拉起來(lái)前后整理了不少配置細(xì)節(jié)和踩坑記錄今天一次性寫(xiě)出來(lái)。這東西適合誰(shuí)參考如果你正在做 LLM 應(yīng)用的快速原型或者想把企業(yè)內(nèi)部的知識(shí)庫(kù)助手、客服問(wèn)答機(jī)器人落地到自有服務(wù)器又不想從零寫(xiě)編排代碼那么 Dify 就是你需要的平臺(tái)。它本身支持私有化部署數(shù)據(jù)在你自己手里模型 API 可以接各家廠(chǎng)商也可以接本地模型服務(wù)。無(wú)論你是后端開(kāi)發(fā)、運(yùn)維還是產(chǎn)品側(cè)的技術(shù)負(fù)責(zé)人只要熟悉基本 Linux 命令和 Docker 操作照著下面的步驟走基本能在一小時(shí)內(nèi)把整套平臺(tái)跑起來(lái)。1. 整體設(shè)計(jì)思路與部署架構(gòu)拆解1.1 Dify 到底解決了什么問(wèn)題先理解 Dify 在技術(shù)棧里的位置。它屬于大模型應(yīng)用開(kāi)發(fā)平臺(tái)底層還是調(diào)用外部大模型 API 或本地模型服務(wù)但上層把業(yè)務(wù)方最常做的事封裝成了可拖拽、可配置的積木。比如你想做一個(gè)帶知識(shí)庫(kù)的問(wèn)答機(jī)器人傳統(tǒng)做法是寫(xiě)代碼搭向量數(shù)據(jù)庫(kù)、做文檔切片、寫(xiě)召回邏輯、設(shè)計(jì) Prompt 模板、處理會(huì)話(huà)上下文再寫(xiě)一套管理后臺(tái)。用 Dify 之后這些能力以現(xiàn)成模塊的形式出現(xiàn)在界面上你只需要配置知識(shí)庫(kù)來(lái)源、選擇模型、編排工作流即可。從部署者的角度看Dify 不是一個(gè)單體程序而是一組相互協(xié)作的服務(wù)集合。它包含 Web 前端、API 服務(wù)、異步任務(wù) Worker、PostgreSQL 數(shù)據(jù)庫(kù)、Redis 緩存、模型請(qǐng)求代理、安全沙箱等組件。這種架構(gòu)天然適合容器化每個(gè)組件是獨(dú)立鏡像通過(guò) Docker Compose 統(tǒng)一編排啟動(dòng)順序和數(shù)據(jù)卷都在一份配置里定義好。這也是我選擇在 Linux 服務(wù)器上用 Docker 部署的核心理由。1.2 為什么選用 Linux 服務(wù)器加 Docker 組合先說(shuō) Linux 服務(wù)器。Dify 官方提供的部署方式里最順手的其實(shí)就是 Linux 加 Docker Compose。Windows 上雖然有 Docker Desktop但 mount 路徑、權(quán)限、換行符、端口監(jiān)聽(tīng)這些細(xì)節(jié)容易出問(wèn)題macOS 本地跑跑沒(méi)問(wèn)題但長(zhǎng)期作為服務(wù)運(yùn)行還是 Linux 更省心。Linux 環(huán)境下 systemd 管理方便日志清理、開(kāi)機(jī)自啟、防火墻策略都更成熟。再說(shuō) Docker。容器化帶來(lái)的最大好處是可復(fù)現(xiàn)性。同一份 Compose 文件在測(cè)試服務(wù)器上驗(yàn)證過(guò)之后生產(chǎn)環(huán)境直接照搬只要系統(tǒng)版本和端口不沖突結(jié)果基本一樣。另一個(gè)好處是隔離Dify 依賴(lài)的 PostgreSQL 和 Redis 版本是自己要求的如果直接裝在宿主機(jī)上很可能和服務(wù)器里已有的 MySQL、Redis 實(shí)例產(chǎn)生版本沖突。用容器之后每個(gè)依賴(lài)都被隔離在獨(dú)立環(huán)境里升級(jí) Dify 時(shí)只需要換鏡像不需要污染宿主機(jī)環(huán)境。1.3 部署架構(gòu)全景圖這套架構(gòu)可以拆成三層來(lái)看。最外層是接入層一般用 Nginx 或 Caddy 對(duì)外提供 HTTPS 訪(fǎng)問(wèn)中間是 Dify 的核心服務(wù)群包括 API 服務(wù)、Web 前端、Worker 異步任務(wù)、SSRF 代理、Sandbox底層是基礎(chǔ)設(shè)施服務(wù)包括 PostgreSQL 和 Redis以及可選的向量數(shù)據(jù)庫(kù)。需要注意的是生產(chǎn)環(huán)境下千萬(wàn)不要直接把 PostgreSQL 和 Redis 的端口暴露到公網(wǎng)。它們只需要在 Docker 內(nèi)網(wǎng)里被 Dify 各服務(wù)訪(fǎng)問(wèn)即可。對(duì)外真正需要暴露的是 Web 端口和 API 端口建議通過(guò)宿主機(jī)的 Nginx 反代而不是直接把容器端口裸奔出去。2. 部署前的環(huán)境準(zhǔn)備2.1 服務(wù)器配置要求先給出我實(shí)測(cè)過(guò)的配置底線(xiàn)。如果只是測(cè)試環(huán)境2 核 CPU、4G 內(nèi)存、40G 磁盤(pán)基本能跑但體驗(yàn)會(huì)比較緊尤其是首次啟動(dòng)時(shí)多個(gè)容器同時(shí)初始化內(nèi)存可能瞬間沖到 3G 以上。我建議個(gè)人使用或者小團(tuán)隊(duì)試用至少 4 核 8G 內(nèi)存生產(chǎn)環(huán)境最好 8 核 16G 起步磁盤(pán)預(yù)留 100G 以上。為什么磁盤(pán)要留這么多因?yàn)橹R(shí)庫(kù)的文檔解析、向量化、緩存和日志都會(huì)持續(xù)增長(zhǎng)我見(jiàn)過(guò)有人磁盤(pán)寫(xiě)滿(mǎn)直接導(dǎo)致 PostgreSQL 容器異常退出所以磁盤(pán)空間千萬(wàn)別卡線(xiàn)。系統(tǒng)方面主流發(fā)行版都可以官方文檔里常見(jiàn)的是 Ubuntu、Debian、CentOS 這類(lèi)。我自己的服務(wù)器是 Debian 系下面命令也按 Debian 系習(xí)慣來(lái)寫(xiě)。如果你是 CentOS 系把 apt 換成 yum防火墻命令改成 firewalld 即可。2.2 安裝 Docker 與 Compose 插件現(xiàn)在 Docker 新版本默認(rèn)自帶 Compose 插件不需要單獨(dú)安裝 docker-compose 二進(jìn)制。先檢查系統(tǒng)里有沒(méi)有裝過(guò)docker --version docker compose version如果提示找不到命令可以按官方源安裝。以 Debian 系為例幾條核心命令是這樣的sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin安裝完成后把當(dāng)前用戶(hù)加入 docker 組避免每次敲命令都要加 sudosudo usermod -aG docker $USER這一步之后重新登錄 shell 或者執(zhí)行 newgrp docker 生效。我遇到過(guò)很多人在這里跳過(guò)導(dǎo)致后續(xù)所有命令都要用 sudo非常影響操作體驗(yàn)。2.3 端口、目錄與防火墻規(guī)劃安裝 Docker 之前先規(guī)劃好 Dify 對(duì)外服務(wù)的端口。默認(rèn)部署包會(huì)用 80 端口給 Web 和 API但服務(wù)器上如果有 Nginx 或者其他站點(diǎn)占用了 80就會(huì)直接沖突。我建議在 .env 文件里把端口改成自定義值比如 8080 和 8081避免和現(xiàn)有服務(wù)糾纏。數(shù)據(jù)目錄規(guī)劃同樣重要。Dify 的 Compose 文件默認(rèn)把數(shù)據(jù)卷交給 Docker 管理雖然方便但我更推薦在部署前就把整個(gè)目錄掛載路徑想清楚比如統(tǒng)一放在 /opt/dify。后續(xù)做備份時(shí)只需要停掉容器打包對(duì)應(yīng)目錄即可。提前規(guī)劃的好處是后期不用遷移數(shù)據(jù)。防火墻方面Debian 系一般用 ufw 或者 iptables。如果改了端口記得放行對(duì)應(yīng)端口否則容器起來(lái)了外部就是訪(fǎng)問(wèn)不到。這里經(jīng)常有人踩坑明明 curl localhost 有響應(yīng)但瀏覽器打不開(kāi)就是防火墻只放行了 80沒(méi)放行自定義端口。2.4 獲取 Dify 部署文件Dify 社區(qū)版在 GitHub 上直接有部署倉(cāng)庫(kù)里面包含了 docker-compose.yaml、.env.example、相關(guān)配置目錄。獲取方式很簡(jiǎn)單git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env需要注意Dify 迭代速度很快master 分支可能是開(kāi)發(fā)版本。我個(gè)人的習(xí)慣是 checkout 到最新的穩(wěn)定發(fā)布 tag而不是直接用 master。因?yàn)殚_(kāi)發(fā)分支有時(shí)候鏡像 tag 還沒(méi)推送完整啟動(dòng)時(shí)會(huì)出現(xiàn)拉取不到鏡像的詭異報(bào)錯(cuò)。3. 核心配置解析環(huán)境變量與 Compose 文件3.1 .env 環(huán)境變量逐項(xiàng)拆解進(jìn)入 dify/docker 目錄后真正決定部署行為的是 .env 文件。我建議不要直接改 docker-compose.yaml而是把可變參數(shù)都放到 .env 里。這個(gè)文件里最關(guān)鍵的幾個(gè)參數(shù)如下EXPOSE_NGINX_PORT80 EXPOSE_NGINX_SSL_PORT443 NGINX_SERVER_NAMElocalhost POSTGRES_PASSWORDchangeme POSTGRES_DBdify REDIS_PASSWORDchangeme DIFY_PORT8080其中 POSTGRES_PASSWORD 和 REDIS_PASSWORD 一定要改成強(qiáng)密碼。默認(rèn)密碼太簡(jiǎn)單如果端口被誤暴露數(shù)據(jù)庫(kù)等于裸奔。NGINX_SERVER_NAME 在實(shí)際生產(chǎn)環(huán)境里要改成你自己的域名否則后面配 HTTPS 證書(shū)時(shí)會(huì)遇到域名不匹配的問(wèn)題。如果你想調(diào)整向量數(shù)據(jù)庫(kù)比如使用 Weaviate 或 Qdrant也需要在這個(gè)文件里配置。默認(rèn)情況下Dify 使用內(nèi)置的 Weaviate 或者 PostgreSQL 的向量擴(kuò)展具體版本要看部署包的默認(rèn)配置。我自己的經(jīng)驗(yàn)是如果知識(shí)庫(kù)數(shù)據(jù)量不大默認(rèn)配置夠用如果要做大規(guī)模 RAG建議單獨(dú)部署獨(dú)立的向量數(shù)據(jù)庫(kù)再用 Dify 的接入功能連過(guò)去。3.2 docker-compose.yaml 的服務(wù)組成打開(kāi) docker-compose.yaml核心服務(wù)包括api提供給前后端調(diào)用的 API 服務(wù)也就是業(yè)務(wù)邏輯入口worker負(fù)責(zé)執(zhí)行異步任務(wù)比如文檔索引、知識(shí)庫(kù)更新、郵件發(fā)送web前端靜態(tài)資源服務(wù)dbPostgreSQL 數(shù)據(jù)庫(kù)redis緩存與任務(wù)隊(duì)列nginx容器內(nèi)部的反向代理ssrf_proxy防止 SSRF 攻擊的代理服務(wù)sandbox安全執(zhí)行 Agent 代碼的沙箱環(huán)境這里面最容易被忽略的是 ssrf_proxy 和 sandbox。ssrf_proxy 把外部模型 API 的請(qǐng)求做了一層過(guò)濾和代理避免模型插件發(fā)起意外的內(nèi)網(wǎng)請(qǐng)求sandbox 為 Agent 里的代碼執(zhí)行提供隔離環(huán)境。生產(chǎn)環(huán)境不要禁用它們否則會(huì)引入安全隱患。Compose 服務(wù)之間的依賴(lài)關(guān)系是通過(guò) depends_on 控制的。數(shù)據(jù)庫(kù)和 Redis 會(huì)先啟動(dòng)等健康檢查通過(guò)后再啟動(dòng) API 服務(wù)。這里有個(gè)小細(xì)節(jié)健康檢查的間隔和超時(shí)參數(shù)已經(jīng)寫(xiě)在 Compose 里如果服務(wù)器性能較差啟動(dòng)時(shí)間會(huì)拉長(zhǎng)不要看到某個(gè)容器還在 restarting 就急著中斷。3.3 數(shù)據(jù)存儲(chǔ)與持久化策略Dify 的數(shù)據(jù)主要存在 PostgreSQL 中包括用戶(hù)、應(yīng)用、工作流、文檔索引元數(shù)據(jù)等。Redis 里存的是會(huì)話(huà)狀態(tài)和異步任務(wù)隊(duì)列。向量數(shù)據(jù)根據(jù)配置可能存在單獨(dú)向量庫(kù)中默認(rèn)會(huì)在 PostgreSQL 里面。此外上傳的原始文檔、處理后的文檔、圖片、圖標(biāo)等文件會(huì)存放在 API 服務(wù)掛載的 volume 里。部署之前要想清楚三個(gè)持久化點(diǎn)PostgreSQL 數(shù)據(jù)卷Redis 數(shù)據(jù)卷Dify 文件存儲(chǔ)目錄這三個(gè)點(diǎn)做好持久化容器刪掉重來(lái)都不怕丟數(shù)據(jù)。我在服務(wù)器上會(huì)把 Compose 文件里的 volume 定義改成具名卷或者宿主目錄綁定原則是至少確認(rèn)這些卷不會(huì)隨著容器刪除被自動(dòng)清空。Docker 的匿名卷在容器重建后可能殘留但容易混淆不如直接用具名卷清晰。4. 完整部署實(shí)操流程4.1 啟動(dòng)整套服務(wù)配置好 .env 之后執(zhí)行docker compose up -d如果你用的是舊版 docker-compose 命令就執(zhí)行 docker-compose up -d。首次啟動(dòng)會(huì)拉取所有鏡像耗時(shí)取決于網(wǎng)絡(luò)和機(jī)器性能。啟動(dòng)完成后依次檢查各容器狀態(tài)docker compose ps正常時(shí)所有服務(wù)狀態(tài)都應(yīng)該是 Up。如果有容器一直顯示 Restarting 或 unhealthy先不要急著訪(fǎng)問(wèn)看日志找原因。docker compose logs -f api docker compose logs -f db我會(huì)習(xí)慣先檢查 db 和 api 兩個(gè)服務(wù)的日志因?yàn)閿?shù)據(jù)庫(kù)初始化往往是最耗時(shí)的環(huán)節(jié)。等 db 日志里出現(xiàn) ready to accept connections 類(lèi)似信息再確認(rèn) api 日志沒(méi)有報(bào)錯(cuò)這時(shí)候整個(gè)系統(tǒng)基本就緒。4.2 首次訪(fǎng)問(wèn)與管理員賬號(hào)創(chuàng)建打開(kāi)瀏覽器訪(fǎng)問(wèn) http://服務(wù)器IP/install。第一次進(jìn)入會(huì)要求設(shè)置管理員郵箱和密碼。這里我多提醒一句管理員密碼一定要用密碼管理器生成不要圖省事。因?yàn)?Dify 管理后臺(tái)權(quán)限極大可以管理所有用戶(hù)、模型和應(yīng)用密碼泄露等于整套平臺(tái)被人拿捏。安裝完成后登錄后臺(tái)。默認(rèn)首頁(yè)會(huì)引導(dǎo)你創(chuàng)建第一個(gè)應(yīng)用。先別急著接真實(shí)模型可以創(chuàng)建一個(gè)空白應(yīng)用把界面流程熟悉一遍。Dify 的應(yīng)用類(lèi)型包括聊天助手、文本生成應(yīng)用、Agent、工作流還有 Chatflow 和 Workflow 兩種編排模式核心區(qū)別在于一個(gè)是對(duì)話(huà)式流程一個(gè)是純?nèi)蝿?wù)處理流程。4.3 接入模型供應(yīng)商模型配置是部署之后最關(guān)鍵的一步。Dify 在設(shè)置里提供了模型供應(yīng)商管理界面支持配置多種大模型服務(wù)。這里有兩種接法第一種是接第三方云 API直接在界面里填 API Key、模型名稱(chēng)、Base URL 等信息。只要你的模型供應(yīng)商提供 OpenAI 兼容接口Dify 基本都能通過(guò)自定義模型供應(yīng)商方式接入。第二種是自己部署本地模型比如通過(guò)本地推理服務(wù)把模型封裝成兼容接口然后在 Dify 里設(shè)置 Base URL 指向本地服務(wù)。這種方式不需要外網(wǎng)流量數(shù)據(jù)全部留在內(nèi)網(wǎng)適合對(duì)數(shù)據(jù)合規(guī)要求高的場(chǎng)景。配置完成后務(wù)必點(diǎn)擊“測(cè)試”按鈕驗(yàn)證連通性。我見(jiàn)過(guò)不少人配置完模型沒(méi)測(cè)試結(jié)果應(yīng)用創(chuàng)建好之后對(duì)話(huà)時(shí)才發(fā)現(xiàn) Key 配錯(cuò)、模型名寫(xiě)錯(cuò)浪費(fèi)了大量時(shí)間。測(cè)試通過(guò)后再去設(shè)計(jì)應(yīng)用流程效率會(huì)高很多。4.4 通過(guò) Nginx 反代與 HTTPS 配置默認(rèn)部署中外部訪(fǎng)問(wèn)直接走 Docker 內(nèi)置 Nginx 的 80 端口。如果只是內(nèi)網(wǎng)試用這樣足夠了。但生產(chǎn)環(huán)境建議在宿主機(jī)上再套一層 Nginx將所有 HTTP 請(qǐng)求轉(zhuǎn)發(fā)到 Dify 的 Nginx 端口同時(shí)完成 HTTPS 證書(shū)配置。這樣證書(shū)和域名解析都集中在宿主機(jī)管理升級(jí) Dify 時(shí)不需要改動(dòng)證書(shū)路徑。宿主機(jī) Nginx 配置片段大概長(zhǎng)這樣server { listen 443 ssl http2; server_name your-domain.example; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; 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; } }這里有一個(gè)關(guān)鍵配置請(qǐng)求頭必須帶上 X-Forwarded-Proto否則平臺(tái)內(nèi)部生成的回調(diào)地址和文件鏈接可能變成 HTTP導(dǎo)致部分功能異常。另一個(gè)容易忽略的點(diǎn)是 websocket 支持Dify 的部分能力依賴(lài) WebSocket所以 proxy_read_timeout 和 proxy_send_timeout 不要設(shè)得太短建議至少 60s。5. 踩坑記錄與問(wèn)題排查5.1 容器啟動(dòng)失敗端口沖突與內(nèi)存不足最常碰到的啟動(dòng)失敗原因有兩個(gè)端口沖突和內(nèi)存不足。先看端口啟動(dòng)前用 ss -lntp 檢查端口占用如果 80 被占用就會(huì)報(bào) bind: address already in use。解決辦法不是強(qiáng) kill 占用進(jìn)程而是改 .env 里的端口。內(nèi)存不足的表現(xiàn)更隱蔽容器日志里可能只顯示數(shù)據(jù)庫(kù)進(jìn)程被 kill或者出現(xiàn) Memory cgroup out of memory。這時(shí)候用 free -m 看下內(nèi)存如果確實(shí)吃緊建議加 swap 或者升級(jí)配置。我的經(jīng)驗(yàn)是測(cè)試環(huán)境 4G 內(nèi)存跑 Dify 太勉強(qiáng)至少 6G 比較穩(wěn)。5.2 模型 API 調(diào)用超時(shí)與配置報(bào)錯(cuò)模型調(diào)用超時(shí)先排查網(wǎng)絡(luò)路徑。在容器內(nèi)部用 curl 測(cè)試模型 API 的連通性docker exec -it dify-api-1 curl -I https://api.example.com如果容器內(nèi)能通而應(yīng)用提示超時(shí)重點(diǎn)檢查 .env 和模型供應(yīng)商配置里的 Base URL 是否寫(xiě)錯(cuò)。另一個(gè)常見(jiàn)問(wèn)題是模型名寫(xiě)錯(cuò)比如云端模型版本號(hào)更新后舊模型名已經(jīng)不可用但界面里沒(méi)同步更新。每次模型供應(yīng)商更新模型列表后建議到 Dify 后臺(tái)重新拉取一次模型列表并核對(duì)默認(rèn)模型。5.3 知識(shí)庫(kù)文檔處理失敗或檢索結(jié)果為空知識(shí)庫(kù)上傳文檔后需要經(jīng)過(guò)切片、向量化這個(gè)流程由 worker 服務(wù)執(zhí)行。如果上傳文檔后狀態(tài)一直停留在“處理中”先查 worker 日志再?gòu)娜齻€(gè)角度排查第一向量數(shù)據(jù)庫(kù)是否正常連接第二模型供應(yīng)商里配置的 Embedding 模型是否可用第三文檔格式是否被支持。Embedding 模型是最容易被忽略的點(diǎn)。有些模型供應(yīng)商的默認(rèn)模型不支持 Embedding 任務(wù)但你只在對(duì)話(huà)模型里配了 Key沒(méi)有單獨(dú)配置 Embedding 模型知識(shí)庫(kù)就會(huì)始終沒(méi)法完成向量化。配置方式是在模型供應(yīng)商設(shè)置里把 Embedding 類(lèi)型的模型單獨(dú)指定一個(gè)可用模型。5.4 文件上傳失敗與權(quán)限問(wèn)題文件上傳失敗時(shí)如果日志里出現(xiàn) permission denied多半是容器內(nèi)工作目錄對(duì)掛載卷沒(méi)有寫(xiě)權(quán)限。檢查宿主機(jī)掛載目錄的屬主和權(quán)限比如chown -R 1000:1000 /opt/dify/volumes因?yàn)槿萜鲀?nèi) API 服務(wù)通常以 UID 1000 運(yùn)行宿主機(jī)目錄如果歸屬 root容器內(nèi)進(jìn)程可能無(wú)法寫(xiě)入。這個(gè)權(quán)限問(wèn)題我在初次部署時(shí)踩過(guò)后來(lái)統(tǒng)一把 Dify 相關(guān)數(shù)據(jù)目錄的屬主設(shè)置成 1000世界清靜了很多。5.5 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查方向80 端口無(wú)法訪(fǎng)問(wèn)防火墻未放行或端口被占用ss -lntp、ufw status容器一直 restarting內(nèi)存不足或配置里密碼錯(cuò)誤free -m、docker compose logs對(duì)話(huà)報(bào)模型 404模型名寫(xiě)錯(cuò)或模型未部署檢查模型供應(yīng)商測(cè)試按鈕知識(shí)庫(kù)不回復(fù)內(nèi)容Embedding 模型未單獨(dú)配置檢查 embedding 類(lèi)型模型上傳文件失敗掛載目錄權(quán)限不對(duì)chown -R 1000:1000刷新后登錄態(tài)丟失Redis 數(shù)據(jù)卷未持久化檢查 Redis volume 配置6. 運(yùn)維擴(kuò)展與升級(jí)維護(hù)6.1 日常運(yùn)維操作日常最常用的運(yùn)維命令主要是看狀態(tài)、看日志、重啟服務(wù)。docker compose ps docker compose logs -f api docker compose restart api修改 .env 后要讓配置生效一般需要重新創(chuàng)建容器docker compose up -d --force-recreate注意修改鏡像 tag 或環(huán)境變量后直接 docker compose up -d 可能不會(huì)重建容器一定要加 --force-recreate或者先 docker compose down 再 up否則容易出現(xiàn)配置改了但容器還是舊參數(shù)的問(wèn)題。6.2 升級(jí) Dify 版本升級(jí)前先備份。Dify 升級(jí)的基本流程是拉取最新部署倉(cāng)庫(kù)或更新當(dāng)前倉(cāng)庫(kù)查看新增的環(huán)境變量然后重新拉鏡像并啟動(dòng)。git pull docker compose pull docker compose up -d升級(jí)時(shí)最容易出問(wèn)題的是數(shù)據(jù)庫(kù)遷移。新版本可能需要執(zhí)行額外的數(shù)據(jù)庫(kù)遷移官方一般會(huì)在升級(jí)文檔里說(shuō)明。我的建議是小版本升級(jí)可以大膽試大版本升級(jí)前務(wù)必在測(cè)試環(huán)境先跑一遍尤其是跨主版本時(shí)環(huán)境變量名稱(chēng)可能有破壞性變化。6.3 備份與恢復(fù)策略備份至少要覆蓋三塊PostgreSQL、Redis、文件數(shù)據(jù)。PostgreSQL 備份最簡(jiǎn)單的方式是用容器內(nèi)置的 pg_dumpdocker exec -i db容器名 pg_dump -U postgres dify dify_backup.sqlRedis 備份則用持久化文件加上定期拷貝。文件數(shù)據(jù)直接打包對(duì)應(yīng) volume 目錄即可?；謴?fù)的話(huà)先啟動(dòng)一套空環(huán)境再把 SQL 導(dǎo)入數(shù)據(jù)庫(kù)把文件解壓回對(duì)應(yīng)目錄最后重啟服務(wù)。完整恢復(fù)流程可以在測(cè)試機(jī)器上演練一次真到出問(wèn)題時(shí)就不用手忙腳亂。6.4 資源限制與高可用擴(kuò)展如果服務(wù)器上還跑著其他服務(wù)建議給 Dify 容器設(shè)置資源上限防止某個(gè)容器把整臺(tái)機(jī)器拖垮。在 Compose 文件里給服務(wù)加 deploy.resources.limits或者直接在 docker run 時(shí)設(shè)置。例如限制 API 服務(wù)最多使用 2 核和 2G 內(nèi)存deploy: resources: limits: cpus: 2 memory: 2G高可用層面Dify 的 API 服務(wù)和 Worker 其實(shí)都可以橫向擴(kuò)容。數(shù)據(jù)庫(kù)和 Redis 建議已有主從或備份機(jī)制時(shí)再做擴(kuò)容否則只是增加 API 副本數(shù)據(jù)庫(kù)反而成為瓶頸。對(duì)多數(shù)團(tuán)隊(duì)來(lái)說(shuō)先保證備份完整比盲目堆副本更實(shí)在。寫(xiě)到這里我再分享一點(diǎn)個(gè)人體會(huì)。Dify 這套平臺(tái)用 Docker 部署真正麻煩的地方往往不是 Docker 本身而是對(duì)環(huán)境變量的理解、對(duì)數(shù)據(jù)卷的把控、以及對(duì)模型服務(wù)的理解。我第一次部署時(shí)因?yàn)橄胧∈聸](méi)改默認(rèn)密碼結(jié)果第二天發(fā)現(xiàn)有人在嘗試登錄后臺(tái)雖然沒(méi)成功但那種后背發(fā)涼的感覺(jué)至今記得。后來(lái)我養(yǎng)成了幾個(gè)習(xí)慣部署前先把 .env 改成強(qiáng)密碼和自定義端口部署后立刻做一次全量備份升級(jí)前先在測(cè)試環(huán)境驗(yàn)證一遍。這幾點(diǎn)看著簡(jiǎn)單但每一條都能幫你避免一次深夜事故。如果你也在規(guī)劃私有化的大模型應(yīng)用平臺(tái)照著這套思路走至少不會(huì)掉進(jìn)同一個(gè)坑里。