🧑‍💻 Ragflow 沙箱本地启动全链路真相溯源

“本地能跑通，才是真的通。—— 但你得知道，到底是哪里让它通了。”

---

目录

1. 背景与目标
2. 项目结构与关键依赖
3. 沙箱服务启动的真正关键
4. 后端 code 组件能用沙箱的本质条件
5. 常见报错与本质原因
6. 最终可用的启动顺序与配置
7. 结语：本地跑通的“真相”

---

背景与目标

ragflow 是一个多组件、强依赖的 AI 应用平台。本地启动 ragflow + 沙箱 + code 组件，让你能在 Mac 上完整体验“代码安全执行”的全链路。

但很多人（包括我）会遇到“沙箱起不来”“code 组件报错”“环境变量无效”等问题。本文要搞清楚：到底哪些配置/操作是“必须的”，哪些是“无关紧要的”？

---

项目结构与关键依赖

你的项目结构大致如下：

ragflow-main/
  ├── api/                # 后端主服务
  ├── sandbox/            # 沙箱服务（安全代码执行）
  ├── web/                # 前端
  ├── docker/             # 依赖服务编排（ES、MySQL等）
  ├── .venv/              # Python 虚拟环境
  ├── .env                # 环境变量（可选）
  └── ...                 # 其他

关键依赖：

• Docker + docker-compose（启动 ES、MySQL、Minio、Redis 等）
• Python 虚拟环境（后端、沙箱）
• Node.js（前端）

---

沙箱服务启动的真正关键

1. 启动命令

cd sandbox
export SANDBOX_ENABLED=1
export SANDBOX_HOST=127.0.0.1
bash scripts/start.sh

2. 必须保证的点

• 端口 9385 没被占用（否则沙箱起不来，或者起了多个冲突）
• 不要用 docker-compose 和 bash 启动沙箱服务“同时进行”，否则端口冲突
• 环境变量 SANDBOX_ENABLED/SANDBOX_HOST 对于 bash 脚本不是必须，但对后端主服务是必须的（见下文）

3. 启动成功的标志

• curl http://localhost:9385/healthz 返回 {"status":"ok"}
• http://localhost:9385/docs 能访问

---

后端 code 组件能用沙箱的本质条件

1. 关键代码溯源

在 agent/component/code.py 里，code 组件执行代码时会动态获取沙箱地址：

if address is None:
    from api import settings
    if settings.SANDBOX_ENABLED and settings.SANDBOX_HOST:
        address = f"http://{settings.SANDBOX_HOST}:9385/run"
    else:
        return Code.be_output("**Error**: Sandbox is not enabled or configured")

也就是说：

• 只有 settings.SANDBOX_ENABLED 为真，且 settings.SANDBOX_HOST 有值，code 组件才会去调用沙箱服务。

2. 这些变量的来源

在 api/settings.py 里：

SANDBOX_ENABLED = int(os.environ.get("SANDBOX_ENABLED", "0"))
SANDBOX_HOST = os.environ.get("SANDBOX_HOST", None) if int(os.environ.get("SANDBOX_ENABLED", "0")) else None

也就是说：

• 你必须在启动后端服务的 shell 环境里 export SANDBOX_ENABLED=1 和 export SANDBOX_HOST=127.0.0.1，否则 code 组件永远不会用沙箱。

3. .env 文件的作用

• 如果你用 .env 文件，确保后端服务会自动加载（有的项目用 dotenv，有的没有）。
• 保险做法：直接 export 到 shell。

---

常见报错与本质原因

**Error**: Sandbox is not enabled or configured

• 本质原因：后端服务没设置 SANDBOX_ENABLED=1 和 SANDBOX_HOST=127.0.0.1。

TypeError: main() got an unexpected keyword argument 'a1'

• 本质原因：code 组件传入的参数名和你代码定义的不一致。参数名必须完全一致！

---

最终可用的启动顺序与配置

1. 启动依赖服务

cd docker
docker compose -f docker-compose-base.yml up -d

2. 启动沙箱

cd sandbox
bash scripts/start.sh

（如需 export 环境变量可加上，但对沙箱本身不是必须）

3. 启动后端服务（关键点）

cd /Users/sanrosang/Documents/ragflow-main
source .venv/bin/activate
export PYTHONPATH=$(pwd)
export SANDBOX_ENABLED=1
export SANDBOX_HOST=127.0.0.1
python api/ragflow_server.py

4. 启动前端

cd web
npm install
npm run dev

5. code 组件参数名要和代码一致

def main(a1: str, a2: str) -> str:
    return f"result: {a1 + a2}"

或者把 code 组件输入参数名改成 arg1, arg2。

---

结语：本地跑通的“真相”

• 沙箱能用的本质：后端服务的环境变量 SANDBOX_ENABLED=1 和 SANDBOX_HOST=127.0.0.1 必须设置对。
• code 组件能用的本质：参数名必须和代码一致，沙箱服务端口不能冲突。
• 启动顺序不是绝对，但先起依赖和沙箱更容易排查问题。
• 所有 export 只对当前 shell 有效，换窗口要重来。

“本地能跑通，靠的不是运气，是对每一个细节的死磕和理解。”

---

祝你少踩坑，多喝水，debug 一路绿灯！
如有新坑，欢迎随时来问！