0 Fork 0

Files

T

TanXin 59497b88a7 feat: 支持 production/test 双环境部署

- wrangler.toml: 新增 [env.test] 环境配置，移除硬编码自定义域名
- package.json: 新增 deploy:test 脚本
- .github/workflows/deploy.yml: 支持 test/main 双分支部署
- README/README_en: 更新部署流程和本地开发说明

2026-06-24 11:47:22 +08:00

16 KiB

Raw Blame History

CloudSSH

一个基于 Cloudflare Workers 的 Serverless Web SSH 终端：通过浏览器直接连接和管理你的服务器。

极致轻量 · 开箱即用 · 赛博朋克 UI

核心优势 · 功能特性 · 部署指南 · 架构设计 · 开源协议

简体中文 | English

Tip

CloudSSH 利用 Cloudflare Workers 的 TCP Sockets 支持，在边缘节点实现 SSH 协议的解析与转发，提供低延迟的 Web 终端体验。

效果演示

想象一下，随时随地打开浏览器，就能以极具科技感的赛博朋克 UI 连接你的服务器，无需安装任何 SSH 客户端。

核心优势

极致 Serverless

零服务器成本：纯前端部署 + Cloudflare Workers，无需自建后端服务器。
边缘加速：得益于 Cloudflare 的全球边缘网络，随时随地享受低延迟的 SSH 连接。

开箱即用

一键部署：通过 Wrangler 工具，一句命令即可完成项目构建与部署。
现代化前端技术栈：TypeScript + Vite + Tailwind CSS，配合 xterm.js 提供丝滑的终端体验。

安全可靠

端到端加密：完整的 SSH-2.0 协议实现，支持 Curve25519-SHA256（优先）和 ECDH-NISTP256 密钥交换，AES-256-GCM（优先）/ AES-128-GCM / AES-256-CTR 数据加密，以及 HMAC-SHA2-256/512 完整性校验。
多算法主机密钥验证：支持 Ed25519、ECDSA P-256、RSA 签名验证，首次连接展示 SHA-256 指纹（TOFU 模式）。
安全加固体系：内置针对 IPv6 与保留地址的 SSRF 防护、API 请求频率限制（防爆破），并在本地使用 AES-256-GCM 算法加密存储您的服务器凭证。
人机验证：支持 Cloudflare Turnstile 验证，防止恶意机器人滥用。
隔离的会话状态：借助 Cloudflare Durable Objects 和 Hibernation API，每个终端会话都在沙盒内安全、持久地运行。
凭据零暴露：One-Time-Token 机制确保密码/私钥不经过前端，完全在 Worker 内部安全流转。

核心特性

纯 TypeScript SSH-2.0 实现：完全自研的 SSH 协议栈，不依赖任何第三方 SSH 库，基于 Web Crypto API 实现全部加密操作。
多算法密钥交换：支持 Curve25519-SHA256（优先）和 ECDH-NISTP256 两种 KEX 算法，适配各类 SSH 服务器（包括 Dropbear）。
IPv4/IPv6 双栈：完整支持 IPv4 和 IPv6 地址连接，包括 IPv6 方括号格式自动处理。
多种认证方式：支持标准 SSH 密码认证以及基于 Ed25519 的纯文本私钥认证。
防范中间人攻击 (TOFU)：首次连接自动提取服务器 Host Key（SHA-256 指纹）并显示，支持 Ed25519/ECDSA/RSA 签名验证。
全功能极客终端：基于 @xterm/xterm 与 @xterm/addon-webgl 硬件加速渲染引擎，保证海量日志输出顺滑不卡顿。
个性化 UI：提供 Cyberpunk、Glacier、Gruvbox 等经典终端主题一键切换，支持移动端适配。
原生文件传输：集成 trzsz.js，支持 trz（上传）/ tsz（下载）命令进行文件传输，兼容 tmux 会话。还支持拖拽文件到终端窗口直接上传、目录传输及断点续传等高级功能。（需远程服务器安装 trzsz）
GitHub OAuth 集成：支持 GitHub 登录，用户可保存和管理常用 SSH 服务器，实现一键连接。

架构说明

系统架构

flowchart TB
    subgraph "浏览器客户端"
        UI["前端 UI<br/>TypeScript + xterm.js"]
        Trzsz["trzsz 文件传输"]
    end
    
    subgraph "Cloudflare Edge Network"
        Worker["Worker<br/>路由 + API"]
        SSH_DO["SSHSessionDO<br/>SSH 会话管理"]
        User_DO["UserDBDO<br/>用户数据管理"]
    end
    
    subgraph "目标服务器"
        SSH["SSH 服务器<br/>(OpenSSH/Dropbear)"]
    end

    UI <-->|"WebSocket<br/>终端 I/O"| Worker
    Trzsz <-->|"trzsz 协议"| UI
    Worker <-->|"WebSocket"| SSH_DO
    Worker <-->|"Internal API"| User_DO
    SSH_DO <-->|"TCP Socket<br/>@cloudflare/sockets"| SSH

核心组件

组件	文件	职责
Worker 入口	`src/worker/index.ts`	HTTP 路由、API 处理、WebSocket 升级
SSHSessionDO	`src/worker/durable-object.ts`	SSH 会话生命周期管理、SSRF 防护
UserDBDO	`src/worker/user-db.ts`	用户数据、服务器配置、速率限制（SQLite）
SSHSession	`src/worker/ssh-session.ts`	SSH 协议状态机（连接→版本→密钥交换→认证→交互）
SSH 协议栈	`src/ssh/*.ts`	纯 TypeScript SSH-2.0 实现（传输层、加密、认证、通道）
前端终端	`frontend/src/terminal.ts`	xterm.js 封装、trzsz 集成、WebSocket 管理

SSH 协议实现

本项目实现了完整的 SSH-2.0 协议栈：

层级	实现	支持算法
密钥交换	`kex-curve25519.ts` / `kex-ecdh.ts`	curve25519-sha256, ecdh-sha2-nistp256
数据加密	`crypto.ts`	aes256-gcm, aes128-gcm, aes256-ctr, aes192-ctr, aes128-ctr
完整性校验	`crypto.ts`	hmac-sha2-256, hmac-sha2-512, hmac-sha1
主机密钥	`ssh-session.ts`	Ed25519, ECDSA P-256, RSA
用户认证	`auth.ts`	密码认证, Ed25519 公钥认证
通道管理	`channel.ts`	session channel, PTY, shell, window-change

数据流

用户在前端输入主机 IP、账号和密码（或通过 GitHub OAuth 选择已保存的服务器）。
前端与后端的 Durable Object 建立 WebSocket 连接。
SSHSessionDO 接收凭据，使用 @cloudflare/sockets 与目标 SSH 服务器建立 TCP 连接。
SSHSession 执行完整的 SSH 协议协商（版本交换→密钥交换→认证→打开通道→PTY→Shell）。
加密的终端数据通过 WebSocket 在前端和 SSH 服务器之间双向转发。

快速部署

前置要求

一个 Cloudflare 账号。
Node.js 环境 (v18+)。
启用 Cloudflare Workers 免费计划（TCP Sockets 和 Durable Objects 功能需要）。

部署步骤

方式一：通过 GitHub 绑定自动部署（推荐）

Fork 本仓库 到你的 GitHub 账号。
创建 Worker 应用：登录 Cloudflare，进入 Workers & Pages，点击创建应用，绑定你的 GitHub 账号，选择 Fork 的仓库。
填写构建命令：在部署设置中，将"构建命令"（Build command）填写为 pnpm run build:frontend，点击保存并部署。
访问应用：部署成功后，可通过默认域名 https://cloudssh.<你的子域>.workers.dev 访问。
绑定自定义域名（可选）：进入 Worker 的 Settings → Domains & Routes → Add，输入你的域名并确认。

说明：如需部署 test 环境，可 Fork 后在 test 分支上重复上述步骤，创建独立的 Worker（如 cloudssh-test），两个 Worker 共享相同的 DO 类名即可实现数据互通。

方式二：本地命令行部署

克隆仓库

git clone https://github.com/newbietan/CloudSSH.git
cd CloudSSH

安装依赖

npm install -g pnpm
pnpm install
cd frontend && pnpm install

登录 Cloudflare
```
npx wrangler login
```
部署生产环境
```
pnpm run deploy
```
部署测试环境（可选）
```
pnpm run deploy:test
```

环境	命令	默认域名	说明
Production	`pnpm run deploy`	`cloudssh.<子域>.workers.dev`	main 分支代码
Test	`pnpm run deploy:test`	`cloudssh-test.<子域>.workers.dev`	test 分支代码，与生产环境共享 DO 数据

说明：两个环境的 Durable Objects 绑定相同的 class_name，数据完全共享。部署完成后可在 Cloudflare Dashboard 中分别绑定不同的自定义域名（Settings → Domains & Routes）。

可选：配置 Turnstile 人机验证

为防止恶意机器人滥用，建议启用 Cloudflare Turnstile 验证：

创建 Turnstile Widget：登录 Cloudflare Dashboard，进入 Turnstile 页面创建一个新的 Widget。
获取密钥：创建后会获得一个 Site Key（公开）和一个 Secret Key（保密）。
配置环境变量：在 Cloudflare Dashboard 的 Workers 设置中，进入 "Settings" → "Variables and Secrets"，添加以下环境变量：
- TURNSTILE_SECRET = 你的 Secret Key（类型选择 Secret）
- TURNSTILE_SITEKEY = 你的 Site Key（类型选择 Text）
重新部署：运行部署命令使配置生效。

说明：Turnstile 验证为会话级别，用户通过验证后当前会话内所有功能可用，关闭浏览器后需重新验证。

可选：配置 GitHub OAuth 登录与服务器管理

启用 GitHub 登录后，用户可以通过 GitHub 账号登录，并在个人空间中保存和管理常用的 SSH 服务器，实现一键连接。不配置时，此功能自动隐藏，不影响匿名 SSH 连接的正常使用。

创建 GitHub OAuth App：
- 登录 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
- Application name：CloudSSH（自定义）
- Homepage URL：https://your-domain.com（你的部署域名）
- Authorization callback URL：https://your-domain.com/api/auth/callback
- 创建后获得 Client ID，点击 Generate a new client secret 生成 Client Secret（仅显示一次，请立即保存）
配置环境变量：在 Cloudflare Dashboard 的 Workers 设置中，进入 "Settings" → "Variables and Secrets"，添加以下环境变量：
- GITHUB_CLIENT_ID = 你的 Client ID（类型选择 Text）
- BASE_URL = https://your-domain.com（你的部署域名，类型选择 Text）
- GITHUB_CLIENT_SECRET = 你的 Client Secret（类型选择 Secret）
重新部署：如果你是刚刚修改了环境变量，且是首次启用该功能，请务必删除旧版并全新部署以初始化数据库。

说明：服务器凭据（密码/私钥）在数据库中使用 AES-256-GCM 加密存储，本地加密密钥将自动生成并安全地存储在数据库中（也可在环境变量中手动设置 SESSION_SECRET 来指定）。连接时凭据不经过前端，通过 one-time-token 机制安全传递。

注意：首次启用此功能需要从零部署（删除旧 Worker 后重新部署），因为需要初始化新的 Durable Object。可通过 npx wrangler delete cloudssh 删除旧 Worker，然后运行 pnpm run deploy 重新部署。

开发说明

项目结构

本项目采用 pnpm monorepo 工作区结构：

CloudSSH/
├── src/                    # 后端源码 (Cloudflare Worker)
│   ├── ssh/                # SSH 协议纯实现层
│   └── worker/             # Worker 入口和 Durable Objects
├── frontend/               # 前端源码 (独立 workspace)
│   ├── src/                # TypeScript + xterm.js + trzsz
│   └── package.json        # 前端依赖
├── scripts/                # 构建脚本
├── pnpm-workspace.yaml     # pnpm 工作区配置
└── wrangler.toml           # Cloudflare 部署配置

本地开发

环境准备

Fork 并克隆仓库

git clone https://github.com/<你的用户名>/CloudSSH.git
cd CloudSSH

安装依赖（需分别安装根目录和前端依赖）
```
pnpm install
cd frontend && pnpm install
```
登录 Cloudflare（首次需要，后续会缓存凭据）
```
npx wrangler login
```
说明：本地开发使用 Wrangler Dev 时，会连接到你的 Cloudflare 账号以使用 Durable Objects 和 TCP Sockets。SSH 连接的真实 TCP 流量会通过 Cloudflare 的基础设施转发。

启动开发服务器

pnpm run dev

此命令将构建前端并启动 Wrangler 本地开发环境，支持：

前端代码变更自动重新构建
Worker 代码变更自动重新加载
完整的 Durable Objects 和 TCP Sockets 功能

开发服务器启动后，访问终端输出的本地地址（通常为 http://localhost:8787）即可进行调试。

常用开发命令

命令	说明
`pnpm run dev`	构建前端 + 启动 Wrangler 开发服务器
`pnpm run build:frontend`	仅构建前端（输出到 `frontend/dist/`）
`pnpm test`	运行测试

提交 PR 的流程

基于 main 分支创建你的特性分支：git checkout -b feat/your-feature
进行开发并本地测试
提交 PR 到 main 分支

说明：test 分支为预发布分支，用于部署测试环境，普通开发请基于 main 分支工作。

技术栈

层级	技术	说明
前端	TypeScript + Vite + xterm.js	Web 终端模拟器，WebGL 硬件加速
UI 框架	Tailwind CSS (CDN)	赛博朋克风格暗色主题
文件传输	trzsz.js	支持 trz/tsz 命令、拖拽上传、断点续传
后端	Cloudflare Workers	Serverless 边缘计算
会话管理	Durable Objects	SSH 会话隔离、Hibernation API
数据存储	Durable Objects SQLite	用户数据、服务器配置
包管理	pnpm (workspace)	Monorepo 依赖管理

开源协议

本项目基于 Apache License 2.0 协议开源。

特别声明：本项目允许商业使用及二次修改，但必须明确注明原作者。

欢迎提交 Issue 和 Pull Request 共建社区。如果这个项目对你有帮助，恳求大家给本项目点个 ⭐ Star 支持一下，非常感谢！

16 KiB Raw Blame History Unescape Escape