Senparc.Xncf.Sandbox
0.4.3
Prefix Reserved
dotnet add package Senparc.Xncf.Sandbox --version 0.4.3
NuGet\Install-Package Senparc.Xncf.Sandbox -Version 0.4.3
<PackageReference Include="Senparc.Xncf.Sandbox" Version="0.4.3" />
<PackageVersion Include="Senparc.Xncf.Sandbox" Version="0.4.3" />
<PackageReference Include="Senparc.Xncf.Sandbox" />
paket add Senparc.Xncf.Sandbox --version 0.4.3
#r "nuget: Senparc.Xncf.Sandbox, 0.4.3"
#:package Senparc.Xncf.Sandbox@0.4.3
#addin nuget:?package=Senparc.Xncf.Sandbox&version=0.4.3
#tool nuget:?package=Senparc.Xncf.Sandbox&version=0.4.3
Senparc.Xncf.Sandbox
NCF 独立沙箱编排模块:为用户快速创建/销毁隔离实验环境(学习 Python/C#、短任务执行、可选 JupyterLab)。
与
XncfBuilderPreview Host 解耦:Preview 用于模块开发预览(进程级);Sandbox 用于可丢弃实验环境(容器/Wasm)。
官方文档(环境准备以 Docs 为准)
- 中文:https://doc.ncf.pub/zh/NcfPackageSources/xncf/sandbox-environment.html
- English:https://doc.ncf.pub/NcfPackageSources/xncf/sandbox-environment.html
镜像 tag、内部仓库示例、安装命令只维护在 NcfDocs,模块 UI 仅做检测摘要 + 文档链接,避免版本漂移。
源码文档路径:NcfDocs/docs/zh/NcfPackageSources/xncf/sandbox-environment.md(需发布到 doc.ncf.pub 后线上可见)。
状态(2026-08-08)
| 项 | 状态 |
|---|---|
| 模块脚手架 + UID/DB 前缀 | ✅ BDF12490-AA0B-41B4-ADB3-63155ED95A93 / Senparc_Sandbox_ |
| Domain Session + 配额/TTL | ✅ |
| Docker Runtime(CLI) | ✅ 一期 |
| Wasm Runtime | ⏳ Stub |
| Function + Admin 面板 | ✅ |
| 环境准备引导页 | ✅ /Admin/Sandbox/Setup(检测 Docker + 链到 Docs) |
| NcfDocs 环境准备文档 | ✅ 线上文档 |
| 镜像仓库映射配置 | ✅ SenparcXncfSandbox:Images(RegistryPrefix / Overrides) |
| 单元测试(ImageResolver) | ✅ |
| Jupyter 访问 / 反向代理 | ✅ 列表使用容器本机映射端口;仍支持 /sandbox-jupyter/{sessionId}/ 代理 |
| csharp-exec .NET 10 file-based | ✅ sdk:10.0 + dotnet run --file main.cs |
| 持久化 Lab FunctionRender 控制 | ✅ 命令、流式/批量工作区文件上传、下载/列举 |
| Wasmtime 实装 | ⏳ |
架构
Areas / Function (SandboxAppService)
↓
SandboxOrchestrator(配额、TTL、孤儿回收)
↓
ISandboxRuntime
├─ DockerSandboxRuntime
└─ WasmSandboxRuntime (Stub)
↓
IIsolatedRuntimeProvider
└─ DockerIsolatedRuntimeProvider(与 Workspace 共用)
DockerSandboxRuntime 只保留 Sandbox 模板和会话语义;Docker CLI、结构化挂载、端口、环境变量、
网络、CPU/memory/pids、只读根、capabilities、日志、超时、销毁和容器查询由
Senparc.Ncf.IsolatedRuntime 统一实现。Workspace Docker Agent 使用同一个 Provider,
但两者仍保持独立的上层 API 和生命周期。
模板键(协议值,勿本地化)
| Key | 说明 | Create 后是否常驻容器 |
|---|---|---|
python-exec |
短任务 Python | 否(登记会话;Exec 时 docker run --rm) |
csharp-exec |
短任务 C#(.NET 10 file-based:dotnet run --file main.cs) |
否(同上) |
jupyter-python |
JupyterLab 交互(Python;更耗内存) | 是(Destroy / TTL 停容器) |
jupyter-csharp |
JupyterLab 交互(C#;需配置独立镜像) | 是(Destroy / TTL 停容器) |
「销毁」停止并清理运行环境,保留会话记录用于状态追踪;若存在真实容器(Jupyter 或将来的常驻 Exec worker)则一并删除。 「删除会话记录」仅允许用于已停止、已过期或已清理完成的失败会话,并会永久删除数据库记录。
默认镜像(与 Docs 对齐):mcr.microsoft.com/dotnet/sdk:10.0。更新 tag 时优先改 Docs,再同步代码模板。
C# 代码可用顶层语句,例如:Console.WriteLine("hello");(无需手写完整 Program/csproj)。
Exec 容器无外网:自动注入离线 nuget.config + PublishAot=false(避免默认 AOT 去拉 NuGet)。
jupyter-csharp 使用 tools/SandboxImages/JupyterDotnet 构建的独立镜像,内含 .NET SDK、.NET Interactive
Jupyter Kernel 和构建时预热的常用 NuGet 包;镜像构建完成后需通过 Images:Overrides:jupyter-csharp 配置。
安全与资源默认
- Docker 标签:
ncf.sandbox=1,启动扫描孤儿容器 - CPU / memory / pids 限额;Exec 默认无外网
- TTL 强制回收
- 无 Docker 时不降级裸进程
- JupyterLab:BSD-3-Clause(勿用商标背书)
- Jupyter 列表链接使用 Docker 分配的本机映射端口和 token 直达容器;容器只绑定
127.0.0.1 - Jupyter 反向代理仍可通过
/sandbox-jupyter/{sessionId}/lab访问(需管理员登录);该入口由服务端注入 token
持久化 Lab 操作
jupyter-python 和 jupyter-csharp 是持久化交互式会话。Sandbox 的 FunctionRender
提供以下稳定方法,可由 Admin Function、AI Function Calling 和 NeuCharWorkflow 复用:
LabExec:在容器工作区内执行/bin/sh -lc命令,默认 30 秒,最长 120 秒,输出有长度上限;LabUploadFile:使用 Base64 写入工作区内的相对路径,单文件默认最多约 3 MB;LabUploadFiles:接收预先上传的FunctionFileReference[],以流方式批量写入工作区根目录或指定相对目录;默认最多 16 个文件,避免将大文件编码进 Function JSON;LabDownloadFile:读取工作区文件并返回 Base64,读取大小受上限约束;LabListFiles:列举工作区文件,可选择递归和返回数量上限。
FunctionRender 文件参数
对于需要处理大文件或多个文件的 Function,不应把文件内容放入请求 JSON。基础层提供
ParameterType.File、FunctionFileReference 和 IFunctionFileStore:
浏览器 / multipart 客户端
↓ 一次请求上传多个 files
FunctionFileStore(流式落盘、SHA-256、过期校验与按访问清理)
↓
FunctionFileReference.FileId
↓ Function JSON / Workflow / AI Function Calling
Function 执行时通过 IFunctionFileStore.OpenReadAsync() 获取 Stream
文件引用绑定到创建时的 RequestTenantInfo.Id。启用多租户后,上传、查询、读取和删除
都会校验当前请求租户;不同租户即使持有相同的 FileId 也不能读取或删除文件。后台任务
必须通过现有的 IBackgroundTenantScopeFactory 创建租户作用域后再执行文件操作。自定义
IFunctionFileStore 实现也必须保持 FunctionFileReference.TenantId 的隔离语义。
Admin 上传接口为 POST /api/Senparc.Areas.Admin/FunctionFiles/upload,字段名为
files,支持同一 multipart 请求上传多个文件。返回的 FileId 仅是可序列化引用,
不会把 Base64 或二进制内容带入 Workflow、AI schema 或 Function 参数持久化数据。
默认单文件上限为 64 MiB、单批次上限为 256 MiB、保留时间为 2 小时;宿主可通过
FunctionFiles 配置节覆盖这些限制,也可以替换 IFunctionFileStore 为对象存储实现。
旧版 LabUploadFile Base64 接口保留用于兼容小文件调用;新 UI、NeuCharPivot 和
Workflow 文件选择器会先批量上传,再把 FileId 写入 Function 参数。
所有文件操作都拒绝绝对路径、路径穿越和符号链接/重解析点,并且只允许运行中的
Jupyter Lab 会话。python-exec / csharp-exec 仍然是一次性 docker run --rm
任务;ncf-preview 仍然只支持固定的 NCF 预览流程,不开放通用 Shell 控制。
AdminChat 仍需开启 Function Invocation,并将 Sandbox 模块关联到会话;Workflow 则通过已有 Function 目录和统一执行服务调用这些方法。命令执行属于高权限容器内操作, 生产部署应继续结合管理员权限、会话关联和 Docker 运行时隔离策略。
后台入口
- 环境准备
/Admin/Sandbox/Setup:Docker 检测 + 文档链接 - 沙箱面板
/Admin/Sandbox/Index:会话列表 / 打开 Notebook(本机映射端口)/ 销毁运行环境 / 删除会话记录 - Function:创建沙箱 / 列表 / Exec / 销毁运行环境 / 删除会话记录
Jupyter 代理调试
- 中间件:
SandboxJupyterProxyMiddleware(HTTP + WebSocket) - 容器启动参数:
ServerApp.base_url=/sandbox-jupyter/{sessionId}/ - 未登录访问代理路径会跳转
/Admin/Login?returnUrl=... - 应用关闭时不会主动删除交互式容器;应用启动会按 Docker 完整容器 ID 校准运行中、已停止和已删除的会话,并清理无对应会话的孤儿容器
调试信息
- 工作目录:
%TEMP%/Senparc.Ncf/Sandbox/{sessionId} - Orchestrator 每 30s 扫 TTL
故障排查:SQL Server 升级 Init 失败(nvarchar(max) 索引)
若出现:
Column 'SessionId' ... is of a type that is invalid for use as a key column in an index
原因:早期手工改写的 SqlServer Init 把字符串列写成了 nvarchar(max),无法建唯一索引;升级会在建索引时失败,并留下半成品表(Init 通常尚未写入 MigrationsHistory)。
处理(当前库):
- 已修复
Domain/Migrations/SqlServer/20240423143154_Init.cs为nvarchar(n) - 在 SQL Server 执行(无业务数据可直接删):
IF OBJECT_ID(N'dbo.Senparc_Sandbox_SandboxSession', N'U') IS NOT NULL
DROP TABLE dbo.Senparc_Sandbox_SandboxSession;
- 重新编译后执行:
dotnet run -- --database-upgrade
约定:模块已对外发布后,schema 变更请新增 migration,不要再改已成功应用的 Init。本次属于 Init 从未成功应用,故直接修正 Init。
镜像配置(appsettings)
{
"SenparcXncfSandbox": {
"Docker": {
// docker run 在本地没有镜像时会同步下载;默认 900 秒,可按需调整为 60-3600
"InteractiveCreateTimeoutSeconds": 900
},
"Images": {
"RegistryPrefix": "",
"Overrides": {
// 国内网络临时代理示例(第三方地址,稳定性不保证;不是清华 TUNA 官方镜像)
// "jupyter-python": "quay.dockerproxy.net/jupyter/minimal-notebook:latest",
// "jupyter-csharp": "ncf-jupyter-dotnet:10.0"
}
}
},
"SenparcNcf": {
"IsolatedRuntime": {
"Docker": {
"Executable": "docker",
"ProbeTimeoutSeconds": 8
}
}
}
}
细节与推荐镜像清单:环境准备指南
你需要继续做的事
- 若尚未处理:清理半成品表并
--database-upgrade(见上一节) - 重启站点(已改 appsettings / 模块代码)
- 打开 环境准备:确认 Docker 检测通过,文档链接可打开
Function 创建✅(ExitCode 0)python-exec并 Exec 冒烟- 下一步可选:A) Wasmtime B) Jupyter 代理/鉴权
版本
0.1.0-preview1:创世骨架- 同日补充:环境准备页 + Docs 链接 + 镜像仓库映射配置
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- DM.Microsoft.EntityFrameworkCore (>= 8.0.0.28188)
- Microsoft.EntityFrameworkCore.Relational (>= 8.0.10)
- Microsoft.EntityFrameworkCore.SqlServer (>= 8.0.10)
- Microsoft.Extensions.FileProviders.Embedded (>= 10.0.2)
- Npgsql.EntityFrameworkCore.PostgreSQL (>= 8.0.10)
- Oracle.EntityFrameworkCore (>= 8.23.60)
- Pomelo.EntityFrameworkCore.MySql (>= 8.0.2)
- Senparc.CO2NET.WebApi (>= 2.1.9-preview)
- Senparc.Ncf.AreaBase (>= 0.23.11)
- Senparc.Ncf.DatabasePlant (>= 0.21.15)
- Senparc.Ncf.IsolatedRuntime (>= 0.1.0-preview1)
- Senparc.Ncf.Service (>= 0.23.12-preview11)
- Senparc.Xncf.AreasBase (>= 0.13.13)
- Senparc.Xncf.Sandbox.Abstractions (>= 0.3.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.4.3 | 55 | 11/11/2026 |
| 0.4.2 | 94 | 11/5/2026 |
| 0.4.1 | 95 | 11/2/2026 |
| 0.3.4 | 114 | 10/4/2026 |
| 0.3.3 | 122 | 9/18/2026 |
| 0.3.2 | 114 | 9/16/2026 |
| 0.3.1 | 110 | 9/15/2026 |
| 0.3.0 | 143 | 8/29/2026 |
| 0.2.0 | 137 | 8/23/2026 |
| 0.2.0-preview3 | 134 | 8/14/2026 |
| 0.1.1-preview2 | 120 | 8/12/2026 |
| 0.1.0-preview1 | 121 | 8/8/2026 |
v0.1.0-preview1 创世:独立沙箱模块骨架
1、引入 ISandboxRuntime 抽象(Docker + Wasm Stub)
2、Session 生命周期、配额与 TTL 回收
3、Function/Admin 管理入口与 Jupyter/Exec 模板占位
[2026-08-13] v0.1.1-preview2 Dependency update from Senparc.Ncf.AreaBase to 0.23.3-preview7; Senparc.Ncf.DatabasePlant to 0.21.7-preview7
[2026-08-15] v0.2.0 增加 NCF 预览沙箱工作负载
1、增加固定 NCF/XNCF 预览模板、Docker 运行参数、启动超时和受控依赖恢复网络
2、提供隔离预览工作区、状态访问和反向代理链路,未配置固定镜像摘要时安全失败
3、新增 jupyter-csharp 模板与镜像解析,完善 Docker/Wasm 运行参数与会话状态管理
4、优化管理端沙箱会话交互与 Jupyter 路径约束,改善创建/回收体验
5、支持创建与更新会话 TTL,并可选择永久保持(需手动销毁)
6、管理端展示无限 TTL 状态,并提供会话生命周期调整入口
7、增加 Jupyter C# 模板、预览代理和工作区路径约束,完善 Docker/Wasm 运行时配置
8、支持会话 TTL 更新和永久保持状态,管理端提供生命周期调整与回收反馈
[2026-08-29] v0.3.0 支持从全局 NeuCharPivot 受控调用 Sandbox Function
1、新增全局调用入口并复用既有 Function 执行路径,保持模块和参数校验
2、通过显式启用与管理员访问边界限制全局调用,保留原 Sandbox 页面入口
3、统一宿主工作区、会话目录和目标路径的边界校验,避免相邻目录被误判为工作区子路径
[2026-09-15] v0.3.1 补充 Sandbox 数据库迁移并保持工作区边界兼容
1、补充 Sandbox 模块迁移文件,支持当前数据库初始化流程
2、保持工作区文件树和路径边界校验行为稳定
[2026-09-16] v0.3.2 Dependency updates from Senparc.Web to 0.39.1
[2026-09-17] v0.3.3 Dependency updates from Senparc.Ncf.XncfBase to 0.28.0
1、同步受影响的基础库、AI 模块或宿主项目版本
2、保持项目引用链与当前功能兼容
[2026-09-18] v0.3.3 增强 JupyterLab 外部控制与会话管理
1、创建 JupyterLab 容器支持可选附加端口映射(loopback 或外部 0.0.0.0 绑定),容器内 Web 站点可被外部访问
2、新增 创建 Notebook Function:在 Lab 工作区生成 Python / C#(dotnet-interactive).ipynb 文件
3、执行 Lab 命令支持可选标准输入内容(docker exec -i),可向终端程序/REPL 批量提交指令
4、每用户沙箱并发上限由 2 提高到 10(全局上限由 20 提高到 50)
5、会话支持可选别名(创建时设置或随时修改/清除),管理页列表展示别名与附加端口并提供重命名入口
6、新增 SandboxSession.Alias / ExtraPorts 持久化列(含六种数据库迁移),别名与端口记录不随容器销毁清除
[2026-09-18] v0.3.3 增强 JupyterLab 外部控制与会话管理
1、创建 JupyterLab 容器支持可选附加端口映射(loopback 或外部 0.0.0.0 绑定),容器内 Web 站点可被外部访问
2、新增 创建 Notebook Function:在 Lab 工作区生成 Python / C#(dotnet-interactive).ipynb 文件
3、执行 Lab 命令支持可选标准输入内容(docker exec -i),可向终端程序/REPL 批量提交指令
4、每用户沙箱并发上限由 2 提高到 10(全局上限由 20 提高到 50)
5、会话支持可选别名(创建时设置或随时修改/清除),管理页列表展示别名与附加端口并提供重命名入口
6、新增 SandboxSession.Alias / ExtraPorts 持久化列(含六种数据库迁移),别名与端口记录不随容器销毁清除
[2026-10-05] v0.3.4 Merge branch 'Developer-MAF-V3-Spark' of https://github.com/NeuCharFramework/NcfPackageSources into Developer-MAF-V3-Spark
1、Updated Senparc.Xncf.Sandbox project behavior and integration for the latest feature and reliability improvements.
2、feat: enhance Sandbox with external JupyterLab control, port mappings, session alias and raised quota
[2026-10-21] v0.3.5 沙箱创建与 Notebook 缺少模板或语言时不再静默回退到 Python
1、创建请求缺少模板时返回明确错误
2、Notebook 缺少语言时要求明确填写 python 或 csharp
[2026-11-03] v0.4.0 统一 Docker 隔离运行时底层能力
1、DockerSandboxRuntime 改为 IIsolatedRuntimeProvider 业务适配器
2、容器启动、执行、日志、销毁、查询与进程超时由共享 Provider 管理
3、Exec 与 Jupyter 统一应用结构化挂载、资源、网络及 capability 策略
4、支持沙箱批量文件上传和隔离运行时连接
5、按租户恢复沙箱编排上下文并迭代执行后台回收
6、Dependency update from Senparc.Xncf.Sandbox.Abstractions to 0.3.1
[2026-11-03] Reuse shared documentation help and automatically select the current documentation language.
[2026-11-05] v0.4.2 区分沙箱环境准备与会话面板帮助,并统一多语言文案
1、环境准备帮助不再指向会话面板操作说明
2、补齐并校正各语言资源条目,使模块界面文案与中文基准保持一致
3、Dependency update from Senparc.Ncf.AreaBase to 0.23.10
4、Dependency update from Senparc.Ncf.DatabasePlant to 0.21.14
5、Dependency update from Senparc.Ncf.Service to 0.23.11-preview10
6、Dependency update from Senparc.Xncf.AreasBase to 0.13.12
[2026-11-11] v0.4.2 统一模块注册显示名称与说明的多语言资源键
1、Register 通过 XncfRegisterText 用稳定资源键和中文基准文本解析菜单名称与模块说明。
[2026-11-12] v0.4.3 统一模块注册显示名称与说明的多语言资源键
1、模块注册信息优先使用稳定资源键解析多语言显示文本。
2、兼容现有资源与默认文案,避免缺少翻译时影响模块加载。