Onyx Sandbox 容器鏡像全解析構(gòu)建、部署與運(yùn)行時(shí)內(nèi)幕【免費(fèi)下載鏈接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM項(xiàng)目地址: https://gitcode.com/GitHub_Trending/da/danswer本文聚焦 Onyx原 DanswerCraft 功能的沙箱容器鏡像Sandbox Container Image以backend/onyx/server/features/build/sandbox/image/目錄為核心系統(tǒng)講解鏡像的構(gòu)建方式CI 與本地兩種路徑、應(yīng)用版本對(duì)齊的部署策略、鏡像內(nèi)預(yù)置的全部組件Next.js 模板、Python venv、OpenCode CLI、快照守護(hù)進(jìn)程等、會(huì)話運(yùn)行時(shí)目錄結(jié)構(gòu)并結(jié)合 Dockerfile、entrypoint、防火墻初始化腳本與 sidecar 守護(hù)進(jìn)程源碼深入揭示鏡像內(nèi)部的啟動(dòng)流程、出口網(wǎng)絡(luò)封鎖與快照持久化機(jī)制。讀完本文你將具備獨(dú)立構(gòu)建、發(fā)布、排查 Onyx 沙箱鏡像的完整能力。一、鏡像在 Onyx 架構(gòu)中的位置Onyx 的 Craft 功能為每個(gè)用戶提供一個(gè)隔離的沙箱環(huán)境用于運(yùn)行 OpenCode 編碼 AgentAgent 在其中構(gòu)建 Web 應(yīng)用、執(zhí)行 Python 代碼并訪問(wèn)知識(shí)庫(kù)文件。這些沙箱的運(yùn)行載體Kubernetes Pod 或 Docker 容器完全由本目錄產(chǎn)出的容器鏡像承載。Kubernetes 模式下每個(gè)用戶一個(gè) Pod由api_server通過(guò) Kubernetes API 驅(qū)動(dòng) Pod 生命周期與kubectl exec見(jiàn) kubernetes_sandbox_manager.pyDocker 模式下api_server掛載/var/run/docker.sock調(diào)用 Docker Engine API見(jiàn) docker_sandbox_manager.py。兩種后端共享同一份鏡像其源碼與構(gòu)建產(chǎn)物全部位于 backend/onyx/server/features/build/sandbox/image。二、鏡像目錄結(jié)構(gòu)速覽image/ ├── Dockerfile # 主容器鏡像定義多階段構(gòu)建 ├── .dockerignore # 裁剪構(gòu)建上下文 ├── entrypoint.sh # 容器啟動(dòng)腳本opencode serve 重啟循環(huán) ├── sidecar-entrypoint.sh # sidecar 守護(hù)進(jìn)程啟動(dòng)腳本 ├── firewall-init.sh # 出口防火墻 CA 信任初始化腳本 ├── browser-cli.sh # agent-browser 的 PATH 包裝器 ├── sandbox_daemon/ # 沙箱內(nèi) push/快照守護(hù)進(jìn)程烘焙進(jìn)鏡像 ├── opencode-plugins/ # 按會(huì)話打出口代理標(biāo)簽的插件烘焙進(jìn)鏡像 ├── templates/ │ └── outputs/ # Web 應(yīng)用腳手架模板Next.js ├── initial-requirements.in # 沙箱預(yù)裝 Python 包清單 └── initial-requirements.txt # 全量鎖定的 Python 依賴一個(gè)容易被忽視的設(shè)計(jì)原則內(nèi)置技能skills并不在鏡像中。它們存放在 backend/onyx/skills/builtin 目錄由 API Server 在會(huì)話建立時(shí)推送到沙箱絕不會(huì)被烘焙進(jìn)鏡像。鏡像只預(yù)裝技能運(yùn)行所需的運(yùn)行時(shí)工具LibreOffice、poppler、字體等。三、構(gòu)建鏡像CI 優(yōu)先本地兜底3.1 通過(guò) CI 發(fā)布推薦路徑應(yīng)用發(fā)布流水線會(huì)將沙箱鏡像與應(yīng)用鏡像打上相同標(biāo)簽例如應(yīng)用 tagv4.1.2對(duì)應(yīng)onyxdotapp/sandbox:v4.1.2。CI 的工作機(jī)制如下.github/workflows/deployment.yml中的沙箱任務(wù)以本目錄內(nèi)容計(jì)算一個(gè)內(nèi)容標(biāo)簽ctx-hash若ctx-hash已存在部署流水線只為既有 manifest 追加應(yīng)用 tag/別名不重復(fù)構(gòu)建若不存在則做一次多架構(gòu)構(gòu)建并推送ctx-hash隨后再補(bǔ)加應(yīng)用對(duì)齊標(biāo)簽。該工作流僅在需要回填或修復(fù)某個(gè)應(yīng)用 tag時(shí)手動(dòng)觸發(fā)。不要為新建構(gòu)建發(fā)布v0.1.x這類僅沙箱的 tag也不要發(fā)布 Docker Hub 的onyxdotapp/sandbox:devtag本地開發(fā)仍可構(gòu)建onyxdotapp/sandbox:dev并直接加載進(jìn) kind 集群。3.2 本地構(gòu)建集群運(yùn)行在 x86_64 節(jié)點(diǎn)上因此沙箱鏡像必須構(gòu)建為 amd64 架構(gòu)。僅構(gòu)建 amd64最快cd backend/onyx/server/features/build/sandbox/image docker build --platform linux/amd64 -t onyxdotapp/sandbox:dev .回填或修復(fù)時(shí)的多架構(gòu)構(gòu)建docker buildx build --platform linux/amd64,linux/arm64 \ -t onyxdotapp/sandbox:app-tag \ --push .3.3 構(gòu)建參數(shù)Build ARG與關(guān)鍵取舍從 Dockerfile 可以看到鏡像構(gòu)建是高度參數(shù)化的多階段構(gòu)建構(gòu)建參數(shù)默認(rèn)值說(shuō)明BASE_IMAGE_REGISTRYdocker.io基礎(chǔ)鏡像倉(cāng)庫(kù)前綴CI 會(huì)覆蓋為 ECR pull-through 緩存以避免 Docker Hub 限流ENABLE_SKILLStrue置為false可跳過(guò)技能運(yùn)行時(shí)依賴LibreOffice、poppler、字體、pptxgenjs省約 700 MBENABLE_BROWSERtrue是否打入 Chromium 引擎與agent-browserCLIOPENCODE_VERSION1.18.19OpenCode CLI 版本AGENT_BROWSER_VERSION0.31.1agent-browser CLI 版本NPM_VERSION11.17.0Node 鏡像階段內(nèi)升級(jí)的 npm 版本GH_CLI_VERSION2.94.0GitHub CLI 版本獨(dú)立階段下載并用 sha256 校驗(yàn)和驗(yàn)證值得注意的源碼細(xì)節(jié)基礎(chǔ)鏡像最終鏡像基于python:3.13-slimDebian 系Node.js 24 從node:24-trixie-slim階段拷貝二進(jìn)制bun 則從oven/bun:1.3.14階段拷貝。npm 符號(hào)鏈接由于只拷貝了node與node_modules需要手動(dòng)建立npm、npx、corepack的符號(hào)鏈接。Chromium 獨(dú)立分層大的、少變的 Chromium 引擎單獨(dú)一層后續(xù)僅升級(jí)AGENT_BROWSER_VERSION時(shí)只重拉小體積 CLI 層。不要執(zhí)行agent-browser install它會(huì)抓取 Chrome-for-Testing無(wú) arm64 構(gòu)建鏡像改用系統(tǒng) Chromium 并通過(guò)AGENT_BROWSER_EXECUTABLE_PATH指定。uid/gid 1000 歸一化構(gòu)建腳本會(huì)把基礎(chǔ)鏡像中已有 uid/gid 1000 的用戶重命名為sandbox保證非 root 運(yùn)行身份統(tǒng)一。Bun 緩存預(yù)熱構(gòu)建期在/workspace/templates/outputs/web執(zhí)行bun install --frozen-lockfile后刪除node_modules從而預(yù)暖 Bun 的 tarball 緩存使每次會(huì)話啟動(dòng)的安裝命中本地存儲(chǔ)。四、部署新版本鏡像與應(yīng)用版本對(duì)齊部署匹配的應(yīng)用 tag 即可部署面會(huì)自動(dòng)從應(yīng)用版本推導(dǎo)沙箱鏡像Docker composeonyxdotapp/sandbox:${IMAGE_TAG}遵循普通應(yīng)用鏡像的IMAGE_TAG行為含默認(rèn)latestHelmonyxdotapp/sandbox:${global.version}。Kubernetes 部署應(yīng)優(yōu)先使用不可變的應(yīng)用發(fā)布 tag除非刻意選擇移動(dòng) tagmoving tags。SANDBOX_CONTAINER_IMAGE是內(nèi)部逃生艙口僅供本地測(cè)試、staging、云端及應(yīng)急操作使用。其默認(rèn)值定義在 configs.pySANDBOX_CONTAINER_IMAGE ( os.environ.get(SANDBOX_CONTAINER_IMAGE, ).strip() or onyxdotapp/sandbox:latest )五、鏡像內(nèi)烘焙了什么鏡像預(yù)置內(nèi)容與文檔一致且均能在 Dockerfile 中逐一找到證據(jù)組件位置說(shuō)明基礎(chǔ)系統(tǒng)python:3.13-slimDebian 系Node.js 24 從node:24-trixie-slim拷貝Web 模板/workspace/templates/outputs/Next.js 應(yīng)用腳手架COPY --exclude.next --excludenode_modules拷貝Python venv/workspace/.venv/由initial-requirements.txt全量鎖定并--only-binary:all:安裝OpenCode CLI/home/sandbox/.opencode/bin/以 sandbox 用戶身份安裝指定版本、--no-modify-pathonyx-cli/usr/local/bin/onyx-cliOnyx CLI用于搜索快照 sidecar 守護(hù)進(jìn)程/workspace/sandbox_daemon/與/opt/sandbox_daemon/打包/恢復(fù)會(huì)話文件持久化由 api_server 經(jīng) Onyx FileStore 負(fù)責(zé)出口標(biāo)簽插件/workspace/opencode-plugins/按會(huì)話打代理標(biāo)簽瀏覽器封裝/usr/local/bin/browseragent-browser 包裝器見(jiàn)下文鏡像內(nèi)不烘焙技能API Server 在會(huì)話建立時(shí)把技能推送到/workspace/managed/skills/。5.1 Python 依賴清單initial-requirements.in是精選清單initial-requirements.txt是其全量鎖定版本。前者內(nèi)容如下cryptography defusedxml fastapi lxml matplotlib matplotlib-inline numpy onyx-cli openpyxl pandas pdfplumber pillow pydantic python-docx python-pptx requests uvicorn[standard]覆蓋數(shù)據(jù)處理pandas/numpy/matplotlib、文檔解析pdfplumber/python-docx/python-pptx/openpyxl、HTTPrequests與 Web 服務(wù)fastapi/uvicorn等場(chǎng)景。5.2 鏡像暴露的端口與入口Dockerfile 末尾暴露三個(gè)端口并指定入口# 3000: Next.js dev server, 4096: opencode serve, 8731: push daemon EXPOSE 3000 4096 8731 ENTRYPOINT [/workspace/entrypoint.sh]3000Next.js 開發(fā)服務(wù)器4096OpenCode 服務(wù)8731push 守護(hù)進(jìn)程端口見(jiàn) contract.py。六、運(yùn)行時(shí)目錄結(jié)構(gòu)一次會(huì)話如何鋪開創(chuàng)建會(huì)話時(shí)Pod 內(nèi)會(huì)搭建如下結(jié)構(gòu)/workspace/ ├── managed/skills/ # 會(huì)話建立時(shí)推送內(nèi)置 自定義技能 ├── opencode-data/ # Kubernetes 下的沙箱級(jí)全局 opencode 數(shù)據(jù) ├── templates/ # 烘焙進(jìn)鏡像 └── sessions/ └── $session_id/ ├── .opencode/ │ └── skills # 符號(hào)鏈接 → /workspace/managed/skills ├── outputs/ # 從模板拷貝內(nèi)含 Web 應(yīng)用 ├── attachments/ # 用戶上傳文件 ├── AGENTS.md # 給 AI Agent 的指令 └── opencode.json # OpenCode 配置關(guān)鍵設(shè)計(jì)點(diǎn)技能通過(guò)符號(hào)鏈接暴露給每個(gè)會(huì)話避免重復(fù)拷貝outputs/從烘焙的模板拷貝保證每個(gè)會(huì)話有干凈的初始工程AGENTS.md由 util/agent_instructions.py 基于AGENTS.template.md動(dòng)態(tài)填充opencode.json由 util/opencode_config.py 動(dòng)態(tài)生成含 MCP 支持與工具權(quán)限。七、啟動(dòng)鏈路源碼剖析7.1 entrypoint.shopencode serve 重啟循環(huán)entrypoint.sh 是容器主進(jìn)程職責(zé)包括opencode 歷史恢復(fù)根據(jù)OPENCODE_DATA_HOMEKubernetes 下由 sidecar 恢復(fù)后指向沙箱級(jí)共享卷設(shè)置XDG_DATA_HOME放寬 bash 工具超時(shí)OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS默認(rèn) 180000ms180s避免圖片生成等合法慢工具被 opencode 120s 默認(rèn)超時(shí)掐斷代理 CA 導(dǎo)入通過(guò)certutil把出口代理的 MITM CA 逐條導(dǎo)入 Chromium 的 NSS 數(shù)據(jù)庫(kù)保證瀏覽器 HTTPS 可用失敗不阻塞啟動(dòng)重啟循環(huán)opencode serve --hostname 0.0.0.0 --port 4096 --print-logs崩潰后按指數(shù)退避1s → 最大 30s自動(dòng)重啟并妥善處理 SIGTERM/SIGINT 信號(hào)。7.2 firewall-init.sh出口網(wǎng)絡(luò)封鎖與 CA 信任firewall-init.sh 是沙箱安全的關(guān)鍵支持兩種引導(dǎo)模式initcontainerK8s initContainer執(zhí)行完步驟后退出 0entrypointdocker-compose 入口執(zhí)行完步驟后用setpriv降權(quán)到 UID 1000 再 exec 真正的入口。它完成三步安裝代理 CA把SANDBOX_PROXY_CA_BUNDLE_SRC默認(rèn)/sandbox-ca/ca.crt裝入系統(tǒng)信任庫(kù)并生成SANDBOX_PROXY_CA_BUNDLE_DST默認(rèn)/etc/ssl/sandbox/ca-bundle.crtiptables 出口封鎖清空 OUTPUT 鏈、默認(rèn)策略DROP僅放行l(wèi)o、已建立的 conntrack 連接以及到SANDBOX_PROXY_HOST:SANDBOX_PROXY_PORT的 TCPIPv6 同步全封鎖部分封鎖即安全回歸自校驗(yàn)檢查 OUTPUT 鏈默認(rèn)策略確為DROP、存在代理放行規(guī)則與 conntrack 規(guī)則失敗即退出。entrypoint模式下還修復(fù)了 Docker 卷掛載點(diǎn)/workspace/sessions的屬主chown 1000:1000并用setpriv --bounding-set-all清除能力邊界集后降權(quán)。注意它顯式設(shè)置HOME/home/sandbox USERsandbox——setpriv 不會(huì)刷新環(huán)境變量繼承HOME/root會(huì)導(dǎo)致降權(quán)后的 Agent 因/root/.cache的 EACCES 而啟動(dòng)失敗。7.3 sidecar 守護(hù)進(jìn)程簽名保護(hù)的 push 與快照sidecar-entrypoint.sh 以無(wú)限重啟循環(huán)方式運(yùn)行/workspace/.venv/bin/python -m sandbox_daemon.server。其核心實(shí)現(xiàn)位于 server.py是一個(gè) FastAPI 服務(wù)提供文件系統(tǒng)列舉/filesystem/list帶路徑穿越防護(hù)輸出 manifest/outputs/manifestpush/push流式接收 tar.gz 并校驗(yàn) SHA-256 與大小上限后安全解包、原子替換快照創(chuàng)建/恢復(fù)/snapshot/create無(wú)內(nèi)容時(shí)返回 204與/snapshot/restoreopencode 歷史創(chuàng)建、恢復(fù)、標(biāo)記恢復(fù)三組端點(diǎn)。所有寫操作都要求X-Push-Signature與X-Push-Timestamp頭使用 Ed25519 公鑰來(lái)自環(huán)境變量注入僅 sidecar 持有驗(yàn)證{timestamp}|{path}|{sha256}簽名并檢查 60 秒時(shí)間戳漂移防止未授權(quán)的數(shù)據(jù)寫入。7.4 browser 包裝器與會(huì)話標(biāo)簽插件browser-cli.sh 把a(bǔ)gent-browser包裝成 PATH 上的browser可執(zhí)行文件剝除代理 URL 中的用戶信息代理按源 IP 授權(quán)、自動(dòng)追加--no-sandbox --proxy-server... --proxy-bypass-list127.0.0.1;localhost等參數(shù)并把當(dāng)前會(huì)話 ID從 cwd 的/sessions/uuid解析傳給agent-browser --session讓瀏覽器實(shí)例與會(huì)話一一對(duì)應(yīng)。opencode-plugins/session-proxy-tag.ts 是 OpenCode 插件在會(huì)話初始化時(shí)從?directory捕獲會(huì)話 ID將其編碼進(jìn)HTTP(S)_PROXY的 userinfo形如https://session-id:xproxy使出口代理能把審批卡片精確路由到對(duì)應(yīng)會(huì)話。HTTPS 下該信息隨 CONNECT 的 Proxy-Authorization 傳遞hop-by-hop不會(huì)到達(dá)源站。該插件路徑與 kubernetes_sandbox_manager.py 中的_OPENCODE_SESSION_TAG_PLUGIN_PATH /workspace/opencode-plugins/session-proxy-tag.ts嚴(yán)格對(duì)應(yīng)。八、會(huì)話啟動(dòng)后的完整時(shí)序綜合上述腳本一次沙箱會(huì)話的啟動(dòng)鏈路為Pod/容器創(chuàng)建K8s 下先運(yùn)行 initContainerfirewall-init 的initcontainer模式完成 CA 安裝、iptables 封鎖與自校驗(yàn)compose 下由 entrypoint 模式完成同樣步驟后setpriv降權(quán)sidecar 啟動(dòng)K8s原生可重啟 init sidecar 運(yùn)行sandbox_daemon.server恢復(fù) opencode 歷史并等待 API Server 就緒探測(cè)主進(jìn)程啟動(dòng)entrypoint.sh導(dǎo)入代理 CA 到 Chromium NSS 后循環(huán)拉起opencode serve端口 4096會(huì)話鋪開API Server 推送技能到/workspace/managed/skills/、從模板拷貝outputs/、掛載附件并注入AGENTS.md與opencode.jsonWeb 預(yù)覽Agent 在會(huì)話目錄執(zhí)行bun install --frozen-lockfile命中鏡像預(yù)暖緩存bun run devNext.js 開發(fā)服務(wù)器監(jiān)聽(tīng) 3000 端口經(jīng) Service/DNS 或橋接網(wǎng)絡(luò)代理對(duì)外提供預(yù)覽快照與恢復(fù)sidecar 經(jīng)簽名 API 打包/恢復(fù)會(huì)話文件持久化由 api_server 通過(guò) Onyx FileStore 完成沙箱與 sidecar 均不持有存儲(chǔ)憑據(jù)。九、故障排查速查9.1 驗(yàn)證鏡像是否存在于 Docker Hubcurl -s https://hub.docker.com/v2/repositories/onyxdotapp/sandbox/tags | jq .results[].name9.2 查看 Pod 實(shí)際使用的鏡像kubectl get pod pod-name -n onyx-sandboxes -o jsonpath{.spec.containers[?(.namesandbox)].image}9.3 常見(jiàn)故障與排查要點(diǎn)癥狀排查要點(diǎn)Pod 停滯在PROVISIONINGK8skubectl logs -n onyx-sandboxes sandbox-{id}查主容器、-c sidecar查 sidecar 日志核對(duì)代理 host/CA 配置與 ServiceAccount 是否存在容器停滯在PROVISIONINGDockerapi_server是否掛載了/var/run/docker.sockonyx_craft_sandbox橋接網(wǎng)絡(luò)是否存在docker logs sandbox-id8確認(rèn)ONYX_SERVER_URL在橋接網(wǎng)絡(luò)內(nèi)可達(dá)且含 API 路徑前綴Next.js 預(yù)覽打不開查容器日志確認(rèn)bun install成功kubectl exec ... -- ls /workspace/outputs/web確認(rèn)模板已拷貝瀏覽器 HTTPS 異常確認(rèn)代理 CA 已導(dǎo)入 Chromium NSSentrypoint 啟動(dòng)日志會(huì)打印導(dǎo)入結(jié)果十、安全設(shè)計(jì)小結(jié)從鏡像構(gòu)建到運(yùn)行時(shí)安全貫穿始終沙箱容器以u(píng)id/gid 1000 非 root運(yùn)行K8s 下使用受限 security contextDocker 下--security-opt no-new-privileges、--cap-drop ALL并通過(guò)setpriv --bounding-set-all清空能力集出口網(wǎng)絡(luò)強(qiáng)制走代理iptables 默認(rèn)丟棄所有 OUTPUT僅放行代理端點(diǎn)瀏覽器/CLI 的流量全部經(jīng)由 egress proxy 審計(jì)與路由沙箱與 sidecar 均不持有 FileStore/S3/MinIO 憑據(jù)快照數(shù)據(jù)經(jīng)簽名 API 流式傳給 api_server 持久化并按租戶隔離存儲(chǔ)路徑寫路徑全部要求Ed25519 簽名 時(shí)間戳防重放 SHA-256 完整性校驗(yàn)Docker 模式下沙箱僅加入專用onyx_craft_sandbox橋接網(wǎng)絡(luò)compose 的 postgres/redis/minio/模型服務(wù)對(duì)沙箱不可達(dá)EC2 上的 IMDS169.254.169.254需在宿主機(jī)強(qiáng)制 IMDSv2 或加DOCKER-USERiptables 規(guī)則阻斷安裝器不會(huì)自動(dòng)處理應(yīng)用層無(wú)兜底。十一、相關(guān)資源沙箱系統(tǒng)總覽架構(gòu)、環(huán)境變量、K8s/Docker 映射sandbox/README.md鏡像定義image/Dockerfile配置項(xiàng)與默認(rèn)值build/configs.py內(nèi)置技能會(huì)話建立時(shí)推送不入鏡像backend/onyx/skills/builtin沙箱配置與解析的單元測(cè)試test_sandbox_backend_parsing.py、test_docker_manager_config.pyHelm 沙箱相關(guān)測(cè)試test_pod_spec.py、test_sandbox_image_prepuller.py【免費(fèi)下載鏈接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM項(xiàng)目地址: https://gitcode.com/GitHub_Trending/da/danswer創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考