# 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、批量执行与定时任务集中在一处;多用户隔离,凭据只在服务端加密保存。 [![ShellBench Web 终端工作台](docs/images/terminal.png)](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 双语;可调字号;左栏面板可上下堆叠、拖动排序、单独关闭。 - 内置使用说明与快捷键帮助;桌面与窄窗口布局均可用。 ## 截图 | 主机管理 | 文件与编辑器 | |---|---| | ![主机管理](docs/images/hosts.png) | ![文件与编辑器](docs/images/files.png) | | AI 对话 | 定时任务 | |---|---| | ![AI 对话](docs/images/agent.png) | ![定时任务](docs/images/schedule.png) | | 系统设置 | 使用说明 | |---|---| | ![系统设置](docs/images/settings.png) | ![使用说明](docs/images/guide.png) |
登录页 ![登录页](docs/images/login.png)
> 截图来自本地演示实例:主机指向本地回环的演示 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)。