前端配置

Web 管理面板的配置与使用说明。

访问面板

获取登录链接

在机器人对话中发送：

#ai管理面板

机器人会返回一个带临时 token 的登录链接。

登录方式

1. 点击链接自动登录
2. 登录后会设置 Cookie，后续访问无需重复登录
3. Cookie 有效期默认 24 小时

Web 服务配置

基础配置

web:
  enabled: true           # 启用 Web 服务
  port: 3000              # 监听端口
  host: "0.0.0.0"         # 监听地址，0.0.0.0 允许外部访问

端口配置

web:
  port: 3000              # 默认端口
  # port: 8080            # 如 3000 被占用，可改用其他端口

端口冲突

如果端口被占用，插件会启动失败。请检查端口占用情况或更换端口。

# 检查端口占用
netstat -tlnp | grep 3000

TRSS 共享端口

如果使用 TRSS-Yunzai，可以共享 Yunzai 的端口：

web:
  sharePort: true         # 使用 Yunzai 的端口
  basePath: /chatai       # 路径前缀

访问地址变为：http://your-server:yunzai-port/chatai

安全配置

访问控制

web:
  security:
    # 允许访问的 IP 白名单（空则允许所有）
    allowedIPs: []
    
    # 启用 HTTPS（需要证书）
    https:
      enabled: false
      cert: /path/to/cert.pem
      key: /path/to/key.pem

Token 配置

web:
  auth:
    tokenExpiry: 86400000   # Token 有效期（毫秒），默认 24 小时
    cookieSecure: false     # 生产环境建议设为 true（需 HTTPS）
    cookieHttpOnly: true    # 防止 XSS 攻击

限流配置

web:
  rateLimit:
    windowMs: 60000         # 时间窗口（毫秒）
    maxRequests: 60         # 最大请求数

面板功能

首页仪表盘

• 系统状态概览
• 对话统计
• 工具调用统计
• 渠道健康状态

渠道管理

功能	说明
添加渠道	配置新的 API 渠道
编辑渠道	修改渠道参数
测试连接	验证 API Key 和网络连通性
启用/禁用	临时禁用渠道
删除渠道	移除渠道配置

预设管理

功能	说明
查看预设	浏览所有预设
编辑预设	修改 System Prompt
复制预设	基于现有预设创建新预设
导入/导出	JSON 格式导入导出

工具管理

功能	说明
内置工具	按类别查看和启用/禁用
自定义工具	上传和管理 JS 工具
MCP 服务器	配置外部 MCP 服务器
调用日志	查看工具执行历史

群组配置

• 按群配置预设
• 按群配置触发方式
• 按群配置工具权限

用户管理

• 查看用户列表
• 管理用户权限
• 查看用户对话统计

前端开发

本地开发

cd plugins/chatgpt-plugin/frontend
pnpm install
pnpm dev

技术栈

技术	说明
React 19	UI 框架
Vite	构建工具
TailwindCSS	样式框架
shadcn/ui	组件库
Lucide	图标库
React Query	数据请求

构建生产版本

pnpm build

构建产物输出到 resources/web/ 目录。

自定义主题

web:
  theme:
    primaryColor: "#6366f1"   # 主题色
    darkMode: auto            # auto/light/dark

API 调用

前端通过 REST API 与后端通信：

// 获取渠道列表
const response = await fetch('/api/config/channels', {
  credentials: 'include'  // 携带 Cookie
})
const { data } = await response.json()

// 更新配置
await fetch('/api/config', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    path: 'trigger.prefix',
    value: '#ai'
  })
})

常见问题

无法访问面板

1. 检查 Web 服务是否启用：web.enabled: true
2. 检查端口是否正确
3. 检查防火墙设置
4. 如果是远程服务器，确保 host: "0.0.0.0"

登录失败

1. 临时 token 可能已过期，重新获取
2. 检查时钟是否同步
3. 清除浏览器 Cookie 后重试

配置不生效

1. 部分配置修改后需要重启插件
2. 检查配置格式是否正确
3. 查看控制台是否有报错

下一步

• API 文档 - REST API 参考
• 渠道配置 - 渠道详细配置