CmdHub 部署使用维护指南

一个以"运维命令库"为核心的轻量级 Web 终端管理面板

一、项目简介

CmdHub 是一个基于 Web 的 SSH 终端管理工具，核心特色是运维命令库。支持多主机管理、命令分组、文件浏览、手机端适配，所有数据本地存储，安全可控。

特性	说明
🖥️ 主机管理	添加、编辑、删除 SSH 主机，支持密码认证
📋 命令库	按应用分组存储常用命令，一键粘贴到终端，支持高风险标记
📁 文件管理	浏览目录、预览文本、上传下载、删除文件
📱 手机端	响应式布局，PWA 支持，长按粘贴
🔒 安全	登录锁定、操作日志、Session 超时
💾 数据自有	所有数据存储在本地 SQLite，支持 JSON 导入导出

二、环境要求

• 一台 Linux 服务器（Debian/Ubuntu/CentOS 均可）
• 安装 Docker 和 Docker Compose
• 开放端口 5100（可在 docker-compose.yml 中修改）

三、安装步骤

1. 解压安装包

mkdir /opt/cmdhub
tar -xzf cmdhub.tar.gz -C /opt/cmdhub
cd /opt/cmdhub

2. 确认文件完整

ls -la

应看到：docker-compose.yml、Dockerfile、requirements.txt、app.py、templates/

3. 构建并启动

sudo docker compose up -d --build

4. 访问

浏览器打开 http://<服务器IP>:5100

5. 修改密码

编辑 docker-compose.yml：

environment:
  - TERMINAL_PASSWORD=你的新密码

然后重建容器：

sudo docker compose up -d --build

四、使用指南

1. 添加主机

1. 登录后，点击左侧 🖥️ 主机管理 图标
2. 侧边栏滑出，点击 + 添加主机
3. 填写名称、IP、端口（默认22）、用户名、密码
4. 点击 保存
5. 在主机列表中点击主机名称，自动连接

2. 使用命令库

1. 连接主机后，点击左侧 📋 命令库 图标
2. 左侧选择分组，右侧显示该分组下的命令
3. 点击命令，自动粘贴到终端（不自动执行，需手动回车）
4. 红色命令为高风险操作，请谨慎确认

3. 管理命令库

• 新建分组：在命令库左侧底部点击 + 新建分组
• 编辑分组名：鼠标悬停分组，点击 ✎ 图标
• 删除分组：鼠标悬停分组，点击 × 图标（命令移入未分组）
• 新建命令：选择分组后，在右侧底部点击 + 新建命令
• 编辑命令：鼠标悬停命令，点击 ✎ 图标
• 标记高风险：编辑命令时勾选"标记为高风险命令"

4. 文件管理

1. 连接主机后，点击左侧 📁 文件管理 图标
2. 点击文件夹进入子目录
3. 点击文件预览内容（仅文本文件）
4. 点击 ⬇ 按钮下载文件
5. 点击 × 按钮删除文件/目录
6. 底部 + 上传文件 可上传本地文件到当前目录

5. 复制粘贴

平台	操作
电脑端	右键 → 复制选中 / 粘贴 / 清屏
电脑端	快捷键 Ctrl+Shift+V 粘贴
手机端	长按终端 0.5 秒 → 弹出粘贴输入框 → 发送

6. 终端外观设置

1. 点击左侧 ⚙️ 设置 图标
2. 拖动滑块调整字体大小和行高
3. 点击 应用并保存

7. 数据导入导出

在设置面板中：

• 导出主机：下载主机列表 JSON 文件
• 导入主机：增量导入主机（不会覆盖已有主机）
• 导出命令库：下载命令库 JSON 文件（含分组）
• 导入命令库：增量导入命令（不会覆盖已有命令，重复的自动跳过）

五、日常维护

容器管理

# 进入项目目录
cd /opt/cmdhub

# 重启容器（修改模板后）
sudo docker compose restart

# 停止容器
sudo docker compose down

# 查看容器状态
sudo docker ps --filter "name=terminal"

# 查看容器日志
sudo docker logs -f terminal

# 重建镜像（无缓存）
sudo docker compose build --no-cache
sudo docker compose up -d

数据备份

# 备份数据库文件
cp /opt/cmdhub/data/term.db /opt/cmdhub/data/term.db.bak.$(date +%Y%m%d)

# 或者通过设置面板导出 JSON（推荐，可跨版本恢复）

日志查看

# 实时查看操作日志
tail -f /opt/cmdhub/data/term.log

# 查看完整日志
cat /opt/cmdhub/data/term.log

更新版本

收到新的安装包后：

cd /opt/cmdhub
sudo docker compose down
tar -xzf cmdhub.tar.gz
sudo docker compose up -d --build

六、安全建议

1. 修改默认密码：首次登录后务必修改
2. 使用 HTTPS：建议前面加 nginx 反向代理，配置 SSL 证书
3. 防火墙：仅开放必要端口，限制来源 IP
4. 定期备份：定期导出命令库和主机列表 JSON 文件
5. 不分享 data 目录：term.db 明文存储密码，切勿分享

七、常见问题

Q: 文件管理打开后显示"目录不存在"

检查主机用户名是否为 root，某些目录需要 root 权限。如确认有权限，请在终端中手动执行 ls -la 路径 确认。

Q: 手机端如何粘贴

长按终端区域 0.5 秒，会弹出粘贴输入框，在框中长按粘贴，点发送。

Q: 导入命令库后数据不见了

当前版本已支持增量导入，不会覆盖已有数据。如果之前用了旧版覆盖导入导致数据丢失，请从备份文件恢复。

Q: 容器启动失败

# 检查端口是否被占用
ss -tlnp | grep 5100

# 检查 Docker 日志
sudo docker logs terminal

八、技术支持

如有问题或建议，请通过以下方式联系：

• 项目地址：/opt/cmdhub
• 数据目录：/opt/cmdhub/data
• 日志文件：/opt/cmdhub/data/term.log

---

CmdHub - 让运维回归简单、高效与安全