扣子编程内测体验开发的SSH和文件浏览器管理系统（网站首页提供源码打包下载）

NexusBridge - 灵犀桥 - 远程设备管理系统需求说明

https://7tjmkcrykh.coze.site/
https://code.coze.cn/home

文档信息

文档名称：NexusBridge 需求说明
系统名称：NexusBridge（灵犀桥）
版本：v2.1
作者：泡鱼
联系方式：chenweidelphi@qq.com
更新日期：2026-01-12
文档状态：正式版本

1. 项目概述

1.1 项目背景

随着云计算和容器化技术的普及，越来越多的服务器部署在私有网络（VPC、内网）中，无法直接通过公网SSH访问。NexusBridge（灵犀桥）是一个基于Web的远程设备管理系统，提供两种设备连接模式：

直连模式：通过 ssh2 库直接连接公网设备，使用标准的 SSH 协议
终端代理模式：通过 Go 语言编写的终端代理服务穿透私有网络，使用 HTTP 长轮询协议

系统提供 WebSSH 终端和 Web 文件管理功能，支持 SFTP 协议进行文件操作，集成 Monaco Editor 提供专业的代码编辑体验。

系统名称：NexusBridge（灵犀桥）
作者：泡鱼
联系方式：chenweidelphi@qq.com

1.2 项目目标

统一的远程访问平台：提供安全的WebSSH服务和Web文件管理功能，支持直连和终端代理两种模式
前后端分离架构：采用显示和服务分离的方式，前端通过HTTP API调用后端服务
统一服务架构：HTTP服务和WebSocket信令服务共用一个端口（5000），统一管理，简化部署
多用户多设备管理：支持多用户、多设备的集中管理，通过JWT token进行身份认证
高性能通信：
- 终端代理模式采用HTTP长轮询实现实时双向通信
- 直连模式使用 ssh2 库直接建立SSH连接
现代化界面：提供类似1Panel的后台管理风格，支持深色/浅色主题切换，多页签操作
安全认证机制：
- 使用JWT token进行用户认证
- user_token用于API调用和终端代理认证
- 终端代理使用用户的user_token连接到Web服务器，通过device_id标识设备
SFTP文件管理：使用标准的SFTP协议进行文件操作，提升安全性和可靠性
专业代码编辑：集成Monaco Editor提供VSCode级别的代码编辑体验
开发体验优化：优化开发环境性能，减少频繁编译，提升开发效率

1.3 适用范围

本需求说明适用于项目开发、测试、验收等各个阶段。

2. 系统架构

2.1 整体架构设计

本系统采用分布式、模块化的三层架构设计：

2.2 连接模式对比

2.2.1 直连模式（公网设备）

2.2.2 终端代理模式（私网设备）

3. 功能模块

3.1 用户认证模块

3.1.1 用户注册

功能描述：新用户可以注册账号
输入：用户名、密码（bcrypt加密）、邮箱（可选）
输出：注册成功/失败信息
API：POST /api/auth/register
特殊功能：注册成功后自动创建名为"缺省"的默认Token，有效期3年

3.1.2 用户登录

功能描述：用户使用用户名和密码登录
输入：用户名、密码
输出：JWT token（有效期24小时）
API：POST /api/auth/login

3.1.3 用户信息管理

功能描述：用户可以查看和编辑个人信息，修改登录密码
输入：用户信息、新密码、邮箱（可选）、头像URL（可选）
输出：更新结果
API：GET/PUT /api/user/me
优化：邮箱改为可选，移除当前密码输入，新密码非可选

3.2 设备管理模块

3.2.1 设备CRUD操作

功能描述：用户可以创建、查看、编辑、删除设备
数据字段：
- 设备ID（device_id）
- 设备名称
- 设备类型（直连模式/终端代理模式）
- SSH配置（host, port, username, password）
- 用户ID（userId）
功能增强：
- 直连模式和终端代理模式设备都支持SSH配置存储
- 所有SSH配置从数据库读取
API：
- POST /api/devices - 创建设备
- GET /api/devices - 获取用户设备列表
- PUT /api/devices/[id] - 编辑设备
- DELETE /api/devices/[id] - 删除设备

3.2.2 设备在线状态

功能描述：实时显示设备在线状态
检测方式：
- 直连模式：尝试SSH连接测试
- 代理模式：检查终端代理连接状态
UI优化：
- 设备列表显示在线状态小圆点（绿色=在线，红色=离线）
- 支持手动刷新状态
- 自动刷新（每30秒）
API：
- GET /api/devices/online - 获取所有设备在线状态
- GET /api/device/[deviceId]/online - 获取单个设备在线状态

3.3 User Token管理模块

3.3.1 Token CRUD操作

功能描述：用户可以创建、查看、编辑、删除user_token
数据字段：
- Token名称
- Token描述
- Token值（自动生成，UUID格式）
- 过期时间（默认3年）
- 用户ID（userId）
关系：用户和user_token是一对多关系
安全性：用户只能删除和编辑自己的Token
API：
- POST /api/tokens - 创建Token
- GET /api/tokens - 获取用户Token列表
- PUT /api/tokens/[id] - 编辑Token（名称、描述）
- DELETE /api/tokens/[id] - 删除Token

3.4 WebSSH终端模块

3.4.1 终端连接

功能描述：建立SSH连接，提供Web终端界面
支持模式：
- 直连模式：使用ssh2库直接连接
- 代理模式：通过终端代理间接连接
组件：xterm.js（终端模拟）
特性：
- 每个页签创建独立的SSH连接
- 支持终端颜色、快捷键
- 自动适配终端大小
- 使用HTTP长轮询实现实时通信（代理模式）
- 页签切换不重新连接（使用CSS hidden控制显示）
API：
- POST /api/nexusbridge/terminal/ssh-connect - 直连模式连接
- POST /api/nexusbridge/terminal/proxy-input - 代理模式发起连接
- POST /api/nexusbridge/terminal/ssh-poll - 直连模式轮询
- POST /api/nexusbridge/terminal/proxy-poll - 代理模式轮询
- POST /api/nexusbridge/terminal/ssh-input - 直连模式输入
- POST /api/nexusbridge/terminal/proxy-input - 代理模式输入
- POST /api/nexusbridge/terminal/ssh-disconnect - 直连模式断开
- POST /api/nexusbridge/terminal/proxy-input - 代理模式断开（disconnect类型）

3.4.2 终端交互

功能描述：支持终端输入输出、多页签独立连接
优化：
- 页签切换不丢失历史输出
- 每个页签独立SSH连接
- 自动检测连接模式并显示（直连模式/终端代理）
性能优化：
- 代理模式轮询间隔：500ms
- 直连模式轮询间隔：200ms
- 输入响应延迟优化

3.5 Web文件管理模块

3.5.1 SFTP文件操作

功能描述：通过SFTP协议进行文件和目录操作
支持模式：
- 直连模式：使用ssh2-sftp-client
- 代理模式：已禁用（终端代理模式不支持文件管理）
操作类型：
- 文件列表浏览
- 文件下载（支持所有文件类型）
- 文件上传
- 文件删除
- 目录创建
- 文件重命名
- 文本文件在线编辑
UI优化：
- 终端代理模式的文件管理按钮禁用（灰色，不可点击）
- 文件列表选中状态增强（蓝色左边框）
- 面包屑导航优化（overflow处理）
- 下载和删除按钮移至文件列表每行操作列
API：
- POST /api/nexusbridge/files/connect - 直连模式连接
- POST /api/nexusbridge/files/execute - 直连模式执行操作
- POST /api/nexusbridge/files/disconnect - 断开连接

3.5.2 文件编辑器

功能描述：在线编辑文本文件
组件：Monaco Editor（VSCode编辑器核心）
特性：
- 支持60+种文件类型语法高亮
- 自动补全、智能提示
- 快捷键支持
- 行号显示
- 深色/浅色主题
界面风格：独立页面打开，类似宝塔BT面板
功能：
- 文件树导航（递归显示，动态加载）
- 代码编辑
- 保存到服务器
- 中文乱码修复（TextDecoder）
优化：
- 编辑器页面自己创建独立SSH连接
- 支持的文本扩展名：txt, js, ts, jsx, tsx, py, java, go, rs, c, cpp, h, php, rb, sh, bash, yaml, yml, json, xml, html, htm, css, scss, less, md, markdown, sql, conf, ini, cfg, properties, env, gitignore, dockerfile, makefile, readme, log等40+种

3.6 终端代理模块

3.6.1 代理注册

功能描述：终端代理启动时注册到Web服务器
输入：device_id、user_token
输出：proxy_id
功能增强：
- 支持数据库SSH配置读取
- 自动获取私网设备的SSH参数
API：POST /api/nexusbridge/proxy/register

3.6.2 代理通信

功能描述：通过HTTP长轮询与Web服务器通信
通信模式：
- 代理主动轮询：POST /api/nexusbridge/proxy/poll
- 代理推送输出：POST /api/nexusbridge/proxy/output
- 浏览器发送输入：POST /api/nexusbridge/terminal/proxy-input
- 浏览器轮询输出：POST /api/nexusbridge/terminal/proxy-poll
消息类型：
- 终端消息：ssh_connect, ssh_input, ssh_output, ssh_disconnect
- 文件消息：file_connect, file_command, file_response, file_disconnect（已禁用）
性能优化：
- 轮询间隔：100ms（从1000ms优化）
- 日志级别：info（从debug优化）
- 高频日志输出已禁用

3.6.3 代理下载

功能描述：提供多平台终端代理程序下载
支持平台：
- Linux AMD64（6.8M → 2.2M，UPX压缩68.69%）
- Linux ARM64（6.4M → 1.9M，UPX压缩71.41%）
- macOS AMD64（7.0M，未压缩，代码签名要求）
- macOS ARM64（6.6M，未压缩，代码签名要求）
- Windows AMD64（7.0M → 2.2M，UPX压缩69.36%）
下载方式：
- Web页面下载（首页）
- API下载：GET /downloads/{filename}（静态资源）
优化：
- 使用public静态资源托管（避免API绝对路径问题）
- 动态编译和压缩

3.6.4 配置文件生成

功能描述：动态生成终端代理配置文件
配置内容：
- device_id
- user_token
- web_server（host、port、protocol、api_path_prefix）
下载方式：
- 首页终端代理下载卡片
- API下载：GET /api/nexusbridge/download/config?device_id=xxx
功能增强：
- 设备管理页面"查看配置"按钮（弹窗预览、编辑、下载）
- host自动使用浏览器访问域名

4. 数据库设计

4.1 数据库选型

数据库：SQLite
ORM框架：Drizzle ORM
客户端：@libsql/client
文件位置：data/data.db

4.2 数据表结构

4.2.1 users表（用户表）

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT NOT NULL UNIQUE,
  password TEXT NOT NULL,  -- bcrypt加密
  email TEXT UNIQUE,       -- 可选
  avatarUrl TEXT,         -- 可选
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

4.2.2 devices表（设备表）

CREATE TABLE devices (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  userId INTEGER NOT NULL,
  deviceId TEXT NOT NULL UNIQUE,  -- 设备唯一标识
  deviceName TEXT NOT NULL,
  isPublic INTEGER DEFAULT 0,    -- 0=终端代理模式, 1=直连模式

  -- SSH配置（两种模式都需要）
  sshHost TEXT,
  sshPort INTEGER DEFAULT 22,
  sshUsername TEXT,
  sshPassword TEXT,

  description TEXT,              -- 可选

  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP,

  FOREIGN KEY (userId) REFERENCES users(id)
);

4.2.3 tokens表（user_token表）

CREATE TABLE tokens (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  userId INTEGER NOT NULL,
  tokenName TEXT NOT NULL,
  tokenValue TEXT NOT NULL UNIQUE,  -- UUID格式
  description TEXT,                  -- 可选
  expiresAt DATETIME NOT NULL,       -- 默认3年

  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,

  FOREIGN KEY (userId) REFERENCES users(id)
);

4.3 数据关系

用户 → 设备：一对多关系（一个用户可以拥有多个设备）
用户 → user_token：一对多关系（一个用户可以创建多个token）
数据隔离：每个用户只能访问自己的设备和token

5. API接口文档

5.1 认证接口

5.1.1 用户注册

POST /api/auth/register
Content-Type: application/json

请求体：
{
  "username": "user1",
  "password": "password123",
  "confirmPassword": "password123",
  "email": "user1@example.com"  // 可选
}

响应：
{
  "success": true,
  "message": "注册成功",
  "user": {
    "id": 1,
    "username": "user1",
    "email": "user1@example.com"
  }
}

5.1.2 用户登录

POST /api/auth/login
Content-Type: application/json

请求体：
{
  "username": "user1",
  "password": "password123"
}

响应：
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "user1"
  }
}

5.1.3 获取当前用户信息

GET /api/user/me
Authorization: Bearer {token}

响应：
{
  "id": 1,
  "username": "user1",
  "email": "user1@example.com",
  "avatarUrl": "https://example.com/avatar.jpg",
  "createdAt": "2026-01-12T00:00:00Z"
}

5.1.4 更新用户信息

PUT /api/user/me
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "email": "newemail@example.com",  // 可选
  "avatarUrl": "https://example.com/new-avatar.jpg",  // 可选
  "newPassword": "newpassword123"  // 可选，不修改则不填
}

响应：
{
  "success": true,
  "user": {
    "id": 1,
    "username": "user1",
    "email": "newemail@example.com",
    "avatarUrl": "https://example.com/new-avatar.jpg"
  }
}

5.2 设备管理接口

5.2.1 获取设备列表

GET /api/devices
Authorization: Bearer {token}

响应：
{
  "devices": [
    {
      "id": 1,
      "userId": 1,
      "deviceId": "device_123",
      "deviceName": "测试服务器",
      "isPublic": 1,  // 1=直连模式, 0=终端代理模式
      "sshHost": "192.168.1.100",
      "sshPort": 22,
      "sshUsername": "root",
      "online": true
    }
  ]
}

5.2.2 创建设备

POST /api/devices
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "deviceName": "测试服务器",
  "isPublic": 1,  // 直连模式
  "sshHost": "192.168.1.100",
  "sshPort": 22,
  "sshUsername": "root",
  "sshPassword": "password",
  "description": "测试用服务器"  // 可选
}

响应：
{
  "success": true,
  "device": {
    "id": 1,
    "deviceId": "device_123",
    "deviceName": "测试服务器",
    "isPublic": 1,
    "sshHost": "192.168.1.100",
    "sshPort": 22,
    "sshUsername": "root",
    ...
  }
}

5.2.3 编辑设备

PUT /api/devices/{id}
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceName": "新名称",
  "sshPassword": "new_password",
  "description": "更新后的描述"
}

响应：
{
  "success": true,
  "device": {
    "id": 1,
    ...
  }
}

5.2.4 删除设备

DELETE /api/devices/{id}
Authorization: Bearer {token}

响应：
{
  "success": true,
  "message": "设备已删除"
}

5.2.5 获取设备在线状态

GET /api/devices/online
Authorization: Bearer {token}

响应：
{
  "status": [
    {
      "deviceId": "device_123",
      "online": true
    }
  ]
}

5.2.6 获取设备信息

GET /api/device/{deviceId}/info
Authorization: Bearer {token}

响应：
{
  "success": true,
  "device": {
    "id": 1,
    "deviceId": "device_123",
    "deviceName": "测试服务器",
    "isPublic": 1,
    "sshHost": "192.168.1.100",
    "sshPort": 22,
    "sshUsername": "root",
    "sshPassword": "password",
    "description": "测试用服务器"
  }
}

5.3 Token管理接口

5.3.1 获取Token列表

GET /api/tokens
Authorization: Bearer {token}

响应：
{
  "tokens": [
    {
      "id": 1,
      "tokenName": "工作电脑",
      "tokenValue": "uuid-xxx-xxx",
      "description": "用于工作电脑",
      "expiresAt": "2029-01-12T00:00:00Z"
    }
  ]
}

5.3.2 创建Token

POST /api/tokens
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "tokenName": "新Token",
  "description": "描述"
}

响应：
{
  "success": true,
  "token": {
    "id": 2,
    "tokenName": "新Token",
    "tokenValue": "uuid-xxx-xxx",
    "description": "描述",
    "expiresAt": "2029-01-12T00:00:00Z"
  }
}

5.3.3 编辑Token

PUT /api/tokens/{id}
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "tokenName": "新名称",
  "description": "新描述"
}

响应：
{
  "success": true,
  "token": {
    "id": 2,
    "tokenName": "新名称",
    ...
  }
}

5.3.4 删除Token

DELETE /api/tokens/{id}
Authorization: Bearer {token}

响应：
{
  "success": true,
  "message": "Token已删除"
}

5.4 终端接口（直连模式）

5.4.1 创建SSH连接

POST /api/nexusbridge/terminal/ssh-connect
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "sshConfig": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "password": "password"
  }
}

响应：
{
  "success": true,
  "connectionId": "ssh_connection_123"
}

5.4.2 轮询终端输出

POST /api/nexusbridge/terminal/ssh-poll
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "connectionId": "ssh_connection_123"
}

响应：
{
  "output": "root@server:~#",
  "hasMore": false
}

5.4.3 发送终端输入

POST /api/nexusbridge/terminal/ssh-input
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "connectionId": "ssh_connection_123",
  "input": "ls -la\n"
}

响应：
{
  "success": true
}

5.4.4 断开SSH连接

POST /api/nexusbridge/terminal/ssh-disconnect
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "connectionId": "ssh_connection_123"
}

响应：
{
  "success": true
}

5.5 终端接口（代理模式）

5.5.1 发起终端连接

POST /api/nexusbridge/terminal/proxy-input
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "type": "ssh_connect",
  "sshConfig": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "password": "password"
  }
}

响应：
{
  "success": true
}

5.5.2 发送终端输入

POST /api/nexusbridge/terminal/proxy-input
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "type": "ssh_input",
  "data": "ls -la\n"
}

响应：
{
  "success": true
}

5.5.3 轮询终端输出

POST /api/nexusbridge/terminal/proxy-poll
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123"
}

响应：
{
  "messages": [
    {
      "type": "ssh_output",
      "data": "root@server:~#"
    }
  ]
}

5.5.4 断开终端连接

POST /api/nexusbridge/terminal/proxy-input
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "type": "ssh_disconnect"
}

响应：
{
  "success": true
}

5.6 文件管理接口（直连模式）

5.6.1 创建SFTP连接

POST /api/nexusbridge/files/connect
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "sshConfig": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "password": "password"
  }
}

响应：
{
  "success": true,
  "connectionId": "sftp_connection_123"
}

5.6.2 执行文件操作

POST /api/nexusbridge/files/execute
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "connectionId": "sftp_connection_123",
  "action": "list",
  "path": "/root"
}

响应：
{
  "success": true,
  "files": [
    {
      "name": "test.txt",
      "type": "file",
      "size": 1024,
      "modified": "2026-01-12T00:00:00Z"
    }
  ]
}

下载文件：
{
  "connectionId": "sftp_connection_123",
  "action": "download",
  "path": "/root/test.txt"
}

响应：
{
  "success": true,
  "content": "base64_encoded_content"
}

5.6.3 断开SFTP连接

POST /api/nexusbridge/files/disconnect
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "connectionId": "sftp_connection_123"
}

响应：
{
  "success": true
}

5.7 终端代理接口

5.7.1 代理注册

POST /api/nexusbridge/proxy/register
Content-Type: application/json

请求体：
{
  "deviceId": "device_123",
  "userToken": "user_token_value"
}

响应：
{
  "success": true,
  "proxyId": "proxy_123"
}

5.7.2 代理轮询

POST /api/nexusbridge/proxy/poll
Content-Type: application/json

请求体：
{
  "proxyId": "proxy_123"
}

响应：
{
  "messages": [
    {
      "type": "ssh_connect",
      "sshConfig": {...}
    }
  ]
}

5.7.3 代理推送输出

POST /api/nexusbridge/proxy/output
Content-Type: application/json

请求体：
{
  "proxyId": "proxy_123",
  "message": {
    "type": "ssh_output",
    "data": "output data"
  }
}

响应：
{
  "success": true
}

5.7.4 代理断开连接

POST /api/nexusbridge/proxy/disconnect
Content-Type: application/json

请求体：
{
  "proxyId": "proxy_123"
}

响应：
{
  "success": true
}

5.8 下载接口

5.8.1 下载终端代理程序

GET /downloads/device-proxy-linux-amd64

响应：
二进制文件流

支持平台：
- device-proxy (通用版本)
- device-proxy-linux-amd64
- device-proxy-linux-arm64
- device-proxy-darwin-amd64
- device-proxy-darwin-arm64
- device-proxy-windows-amd64.exe

5.8.2 下载配置文件

GET /api/nexusbridge/download/config?device_id=device_123
Authorization: Bearer {token}

响应：
YAML格式配置文件

device_id: device_123
user_token: user_token_value
web_server:
  host: example.com
  port: 443
  protocol: https
  api_path_prefix: /api/nexusbridge

5.9 调试接口

5.9.1 查看连接状态

GET /api/debug/connections
Authorization: Bearer {token}

响应：
{
  "connections": [
    {
      "connectionId": "ssh_connection_123",
      "deviceId": "device_123",
      "type": "terminal",
      "isPublic": true,
      "refCount": 1
    }
  ]
}

5.9.2 查看代理连接状态

GET /api/debug/proxy-connections

响应：
{
  "proxyConnections": [
    {
      "proxyId": "proxy_123",
      "deviceId": "device_123",
      "connectedAt": "2026-01-12T00:00:00Z"
    }
  ]
}

5.9.3 查看消息队列状态

GET /api/debug/queue-status

响应：
{
  "queues": {
    "proxy_123": {
      "inputQueue": 5,
      "outputQueue": 3
    }
  }
}

6. 技术栈

6.1 前端技术栈

技术	版本	用途
Next.js	16.0.10	React框架，SSR支持
React	19.2.1	UI框架
TypeScript	5.9.3	类型安全
Tailwind CSS	4.1.18	CSS框架
xterm	5.3.0	终端模拟
xterm-addon-fit	0.8.0	终端自适应
xterm-addon-web-links	0.9.0	终端链接支持
react-markdown	10.1.0	Markdown渲染
mermaid	11.12.2	流程图渲染
remark-gfm	4.0.1	Markdown GFM支持
rehype-highlight	7.0.2	代码高亮
rehype-raw	7.0.0	HTML支持
highlight.js	11.11.1	语法高亮
@monaco-editor/react	4.7.0	代码编辑器
monaco-editor	0.55.1	Monaco核心
marked	17.0.1	Markdown解析
drizzle-zod	0.8.3	Schema验证
zod	4.3.5	数据验证

6.2 后端技术栈

技术	版本	用途
Node.js	24.11.1	运行环境
@libsql/client	0.17.0	SQLite客户端
drizzle-orm	0.45.1	ORM框架
drizzle-kit	0.31.8	数据库迁移工具
bcrypt	6.0.0	密码加密
jsonwebtoken	9.0.3	JWT认证
ssh2	1.17.0	SSH客户端（直连模式）
ssh2-sftp-client	12.0.1	SFTP客户端（直连模式）
ws	8.19.0	WebSocket支持（调试用）
coze-coding-dev-sdk	0.5.5	对象存储集成

6.3 终端代理技术栈（Go）

技术	版本	用途
Go	1.22.2	编程语言
golang.org/x/crypto/ssh	latest	SSH客户端
net/http	标准库	HTTP客户端（长轮询）

6.4 开发工具

工具	版本	用途
pnpm	10.26.0	包管理器
ESLint	9.39.2	代码检查
ts-node	10.9.2	TypeScript运行
UPX	4.2.2	二进制压缩
node-loader	2.1.0	原生模块加载

7. 部署架构

7.1 部署环境

7.1.1 开发环境

操作系统：Linux/macOS/Windows
Node.js：v24.x
Go：v1.22.2+（用于编译终端代理）
端口：5000（HTTP服务）
启动命令：pnpm dev
性能优化：
- 文件监听忽略日志、缓存等目录
- 减少webpack日志输出
- 优化Go代理日志级别

7.1.2 生产环境

平台：Coze FaaS
Node.js：v24.x
端口：5000
启动命令：NODE_ENV=production npx next start -p 5000
数据库：SQLite（data/data.db）

7.2 部署流程

7.2.1 Web服务部署

7.2.2 终端代理部署

7.3 配置文件

7.3.1 .coze 配置文件

[project]
entrypoint = "package.json"
requires = ["nodejs-24"]

[dev]
build = ["bash", ".cozeproj/scripts/dev_build.sh"]
run = ["bash", ".cozeproj/scripts/dev_run.sh"]

[deploy]
build = ["bash", "-c", "pnpm install && pnpm rebuild cpu-features bcrypt ssh2"]
run = ["bash", ".cozeproj/scripts/deploy_run.sh"]

7.3.2 终端代理配置文件（config.yaml）

device_id: device_123
user_token: user_token_value
web_server:
  host: 127.0.0.1  # 强制使用IPv4
  port: 5000
  protocol: http
  api_path_prefix: nexusbridge
  poll_interval: 200  # 毫秒
  connect_timeout: 10  # 秒

logging:
  level: info  # info, debug, warn, error
  file: ""
  format: text

8. 界面设计

8.1 整体风格

设计风格：参考1Panel，深色主题为主
主题支持：深色/浅色主题切换
布局：侧边栏导航 + 主内容区

8.2 主要页面

8.2.1 首页

三栏布局：
- 左侧：登录/注册（横向布局）
- 中间：软件功能介绍（直连模式 vs 终端代理模式）
- 右侧：终端代理下载（多平台）
软件功能卡片（核心功能区）
版权信息

8.2.2 Dashboard（工作台）

用户信息卡片
设备统计
快速访问按钮（工作台、设备列表、用户管理、用户私钥）
操作按钮改为<a>标签，新标签页打开

8.2.3 设备管理页面

设备列表卡片
设备在线状态指示（绿色小圆点=在线，红色小圆点=离线）
操作按钮：
- 直连模式：控制台（连接）、文件管理、编辑、删除
- 终端代理模式：控制台（连接）、查看配置、编辑、删除（文件管理按钮禁用）
配置下载功能（弹窗预览、编辑、下载）
自动刷新状态（30秒）

8.2.4 Workspace（工作区）

左侧设备列表（320px）
- 设备卡片显示在线状态
- 控制台和文件管理按钮
- 刷新状态按钮
右侧多页签布局
- 页签类型：终端、文件管理
- 页签切换不重新连接（CSS hidden）
- 自动刷新设备状态（30秒）
URL参数支持：
- ?deviceId=xxx&tabType=terminal - 自动创建终端页签
- ?deviceId=xxx&tabType=file - 自动创建文件管理页签

8.2.5 终端页面

xterm终端窗口
模式显示：直连模式/终端代理模式
连接状态提示
断开连接按钮
性能优化：轮询间隔500ms（代理模式）/200ms（直连模式）

8.2.6 文件管理页面

文件列表（支持排序）
面包屑导航（overflow-x-auto处理）
操作按钮：上传、新建文件夹、刷新
文件操作（每行操作列）：
- 直连模式：下载、删除、编辑（文本文件）
- 终端代理模式：按钮禁用（灰色，不可点击）
文件信息面板
选中状态：蓝色左边框

8.2.7 代码编辑器页面

独立页面打开（target=“_blank”）
左侧文件树导航（递归显示，动态加载）
中间Monaco编辑器（60+种语法高亮）
顶部工具栏
底部状态栏
中文乱码修复（TextDecoder）

8.2.8 Token管理页面

Token列表
Token信息：名称、值、描述、过期时间
操作按钮：编辑（名称、描述）、删除
创建新Token
数据隔离：用户只能查看和操作自己的Token

8.2.9 需求说明页面

Markdown渲染
支持Mermaid图表
低对比度配色（长时间阅读优化）

9. 安全机制

9.1 认证安全

用户认证：JWT token，有效期24小时
密码加密：bcrypt哈希
Token管理：UUID格式，默认3年有效期

9.2 数据隔离

用户数据：用户只能访问自己的设备和token
数据库验证：所有API接口验证用户身份和所有权
关联查询：使用eq(tokens.userId, userId)确保数据隔离

9.3 通信安全

HTTPS：生产环境强制HTTPS
SSH加密：SSH连接使用加密通道
SFTP：文件传输使用SFTP协议（SSH加密）

9.4 权限控制

设备访问：用户只能管理自己的设备
Token使用：用户token仅用于授权终端代理连接
API验证：所有API接口验证JWT token和Authorization header

10. 性能优化

10.1 开发环境优化

文件监听优化：
- 忽略日志目录（logs/）
- 忽略缓存目录（.next/, .cache/, .turbo/）
- 忽略构建目录（build/, dist/, out/）
- 忽略所有.log文件
Webpack配置：
- stats: ‘errors-warnings’（减少日志输出）
- watchOptions.poll: 1000ms（增加轮询间隔）
- watchOptions.aggregateTimeout: 300ms
Go代理日志优化：
- 日志级别从debug改为info
- 禁用高频日志输出（“发送消息成功”）
- 保留关键错误日志

10.2 连接管理

连接复用：使用global对象持久化SSH连接，避免Next.js HMR导致连接丢失
连接缓存：SFTP客户端缓存，避免重复创建连接
独立连接：每个页签创建独立SSH连接，不复用
引用计数：管理连接生命周期，避免内存泄漏

10.3 长轮询优化

轮询间隔：
- 终端代理模式：500ms（从1000ms优化）
- 文件管理：500ms（从100ms优化）
- Go代理轮询：100ms（从1000ms优化）
消息队列：区分输入和输出队列，避免消息混淆
批量处理：支持批量消息传输

10.4 前端优化

代码分割：Next.js自动代码分割
静态生成：静态页面预渲染
热更新：开发环境支持HMR
页签优化：使用CSS hidden而非条件渲染，避免组件卸载

11. 故障排查

11.1 常见问题

11.1.1 设备显示离线

直连模式：检查SSH配置是否正确，网络是否可达
代理模式：检查终端代理是否运行，user_token是否有效

11.1.2 终端无响应

检查长轮询连接状态
查看浏览器控制台错误信息
检查服务器日志

11.1.3 文件上传失败

检查文件大小限制
检查目标目录权限
查看服务器错误日志

11.1.4 页面频繁显示"编译中"

原因：日志文件持续写入触发文件监听
解决：
- Go代理日志级别设为info
- 文件监听忽略logs/目录
- 清理.next/cache/缓存
已知限制：项目规模较大时，会有一定CPU占用（约100%），属于正常范围

11.2 调试工具

11.2.1 连接调试API

GET /api/debug/connections - 查看所有SSH连接状态
GET /api/debug/proxy-connections - 查看代理连接详情
GET /api/debug/queue-status - 查看消息队列状态

11.2.2 日志文件

logs/ssh-connection-manager.log - SSH连接日志
logs/proxy-connection-manager.log - 代理连接日志
device_proxy/logs/device-proxy.log - 终端代理日志

11.2.3 诊断页面

/test-file-connect - 文件管理连接诊断
/ws-diagnose - WebSocket诊断（Coze平台不支持）

12. 版本历史

版本	日期	更新内容
v2.1	2026-01-12	- 禁用终端代理模式文件管理功能 - 优化开发环境性能（减少频繁编译） - Go代理日志优化（info级别） - Workspace页面优化（页签切换、自动刷新） - 文件管理UI优化（选中状态、操作列） - 编辑器增强（60+种语法高亮、40+种文件类型） - 终端代理程序压缩优化（UPX 4.2.2） - 添加开发环境性能优化指南
v2.0	2026-01-12	- 数据库从PostgreSQL迁移到SQLite - 终端代理使用Go语言实现 - 支持HTTP长轮询架构 - 文件管理全面支持SFTP协议 - 集成Monaco Editor代码编辑器 - 提供多平台终端代理下载 - 添加配置文件动态生成功能
v1.0	2025-01-XX	初始版本

13. 附录

13.1 术语表

术语	说明
直连模式	通过ssh2库直接连接公网设备的模式
终端代理模式	通过Go终端代理穿透私网连接设备的模式
长轮询	客户端主动轮询服务器获取数据的通信模式
user_token	用户级别的访问凭证，用于终端代理认证
JWT	JSON Web Token，用于用户身份认证
SFTP	SSH File Transfer Protocol，SSH文件传输协议
HMR	Hot Module Replacement，热模块替换