WebChat 设置与使用

July 7, 2026 · View on GitHub

HotPlex 内置 Web Chat UI 的安装、配置和开发指南

概述

WebChat 是 HotPlex Gateway 内置的 Web 聊天界面，使用 Next.js 16 + React 19 构建，通过 go:embed 嵌入到 Gateway 二进制中。无需额外部署，启动 Gateway 即可使用。

快速开始

生产模式

Gateway 启动后直接访问：

http://localhost:8888/

无需单独启动 WebChat 服务，静态文件已嵌入 Gateway 二进制。

开发模式

开发模式下支持热更新，前后端分离运行：

# 方式一：使用 Make 命令（推荐）
make dev              # 同时启动 Gateway + WebChat

# 方式二：手动启动
# 终端 1：启动 Gateway
make run              # 构建 + 运行 Gateway（端口 8888）

# 终端 2：启动 WebChat 开发服务器
cd webchat
pnpm dev              # 启动 Next.js dev server（端口 3000）

开发模式下访问 http://localhost:3000，Next.js dev server 提供热更新。

构建与嵌入

cd webchat
pnpm build            # 构建 Next.js 静态导出（输出到 out/）
                      # go:embed 会将 out/ 目录嵌入到 Gateway 二进制

构建产物位于 webchat/out/，Gateway 启动时通过 go:embed 读取这些文件并直接提供服务。

功能特性

聊天功能

流式输出：实时显示 AI 响应，使用 AEP v1 的 message.start / message.delta / message.end 三段式协议
Markdown 渲染：支持 GFM（GitHub Flavored Markdown），使用 react-markdown + remark-gfm
代码高亮：使用 highlight.js + rehype-highlight，支持多种编程语言
暗色模式：支持亮/暗主题切换

Session 管理

WebChat 提供 Session 面板（SessionPanel 组件）：

新建 Session：点击 "+" 按钮创建新对话
切换 Session：在侧边栏 Session 列表中点击切换
删除 Session：删除不需要的对话

Session 信息包括：

Session 标题（SessionInfo.Title）
创建时间
当前状态

交互功能

权限请求：AI 请求执行敏感操作时弹出审批对话框
问题交互：AI 提出选择题时显示选项卡片
Tool 调用展示：实时显示 AI 正在使用的工具

技术栈

依赖	版本	用途
Next.js	^16.2.4	React 框架
React	^19.2.5	UI 库
Tailwind CSS	^4.2.2	样式框架
@assistant-ui/react	^0.14.0	AI 聊天 UI 组件库
ai (Vercel AI SDK)	7.0.0-beta	AI SDK 集成
react-markdown	^10.1.0	Markdown 渲染
highlight.js	^11.11.1	代码语法高亮
framer-motion	^12.38.0	动画库
nuqs	^2.8.9	URL 状态管理

项目结构

webchat/
├── app/
│   ├── page.tsx                         # 主页面
│   ├── layout.tsx                       # 根布局
│   ├── error.tsx                        # 错误边界
│   ├── global-error.tsx                 # 全局错误边界
│   └── components/
│       ├── chat/
│       │   ├── ChatContainer.assistant-ui.tsx  # 聊天容器
│       │   ├── SessionPanel.tsx                 # Session 管理
│       │   └── NewSessionModal.tsx              # 新建 Session
│       └── ui/
│           └── CopyButton.tsx                   # 复制按钮
├── components/
│   ├── assistant-ui/                    # assistant-ui 自定义组件
│   └── icons.tsx                        # 图标组件
├── lib/
│   ├── adapters/                        # AEP 协议适配器
│   ├── ai-sdk-transport/                # Vercel AI SDK 传输层
│   ├── api/                             # Gateway API 客户端
│   ├── hooks/                           # React Hooks
│   ├── types/                           # TypeScript 类型定义
│   ├── config.ts                        # 配置
│   ├── highlight.ts                     # 高亮配置
│   ├── logger.ts                        # 日志
│   ├── utils.ts                         # 工具函数
│   └── tool-categories.ts               # Tool 分类
├── e2e/                                 # Playwright E2E 测试
├── package.json
├── tsconfig.json
├── next.config.mjs
└── playwright.config.ts

开发命令

cd webchat

# 安装依赖
pnpm install

# 开发服务器（热更新）
pnpm dev

# 生产构建
pnpm build

# Lint 检查
pnpm lint

# E2E 测试
pnpm test:e2e

与 Gateway 的集成

通信协议

WebChat 使用 AEP v1 协议通过 WebSocket 与 Gateway 通信：

建立 WebSocket 连接（ws://localhost:8888/ws）
发送 init 握手（包含 worker_type、client_caps）
接收 init_ack 确认
通过 input / message.delta / done 进行双向通信

go:embed 嵌入

Gateway 使用 Go 的 go:embed 机制将 WebChat 静态文件嵌入二进制：

//go:embed all:out
var StaticFS embed.FS

构建流程：pnpm build → webchat/out/ → go:embed → Gateway 二进制

认证（Authentication）

WebChat 多租户化后（spec ⑥）强制登录：废除匿名 webchat_user 身份，未登录用户自动重定向到 /login。

用户登录方式（登录成功后签发 HMAC Cookie）：

内建账号（spec ①）：username/password 本地账号，由 admin 通过邀请码（/api/admin/invitations）创建。首次部署尚无任何账号时，登录页根据 GET /api/auth/bootstrap-status 引导创建首个管理员。
企业 SSO（spec ④）：标准 OIDC Authorization Code flow + PKCE。在 oauth.providers[] 配置 IdP（Keycloak / Okta / Microsoft Entra ID / Google Workspace 等）后，登录页渲染对应 SSO 按钮，点击跳转 IdP 完成认证。详见配置参考 — oauth 与企业 IAM 对接指南。

HMAC Cookie 认证：登录成功后 Gateway 签发 HttpOnly、SameSite=None; Secure 的签名 cookie（7 天有效），后续 WebSocket 连接自动携带，无需配置 API Key。SameSite=None 支持跨域 WebChat 部署——但 SameSite=None cookie 会被跨站请求自动携带，故状态变更方法（POST/PATCH/DELETE）由同源校验中间件防护 CSRF（依据 Sec-Fetch-Site/Origin，不通过返回 403 FORBIDDEN）；HMAC 签名仅保证 cookie 完整性，本身不防 CSRF。跨域时网关须 HTTPS（浏览器拒绝非 Secure 的 SameSite=None cookie）。Cookie HMAC secret 持久化到 ~/.hotplex/data/cookie_secret.key（权限 0600），重启后仍有效。

跨域部署 / SDK 集成：WebChat 部署在不同域名，或客户端 SDK 直连 Gateway 时，回退到 API Key 认证：

HTTP Header X-API-Key
Query Parameter api_key（浏览器 WebSocket 的 CORS 兼容方案）
Init Envelope 延迟认证（auth.token 字段）

概述