dumbwareio/dumbterm

DumbTerm

一个极其简单的基于Web的终端模拟器，包含常用工具和Starship支持！🚀

!https://github.com/user-attachments/assets/45a4542f-7f69-4dcd-a6df-39e5231e3db2

• 从任何有Web浏览器的设备访问您的终端
• 像在原生终端中一样执行命令
• Starship提示符提供美观的终端体验，包含git状态、命令持续时间等信息
• PIN保护（推荐）可防止未授权访问
• 使用数据目录在容器重启之间持久化文件
• 演示模式可用于测试和演示 - 模拟终端（设置DEMO_MODE=true）

使用场景

• Docker构建：创建沙盒环境用于测试脚本、代码、应用程序，模拟VPS，展示示例等。无需在本地机器上安装依赖！
• 本地构建：通过浏览器访问客户端的命令行/终端！
• 自托管：放置在反向代理、认证提供器（如authentik、authelia等）、具有应用访问规则的Cloudflare隧道等后面，以实现安全的外部访问。
• ttyd、shellinabox等Web终端的另一种替代方案

目录

• 特性
• 快速开始
  • 前提条件
  • 选项1：Docker（傻瓜式）
  • 选项2：Docker Compose（推荐）
  • 选项3：本地运行
    • Windows特定说明
• 配置
  • 环境变量
  • Starship使用
    • Starship预设
• 键盘快捷键
  • 终端搜索
  • 标签管理
• 安全性
  • 安全特性
• 技术细节
  • 技术栈
  • 依赖项
  • 支持的XTerm插件
• 链接
• 贡献
• 了解我们
• 未来功能

特性

• 🖥️ 可从任何地方访问的基于Web的终端
• 🌙 支持深色模式
• 📱 响应式设计，适用于移动设备和桌面
• 🐳 Docker支持（基于Debian的容器）
• 🔧 预装实用工具：starship、nerdfonts、apt-utils、curl、wget、ssh、git、vim、nano、htop、net-tools、iputils-ping、traceroute、fontconfig、unzip、locales。
• 🔒 可选PIN保护（数字）
• ✨ Starship提示符集成，提供美观的终端体验
• 🔍 终端搜索功能（ctrl+f 或 cmd+f）
• 📂 自定义卷映射
• 🔗 终端内超链接
• ⌨️ 常用操作的键盘快捷键
• 📑 标签管理：
  • 拖放重新排序标签
  • 双击重命名标签
  • 使用快捷键直接选择标签
  • 跨会话持久化终端历史

快速开始

前提条件

• Docker（推荐）
• Node.js >=20.0.0（用于本地开发）
  • Windows特定：WSL或Node.js v16 - 选项3：本地运行

选项1：Docker（傻瓜式）

• Docker方法使用预安装的基于Debian Bullseye的容器/环境。

bash
# 一键拉取并运行
docker run -p 3000:3000 \
  -v ./data:/root/data \
  -v ./config:/root/.config \ 
  -e DUMBTERM_PIN=1234 \
  -e SITE_TITLE=DumbTerm \
  -e BASE_URL=http://localhost:3000 \
  -e ALLOWED_ORIGINS=http://localhost:3000 \
  -e ENABLE_STARSHIP=true \
  -e TZ=Asia/Shanghai \
  -e LOCKOUT_TIME=15 \
  -e MAX_SESSION_AGE=24 \
  dumbwareio/dumbterm:latest

1. 访问 http://localhost:3000
2. 如果已配置，输入您的PIN
3. 享受基于Web的终端！

选项2：Docker Compose（推荐）

创建docker-compose.yml文件或使用提供的文件：

yaml
services:
  dumbterm:
    image: dumbwareio/dumbterm:latest
    container_name: dumbterm
    restart: unless-stopped
    ports:
      - ${DUMBTERM_PORT:-3000}:3000
    volumes:
      - ${DUMBTERM_CONFIG:-./config}:/root/.config
      - ${DUMBTERM_DATA_DIR:-./data}:/root/data
    environment:
      # 容器时区
      TZ: ${DUMBTERM_TZ:-Asia/Shanghai}
      # Web界面中显示的标题
      SITE_TITLE: ${DUMBTERM_SITE_TITLE:-DumbTerm}
      # 推荐的PIN保护（留空禁用）
      DUMBTERM_PIN: ${DUMBTERM_PIN:-1234}
      # 应用程序的基本URL
      BASE_URL: ${DUMBTERM_BASE_URL:-http://localhost:3000}
      ENABLE_STARSHIP: ${ENABLE_STARSHIP:-true}
      LOCKOUT_TIME: ${DUMBTERM_LOCKOUT_TIME:-15} # 分钟
      # 需要重新认证前的会话持续时间（小时）
      MAX_SESSION_AGE: ${DUMBTERM_MAX_SESSION_AGE:-24} # 小时
      # （可选）- 允许的CORS源列表
      # ALLOWED_ORIGINS: ${DUMBTERM_ALLOWED_ORIGINS:-http://localhost:3000}

然后运行：

bash
docker compose up -d

选项3：本地运行（开发者）

• 本地方法将使用您的本地终端环境（Windows：Powershell，Mac / Linux：bash）。

1. 安装依赖项：

bash
npm install

[!提示]

Windows特定说明：

• 如果遇到node-pty问题，您可以尝试使用Windows Subsystem for Linux (WSL)或可能需要安装：
• Node.js v16（查看https://github.com/coreybutler/nvm-windows%E4%BB%A5%E8%8E%B7%E5%BE%97%E5%A4%9A%E8%8A%82%E7%82%B9%E7%89%88%E6%9C%AC%E6%94%AF%E6%8C%81%EF%BC%89%EF%BC%9A
  • winget install CoreyButler.NVMforWindows
  • 安装nvm后使用：nvm install 16 && nvm use 16
• 通过Visual Studio安装程序安装windows-build-tools MSVC v142 - VS 2019 C++ {arch} Build Tools
  • 如需更多详细信息，请联系我们或查看https://github.com/microsoft/node-pty?tab=readme-ov-file#windows

2. cp .env.example .env > 在.env中设置环境变量：

bash
PORT=3000                  # 服务器运行的端口
DUMBTERM_PIN=1234          # 可选PIN保护
SITE_TITLE=DumbTerm        # 自定义站点标题
BASE_URL=http://localhost:3000  # 应用程序的基本URL

3. 启动服务器：

bash
npm start

配置

环境变量

Starship使用

• Starship是一个跨shell提示符，提供美观的终端体验。
• 在Docker镜像中默认启用，是推荐的方法。
• 要禁用它，请在环境变量中将ENABLE_STARSHIP设置为false。
• 您可以通过以下步骤之一自定义Starship提示符：

1. 使用starship的预设配置

Starship预设：

[!提示] 复制并粘贴以下starship预设命令之一到DumbTerm中即可！

预设命令示例：

!https://github.com/user-attachments/assets/affdd780-5471-40de-adfd-9242feeec9da

[!警告] 注意： 如果本地运行或将卷映射到实际的starship.toml配置，预设命令将覆盖您现有的starship.toml文件。确保根据需要进行备份。

查看所有Starship预设：

预设名称	命令	预览
Nerd Font Symbols	starship preset nerd-font-symbols -o ~/.config/starship.toml	!Nerd Font Symbols
Bracketed Segments	starship preset bracketed-segments -o ~/.config/starship.toml	!Bracketed Segments
Plain Text Symbols	starship preset plain-text-symbols -o ~/.config/starship.toml	!Plain Text Symbols
No Runtime Versions	starship preset no-runtime-versions -o ~/.config/starship.toml	!No Runtime Versions
No Empty Icons	starship preset no-empty-icons -o ~/.config/starship.toml	!No Empty Icons
Pure Prompt	starship preset pure-preset -o ~/.config/starship.toml	!Pure Prompt
Pastel Powerline	starship preset pastel-powerline -o ~/.config/starship.toml	!Pastel Powerline
Tokyo Night (DumbTerm默认修改版)	starship preset tokyo-night -o ~/.config/starship.toml	!Tokyo Night
Gruvbox Rainbow	starship preset gruvbox-rainbow -o ~/.config/starship.toml	!Gruvbox Rainbow
Jetpack	starship preset jetpack -o ~/.config/starship.toml	!Jetpack
No Nerd Fonts	starship preset no-nerd-font -o ~/.config/starship.toml	n/a

• 您也可以在DumbTerm中运行starship preset -l查看可用的预设。

有关更多详细信息，请访问Starship Presets页面。

2. 修改已设置的卷挂载中的~/.config/starship.toml文件或容器内的该文件。

• 默认配置位于/root/.config/starship.toml。
• 您也可以使用Docker卷将自定义的starship.toml文件挂载到容器中。
• 更新或添加自定义配置到starship.toml。
  • 访问Starship配置了解有关自定义提示符的更多信息。

3. 本地运行

• 如果您在本地运行DumbTerm，DumbTerm将继承您当前的样式。
  • 这意味着如果您已经在本地启用了starship，您应该能够相应地看到您当前的样式。
• 如果您希望在_本地_使用带有starship的DumbTerm，必须在本地计算机上安装Starship。
  • 要安装Starship，请按照Starship安装页面上的说明进行操作。

键盘快捷键

DumbTerm提供了一套全面的键盘快捷键，用于高效的终端管理。修饰键因操作系统而异：

• Windows/Linux: Ctrl+Alt+{键}
• macOS: Ctrl+Cmd+{键}

终端搜索

• 按Ctrl+F（Windows/Linux）或Cmd+F（macOS）打开搜索栏
• 使用上下箭头按钮或Enter/Shift+Enter循环浏览匹配项
• 按Escape或关闭按钮退出搜索模式

标签管理

• 拖放：点击并拖动标签以重新排序
• 重命名：双击标签或使用键盘快捷键重命名
• 历史记录：终端内容在浏览器刷新和重启之间自动保留
• 直接选择：使用数字快捷键（1-9）快速切换前9个终端

安全性

强烈建议设置强PIN，使用HTTPS，使用ALLOWED_ORIGINS，并与认证提供器（即Authentik / Authelia / tinyauth等）集成。

我们很"笨"，但不愚蠢。生产环境使用时请使用全功能的认证提供器。

• https://github.com/goauthentik/authentik%EF%BC%88%E8%AE%BE%E7%BD%AE%E8%BE%83%E5%A4%8D%E6%9D%82%EF%BC%8C%E4%BD%86%E9%80%82%E5%90%88%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%EF%BC%89
• https://github.com/authelia/authelia
• https://github.com/steveiliop56/tinyauth%EF%BC%88%E6%98%93%E4%BA%8E%E4%B8%8Edocker compose集成）

安全特性

• 变长PIN支持（数字）
• 恒定时间PIN比较
• 暴力破解保护：
  • 最多5次尝试
  • 失败尝试后15分钟锁定
  • 基于IP的跟踪
• 安全Cookie处理
• 基于会话的认证
• 用于源限制的CORS支持（可选）
• HTTPS支持（当使用适当的BASE_URL配置时）

技术细节

技术栈

• 后端：Node.js (>=20.0.0) 与 Express
• 前端：XTerm.js 用于终端模拟
• 容器：Docker 与 Debian Bullseye 基础镜像
• 终端：node-pty 用于进程生成
• 通信：WebSocket 用于实时终端I/O
• 安全：cors 用于跨域请求

依赖项

• express: Web框架
• node-pty: 终端进程生成
• xterm: 终端前端
• ws: WebSocket服务器
• cookie-parser: Cookie处理
• express-session: 会话管理
• cors: 跨域请求安全

支持的XTerm插件

DumbTerm包含以下XTerm.js插件以增强您的终端