Dify VPS Docker Compose 自架教學
Dify 預設會啟動 15 個容器,最低需要 4 GiB RAM。首次啟動前先在 .env 修改預設密碼,並在其他人之前前往 /install 取得管理員帳號。
Dify 是什麼,以及你將執行哪些元件
Dify 是一個可自行託管的平台,用於建構以大型語言模型為基礎的應用程式。你可以使用網頁介面設計聊天應用程式、agent 與檢索管線,透過 API 從自己的程式碼呼叫這些功能,並在同一處管理提示詞、資料集與模型金鑰。小型團隊通常會部署這類工具,讓所有人都以同一個私有基礎環境建構應用程式,而不是把 API 金鑰分散在各個指令碼中。如果你仍不熟悉 agent、tool call 與檢索管線等概念,先從頭了解這些概念,就能把 Dify 的建構介面視為熟悉的控制項,而不是一面沒有標示的開關牆。
自行執行 Dify 代表必須執行許多相互依賴的元件。截至 2026 年 10 月,Dify 文件所述的預設堆疊會啟動 15 個長時間執行的容器,另有一個只執行一次、設定檔案權限後結束的工作。其中 7 個是 Dify 自有服務:API server、websocket server、background worker、scheduler、web frontend、plugin daemon 及 agent backend。另外 8 個是相依元件:Postgres database、Redis cache、Weaviate vector database、nginx front door、2 個 code sandbox,以及 2 個 SSRF proxy。Docker Compose 會將這些元件全部串接起來,但這確實是一個完整的堆疊。Dify 文件所述的最低需求是 4 GiB RAM 與 2 個 CPU core。如果這台 VPS 還要執行其他服務,應依據實測數據評估規模,不要只看官方宣稱的需求,因為PhotoPrism 與 Immich也需要自己的記憶體,而與 Dify 共用主機的相片伺服器會和 Dify 的 database 與 vector store 競爭資源。CPU 競爭也會造成相同問題:將 Jellyfin library 重新套用 90s 影音出租店外觀時,單純瀏覽封面幾乎不需要額外資源;但只要有人開始轉碼,Dify 的 worker 就會排在轉碼工作後面。好處是,無論你在 Dify 上建構多少應用程式,容器數量都維持固定。這比OpenBot 中每個 AI coworker 都各自使用一個容器與自己的 browser更容易控制成本,因為每增加一個 AI coworker,記憶體最低需求就會再次上升。
由於 Dify 會保存你的模型 API 金鑰,以及通常會載入供檢索使用的私人文件,因此從一開始就應將執行 Dify 的主機視為敏感環境。本指南會先安裝 Dify,再依照保護任何保存 secret 的服務的方式強化安全性。
必要條件
您需要一台執行 Ubuntu 24.04 的 VPS,至少具備 4 GiB RAM 與 2 個 CPU 核心,並安裝 Docker 及 Docker Compose plugin(Dify 需要 Compose 2.35.0 或更新版本)。此外,還需要具備 sudo 的使用者,或屬於 docker 群組的使用者。下方的 clone 指令也會使用 git、curl 與 jq。如果您不熟悉 Docker,VPS 上的 Docker Compose 基礎涵蓋本指南所需的安裝方式與核心指令。建議準備一個指向該伺服器的網域名稱,因為您會希望在 Dify 前方設定 TLS,而不是直接使用裸 IP 位址。
步驟 1:取得 Dify 及其 Compose 檔案
Dify 將 Docker 設定放在主要 repository 中。請 clone 最新的 release,不要使用 development branch,然後進入 docker 目錄:
git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env如果 clone 失敗並顯示「Remote branch null」錯誤,表示 GitHub API 查詢沒有傳回結果。請從 releases 頁面選擇版本,然後手動將版本傳給 --branch。
.env 檔案是核心設定。開始任何操作前,請先閱讀此檔案。首先應處理設定密碼與 secret 的值:SECRET_KEY、Postgres 密碼及 Redis 密碼。SECRET_KEY 預設為空白;若維持空白,Dify 會產生金鑰,並將其存放在儲存目錄中。密碼則不同:envs/ 下的內建預設值會為 Postgres 和 Redis 設定相同的 difyai123456,也會為 code sandbox、plugin daemon、Weaviate 及 agent backend 設定固定且公開可知的金鑰。目前的 .env.example 只包含預設的 Compose profiles 及必要的 agent sandbox token;請將自訂憑證覆寫值加入 .env。如果要自行設定 secret key,請產生一組:
openssl rand -base64 42將結果貼到 SECRET_KEY,並為 DB_PASSWORD、REDIS_PASSWORD、PLUGIN_DAEMON_KEY 及 PLUGIN_DIFY_INNER_API_KEY 設定強度高且彼此不同的值。將 SANDBOX_API_KEY 和 CODE_EXECUTION_API_KEY 設為同一組獨立的 secret。將 WEAVIATE_API_KEY 和 WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS 設為另一組獨立的 secret,並設定 WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false。目前預設的 CELERY_BROKER_URL 會從 REDIS_PASSWORD 衍生密碼;如果明確覆寫 URL,也請同步更新其密碼。
使用 openssl rand -base64 32 產生獨立的 token,並在啟動 stack 前於 .env 中設定 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN。沒有這項設定時,agent backend 及其 sandbox 不會啟動。另請將 DIFY_AGENT_API_TOKEN 替換為獨立的隨機 token,並使用 openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' 產生未填補的 base64url 值,確保解碼後正好為 32 bytes,然後將該值設定給 DIFY_AGENT_SERVER_SECRET_KEY。
步驟 2:啟動
啟動整個服務堆疊:
docker compose up -d第一次執行會下載數個映像檔並初始化資料庫,因此請稍候片刻。確認容器狀態正常:
docker compose ps每個長時間執行的服務都應讀取 running;一次性權限工作會在完成任務後結束。Dify 預設會透過內建的 nginx 容器,在 port 80 提供 Web 介面。第一次造訪 http://YOUR_SERVER/install 時,請建立管理員帳號。請立即完成此操作,避免其他人先連線至該 port,因為在帳號建立前,任何載入該頁面的人都能註冊並取得執行個體的控制權。
若要讓遠端瀏覽器進行即時協作,請在 .env 中將 NEXT_PUBLIC_SOCKET_URL 設為伺服器的 WebSocket 位址,並透過 HTTPS 使用 wss://,然後執行 docker compose up -d。
步驟 3:不要直接暴露服務。在前方配置 TLS 與防火牆
這是多數快速安裝流程停止的地方,也是多數事件開始的地方。Dify 自有的 nginx 會在 port 80 上以明文監聽所有介面,並且也會發布 port 443。您不應讓管理員登入資訊與模型金鑰透過純 HTTP 傳輸,也不應讓外部網路直接連線到內部服務。
使用預設拒絕的防火牆鎖定伺服器,只允許 SSH 與 Web 流量:
sudo ufw default deny incoming
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable請注意,只涵蓋 IPv4 的防火牆可能會讓相同的連接埠在 IPv6 上保持開放,形成許多自架服務管理者都會遇到的 IPv6 防火牆缺口。請確認兩種 IP 協定堆疊都受到過濾。此外,Docker 發布的連接埠由 Docker 自己的防火牆規則處理,而不是由 ufw 處理;預設堆疊也會在所有介面上發布 plugin daemon 的除錯連接埠 5003。請將 EXPOSE_PLUGIN_DEBUGGING_PORT=5003 保留在 .env 中:它也會提供給 PLUGIN_REMOTE_INSTALL_PORT,而該設定要求整數,因此 127.0.0.1:5003 會導致 API 無法啟動。請改在 docker-compose.override.yaml 中將其繫結至 loopback。使用 Docker Compose 2.24.4 或更新版本時,請在 docker 目錄中建立此檔案:
services:
plugin_daemon:
ports: !override
- "127.0.0.1:5003:5003"!override 標籤會取代原本的公開映射;一般的 ports 清單則會保留原本的映射。執行 docker compose up -d 套用變更。
至於 TLS,最乾淨的做法是將 Dify 的 Web port 繫結至 loopback,並在前方執行搭配 Let's Encrypt 憑證的反向代理,讓公開網際網路上唯一可見的服務是使用 HTTPS 通訊的代理。Dify 的 .env 可讓您變更公開的連接埠;請將其設定為繫結至 127.0.0.1,再將代理指向該連接埠。EXPOSE_NGINX_SSL_PORT 也要採用相同設定,因為 Dify 的 nginx 預設會佔用主機的 port 443,而您的代理需要使用該連接埠。在 VPS 上安全執行 AI agent 中的 agent 強化概念同樣適用:讓各個元件留在 loopback,只公開必要的服務,並由單一強化過的入口處理 TLS。若某項工具的介面只有您自己需要,且完全不需要憑證,則可略過代理,改用 SSH tunnel 存取;自架 open-kritt 安全掃描器 就是將其儀表板繫結至 loopback,再轉送至您的筆電,而不是公開發布。如果整個團隊都需要使用 Dify,但不希望開放給公開網際網路,overlay network 可將這個做法擴展到單一筆電之外:將伺服器的私有子網路發布至您的 tailnet 可讓每台核准的裝置透過私有位址連線至 builder,同時防火牆仍只對 SSH 開放。若您是透過 coding agent 而非手動管理此伺服器,請在交付權限前先決定它可以在無人監督下執行多少操作,因為您留給 Claude Code 的權限模式會決定它在重寫 .env 或重新啟動堆疊前,是否會先停下來詢問。如果最後讓一個工作階段持續查看容器日誌,另一個工作階段編輯代理設定,這兩個工作階段可以在同一台伺服器上互傳文字,每次重新啟動堆疊時就不必在終端機之間反覆複製輸出。
步驟 4:持續套用修補程式
Dify 更新快速,且更新內容包含安全性修正。由於您複製的是發行版本標籤,因此更新時應切換至下一個標籤,而不是拉取分支。先備份資料庫,再從 docker 目錄執行:
docker compose stop -t -1
git fetch --tags
git checkout NEW_VERSION
docker compose pull
docker compose up -d資料庫遷移會在啟動時自動執行,其中部分遷移無法復原,因此必須先備份。每次升級前都應閱讀發行說明,不只是在重大版本升級時閱讀:Dify 表示,不同版本之間的升級步驟可能不同。例如,1.17.1 的發行說明(2026 年 9 月)提醒,使用內建 Weaviate 且已有資料的人員,不應直接跳至該版本,而應先讓 Weaviate 逐一升級經過每個次要版本。Dify 也會在不同版本之間變更設定結構,因此切換至新標籤後,請比較 .env.example 與您的 .env,並將每個本機服務的 .env 檔案與內建範本比較,因為未設定的新變數可能會導致容器無法啟動。升級時請維持相同的 Compose 專案名稱與自訂 Compose 檔案,讓具名 volume 繼續附加至原有服務。
步驟 5:備份無法重新產生的資料
備份存放應用程式、使用者與設定的 Postgres 資料庫,以及 volumes/app/storage 中的已上傳文件和 volumes/weaviate 中的向量索引。這些是位於 docker 目錄下的獨立 bind mount 目錄,不是共用的單一 volume。也要保留 .env、envs/ 下的本機服務 .env 檔案、自訂 Compose 檔案、外掛程式儲存資料,以及 agent sandbox 的 home 和 workspace 所使用的 named volume。依排程建立快照,並將快照複製到伺服器之外。複製資料庫檔案前,先使用 docker compose stop -t -1 停止整個 stack;若要在服務運作期間備份,則使用資料庫本身提供的 dump 工具。這些備份包含 secrets 和已上傳文件,因此在離開伺服器前必須加密,理由與原本安全性完善的密碼伺服器,最後卻發現 Vaultwarden 備份成為弱點相同。model API key 可以重新簽發,但花費一週建立的應用程式無法重新建立。任何必須在執行它的機器故障後仍保留狀態的 agent,都適用相同原則:讓 KiroCrew 以 always-on container 持續執行,就是建立快照保存原本會在下次重新開機時消失的記憶與排程。
如果希望在這裡建立的 agents 能存取自己的資料集以外的內容並搜尋即時網頁,將它們指向自架的 SearXNG instance,就能讓查詢流量留在你控制的硬體上。不過,啟用前應先了解因此暴露的 prompt injection 攻擊面。若要使用更具自主性、能執行程式碼的 agent,請參閱自架 Agent Zero;而在 VPS 上建立自己的 AI agent則涵蓋所有這些 agent 所需的基礎。
FAQ
自行代管 Dify 的系統需求為何?
Dify 文件列出的最低需求為 4 GiB RAM、2 個 CPU 核心,以及 Docker Compose 2.35.0 或更新版本。這項最低需求反映預設堆疊的規模:截至 October 2026,共有 15 個長時間執行的容器,以及 1 個只執行一次的初始化工作。如果還有其他服務共用同一台主機,請為上傳的文件、向量索引與額外記憶體預留足夠的磁碟空間。
直接在 port 80 對外公開 Dify 安全嗎?
不安全。Dify 隨附的 Web server 會監聽純 HTTP,且會處理管理員登入與模型 API key。請在前方設定使用 Let’s Encrypt 憑證的反向代理,將 Dify 自身的 port 綁定至 loopback,並只讓 HTTPS proxy 面向網際網路。另請搭配涵蓋 IPv4 與 IPv6 的預設拒絕防火牆規則。
如何更新自行代管的 Dify?
先備份資料庫,然後從 docker 目錄執行 docker compose stop -t -1、git fetch --tags,指定新的 release tag git checkout,再執行 docker compose pull 與 docker compose up -d。請先閱讀 release notes,因為不同版本的升級步驟可能不同,migration 可能無法復原,而且 Dify 有時會新增 .env 變數;缺少該變數可能導致容器無法啟動。
安裝 Dify 後,第一件事應該做什麼?
造訪 /install,並立即建立管理員帳號。在該帳號建立前,任何能連到該頁面的人都可以搶先註冊。請在容器狀態正常後立即完成設定,並在將防火牆對外開放前完成。