MacOS 安装 RagFlow 全踩坑指南

整整3天，才把RagFlow在MacOS上跑通。过程有多曲折，看这篇记录就知道了——每一步都踩过坑，索性把要点全拆出来，苹果用户照着做就行。

1-修改RAGFLOW镜像

如果要下载embedding模型，得先动.env文件里的RAGFLOW_IMAGE配置。找到那行代码，注释掉默认的镜像地址：

#RAGFLOW_IMAGE=infiniflow/ragflow:v0.17.0-slim

RagFlow的安装依赖Docker，对应的文件夹里放着不同版本的.yml配置文件。MacOS必须选docker-compose-macos.yml来启动服务——这个文件对苹果系统做了专门优化，用别的版本大概率会翻车。

然后就是经典问题：网络连接失败。从Docker Hub拉基础镜像时请求超时，报错信息长这样：

> [ragflow internal] load metadata for docker.io/infiniflow/ragflow_deps:latest:

------

------

> [ragflow internal] load metadata for docker.io/library/ubuntu:22.04:

------

failed to solve: ubuntu:22.04: failed to resolve source metadata for docker.io/library/ubuntu:22.04: failed to authorize: failed to fetch anonymous token: Get "https://auth.docker.io/token?scope=repository%3Alibrary%2Fubuntu%3Apull&service=registry.docker.io": dial tcp [2a03:2880:f12c:183:face:b00c:0:25de]:443: i/o timeout

解决办法在这里：继续改.env文件，用国内镜像源代替自建拉取：

# 修改这部分，使用预构建的镜像而不是尝试构建
# RAGFLOW_IMAGE=infiniflow/ragflow:v0.17.0
# 使用国内镜像源
RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v0.17.0

# 确保已启用MacOS优化
MACOS=1

# 添加HuggingFace镜像
HF_ENDPOINT=https://hf-mirror.com

然后用docker-compose-macos.yml启动，但得先确认文件已经指向了预构建镜像（而不是走构建流程）。之后运行：

docker-compose -f docker-compose-macos.yml up -d

注意：整个镜像文件有50G，拉取时间会非常非常长。这段时间可以去做点别的，慢慢等着就好。

拉完后用docker ps查看容器状态，如果所有服务都正常，那就基本到位了。

接下来打开浏览器访问本地页面：http://localhost/login。第一次用需要注册账号。

如果你的电脑上还装了Dify，大概率会遇上端口冲突——两个服务默认都占80/443端口。解决办法很简单：编辑docker-compose-macos.yml，把端口映射改掉。

应用更改并重启服务

端口改好后，用下面两条命令重启RagFlow：

docker-compose -f docker-compose-macos.yml down  #关闭
docker-compose -f docker-compose-macos.yml up -d #启动服务

访问RagFlow Web界面

再用浏览器访问新端口，比如http://localhost:8080。奋战3天的成果，终于能用了。