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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Senparc.Xncf.Sandbox" Version="0.4.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Senparc.Xncf.Sandbox" Version="0.4.3" />
                    
Directory.Packages.props
<PackageReference Include="Senparc.Xncf.Sandbox" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Senparc.Xncf.Sandbox --version 0.4.3
                    
#r "nuget: Senparc.Xncf.Sandbox, 0.4.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Senparc.Xncf.Sandbox@0.4.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Senparc.Xncf.Sandbox&version=0.4.3
                    
Install as a Cake Addin
#tool nuget:?package=Senparc.Xncf.Sandbox&version=0.4.3
                    
Install as a Cake Tool

Senparc.Xncf.Sandbox

NCF 独立沙箱编排模块:为用户快速创建/销毁隔离实验环境(学习 Python/C#、短任务执行、可选 JupyterLab)。

与 XncfBuilder Preview 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 运行时隔离策略。

后台入口

  1. 环境准备 /Admin/Sandbox/Setup:Docker 检测 + 文档链接
  2. 沙箱面板 /Admin/Sandbox/Index:会话列表 / 打开 Notebook(本机映射端口)/ 销毁运行环境 / 删除会话记录
  3. 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)。

处理(当前库):

  1. 已修复 Domain/Migrations/SqlServer/20240423143154_Init.cs 为 nvarchar(n)
  2. 在 SQL Server 执行(无业务数据可直接删):
IF OBJECT_ID(N'dbo.Senparc_Sandbox_SandboxSession', N'U') IS NOT NULL
    DROP TABLE dbo.Senparc_Sandbox_SandboxSession;
  1. 重新编译后执行:
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
      }
    }
  }
}

细节与推荐镜像清单:环境准备指南

你需要继续做的事

  1. 若尚未处理:清理半成品表并 --database-upgrade(见上一节)
  2. 重启站点(已改 appsettings / 模块代码)
  3. 打开 环境准备:确认 Docker 检测通过,文档链接可打开
  4. Function 创建 python-exec 并 Exec 冒烟 ✅(ExitCode 0)
  5. 下一步可选:A) Wasmtime B) Jupyter 代理/鉴权

版本

  • 0.1.0-preview1:创世骨架
  • 同日补充:环境准备页 + Docs 链接 + 镜像仓库映射配置
Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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、兼容现有资源与默认文案,避免缺少翻译时影响模块加载。