OGX UI 实战指南基于 Next.js 与 shadcn/ui 构建的 Open GenAI Stack Web 控制台【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx本文围绕仓库中 src/ogx_ui/README.md 的核心内容展开系统介绍 Open GenAI StackOGX自带 Web 用户界面 OGX UI 的安装、启动、环境变量配置与模型过滤机制。读完本文你将掌握从源码启动开发服务器、用npx/Docker 在生产环境运行 UI、对接后端 OGX 服务器含认证以及通过NEXT_PUBLIC_OGX_UI_ALLOWED_MODELS精确控制 Chat Playground 模型下拉列表的完整方法。OGX UI 是什么OGX UI 是 OGX 项目附带的 Web 界面位于 src/ogx_ui基于 Next.js 15 与 React 19 构建见 src/ogx_ui/package.jsonUI 组件层采用 shadcn/ui 体系。根据 docs/docs/distributions/ogx_ui.mdx它的定位是连接到 OGX 后端服务器的客户端提供可视化的方式Chat Playground与模型对话、配置工具webSearch、fileSearch、MCP查看流式响应日志与监控查看 chat completions、agent responses 与 vector store 活动Vector Stores为 RAG 工作流创建和管理向量数据库Prompt 管理创建和复用可用的 prompt 模板。关键前提运行 UI 前需要有一个可访问的 OGX 服务器默认后端地址为http://localhost:8321。启动 OGX 服务器的方式可参考 docs/docs/distributions/starting_ogx_server.mdx。从源码启动开发服务器README 给出的开发启动流程非常简洁核心是两步安装依赖、启动 dev server。以当前工作目录仓库根目录为起点# 1. 进入 UI 源码目录 cd src/ogx_ui # 2. 安装依赖 npm install # 3. 启动开发服务器 npm run devnpm run dev实际执行的是见 src/ogx_ui/package.jsonnext dev --turbopack --port ${OGX_UI_PORT:-8322}也就是说开发服务器默认监听http://localhost:8322且端口可通过环境变量OGX_UI_PORT覆盖。README 同时提示其他包管理器同样可用npm run dev # 或 yarn dev # 或 pnpm dev # 或 bun dev除了devpackage.json 还提供了完整的工程化脚本脚本作用npm run build生产构建并在构建后执行node scripts/postbuild.js做产物后处理npm run start以生产模式启动已构建的应用npm run lint运行 ESLint 检查npm run type-check运行tsc --noEmit做 TypeScript 类型检查npm run test运行 Jest 单元测试npm run test:e2e运行 Playwright 端到端测试如果只想在开发模式下快速验证配置是否就绪服务启动时 instrumentation.ts 会调用 lib/config-validator.ts在控制台打印NEXTAUTH_URL、OGX_BACKEND_URL、OGX_UI_PORT的当前值并提示 GitHub OAuth 是否已配置。生产环境运行方式npx 与 Dockersrc/ogx_ui/README.md聚焦于开发模式而生产运行方式记录在 docs/docs/distributions/ogx_ui.mdx这里一并补全便于读者在真实部署时直接使用。方式一npx 一键启动ogx-ui已发布为 npm 包包内bin字段指向 bin/cli.js因此可以直接npx ogx-uibin/cli.js的实现逻辑是读取OGX_UI_PORT默认8322随后spawn启动.next/standalone目录下的生产服务器并把PORT注入子进程环境同时对SIGINT/SIGTERM做了信号转发以保证优雅退出。UI 服务随即监听http://localhost:8322。方式二Docker 构建并运行仓库在 src/ogx_ui/Containerfile 中提供了镜像定义其要点包括基于node:22.5.1-alpine、安装dumb-init做进程信号托管、创建非 root 用户nextjsuid/gid 1001以降低安全风险、通过npm install -g ogx-ui从 npm 安装 UI 包最终以ogx-ui命令作为入口。构建与运行docker build -t ogx-ui -f src/ogx_ui/Containerfile . docker run -p 8322:8322 ogx-ui然后浏览器访问http://localhost:8322。环境变量对接后端与启用认证UI 的运行时行为完全由环境变量驱动docs/docs/distributions/ogx_ui.mdx 给出了完整清单核心连接配置变量说明默认值OGX_BACKEND_URLOGX 后端服务器地址http://localhost:8321OGX_UI_PORTUI 服务监听端口8322npx 方式设置环境变量OGX_BACKEND_URLhttp://localhost:8321 \ OGX_UI_PORT8080 \ npx ogx-uiDocker 方式设置环境变量docker run -p 8080:8080 \ -e OGX_BACKEND_URLhttp://localhost:8321 \ -e OGX_UI_PORT8080 \ ogx-ui认证相关配置可选当 OGX 服务器启用了认证时UI 通过 NextAuth 接入 GitHub OAuth变量说明默认值NEXTAUTH_URLNextAuth 回调基础 URLhttp://localhost:8322GITHUB_CLIENT_IDGitHub OAuth Client ID可选-GITHUB_CLIENT_SECRETGitHub OAuth Client Secret可选-配置入口可参考 lib/auth.ts应用根布局通过 components/providers/session-provider.tsx 挂载SessionProvider见 app/layout.tsx并在顶栏渲染SignInButton。若未配置 GitHub OAuthlib/config-validator.ts 会打印提示认证功能保持禁用不会阻塞 UI 启动。开发模式下配置 GitHub OAuth 时OAuth 回调地址需设为http://localhost:8322/api/auth/callback/github。核心配置模型过滤Model FilteringREADME 中技术含量最高的部分是模型过滤Chat Playground 默认展示后端返回的全部 LLM 模型若想收敛模型下拉列表设置环境变量NEXT_PUBLIC_OGX_UI_ALLOWED_MODELS为逗号分隔的模型 ID 列表即可NEXT_PUBLIC_OGX_UI_ALLOWED_MODELSopenai/gpt-4.1-mini,anthropic/claude-sonnet-4-6注意该变量带NEXT_PUBLIC_前缀属于 Next.js 约定的构建期注入客户端的环境变量因此它是在构建/启动 UI 时生效而非运行时动态切换。行为语义README 明确了三条行为规则配置后只有匹配的模型会出现在下拉列表中模型的展示顺序严格遵循配置列表中的书写顺序而不是后端返回顺序默认选中第一个匹配的模型若变量未设置则默认选中现有排序列表中的第一个模型。源码级实现模型过滤的完整逻辑封装在 lib/model-filter.ts由两个函数组成export function parseModelAllowlist(value: string | undefined): string[] { return (value ?? ) .split(,) .map(modelId modelId.trim()) .filter(Boolean); } export function filterModels( models: Model[], allowedModelIds: string[] ): Model[] { if (allowedModelIds.length 0) { return models; } const modelsById new Map(models.map(model [model.id, model])); const seenModelIds new Setstring(); return allowedModelIds.flatMap(modelId { const model modelsById.get(modelId); if (!model || seenModelIds.has(modelId)) { return []; } seenModelIds.add(modelId); return [model]; }); }parseModelAllowlist负责解析原始字符串按逗号切分、trim去除空白、过滤空项——这解释了为什么配置值允许写成 model-c, model-a 这样的带空格形式filterModels则先把后端模型列表转成id - Model的 Map再按允许列表顺序flatMap取模型不存在的 ID 会被静默跳过重复出现的 ID 只保留首个通过seenModelIds去重未配置时原样返回完整列表。在 Chat Playground 中app/chat-playground/page.tsx 于模块加载时调用parseModelAllowlist(process.env.NEXT_PUBLIC_OGX_UI_ALLOWED_MODELS)得到configuredModelIds模型列表加载完成后经filterModels过滤再填充下拉框首个模型即默认选中。单元测试验证过滤逻辑有对应的 Jest 测试 lib/model-filter.test.ts覆盖了三条核心断言可作为行为契约参考未配置时不改变模型列表parseModelAllowlist(undefined)返回空数组filterModels(models, [])原样返回所有模型按允许列表顺序输出输入 model-c, model-a 时结果顺序为model-c, model-a跳过未知模型 ID输入missing, model-b时未知的missing被忽略只保留model-b。这些测试与 README 描述的行为完全一致验证了过滤 保序 首项默认选中的实现语义。技术栈速览从 package.json 与源码目录可以勾勒出 UI 的整体技术构成框架Next.js 15.5App Routernext.config.ts开启output: standalone独立部署模式便于npx ogx-ui直接运行构建产物UI 组件shadcn/ui 风格组件components/ui底层依赖 Radix UISelect、Dialog、Dropdown、Tabs、Tooltip 等、class-variance-authority、clsx、tailwind-merge样式基于 Tailwind CSS 4客户端 SDK直接使用ogx-clientnpm 包与 OGX 后端交互模型类型来自ogx-client/resources/models辅助能力framer-motion动画、react-markdownremark-gfm渲染模型输出的 Markdown、shiki代码高亮、papaparseCSV 解析、sonnerToast 提示、next-themes明暗主题切换测试Jest Testing Library 做单元测试Playwright 做端到端测试参考 e2e/logs-table-scroll.spec.ts。常见问题排查要点启动后页面打不开确认端口未被占用若通过OGX_UI_PORT修改过端口浏览器需访问对应端口。下拉列表为空或模型缺失检查后端是否正常返回/v1/models默认http://localhost:8321再检查NEXT_PUBLIC_OGX_UI_ALLOWED_MODELS中的模型 ID 是否与后端注册的 ID 完全一致含 provider 前缀。模型列表顺序不符合预期请确认配置值中模型 ID 的书写顺序UI 严格按该顺序展示。认证按钮不可用确认已设置NEXTAUTH_URL、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET且回调地址与NEXTAUTH_URL匹配。小结OGX UI 为 OGX 后端提供了开箱即用的可视化入口开发场景下一条npm run dev即可在http://localhost:8322开始调试生产场景可选择npx ogx-ui或基于 Containerfile 的 Docker 镜像通过OGX_BACKEND_URL、OGX_UI_PORT与 NextAuth/GitHub OAuth 三组环境变量即可完成对接与认证而NEXT_PUBLIC_OGX_UI_ALLOWED_MODELS让团队可以把模型下拉列表收敛到一组白名单模型配合 lib/model-filter.ts 的保序过滤实现与对应单测行为可预期、可回归。上述内容均可在当前仓库对应文件中复现验证。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考