mirror of
https://github.com/infiniflow/ragflow.git
synced 2026-01-28 14:16:34 +08:00
## Summary Implement a flexible sandbox provider system supporting both self-managed (Docker) and SaaS (Aliyun Code Interpreter) backends for secure code execution in agent workflows. **Key Changes:** - ✅ Aliyun Code Interpreter provider using official `agentrun-sdk>=0.0.16` - ✅ Self-managed provider with gVisor (runsc) security - ✅ Arguments parameter support for dynamic code execution - ✅ Database-only configuration (removed fallback logic) - ✅ Configuration scripts for quick setup Issue #12479 ## Features ### 🔌 Provider Abstraction Layer **1. Self-Managed Provider** (`agent/sandbox/providers/self_managed.py`) - Wraps existing executor_manager HTTP API - gVisor (runsc) for secure container isolation - Configurable pool size, timeout, retry logic - Languages: Python, Node.js, JavaScript - ⚠️ **Requires**: gVisor installation, Docker, base images **2. Aliyun Code Interpreter** (`agent/sandbox/providers/aliyun_codeinterpreter.py`) - SaaS integration using official agentrun-sdk - Serverless microVM execution with auto-authentication - Hard timeout: 30 seconds max - Credentials: `AGENTRUN_ACCESS_KEY_ID`, `AGENTRUN_ACCESS_KEY_SECRET`, `AGENTRUN_ACCOUNT_ID`, `AGENTRUN_REGION` - Automatically wraps code to call `main()` function **3. E2B Provider** (`agent/sandbox/providers/e2b.py`) - Placeholder for future integration ### ⚙️ Configuration System - `conf/system_settings.json`: Default provider = `aliyun_codeinterpreter` - `agent/sandbox/client.py`: Enforces database-only configuration - Admin UI: `/admin/sandbox-settings` - Configuration validation via `validate_config()` method - Health checks for all providers ### 🎯 Key Capabilities **Arguments Parameter Support:** All providers support passing arguments to `main()` function: ```python # User code def main(name: str, count: int) -> dict: return {"message": f"Hello {name}!" * count} # Executed with: arguments={"name": "World", "count": 3} # Result: {"message": "Hello World!Hello World!Hello World!"} ``` **Self-Describing Providers:** Each provider implements `get_config_schema()` returning form configuration for Admin UI **Error Handling:** Structured `ExecutionResult` with stdout, stderr, exit_code, execution_time ## Configuration Scripts Two scripts for quick Aliyun sandbox setup: **Shell Script (requires jq):** ```bash source scripts/configure_aliyun_sandbox.sh ``` **Python Script (interactive):** ```bash python3 scripts/configure_aliyun_sandbox.py ``` ## Testing ```bash # Unit tests uv run pytest agent/sandbox/tests/test_providers.py -v # Aliyun provider tests uv run pytest agent/sandbox/tests/test_aliyun_codeinterpreter.py -v # Integration tests (requires credentials) uv run pytest agent/sandbox/tests/test_aliyun_codeinterpreter_integration.py -v # Quick SDK validation python3 agent/sandbox/tests/verify_sdk.py ``` **Test Coverage:** - 30 unit tests for provider abstraction - Provider-specific tests for Aliyun - Integration tests with real API - Security tests for executor_manager ## Documentation - `docs/develop/sandbox_spec.md` - Complete architecture specification - `agent/sandbox/tests/MIGRATION_GUIDE.md` - Migration from legacy sandbox - `agent/sandbox/tests/QUICKSTART.md` - Quick start guide - `agent/sandbox/tests/README.md` - Testing documentation ## Breaking Changes ⚠️ **Migration Required:** 1. **Directory Move**: `sandbox/` → `agent/sandbox/` - Update imports: `from sandbox.` → `from agent.sandbox.` 2. **Mandatory Configuration**: - SystemSettings must have `sandbox.provider_type` configured - Removed fallback default values - Configuration must exist in database (from `conf/system_settings.json`) 3. **Aliyun Credentials**: - Requires `AGENTRUN_*` environment variables (not `ALIYUN_*`) - `AGENTRUN_ACCOUNT_ID` is now required (Aliyun primary account ID) 4. **Self-Managed Provider**: - gVisor (runsc) must be installed for security - Install: `go install gvisor.dev/gvisor/runsc@latest` ## Database Schema Changes ```python # SystemSettings.value: CharField → TextField api/db/db_models.py: Changed for unlimited config length # SystemSettingsService.get_by_name(): Fixed query precision api/db/services/system_settings_service.py: startswith → exact match ``` ## Files Changed ### Backend (Python) - `agent/sandbox/providers/base.py` - SandboxProvider ABC interface - `agent/sandbox/providers/manager.py` - ProviderManager - `agent/sandbox/providers/self_managed.py` - Self-managed provider - `agent/sandbox/providers/aliyun_codeinterpreter.py` - Aliyun provider - `agent/sandbox/providers/e2b.py` - E2B provider (placeholder) - `agent/sandbox/client.py` - Unified client (enforces DB-only config) - `agent/tools/code_exec.py` - Updated to use provider system - `admin/server/services.py` - SandboxMgr with registry & validation - `admin/server/routes.py` - 5 sandbox API endpoints - `conf/system_settings.json` - Default: aliyun_codeinterpreter - `api/db/db_models.py` - TextField for SystemSettings.value - `api/db/services/system_settings_service.py` - Exact match query ### Frontend (TypeScript/React) - `web/src/pages/admin/sandbox-settings.tsx` - Settings UI - `web/src/services/admin-service.ts` - Sandbox service functions - `web/src/services/admin.service.d.ts` - Type definitions - `web/src/utils/api.ts` - Sandbox API endpoints ### Documentation - `docs/develop/sandbox_spec.md` - Architecture spec - `agent/sandbox/tests/MIGRATION_GUIDE.md` - Migration guide - `agent/sandbox/tests/QUICKSTART.md` - Quick start - `agent/sandbox/tests/README.md` - Testing guide ### Configuration Scripts - `scripts/configure_aliyun_sandbox.sh` - Shell script (jq) - `scripts/configure_aliyun_sandbox.py` - Python script ### Tests - `agent/sandbox/tests/test_providers.py` - 30 unit tests - `agent/sandbox/tests/test_aliyun_codeinterpreter.py` - Provider tests - `agent/sandbox/tests/test_aliyun_codeinterpreter_integration.py` - Integration tests - `agent/sandbox/tests/verify_sdk.py` - SDK validation ## Architecture ``` Admin UI → Admin API → SandboxMgr → ProviderManager → [SelfManaged|Aliyun|E2B] ↓ SystemSettings ``` ## Usage ### 1. Configure Provider **Via Admin UI:** 1. Navigate to `/admin/sandbox-settings` 2. Select provider (Aliyun Code Interpreter / Self-Managed) 3. Fill in configuration 4. Click "Test Connection" to verify 5. Click "Save" to apply **Via Configuration Scripts:** ```bash # Aliyun provider export AGENTRUN_ACCESS_KEY_ID="xxx" export AGENTRUN_ACCESS_KEY_SECRET="yyy" export AGENTRUN_ACCOUNT_ID="zzz" export AGENTRUN_REGION="cn-shanghai" source scripts/configure_aliyun_sandbox.sh ``` ### 2. Restart Service ```bash cd docker docker compose restart ragflow-server ``` ### 3. Execute Code in Agent ```python from agent.sandbox.client import execute_code result = execute_code( code='def main(name: str) -> dict: return {"message": f"Hello {name}!"}', language="python", timeout=30, arguments={"name": "World"} ) print(result.stdout) # {"message": "Hello World!"} ``` ## Troubleshooting ### "Container pool is busy" (Self-Managed) - **Cause**: Pool exhausted (default: 1 container in `.env`) - **Fix**: Increase `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE` to 5+ ### "Sandbox provider type not configured" - **Cause**: Database missing configuration - **Fix**: Run config script or set via Admin UI ### "gVisor not found" - **Cause**: runsc not installed - **Fix**: `go install gvisor.dev/gvisor/runsc@latest && sudo cp ~/go/bin/runsc /usr/local/bin/` ### Aliyun authentication errors - **Cause**: Wrong environment variable names - **Fix**: Use `AGENTRUN_*` prefix (not `ALIYUN_*`) ## Checklist - [x] All tests passing (30 unit tests + integration tests) - [x] Documentation updated (spec, migration guide, quickstart) - [x] Type definitions added (TypeScript) - [x] Admin UI implemented - [x] Configuration validation - [x] Health checks implemented - [x] Error handling with structured results - [x] Breaking changes documented - [x] Configuration scripts created - [x] gVisor requirements documented Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
266 lines
9.4 KiB
Python
266 lines
9.4 KiB
Python
#
|
|
# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
#
|
|
import asyncio
|
|
import base64
|
|
import json
|
|
import os
|
|
import time
|
|
import uuid
|
|
|
|
from core.config import TIMEOUT
|
|
from core.container import allocate_container_blocking, release_container
|
|
from core.logger import logger
|
|
from models.enums import ResourceLimitType, ResultStatus, RuntimeErrorType, SupportLanguage, UnauthorizedAccessType
|
|
from models.schemas import CodeExecutionRequest, CodeExecutionResult
|
|
from utils.common import async_run_command
|
|
|
|
|
|
async def execute_code(req: CodeExecutionRequest):
|
|
"""Fully asynchronous execution logic"""
|
|
language = req.language
|
|
container = await allocate_container_blocking(language)
|
|
if not container:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.PROGRAM_RUNNER_ERROR,
|
|
stdout="",
|
|
stderr="Container pool is busy",
|
|
exit_code=-10,
|
|
detail="no_available_container",
|
|
)
|
|
|
|
task_id = str(uuid.uuid4())
|
|
workdir = f"/tmp/sandbox_{task_id}"
|
|
os.makedirs(workdir, mode=0o700, exist_ok=True)
|
|
|
|
try:
|
|
if language == SupportLanguage.PYTHON:
|
|
code_name = "main.py"
|
|
# code
|
|
code_path = os.path.join(workdir, code_name)
|
|
with open(code_path, "wb") as f:
|
|
f.write(base64.b64decode(req.code_b64))
|
|
# runner
|
|
runner_name = "runner.py"
|
|
runner_path = os.path.join(workdir, runner_name)
|
|
with open(runner_path, "w") as f:
|
|
f.write("""import json
|
|
import os
|
|
import sys
|
|
sys.path.insert(0, os.path.dirname(__file__))
|
|
from main import main
|
|
if __name__ == "__main__":
|
|
args = json.loads(sys.argv[1])
|
|
result = main(**args)
|
|
if result is not None:
|
|
print(result)
|
|
""")
|
|
|
|
elif language == SupportLanguage.NODEJS:
|
|
code_name = "main.js"
|
|
code_path = os.path.join(workdir, "main.js")
|
|
with open(code_path, "wb") as f:
|
|
f.write(base64.b64decode(req.code_b64))
|
|
|
|
runner_name = "runner.js"
|
|
runner_path = os.path.join(workdir, "runner.js")
|
|
with open(runner_path, "w") as f:
|
|
f.write("""
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
|
|
const args = JSON.parse(process.argv[2]);
|
|
const mainPath = path.join(__dirname, 'main.js');
|
|
|
|
function isPromise(value) {
|
|
return Boolean(value && typeof value.then === 'function');
|
|
}
|
|
|
|
if (fs.existsSync(mainPath)) {
|
|
const mod = require(mainPath);
|
|
const main = typeof mod === 'function' ? mod : mod.main;
|
|
|
|
if (typeof main !== 'function') {
|
|
console.error('Error: main is not a function');
|
|
process.exit(1);
|
|
}
|
|
|
|
if (typeof args === 'object' && args !== null) {
|
|
try {
|
|
const result = main(args);
|
|
if (isPromise(result)) {
|
|
result.then(output => {
|
|
if (output !== null) {
|
|
console.log(output);
|
|
}
|
|
}).catch(err => {
|
|
console.error('Error in async main function:', err);
|
|
});
|
|
} else {
|
|
if (result !== null) {
|
|
console.log(result);
|
|
}
|
|
}
|
|
} catch (err) {
|
|
console.error('Error when executing main:', err);
|
|
}
|
|
} else {
|
|
console.error('Error: args is not a valid object:', args);
|
|
}
|
|
} else {
|
|
console.error('main.js not found in the current directory');
|
|
}
|
|
""")
|
|
# dirs
|
|
returncode, _, stderr = await async_run_command("docker", "exec", container, "mkdir", "-p", f"/workspace/{task_id}", timeout=5)
|
|
if returncode != 0:
|
|
raise RuntimeError(f"Directory creation failed: {stderr}")
|
|
|
|
# archive
|
|
tar_proc = await asyncio.create_subprocess_exec("tar", "czf", "-", "-C", workdir, code_name, runner_name, stdout=asyncio.subprocess.PIPE)
|
|
tar_stdout, _ = await tar_proc.communicate()
|
|
|
|
# unarchive
|
|
docker_proc = await asyncio.create_subprocess_exec(
|
|
"docker", "exec", "-i", container, "tar", "xzf", "-", "-C", f"/workspace/{task_id}", stdin=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
|
|
)
|
|
stdout, stderr = await docker_proc.communicate(input=tar_stdout)
|
|
|
|
if docker_proc.returncode != 0:
|
|
raise RuntimeError(stderr.decode())
|
|
|
|
# exec
|
|
start_time = time.time()
|
|
try:
|
|
logger.info(f"Passed in args: {req.arguments}")
|
|
args_json = json.dumps(req.arguments or {})
|
|
run_args = [
|
|
"docker",
|
|
"exec",
|
|
"--workdir",
|
|
f"/workspace/{task_id}",
|
|
container,
|
|
"timeout",
|
|
str(TIMEOUT),
|
|
language,
|
|
]
|
|
# flags
|
|
if language == SupportLanguage.PYTHON:
|
|
run_args.extend(["-I", "-B"])
|
|
elif language == SupportLanguage.NODEJS:
|
|
run_args.extend([])
|
|
else:
|
|
assert False, "Will never reach here"
|
|
run_args.extend([runner_name, args_json])
|
|
|
|
returncode, stdout, stderr = await async_run_command(
|
|
*run_args,
|
|
timeout=TIMEOUT + 5,
|
|
)
|
|
|
|
time_used_ms = (time.time() - start_time) * 1000
|
|
|
|
logger.info("----------------------------------------------")
|
|
logger.info(f"Code: {str(base64.b64decode(req.code_b64))}")
|
|
logger.info(f"{returncode=}")
|
|
logger.info(f"{stdout=}")
|
|
logger.info(f"{stderr=}")
|
|
logger.info(f"{args_json=}")
|
|
|
|
if returncode == 0:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.SUCCESS,
|
|
stdout=str(stdout),
|
|
stderr=stderr,
|
|
exit_code=0,
|
|
time_used_ms=time_used_ms,
|
|
)
|
|
elif returncode == 124:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.RESOURCE_LIMIT_EXCEEDED,
|
|
stdout="",
|
|
stderr="Execution timeout",
|
|
exit_code=-124,
|
|
resource_limit_type=ResourceLimitType.TIME,
|
|
time_used_ms=time_used_ms,
|
|
)
|
|
elif returncode == 137:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.RESOURCE_LIMIT_EXCEEDED,
|
|
stdout="",
|
|
stderr="Memory limit exceeded (killed by OOM)",
|
|
exit_code=-137,
|
|
resource_limit_type=ResourceLimitType.MEMORY,
|
|
time_used_ms=time_used_ms,
|
|
)
|
|
return analyze_error_result(stderr, returncode)
|
|
|
|
except asyncio.TimeoutError:
|
|
await async_run_command("docker", "exec", container, "pkill", "-9", language)
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.RESOURCE_LIMIT_EXCEEDED,
|
|
stdout="",
|
|
stderr="Execution timeout",
|
|
exit_code=-1,
|
|
resource_limit_type=ResourceLimitType.TIME,
|
|
time_used_ms=(time.time() - start_time) * 1000,
|
|
)
|
|
|
|
except Exception as e:
|
|
logger.error(f"Execution exception: {str(e)}")
|
|
return CodeExecutionResult(status=ResultStatus.PROGRAM_RUNNER_ERROR, stdout="", stderr=str(e), exit_code=-3, detail="internal_error")
|
|
|
|
finally:
|
|
# cleanup
|
|
cleanup_tasks = [async_run_command("docker", "exec", container, "rm", "-rf", f"/workspace/{task_id}"), async_run_command("rm", "-rf", workdir)]
|
|
await asyncio.gather(*cleanup_tasks, return_exceptions=True)
|
|
await release_container(container, language)
|
|
|
|
|
|
def analyze_error_result(stderr: str, exit_code: int) -> CodeExecutionResult:
|
|
"""Analyze the error result and classify it"""
|
|
if "Permission denied" in stderr:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.UNAUTHORIZED_ACCESS,
|
|
stdout="",
|
|
stderr=stderr,
|
|
exit_code=exit_code,
|
|
unauthorized_access_type=UnauthorizedAccessType.FILE_ACCESS,
|
|
)
|
|
elif "Operation not permitted" in stderr:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.UNAUTHORIZED_ACCESS,
|
|
stdout="",
|
|
stderr=stderr,
|
|
exit_code=exit_code,
|
|
unauthorized_access_type=UnauthorizedAccessType.DISALLOWED_SYSCALL,
|
|
)
|
|
elif "MemoryError" in stderr:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.RESOURCE_LIMIT_EXCEEDED,
|
|
stdout="",
|
|
stderr=stderr,
|
|
exit_code=exit_code,
|
|
resource_limit_type=ResourceLimitType.MEMORY,
|
|
)
|
|
else:
|
|
return CodeExecutionResult(
|
|
status=ResultStatus.PROGRAM_ERROR,
|
|
stdout="",
|
|
stderr=stderr,
|
|
exit_code=exit_code,
|
|
runtime_error_type=RuntimeErrorType.NONZERO_EXIT,
|
|
)
|