danswerOnyxWeb 前端开发指南Next.js 本地开发、云端后端联调与 Playwright E2E 测试全解析【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer本文以 web/README.md 为骨架结合 Onyx原 danswer仓库中的实际源码与配置系统讲解web/前端模块的本地开发环境搭建、如何用INTERNAL_URL与DEBUG_AUTH_COOKIE对接云端后端以及基于 Playwright 的端到端测试体系。读完你既能在一分钟内启动本地开发服务器也能配置一套安全的远程后端联调环境并掌握本项目 Playwright 测试的组织规范与调试技巧。一、web/前端模块概览web/是 Onyx 项目的前端应用目录基于Next.js 16.3.3与React 19.2.8构建采用 App Router 架构代码位于 web/src 下app/、components/、lib/、sections/、views/等。项目还通过 npm workspaces 托管了两个内部共享包见 web/package.jsononyx-ai/opalweb/lib/opal设计系统与 UI 组件库负责侧边栏断点等视觉规范onyx-ai/sharedweb/lib/shared前后端共享的类型与工具。从依赖清单web/package.json可以看出该前端的业务广度radix-ui/*系列提供无障碍原语组件react-markdownrehype-*remark-*负责聊天消息的 Markdown/数学公式渲染与消毒recharts承担使用量统计图表sentry/nextjs负责错误监控swr与zustand分别管理服务端数据缓存和客户端状态。启动整个栈并非只有前端一件事聊天、搜索、文档索引等能力全部由backend/FastAPI提供前端默认代理到本地 8080 端口详见下文后端地址的解析链路。二、环境准备安装 bun 与依赖Onyx 前端使用 bun 作为包管理器与运行时这也与仓库根目录、web/下分别存在bun.lock的事实一致。首先安装 bun详见官方安装文档然后在web/目录下安装依赖cd web bun install依赖安装的细节仓库通过 npm workspacesworkspaces: [lib/opal, lib/shared]把内部包软链进node_modules因此bun install会一并处理onyx-ai/opal与onyx-ai/shared两个本地包。切换分支后如果package.json发生变化项目通过 pre-commit 钩子自动重装依赖见根目录 CONTRIBUTING.md 中 Formatting and Linting 一节通常无需手动干预。Playwright 相关依赖playwright/test同样在此步骤中就位后续bunx playwright install才能解析到仓库锁定的版本。三、启动开发服务器安装完成后在web/目录执行bun run dev该命令对应 web/package.json 中的next dev启动后浏览器访问http://localhost:3000即可看到应用。如果 3000 端口访问异常例如被占用或代理冲突README 建议设置WEB_DOMAIN环境变量指向http://127.0.0.1:3000再访问WEB_DOMAINhttp://127.0.0.1:3000 bun run dev后端地址的解析链路前端默认假定本地后端运行在8080端口。这个默认值在源码中有三处体现web/src/lib/constants.tsexport const INTERNAL_URL process.env.INTERNAL_URL || http://localhost:8080;web/src/lib/utilsSS.ts服务端请求统一拼接为${INTERNAL_URL}${path}web/next.config.jsrewrites()把/api/docs、/openapi.json等路径代理到INTERNAL_URL未设置时同样回退到http://localhost:8080。因此bun run dev配合本地backend/FastAPI8080即可组成完整可用的开发环境。理解这条链路是下一步对接云端后端的基础。四、连接云端后端.env.local与INTERNAL_URL日常开发中你可能不想本地起一整套后端含数据库、向量库等而是让前端直连远程的后端环境如 staging 或 production。此时需要在web/目录下与package.json同级创建.env.local文件# 让本地开发服务器指向云端后端 INTERNAL_URLhttps://st-dev.onyx.app/api # 用于对远程后端做认证的调试 Cookie # 开发模式下该 Cookie 会被自动注入到 API 请求中 # 获取方式 # 1. 打开 https://st-dev.onyx.app或你的目标后端地址并登录 # 2. 打开 DevToolsF12→ Application → Cookies → [你的后端域名] # 3. 找到名为 fastapiusersauth 的 Cookie复制其值 # 4. 粘贴到下面不要加引号 # 注意该 Cookie 会过期需要定期刷新 DEBUG_AUTH_COOKIE你的cookie值关键行为与注意事项配置文件位置.env.local必须放在web/目录与package.json同级不要放在仓库根目录。修改后必须重启创建或修改.env.local后需要重启开发服务器bun run dev才能生效。DEBUG_AUTH_COOKIE仅开发模式生效只有NODE_ENVdevelopment时才被注入生产构建完全不受影响。未设置INTERNAL_URL时前端回退到本地后端http://127.0.0.1:8080见上文源码。不会覆盖已有 Cookie默认情况下该机制不会覆盖已存在的同名认证 Cookie如果你之前登录过可能需要先清除localhost域下的 Cookie。安全红线.env.local中存放的是有效会话凭证务必保持机密绝不能提交进版本控制该文件已列入.gitignore。注入机制的源码实现DEBUG_AUTH_COOKIE的注入逻辑位于 web/src/lib/users/svcSS.ts 的processCookies()函数收集当前请求携带的所有 Cookie拼成namevalue; namevalue字符串当process.env.DEBUG_AUTH_COOKIE process.env.NODE_ENV development时检查字符串中是否已存在认证 CookieCookie 名由SERVER_SIDE_ONLY__AUTH_COOKIE_NAME决定若不存在则把DEBUG_AUTH_COOKIE以fastapiusersauthvalue的形式追加进请求头。Cookie 名称默认是fastapiusersauthFastAPI-Users 标准名称定义于 web/src/lib/constants.ts并且可通过AUTH_COOKIE_NAME环境变量覆盖——这样在 localhost 不同端口并行开多个 worktree 时各前端实例可以维护彼此独立的认证 Cookie避免串号。getCurrentUserSS()同一文件 web/src/lib/users/svcSS.ts通过调用后端/me接口完成服务端会话校验注入后的 Cookie 会随该请求一并发送。五、Playwright E2E 测试从入门到调试5.1 警告测试会重置应用状态在web/下执行测试会把应用重置为干净状态注册测试账号、清理/重建测试数据如果你不希望动当前数据就不要在本地随意运行整套测试。5.2 安装 Playwright 浏览器先确保已执行过bun install这样bunx会解析到node_modules中仓库锁定的 Playwright 版本而不是临时拉取最新版然后安装浏览器bun install bunx playwright install5.3 运行测试playwright脚本在 web/package.json 中展开为playwright testbun run playwright只跑单个测试文件bun run playwright landing-page.spec.ts本地调试时可以加交互式参数直观看到每一步在浏览器中的执行情况bun run playwright --ui # UI 模式可视化管理与单步调试 bun run playwright --headed # 有头模式弹出浏览器窗口5.4 测试结果与截图输出web/playwright.config.ts 将输出目录配置为web/output/playwright/测试运行过程中会自动截图并保存到web/output/screenshots/。跨 CI 运行对比截图可使用 ODS 工具ods screenshot-diff compare --project admin该命令属于仓库内 ODSOnyx Developer Suite工具集详见 tools/ods/README.md 的 screenshot-diff 章节。5.5 Playwright 配置要点从 web/playwright.config.ts 可以看到本项目测试基础设施的关键设定配置项取值说明单测超时100 秒timeout: 100000断言超时15 秒降低断言抖动expect.timeout: 15000截图容差maxDiffPixelRatio: 0.01、threshold: 0.2容忍抗锯齿/亚像素渲染差异CI 重试2 次本地 0 次retries: process.env.CI ? 2 : 0CI 并发4 个 worker本地默认并发可注释切换为串行workers: 1便于调试测试范围tests/e2e/*.spec.ts用testMatch与 Jest 测试隔离失败追踪trace: retain-on-failure失败时保留 Trace 供回放基准地址BASE_URL环境变量覆盖默认http://localhost:3000对应use.baseURL项目还定义了三个测试项目projectadmin默认全量测试grepInvert排除exclusive、lite标记桌面 Chrome、1280×720 视口复用admin_auth.json登录态exclusive仅跑带exclusive标记的用例串行、单 worker适合独立慢速场景lite针对 Onyx Lite 栈DISABLE_VECTOR_DBtrue无 Vespa/Redis的用例仅跑带lite标记的测试。5.6 Global Setup测试前的自动准备测试不是裸奔的。globalSetupweb/tests/e2e/global-setup.ts会在测试套件运行前自动完成健康检查轮询BASE_URL直到返回 200最长 60 秒每 2 秒一次15 秒后开始告警。若超时会抛出明确错误并提示先用ods compose dev启动前后端注册测试账号通过 APIPOST /api/auth/register幂等注册管理员admin_userexample.com、二号管理员admin2_userexample.com和 8 个 worker 用户worker0..7example.com凭证定义见 web/tests/e2e/constants.ts。第一个注册的用户自动成为管理员API 登录并保存登录态用 Playwright 的轻量 request context 调POST /api/auth/login把 Cookie 保存为admin_auth.json、admin2_auth.json、workerN_auth.json等 storage state 文件——比真实浏览器登录更快、更安静消除新手引导干扰通过PATCH /api/user/personalization设置显示名称关掉首次登录时Onyx 该怎么称呼你的弹窗避免它遮挡聊天界面导致测试误判提升权限把二号管理员加入默认 Admin 用户组/api/manage/admin/user-groupadd-users准备公共 LLM Provider复用 admin 会话确保存在默认的公开 LLM Provider许多测试——文件上传、Agent 创建等——都依赖默认 LLM 已配置。从 web/tests/e2e 的目录结构可以看到测试覆盖范围admin/管理后台、安全加固、Token 限流、SCIM、OAuth 等、agents/、auth/、chat/、connectors/、craft/、mcp/、onboarding/、settings/等基本对应前端全部功能面。六、E2E 测试编写规范给测试作者仓库为 e2e 测试制定了明确的硬性规则见 web/tests/e2e/README.md核心两条6.1 强制使用 Page Object Model所有定位器与交互逻辑必须封装在 Page Object 类中放在tests/e2e/pages/一个类一个文件按界面命名如ChatPage、InputBar复合页面用嵌套对象暴露方法chatPage.inputBar.someMethod()spec 只调用方法、绝不直接构造定位器// ✅ 正确 —— spec 调用 POM 方法 await chatPage.goto(); await chatPage.inputBar.type(hello); await chatPage.inputBar.send(); await chatPage.expectHumanMessage(hello); // ❌ 错误 —— spec 内写裸定位器 await page.goto(/app); await page.locator([contenteditabletrue]).fill(hello); await page.keyboard.press(Enter); await expect(page.locator(.message)).toContainText(hello);定位器优先级从高到低data-testid/aria-labelgetByTestId、getByLabel→ 角色getByRole→ 文本/标签getByText、getByLabel→ CSS 选择器最后手段。6.2 断言必须用自动重试的 matcherPlaywright 的expect(locator).*会轮询重试直到断言通过或超时而locator.getAttribute()、page.evaluate()只读取一次 DOM 快照在 React 异步更新场景下极易产生抖动flaky测试断言对象应使用不应使用属性expect(locator).toHaveAttribute(name, value)getAttribute()后expect(...)classtoHaveClass(/regex/)/.not.toHaveClass(...)page.evaluate手写判断文本toHaveText(value)/toContainText(value)textContent()后expect(...)数量toHaveCount(n)count()后expect(...)可见性toBeVisible()/toBeHidden()手写isVisible()判断值toHaveValue(value)inputValue()后expect(...)getAttribute/evaluate等一次性读取仍可用于 spec 内部的控制流分支例如按读取值决定后续动作只是不能作为对异步状态的断言基础。这些规则连同更宏观的 Onyx 测试分层策略单元 / 外部依赖单元 / 集成 / E2E在 backend/AGENTS.md 与 backend/tests/README.md 中有更完整的说明。七、生产构建与常用脚本速查开发之外web/package.json 还提供了完整的工程化脚本命令作用bun run dev启动开发服务器next devbun run dev:profile开启NEXT_PUBLIC_ENABLE_STATStrue的带统计开发模式bun run dev:clean清理.next缓存后启动开发服务器bun run build生产构建next buildbun run build:fast跳过类型检查的快速构建SKIP_TYPE_CHECK1bun run start启动生产服务器next startbun run lint/lint:fix基于 oxlint 的代码检查与自动修复bun run types:checkNext 类型生成 TypeScript 严格类型检查tsconfig.types.jsonbun run format/format:check基于 oxfmt 的格式化与校验bun run test系列Jest 单元测试含 watch、coverage、CI 模式bun run playwrightPlaywright E2E 测试bun run storybook组件文档Storybook6006 端口值得注意的是 web/next.config.js 中的几处工程化决策output: standalone支持独立部署镜像turbopack.root显式固定到web/以避免仓库根目录多 lockfile 干扰React Compiler 在next build时开启、next dev时关闭可用ENABLE_REACT_COMPILER1强制开启——这些配置共同支撑了前端在开发、CI、生产三条链路上的稳定性。八、总结围绕 web/README.md本篇梳理了 Onyx 前端开发的完整闭环本地开发bun installbun run dev默认对接本地 8080 后端源码回退逻辑见 web/src/lib/constants.ts远程联调通过web/.env.local中的INTERNAL_URL指向云端后端、DEBUG_AUTH_COOKIE注入fastapiusersauth会话注入实现见 web/src/lib/users/svcSS.ts并牢记 Cookie 会过期、需定期刷新且严禁入库质量保障Playwright E2E 测试体系web/playwright.config.ts配备 global-setup 自动造数、storage state 复用登录态、POM 分层与自动重试断言规范web/tests/e2e/README.md配合--ui/--headed调试和 ODS 截图对比工具构成从开发到 CI 的完整质量闭环。掌握了这三层你就可以在 Onyx 仓库中高效地进行前端开发、后端联调与回归测试无论面向本地全栈环境还是云端后端。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考