1. 项目缘起：为什么要在OpenCloudOS 9上折腾Dify？

最近在搞一个内部AI应用平台，选型时盯上了Dify。这玩意儿确实不错，一个开源的可视化LLM应用开发平台，能快速把大模型能力包装成API、智能体或者知识库应用。团队决定用容器化部署，一来环境干净，二来也方便后续的CI/CD和扩缩容。

官方的Docker镜像自然是首选，但一上手就发现了个不大不小的问题：官方镜像是基于 ubuntu:22.04 构建的。而我们生产环境的底层操作系统，清一色换成了OpenCloudOS 9——一个由国内社区主导、兼容CentOS/RHEL生态的企业级Linux发行版。直接拉取官方镜像跑，不是不行，但总感觉有点“隔靴搔痒”。一方面，基础镜像层多了一层Ubuntu，增加了镜像体积和潜在的安全维护点；另一方面，我们内部有严格的软件供应链安全要求，希望基础镜像能使用经过我们内部安全扫描和加固的OpenCloudOS 9镜像。

于是，一个很自然的想法就冒出来了：能不能基于OpenCloudOS 9，从头构建一个Dify的容器镜像？这样既能保证基础环境与我们生产环境高度一致，又能对构建全过程有更深的把控。说干就干，目标锁定当时的最新稳定版v1.13.3。这个过程，远不是把Dockerfile里的 FROM ubuntu:22.04 改成 FROM opencloudos:9 那么简单，里面涉及到依赖库的差异、Python环境的配置、前端构建的适配等一系列坑。这篇内容，就是这次“踩坑”和“填坑”的完整记录，希望能给同样在信创或特定OS环境下部署Dify的朋友们铺条路。

2. 环境准备与核心依赖的“水土不服”

构建的第一步，自然是准备构建环境。我们在一台开发服务器上操作，其本身也运行着OpenCloudOS 9，这保证了构建环境与目标环境的一致性。

2.1 构建机基础环境配置

首先，确保构建机上的Docker服务是正常运行的。OpenCloudOS 9的软件源里已经包含了Docker，安装非常方便：

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

接下来，我们需要获取Dify v1.13.3的源代码。这里有个小技巧，直接从GitHub拉取时，最好指定 --depth=1 只克隆最新提交，可以大大加快速度，特别是对于Dify这种前后端分离、提交历史较长的项目。

git clone https://github.com/langgenius/dify.git --depth=1 -b v1.13.3
cd dify

进入代码目录后，别急着构建，先花几分钟看看它的Dockerfile结构。Dify采用了多阶段构建，主要分为后端（API）和前端（Web）两部分。我们的适配工作，也主要围绕这两部分展开。

2.2 OpenCloudOS 9与Ubuntu的核心差异点

这才是问题的核心。Ubuntu基于Debian，使用 apt 包管理器；OpenCloudOS 9继承自RHEL/CentOS，使用 dnf （或 yum ）。两者提供的软件包名称、版本甚至默认配置都有差异。直接照搬官方Dockerfile里的 apt-get install 命令，在OpenCloudOS下肯定会失败。

我们需要逐一识别并转换这些依赖。通过分析官方Dockerfile，我梳理出以下几类关键依赖：

1. 系统工具与编译环境 ：如 curl , wget , git , build-essential （Ubuntu下的元包，包含gcc, g++, make等）。在OpenCloudOS 9中，对应的包组是 @development tools 。
2. Python环境与数据库客户端 ：Dify后端是Python（Django）写的，需要Python 3.10+、 pip 以及 postgresql-client （用于连接数据库）。OpenCloudOS 9默认的Python3版本是3.9，我们需要通过 dnf 安装更新的版本，或者使用其他方式（如 pyenv ，但在容器构建中更推荐用系统包管理器安装指定版本）。
3. Node.js环境 ：Dify前端基于Node.js构建。官方Dockerfile使用了 nodesource 的源来安装Node.js 20。在OpenCloudOS 9上，我们需要采用兼容的方式安装相同的主要版本。
4. 特定库文件 ：一些底层库，如用于处理图片的 libvips ，在Ubuntu和OpenCloudOS中的包名可能不同。

我的策略是，先根据官方Dockerfile列出所有 apt-get install 的包，然后通过查询OpenCloudOS 9的软件源（ dnf search 或 dnf provides ）找到功能等价或兼容的包。这是一个需要耐心和一点经验的过程，有时候一个Ubuntu包可能对应OpenCloudOS里的多个包，或者需要启用额外的软件源（如EPEL）。

注意 ：在寻找替代包时，优先选择功能一致、版本相近的官方包。如果找不到完全对应的，需要评估该依赖对于Dify运行是否必需。例如， build-essential 是一个元包，安装它是为了获得编译Python C扩展的能力。在OpenCloudOS中安装 @development tools 组可以达到同样目的。

3. 后端镜像构建：从Python版本到依赖编译

后端的Dockerfile通常位于 docker/Dockerfile 或项目根目录。我们的任务是创建一个新的Dockerfile，比如 Dockerfile.oc9 ，基于 opencloudos:9 进行构建。

3.1 基础镜像选择与系统包安装

第一行，将基础镜像替换为OpenCloudOS 9的最小化镜像：

FROM opencloudos:9 AS backend-base

然后，设置国内镜像源以加速下载（根据你的网络环境可选，但强烈建议）。接着，安装系统级依赖。这是转换的关键一步。以下是我转换后的 dnf install 命令示例：

RUN dnf install -y epel-release && \
    dnf install -y python3.11 python3.11-devel python3.11-pip \
                   postgresql15 postgresql15-devel \
                   gcc gcc-c++ make git curl wget which \
                   libvips libvips-devel openssl-devel \
                   libffi-devel bzip2-devel readline-devel \
                   sqlite-devel xz-devel tk-devel uuid-devel \
                   @development-tools

逐项解释：

• epel-release : EPEL（Extra Packages for Enterprise Linux）源提供了大量额外的软件包，是RHEL/CentOS/OpenCloudOS生态的重要补充，很多软件需要从这里安装。
• python3.11 : OpenCloudOS 9默认源可能没有3.11，需要从EPEL或其他可信源（如SCLo）安装。这里假设已配置好包含Python 3.11的源。 这是第一个大坑 ，务必确认你的源里有所需的Python版本。
• postgresql15 : Dify支持PostgreSQL，我们需要客户端库（ -devel ）来编译 psycopg2 这个Python PostgreSQL适配器。
• gcc, make 等：代替Ubuntu的 build-essential 。
• libvips : 图像处理库，在OpenCloudOS中包名就是 libvips ，而Ubuntu里可能是 libvips-dev 或 libvips-tools 。
• 其他 *-devel 包：都是编译Python依赖（如 cryptography , pillow 等）时所必须的头文件和静态库。

3.2 Python虚拟环境与项目依赖安装

在系统Python 3.11安装好后，接下来的步骤与官方Dockerfile类似，但需要注意路径差异。

WORKDIR /app/backend
COPY ./backend/requirements.txt .
COPY ./backend/requirements/*.txt ./requirements/

# 创建虚拟环境，明确使用python3.11
RUN python3.11 -m venv /app/venv
ENV PATH="/app/venv/bin:$PATH"

# 升级pip并安装依赖，使用国内PyPI镜像加速
RUN pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple && \
    pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

这里有一个 关键细节 ：官方Dockerfile可能直接使用 python 命令，但在我们的环境里，必须显式使用 python3.11 来确保版本正确。虚拟环境路径（ /app/venv ）也需要在后续的 ENV 指令中正确设置。

3.3 拷贝代码与构建优化

之后便是拷贝后端代码，运行数据迁移、收集静态文件等标准Django部署步骤。这部分与OS关系不大，照搬即可，但要注意文件路径。

COPY ./backend .
# 假设你的配置文件通过环境变量或外部挂载注入，这里不拷贝本地配置文件
# COPY ./backend/.env.example .env

RUN python manage.py collectstatic --noinput

在构建这个阶段时，我遇到了一个关于 psycopg2 编译的典型问题。虽然安装了 postgresql15-devel ，但构建时仍然报错找不到 pg_config 。原因是 pg_config 可执行文件可能不在 PATH 中。解决方案是在 pip install 之前，确保PostgreSQL的bin目录在PATH里，或者通过环境变量 PG_CONFIG 指定其路径：

ENV PG_CONFIG=/usr/pgsql-15/bin/pg_config
RUN pip install -r requirements.txt ...

这个路径需要根据你实际安装的PostgreSQL版本进行调整。通过 dnf list installed | grep postgresql 可以找到确切的路径。

4. 前端镜像构建：Node.js版本与构建工具链

前端构建的挑战主要在于Node.js运行环境和构建工具链（如pnpm、vite）在OpenCloudOS下的兼容性。

4.1 Node.js安装策略选择

官方Dockerfile通常使用 nodesource 的脚本安装Node.js。在OpenCloudOS上，我们有几种选择：

1. 使用dnf安装 ：如果OpenCloudOS或EPEL源提供了Node.js 20，那最简单。但企业版Linux的软件源通常版本较旧。
2. 使用NodeSource的RPM源 ：NodeSource也提供针对RHEL/CentOS的RPM仓库，理论上兼容OpenCloudOS。这是最接近官方方案的选择。
3. 使用二进制包 ：从Node.js官网下载Linux二进制包（ tar.xz ）并解压到指定目录。

为了最大程度保证一致性，我选择了第二种方案，即添加NodeSource仓库。在Dockerfile中这样操作：

FROM opencloudos:9 AS frontend-base

# 安装curl用于获取NodeSource脚本
RUN dnf install -y curl
# 添加NodeSource 20.x仓库并安装Node.js
RUN curl -fsSL https://rpm.nodesource.com/setup_20.x | bash - && \
    dnf install -y nodejs

踩坑记录 ：直接运行NodeSource的脚本时，可能会因为系统证书问题导致 curl 下载失败。如果遇到，可以先尝试更新CA证书包（ dnf install -y ca-certificates ），或者在一个网络通畅的环境下测试。另一种更可控的方式是，先将Node.js的二进制包下载到构建上下文，然后在Dockerfile中使用 COPY 和 tar 解压，这样可以避免构建时对外部网络的依赖。

4.2 前端依赖安装与构建

安装好Node.js后，剩下的步骤就标准化了。首先安装pnpm（Dify前端使用的包管理器）：

RUN npm install -g pnpm
WORKDIR /app/web
COPY ./web/package.json ./web/pnpm-lock.yaml ./

这里有个 性能优化点 ：在拷贝源代码之前先拷贝 package.json 和 pnpm-lock.yaml ，然后安装依赖。这样可以利用Docker的构建缓存层。只要依赖文件没变，这一层就不会重建，能极大加速后续的构建尝试。

RUN pnpm install --frozen-lockfile
COPY ./web .
# 构建生产环境产物，注意环境变量
RUN VITE_APP_API_BASE_URL=/api VITE_APP_PUBLIC_API_BASE_URL=/api pnpm run build

注意构建命令中的环境变量 VITE_APP_API_BASE_URL 等。这些需要与你的后端API部署路径保持一致。在官方Dockerfile中，这些通常通过 ARG 或 ENV 传入，这里我写死了示例值，实际构建时你应该根据你的部署方案调整，或者通过多阶段构建的 --build-arg 传递。

5. 最终镜像合成与配置注入

经过多阶段构建，我们得到了精简的后端运行镜像和前端静态文件。最后一步是将它们合成一个用于生产环境运行的镜像。

5.1 创建最终运行镜像

我们基于一个更小的OpenCloudOS 9运行时镜像（如 opencloudos:9-minimal ）来创建最终镜像。

FROM opencloudos:9-minimal AS runtime

# 安装运行时依赖，比构建阶段少很多
RUN dnf install -y python3.11 libvips postgresql15-libs && \
    dnf clean all && rm -rf /var/cache/dnf/*

# 从backend阶段拷贝虚拟环境和收集的静态文件
COPY --from=backend-base /app/venv /app/venv
COPY --from=backend-base /app/backend/staticfiles /app/backend/staticfiles
# 从frontend阶段拷贝构建好的前端静态文件
COPY --from=frontend-base /app/web/dist /app/web/dist

# 设置环境变量
ENV PATH="/app/venv/bin:$PATH"
ENV PYTHONUNBUFFERED=1
WORKDIR /app/backend

# 拷贝后端源代码（不含虚拟环境和已收集的staticfiles）
COPY ./backend .
# 拷贝启动脚本
COPY ./docker/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

EXPOSE 5001
ENTRYPOINT ["/entrypoint.sh"]

这个最终镜像只包含了Python解释器、必要的系统库（如 libvips 、 postgresql15-libs ）、虚拟环境中的Python包、以及前后端的静态文件与源代码。非常精简。

5.2 关键配置：entrypoint.sh与环境变量

entrypoint.sh 启动脚本是容器灵活性的关键。它需要在容器启动时执行数据库迁移、创建超级用户（如果需要）、然后启动应用服务器（如Gunicorn）。一个简化的示例：

#!/bin/bash
set -e

# 等待数据库就绪（如果需要）
# wait-for-it.sh db:5432 --timeout=30

# 执行数据库迁移
python manage.py migrate --noinput

# 收集静态文件（如果在上游阶段没做，或者需要覆盖）
# python manage.py collectstatic --noinput

# 启动Gunicorn
exec gunicorn --bind 0.0.0.0:5001 --workers 4 --threads 8 --timeout 120 wsgi:application

重要经验 ：数据库连接信息（主机、端口、用户名、密码、数据库名）、Secret Key等敏感配置， 绝对不要 硬编码在Dockerfile或代码里。必须通过环境变量传入，并在 settings.py 或 .env 文件中读取。在Docker中，可以通过 -e 参数或Docker Compose文件设置。

6. 构建、测试与优化实践

所有Dockerfile准备就绪后，就可以开始构建了。

6.1 执行构建命令

在项目根目录，执行构建命令。为了区分，我们给新镜像打上标签。

# 构建后端镜像
docker build -f Dockerfile.backend.oc9 -t dify-backend:oc9-v1.13.3 .
# 构建前端镜像（如果分开构建）
# docker build -f Dockerfile.frontend.oc9 -t dify-frontend:oc9-v1.13.3 .
# 构建最终合成镜像
docker build -f Dockerfile.runtime.oc9 -t dify:oc9-v1.13.3 .

构建过程可能会比较耗时，特别是第一次安装系统包和npm依赖的时候。利用好Docker缓存是关键。

6.2 运行测试与排错

构建成功后，不要急于上生产。先在本机或测试环境运行起来。

# 假设使用docker-compose测试
docker-compose -f docker-compose.oc9.yaml up -d

启动后，重点检查以下几点：

1. 容器日志 ： docker logs -f <container_id> 查看是否有启动错误，特别是数据库连接、Redis连接、环境变量缺失等问题。
2. 服务健康检查 ：访问 http://localhost:5001/health 或 http://localhost:5001/api ，看后端API是否正常响应。
3. 前端静态文件 ：访问 http://localhost:5001 ，看前端页面是否正常加载，资源（JS、CSS、图片）是否都能正确获取。
4. 核心功能测试 ：尝试创建一个应用，调用API，测试知识库上传等核心流程。

我在测试时遇到了一个前端路由问题。页面直接访问 / 正常，但刷新子页面（如 /app/xxx ）会返回404。这是因为前端是单页应用（SPA），路由由前端控制，但刷新时请求会直接发到后端，而后端Django没有配置对应的路由。解决方案是在Django的URL配置中，添加一个兜底路由，将前端路由的请求返回给 index.html 。或者，更常见的做法是在Nginx等Web服务器层做 try_files 处理。在纯容器部署时，需要确保你的静态文件服务配置正确。

6.3 镜像优化与尺寸控制

构建完成后，用 docker images 查看镜像大小。与官方Ubuntu镜像对比，我们的OpenCloudOS版本可能会因为基础镜像和安装包的不同而有差异。优化方向：

• 使用多阶段构建 ：我们已经做了，确保最终镜像只包含运行时必要内容。
• 清理缓存 ：在 dnf install 和 pip install 、 pnpm install 后，及时运行清理命令（如 dnf clean all , pip cache purge , pnpm store prune ）。
• 选择更小的基础镜像 ： opencloudos:9-minimal 比 opencloudos:9 体积小很多。
• 合并RUN指令 ：将多个 RUN 指令用 && 连接成一个，减少镜像层数。

经过优化，我们最终得到的 dify:oc9-v1.13.3 镜像，在包含了所有必要依赖后，体积控制在了1.2GB左右，比官方镜像略大一点（主要源于基础镜像和部分库的差异），但在可接受范围内。

7. 总结与延伸思考

这次将Dify v1.13.3适配到OpenCloudOS 9并构建容器镜像的过程，是一次典型的跨Linux发行版软件部署实践。核心难点不在于Dify本身，而在于两个操作系统生态在包管理、默认软件版本和底层库上的差异。

整个过程下来，最重要的经验有两条：

1. 系统性依赖转换 ：不要看到一个 apt 包就简单替换成 dnf 包名。要理解这个包是做什么的（是运行时库 libxxx ，还是开发头文件 libxxx-devel ，或者是工具集 xxx-tools ），然后在目标系统中寻找功能对等的包。善用 dnf provides <file> 命令，它可以查找哪个包提供了某个特定的文件（比如 pg_config ）。
2. 构建环境与运行环境分离 ：多阶段构建是容器镜像优化的利器。在OpenCloudOS环境下同样适用。把需要编译工具链的步骤放在庞大的 backend-base 或 frontend-base 阶段，最终只把虚拟环境、node_modules和构建产物拷贝到干净的 runtime 镜像中，能有效控制最终镜像体积。

对于想在类似环境（如Anolis OS、统信UOS服务器版、麒麟OS等）部署Dify的团队，这份适配思路是通用的。关键在于吃透软件本身的依赖树，并熟悉目标操作系统的软件生态。当然，最“省事”的办法还是直接使用官方镜像。但当你需要对底层有更强控制力，或处于特定的信创环境时，这份“折腾”就是必要且有价值的。它带来的不仅仅是一个可运行的镜像，更是对应用依赖的深刻理解，这在后续的故障排查、性能调优和安全加固中，都会成为你的优势。