群辉NAS部署Dify全指南：从离线安装包到容器化避坑

简介：面向群辉NAS用户、开发者以及计划自托管AI应用的技术人员，该安装包用于在群辉设备上完成Dify平台的部署。它整合了Dify运行所需的全部核心文件，避免了从零配置的繁琐，尤其适合需要在内网环境中快速搭建智能应用服务、实现数据本地化管理的场景。压缩包共2000个文件，大小约20.2MB，其中Python脚本占据多数（1369个），承担后端处理逻辑；另有367个JSON配置、107个CSS与67个JS构成前端界面，22个YAML用于容器编排，12个Shell脚本辅助自动化安装，整体结构完整且层次分明。已有1368人学习下载，包内目录划分清楚，前端与后端模块互相独立，配置文件可直接修改端口、服务参数，部署时可按需调整。对于想了解Dify在群辉环境中的安装结构、参与二次开发或进行离线部署的用户，这份资源能提供直观的参考和可复用的配置基础。

1. 群辉部署 Dify 安装包：NAS 上跑 LLM 应用平台，先想清楚这几件事

群辉部署 Dify 安装包，最容易被绕进去的思路是去套件中心找现成的套件——DSM 官方仓库里根本没有这个东西。网上流传的群辉部署 Dify 安装包，拆开看就是 docker-compose 编排文件、一摞镜像 tar 包和一份环境变量模板，本质是给 Container Manager 准备的离线部署包。我先后在 DS920+ 和一台黑群辉上各部署了一遍，结论一致：内存 8G 起步，能用 Container Manager（DSM 7.2+）就能跑。这套东西落地后，NAS 上相当于多了一个可视化 LLM 应用平台：接 DeepSeek、Ollama 本地模型，做知识库 RAG、工作流编排、Agent 应用都行。适合手里有群辉、不想额外租服务器跑 Dify 的开发者，尤其是内网环境和中小团队内部工具。

2. 安装包与镜像准备：把 Container Manager 环境梳理到能直接导入

2.1 前置检查：DSM 版本、架构和内存边界

群辉跑容器，第一道门槛是 Docker 环境。DSM 7.2 及以上自带 Container Manager，可以直接拉镜像、管理 compose 项目；DSM 7.0/7.1 是旧版 Docker 套件，功能阉割不少，compose 支持需要额外开启。安装包方案里，镜像导入用 docker load，跟套件版本没有硬性冲突，但如果你打算后续用 compose 反复更新服务，我建议直接上 DSM 7.2——旧版套件在编排项目时经常要手动改配置文件，升级路径也绕。硬件方面，Dify 全家桶包含 API 服务、Worker、Web、PostgreSQL、Redis、向量数据库加 Nginx，内存占用最少 6G，实际跑起来 8G 才踏实。群辉的 x86 机型都能用官方镜像，ARM 机型会碰到镜像架构不匹配的问题，下载安装包先确认 tag 是 amd64 还是 arm64。磁盘空间留 30G 保底，镜像 tar 包、数据目录、日志加在一起，消耗速度比预想快。

导入前，SSH 进群辉看一眼基本信息：

# 查看 CPU 架构 uname -m # 查看内存总量 free -h # 确认 Docker 引擎版本 docker --version

逻辑说明：uname -m 输出 x86_64 就用 x86 镜像，输出 aarch64 就找 arm64 的包；free -h 看总内存，只有 4G 的话 Dify 会跟群辉自己的文件服务抢资源，知识库同步时 Worker 经常被系统杀掉。docker --version 顺手确认当前 Container Manager 内置引擎版本，太低就先去套件中心升级 DSM。

参数说明：DSM 7.2 的 Container Manager 内置 compose v2，不需要额外安装 docker-compose 二进制；旧版套件建议在套件中心把 Docker 套件更新到最新再继续。另外，群辉 SSH 默认没开，需要在“控制面板 → 终端机和 SNMP”里启用，这一步经常被人忘掉。

2.2 安装包的组织结构：镜像 tar 与 compose 文件

所谓安装包，解压后通常是这样的目录结构：

dify-offline/ ├── docker-compose.yml ├── .env ├── images/ │ ├── dify-nginx.tar │ ├── dify-api.tar │ ├── dify-web.tar │ ├── dify-worker.tar │ ├── postgres.tar │ ├── redis.tar │ └── weaviate.tar └── README.md

images 目录是核心。在能联网的机器上拉好镜像再导出，到群辉上导入，这一步是离线部署的关键。把安装包放到群辉共享目录后，SSH 进去批量导入：

cd /volume1/docker/dify-offline/images for f in *.tar; do echo "==> $f" docker load -i "$f" done docker images | grep -E 'dify|postgres|redis|weaviate'

逻辑说明：docker load 是把 tar 包里的镜像还原成本地镜像层，不依赖外部网络。循环导入的好处是单个文件失败不影响其他镜像，echo 打出来的文件名能直接定位坏掉的 tar。docker images 的输出要和 compose 文件里的 image 字段对照，tag 对不上时，docker compose up 会尝试从远程拉镜像，离线环境就卡死在拉取阶段。

参数说明：路径按实际位置改，/volume1/docker 是我惯用的容器目录，你放在 /volume2 也一样。有的安装包会把镜像打成带 registry 前缀的完整名字，比如 docker.io/langgenius/dify-api:1.10.0，导入后 compose 里的 image 字段必须一字不差地匹配，否则还是会走远程拉取。

2.3 目录映射与权限：把数据落在 RAID 上

镜像只是程序本体，数据都在容器卷里。Dify 的关键数据包括 PostgreSQL 数据库、Redis 缓存、Weaviate/Qdrant 向量库，以及上传文件的本地存储。在群辉上部署，最好把这些卷显式映射到磁盘阵列上的共享目录，而不是留在容器可写层——否则重装或迁移时，数据跟着镜像一起消失。我在 /volume1/docker/dify 下按服务分目录，规划如下：

创建目录后，权限先预置好，避免容器启动时写不进数据目录：

mkdir -p /volume1/docker/dify/{storage,postgres,redis,weaviate} chown -R 999:999 /volume1/docker/dify/postgres ls -ld /volume1/docker/dify/*

逻辑说明：PostgreSQL 官方镜像默认以 postgres 用户运行，uid 999 是这个用户最常见的值。把数据目录属主预授权到 999:999，容器首次启动就不会因为写权限失败退出。Redis 和 Weaviate 对属主相对宽容，如果启动时报 permission denied，再按同样思路调整。

参数说明：chown 的 999:999 不是写死的。不同镜像版本 uid 可能不同，更稳的做法是先启动一次容器看报错提示的 uid，再停下来 chown。我第一次部署就是因为套用网上教程写死 999，换了个镜像版本直接翻车。

3. 用 docker compose 编排 Dify：服务拆解与核心参数调优

3.1 compose 文件里的服务拆解：谁在跑什么

从安装包解压出来的 docker-compose.yml 一般包含 8 个左右服务，先别急着 up -d，把每个服务的作用摸清楚，后面排查问题才能定位到具体容器。核心服务关系如下表：

api 和 worker 跑的是同一份镜像，只是启动命令不同。理解这个结构对排查很关键：知识库文档处理进度卡住，问题多半在 worker；对话报错，多半在 api 和模型供应商之间。

端口映射是群辉部署最需要改的地方。DSM 的 80 和 443 端口默认被系统占用，nginx 服务不能直接映射到这两个端口，我习惯在前面加个 2：

nginx: image: nginx:latest ports: - "2080:80" - "2443:443"

逻辑说明：容器内 nginx 仍然监听 80/443，宿主机映射到 2080/2443，群辉自己的 Web 服务不受影响。访问 Dify 控制台时用 http://群辉IP:2080，后面配置 HTTPS 反向代里时再由群辉的 443 转发进来。

参数说明：如果你要接群辉自带的反向代里，这里的 2443 可以不映射，直接在群辉反向代里里把 https 请求转发到 http://127.0.0.1:2080。但为了迁移时少依赖群辉配置，我倾向把两个端口都映射出来。

3.2 环境变量：向量库、存储和密钥的关系

compose 文件里大量环境变量是 .env 文件引入的，部署前至少要改这几个：SECRET_KEY、VECTOR_STORE、DB_USERNAME/DB_PASSWORD、STORAGE_TYPE。SECRET_KEY 用于加密会话和 API 密钥，不填或者用默认值，生产环境等于裸奔；VECTOR_STORE 决定知识库的向量索引存在哪，weaviate 和 qdrant 是两个常见选项，安装包里通常预置了 weaviate 服务。

我一般这样改 .env：

# 生成一个足够长的随机密钥 openssl rand -hex 32 # 写入 .env SECRET_KEY=<上面生成的密钥> VECTOR_STORE=weaviate STORAGE_TYPE=local # 注意 STORAGE_LOCAL_PATH 要和卷映射一致

逻辑说明：openssl rand -hex 32 能生成 64 位十六进制密钥，比手敲可靠。VECTOR_STORE 改了之后，对应服务的镜像和环境变量也要匹配，比如选 weaviate 就保留 weaviate 服务，选 qdrant 就把 weaviate 服务注释掉。向量库切换在后续使用中很麻烦，因为向量数据不兼容，选型要在部署初期定好。

参数说明：STORAGE_TYPE 保持 local 的话，文件上传和导出产物存在 api 容器 /app/api/storage 目录，对应第 2 章映射的 /volume1/docker/dify/storage。如果改成 s3，还需要填 S3 相关的 bucket 配置，群辉本地场景不推荐，除非你外接了 MinIO。还有数据库账号：镜像内置的 postgres 服务会按 POSTGRES_USER、POSTGRES_PASSWORD 初始化，compose 里 db 服务和 api 服务的 DB_USERNAME/DB_PASSWORD 要一致，否则 api 容器连不上数据库，启动日志会刷 connection refused。

3.3 数据持久化与备份策略：哪些目录不能丢

Dify 的数据分布在多个地方，备份时最容易漏掉的是本地存储目录。只要涉及文件上传、知识库自定义分段、导出对话记录，这些文件就落在 storage 目录里，数据库里只存元数据和文件路径索引。只备份数据库，迁移过去之后知识库列表还在，点进文档却提示文件缺失。所以我做群辉备份时，直接用 Hyper Backup 把 /volume1/docker/dify 整个目录纳入备份任务，同时保留一个手动导出数据库的快速通道：

# 在群辉上导出 postgres 数据到当前目录 docker exec -t dify-db pg_dump -U postgres dify > dify-db-backup-$(date +%Y%m%d).sql # 导出 redis 数据（RDB 文件） docker run --rm --volumes-from dify-redis -v /volume1/docker/dify/backup:/backup alpine tar czf /backup/redis-data.tar.gz /data

逻辑说明：pg_dump 是逻辑备份，能在 PostgreSQL 版本升级后恢复，比直接拷贝数据目录更稳妥；redis 备份则是把 /data 目录整体打包，因为 Dify 用它缓存会话和任务队列状态，丢失后最坏的影响是正在执行的任务中断，会话状态重建。

参数说明：pg_dump 需要数据库名，Dify 的库名默认是 dify，这个值在 .env 的 DB_DATABASE 里可以改，备份时记得对应。tar 打包 redis 数据时我用一个临时 alpine 容器加 --volumes-from，避免直接在宿主机操作容器卷目录，这个习惯在群辉上尤其有用，因为群辉的目录权限对 root 之外的登录用户不友好。

4. 接入本地模型与 HTTPS：Ollama、DeepSeek 到反向代里的配置路径

4.1 Ollama 接入：把模型跑在群辉上还是独立机器上

Dify 装好只是骨架，真正要跑通问答和 RAG，得把一个可用的模型供应商接进来。常见做法是用 Ollama 部署 DeepSeek 这类本地模型。群辉的 CPU 跑 7B 模型很吃力，推理速度只能用“能跑”来形容，所以我在实际项目中把 Ollama 装在独立 Linux 机器上，群辉只跑 Dify 应用层。

Ollama 安装后默认只监听 127.0.0.1，要让群辉里的 Dify 容器能访问，必须把监听地址改成 0.0.0.0：

# 在 Ollama 宿主机上 export OLLAMA_HOST=0.0.0.0 # 如果你用 systemd 管理 sudo systemctl edit ollama # 填入: # [Service] # Environment="OLLAMA_HOST=0.0.0.0:11434"

逻辑说明：OLLAMA_HOST 决定模型服务的对外监听地址。只改这一个变量还不行，Dify 容器访问宿主机 IP 时，Linux 防火墙要放行 11434 端口。我通常顺手用 ufw allow 11434/tcp 或 firewalld 加规则，并限定只允许群辉的内网 IP，避免整个内网都能调用模型服务。

参数说明：Ollama 侧就一个端口。Dify 控制台的模型供应商配置里选 Ollama，基 URL 填 http://<Ollama宿主机IP>:11434，模型名填你下载的模型 tag，比如 deepseek-r1:7b。模型名必须和 Ollama 里 ollama list 输出的一致，多写一个字母都会在 credentials validation 阶段报错。

4.2 反向代里与 SSL：把 API 和 Web 入口收进 HTTPS

Dify 默认走 HTTP，如果你要通过公网访问，或者要在企业 IM 工具里接入回调，HTTPS 几乎是必须的。网上搜“dify ssl错误”出现频率很高，十有八九是证书配置了但 API 地址没跟着切到 https。群辉自带的“登录门户 → 高级 → 反向代里”可以直接把某个域名转发到本机 2080 端口，证书用 Let's Encrypt 或手动导入的证书。

配完成后，Dify 控制台里有两处要同步改：一是“设置 → 模型供应商”里每个模型 API 的地址，二是“设置 → API 访问 → API 服务器 URL”。这两处如果还留着 http://群辉IP:2080，页面能打开，但应用通过 API 调用时就会报 SSL 校验失败或地址不匹配。

反向代里配置好后，用 curl 验证一下转发和证书链：

# 从公网或内网机器验证前端页面 curl -I https://dify.example.com # 验证 API 健康检查接口 curl https://dify.example.com/health

逻辑说明：curl -I 看返回的 HTTP 状态和证书有效期，/health 是 Dify API 的健康检查路径，能通就说明反向代里到 api 服务的链路是通的。如果 /health 返回 502，优先看反向代里目标端口写没写对，2080 对应 nginx 服务，nginx 再把 / 和 /api 分流到 web 和 api 容器。

参数说明：群辉反向代里支持 HTTP 和 WebSocket，Dify 的工作流画布和流式输出依赖 WebSocket，代里设置里“启用 WebSocket”必须打开，否则对话响应会一直转圈。这一步容易被忽略，我遇到过多次。

4.3 离线安装插件：把 Dify 的扩展能力装进内网

Dify 社区版 1.x 之后，工具插件和模型供应商部分改成了插件化加载，在线模式会自动去 marketplace 下载插件。但在纯内网群辉环境里，容器访问不到 marketplace，插件安装会一直卡在下载中。网上搜“dify 如何离线安装插件”的人不少，这里给一个走通过的路径：先在能联网的机器上，从 Dify 的 GitHub Releases 页面下载对应版本的插件包（.difypkg 格式），然后用 docker cp 把插件包放进 api 容器，再通过控制台的“插件管理 → 安装”选择本地文件或指定路径：

# 把插件包放进 api 容器 docker cp dify-plugin-some.difypkg dify-api:/tmp/ # 进入容器确认文件存在 docker exec -it dify-api ls -l /tmp/*.difypkg

逻辑说明：docker cp 是宿主机和容器之间传文件的通用手段，不需要挂载额外目录。插件包放进去之后，在 Dify 控制台安装时选择本地安装并填容器内路径，或者直接在插件管理里上传，取决于版本。离线安装的顺序有讲究，必须先装依赖插件再装工具插件，比如装文件处理类插件前，得先检查它依赖的 base 包是不是已经在库里。

参数说明：不同 Dify 版本的插件市场地址和插件格式有差异，0.9 和 1.x 的插件安装方式完全不同。离线安装前先在联网机器上看清插件包要求的 Dify 版本，配套版本不对，装上后控制台会一直提示插件异常。

4.4 DeepSeek 在线 API 与本地 embedding 的选型

其实 Dify 也支持直接接 DeepSeek 的在线 API，配置路径是模型供应商 → DeepSeek，填入 API Key 就能用。这块没什么群辉特有的坑，但很多人把本地部署和在线 API 混着用，一个 Dify 实例里同时挂 Ollama 的本地模型和 DeepSeek 官方 API 是可行的。每个应用的默认模型独立选择，知识库的 embedding 模型也可以和对话模型分开。离线环境下，embedding 模型建议用本地的，否则文档索引阶段会卡在网络请求上。我在内网项目里用的是本地 embedding 加在线 DeepSeek 对话模型的组合，知识库索引速度比全本地快，还省了 GPU 资源。

5. 群辉部署 Dify 避坑：credentials、unstructured 与上下文超长排查记录

5.1 credentials validation 失败：模型配置总说校验不过

现象：在“设置 → 模型供应商”里填完 DeepSeek 或 Ollama 的配置，点校验，弹出 “An error occurred during credentials validation”。原因：这个报错有八成是网络不通，两成是参数写错。Ollama 场景下，Dify 容器访问宿主机 IP，代码执行沙箱和 ssrf_proxy 会拦截默认端口以外的连接；DeepSeek 在线 API 场景下，大多是网络代理或 DNS 解析问题。解决：先从 api 容器内部验证网络链路：

docker exec -it dify-api curl -I https://api.deepseek.com docker exec -it dify-api curl -I http://<OllamaIP>:11434

逻辑说明：容器内 curl 通，说明网络没问题，问题在 Dify 侧的地址或密钥；不通，则要检查群辉 DNS、路由，或者 api 容器是否被 ssrf_proxy 拦了。ssrf_proxy 默认拦截内网 IP 的请求，如果 Ollama 和群辉在同一内网，需要在 ssrf_proxy 服务的环境变量里放行对应网段，否则 credentials validation 永远过不去。

参数说明：第二行命令的 要替换成实际内网 IP，比如 192.168.1.10。如果 curl 返回空，加个 -v 看卡在哪一步，是 DNS 解析失败还是连接超时，两者处理方向完全不同。

5.2 unstructured API URL 未配置：文档处理黑匣子

现象：知识库上传 .docx 或 PDF，任务一直失败，日志里出现 “unstructured API URL is not configured for doc file processing.”。原因：Dify 解析 Office/PDF 文档依赖 unstructured 服务或外部 API，安装包里如果没有把这个服务启用，API URL 就为空。解决：在 .env 里找到 UNSTRUCTURED_API_URL，配置为 http://unstructured:8000，前提是 compose 文件里有 unstructured 服务；没有这个服务就用外部 API 地址。配置完重启 api 和 worker 容器：

grep UNSTRUCTURED .env docker compose up -d docker compose restart api worker

逻辑说明：grep 先看当前配置是否为空，这步能快速区分是没配还是配错。重启 api 和 worker 是因为文档解析任务由 worker 执行，而 API 服务负责读取环境变量初始化客户端，两个都重启才能确保新配置生效。

参数说明：unstructured 服务如果安装包里没带，离线环境会比较被动，需要额外导入 unstructured 镜像。我建议部署前先确认安装包的 images 目录里有没有 unstructured 相关 tar，没有的话在线机器上先拉下来补进去。

5.3 SSL 错误：页面能开但回调一直失败

现象：配置 HTTPS 反向代里后，控制台能访问，但应用调用 API 报 SSL 证书错误，或者模型供应商回调失败。原因：API 服务器 URL 还写的是 http 地址，或者反向代里未启用 WebSocket。解决：把 Dify 的“API 服务器 URL”改成 https 域名，确认反向代里的 WebSocket 已启用。另外，群辉自签证书存在浏览器信任问题，控制台用自签证书访问时浏览器会拦截，API 调用同理，建议证书用 Let's Encrypt 或导入正规证书。

# 验证证书链和响应头 curl -I https://dify.example.com/health # 检查是否有 WebSocket 握手字段 curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \ https://dify.example.com/ 2>&1 | head -20

逻辑说明：第一条命令确认 HTTPS 证书链正常；第二条命令模拟 WebSocket 握手，返回 101 Switching Protocols 就说明反向代里的 WebSocket 转发是通的，返回 400 或 403 则要回群辉反向代里设置里检查 WebSocket 开关。

参数说明：自签证书在移动端 App 调用 API 时更麻烦，iOS 和 Android 对自签证书的信任策略不同，统一用正规证书能省掉大量客户端侧的兼容问题。

5.4 工作流上下文超长：对话突然断掉

现象：在 Dify 工作流里把多个知识库检索结果拼接给模型，超过模型上下文窗口，调用直接失败，报错里经常出现上下文超长相关提示。原因：检索多个知识库的 top_k 叠加后 token 数超出模型限制，或者工作流里用了上下文变量聚合但没有截断。解决：在知识库检索节点降低 top_k、限制分段长度，或在工作流里用变量聚合器之前加一层模板格式化，把输出截断到可接受的长度。参数参考如下：

逻辑说明：知识库检索结果会以纯文本拼进 context，多个 top_k 累加是超长的主因。把 top_k 调低、分段调短，是最直接的手段；变量聚合器本身不截断，只是把内容合并，所以要在聚合前就控制住来源的长度。

参数说明：不同模型的上下文窗口差异很大，DeepSeek 7B 和 GPT 类模型的限制完全不同。我习惯把模型最大上下文乘以 0.8 作为安全阈值，超过就优先压缩检索条数，而不是盲目加长输出。

5.5 数据卷权限导致容器启动失败

现象：群辉重启后，dify-db 或 weaviate 容器起不来，日志里是 permission denied 或 mkdir 失败。原因：群辉开机挂载磁盘的顺序比 Docker 晚，容器数据目录在挂载前不可用；或者目录属主不对。解决：在群辉任务计划里加一个开机任务，延迟 30 秒再执行 docker compose up -d，并确保数据目录 chown 到正确 uid。任务计划脚本如下：

sleep 30 cd /volume1/docker/dify && docker compose up -d

逻辑说明：sleep 30 是给群辉的存储挂载和 Docker 服务启动留出时间窗口。群辉的开机流程里，存储卷挂载完成时间和 Docker 服务启动时间存在竞争，容器数据目录落在尚未挂载的存储上，启动必然失败。延迟执行后，目录存在且权限正确，容器才能正常拉起。

参数说明：任务计划里要选“开机触发”，用户选 root。脚本里的路径和 compose 文件位置按实际改。如果你用的是旧版 Docker 套件，compose 命令要换成 docker-compose，注意变量名差异。

6. Dify 迁移与升级：从版本检查到数据恢复的收尾技巧

6.1 用 pg_dump 和 docker cp 导出数据

迁移最省心的路径是：镜像重新 load，数据卷用 docker cp 打包搬运。数据库用 pg_dump，而不是直接拷贝整个 postgres 目录，因为 PostgreSQL 大版本跨版本恢复时，物理文件不兼容。

# 备份数据库 docker exec dify-db pg_dump -U postgres dify > /volume1/docker/dify/backup/dify.sql # 把 api 容器里的存储目录复制到群辉目录 docker cp dify-api:/app/api/storage /volume1/docker/dify/backup/storage

逻辑说明：备份完成之后，把 backup 目录整体拷贝到新机器，先 load 镜像再启动空容器，最后恢复 sql 和 storage。顺序反了会丢数据——先启动容器再恢复，容器里已有的文件会被覆盖或忽略。恢复顺序是：导入镜像 → 创建数据目录 → 恢复 sql → 恢复 storage → 启动服务。

参数说明：新机器 .env 里的 SECRET_KEY 必须和旧机器一致，否则加密的 API 密钥和认证信息全部失效。这是迁移中最容易被忽略的一点，我吃过一次亏。

6.2 升级后的核对清单

升级 Dify 前先做一次完整备份，然后把 .env 先备份为 .env.bak。拉新镜像后 docker compose up -d，等日志里出现启动完成字样，按这个顺序验证：控制台能登录，应用列表还在；知识库文档能检索，分段没有丢；模型供应商的 credentials validation 通过；跑一个流式对话，确认 WebSocket 正常。

我在一次升级中跳过备份，直接 docker compose pull 和 up -d，结果 Postgres 版本自动升级后旧数据文件读不出来，整个知识库索引全废了。从那以后，我每次在群辉上碰 Dify 的升级或迁移，都强制把 6.1 的备份命令走一遍，再动镜像版本，改任何 .env 前先 cp 一份 .bak。这个习惯帮我避开过好几次后悔药。希望帮到你。

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