Onyx Craft 自托管部署实战基于 docker-compose 与 opencode serve 的完整上手指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswerOnyx Craft 是 Onyx 开源的 AI 编程式 Web 应用构建能力本文聚焦于自托管用户最关心的 Docker 后端路径如何在 docker-compose 部署形态下通过opencode serveHTTP 传输AGENT_TRANSPORTserve将 Craft 完整跑起来。读完本文你将掌握从零搭建 Craft 的完整流程、全部关键环境变量与镜像选择逻辑、未发布 PR 的本地镜像构建方法以及部署过程中几乎必然遇到的一线排障经验含 macOS bash 3.2、OpenSearch 磁盘只读、网络缺失、镜像陈旧等十余个真实问题。本文以仓库文档 docs/craft/docker/docker-compose-overview.md 为主体骨架并结合docker-compose.craft.yml、安装脚本与 Docker 沙箱管理器源码进行纵深印证。如果你的部署目标是云环境cloud / kind或 Kubernetes请直接使用 Kubernetes 管理器路径可参考 docs/craft/kubernetes/craft-eks-runbook.md本文的 Docker 后端专为自托管 docker-compose 部署者而存在。一、架构概览为什么 Docker 后端只需要普通镜像在进入部署之前先厘清一个关键事实Onyx 并没有任何 Craft 专属的应用/后端镜像。Craft 的 agentopencode完全运行在独立的沙箱容器内api_server 只是opencode-serve的 HTTP 客户端自身从不执行opencode/node。因此后端镜像无需内置任何 Craft 专属内容ENABLE_CRAFTtrue在运行时被读取即可启用该功能。镜像体系如下表详见 docs/craft/infra/image-architecture.md镜像是否 Craft 专属说明onyxdotapp/onyx-backend否标准镜像运行时以ENABLE_CRAFTtrue启用 Craftonyxdotapp/onyx-web-server否标准镜像onyxdotapp/onyx-model-server否标准镜像onyxdotapp/sandbox是唯一 Craft 专属镜像内置 Node opencodeCLI负责运行 agent沙箱镜像与应用镜像共用同一个 tag应用 tag 为X时onyxdotapp/sandbox:X必须已发布。docker-compose 遵循既有的IMAGE_TAG行为默认latest。由于沙箱容器是由 Docker 管理器而非 compose在运行时创建的管理器遵循不可变 tag 缺失才拉取、可变 tag 每个 API 进程刷新一次的策略对应源码 docker_sandbox_manager.py 中的_ensure_sandbox_image()。docker-compose.craft.yml是叠加在主 compose 之上的覆盖文件。值得注意的安全提示文件头部注释api_server、background与sandbox-proxy都会 bind-mount 宿主机的/var/run/docker.sock等价于宿主机 root 权限因此只应在完全受控的宿主机上运行。二、TL;DR —— 快速开始如果你已经熟悉 Onyx 部署下面是整条捷径文档原文完整保留# 1. Stage compose 文件这些文件尚未进入任何 release tag WT/path/to/onyx/checkout # 本仓库检出在包含 Docker 后端的分支上 mkdir -p ~/onyx_data/deployment ~/onyx_data/data/nginx cp $WT/deployment/docker_compose/docker-compose.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/docker-compose.craft.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/env.template ~/onyx_data/deployment/ cp $WT/deployment/data/nginx/app.conf.template ~/onyx_data/data/nginx/ cp $WT/deployment/data/nginx/run-nginx.sh ~/onyx_data/data/nginx/ # 2. 以 --local 模式运行安装器并带上 craft bash $WT/deployment/docker_compose/install.sh --local --include-craft --dir ~/onyx_data # 3. 修正 .envexisting-env 安装路径会跳过这些参见下文必需环境变量 cat ~/onyx_data/deployment/.env ENV ENABLE_CRAFTtrue SANDBOX_BACKENDdocker HOST_PORT3001 ENV # 4. 如果运行未发布的 PR例如 opencode-serve需要在本地构建后端与 # sandbox 镜像并在 .env 中指向它们。参见下文运行未发布的 PR。 # 5. 启动 (cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml up -d) # 6. 通过 Admin UI 在 http://localhost:3001 配置 LLM provider # 在此之前Craft 会以 No default LLM model found 失败注意以上命令路径~/onyx_data等是文档中的示例部署目录你可以用任何自托管部署目录替代只需保持一致。三、前置条件Docker Desktop、OrbStack 或 Linux 上的 Docker Engine。Craft overlay 在所有平台上都使用私有的onyx-craft-api网桥别名。约 80 GB 可用的 Docker 磁盘空间。Onyx 全栈镜像拉取约 30 GB本地镜像构建再增加 10–15 GB如果不清理构建缓存可膨胀到 40 GB详见下文OpenSearch 进入只读模式一节。一个 LLM API keyAnthropic / OpenAI 等。四、必需环境变量安装完成后以下变量必须出现在~/onyx_data/deployment/.env中变量是否必需说明ENABLE_CRAFTtrue是--include-craft会写入它全新安装与已有.env都适用。SANDBOX_BACKENDdocker是--include-craft会与ENABLE_CRAFT一并写入。ONYX_SERVER_URL可选完整的 API 基础 URL。Craft overlay 默认使用私有沙箱网桥上的http://onyx-craft-api:8080。仅当需要走公共 URL 时才覆盖且要包含其/api路径前缀。HOST_PORT3001仅在 3000 冲突时默认 3000nginx 在宿主机绑定该端口。释放 3000 或在此修改。IMAGE_TAG可选除非设置否则使用 compose 默认值latest。Craft 对沙箱镜像使用同一 tag正常部署不要单独设置沙箱镜像。没有Craft 专属的 app/backend 镜像——Craft 通过ENABLE_CRAFTtrue在运行时启用见 docs/craft/infra/image-architecture.md。ONYX_BACKEND_IMAGE仅在运行未发布 PR 时只覆盖后端镜像而不强制 model-server / web-server 使用同一 tag。AGENT_TRANSPORTserve针对 serve 传输docker-compose.craft.yml默认值为servepost-#11402回滚路径可覆盖为acp。通过环境变量透传到达沙箱容器。ENABLE_OPENCODE_DEBUGGINGtrue可选Craft UI 中面向开发者的 pod 日志查看按钮。默认false。需要特别说明的是OPENCODE_SERVER_PASSWORD、OPENCODE_CONFIG_CONTENT、OPENCODE_SERVE_PORT不是由你设置的——DockerSandboxManager.provision()会在每次供给沙箱时用secrets.token_urlsafe(32)生成密码、生成配置内容并在容器创建时注入其环境变量见 docker_sandbox_manager.py 中build_container_create_kwargs()对OPENCODE_SERVER_PASSWORD与OPENCODE_CONFIG_CONTENT的注入逻辑以及 configs.py 中对OPENCODE_SERVE_PORT默认 4096的定义。环境变量如何真正生效源码级说明SANDBOX_BACKEND的解析configs.py中定义了SandboxBackend枚举KUBERNETES kubernetes、DOCKER docker启动时从环境读取并做小写匹配非法值会抛出ValueError——这就是文档中镜像陈旧报错docker is not a valid SandboxBackend的根源。docker-compose 只透传environment:块中列出的变量.env中的变量只参与 compose 的插值不会自动传播进容器。这正是 pre-#11402 时AGENT_TRANSPORTserve无效的原因修复方式是显式把AGENT_TRANSPORT与ENABLE_OPENCODE_DEBUGGING加入api_server和background服务的environment:透传。ONYX_SERVER_URL的默认值docker-compose.craft.yml中api_server/background服务将其默认设为http://onyx-craft-api:8080对应沙箱网桥上api_server的别名。若将其指向 compose 内部服务名如http://api_server:8080docker_sandbox_manager.py中的_looks_like_internal_compose_host()会发出警告沙箱只加入 Craft 网桥无法解析默认网络上的服务名。docker-compose.craft.yml 中还有哪些固定值除上述变量外overlay 中还固定pinned了几个值不可通过.env覆盖以避免env_file泄漏导致不一致SANDBOX_DOCKER_NETWORKonyx_craft_sandbox必须与 compose 的networks:块及 install.sh 中的字面量一致SANDBOX_DOCKER_SOCKET/var/run/docker.sock容器侧绑定目标OPENCODE_SERVE_PORT4096必须与沙箱镜像 entrypoint.sh 中的硬编码一致见 entrypoint.shSANDBOX_PROXY_HOSTsandbox-proxy、SANDBOX_PROXY_PORT8080代理是强制的显式的空值会在 api_server 启动时抛错对应DockerSandboxManager.__init__中requires SANDBOX_PROXY_HOST的检查此外还提供可调参数SANDBOX_DOCKER_MEMORY_LIMIT默认2g与SANDBOX_DOCKER_CPU_LIMIT默认1.0。这两个默认值与 K8s 沙箱 pod 的requests1 CPU / 2Gi一致而非其 limits2 CPU / 10Gi——因为单机 compose 部署很少有超卖到 10Gi 的余量见 configs.py 中 Docker 沙箱段落的注释。env.template中同样对这些变量做了完整注释见 env.template 的 Craft 配置段落。五、逐步部署详解1. Stage compose 文件安装脚本正常情况下会从最新 GitHub release 下载docker-compose.yml/docker-compose.craft.yml/env.template。但docker-compose.craft.yml目前尚未出现在任何 release tag 中——craft 仅存在于main分支。因此需要先从 checkout 预置WT/path/to/onyx mkdir -p ~/onyx_data/deployment ~/onyx_data/data/nginx cp $WT/deployment/docker_compose/docker-compose.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/docker-compose.craft.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/env.template ~/onyx_data/deployment/ cp $WT/deployment/data/nginx/app.conf.template ~/onyx_data/data/nginx/ cp $WT/deployment/data/nginx/run-nginx.sh ~/onyx_data/data/nginx/2. 运行安装器bash $WT/deployment/docker_compose/install.sh --local --include-craft --dir ~/onyx_data--local跳过下载使用预置文件。--include-craft选择 Docker 沙箱后端。--dir指向预置目录——不传则默认~/.config/onyx。需要注意安装器是交互式的——它只在 stdin 是终端时才提示因此echo 2\n\n | bash这类管道输入不会生效。要么从终端运行要么适配其提示Standard 模式 2保留现有 env 留空。此外--no-prompt会默认进入Lite 模式而 Lite 模式与--include-craft互斥不要组合使用。从仓库中的 install.sh 可以看到安装脚本本身只是一个引导器它下载并校验onyx-cli含 sha256 校验与失败即退出然后把参数原样转发给onyx-cli deploy install。脚本要求保持与 bash 3.2 兼容macOS 默认仍是 3.2.57这正是下文多个 macOS 排障问题的伏笔。3. 修正 .env在已有.env上--include-craft会替你写入ENABLE_CRAFTtrue与SANDBOX_BACKENDdockerupdate 与 restart 两条路径都会写。仅当默认端口不可用时才设置HOST_PORTcat ~/onyx_data/deployment/.env ENV HOST_PORT3001 ENV如果你同时为未发布的 PR 构建了本地镜像还需要追加覆盖变量见下一节。4. 启动整个栈cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml up -dcompose 文件将onyx_craft_sandbox网络声明为external: true。安装器只在全新安装路径上创建它。如果你是在已有安装上以--include-craft升级需要手动创建docker network create onyx_craft_sandbox佐证docker-compose.craft.yml的networks:块将onyx_craft_sandbox声明为external: true并注释Pre-created by install.sh --include-craft同时声明了external: true的命名卷sandbox_proxy_ca供沙箱代理的 MITM CA 持久化之所以用 external 固定 name是为了让DockerSandboxManager在 compose 项目作用域之外供给沙箱容器时也能挂载同一名称的卷。此外overlay 还定义了一个有意思的服务sandbox-image-prepull它以deploy.replicas: 0声明且entrypoint: [/bin/true]其唯一目的是让docker compose pull能提前拉取约 1 GB 的沙箱镜像避免第一次提示时在供给请求内才冷拉。replicas: 0保证up时不会真正创建容器注释明确说明它不是 workload而是一个镜像引用。5. 配置 LLM provider打开 http://localhost:3001登录后进入Admin Panel → Language Models添加一个 providerAnthropic / OpenAI / OpenRouter。在此之前每一个 Craft 提示都会失败报错ValueError: No default LLM model found6. 在 Craft 中尝试一次提示点击侧边栏的Craft发送一条提示。观察 api_server 日志docker logs -f onyx-api_server-1 21 | grep -E SANDBOX-SERVE|SESSION-LIFECYCLE正常应依次看到[SESSION-LIFECYCLE] sandbox.ensure_opencode_session: build_session… directory/workspace/sessions/…[SANDBOX-SERVE] Created PodEventBus for sandbox … dir/workspace/sessions/…[SANDBOX-SERVE] opencode-serve ready for sandbox …[SESSION-LIFECYCLE] _send_message_via_serve: build_session… caller-supplied opencode_session_id…[SANDBOX-SERVE] send_message completed: session… events… got_prompt_responseTrue六、运行未发布的 PR本地镜像构建已发布的edge由main构建。如果你在测试尚未合并的 PR已发布镜像不会包含你的代码必须本地构建受影响的镜像。后端镜像cd /path/to/onyx docker build \ -t onyxdotapp/onyx-backend:craft-prN \ -f backend/Dockerfile \ backend/耗时约 10–20 分钟。Craft 通过ENABLE_CRAFTtrue在运行时启用不存在Craft 专属的后端镜像变体。然后在.env中ONYX_BACKEND_IMAGEonyxdotapp/onyx-backend:craft-prN不要把IMAGE_TAG指向你的 PR 构建——IMAGE_TAG作用于 compose 文件中引用的每一个镜像model-server、web-server 等Docker 会尝试拉取onyxdotapp/onyx-model-server:craft-prN并失败。ONYX_BACKEND_IMAGE是仅针对后端的覆盖。沙箱镜像沙箱容器有自己的镜像但正常部署使用IMAGE_TAG选定的应用对齐沙箱 tag。如果你测试的 PR 包含未发布的沙箱镜像改动可本地构建覆盖镜像。这仅用于 PR 与内部测试不适用于正常客户部署。docker build --networkhost \ -t onyxdotapp/sandbox:prN \ -f backend/onyx/server/features/build/sandbox/image/Dockerfile \ backend/onyx/server/features/build/sandbox/image/--networkhost用于绕过 Docker Desktop 的 HTTP 代理——如果deb.debian.org在 apt-get 期间返回Connection refused构建会以 Unable to locate package python3-venv / Connection refused针对 Debian apt 镜像源失败。然后在.env中SANDBOX_CONTAINER_IMAGEonyxdotapp/sandbox:prN更新.env后强制重建 api_server 与 background 以使其读取新环境cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml \ up -d --no-build --force-recreate api_server background--no-build很重要——不加的话 compose 会尝试构建镜像因为 compose 文件中也有build:指令并因相对路径../../backend在~/onyx_data/deployment下无法解析而失败。七、你将遇到的坑按出现顺序大致排列1. macOS bash 3.2安装脚本以unbound variable中止症状运行curl -fsSL …/install_onyx.sh | bash时/bin/bash: DOCKER_SUDO[]: unbound variable原因macOS 仍自带 bash 3.2.57。在set -u下对空数组arr()做${arr[]}展开会直接报错——即使数组已被显式声明。修复提供一个run_docker()包装函数基于${#DOCKER_SUDO[]} 0分支使数组展开仅在非空时执行见 PR #11424。2. macOS bash 3.2HOST_PORT3000: command not found症状去掉set -u后安装仍失败install.sh: line 371: HOST_PORT3000: command not found原因bash 3.2 的解析器是单趟的——当可能为空的展开位于命令位置${DOCKER_SUDO[]} VARval cmd时解析器在解析期就把VARval归类为位置参数而非环境变量前缀。数组随后展开为 0 个词时VARval被当作命令名解释。bash 4 会在展开后重新求值因此 Linux/CI 永远不会遇到。去掉set -u并不能修复此问题。修复同一个run_docker()包装——调用点变为VARval run_docker $cmd …此时首 token 是函数调用上的字面环境变量前缀解析器满意数组展开位于函数体内、远离命令位置。3. sudo 路径env_reset 剥离内联 VARval未关闭的 P1Greptile 在 PR #11424 上标记了此问题但合入前未解决。当DOCKER_SUDO(sudo)Linux 刚加入 docker 组的路径时run_docker最终调用sudo docker compose。sudo 默认的env_reset会剥离HOST_PORT…/IMAGE_TAG…前缀因为它们经由父进程的环境到达 sudo而非作为位置参数。PR #11424 之前的调用形式是${DOCKER_SUDO[]} VARval cmd它把VARval作为 sudo 的位置参数传递——即便env_reset生效 sudo 也认可。修复尚未发布在run_docker的 sudo 分支内通过显式env重新注入相关变量run_docker() { if [ ${#DOCKER_SUDO[]} -gt 0 ]; then local env_args() [ -n ${HOST_PORT-} ] env_args(HOST_PORT$HOST_PORT) [ -n ${IMAGE_TAG-} ] env_args(IMAGE_TAG$IMAGE_TAG) ${DOCKER_SUDO[]} env ${env_args[]${env_args[]}} $ else $ fi }4. 安装脚本在已有 .env 路径上跳过网络创建症状network onyx_craft_sandbox declared as external, but could not be found ✗ Failed to start Onyx services原因install.sh 的docker network create onyx_craft_sandbox只在全新安装分支if [ ! -f $ENV_FILE ]内执行。脚本检测到已有.env时走 update 路径完全跳过网络创建。修复PR #11402将网络创建块移出全新安装门控使它在--include-craft被设置时总是执行if [ $INCLUDE_CRAFT true ]; then SANDBOX_NET${SANDBOX_DOCKER_NETWORK:-onyx_craft_sandbox} if ! run_docker docker network inspect $SANDBOX_NET /dev/null 21; then run_docker docker network create $SANDBOX_NET /dev/null fi fi修复前的临时方案手动执行docker network create onyx_craft_sandbox。5.docker-compose.craft.yml未透传 AGENT_TRANSPORTpre-#11402症状在.env中设置AGENT_TRANSPORTserve无效果——api_server 容器的环境里没有它。原因docker-compose 只传递服务environment:块中列出的变量。.env中的变量只供 compose插值使用不会自动传播到容器。修复PR #11402在docker-compose.craft.yml的api_server与background服务中显式添加透传environment: - AGENT_TRANSPORT${AGENT_TRANSPORT:-serve} - ENABLE_OPENCODE_DEBUGGING${ENABLE_OPENCODE_DEBUGGING:-false}6. 镜像陈旧已发布 tag 落后于 main症状 Aapi_server 启动即崩溃报ValueError: docker is not a valid SandboxBackend。原因你用的 release 镜像早于 Docker 沙箱后端PR #112225 月 20 日——其SandboxBackend枚举只有LOCAL/KUBERNETES。修复使用足够新的镜像 tagIMAGE_TAGlatest症状 Bedge对 Docker 后端可用但缺少 PR #11402 的 serve 传输新增。ensure_opencode_session()返回None因为 base.py 的桩从未被DockerSandboxManager覆盖已发布镜像未实现_serve_base_url/_read_opencode_password。修复本地构建后端镜像见上文运行未发布的 PR。症状 Copencode-serve never became ready for sandbox … after 30s (last error: ConnectError: [Errno 111] Connection refused)。原因应用镜像与沙箱镜像来自不同源版本或你测试未发布的沙箱镜像改动却没有匹配的本地沙箱镜像。修复部署匹配的 app/sandbox tag或同样本地构建沙箱镜像。7.IMAGE_TAG作用于每一个镜像症状设置IMAGE_TAGcraft-prN后拉取失败报No such image: onyxdotapp/onyx-model-server:craft-prN。原因compose 文件中所有服务的image:行都引用IMAGE_TAG并非只有后端。修复使用ONYX_BACKEND_IMAGE只覆盖后端镜像。8.compose up --force-recreate触发了构建症状镜像 tag 指向仅本地存在的 tag 时报unable to prepare context: path /path/to/Desktop/backend not found。原因image:查找无法从 registry 拉取时compose 回退到 compose 文件中的build:指令。构建上下文../../backend相对 compose 文件目录解析在~/onyx_data/deployment下无法解析。修复给docker compose up传--no-build。9.compose down/up遗留孤儿容器症状Conflict. The container name /onyx-cache-1 is already in use by container …——即使down报告已移除。原因之前的up --force-recreate与不完整构建交错使命名容器处于不一致状态。修复docker compose -f docker-compose.yml -f docker-compose.craft.yml down docker compose -f docker-compose.yml -f docker-compose.craft.yml up -d --no-build10. OpenSearch 进入只读模式磁盘满症状api_server 崩溃报TransportError(429, cluster_block_exception, index [danswer_chunk_…] blocked by: [TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark, index has read-only-allow-delete block];)原因Docker Desktop 的虚拟磁盘达到 95% 的 flood-stage 水位。macOS 上 Docker VM 使用固定大小磁盘镜像拉取 构建会消耗它。OpenSearch 看到的是 VM 磁盘而非宿主机磁盘。修复docker builder prune -af # 构建缓存常达 40 GB docker image prune -af --filter until24h释放足够空间后磁盘低于低水位时 OpenSearch 会自动解除阻塞。重启 api_server 重试。11. 端口 3000 已被占用症状nginx 绑定失败bind: address already in use。原因另一个进程常见的是 Node 开发服务器占用了 3000 端口。修复lsof -nP -iTCP:3000 -sTCP:LISTEN # 找到 PID # 要么杀掉它要么 echo HOST_PORT3001 ~/onyx_data/deployment/.env # 然后启动栈通过 http://localhost:3001 访问12. 沙箱镜像 apt 构建失败症状W: Failed to fetch http://deb.debian.org/debian/dists/bookworm/InRelease Could not connect to deb.debian.org:80 … (111: Connection refused) E: Unable to locate package python3-venv原因Docker Desktop 有时将 buildkit 的出站 HTTP 路由到不可达或异常的代理http.docker.internal:3128。修复使用宿主机网络构建docker build --networkhost -t … -f Dockerfile .13. UI 中 Finding sandbox... 卡住症状Craft UI 无限显示 Finding sandbox...api_server 日志无供给活动。原因数据库中存在指向已被移除容器的陈旧Sandbox行。UI 在等待一个 api_server 认为存在但实际不可达的沙箱。修复docker exec onyx-relational_db-1 psql -U postgres -c \ DELETE FROM sandbox WHERE id sandbox-uuid;删除后Craft 中的下一条提示会触发全新供给。14. 陈旧沙箱容器以旧 env 运行症状沙箱容器来自之前的安装但缺少新代码注入的环境变量没有AGENT_TRANSPORT、没有OPENCODE_SERVER_PASSWORD等。原因容器由之前不了解这些变量的 api_server 镜像供给。重启 api_server 不会重建既有容器。修复删除容器及其卷docker rm -f sandbox-id docker volume rm onyx-craft-sandbox-id docker exec onyx-relational_db-1 psql -U postgres -c \ DELETE FROM sandbox WHERE id full-uuid;下一条 Craft 提示会以当前代码的环境注入重新供给。八、如何验证它确实在工作API server 具备 serve 方法post-#11402 代码已加载docker exec onyx-api_server-1 grep -c _serve_base_url\|_read_opencode_password \ /app/onyx/server/features/build/sandbox/docker/docker_sandbox_manager.py # 预期2SandboxBackend.DOCKER存在post-#11222 代码已加载docker exec onyx-api_server-1 python -c \ from onyx.server.features.build.configs import SandboxBackend; print(list(SandboxBackend)) # 预期[..., SandboxBackend.DOCKER: docker]沙箱镜像的 entrypoint 以 AGENT_TRANSPORT 为门控post-#11402 镜像docker run --rm --entrypoint cat your-sandbox-image /workspace/entrypoint.sh \ | grep -E AGENT_TRANSPORT|opencode serve # 预期两行均被引用仓库中当前 entrypoint.sh 会以重启循环运行opencode serve --hostname 0.0.0.0 --port $OPENCODE_PORT --print-logs端口 4096。一次提示触发后应存在一个沙箱容器docker ps --filter namesandbox- --format {{.Names}} {{.Status}} {{.Ports}} # 预期一个 sandbox-id8 Up且显示内部端口 4096容器名规则与 K8s 一致sandbox-uuid 前 8 位见docker_sandbox_manager.py中的_sandbox_container_name()。该容器内部opencode serve 应在运行docker exec sandbox-id8 ps auxw | grep opencode # 预期一个 opencode serve 进程而不是仅 sleep infinityapi_server 可达 opencode-servedocker exec onyx-api_server-1 curl -fsS \ -u opencode:$(docker inspect sandbox-id8 --format {{range .Config.Env}}{{println .}}{{end}} \ | grep ^OPENCODE_SERVER_PASSWORD | cut -d -f2-) \ http://sandbox-id8:4096/doc \ | head -c 100 # 预期一段 OpenAPI / Swagger 内容非空对应源码_load_serve_connection_info()通过一次docker inspect提取环境中的OPENCODE_SERVER_PASSWORDURL 使用沙箱网桥上的容器名 DNS。发送提示时日志显示完整 serve 传输序列docker logs -f onyx-api_server-1 21 | grep -E SANDBOX-SERVE|SESSION-LIFECYCLE应在提示后几秒内依次看到ensure_opencode_session、Created PodEventBus、opencode-serve ready、_send_message_via_serve、send_message completed。九、清理与拆除# 停止整个栈保留数据 cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml down # 或使用安装器交付的 CLI onyx-cli deploy stop # 停止容器保留卷 onyx-cli deploy uninstall # 停止并擦除所有数据 # 清理孤儿沙箱容器 docker ps --filter namesandbox- -q | xargs -r docker rm -f # 测试后回收 Docker 磁盘 docker builder prune -af docker image prune -af --filter until24h十、相关引用PR #11222 —feat(craft): docker-compose sandbox backend— 新增 Docker 管理器与 craft compose 文件。PR #11334 —feat(craft): opencode-serve transport with PodEventBus— 在 K8s 上新增 serve 传输。PR #11402 —feat(craft): port DockerSandboxManager to opencode-serve transport— serve 传输的 Docker 侧移植本文工作。PR #11424 —fix(install): route DOCKER_SUDO via wrapper so bash 3.2 parses empty arrays— 针对 macOS 的 install.sh 修复。serve 传输的设计文档可参考仓库中的 docs/craft/features/streaming/docker-opencode-serve.mdDocker serve 移植与 docs/craft/features/streaming/drop-acp-layer.mdACP 层迁移相关设计。镜像架构说明docs/craft/infra/image-architecture.md。部署所需全部 compose 与配置文件主栈 docker-compose.yml、Craft 覆盖 docker-compose.craft.yml、环境变量模板 env.template、安装脚本 install.sh。核心源码沙箱后端枚举与全部配置项 configs.py、Docker 沙箱管理器 docker_sandbox_manager.py、沙箱容器入口 entrypoint.sh。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Onyx Craft 自托管部署实战基于 docker-compose 与 opencode serve 的完整上手指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswerOnyx Craft 是 Onyx 开源的 AI 编程式 Web 应用构建能力本文聚焦于自托管用户最关心的 Docker 后端路径如何在 docker-compose 部署形态下通过opencode serveHTTP 传输AGENT_TRANSPORTserve将 Craft 完整跑起来。读完本文你将掌握从零搭建 Craft 的完整流程、全部关键环境变量与镜像选择逻辑、未发布 PR 的本地镜像构建方法以及部署过程中几乎必然遇到的一线排障经验含 macOS bash 3.2、OpenSearch 磁盘只读、网络缺失、镜像陈旧等十余个真实问题。本文以仓库文档 docs/craft/docker/docker-compose-overview.md 为主体骨架并结合docker-compose.craft.yml、安装脚本与 Docker 沙箱管理器源码进行纵深印证。如果你的部署目标是云环境cloud / kind或 Kubernetes请直接使用 Kubernetes 管理器路径可参考 docs/craft/kubernetes/craft-eks-runbook.md本文的 Docker 后端专为自托管 docker-compose 部署者而存在。一、架构概览为什么 Docker 后端只需要普通镜像在进入部署之前先厘清一个关键事实Onyx 并没有任何 Craft 专属的应用/后端镜像。Craft 的 agentopencode完全运行在独立的沙箱容器内api_server 只是opencode-serve的 HTTP 客户端自身从不执行opencode/node。因此后端镜像无需内置任何 Craft 专属内容ENABLE_CRAFTtrue在运行时被读取即可启用该功能。镜像体系如下表详见 docs/craft/infra/image-architecture.md镜像是否 Craft 专属说明onyxdotapp/onyx-backend否标准镜像运行时以ENABLE_CRAFTtrue启用 Craftonyxdotapp/onyx-web-server否标准镜像onyxdotapp/onyx-model-server否标准镜像onyxdotapp/sandbox是唯一 Craft 专属镜像内置 Node opencodeCLI负责运行 agent沙箱镜像与应用镜像共用同一个 tag应用 tag 为X时onyxdotapp/sandbox:X必须已发布。docker-compose 遵循既有的IMAGE_TAG行为默认latest。由于沙箱容器是由 Docker 管理器而非 compose在运行时创建的管理器遵循不可变 tag 缺失才拉取、可变 tag 每个 API 进程刷新一次的策略对应源码 docker_sandbox_manager.py 中的_ensure_sandbox_image()。docker-compose.craft.yml是叠加在主 compose 之上的覆盖文件。值得注意的安全提示文件头部注释api_server、background与sandbox-proxy都会 bind-mount 宿主机的/var/run/docker.sock等价于宿主机 root 权限因此只应在完全受控的宿主机上运行。二、TL;DR —— 快速开始如果你已经熟悉 Onyx 部署下面是整条捷径文档原文完整保留# 1. Stage compose 文件这些文件尚未进入任何 release tag WT/path/to/onyx/checkout # 本仓库检出在包含 Docker 后端的分支上 mkdir -p ~/onyx_data/deployment ~/onyx_data/data/nginx cp $WT/deployment/docker_compose/docker-compose.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/docker-compose.craft.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/env.template ~/onyx_data/deployment/ cp $WT/deployment/data/nginx/app.conf.template ~/onyx_data/data/nginx/ cp $WT/deployment/data/nginx/run-nginx.sh ~/onyx_data/data/nginx/ # 2. 以 --local 模式运行安装器并带上 craft bash $WT/deployment/docker_compose/install.sh --local --include-craft --dir ~/onyx_data # 3. 修正 .envexisting-env 安装路径会跳过这些参见下文必需环境变量 cat ~/onyx_data/deployment/.env ENV ENABLE_CRAFTtrue SANDBOX_BACKENDdocker HOST_PORT3001 ENV # 4. 如果运行未发布的 PR例如 opencode-serve需要在本地构建后端与 # sandbox 镜像并在 .env 中指向它们。参见下文运行未发布的 PR。 # 5. 启动 (cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml up -d) # 6. 通过 Admin UI 在 http://localhost:3001 配置 LLM provider # 在此之前Craft 会以 No default LLM model found 失败注意以上命令路径~/onyx_data等是文档中的示例部署目录你可以用任何自托管部署目录替代只需保持一致。三、前置条件Docker Desktop、OrbStack 或 Linux 上的 Docker Engine。Craft overlay 在所有平台上都使用私有的onyx-craft-api网桥别名。约 80 GB 可用的 Docker 磁盘空间。Onyx 全栈镜像拉取约 30 GB本地镜像构建再增加 10–15 GB如果不清理构建缓存可膨胀到 40 GB详见下文OpenSearch 进入只读模式一节。一个 LLM API keyAnthropic / OpenAI 等。四、必需环境变量安装完成后以下变量必须出现在~/onyx_data/deployment/.env中变量是否必需说明ENABLE_CRAFTtrue是--include-craft会写入它全新安装与已有.env都适用。SANDBOX_BACKENDdocker是--include-craft会与ENABLE_CRAFT一并写入。ONYX_SERVER_URL可选完整的 API 基础 URL。Craft overlay 默认使用私有沙箱网桥上的http://onyx-craft-api:8080。仅当需要走公共 URL 时才覆盖且要包含其/api路径前缀。HOST_PORT3001仅在 3000 冲突时默认 3000nginx 在宿主机绑定该端口。释放 3000 或在此修改。IMAGE_TAG可选除非设置否则使用 compose 默认值latest。Craft 对沙箱镜像使用同一 tag正常部署不要单独设置沙箱镜像。没有Craft 专属的 app/backend 镜像——Craft 通过ENABLE_CRAFTtrue在运行时启用见 docs/craft/infra/image-architecture.md。ONYX_BACKEND_IMAGE仅在运行未发布 PR 时只覆盖后端镜像而不强制 model-server / web-server 使用同一 tag。AGENT_TRANSPORTserve针对 serve 传输docker-compose.craft.yml默认值为servepost-#11402回滚路径可覆盖为acp。通过环境变量透传到达沙箱容器。ENABLE_OPENCODE_DEBUGGINGtrue可选Craft UI 中面向开发者的 pod 日志查看按钮。默认false。需要特别说明的是OPENCODE_SERVER_PASSWORD、OPENCODE_CONFIG_CONTENT、OPENCODE_SERVE_PORT不是由你设置的——DockerSandboxManager.provision()会在每次供给沙箱时用secrets.token_urlsafe(32)生成密码、生成配置内容并在容器创建时注入其环境变量见 docker_sandbox_manager.py 中build_container_create_kwargs()对OPENCODE_SERVER_PASSWORD与OPENCODE_CONFIG_CONTENT的注入逻辑以及 configs.py 中对OPENCODE_SERVE_PORT默认 4096的定义。环境变量如何真正生效源码级说明SANDBOX_BACKEND的解析configs.py中定义了SandboxBackend枚举KUBERNETES kubernetes、DOCKER docker启动时从环境读取并做小写匹配非法值会抛出ValueError——这就是文档中镜像陈旧报错docker is not a valid SandboxBackend的根源。docker-compose 只透传environment:块中列出的变量.env中的变量只参与 compose 的插值不会自动传播进容器。这正是 pre-#11402 时AGENT_TRANSPORTserve无效的原因修复方式是显式把AGENT_TRANSPORT与ENABLE_OPENCODE_DEBUGGING加入api_server和background服务的environment:透传。ONYX_SERVER_URL的默认值docker-compose.craft.yml中api_server/background服务将其默认设为http://onyx-craft-api:8080对应沙箱网桥上api_server的别名。若将其指向 compose 内部服务名如http://api_server:8080docker_sandbox_manager.py中的_looks_like_internal_compose_host()会发出警告沙箱只加入 Craft 网桥无法解析默认网络上的服务名。docker-compose.craft.yml 中还有哪些固定值除上述变量外overlay 中还固定pinned了几个值不可通过.env覆盖以避免env_file泄漏导致不一致SANDBOX_DOCKER_NETWORKonyx_craft_sandbox必须与 compose 的networks:块及 install.sh 中的字面量一致SANDBOX_DOCKER_SOCKET/var/run/docker.sock容器侧绑定目标OPENCODE_SERVE_PORT4096必须与沙箱镜像 entrypoint.sh 中的硬编码一致见 entrypoint.shSANDBOX_PROXY_HOSTsandbox-proxy、SANDBOX_PROXY_PORT8080代理是强制的显式的空值会在 api_server 启动时抛错对应DockerSandboxManager.__init__中requires SANDBOX_PROXY_HOST的检查此外还提供可调参数SANDBOX_DOCKER_MEMORY_LIMIT默认2g与SANDBOX_DOCKER_CPU_LIMIT默认1.0。这两个默认值与 K8s 沙箱 pod 的requests1 CPU / 2Gi一致而非其 limits2 CPU / 10Gi——因为单机 compose 部署很少有超卖到 10Gi 的余量见 configs.py 中 Docker 沙箱段落的注释。env.template中同样对这些变量做了完整注释见 env.template 的 Craft 配置段落。五、逐步部署详解1. Stage compose 文件安装脚本正常情况下会从最新 GitHub release 下载docker-compose.yml/docker-compose.craft.yml/env.template。但docker-compose.craft.yml目前尚未出现在任何 release tag 中——craft 仅存在于main分支。因此需要先从 checkout 预置WT/path/to/onyx mkdir -p ~/onyx_data/deployment ~/onyx_data/data/nginx cp $WT/deployment/docker_compose/docker-compose.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/docker-compose.craft.yml ~/onyx_data/deployment/ cp $WT/deployment/docker_compose/env.template ~/onyx_data/deployment/ cp $WT/deployment/data/nginx/app.conf.template ~/onyx_data/data/nginx/ cp $WT/deployment/data/nginx/run-nginx.sh ~/onyx_data/data/nginx/2. 运行安装器bash $WT/deployment/docker_compose/install.sh --local --include-craft --dir ~/onyx_data--local跳过下载使用预置文件。--include-craft选择 Docker 沙箱后端。--dir指向预置目录——不传则默认~/.config/onyx。需要注意安装器是交互式的——它只在 stdin 是终端时才提示因此echo 2\n\n | bash这类管道输入不会生效。要么从终端运行要么适配其提示Standard 模式 2保留现有 env 留空。此外--no-prompt会默认进入Lite 模式而 Lite 模式与--include-craft互斥不要组合使用。从仓库中的 install.sh 可以看到安装脚本本身只是一个引导器它下载并校验onyx-cli含 sha256 校验与失败即退出然后把参数原样转发给onyx-cli deploy install。脚本要求保持与 bash 3.2 兼容macOS 默认仍是 3.2.57这正是下文多个 macOS 排障问题的伏笔。3. 修正 .env在已有.env上--include-craft会替你写入ENABLE_CRAFTtrue与SANDBOX_BACKENDdockerupdate 与 restart 两条路径都会写。仅当默认端口不可用时才设置HOST_PORTcat ~/onyx_data/deployment/.env ENV HOST_PORT3001 ENV如果你同时为未发布的 PR 构建了本地镜像还需要追加覆盖变量见下一节。4. 启动整个栈cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml up -dcompose 文件将onyx_craft_sandbox网络声明为external: true。安装器只在全新安装路径上创建它。如果你是在已有安装上以--include-craft升级需要手动创建docker network create onyx_craft_sandbox佐证docker-compose.craft.yml的networks:块将onyx_craft_sandbox声明为external: true并注释Pre-created by install.sh --include-craft同时声明了external: true的命名卷sandbox_proxy_ca供沙箱代理的 MITM CA 持久化之所以用 external 固定 name是为了让DockerSandboxManager在 compose 项目作用域之外供给沙箱容器时也能挂载同一名称的卷。此外overlay 还定义了一个有意思的服务sandbox-image-prepull它以deploy.replicas: 0声明且entrypoint: [/bin/true]其唯一目的是让docker compose pull能提前拉取约 1 GB 的沙箱镜像避免第一次提示时在供给请求内才冷拉。replicas: 0保证up时不会真正创建容器注释明确说明它不是 workload而是一个镜像引用。5. 配置 LLM provider打开 http://localhost:3001登录后进入Admin Panel → Language Models添加一个 providerAnthropic / OpenAI / OpenRouter。在此之前每一个 Craft 提示都会失败报错ValueError: No default LLM model found6. 在 Craft 中尝试一次提示点击侧边栏的Craft发送一条提示。观察 api_server 日志docker logs -f onyx-api_server-1 21 | grep -E SANDBOX-SERVE|SESSION-LIFECYCLE正常应依次看到[SESSION-LIFECYCLE] sandbox.ensure_opencode_session: build_session… directory/workspace/sessions/…[SANDBOX-SERVE] Created PodEventBus for sandbox … dir/workspace/sessions/…[SANDBOX-SERVE] opencode-serve ready for sandbox …[SESSION-LIFECYCLE] _send_message_via_serve: build_session… caller-supplied opencode_session_id…[SANDBOX-SERVE] send_message completed: session… events… got_prompt_responseTrue六、运行未发布的 PR本地镜像构建已发布的edge由main构建。如果你在测试尚未合并的 PR已发布镜像不会包含你的代码必须本地构建受影响的镜像。后端镜像cd /path/to/onyx docker build \ -t onyxdotapp/onyx-backend:craft-prN \ -f backend/Dockerfile \ backend/耗时约 10–20 分钟。Craft 通过ENABLE_CRAFTtrue在运行时启用不存在Craft 专属的后端镜像变体。然后在.env中ONYX_BACKEND_IMAGEonyxdotapp/onyx-backend:craft-prN不要把IMAGE_TAG指向你的 PR 构建——IMAGE_TAG作用于 compose 文件中引用的每一个镜像model-server、web-server 等Docker 会尝试拉取onyxdotapp/onyx-model-server:craft-prN并失败。ONYX_BACKEND_IMAGE是仅针对后端的覆盖。沙箱镜像沙箱容器有自己的镜像但正常部署使用IMAGE_TAG选定的应用对齐沙箱 tag。如果你测试的 PR 包含未发布的沙箱镜像改动可本地构建覆盖镜像。这仅用于 PR 与内部测试不适用于正常客户部署。docker build --networkhost \ -t onyxdotapp/sandbox:prN \ -f backend/onyx/server/features/build/sandbox/image/Dockerfile \ backend/onyx/server/features/build/sandbox/image/--networkhost用于绕过 Docker Desktop 的 HTTP 代理——如果deb.debian.org在 apt-get 期间返回Connection refused构建会以 Unable to locate package python3-venv / Connection refused针对 Debian apt 镜像源失败。然后在.env中SANDBOX_CONTAINER_IMAGEonyxdotapp/sandbox:prN更新.env后强制重建 api_server 与 background 以使其读取新环境cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml \ up -d --no-build --force-recreate api_server background--no-build很重要——不加的话 compose 会尝试构建镜像因为 compose 文件中也有build:指令并因相对路径../../backend在~/onyx_data/deployment下无法解析而失败。七、你将遇到的坑按出现顺序大致排列1. macOS bash 3.2安装脚本以unbound variable中止症状运行curl -fsSL …/install_onyx.sh | bash时/bin/bash: DOCKER_SUDO[]: unbound variable原因macOS 仍自带 bash 3.2.57。在set -u下对空数组arr()做${arr[]}展开会直接报错——即使数组已被显式声明。修复提供一个run_docker()包装函数基于${#DOCKER_SUDO[]} 0分支使数组展开仅在非空时执行见 PR #11424。2. macOS bash 3.2HOST_PORT3000: command not found症状去掉set -u后安装仍失败install.sh: line 371: HOST_PORT3000: command not found原因bash 3.2 的解析器是单趟的——当可能为空的展开位于命令位置${DOCKER_SUDO[]} VARval cmd时解析器在解析期就把VARval归类为位置参数而非环境变量前缀。数组随后展开为 0 个词时VARval被当作命令名解释。bash 4 会在展开后重新求值因此 Linux/CI 永远不会遇到。去掉set -u并不能修复此问题。修复同一个run_docker()包装——调用点变为VARval run_docker $cmd …此时首 token 是函数调用上的字面环境变量前缀解析器满意数组展开位于函数体内、远离命令位置。3. sudo 路径env_reset 剥离内联 VARval未关闭的 P1Greptile 在 PR #11424 上标记了此问题但合入前未解决。当DOCKER_SUDO(sudo)Linux 刚加入 docker 组的路径时run_docker最终调用sudo docker compose。sudo 默认的env_reset会剥离HOST_PORT…/IMAGE_TAG…前缀因为它们经由父进程的环境到达 sudo而非作为位置参数。PR #11424 之前的调用形式是${DOCKER_SUDO[]} VARval cmd它把VARval作为 sudo 的位置参数传递——即便env_reset生效 sudo 也认可。修复尚未发布在run_docker的 sudo 分支内通过显式env重新注入相关变量run_docker() { if [ ${#DOCKER_SUDO[]} -gt 0 ]; then local env_args() [ -n ${HOST_PORT-} ] env_args(HOST_PORT$HOST_PORT) [ -n ${IMAGE_TAG-} ] env_args(IMAGE_TAG$IMAGE_TAG) ${DOCKER_SUDO[]} env ${env_args[]${env_args[]}} $ else $ fi }4. 安装脚本在已有 .env 路径上跳过网络创建症状network onyx_craft_sandbox declared as external, but could not be found ✗ Failed to start Onyx services原因install.sh 的docker network create onyx_craft_sandbox只在全新安装分支if [ ! -f $ENV_FILE ]内执行。脚本检测到已有.env时走 update 路径完全跳过网络创建。修复PR #11402将网络创建块移出全新安装门控使它在--include-craft被设置时总是执行if [ $INCLUDE_CRAFT true ]; then SANDBOX_NET${SANDBOX_DOCKER_NETWORK:-onyx_craft_sandbox} if ! run_docker docker network inspect $SANDBOX_NET /dev/null 21; then run_docker docker network create $SANDBOX_NET /dev/null fi fi修复前的临时方案手动执行docker network create onyx_craft_sandbox。5.docker-compose.craft.yml未透传 AGENT_TRANSPORTpre-#11402症状在.env中设置AGENT_TRANSPORTserve无效果——api_server 容器的环境里没有它。原因docker-compose 只传递服务environment:块中列出的变量。.env中的变量只供 compose插值使用不会自动传播到容器。修复PR #11402在docker-compose.craft.yml的api_server与background服务中显式添加透传environment: - AGENT_TRANSPORT${AGENT_TRANSPORT:-serve} - ENABLE_OPENCODE_DEBUGGING${ENABLE_OPENCODE_DEBUGGING:-false}6. 镜像陈旧已发布 tag 落后于 main症状 Aapi_server 启动即崩溃报ValueError: docker is not a valid SandboxBackend。原因你用的 release 镜像早于 Docker 沙箱后端PR #112225 月 20 日——其SandboxBackend枚举只有LOCAL/KUBERNETES。修复使用足够新的镜像 tagIMAGE_TAGlatest症状 Bedge对 Docker 后端可用但缺少 PR #11402 的 serve 传输新增。ensure_opencode_session()返回None因为 base.py 的桩从未被DockerSandboxManager覆盖已发布镜像未实现_serve_base_url/_read_opencode_password。修复本地构建后端镜像见上文运行未发布的 PR。症状 Copencode-serve never became ready for sandbox … after 30s (last error: ConnectError: [Errno 111] Connection refused)。原因应用镜像与沙箱镜像来自不同源版本或你测试未发布的沙箱镜像改动却没有匹配的本地沙箱镜像。修复部署匹配的 app/sandbox tag或同样本地构建沙箱镜像。7.IMAGE_TAG作用于每一个镜像症状设置IMAGE_TAGcraft-prN后拉取失败报No such image: onyxdotapp/onyx-model-server:craft-prN。原因compose 文件中所有服务的image:行都引用IMAGE_TAG并非只有后端。修复使用ONYX_BACKEND_IMAGE只覆盖后端镜像。8.compose up --force-recreate触发了构建症状镜像 tag 指向仅本地存在的 tag 时报unable to prepare context: path /path/to/Desktop/backend not found。原因image:查找无法从 registry 拉取时compose 回退到 compose 文件中的build:指令。构建上下文../../backend相对 compose 文件目录解析在~/onyx_data/deployment下无法解析。修复给docker compose up传--no-build。9.compose down/up遗留孤儿容器症状Conflict. The container name /onyx-cache-1 is already in use by container …——即使down报告已移除。原因之前的up --force-recreate与不完整构建交错使命名容器处于不一致状态。修复docker compose -f docker-compose.yml -f docker-compose.craft.yml down docker compose -f docker-compose.yml -f docker-compose.craft.yml up -d --no-build10. OpenSearch 进入只读模式磁盘满症状api_server 崩溃报TransportError(429, cluster_block_exception, index [danswer_chunk_…] blocked by: [TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark, index has read-only-allow-delete block];)原因Docker Desktop 的虚拟磁盘达到 95% 的 flood-stage 水位。macOS 上 Docker VM 使用固定大小磁盘镜像拉取 构建会消耗它。OpenSearch 看到的是 VM 磁盘而非宿主机磁盘。修复docker builder prune -af # 构建缓存常达 40 GB docker image prune -af --filter until24h释放足够空间后磁盘低于低水位时 OpenSearch 会自动解除阻塞。重启 api_server 重试。11. 端口 3000 已被占用症状nginx 绑定失败bind: address already in use。原因另一个进程常见的是 Node 开发服务器占用了 3000 端口。修复lsof -nP -iTCP:3000 -sTCP:LISTEN # 找到 PID # 要么杀掉它要么 echo HOST_PORT3001 ~/onyx_data/deployment/.env # 然后启动栈通过 http://localhost:3001 访问12. 沙箱镜像 apt 构建失败症状W: Failed to fetch http://deb.debian.org/debian/dists/bookworm/InRelease Could not connect to deb.debian.org:80 … (111: Connection refused) E: Unable to locate package python3-venv原因Docker Desktop 有时将 buildkit 的出站 HTTP 路由到不可达或异常的代理http.docker.internal:3128。修复使用宿主机网络构建docker build --networkhost -t … -f Dockerfile .13. UI 中 Finding sandbox... 卡住症状Craft UI 无限显示 Finding sandbox...api_server 日志无供给活动。原因数据库中存在指向已被移除容器的陈旧Sandbox行。UI 在等待一个 api_server 认为存在但实际不可达的沙箱。修复docker exec onyx-relational_db-1 psql -U postgres -c \ DELETE FROM sandbox WHERE id sandbox-uuid;删除后Craft 中的下一条提示会触发全新供给。14. 陈旧沙箱容器以旧 env 运行症状沙箱容器来自之前的安装但缺少新代码注入的环境变量没有AGENT_TRANSPORT、没有OPENCODE_SERVER_PASSWORD等。原因容器由之前不了解这些变量的 api_server 镜像供给。重启 api_server 不会重建既有容器。修复删除容器及其卷docker rm -f sandbox-id docker volume rm onyx-craft-sandbox-id docker exec onyx-relational_db-1 psql -U postgres -c \ DELETE FROM sandbox WHERE id full-uuid;下一条 Craft 提示会以当前代码的环境注入重新供给。八、如何验证它确实在工作API server 具备 serve 方法post-#11402 代码已加载docker exec onyx-api_server-1 grep -c _serve_base_url\|_read_opencode_password \ /app/onyx/server/features/build/sandbox/docker/docker_sandbox_manager.py # 预期2SandboxBackend.DOCKER存在post-#11222 代码已加载docker exec onyx-api_server-1 python -c \ from onyx.server.features.build.configs import SandboxBackend; print(list(SandboxBackend)) # 预期[..., SandboxBackend.DOCKER: docker]沙箱镜像的 entrypoint 以 AGENT_TRANSPORT 为门控post-#11402 镜像docker run --rm --entrypoint cat your-sandbox-image /workspace/entrypoint.sh \ | grep -E AGENT_TRANSPORT|opencode serve # 预期两行均被引用仓库中当前 entrypoint.sh 会以重启循环运行opencode serve --hostname 0.0.0.0 --port $OPENCODE_PORT --print-logs端口 4096。一次提示触发后应存在一个沙箱容器docker ps --filter namesandbox- --format {{.Names}} {{.Status}} {{.Ports}} # 预期一个 sandbox-id8 Up且显示内部端口 4096容器名规则与 K8s 一致sandbox-uuid 前 8 位见docker_sandbox_manager.py中的_sandbox_container_name()。该容器内部opencode serve 应在运行docker exec sandbox-id8 ps auxw | grep opencode # 预期一个 opencode serve 进程而不是仅 sleep infinityapi_server 可达 opencode-servedocker exec onyx-api_server-1 curl -fsS \ -u opencode:$(docker inspect sandbox-id8 --format {{range .Config.Env}}{{println .}}{{end}} \ | grep ^OPENCODE_SERVER_PASSWORD | cut -d -f2-) \ http://sandbox-id8:4096/doc \ | head -c 100 # 预期一段 OpenAPI / Swagger 内容非空对应源码_load_serve_connection_info()通过一次docker inspect提取环境中的OPENCODE_SERVER_PASSWORDURL 使用沙箱网桥上的容器名 DNS。发送提示时日志显示完整 serve 传输序列docker logs -f onyx-api_server-1 21 | grep -E SANDBOX-SERVE|SESSION-LIFECYCLE应在提示后几秒内依次看到ensure_opencode_session、Created PodEventBus、opencode-serve ready、_send_message_via_serve、send_message completed。九、清理与拆除# 停止整个栈保留数据 cd ~/onyx_data/deployment docker compose -f docker-compose.yml -f docker-compose.craft.yml down # 或使用安装器交付的 CLI onyx-cli deploy stop # 停止容器保留卷 onyx-cli deploy uninstall # 停止并擦除所有数据 # 清理孤儿沙箱容器 docker ps --filter namesandbox- -q | xargs -r docker rm -f # 测试后回收 Docker 磁盘 docker builder prune -af docker image prune -af --filter until24h十、相关引用PR #11222 —feat(craft): docker-compose sandbox backend— 新增 Docker 管理器与 craft compose 文件。PR #11334 —feat(craft): opencode-serve transport with PodEventBus— 在 K8s 上新增 serve 传输。PR #11402 —feat(craft): port DockerSandboxManager to opencode-serve transport— serve 传输的 Docker 侧移植本文工作。PR #11424 —fix(install): route DOCKER_SUDO via wrapper so bash 3.2 parses empty arrays— 针对 macOS 的 install.sh 修复。serve 传输的设计文档可参考仓库中的 docs/craft/features/streaming/docker-opencode-serve.mdDocker serve 移植与 docs/craft/features/streaming/drop-acp-layer.mdACP 层迁移相关设计。镜像架构说明docs/craft/infra/image-architecture.md。部署所需全部 compose 与配置文件主栈 docker-compose.yml、Craft 覆盖 docker-compose.craft.yml、环境变量模板 env.template、安装脚本 install.sh。核心源码沙箱后端枚举与全部配置项 configs.py、Docker 沙箱管理器 docker_sandbox_manager.py、沙箱容器入口 entrypoint.sh。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 派生宏的合法目标类型约束)
