0 Fork 0

Files

T

gdz66601 082c458897 docs: prefer Cloudflare dashboard configuration

2026-09-19 08:50:11 +08:00

13 KiB

Raw Blame History

本项目基于 Worker Web SSH（CF-Workers-WebSSH）深度开发。
在上游原生 WebSSH 能力的基础上，扩展主机管理、加密云端存储、地球可视化与操作系统识别，打造面向个人管理员的云端 SSH 工作台。感谢原作者的开源贡献。

EdgeSSH

打开浏览器，连接你的服务器。

运行于 Cloudflare Workers 的轻量 SSH 工作台
主机总览 · 交互终端 · 文件管理 · 进程监控

功能特性 · 界面预览 · 快速开始 · 本地开发 · 安全与限制

界面预览

_{演示数据使用保留地址，不对应任何真实服务器。}

功能特性

🗂️ 主机管理

集中保存服务器资料与连接凭据，支持搜索、分组筛选与编辑。从列表直接进入工作台，无需反复输入连接信息。

🌍 地球可视化

以可交互地球呈现主机地理位置，支持点位连接、刷新定位，配合城市与国旗展示服务器分布。

⌨️ 浏览器终端

基于 xterm.js，支持交互式 Shell、窗口尺寸同步、全屏与会话日志，适配桌面和移动端，工作台支持中英文切换。

📁 SFTP 文件管理

在终端旁浏览远程目录，上传与下载文件、新建目录、重命名，以及删除文件或空目录。

📊 实时进程面板

通过独立通道查看远端进程与 CPU、负载、内存和 Swap 信息，无需离开 SSH 工作台。

🐧 系统自动识别

通过 SSH 命令探测操作系统，记录系统版本与架构，并以品牌色圆角图标区分常见系统与发行版。

不只是一个终端

边缘原生：Worker 通过 Cloudflare TCP Sockets 直接连接 SSH 服务器，无需额外部署 SSH 中转服务，每个会话由 Durable Object 隔离。
身份保护：使用 Cloudflare Zero Trust Access 认证管理员，不提供匿名连接入口或本地注册登录。
加密存储：主机资料、密码、私钥与指纹通过 AES-256-GCM 加密后保存到 D1，浏览器不持久化连接凭据。
指纹确认：首次连接时展示服务器 SHA-256 指纹，确认后才发送 SSH 凭据。
灵活连接：支持密码、单密码提示的 keyboard-interactive，以及未加密 OpenSSH 私钥认证；支持 UTF-8、GB18030、Big5 终端编码。
轻量实现：TypeScript + Vite + Web Crypto；地球采用 Canvas 球面投影，不引入 Three.js 等大型三维依赖。

工作原理

浏览器 · 主机总览 / xterm.js / SFTP / 进程面板
    │ HTTPS / WebSocket · Cloudflare Access 身份认证
    ▼
Cloudflare Worker
    ├── 静态资源与 API
    ├── 主机资料加密读写 ──→ D1
    └── 一次性会话票据
            ▼
    Durable Object · 每会话 SSH 客户端
            │ Cloudflare TCP Socket
            ▼
        公网 SSH 服务器

SSH 握手、密钥交换、认证与通道逻辑在 Worker 内完成。浏览器连接的是 Worker，而不是直接建立到服务器的 TCP 连接。

快速开始

环境准备

Node.js 22.12.0 或更高版本，以及 npm。
可使用 Workers、Durable Objects 与 D1 的 Cloudflare 账户。
自定义域名及 Cloudflare Zero Trust Access 应用。
一台你有权访问的公网 SSH 服务器。

配置 Cloudflare Zero Trust Access

EdgeSSH 没有独立的本地登录系统，正式入口必须先经过 Cloudflare Zero Trust Access。首次部署时请先完成：

在 Zero Trust > Access controls（访问控制）> Applications（应用程序） 创建 Self-hosted and private（自托管和私有） 应用，并绑定 EdgeSSH 的自定义域名。
添加一条 Allow（允许） 策略，使用 Include > Emails 明确填写管理员邮箱；不要使用 Everyone（所有人） 或 Bypass（绕过）。
选择 Identity Provider（标识提供程序）。个人部署可使用 One-time PIN（一次性 PIN）；新建 Zero Trust 组织若没有该选项，需要先到 Integrations（集成）> Identity providers（标识提供程序） 手动添加。
从 Access 应用中取得 Application Audience (AUD) Tag（应用程序受众 (AUD) 标签），并从 Zero Trust Settings（设置） 取得 Team Domain（团队域）。
将它们分别写入 ACCESS_AUD 与 ACCESS_TEAM_DOMAIN Worker Secret。

完整的控制台点击步骤、OTP 配置、参数获取和故障排查见 Cloudflare Zero Trust 配置指南。

获取项目

git clone https://github.com/aozorae/EdgeSSH.git
cd EdgeSSH
npm ci

配置与部署

Important

本项目面向单管理员使用。Access 策略应仅允许管理员的明确身份，不要配置 Everyone 或 Bypass。缺少 Access 配置时，受保护 API 会拒绝访问，不会降级为匿名网关。

在 Cloudflare 控制台复用或创建 D1 数据库，并调整 wrangler.toml 中的 Worker 名称、自定义域名与 D1 database_id，不要直接使用仓库中原部署环境的资源 ID。
在 Zero Trust 控制台创建 Self-hosted Access 应用，只允许管理员的明确邮箱或身份，并记下 Team Domain 与 Application Audience (AUD) Tag。
在 GitHub 配置一个 Actions Variable 和一个 Actions Secret，首次运行 Deploy workflow；它会自动检查项目、迁移 D1 并创建或更新 Worker。
Worker 首次出现后，在 Cloudflare 控制台的 Workers & Pages > 你的 Worker（默认 edgessh）> Settings > Variables and Secrets 中添加三个运行时 Secret。保存并部署这些设置后即可通过 Access 入口验收。

配置	类型与位置	用途
`DB`	`wrangler.toml` 中的 D1 binding	保存加密主机资料
`SSH_SESSIONS`	`wrangler.toml` 中的 Durable Object binding	隔离 SSH 会话
`ASSETS`	`wrangler.toml` 中的静态资源 binding	提供前端资源
`ACCESS_TEAM_DOMAIN`	Cloudflare Worker Secret	Access 团队域名，如 `my-team.cloudflareaccess.com`，不含协议和路径
`ACCESS_AUD`	Cloudflare Worker Secret	Access 应用的 Application Audience (AUD) Tag
`ENCRYPTION_KEY`	Cloudflare Worker Secret	32 字节安全随机密钥的标准 Base64
`CONNECT_TIMEOUT_MS`	可选普通变量	TCP 建连超时；仓库已设为 `10000`，通常无需填写

生产运行时只需在 Cloudflare 控制台填写 ACCESS_TEAM_DOMAIN、ACCESS_AUD 与 ENCRYPTION_KEY 三个 Worker Secret。DB、SSH_SESSIONS 与 ASSETS 是部署时创建的绑定，不是环境变量；CONNECT_TIMEOUT_MS 已有默认配置，也无需重复添加。

首次部署才生成 ENCRYPTION_KEY，后续部署始终复用原值。 丢失或直接替换密钥会导致已有资料无法解密。密钥只粘贴到 Cloudflare 的 Secret 输入框，不要写入源码、wrangler.toml、GitHub Actions 或提交记录。

完整配置顺序、安全边界与验收清单见部署指南。

GitHub Actions 自动部署

仓库内置的 Deploy workflow 会在推送到 main 后自动检查、迁移 D1 并部署，也可在 Actions 页面手动触发。首次使用前，在仓库的 Settings > Secrets and variables > Actions 中配置：

名称	GitHub 配置类型	用途
`CLOUDFLARE_ACCOUNT_ID`	Variable	Cloudflare 账户 ID
`CLOUDFLARE_API_TOKEN`	Secret	具备 Workers 部署和 D1 迁移权限的 API Token

Action 只需要这两项部署凭据。创建 API Token 时，可使用 Cloudflare 的 Edit Cloudflare Workers 模板并补充 D1: Edit，再将 Account 与 Zone Resources 限制到实际使用的账户和域名；该模板会覆盖 Worker 与自定义域名部署所需权限。ACCESS_TEAM_DOMAIN、ACCESS_AUD 与 ENCRYPTION_KEY 只保存在 Cloudflare Worker Secrets 中，普通部署不会读取或覆盖它们。API Token 属于敏感信息，必须使用 GitHub Secret，不能保存为普通 Variable。

本地开发

安装依赖并准备本地变量：

npm ci
cp .env.example .dev.vars
npx wrangler d1 migrations apply DB --local
npm run dev

按部署指南在 .dev.vars 中填写所需配置。本地开发仍保留 Access 身份校验，不提供匿名绕过；本地变量文件不得提交。

需要前端热更新时，在另一个终端运行 npm run dev:web。Vite 默认位于 http://localhost:5173，将 /api 代理到本地 Worker 的 8787 端口；公网目标限制在本地同样生效。

命令	说明
`npm run dev`	构建前端并启动本地 Worker
`npm run dev:web`	启动 Vite 前端开发服务器
`npm run build:web`	构建前端到 `dist/`
`npm run typecheck`	检查 Worker 与前端类型
`npm test`	运行测试
`npm run check`	类型检查、测试与部署 dry-run（包含前端构建）
`npm run deploy`	构建前端并部署 Worker

项目结构

EdgeSSH/
├── .github/workflows/ # GitHub Actions 自动部署
├── frontend/          # 主机总览、地球可视化与 SSH 工作台
├── src/
│   ├── accounts/      # Access 认证、主机管理与加密存储
│   ├── backend/       # 会话生命周期、SFTP 与系统信息探测
│   ├── ssh/           # SSH 协议、认证、密码学与通道
│   └── worker.ts      # HTTP、API 与 WebSocket 入口
├── migrations/        # D1 数据库迁移
├── tests/             # 自动化测试
├── DEPLOYMENT.md      # 部署与验收指南
└── wrangler.toml      # Worker 与资源绑定配置

安全与限制

安全边界

不是端到端加密：Worker 是实际的 SSH 客户端，会在会话内处理明文凭据。请仅部署到可信账户，并使用最小权限的 SSH 账号或密钥。
主机资料绑定 Access 身份；会话使用一次性票据，辅助通道使用附着令牌，并检查同源请求。
连接目标仅限公网地址；域名解析后校验目标 IP，降低 SSRF 与 DNS 重绑定风险。
地理定位会向外部定位服务发送服务器公网 IP，不发送 SSH 凭据或命令；位置点位不代表在线状态。
建议通过受 Access 保护的自定义域名访问；若保留 workers.dev 诊断入口，不应将其视为公开 SSH 入口。

当前支持范围

类别	支持情况
会话	SSH 2.0、交互式 Shell、PTY、窗口尺寸同步、Keepalive
文件协议	SFTP v3；单文件上传与下载上限 64 MiB；仅删除空目录
私钥认证	未加密 OpenSSH Ed25519、RSA、ECDSA P-256/P-384/P-521
主机管理	每个身份最多 200 台；不支持团队共享
终端编码	UTF-8、GB18030、Big5，取决于浏览器解码支持

暂不支持加密私钥、PEM/PKCS#8 私钥、SSH Agent、多因素键盘交互认证、SCP、端口转发、ProxyJump、SSH 压缩与会话内 rekey；不支持出站 TCP 25 端口。

参与贡献

欢迎通过 Issue 反馈问题或通过 Pull Request 提交改进。提交前请运行 npm run check；涉及连接、文件传输或进程面板的改动，请使用真实且已获授权的 SSH 目标验证。

反馈时请附上复现步骤和必要的环境信息，不要上传密码、私钥、Access Token 或未脱敏的日志。

致谢

Worker Web SSH / cmliu/CF-Workers-WebSSH：本项目的直接上游与开发基础。
huashengdun/webssh：WebSSH 终端与前端兼容 API 参考。
newbietan/CloudSSH：Cloudflare Workers SSH 实现参考。
crazypeace/huashengdun-webssh：WebSSH 二次开发与前端兼容性参考。

13 KiB Raw Blame History Unescape Escape