macOS 环境下的 RAGFlow 部署涉及环境准备、Docker 安装及配置优化。首先需满足内存与磁盘要求，调整系统虚拟内存映射参数以支持 Elasticsearch。通过克隆仓库并拉取镜像完成基础部署，处理端口冲突后启动服务。验证阶段检查容器状态并访问 Web 界面初始化账户。常见问题包括 ES 启动失败、镜像超时及权限问题，可通过调整系统参数、配置代理或修改权限解决。进阶配置涵盖嵌入模型选择、向量数据库切换及 GPU 加速启用，确保系统性能与安全。
RAGFlow 是由 Infiniflow 团队开发的开源知识库引擎，专为构建企业级检索增强生成（RAG）系统而设计。它结合了先进的文档解析、向量化存储和智能检索技术，能够帮助用户快速搭建高性能的问答系统。
在开始安装前，请确保您的系统满足以下要求：
# 检查 Docker 版本（需 ≥ 24.0.0）
docker --version
# 检查 Docker Compose 版本（需 ≥ v2.26.1）
docker compose version
# 检查 Git 版本
git --version
为避免 Elasticsearch 启动报错，需增加虚拟内存映射限制：
# 临时设置（重启后失效）
sudo sysctl -w vm.max_map_count=262144
# 永久设置（推荐）
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
# 立即生效
重要提醒：此参数调整是必须步骤，否则 Elasticsearch 将因内存映射不足无法启动。
# 克隆项目仓库
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
# 查看项目结构
ls -la
为避免国内网络环境导致的镜像拉取问题，需先手动拉取基础镜像：
# 拉取基础依赖镜像
docker pull --platform linux/amd64 infiniflow/ragflow_deps:latest
# 验证镜像拉取成功
docker images | grep ragflow
如果遇到镜像拉取失败，编辑 /etc/docker/daemon.json，删除以下镜像源配置：
{"registry-mirrors":["https://docker.mirrors.ustc.edu.cn","https://hub-mirror.c.163.com"]}
然后重启 Docker 服务：
# macOS 重启 Docker
osascript -e 'quit app "Docker"'
open -a Docker
# 或者使用命令行重启（Linux）
sudo systemctl restart docker
# 启动所有服务
docker compose -p ragflow -f docker-compose-macos.yml up -d
# 查看启动日志
docker compose -p ragflow logs -f
如果 80 端口被占用，修改为其他端口（如 8080）：
# macOS 修改命令
sed -i '' 's/- "80:80"/- "8080:80"/' docker-compose-macos.yml
# Linux 修改命令
sed -i 's/- "80:80"/- "8080:80"/' docker-compose-macos.yml
# 重新启动服务
docker compose -p ragflow -f docker-compose-macos.yml down
docker compose -p ragflow -f docker-compose-macos.yml up -d
# 查看所有容器状态
docker compose -p ragflow ps
# 查看详细日志
docker compose -p ragflow logs ragflow
预期输出应显示所有容器处于 running 状态：
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
ragflow-es01 docker.elastic.co/elasticsearch... "/bin/tini -- /usr/l…" elasticsearch 5 minutes ago Up 5 minutes 9200/tcp, 9300/tcp
ragflow-ragflow infiniflow/ragflow_deps:latest "/entrypoint.sh" ragflow 5 minutes ago Up 5 minutes 0.0.0.0:80->80/tcp ...
打开浏览器访问：http://localhost（或修改后的端口如 http://localhost:8080）
首次访问需完成初始化配置：
BAAI/bge-large-en-v1.5完成配置后，可以尝试以下功能：
现象：容器日志显示 max virtual memory areas vm.max_map_count [65530] is too low
解决：重新执行系统参数调优步骤：
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
现象：Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled
解决：
docker pull --platform linux/amd64 infiniflow/ragflow_deps:latest
现象：Bind for 0.0.0.0:80 failed: port is already allocated
解决：按前文方法修改端口配置后重新启动：
docker compose -p ragflow -f docker-compose-macos.yml down
docker compose -p ragflow -f docker-compose-macos.yml up -d
现象：容器频繁重启或服务响应缓慢
解决：
# 增加 Docker 内存限制
# 在 Docker Desktop 设置中调整内存分配（推荐 8GB+）
# 或者调整 Elasticsearch 内存配置
# 编辑 docker-compose-macos.yml 中的环境变量
现象：文件访问权限错误
解决：
# 检查文件权限
ls -la docker-compose-macos.yml
# 修改权限
chmod 644 docker-compose-macos.yml
编辑 docker/ragflow/conf/service_conf.yaml：
embedding:
model_name: "BAAI/bge-large-en-v1.5"
# 替换为您的模型
device: "cuda"
# 或 "cpu"
max_length: 512
batch_size: 32
修改 docker-compose-macos.yml 中的环境变量：
environment:
- VECTOR_DB_TYPE=milvus
# 支持 milvus, qdrant, weaviate 等
- MILVUS_HOST=your-milvus-host
- MILVUS_PORT=19530
在 docker-compose-macos.yml 中添加：
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
# 调整 Elasticsearch 配置
ES_JAVA_OPTS=-Xms2g -Xmx4g
# discovery.type=single-node
# 调整 RAGFlow 配置
WORKER_NUM=4
MAX_WORKER_NUM=8
# 启用 HTTPS
nginx:
volumes:
- ./ssl:/etc/nginx/ssl
environment:
- SSL_CERT=/etc/nginx/ssl/cert.pem
- SSL_KEY=/etc/nginx/ssl/key.pem
# 查看容器资源使用情况
docker stats
# 查看日志
docker compose -p ragflow logs -f --tail=100
通过本文的详细指南，您已成功部署了企业级知识库引擎 RAGFlow。该系统具备以下核心价值：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online