6.6 KiB
6.6 KiB
Next Terminal 前端升级对接文档
已完成的工作
1. 前端代码替换 ✅
- 从 GitHub 克隆了最新的 next-terminal 前端代码（v2.6.6+）
- 替换了旧的前端代码（v1.3.9）
- 备份了旧前端代码到
web-backup目录
2. 前端配置修改 ✅
- 更新了
package.json（新依赖：Vite, TypeScript, Tailwind CSS, Ant Design 5 等） - 配置了
vite.config.ts：- 添加开发服务器代理（/api -> localhost:8088）
- 设置前端端口为 3000
- 配置 PWA 支持
- 修改了 API 基础 URL 配置，使用相对路径
/api - 配置 WebSocket URL 指向后端 8088 端口
3. 后端路由重构 ✅
- 重构了
server/app/server.go的路由配置 - 添加了
/api/admin前缀以匹配新前端的 API 调用格式 - 所有 API 路由现在都位于
/api/admin/路径下 - 修复了 access-token 删除接口的路径参数问题
4. 新增后端 API 端点 ✅
创建了 server/api/setup.go 文件，包含以下新端点：
初始化相关
GET /api/admin/setup-status- 检查系统是否需要初始化POST /api/admin/setup-user- 创建初始管理员用户
登录认证相关
GET /api/admin/login-status- 获取当前登录状态POST /api/admin/validate-totp- 验证 TOTP 验证码GET /api/admin/account/password-policy- 获取密码策略配置
5. 数据模型扩展 ✅
- 在
dto/auth.go中添加了UserCreate结构体
6. 后端编译验证 ✅
- Go 后端代码编译成功，无错误
技术栈变化
旧版本 (v1.3.9)
- 构建工具: Create React App (react-scripts)
- UI 框架: Ant Design 4.x
- 语言: JavaScript (JSX)
- 状态管理: React Query 3.x
- 路由: React Router 6
- 终端: xterm 4.x
新版本 (latest)
- 构建工具: Vite 7.x
- UI 框架: Ant Design 5.x + Tailwind CSS 4.x
- 语言: TypeScript (TSX)
- 状态管理: React Query 5.x + Jotai
- 路由: React Router 7.x
- 终端: @xterm/xterm 5.x
- 新增功能:
- i18n 国际化支持
- PWA 支持
- WebAuthn 认证
- OIDC 支持
- 更多资产管理功能
待完成的工作
高优先级
-
前端依赖安装
- 正在执行 npm install（需要较长时间）
- 安装完成后需要验证依赖完整性
-
前端构建测试
cd web npm run build- 可能需要修复 TypeScript 类型错误
- 可能需要调整 Tailwind CSS 配置
- 可能需要处理新的依赖兼容性问题
-
核心功能对接验证
- 用户登录流程
- 资产管理（CRUD）
- 会话连接（SSH/RDP/VNC）
- 终端操作
- 权限控制
中优先级
-
缺失 API 端点实现
新前端包含许多旧后端不支持的功能，需要逐步实现：
用户管理增强
- 部门管理 API (
/departments) - 用户部门关联 API
- LDAP 同步 API (
/sync-from-ldap) - 用户导入 API (
/import) - 用户客户端证书 API (
/client-cert) - 批量重置密码/TOTP API
资产管理增强
- 资产分组 API (
/groups,/tree) - 资产排序 API (
/sort) - 资产网关统一接口 (
/change-gateway) - 资产连接检测 API (
/checking) - 资产解密 API (
/decrypted) - Logo 管理 API (
/logos)
新功能模块
- 数据库资产管理 (
database-assets) - 网站资产管理 (
websites) - 证书管理 (
certificates) - DNS 提供商管理 (
dns-providers) - 命令过滤器 (
command-filters,command-filter-rules) - 代码片段管理 (
snippets,snippet-users) - Agent 网关管理 (
agent-gateways,agent-gateway-tokens) - SSH 网关管理 (
ssh-gateways) - 网关组管理 (
gateway-groups) - 计划任务管理 (
scheduled-tasks) - 替代旧的 jobs - 操作日志 (
operation-logs) - 访问日志 (
access-logs) - 文件系统日志 (
filesystem-logs) - Shell 助手 (
shell-assistant) - 会话命令记录 (
session-commands) - 数据库 SQL 日志 (
database-sql-logs) - 数据库工单 (
db-work-orders)
安全与认证
- WebAuthn API (
/webauthn/*) - 安全令牌 API (
/security-token/*) - OIDC 客户端管理 (
oidc-clients) - OIDC Server 功能 (
/oidc/server/*) - 登录锁定管理 (
login-locked) - 企业微信集成 (
wechat-work)
系统设置
- 许可证管理 (
license) - Logo 管理 (
logo) - 品牌/自定义设置 (
branding) - 匿名访问设置 (
anonymous) - Portal 页面设置 (
portal) - 访问设置 (
access-setting)
- 部门管理 API (
-
数据结构适配
- 新前端可能期望不同的响应格式
- 需要检查并调整 API 响应结构
- 可能需要添加或修改字段
-
静态资源处理
- 配置后端服务前端静态文件
- 确保
/api/logo等静态资源端点正常工作 - 处理 PWA 相关资源
低优先级
-
性能优化
- 实现新前端需要的分页、排序优化
- 添加缓存策略
- 优化大量数据的加载
-
国际化支持
- 配置 i18n 后端支持
- 添加多语言翻译文件
-
测试与调试
- 编写单元测试
- 进行端到端测试
- 性能测试
快速开始指南
1. 启动后端
cd next-terminal-1.3.9
# 编辑 config.yml 配置数据库等信息
go run main.go
2. 安装并启动前端（开发模式）
cd web
npm install # 如果尚未完成
npm run dev # 启动开发服务器，默认在 http://localhost:3000
3. 访问系统
- 前端地址: http://localhost:3000
- 后端 API: http://localhost:8088/api
- 首次访问会进入初始化页面，需要创建管理员账户
注意事项
- API 兼容性: 新前端是为更新的后端版本设计的，部分高级功能暂时不可用
- 渐进式实现: 建议优先实现核心功能，然后逐步添加高级功能
- 数据备份: 在进行升级前务必备份数据库
- 测试环境: 建议先在测试环境中验证所有功能
- 日志监控: 升级后密切关注日志，及时发现和解决问题
下一步行动
- 等待 npm install 完成
- 尝试前端构建，修复可能的错误
- 启动前后端服务，测试基本功能
- 根据测试结果补充缺失的 API 端点
- 逐步完善高级功能
最后更新时间: 2026-04-16 当前状态: 前端代码已替换，后端基础 API 已就绪，等待前端依赖安装完成