212 lines
6.6 KiB
Markdown
212 lines
6.6 KiB
Markdown
# 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 支持
|
||
- 更多资产管理功能
|
||
|
||
## 待完成的工作
|
||
|
||
### 高优先级
|
||
1. **前端依赖安装**
|
||
- 正在执行 npm install（需要较长时间）
|
||
- 安装完成后需要验证依赖完整性
|
||
|
||
2. **前端构建测试**
|
||
```bash
|
||
cd web
|
||
npm run build
|
||
```
|
||
- 可能需要修复 TypeScript 类型错误
|
||
- 可能需要调整 Tailwind CSS 配置
|
||
- 可能需要处理新的依赖兼容性问题
|
||
|
||
3. **核心功能对接验证**
|
||
- [ ] 用户登录流程
|
||
- [ ] 资产管理（CRUD）
|
||
- [ ] 会话连接（SSH/RDP/VNC）
|
||
- [ ] 终端操作
|
||
- [ ] 权限控制
|
||
|
||
### 中优先级
|
||
4. **缺失 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`)
|
||
|
||
5. **数据结构适配**
|
||
- 新前端可能期望不同的响应格式
|
||
- 需要检查并调整 API 响应结构
|
||
- 可能需要添加或修改字段
|
||
|
||
6. **静态资源处理**
|
||
- 配置后端服务前端静态文件
|
||
- 确保 `/api/logo` 等静态资源端点正常工作
|
||
- 处理 PWA 相关资源
|
||
|
||
### 低优先级
|
||
7. **性能优化**
|
||
- 实现新前端需要的分页、排序优化
|
||
- 添加缓存策略
|
||
- 优化大量数据的加载
|
||
|
||
8. **国际化支持**
|
||
- 配置 i18n 后端支持
|
||
- 添加多语言翻译文件
|
||
|
||
9. **测试与调试**
|
||
- 编写单元测试
|
||
- 进行端到端测试
|
||
- 性能测试
|
||
|
||
## 快速开始指南
|
||
|
||
### 1. 启动后端
|
||
```bash
|
||
cd next-terminal-1.3.9
|
||
# 编辑 config.yml 配置数据库等信息
|
||
go run main.go
|
||
```
|
||
|
||
### 2. 安装并启动前端（开发模式）
|
||
```bash
|
||
cd web
|
||
npm install # 如果尚未完成
|
||
npm run dev # 启动开发服务器，默认在 http://localhost:3000
|
||
```
|
||
|
||
### 3. 访问系统
|
||
- 前端地址: http://localhost:3000
|
||
- 后端 API: http://localhost:8088/api
|
||
- 首次访问会进入初始化页面，需要创建管理员账户
|
||
|
||
## 注意事项
|
||
|
||
1. **API 兼容性**: 新前端是为更新的后端版本设计的，部分高级功能暂时不可用
|
||
2. **渐进式实现**: 建议优先实现核心功能，然后逐步添加高级功能
|
||
3. **数据备份**: 在进行升级前务必备份数据库
|
||
4. **测试环境**: 建议先在测试环境中验证所有功能
|
||
5. **日志监控**: 升级后密切关注日志，及时发现和解决问题
|
||
|
||
## 下一步行动
|
||
|
||
1. 等待 npm install 完成
|
||
2. 尝试前端构建，修复可能的错误
|
||
3. 启动前后端服务，测试基本功能
|
||
4. 根据测试结果补充缺失的 API 端点
|
||
5. 逐步完善高级功能
|
||
|
||
---
|
||
|
||
**最后更新时间**: 2026-04-16
|
||
**当前状态**: 前端代码已替换，后端基础 API 已就绪，等待前端依赖安装完成
|