Onyx devcontainer 开发环境指南兄弟容器服务发现、前后端本地启动与 Claude Code 覆盖层机制【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswerOnyx原 Danswer仓库为容器内开发者提供了一套专门的开发环境所有 Onyx 后端服务以兄弟容器形式运行在共享 Docker 网络上而前端与 API 则在 devcontainer 内部以热重载模式启动。本文以 .devcontainer/claude-code/CLAUDE.md 这份容器内专属说明为主体结合 devcontainer.json、devcontainer 说明文档 与前后端源码讲清容器内如何发现服务、如何启动应用、以及如何停止开发服务器。读完后你可以直接在 devcontainer 中通过服务主机名访问 Postgres、Redis、OpenSearch 等全部依赖并用odsCLI 一条命令拉起带热重载的完整应用。一、覆盖层定位叠加在项目级 CLAUDE.md 之上的容器专属指令.devcontainer/claude-code/CLAUDE.md的开头即声明了它的定位Runninginside the Onyx dev container. These notes are additive to the root/workspace/CLAUDE.md; on conflict with a host-oriented instruction there, prefer these.也就是说它是**增量补充additive**而非替换项目根目录的 CLAUDE.mdPROJECT KNOWLEDGE BASE面向宿主机 容器两种场景给出通用指引而这份覆盖层只在容器内生效且当两者冲突时典型例子就是docker exec回退方案以覆盖层为准。这种双份指令、冲突时就近优先的设计正是 Claude Code 等 Agent 在不同执行环境中保持指令一致性的常见做法。注入机制挂载到 /etc/claude-code 托管策略目录devcontainer 说明文档 解释了这份文件是如何自动加载的。在 devcontainer.json 的mounts数组中有一条关键配置source${localWorkspaceFolder}/.devcontainer/claude-code,target/etc/claude-code,typebind,即把仓库中的.devcontainer/claude-code/目录而非单个文件只读绑定挂载到容器内的/etc/claude-code/——这是 Claude Code 的 managed-policy 记忆文件位置。容器启动后Claude Code 会自动将/etc/claude-code/CLAUDE.md与项目根目录的CLAUDE.md一起加载无需任何手动操作。文档还解释了两个工程细节值得参考为什么挂载目录而不是单文件某些编辑器的原子保存先写临时文件再替换会使单文件 bind mount 脱离挂载点挂载整个目录则不会并且日后还可以往同目录放managed-settings.json等托管配置。热生效由于是 live bind mount修改仓库里这份文件后下一个 Claude Code 会话即生效——不需要重建镜像或重启容器。二、没有 Docker daemon在 onyx_default 网络上按主机名发现服务覆盖层的第一条硬性约束Dont usedocker/docker exec/docker compose. Onyx services run as sibling containers on theonyx_defaultnetwork, reachable directly by hostname.devcontainer 内部没有 Docker daemon因此根指引里连不上 psql 客户端就回退docker exec onyx-relational_db-1 ...的方案在容器内不可用但根指引里的psql直连命令却可以原样使用因为POSTGRES_HOST等环境变量已在容器内导出见下文第三节。网络是怎么建立起来的从 devcontainer.json 可以看到两处配合的配置initializeCommand: docker network create onyx_default 2/dev/null || true, runArgs: [--cap-addNET_ADMIN, --cap-addNET_RAW, --networkonyx_default]initializeCommand在宿主机上创建名为onyx_default的 Docker 网络幂等已存在则忽略runArgs中的--networkonyx_default让 devcontainer 加入同一网络。而 Onyx 的服务容器Postgres、Redis 等由 docker compose 启动时其项目名默认产生同样的onyx_default网络——可以推断 devcontainer 与这些服务容器正是通过共享该网络成为邻居从而在容器内直接用服务名作为主机名互访。NET_ADMIN/NET_RAW两个 capability 则是为可选的出站防火墙预留的与网络发现本身无关。原样可用的 psql 示例根 CLAUDE.md 给出的数据库访问命令在容器内无需任何改动PGPASSWORD${POSTGRES_PASSWORD:-password} psql -h ${POSTGRES_HOST:-localhost} -U postgres -c SQL在容器内${POSTGRES_HOST}会被解析为relational_db${POSTGRES_PASSWORD}默认回落到passworddevcontainer.json 中POSTGRES_PASSWORD的默认值正是password。devcontainer 镜像的 Dockerfile 也预装了postgresql-client因此psql客户端必然可用。三、服务主机名与环境变量速查覆盖层列出了容器内各服务的主机名并强调每个主机名同时以环境变量的形式导出。完整对照表如下主机名与 docker-compose.dev.yml 中的服务名一致服务容器内主机名导出环境变量Postgresrelational_dbPOSTGRES_HOSTRediscacheREDIS_HOSTVespaindexVESPA_HOSTModel serverinference_model_serverMODEL_SERVER_HOSTOpenSearchopensearchOPENSEARCH_HOSTMinIO / S3minio:9000S3_ENDPOINT_URLhttp://minio:9000这些环境变量并非口头约定而是实实在在写在 devcontainer.json 的containerEnv中containerEnv: { MODEL_SERVER_HOST: inference_model_server, OPENSEARCH_HOST: opensearch, POSTGRES_HOST: relational_db, POSTGRES_PASSWORD: ${localEnv:POSTGRES_PASSWORD:password}, REDIS_HOST: cache, S3_ENDPOINT_URL: http://minio:9000, VESPA_HOST: index }从源码结构看这套变量名与后端代码的常规读取方式一一对应如POSTGRES_HOST、REDIS_HOST是 Onyx 后端的通用连接配置所以在容器内写脚本或调 CLI 时直接引用环境变量即可不必硬编码主机名。此外docker-compose.dev.yml 还把各服务端口映射到了宿主机Postgres5432、OpenSearch9200、model server9000、Redis6379、MinIO9004/9005这意味着宿主机上的工具同样可以直连这些依赖但按覆盖层的要求容器内一律走主机名而不是宿主机端口。四、运行应用本地启动热重载的前端与后端覆盖层明确指出上述支撑服务由兄弟容器提供但前端和后端不会替你启动——需要在 devcontainer 内部手动运行且两者都支持热重载ods web dev # Next.js 前端监听 localhost:3000 ods backend api # FastAPI 后端uvicorn监听 localhost:8080ods是仓库自带的开发工具 CLI见 tools/ods/README.md。从 tools/ods/cmd/web.go 的源码看ods web dev的本质是从web/package.json读取 scripts 并用 bun 执行的 workspace 感知包装器tools/ods/cmd/backend.go 则支持ods backend api、--port 9090换端口、--no-ee不启用企业版模块等参数。开发模式下的 /api 兜底代理为什么localhost:3000一个端口就能同时服务 UI 和 API答案在前端的开发专用 catch-all 路由 web/src/app/api/[...path]/route.ts。该文件为 GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS 各方法都导出了同一个handleRequest转发函数其行为包括仅开发模式放行当NODE_ENV ! development且未设置OVERRIDE_API_PRODUCTIONtrue时直接返回 404并提示生产环境应由 nginx 等组件处理该路径目标地址请求被转发到INTERNAL_URL定义于 web/src/lib/constants.ts默认http://localhost:8080即 uvicorn 后端流式响应处理当响应是chunked传输或Content-Type含stream如聊天补全时代理会设置Cache-Control: no-cache, no-transform与X-Accel-Buffering: no并剥离content-length保证 SSE 流不被缓冲——这解释了为什么聊天类接口在:3000下也能实时出字。因此覆盖层给出的访问规则可以总结为入口说明http://localhost:3000同时服务 UI 与/api/*经 dev 代理转发到:8080无需反向代理http://localhost:8080直连 FastAPI 后端注意没有/api前缀例如/health、/auth/type一个容易踩的坑直连:8080时路径要去掉/api前缀而经过:3000时则保留/api前缀。根 CLAUDE.md 也要求调用后端时始终走前端如http://localhost:3000/api/persona而非:8080/api/persona以让认证 cookie 等会话语义保持一致。五、停止开发服务器覆盖层的最后一条操作指令开发结束后要主动停掉两个 dev server避免端口占用与资源泄漏# 前端 pkill -f next dev; pkill -f next-server # 后端 pkill -f uvicorn onyx.main:app前端需要两条pkill分别匹配启动进程next dev与 Next.js 实际的next-serverworker 进程后端则匹配 uvicorn 加载的onyx.main:app应用对象对应 backend/onyx/main.py 的 FastAPI 入口。由于 devcontainer 内没有 Docker daemon容器内进程只能用这类进程级手段管理而兄弟容器数据库、Redis 等的生命周期由宿主机上的 compose 部署负责不在容器内操作。六、小结devcontainer 工作模式的三条心法指令分两层根 CLAUDE.md 是项目通用知识.devcontainer/claude-code/CLAUDE.md 是容器内增量覆盖冲突时以后者为准它通过 bind mount 到/etc/claude-code实现免重建的热更新。服务发现靠网络而非 Dockeronyx_default网络上按主机名relational_db、cache、index、inference_model_server、opensearch、minio:9000直连环境变量已由containerEnv导出psql等根指引命令原样可用docker exec不可用。端口即入口ods web devods backend api启动后localhost:3000是UI /api统一入口dev-only 代理localhost:8080是去前缀的后端直连入口结束工作时用pkill分别停掉next dev/next-server与uvicorn onyx.main:app。这套模式对任何以 Docker 网络共享依赖、仅在容器内跑应用进程的项目都有借鉴价值把环境差异写进分层指令文件、用环境变量固化服务地址、用框架自带的 dev 代理替代反向代理可以显著降低容器化开发的心智负担。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考