# TermuxWebui

**Repository Path**: linDream-StarSpark/termux-webui

## Basic Information

- **Project Name**: TermuxWebui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Termux WebUI

基于 Web 的 Termux 环境管理面板，通过浏览器管理文件、软件包、进程，并提供多标签 Web 终端访问。

## 功能

- **用户认证** — 首次启动设置管理员密码，JWT + bcrypt 登录，5 次失败锁定 5 分钟
- **系统仪表盘** — CPU/内存/存储实时监控，设备信息展示，5 秒自动刷新
- **文件管理** — 目录浏览、文件读写/上传/下载/重命名/删除，Monaco 编辑器
- **包管理** — pkg 包的搜索、安装、更新、卸载，安装过程 SSE 实时流式输出
- **进程管理** — 进程列表查看，支持 kill/kill-force，自身进程保护
- **Web 终端** — xterm.js + node-pty 多标签终端，支持会话复连
- **设置管理** — 服务器配置、密码修改、主题切换

## 技术栈

| 层 | 技术 |
|----|------|
| 后端 | Node.js + Express + WebSocket (ws) |
| 前端 | Vue 3 + Vite + Pinia + Vue Router |
| 终端 | xterm.js + node-pty |
| 编辑器 | Monaco Editor |
| 认证 | JWT + bcryptjs |
| 测试 | Vitest + @vue/test-utils |

## 快速开始

### 安装依赖

```bash
# 后端
cd server && npm install

# 前端
cd client && npm install
```

### 开发模式

```bash
# 启动后端 (默认端口 3000)
cd server && node server.js

# 启动前端开发服务器 (含 API 代理)
cd client && npm run dev
```

### 生产模式

```bash
# 构建前端
cd client && npm run build

# 启动后端 (自动托管前端静态文件)
cd server && node server.js
```

服务启动后访问 `http://localhost:3000`，首次访问会提示设置管理员密码。

### 运行测试

```bash
# 后端测试 (45 个)
cd server && npm test

# 前端测试 (8 个)
cd client && npm test
```

## 配置

配置文件默认存储在 `~/.termux-webui/config.json`，首次启动时自动创建。

可通过环境变量覆盖：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `TERMUX_WEBUI_CONFIG` | 配置文件路径 | `~/.termux-webui/config.json` |

配置项：

```json
{
  "host": "0.0.0.0",
  "port": 3000,
  "jwtSecret": "<auto-generated>",
  "theme": "dark",
  "refreshInterval": 5
}
```

## 项目结构

```
├── server/
│   ├── server.js              # 服务入口
│   ├── config.js              # 配置管理
│   ├── middleware/
│   │   └── auth.js            # JWT 认证中间件
│   ├── routes/
│   │   ├── auth.js            # 认证路由
│   │   ├── system.js          # 系统信息 API
│   │   ├── files.js           # 文件管理 API
│   │   ├── packages.js        # 包管理 API
│   │   ├── processes.js       # 进程管理 API
│   │   └── settings.js        # 设置 API
│   ├── ws/
│   │   └── terminal.js        # WebSocket 终端服务
│   └── __tests__/
├── client/
│   ├── src/
│   │   ├── views/             # 页面组件
│   │   ├── stores/            # Pinia 状态管理
│   │   ├── api/               # API 客户端
│   │   └── router/            # 路由配置
│   └── __tests__/
└── .monkeycode/
    └── specs/termux-webui/    # 需求与设计文档
```

## License

MIT