📖 on 技术分享 Public Site

RAGFlow项目配置与部署指南 😸

mr_yupengfei@foxmail.com (MrYuPengfei) — Fri, 23 Jan 2026 11:22:58 +0800

RAGFlow 项目配置与部署指南

作者：Manus AI 日期：2026年1月22日

摘要

RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在通过融合前沿的 RAG 技术与 Agent 能力，为大型语言模型提供卓越的上下文层 [1]。基于您提供的文件列表，该项目采用 Docker Compose 进行部署，以简化环境依赖（如 MySQL、MinIO、Redis 等）的管理。本指南将详细分析项目文件结构，并提供配置和启动 RAGFlow 服务的具体步骤。

1. 核心文件结构分析

理解项目文件结构是成功配置的第一步。以下表格总结了您提供的文件列表中，对配置和部署至关重要的文件和目录的功能：

文件/目录	功能描述	关键配置内容
`.env`	核心环境变量文件。包含 Docker 容器所需的重要环境变量，用于配置依赖服务的凭证、端口映射和镜像版本等。	`MYSQL_PASSWORD`, `MINIO_PASSWORD`, `SVR_HTTP_PORT`, `RAGFLOW_IMAGE`
`service_conf.yaml.template`	后端服务配置模板。定义 RAGFlow 核心服务的业务逻辑配置，如 LLM 供应商、日志级别等。容器启动时会基于此模板生成 `service_conf.yaml`。	LLM 配置（`factory`、`api_key`）、数据库连接信息（通过 `.env` 变量替换）
`docker-compose.yml`	默认部署编排文件。定义了 RAGFlow 服务及其所有依赖项（如 MySQL、MinIO、Redis、Elasticsearch/Infinity）的启动、网络和卷配置。	服务定义、端口映射、卷挂载
`docker-compose-CN-oc9.yml`	国内/OceanBase 优化版。可能针对国内用户优化了镜像源，或替换了默认的 MySQL 依赖为 OceanBase [2]。	依赖服务替换、镜像源配置
`nginx/` 目录	反向代理配置。包含 Nginx 配置文件，用于处理 HTTP/HTTPS 请求转发，通常默认监听 80 端口，并将请求转发给 RAGFlow 后端服务。	`nginx.conf`, `proxy.conf`, `ragflow.conf`
`entrypoint.sh`	容器启动入口脚本。负责在容器启动时执行初始化任务，例如根据 `.env` 文件替换模板变量，生成最终的 `service_conf.yaml` 文件，并启动 RAGFlow 服务。	环境初始化逻辑
`init.sql`	数据库初始化脚本。用于首次启动时创建 RAGFlow 所需的数据库和表结构。	SQL DDL/DML 语句

2. RAGFlow 配置步骤详解

RAGFlow 的配置主要集中在两个文件：.env 和 service_conf.yaml.template。

LFM2.5 1.2B Instruct在DockerOllama上的部署、训练与RAGFlow集成指南 😸

mr_yupengfei@foxmail.com (MrYuPengfei) — Fri, 23 Jan 2026 11:22:01 +0800

LFM2.5-1.2B-Instruct 模型在 Docker Ollama 上的部署、训练与 RAGFlow 集成指南

作者: Manus AI 日期: 2026年1月22日 工作语言: 简体中文

摘要

本文档旨在提供一个全面的技术指南，指导用户如何使用 Docker 和 Ollama 运行 LFM2.5-1.2B-Instruct 模型，如何利用 Unsloth 进行模型微调（训练），以及如何将该模型集成到 RAGFlow 平台中，以构建一个高效的本地检索增强生成（RAG）系统。LFM2.5-1.2B-Instruct 是 Liquid AI 推出的一款高性能、低内存占用的混合模型，非常适合在本地或边缘设备上部署 [1]。

一、使用 Docker Ollama 运行 LFM2.5-1.2B-Instruct

Ollama 是一个轻量级的框架，用于在本地运行大型语言模型（LLM）。通过 Docker 部署 Ollama 可以简化环境配置，并确保隔离性。

1. 部署 Ollama Docker 容器

首先，您需要确保系统已安装 Docker 和 NVIDIA Container Toolkit（如果需要 GPU 加速）。

使用以下命令运行 Ollama 容器，并将端口 11434 映射出来：

# 运行 Ollama 容器
# 如果需要 GPU 支持，请添加 --gpus all 参数
docker run -d \
    --name ollama \
    -p 11434:11434 \
    -v ollama:/root/.ollama \
    ollama/ollama

2. 拉取 LFM2.5-1.2B-Instruct 模型

LFM2.5-1.2B-Instruct 模型已被社区打包并上传到 Ollama 库中，通常以 lfm2.5-thinking:1.2b 或类似名称存在 [2]。

配置RagFlow 😸

mr_yupengfei@foxmail.com (MrYuPengfei) — Thu, 22 Jan 2026 14:07:36 +0800

RAGFlow 项目配置与部署指南

作者：Manus AI 日期：2026年1月22日

摘要

1. 核心文件结构分析

理解项目文件结构是成功配置的第一步。以下表格总结了您提供的文件列表中，对配置和部署至关重要的文件和目录的功能：

文件/目录	功能描述	关键配置内容
`.env`	核心环境变量文件。包含 Docker 容器所需的重要环境变量，用于配置依赖服务的凭证、端口映射和镜像版本等。	`MYSQL_PASSWORD`, `MINIO_PASSWORD`, `SVR_HTTP_PORT`, `RAGFLOW_IMAGE`
`service_conf.yaml.template`	后端服务配置模板。定义 RAGFlow 核心服务的业务逻辑配置，如 LLM 供应商、日志级别等。容器启动时会基于此模板生成 `service_conf.yaml`。	LLM 配置（`factory`、`api_key`）、数据库连接信息（通过 `.env` 变量替换）
`docker-compose.yml`	默认部署编排文件。定义了 RAGFlow 服务及其所有依赖项（如 MySQL、MinIO、Redis、Elasticsearch/Infinity）的启动、网络和卷配置。	服务定义、端口映射、卷挂载
`docker-compose-CN-oc9.yml`	国内/OceanBase 优化版。可能针对国内用户优化了镜像源，或替换了默认的 MySQL 依赖为 OceanBase [2]。	依赖服务替换、镜像源配置
`nginx/` 目录	反向代理配置。包含 Nginx 配置文件，用于处理 HTTP/HTTPS 请求转发，通常默认监听 80 端口，并将请求转发给 RAGFlow 后端服务。	`nginx.conf`, `proxy.conf`, `ragflow.conf`
`entrypoint.sh`	容器启动入口脚本。负责在容器启动时执行初始化任务，例如根据 `.env` 文件替换模板变量，生成最终的 `service_conf.yaml` 文件，并启动 RAGFlow 服务。	环境初始化逻辑
`init.sql`	数据库初始化脚本。用于首次启动时创建 RAGFlow 所需的数据库和表结构。	SQL DDL/DML 语句

2. RAGFlow 配置步骤详解

RAGFlow 的配置主要集中在两个文件：.env 和 service_conf.yaml.template。

在VMware虚拟机部署Gitlab😎

mr_yupengfei@foxmail.com (MrYuPengfei) — Wed, 21 Jan 2026 19:09:04 +0800

太棒了！恭喜您，这真是一次史诗级的故障排除，您展现了惊人的耐心和学习能力。最终找到根源——gitlab.rb 文件放错了位置——这是一个非常经典且容易被忽略的问题。

您能自己定位到这个问题，并用 cp 命令将其修正，这说明您已经完全掌握了 Docker 数据卷挂载的核心逻辑。为您喝彩！

总结：从启动失败到 HTTPS 成功，我们的排错之旅

好的，我们来全面复盘一下这次从零开始部署 GitLab 并最终成功启用 HTTPS 的全过程。这不仅是对我们工作的总结，更是一份极具价值的、可供未来参考的实践指南。

初始目标

在本地虚拟机（vm-noble）上，通过 Docker Compose 部署一个功能完整的 GitLab CE 实例，并为其配置公网可访问的 HTTPS。

第一阶段：Docker 权限与环境问题

问题 1：permission denied ... /var/run/docker.sock
- 现象：执行 docker 命令时报权限错误。
- 根源：当前用户 yupengfei 不在 docker 用户组中，无权访问 Docker 守护进程。
- 解决：通过 sudo usermod -aG docker yupengfei 将用户加入组，并重新登录使其生效。这是所有 Docker 用户都应该掌握的基础操作。
问题 2：The "GITLAB_HOME" variable is not set
- 现象：docker compose 警告环境变量未设置，导致镜像版本错误、数据卷挂载路径不正确。
- 根源：使用 sudo docker compose 时，当前用户的环境变量不会被传递给 root 环境。
- 解决：采用 docker-compose 的最佳实践——在项目根目录创建 .env 文件来定义环境变量 (GITLAB_HOME=...)。这使得配置与环境解耦，命令更简洁，行为更可预测。

第二阶段：`docker-compose.yml` 语法混淆

问题：configs 和 secrets 顶层配置块导致错误。
- 现象：docker compose up 无法解析 yml 文件。
- 根源：原始的 docker-compose.yml 混用了 Docker Compose 模式的语法和 Docker Swarm 模式的语法（configs, secrets）。
- 解决：将其完全重构为纯粹的 Docker Compose 语法。关键是将 configs 和 secrets 的功能，通过 volumes 挂载（将 gitlab.rb 和 root_password.txt 直接挂载到容器内指定路径）和 environment 注入（在环境块内用 Ruby 代码读取挂载的文件）来替代。

第三阶段：网络访问与 HTTPS 配置的曲折之路

这是最复杂、最曲折，但也最有价值的阶段。

让Hugo主题能够灵活地显示文章的封面图片 😸

mr_yupengfei@foxmail.com (MrYuPengfei) — Mon, 19 Jan 2026 17:20:08 +0800

需求背景

我们的核心需求是：让 Hugo 主题能够灵活地显示文章的封面图片，并且希望它能同时支持两种主流的图片引用方式：

页面包 (Page Bundle)：图片与 .md 文件存放在同一个目录下，路径只写文件名。
Static 目录：图片存放在全局的 static/images/ 目录下，路径写成根相对路径（如 /images/cat-hacker.png）。

问题分析

我们最初发现，主题模板默认只支持“页面包”模式。它使用了 Hugo 的 .Resources.GetMatch 函数来查找与文章捆绑的图片资源。这种方式功能强大，可以利用 Hugo 内置的图片处理能力（如裁剪、格式转换），但无法直接读取 static 目录下的文件。

解决方案：“优雅降级”的模板逻辑

为了实现“双模”支持，我们对主题的模板文件进行了修改，引入了一套“优雅降级”（Graceful Fallback）的逻辑。

核心思路如下：

优先采用最佳实践：模板首先会尝试将 Front Matter 中 images 参数提供的路径作为“页面资源”来查找。
如果成功：证明用户使用了“页面包”模式。模板会利用 Hugo 强大的图片处理 API（例如 .Fill）对图片进行自动裁剪、压缩和格式转换（如转为 WebP），以获得最佳的页面加载性能和显示效果。
如果失败：证明图片不是页面资源，模板则“降级”到第二方案。
执行回退方案：模板会判断该路径是否为一个指向 static 目录的根相对路径（即以 / 开头）。如果是，就直接使用该路径来渲染图片，但不进行任何图片处理，图片将以原始状态显示。

最终实现的代码

我们将模板中的相关部分替换为以下实现了“双模”逻辑的 Go Template 代码：

{{/* 获取 Front Matter 中定义的第一张图片路径 */}}
{{ $imagePath := index .Params.images 0 }}

{{/* 1. 优先尝试作为“页面资源”获取图片 */}}
{{ $imageResource := .Resources.GetMatch $imagePath }}

{{ if $imageResource }}
    {{/* --- 如果是页面资源，使用 Hugo 的图片处理功能 --- */}}
    {{ $image := $imageResource.Fill "600x300 Center webp" }}
    <img src="{{ $image.RelPermalink }}" ... >
{{ else }}
    {{/* --- 如果不是页面资源，则假定为 static 目录下的路径 --- */}}
    {{ if hasPrefix $imagePath "/" }}
        <img src="{{ $imagePath | absURL }}" ... >
    {{ end }}
{{ end }}

总结

通过这次修改，我们成功地让 Hugo 主题变得更加智能和健壮。它现在能够自动识别作者的图片引用方式，并尽可能地采用最优策略进行处理：

一次对WSL2“网络连接风暴”的深度诊断与修复实录 😸

mr_yupengfei@foxmail.com (MrYuPengfei) — Mon, 19 Jan 2026 16:55:15 +0800

前言

今天下午，我经历了一场堪称“完美风暴”的 WSL2 (Windows Subsystem for Linux) 故障。起初只是一个简单的 systemctl 命令报错，但随着排查的深入，问题如剥洋葱般层层展现，从上层应用一直牵扯到 Windows 的底层网络配置。最终，在经历了近乎“法医级别”的诊断后，我们成功让系统恢复了健康。

这不仅仅是一篇故障排除指南，更是一次对 WSL2 内部工作机制的深度探索。如果你也曾被 WSL2 的网络问题所困扰，那么这篇文章或许能为你提供一些思路和慰藉。

故障初现：`systemctl` 失效

一切始于一个常见的命令：

sudo systemctl enable --now ssh

得到的却是一个经典错误：

System has not been booted with systemd as init system (PID 1). Can't operate. Failed to connect to bus: Host is down

对于有经验的 WSL 用户来说，这通常意味着 systemd 没有启用。于是，我们按照官方推荐的方法，在 /etc/wsl.conf 中添加了配置：

[boot]
systemd=true

然后执行 wsl --shutdown 重启。然而，这只是噩梦的开始。

第一层迷雾：`apt` 网络中断

systemd 启用后，我们尝试运行 sudo apt update，却一头撞上了网络错误：

Temporary failure resolving 'archive.ubuntu.com'

Podman运行gitlab时的权限问题 😸

mr_yupengfei@foxmail.com (MrYuPengfei) — Sun, 18 Jan 2026 20:09:18 +0800

[gitlab] | Thank you for using GitLab Docker Image!
[gitlab] | Current version: gitlab-ce=18.8.0-ce.0
[gitlab] | 
[gitlab] | Configure GitLab for your system by editing /etc/gitlab/gitlab.rb file
[gitlab] | And restart this container to reload settings.
[gitlab] | To do it use docker exec:
[gitlab] | 
[gitlab] |   docker exec -it gitlab editor /etc/gitlab/gitlab.rb
[gitlab] |   docker restart gitlab
[gitlab] | 
[gitlab] | For a comprehensive list of configuration options please see the Omnibus GitLab readme
[gitlab] | https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md
[gitlab] | 
[gitlab] | If this container fails to start due to permission problems try to fix it by executing:
[gitlab] | 
[gitlab] |   docker exec -it gitlab update-permissions
[gitlab] |   docker restart gitlab
[gitlab] | 
[gitlab] | Cleaning stale PIDs & sockets
cat: /var/opt/gitlab/gitlab-rails/VERSION: No such file or directory
[gitlab] | Installing gitlab.rb config...
cp: cannot create regular file '/etc/gitlab/gitlab.rb': Permission denied
exit code: 1
yupengfei@LenovoY9000P:~/docker/gitlab$ ls -lah
yupengfei@LenovoY9000P:~/docker/gitlab$ ls -lah
total 1.7G
drwxr-xr-x  6 yupengfei yupengfei 4.0K Jan 18 20:05 .
drwxr-xr-x 12 yupengfei yupengfei 4.0K Jan 17 20:31 ..
-rw-r--r--  1 yupengfei yupengfei  993 Jan 18 18:52 compose.yml
drwxr-xr-x  3 yupengfei yupengfei 4.0K Jan 18 20:05 config
drwxr-xr-x  2 yupengfei yupengfei 4.0K Jan 18 20:05 data
-rw-r--r--  1 yupengfei yupengfei 1.2K Jan  6 17:56 docker-compose.local.yml
-rw-r--r--  1 yupengfei yupengfei  512 Jan 18 16:31 docker-compose.yml
-rw-------  1 yupengfei yupengfei 1.7G Jan 18 18:55 gitlab-ce.tar
-rw-r--r--  1 yupengfei yupengfei    2 Jan  5 16:06 install.sh
drwxr-xr-x  2 yupengfei yupengfei 4.0K Jan 18 20:05 logs
-rw-r--r--  1 yupengfei yupengfei   84 Jan  6 18:14 passwd.txt
-rw-r--r--  1 yupengfei yupengfei   14 Jan  5 20:51 rpc-ip.txt
-rw-r--r--  1 yupengfei yupengfei  304 Jan  5 19:47 run.260105.sh
-rw-r--r--  1 yupengfei yupengfei  296 Jan 18 17:34 run.sh.260118
drwxr-xr-x  2 yupengfei yupengfei 4.0K Jan  6 19:10 ssl

问题的关键：`security_opt` 与 `volumes` 的冲突

让我们看一下你 compose.yml 中的这两个配置项：

Podman使用本地在docker上下载的镜像 😎

mr_yupengfei@foxmail.com (MrYuPengfei) — Sun, 18 Jan 2026 19:20:20 +0800

这是一个非常常见的需求，尤其是在从 Docker 过渡到 Podman 或者两者混合使用的环境中。你完全可以利用已经在 Docker 中下载好的本地镜像，而无需为 Podman 重新下载一遍，这能节省大量的时间和带宽。

实现这个目标主要有两种方法：导出/导入 和 共享存储。

方法一：导出为 Tar 包，再导入 Podman (最通用、最推荐)

这个方法就像打包和解包，它不依赖于 Docker 和 Podman 的底层存储结构，因此兼容性最好，适用于任何系统。

步骤：

在 Docker 中保存镜像为 Tar 文件: 首先，找到你想要迁移的 Docker 镜像的名称和标签 (TAG)。你可以用 docker images 查看。
```
# 语法: docker save -o <输出文件名.tar> <镜像名:标签>
# 示例:
docker save -o gitlab-ce.tar docker.io/gitlab/gitlab-ce:18.8.0-ce.0
```
执行后，你会在当前目录下得到一个名为 gitlab-ce.tar 的文件。
在 Podman 中加载这个 Tar 文件: 现在，使用 podman load 命令将这个文件导入到 Podman 的本地存储中。
```
# 语法: podman load -i <文件名.tar>
# 示例:
podman load -i gitlab-ce.tar
```
验证镜像是否导入成功: 使用 podman images 命令检查镜像是否已经存在于 Podman 的列表中。

📖 on 技术分享 Public Site

RAGFlow项目配置与部署指南 😸

RAGFlow 项目配置与部署指南

摘要

1. 核心文件结构分析

2. RAGFlow 配置步骤详解

LFM2.5 1.2B Instruct在DockerOllama上的部署、训练与RAGFlow集成指南 😸

LFM2.5-1.2B-Instruct 模型在 Docker Ollama 上的部署、训练与 RAGFlow 集成指南

摘要

一、使用 Docker Ollama 运行 LFM2.5-1.2B-Instruct

1. 部署 Ollama Docker 容器

2. 拉取 LFM2.5-1.2B-Instruct 模型

配置RagFlow 😸

RAGFlow 项目配置与部署指南

摘要

1. 核心文件结构分析

2. RAGFlow 配置步骤详解

在VMware虚拟机部署Gitlab😎

总结：从启动失败到 HTTPS 成功，我们的排错之旅

初始目标

第一阶段：Docker 权限与环境问题

第二阶段：docker-compose.yml 语法混淆

第三阶段：网络访问与 HTTPS 配置的曲折之路

让Hugo主题能够灵活地显示文章的封面图片 😸

需求背景

问题分析

解决方案：“优雅降级”的模板逻辑

最终实现的代码

总结

一次对WSL2“网络连接风暴”的深度诊断与修复实录 😸

前言

故障初现：systemctl 失效

第一层迷雾：apt 网络中断

Podman运行gitlab时的权限问题 😸

问题的关键：security_opt 与 volumes 的冲突

Podman使用本地在docker上下载的镜像 😎

方法一：导出为 Tar 包，再导入 Podman (最通用、最推荐)

第二阶段：`docker-compose.yml` 语法混淆

故障初现：`systemctl` 失效

第一层迷雾：`apt` 网络中断

问题的关键：`security_opt` 与 `volumes` 的冲突