白嫖腾讯Cloud Studio从源码部署最新版完整RAGFlow

相比于 dify、n8n 等框架，RAGFlow 资源要求较高，非生产环境下，仅仅为了测试用途开设一台符合最低标准的 VPS 开销过大。本文建议采用赠送时长的腾讯 Cloud Studio 从源码部署 RAGFlow，对于个人或小型团队而言，可以节约一定的测试、开发开销。腾讯 Cloud Studio 提供了高性能、通用两种工作空间，通俗地说，就是提供 GPU 算力和 CPU 算力的区别，本文以通用工作空间为例，旗舰型提供了8 核 16G 内存的工作空间，提供公网访问接口，每月赠送 50000 分钟运行时长，尤其适用于已经在本地测试完成、无须 24 小时在线运行的 PoC 演示等项目需求。

克隆仓库、安装依赖

建议直接克隆拉取官方仓库，作者仓库启用了 sandbox，使用本地 embedding 模型，增加了两项私有 API 实现，同时删除了自带前端（web 目录）。

apt install libjemalloc-dev pipx unixodbc-dev unixodbc -y
apt install default-jdk -y
pipx install uv pre-commit
git clone https://github.com/secpo/ragflow.git
cd ragflow/
uv sync --python 3.11 --all-extras
uv run download_deps.py
pre-commit install

依赖安装过程很快，无需额外指定镜像加速站点，huggingface 模型文件拉取也不会有任何障碍。

depend.py

Sandbox启用说明

Sandbox启用/禁用在官方文档中说明不详，导致 0.19.0 以来新增的 code 节点在使用上对普通用户存在障碍，简要说明。

编辑 docker/.env 文件

-- 取消所有的 SANDBOX 注释，其中的 infiniflow/sandbox-executor-manager 会在加载时自动下载

SANDBOX_ENABLED=1
SANDBOX_HOST=sandbox-executor-manager
SANDBOX_EXECUTOR_MANAGER_IMAGE=infiniflow/sandbox-executor-manager:latest
SANDBOX_EXECUTOR_MANAGER_POOL_SIZE=3
SANDBOX_BASE_PYTHON_IMAGE=infiniflow/sandbox-base-python:latest
SANDBOX_BASE_NODEJS_IMAGE=infiniflow/sandbox-base-nodejs:latest
SANDBOX_EXECUTOR_MANAGER_PORT=9385
SANDBOX_ENABLE_SECCOMP=false
SANDBOX_MAX_MEMORY=256m # b, k, m, g
SANDBOX_TIMEOUT=10s # s, m, 1m30s

# Important: To enable sandbox, you must re-declare the compose profiles.
# 1. Comment out the COMPOSE_PROFILES line above.
# 2. Uncomment one of the following based on your chosen document engine:
#    - For Elasticsearch:
# COMPOSE_PROFILES=elasticsearch,sandbox
#    - For Infinity:
# COMPOSE_PROFILES=infinity,sandbox
#    - For OpenSearch:
# COMPOSE_PROFILES=opensearch,sandbox

-- 将 COMPOSE_PROFILES 行修改如下，添加 sandbox 环境

# COMPOSE_PROFILES=${DOC_ENGINE}
COMPOSE_PROFILES=elasticsearch,sandbox

安装 Gvisor 并作为 docker 运行时

RAGFlow sandbox 基于 gvisor，不安装 gvisor 控制台和日志不会显示任何错误，agent code 节点一定无法正常运行。

-- 下载最新的 gvisor 发布版本

该步骤建议通过 ssh 登录腾讯 Cloud studio 后完成，VS Code 终端中可能会出现 shell 版本问题出现命令转义错误。

(
  set -e
  ARCH=$(uname -m)
  URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
  wget ${URL}/runsc ${URL}/runsc.sha512 \
    ${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512
  sha512sum -c runsc.sha512 \
    -c containerd-shim-runsc-v1.sha512
  rm -f *.sha512
  chmod a+rx runsc containerd-shim-runsc-v1
  sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin
)

-- 将 gvisor 安装为 docker 运行时

/usr/local/bin/runsc install
systemctl reload docker
docker run --rm --runtime=runsc hello-world

启动依赖容器

通过 Docker Compose 启动依赖的服务（MinIO, Elasticsearch, Redis, MySQL, Sandbox-executor-manager ），所有依赖镜像会自动拉取，而且速度很快。腾讯 Cloud Studio 这方面很有优势，docker hub、huggingface 访问畅通无阻，无需额外指定 mirror 站点。

docker pull

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

ports

添加所有依赖的服务项的解析。

echo "127.0.0.1       es01 infinity mysql minio redis sandbox-executor-manager" >> /etc/hosts

当然，也可以手动编辑 /etc/hosts 文件，添加上述行。

hosts

启动后端服务

启动后端服务时，是否创建、使用虚拟环境取决于实际需要，本文演示环境同时部署了 n8n，所以使用了虚拟环境。所有环境变量到处都建议通过编辑用户主目录下的 .bashrc 实现。

# 0.如果所有依赖安装至宿主环境，务必忽略
source .venv/bin/activate
# 1.启动debug模式，无热更新需求可忽略
export RAGFLOW_DEBUG=true
# 2.launch_backend_service.sh 启动脚本已包含，可忽略
# export PYTHONPATH=$(pwd)
# 3.指定 tika-server 库，用于解析doc文件
export TIKA_SERVER_JAR="file:///opt/ragflow/tika-server-standard-3.0.0.jar"
# 4. 启动后端服务（支持热更新）
bash docker/launch_backend_service.sh

后端成功加载运行后，点击『打开浏览器』，页面显示如下内容说明部署成功。地址栏中的 xxxxx-9380.app.cloudstudio.work 就是你的 ragflow 后端 url，Cloud studio 自动分配了主机名并进行反代。这这时，你只需要在前端配置上述 url 就可以注册、登录了，注意前端配置不要再画蛇添足指定后端端口，Cloud Studio 工作空间会自动配置好 ssl 证书和后缀为 9380 的随机主机名。

自定义 API 与热更新

在指定 RAGFLOW_DEBUG=true 后，后端可以热更新。修改、新增公共 API 或私有 API ，都可以直接上传文件至对应目录，ragflow 会进行自动搜索、自动注册以及端点 url 检查，api 实现即时生效。RAGFlow API 分类如下：

私有 api，端点 url 为 /v1/{api_name} ，服务端监听端口默认为 9380，对应后端目录为 api/apps，调用要求登录（@login_required），基于 session/cookie 认证
公共 api，端点 url 为 /v1/api/{api_name}，服务端监听端口默认为 9222，对应后端目录为 api/apps/sdk，调用需要 Bearer Token（@token_required），基于 API Key 认证

在自带前端中，src/utils/api.ts 映射了所有的私有 api 端点，如有新增自定义私有 API，可在文件末尾添加映射。api.ts 中还定义了少量伪公共 API 端点映射如 /v1/api/new_token，实际是私有 API 中的 API Token 管理功能，并不是真正的公共 SDK API，而 RAGFlow 默认的公共 API 功能、丰富度要远远逊色于私有 API，二次开发首选私有 API，可以少造很多轮子。

let api_host = `/v1`;

export { api_host };

export default {
  // user
  login: `${api_host}/user/login`,
  logout: `${api_host}/user/logout`,
  register: `${api_host}/user/register`,
  setting: `${api_host}/user/setting`,
  user_info: `${api_host}/user/info`,
  tenant_info: `${api_host}/user/tenant_info`,
  set_tenant_info: `${api_host}/user/set_tenant_info`,
  login_channels: `${api_host}/user/login/channels`,
  login_channel: (channel: string) => `${api_host}/user/login/${channel}`,

... ...

除此之外，0.19.0 版本 RAGFlow 中的插件也是可以很容易自定义并添加，实现“即插即用”的效果，其功能依赖于 sandbox 的开启。启用 sandbox 后，在前端画布中添加的“生成回答”节点中，就可以看到可以指定允许 LLM 调用的工具。默认的 bad_calculator 是个官方示例，添加插件的方法和自定义 api 相同，将工具实现文件放在后端 plugin 目录下（供 LLM 调用的工具目录为 plugin/embedded_plugins/llm_tools/），如果符合规范，系统会自动进行注册、加载，自带前端也可以进行选择指定。LLM 工具调用的前提是模型服务商和 LLM 本身支持完整的函数式调用。

tools

至此，从源码部署一个完整的、包括 Sandbox 支持的 RAGFlow 就完成了。Cloud Studio 旗舰级通用工作空间的规格足够中小型项目后端演示使用，还可以停止运行以节省免费配额，Cloud Studio 实例自带的 ollama、deepseek 等服务，如果没有需要可以不再加载甚至删除，理论上不会受到官方限制。另外，也可以直接删除该工作空间，删除后 90 天内工作空间的所有内容仍将得到保留，不需要进行重新部署。如果 50000 分钟不够用，那么恭喜，生意太好了，别再抠唆这点费用了。

workspace