mirror of
https://github.com/infiniflow/ragflow.git
synced 2026-07-04 01:29:35 +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>
321 lines
9.5 KiB
TypeScript
321 lines
9.5 KiB
TypeScript
import { history } from '@/utils/simple-history-util';
|
|
import axios from 'axios';
|
|
|
|
import message from '@/components/ui/message';
|
|
import { Authorization } from '@/constants/authorization';
|
|
import i18n from '@/locales/config';
|
|
import { Routes } from '@/routes';
|
|
import api from '@/utils/api';
|
|
import authorizationUtil, {
|
|
getAuthorization,
|
|
} from '@/utils/authorization-util';
|
|
import { convertTheKeysOfTheObjectToSnake } from '@/utils/common-util';
|
|
import { ResultCode, RetcodeMessage } from '@/utils/request';
|
|
|
|
const request = axios.create({
|
|
timeout: 300000,
|
|
});
|
|
|
|
request.interceptors.request.use((config) => {
|
|
const data = convertTheKeysOfTheObjectToSnake(config.data);
|
|
const params = convertTheKeysOfTheObjectToSnake(config.params) as any;
|
|
|
|
const newConfig = { ...config, data, params };
|
|
|
|
// @ts-ignore
|
|
if (!newConfig.skipToken) {
|
|
newConfig.headers.set(Authorization, getAuthorization());
|
|
}
|
|
|
|
return newConfig;
|
|
});
|
|
|
|
request.interceptors.response.use(
|
|
(response) => {
|
|
if (response.config.responseType === 'blob') {
|
|
return response;
|
|
}
|
|
|
|
const { data } = response ?? {};
|
|
|
|
if (data?.code === 100) {
|
|
message.error(data?.message);
|
|
} else if (data?.code === 401) {
|
|
message.error(data?.message, {
|
|
description: data?.message,
|
|
});
|
|
|
|
authorizationUtil.removeAll();
|
|
history.push(Routes.Admin);
|
|
window.location.reload();
|
|
} else if (data?.code && data.code !== 0) {
|
|
message.error(`${i18n.t('message.hint')}: ${data?.code}`, {
|
|
description: data?.message,
|
|
});
|
|
}
|
|
|
|
return response;
|
|
},
|
|
(error) => {
|
|
const { response } = error;
|
|
const { data } = response ?? {};
|
|
|
|
if (error.message === 'Failed to fetch') {
|
|
message.error({
|
|
description: i18n.t('message.networkAnomalyDescription'),
|
|
message: i18n.t('message.networkAnomaly'),
|
|
});
|
|
} else if (data?.code === 100) {
|
|
message.error(data?.message);
|
|
} else if (response.status === 401 || data?.code === 401) {
|
|
message.error({
|
|
message: data?.message || response.statusText,
|
|
description:
|
|
data?.message || RetcodeMessage[response?.status as ResultCode],
|
|
duration: 3,
|
|
});
|
|
|
|
authorizationUtil.removeAll();
|
|
history.push(Routes.Admin);
|
|
window.location.reload();
|
|
} else if (data?.code && data.code !== 0) {
|
|
message.error({
|
|
message: `${i18n.t('message.hint')}: ${data?.code}`,
|
|
description: data?.message,
|
|
duration: 3,
|
|
});
|
|
} else if (response.status) {
|
|
message.error({
|
|
message: `${i18n.t('message.requestError')} ${response.status}: ${response.config.url}`,
|
|
description:
|
|
RetcodeMessage[response.status as ResultCode] || response.statusText,
|
|
});
|
|
} else if (response.status === 413 || response?.status === 504) {
|
|
message.error(RetcodeMessage[response?.status as ResultCode]);
|
|
}
|
|
|
|
throw error;
|
|
},
|
|
);
|
|
|
|
const {
|
|
adminLogin,
|
|
adminLogout,
|
|
adminListUsers,
|
|
adminCreateUser,
|
|
adminGetUserDetails,
|
|
adminUpdateUserStatus,
|
|
adminUpdateUserPassword,
|
|
adminDeleteUser,
|
|
adminListUserDatasets,
|
|
adminListUserAgents,
|
|
|
|
adminListServices,
|
|
adminShowServiceDetails,
|
|
|
|
adminListRoles,
|
|
adminListRolesWithPermission,
|
|
adminCreateRole,
|
|
adminDeleteRole,
|
|
adminUpdateRoleDescription,
|
|
adminGetRolePermissions,
|
|
adminAssignRolePermissions,
|
|
adminRevokeRolePermissions,
|
|
|
|
adminGetUserPermissions,
|
|
adminUpdateUserRole,
|
|
|
|
adminListResources,
|
|
|
|
adminListWhitelist,
|
|
adminCreateWhitelistEntry,
|
|
adminUpdateWhitelistEntry,
|
|
adminDeleteWhitelistEntry,
|
|
adminImportWhitelist,
|
|
|
|
adminGetSystemVersion,
|
|
|
|
adminListSandboxProviders,
|
|
adminGetSandboxProviderSchema,
|
|
adminGetSandboxConfig,
|
|
adminSetSandboxConfig,
|
|
adminTestSandboxConnection,
|
|
} = api;
|
|
|
|
type ResponseData<D = NonNullable<unknown>> = {
|
|
code: number;
|
|
message: string;
|
|
data: D;
|
|
};
|
|
|
|
export const login = (params: { email: string; password: string }) =>
|
|
request.post<ResponseData<AdminService.LoginData>>(adminLogin, params);
|
|
export const logout = () => request.get<ResponseData<boolean>>(adminLogout);
|
|
export const listUsers = () =>
|
|
request.get<ResponseData<AdminService.ListUsersItem[]>>(adminListUsers, {});
|
|
|
|
export const createUser = (email: string, password: string) =>
|
|
request.post<ResponseData<boolean>>(adminCreateUser, {
|
|
username: email,
|
|
password,
|
|
});
|
|
|
|
export const grantSuperuser = (email: string) =>
|
|
request.put<ResponseData<void>>(api.adminSetSuperuser(email));
|
|
|
|
export const revokeSuperuser = (email: string) =>
|
|
request.delete<ResponseData<void>>(api.adminSetSuperuser(email));
|
|
|
|
export const getUserDetails = (email: string) =>
|
|
request.get<ResponseData<[AdminService.UserDetail]>>(
|
|
adminGetUserDetails(email),
|
|
);
|
|
export const listUserDatasets = (email: string) =>
|
|
request.get<ResponseData<AdminService.ListUserDatasetItem[]>>(
|
|
adminListUserDatasets(email),
|
|
);
|
|
export const listUserAgents = (email: string) =>
|
|
request.get<ResponseData<AdminService.ListUserAgentItem[]>>(
|
|
adminListUserAgents(email),
|
|
);
|
|
export const updateUserStatus = (email: string, status: 'on' | 'off') =>
|
|
request.put(adminUpdateUserStatus(email), { activate_status: status });
|
|
export const updateUserPassword = (email: string, password: string) =>
|
|
request.put(adminUpdateUserPassword(email), { new_password: password });
|
|
export const deleteUser = (email: string) =>
|
|
request.delete(adminDeleteUser(email));
|
|
|
|
export const listServices = () =>
|
|
request.get<ResponseData<AdminService.ListServicesItem[]>>(adminListServices);
|
|
export const showServiceDetails = (serviceId: number) =>
|
|
request.get<ResponseData<AdminService.ServiceDetail>>(
|
|
adminShowServiceDetails(String(serviceId)),
|
|
);
|
|
|
|
export const createRole = (params: {
|
|
roleName: string;
|
|
description?: string;
|
|
}) =>
|
|
request.post<ResponseData<AdminService.RoleDetail>>(adminCreateRole, params);
|
|
export const updateRoleDescription = (role: string, description: string) =>
|
|
request.put<ResponseData<AdminService.RoleDetail>>(
|
|
adminUpdateRoleDescription(role),
|
|
{ description },
|
|
);
|
|
export const deleteRole = (role: string) =>
|
|
request.delete<ResponseData<ResponseData<never>>>(adminDeleteRole(role));
|
|
export const listRoles = () =>
|
|
request.get<
|
|
ResponseData<{ roles: AdminService.ListRoleItem[]; total: number }>
|
|
>(adminListRoles);
|
|
export const listRolesWithPermission = () =>
|
|
request.get<
|
|
ResponseData<{
|
|
roles: AdminService.ListRoleItemWithPermission[];
|
|
total: number;
|
|
}>
|
|
>(adminListRolesWithPermission);
|
|
export const getRolePermissions = (role: string) =>
|
|
request.get<ResponseData<AdminService.RoleDetailWithPermission>>(
|
|
adminGetRolePermissions(role),
|
|
);
|
|
export const assignRolePermissions = (
|
|
role: string,
|
|
permissions: Partial<AdminService.AssignRolePermissionsInput>,
|
|
) =>
|
|
request.post<ResponseData<never>>(adminAssignRolePermissions(role), {
|
|
new_permissions: permissions,
|
|
});
|
|
export const revokeRolePermissions = (
|
|
role: string,
|
|
permissions: Partial<AdminService.RevokeRolePermissionInput>,
|
|
) =>
|
|
request.delete<ResponseData<never>>(adminRevokeRolePermissions(role), {
|
|
data: { revoke_permissions: permissions },
|
|
});
|
|
|
|
export const updateUserRole = (username: string, role: string) =>
|
|
request.put<ResponseData<never>>(adminUpdateUserRole(username), {
|
|
role_name: role,
|
|
});
|
|
export const getUserPermissions = (username: string) =>
|
|
request.get<ResponseData<AdminService.UserDetailWithPermission>>(
|
|
adminGetUserPermissions(username),
|
|
);
|
|
export const listResources = () =>
|
|
request.get<ResponseData<AdminService.ResourceType>>(adminListResources);
|
|
|
|
export const listWhitelist = () =>
|
|
request.get<
|
|
ResponseData<{
|
|
total: number;
|
|
white_list: AdminService.ListWhitelistItem[];
|
|
}>
|
|
>(adminListWhitelist);
|
|
|
|
export const createWhitelistEntry = (email: string) =>
|
|
request.post<ResponseData<never>>(adminCreateWhitelistEntry, { email });
|
|
|
|
export const updateWhitelistEntry = (id: number, email: string) =>
|
|
request.put<ResponseData<never>>(adminUpdateWhitelistEntry(id), { email });
|
|
|
|
export const deleteWhitelistEntry = (email: string) =>
|
|
request.delete<ResponseData<never>>(adminDeleteWhitelistEntry(email));
|
|
|
|
export const importWhitelistFromExcel = (file: File) => {
|
|
const fd = new FormData();
|
|
|
|
fd.append('file', file);
|
|
|
|
return request.post<ResponseData<never>>(adminImportWhitelist, fd);
|
|
};
|
|
|
|
export const getSystemVersion = () =>
|
|
request.get<ResponseData<{ version: string }>>(adminGetSystemVersion);
|
|
|
|
// Sandbox settings APIs
|
|
export const listSandboxProviders = () =>
|
|
request.get<ResponseData<AdminService.SandboxProvider[]>>(
|
|
adminListSandboxProviders,
|
|
);
|
|
|
|
export const getSandboxProviderSchema = (providerId: string) =>
|
|
request.get<ResponseData<Record<string, AdminService.SandboxConfigField>>>(
|
|
adminGetSandboxProviderSchema(providerId),
|
|
);
|
|
|
|
export const getSandboxConfig = () =>
|
|
request.get<ResponseData<AdminService.SandboxConfig>>(adminGetSandboxConfig);
|
|
|
|
export const setSandboxConfig = (params: {
|
|
providerType: string;
|
|
config: Record<string, unknown>;
|
|
}) =>
|
|
request.post<ResponseData<AdminService.SandboxConfig>>(
|
|
adminSetSandboxConfig,
|
|
{
|
|
provider_type: params.providerType,
|
|
config: params.config,
|
|
},
|
|
);
|
|
|
|
export const testSandboxConnection = (params: {
|
|
providerType: string;
|
|
config: Record<string, unknown>;
|
|
}) =>
|
|
request.post<
|
|
ResponseData<{
|
|
success: boolean;
|
|
message: string;
|
|
details?: {
|
|
exit_code: number;
|
|
execution_time: number;
|
|
stdout: string;
|
|
stderr: string;
|
|
};
|
|
}>
|
|
>(adminTestSandboxConnection, {
|
|
provider_type: params.providerType,
|
|
config: params.config,
|
|
});
|