WebSSHGateway/README.md

WebSSH Gateway 社区版

English version: README.en.md

WebSSH Gateway 是一个面向运维和开发场景的浏览器 SSH 网关。你可以在 Web 页面内完成 SSH 连接管理、终端会话、系统监控和文件管理，减少多终端切换带来的成本。

其中一个核心特点是面向长时任务的“持久会话设计”。基于增强会话与 tmux 保活能力，即使浏览器关闭、网络抖动或前端页面刷新，后台任务仍可持续运行，适合执行需要保活的部署/巡检脚本、AI Code（自动化编码）长流程开发、定期数据监控与日志采集等场景。

项目预览

移动端适配

移动端提供专门的触摸友好布局与交互，支持在手机浏览器中完成终端操作、文件管理与系统监控。

社区版声明

• 本仓库为 WebSSH Gateway 社区版（Community Edition）。
• 社区版将持续开源，聚焦核心 SSH 网关能力。
• 项目后续存在付费开发方向意向（商业版/企业版），但具体功能范围与发布时间 待定。
• 社区版与潜在付费版的边界方案 待定，社区版仍会保持可独立部署与可持续维护。

核心特性

• Web 端 SSH 终端：基于 WebSocket 的实时交互终端。
• 连接资产管理：支持保存主机连接信息，密码/私钥凭据加密存储。
• 会话生命周期管理：会话状态跟踪、断开重连、会话备注。
• 增强会话持久化：支持基于 tmux 的持久会话设计、增强保活与自动重试机制。
• 移动端适配：面向手机浏览器的触摸友好操作与布局。
• 系统监控面板：CPU、内存、网络、进程、磁盘等实时查看。
• 文件管理能力：浏览、上传、下载、重命名、删除、权限修改、批量上传。
• 基础安全能力：JWT 鉴权、密码复杂度校验、登录失败锁定、请求追踪 ID 日志。

技术栈

• 后端：FastAPI + SQLAlchemy + AsyncSSH + SQLite
• 前端：React + TypeScript + Vite + TailwindCSS + xterm.js
• 部署：Docker / Docker Compose

快速开始

重要安全提示：部署前务必修改 .env 中的 SECRET_KEY（不要使用示例值或弱口令），否则会显著降低会话与鉴权安全性。

方式 1：本地开发部署

请阅读 docs/DEPLOYMENT.md 中“本地开发部署”章节。

方式 2：Docker 镜像部署

Docker Hub 镜像：https://hub.docker.com/r/beibeizi/websshgateway

快速启动示例（注意：SECRET_KEY 仅为示例，自行部署必须替换，32 位 UUID 即可）：

docker run -d -p 8080:8080 -e SECRET_KEY="67e457b4eab14012b34382b3d634f297" beibeizi/websshgateway:latest

export DOCKER_IMAGE=beibeizi/websshgateway:latest

# 也可以自行构建本地镜像
docker build -t webssh-gateway:community .
docker run -d \
  --name webssh-gateway \
  -p 8080:8080 \
  --env-file .env \
  -v webssh-data:/data \
  ${DOCKER_IMAGE:-webssh-gateway:community}

更完整说明见 docs/DEPLOYMENT.md。

文档导航

• 架构说明： docs/ARCHITECTURE.md
• 开发与部署： docs/DEPLOYMENT.md
• 贡献指南： CONTRIBUTING.md
• 英文文档： README.en.md

目录结构

.
├── backend/                  # FastAPI 后端
├── frontend/                 # React 前端
├── session-transfer-files/   # 增强会话所需二进制文件
├── docs/                     # 项目文档
├── .env.example              # 环境变量示例
├── Dockerfile                # 镜像构建
├── docker-compose.yml        # 本地容器编排
└── LICENSE

版本路线图（Roadmap）

• 社区版（当前）：单租户、基础鉴权、连接管理、终端与文件能力。
• 付费方向（待定）：仅保留付费开发方向意向，具体能力与里程碑待定。

License

本项目基于 Apache-2.0 License 开源。