RAGFlow ARM64 (64KB Page Size) 部署避坑指南

1. 问题背景

在特定的 ARM64 Linux 系统上部署 RAGFlow 时，核心组件 sandbox 或 sandbox-executor-manager 无法启动，主要表现为以下错误：

核心报错 (Panic):

text 复制代码

panic: Only 4K page size is supported on arm64!

原因：gVisor (runsc) 目前不支持 64KB 页大小的内核。

次生报错 (Container pool is busy):

即使强制去掉了 runsc，系统仍提示资源忙。
日志显示 [Errno 8] Exec format error: 'docker'。
原因：沙盒管理器内部的 Docker 客户端与宿主机架构/内核不兼容，导致无法创建子容器。

2. 核心解决方案

由于硬件环境限制无法使用 gVisor (runsc)，必须彻底切换为标准 Docker 运行时 (runc)，并修复容器内部调用 Docker 的兼容性问题。

核心修改点

禁用 gVisor ：通过环境变量强制指定子容器运行时为 runc。
修复 Docker 调用：将宿主机的 Docker 二进制文件挂载到容器内。
提升权限与资源：开启特权模式并增加内存限制（ARM Python 内存开销大）。

3. 详细配置指南

请直接修改 docker-compose.yml 中的 sandbox-executor-manager 部分。

3.1 确认宿主机 Docker 路径

在修改配置前，先在宿主机执行命令，确认 docker 可执行文件的位置：

bash 复制代码

which docker
# 输出通常为 /usr/bin/docker 或 /usr/local/bin/docker

3.2 修改 `docker-compose.yml`

用以下配置替换原有的 sandbox-executor-manager 服务块：

yaml 复制代码

  sandbox-executor-manager:
    profiles:
      - sandbox
    image: ${SANDBOX_EXECUTOR_MANAGER_IMAGE-infiniflow/sandbox-executor-manager:latest}
    
    # 【关键点 1】开启特权模式
    # 普通容器无法在内部操作 Docker 或进行复杂的网络绑定
    privileged: true 
    
    # 保持 Host 网络模式 (根据实际网络环境调整，通常 Host 模式最稳)
    network_mode: host
    
    ports:
      - ${SANDBOX_EXECUTOR_MANAGER_PORT-9385}:9385
    
    env_file: .env
    
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      # 【关键点 2】解决 Exec format error
      # 容器自带的 docker cli 可能与宿主机内核不兼容，强制挂载宿主机的 docker 命令
      # 注意：如果你的 docker 在 /usr/local/bin，请相应修改冒号前的路径
      - /usr/bin/docker:/usr/bin/docker
    
    environment:
      # 【关键点 3】强制禁用 gVisor
      # 告诉管理器创建子容器时使用 runc 而不是 runsc
      - SANDBOX_RUNTIME=runc
      - RAGFLOW_SANDBOX_RUNTIME=runc  # 双重保险，防止不同版本变量名差异
      
      # 基础配置
      - SANDBOX_EXECUTOR_MANAGER_POOL_SIZE=${SANDBOX_EXECUTOR_MANAGER_POOL_SIZE:10}
      - SANDBOX_BASE_PYTHON_IMAGE=${SANDBOX_BASE_PYTHON_IMAGE:-infiniflow/sandbox-base-python:latest}
      - SANDBOX_BASE_NODEJS_IMAGE=${SANDBOX_BASE_NODEJS_IMAGE:-infiniflow/sandbox-base-nodejs:latest}
      
      # 【关键点 4】资源调整
      # ARM64 下 Python 进程内存占用较高，256m 极易导致 OOM (内存溢出) 崩溃
      - SANDBOX_MAX_MEMORY=${SANDBOX_MAX_MEMORY:-512m}
      - SANDBOX_TIMEOUT=${SANDBOX_TIMEOUT:-10s}
      - SANDBOX_ENABLE_SECCOMP=false

    healthcheck:
      test: ["CMD", "curl", "http://localhost:9385/healthz"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: on-failure

4. 重启与验证步骤

修改配置后，必须执行彻底的重启以清理之前的僵尸容器。

步骤 1：清理环境

bash 复制代码

# 停止所有服务
docker compose -f docker/docker-compose.yml down

# (可选但推荐) 清理之前创建失败的僵尸容器，释放资源
docker container prune -f

步骤 2：启动服务

bash 复制代码

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

步骤 3：验证日志

查看管理器日志，确认子容器池初始化成功：

bash 复制代码

docker logs -f sandbox-executor-manager

成功的标志：

没有 Exec format error 报错。
没有 panic 报错。
日志显示类似：

text 复制代码

INFO:sandbox:🛠️ Creating Python container 1/10
...
INFO:sandbox:📊 Container pool initialization complete: 10/10 available

5. 安全提示

注意： 上述修改去除了 RAGFlow 的核心安全屏障（gVisor 沙盒）。

原本机制： 代码在 gVisor 隔离的内核中运行，无法攻击宿主机。
当前机制： 代码在普通 Docker 容器中运行，且该容器可能拥有较高权限。

适用场景： 内部网络部署、个人测试、处理可信文档。
不适用场景： 公网开放服务（SaaS）、处理不可信用户上传的恶意文件或代码。

RAGFlow ARM64 (64KB Page Size) 部署避坑指南