# shellbench-web
**Repository Path**: newpc/shellbench-web
## Basic Information
- **Project Name**: shellbench-web
- **Description**: ShellBench Web —— 多用户 AI 运维工作台:SSH 终端、文件管理、AI Agent、批量运维与定时任务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-08
- **Last Updated**: 2026-11-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# ShellBench Web
**把服务器运维收进一个浏览器工作台。** SSH 终端、文件管理、AI Agent、批量执行与定时任务集中在一处;多用户隔离,凭据只在服务端加密保存。
[](docs/images/terminal.png)
> 当前版本 **0.1.11** · Node ≥ 22.5 · MIT License
## 目录
- [功能](#功能)
- [截图](#截图)
- [架构](#架构)
- [快速开始](#快速开始)
- [配置](#配置)
- [安全模型](#安全模型)
- [开发与测试](#开发与测试)
- [目录结构](#目录结构)
- [状态与许可](#状态与许可)
## 功能
### 终端与文件
- **多标签 SSH 终端**:WebSocket 二进制帧传输,断线自动重连并保留已收到的回滚输出;会话状态、流量速率与退出原因可见。
- **终端搜索与关键字高亮**:`Ctrl+Shift+F` 查找、`F3` / `Shift+F3` 跳转;错误 / 警告 / 成功 / 状态四组关键字自动染色,规则可改。
- **文件工作区**:远程目录树 + 详细表格 + 在线编辑器(CodeMirror 6),双击即开;支持语法高亮、格式化、GBK / UTF-16 等编码识别与大文件只读预览。
- **上传下载**:拖拽上传、浏览器下载、进度与速率、失败原因;目录下载与文件夹上传按边界明确拒收。
- **命令历史与收藏**:手输命令、Agent 执行、批量执行分别记账;收藏夹可新建、排序、写说明,一键填入终端。
### AI 与自动化
- **AI 对话**:独立「AI 对话」页,按会话保存台账;可以不带目标先聊,由模型读取主机清单后自己挑。
- **Agent 任务执行**:模型通过 `exec`、`list_dir`、`read_file`、`write_file`、`search_files`、`list_hosts`、`propose_schedule` 七个工具操作远端。
- **审批门禁**:审核模式逐次批准;全自动模式放行普通命令;**红线命令在任何模式下都阻断**。每次工具调用都进审计。
- **批量运维**:多选主机 → 只读侦察 → 生成方案 → 整批批准 → 并发执行 → 逐台对账;失败即停、重试、回滚草稿与批次回看。
- **定时任务**:命令型 / AI 型,多台主机,四档计划(一次 / 每隔 / 每天 / 每周);服务端调度、补跑窗口、无人值守三档权限。AI 只能起草,创建与启用永远由人点。
- **常用任务**:把例行检查写成模板,在 Agent 与批量任务里一键填入。
### 多用户与安全
- 管理员 / 普通用户两种角色;首次登录强制改密,可强制下线、删除账号。
- **私有主机**只有属主可见;**公开主机**任何用户都能发布,他人可连但只读,并且**各填各的凭据**;分组、颜色、置顶属于个人视图。
- 凭据(SSH 口令 / 私钥、AI Key)以服务端主密钥加密落库,浏览器只能拿到「是否已配置」的布尔值。
- 主机指纹按 OpenSSH 的 `known_hosts` 语义校验(TOFU / 严格 / 关闭三档),指纹变化默认拒绝。
- 审计为追加写,只读查询与 CSV 导出;管理台可查看用户、公开服务器、活动会话、AI 配额与系统状态。
### 界面
- 深色 / 浅色 / 高对比等 8 套预设主题,支持自定义与跟随系统。
- 中文 / English 双语;可调字号;左栏面板可上下堆叠、拖动排序、单独关闭。
- 内置使用说明与快捷键帮助;桌面与窄窗口布局均可用。
## 截图
| 主机管理 | 文件与编辑器 |
|---|---|
|  |  |
| AI 对话 | 定时任务 |
|---|---|
|  |  |
| 系统设置 | 使用说明 |
|---|---|
|  |  |
登录页

> 截图来自本地演示实例:主机指向本地回环的演示 SSH 服务,AI 回复由本地桩模型生成;不含任何真实环境信息。
## 架构
```
浏览器(React 19 + Vite)
│ HTTP(登录 / 静态资源 / 管理接口)
│ WebSocket /ws(JSON-RPC + 终端二进制帧)
▼
Fastify 5 服务端
├─ 会话域:SSH 连接、重连、终端缓冲、流量台账
├─ 文件域:SFTP 浏览、读写、上传下载、编码识别
├─ Agent 域:工具循环、审批门禁、红线判定、审计
├─ 批量域:侦察 → 方案 → 批准 → 并发执行
├─ 调度域:四档计划、补跑、无人值守权限
├─ 租户域:用户 / 配额 / 隔离
├─ SQLite(node:sqlite):主机、会话记录、运行、审计、偏好
└─ ssh2:到目标主机的 SSH / SFTP
```
- **会话在服务端**:浏览器关闭或刷新后,服务端负责收尾;终端回滚缓冲不依赖浏览器本地存储。
- **目标按调用解析**:Agent 的每个工具调用都可以指定 `host`;未指定时用运行自身的目标或对话首个目标。
- **渲染层拿不到秘密**:凭据只在服务端解密,用于建立 SSH 连接。
- **无隐藏端口**:除对外服务的 HTTP/HTTPS 端口外,不额外监听本地端口。
## 快速开始
### 前置条件
- **Node.js ≥ 22.5**(需要内置 `node:sqlite`;推荐 Node 24 LTS)
- 一台可 SSH 登录的目标主机(可选,先用本地回环靶机也可以)
### 本地运行
```bash
git clone https://gitee.com/newpc/shellbench-web.git
cd shellbench-web
npm install
cp .env.example .env
# 生成 32 字节主密钥,填进 .env 的 SHELLBENCH_MASTER_KEY
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# 首次启动创建管理员:填 SB_ADMIN_PASSWORD
npm run dev
```
打开 ,用 `SB_ADMIN_USER` / `SB_ADMIN_PASSWORD` 登录。首次登录会要求改密。
### 生产运行
```bash
npm run build
npm start
# 默认监听 127.0.0.1:8787,由反向代理终止 TLS
```
生产部署建议使用仓库内的 Docker Compose(Fastify + Caddy 自动 HTTPS):
```bash
cd deploy
cp .env.example .env
# 填 SHELLBENCH_MASTER_KEY / SB_ADMIN_PASSWORD / SB_SITE_ADDRESS / SB_PUBLIC_ORIGIN
docker compose up -d --build
```
完整步骤、只有 IP 的自签模式、frp 内网穿透、备份与恢复见 [docs/deployment.md](docs/deployment.md)。
## 配置
配置全部来自环境变量;常用项:
| 变量 | 说明 |
|---|---|
| `SHELLBENCH_MASTER_KEY` | **必填**。32 字节 base64 主密钥,加密主机凭据与 AI Key。丢失 = 所有托管凭据不可用 |
| `SHELLBENCH_DATA_DIR` | 数据目录(SQLite、备份、pi 工作目录、临时上传),默认 `./data` |
| `SB_ADMIN_USER` / `SB_ADMIN_PASSWORD` | 首次启动创建管理员(仅当 `users` 表为空) |
| `SB_PUBLIC_ORIGIN` | 浏览器实际访问的 origin;决定 Cookie `Secure` 与 WebSocket Origin 校验 |
| `SB_HOST` / `SB_PORT` | 监听地址与端口,默认 `127.0.0.1:8787` |
| `SB_HOST_CIDR_ALLOW` | 允许 SSH 连接的目标网段,留空 = 回环 + 私网 |
| `SB_MAX_RUNS_PER_USER` / `SB_MAX_SESSIONS_PER_USER` | 每用户并发 Agent 运行数 / 会话数 |
| `SB_SESSION_TTL_HOURS` / `SB_SESSION_MAX_DAYS` | 登录会话有效期 |
| `SB_AUDIT_RETENTION_DAYS` | 审计保留天数 |
其余变量见 [.env.example](.env.example) 与 [deploy/.env.example](deploy/.env.example)。
## 安全模型
| 边界 | 做法 |
|---|---|
| 凭据 | 服务端主密钥加密落库;API 只返回 `*Configured` 布尔;日志与审计不记录明文 |
| 多租户 | 主机、会话、运行、常用任务、收藏、偏好全部按 `userId` 作用域读写;跨用户访问返回 `not_found` |
| 公开主机 | 属主或管理员才能改配置;他人只读,可填自己的凭据,可设自己的分组 / 颜色 / 置顶 |
| Agent | 审批门禁在引擎层;红线命令在保存期与运行期各判一次;无人值守运行不挂起等审批 |
| 本机文件 | Web 版没有「本机 / WSL」目标,服务端访问不到用户电脑上的文件 |
| 主机指纹 | 默认 `accept-new`(TOFU),指纹变化拒绝;`off` 仅调试并需二次确认 |
| 审计 | 追加写,没有修改 / 删除通道;管理台只读查询 |
发现安全问题请不要公开提 Issue,先通过仓库主页的联系方式私下联系维护者。
## 开发与测试
```bash
npm run typecheck # 服务端 + 前端类型检查
npm test # Vitest 单元测试(服务端 + 渲染层纯逻辑 + jsdom 组件)
npm run size # 文件体量门禁(组件 ≤400 行、hook ≤250 行等)
npm run gate # 提交前必跑:typecheck + test + size
```
端到端脚本需要先启动一个测试实例(默认 `http://127.0.0.1:8899`):
```bash
npm run verify:isolation # 多租户隔离矩阵
npm run verify:public-hosts # 公开主机三层视角
npm run verify:p3 # 终端 / 文件 / 编码 / Agent
npm run verify:p4 # 管理台 / 审计 / 备份
npm run verify:users # 用户生命周期
```
- 测试与门禁不删除失败用例、不降低阈值。
- 新增或修改接口时同步 `shared/src/` 的契约类型;两侧引用同一份类型。
- 改前端交互(testid / aria / 键盘 / 焦点)要补对应的 jsdom 组件测试。
## 目录结构
```
shared/src/ 前端与服务端共用的契约类型(IPC 通道、主机、Agent、定时任务……)
server/src/ Fastify 服务端
auth/ 登录、会话 Cookie、CSRF、角色
tenant/ 多租户作用域与配额
domain/ 主机、会话、文件、Agent、批量、调度、审计、AI
infra/ SQLite、SSH、SFTP、凭据加密、日志
http/ REST 路由(登录 / 管理 / 健康检查 / 下载)
transport/ WebSocket JSON-RPC 通道
web/src/ React 渲染层(终端、文件、Agent、设置、管理台)
deploy/ Dockerfile、Compose、Caddy、备份与恢复脚本
docs/ 部署手册、用户管理、截图
tools/ 构建、体量门禁、端到端验证脚本
```
## 状态与许可
- 版本 **0.1.11**;数据库 schema v21。
- 已实现:终端 / 文件 / Agent / 批量 / 定时 / 多租户 / 管理台 / 审计 / 双语 / 主题。
- 明确不做:浏览器直接访问用户本机文件、系统级计划任务、桌面端安装包更新。
- 许可证:[MIT](LICENSE)。