okooooooo/EdgeSSH
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: prioritize custom domain setup and bilingual UI labels

Browse Source
This commit is contained in:
gdz66601 committed 2026-09-23 00:43:34 +08:00
1 parent e5bc7090e2
commit 8505da5262
2 files changed
+33 -28
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

DEPLOYMENT.md
+22 -20
View File
@@ -1,36 +1,39 @@
# EdgeSSH 部署与验收
## 先选择一种登录方式
## 先确定入口并选择一种登录方式
本项目只有一个管理员、一份主机资料库。`AUTH_PROVIDER` 决定唯一生效的认证方式，不同时维护两套登录状态。两种方式都部署到 Cloudflare Workers，但 **GitHub 模式不需要 Zero Trust 或 Access 权限**。
在 GitHub **Settings > Secrets and variables > Actions** 配置：
多数用户建议先准备自定义域名，例如 `ssh.example.com`。在 GitHub **设置（Settings）> 机密和变量（Secrets and variables）> Actions** 配置：
| 名称 | 类型 | Cloudflare 模式 | GitHub 模式 |
| --- | --- | --- | --- |
| `AUTH_PROVIDER` | Variable | `cloudflare`（默认） | `github` |
| `CLOUDFLARE_API_TOKEN` | Secret | 必填 | 必填 |
| `CUSTOM_DOMAIN` | Variable | 推荐填写实际主机名 | 推荐填写实际主机名 |
| `ADMIN_EMAIL` | Variable | 管理员邮箱 | 不需要 |
| `GITHUB_CLIENT_ID` | Variable | 不需要 | OAuth App 的 Client ID |
| `GITHUB_CLIENT_SECRET` | Secret | 不需要 | OAuth App 的 Client Secret |
| `GITHUB_ADMIN` | Variable | 不需要 | 允许登录的唯一 GitHub 用户名，不是邮箱或组织名 |
`CUSTOM_DOMAIN` 只填完整主机名，不带 `https://`、路径或通配符。域名必须由部署账户的 Cloudflare Zone 管理；Action 会自动绑定 Worker，Cloudflare 负责 DNS 与证书。需要使用免费 `workers.dev` 地址时将它留空，不能填写 `*.workers.dev`。
敏感值不要放 Variable。工作流只校验所选方式的配置，另一种方式的旧配置不会参与认证。
## Cloudflare 模式准备
1. 在 Cloudflare **启用 Zero Trust**，完成团队域名与计划初始化。组织开通涉及账户确认，不由脚本代办。
2. Fork 本仓库，启用 GitHub Actions，在 **Settings > Secrets and variables > Actions** 保存 `CLOUDFLARE_API_TOKEN` Secret。
3. 在 **Actions > Deploy > Run workflow** 输入管理员邮箱，运行并等待摘要给出访问地址。可将邮箱保存为 `ADMIN_EMAIL` Variable，省去重复输入。
2. Fork 本仓库，启用 GitHub Actions，在 **设置（Settings）> 机密和变量（Secrets and variables）> Actions** 保存 `CLOUDFLARE_API_TOKEN` Secret，并按上表保存 `CUSTOM_DOMAIN` 与 `AUTH_PROVIDER` Variable。
3. 在 **Actions > Deploy > 运行工作流（Run workflow）** 输入管理员邮箱，运行并等待摘要给出访问地址。可将邮箱保存为 `ADMIN_EMAIL` Variable，省去重复输入。
无需手动创建 Access 应用、OTP、D1，也无需抄录 Account ID、Team Domain 或 AUD。默认入口是 `https://edgessh.<账户子域>.workers.dev`。没有自定义域名也能使用。
无需手动创建 Access 应用、OTP、D1，也无需抄录 Account ID、Team Domain 或 AUD。填写 `CUSTOM_DOMAIN` 时使用自定义域名；留空才使用 `https://edgessh.<账户子域>.workers.dev`。
## GitHub 模式准备
1. 打开 GitHub **Settings > Developer settings > OAuth Apps > New OAuth App**。
2. Application name 自定；Homepage URL 填 EdgeSSH 地址，Authorization callback URL 填 `https://你的入口/auth/callback`。
1. 打开 GitHub **设置（Settings）> 开发者设置（Developer settings）> OAuth 应用（OAuth Apps）> 新建 OAuth 应用（New OAuth App）**。
2. **应用名称（Application name）**自定；**主页 URL（Homepage URL）**填 EdgeSSH 地址，**授权回调 URL（Authorization callback URL）**填 `https://你的入口/auth/callback`。
3. 保存 Client ID，生成一个 Client Secret，按上表分别保存到 Actions Variable 和 Secret。
4. 设置 `AUTH_PROVIDER=github`、`GITHUB_ADMIN=你的GitHub用户名`，保存 Cloudflare API Token，然后运行 **Actions > Deploy**。邮箱输入框留空。
4. 设置 `AUTH_PROVIDER=github`、`CUSTOM_DOMAIN=你的主机名`、`GITHUB_ADMIN=你的GitHub用户名`，保存 Cloudflare API Token，然后运行 **Actions > Deploy**。使用 `workers.dev` 时才省略 `CUSTOM_DOMAIN`；邮箱输入框留空。
5. 若首次部署前不知道入口，可先为 OAuth App 使用占位 URL；部署后将 Action 摘要中的正式入口与回调地址复制回 OAuth App 设置，再登录。
GitHub OAuth App 必须由用户在 GitHub 创建；普通 GitHub Token 没有官方“创建 OAuth App”的 REST 接口，工作流不会假装自动完成它。
@@ -39,20 +42,20 @@ GitHub OAuth App 必须由用户在 GitHub 创建；普通 GitHub Token 没有
## API Token 权限
以 Cloudflare **Edit Cloudflare Workers** 模板为起点，保留部署所需权限，并补齐以下账户权限。控制台的 Edit/Read 对应 API 文档的 Write/Read。
在 Cloudflare **我的个人资料（My Profile）> API 令牌（API Tokens）> 创建令牌（Create Token）**，以 **编辑 Cloudflare Workers（Edit Cloudflare Workers）** 模板为起点，保留部署所需权限，并补齐以下账户权限。Cloudflare 中文界面可能仍显示部分英文；下表同时保留英文原名。控制台的编辑（Edit）/读取（Read）对应 API 文档的 Write/Read。
| 账户权限 | 级别 | 用途 |
| 账户（Account）权限 | 级别 | 用途 |
| --- | --- | --- |
| Workers Scripts | Edit | Worker、Durable Object、Secret 和子域部署 |
| Workers KV Storage | Edit | 保留官方 Workers 模板的部署权限 |
| Account Settings | Read | 自动发现账户 |
| D1 | Edit | 查找/创建数据库、检查旧数据与执行迁移 |
| Access: Apps and Policies | Edit | **仅 cloudflare 模式**：查找/创建应用及邮箱策略 |
| Access: Organizations, Identity Providers, and Groups | Edit | **仅 cloudflare 模式**：获取团队域名、查找/创建 OTP |
| Workers 脚本（Workers Scripts） | 编辑（Edit） | Worker、Durable Object、Secret 和子域部署 |
| Workers KV 存储（Workers KV Storage） | 编辑（Edit） | 保留官方 Workers 模板的部署权限 |
| 账户设置（Account Settings） | 读取（Read） | 自动发现账户 |
| D1 | 编辑（Edit） | 查找/创建数据库、检查旧数据与执行迁移 |
| Access：应用和策略（Apps and Policies） | 编辑（Edit） | **仅 cloudflare 模式**：查找/创建应用及邮箱策略 |
| Access：组织、身份提供程序和组（Organizations, Identity Providers, and Groups） | 编辑（Edit） | **仅 cloudflare 模式**：获取团队域名、查找/创建 OTP |
账户资源只选择实际部署账户。若 Token 可访问多个账户，设置 Actions Variable `CLOUDFLARE_ACCOUNT_ID`，脚本不会猜测目标账户。
只用 `workers.dev` 不需要自定义域名的 Zone 权限。使用 `CUSTOM_DOMAIN` 时，还需模板的 **Zone > Workers Routes: Edit、Zone: Read**，并将区域范围限定到该域名所在 Zone。域名必须已经由同账户的 Cloudflare 管理。
只用 `workers.dev` 不需要自定义域名的区域权限。使用 `CUSTOM_DOMAIN` 时，还需模板的 **区域（Zone）> Workers 路由（Workers Routes）：编辑（Edit）、区域（Zone）：读取（Read）**，并将区域资源范围限定到该域名所在 Zone。域名必须已经由同账户的 Cloudflare 管理。
API Token 只存 GitHub Secret，不放普通变量、代码或命令行输入框。不要将 Token 填到 Run workflow 的邮箱字段。
@@ -60,7 +63,7 @@ API Token 只存 GitHub Secret，不放普通变量、代码或命令行输入
1. 校验本地配置，运行类型检查、测试、前端构建和 Wrangler dry-run。
2. 自动发现唯一账户（显式账户 ID 优先），读取现有 Worker Secret **名称**，不尝试读取密钥明文。
3. 默认读取账户 `workers.dev` 子域；未注册时自动注册确定性名称。已有子域不改名，避免影响其他 Worker。
3. 有 `CUSTOM_DOMAIN` 时使用该入口；否则读取账户 `workers.dev` 子域，未注册时自动注册确定性名称。已有子域不改名，避免影响其他 Worker。
4. 根据 `AUTH_PROVIDER` 仅准备所选认证：Cloudflare 配置 Access/OTP/Allow，GitHub 验证指定管理员并准备 OAuth Secret。
5. GitHub 模式不调用 Zero Trust API；Cloudflare 模式不需要 GitHub OAuth 参数。既有 Access 应用不重写人工 IdP 配置。
6. 按 ID 或名称复用 D1，不存在才创建；指定 ID 不存在时直接失败，不用新空库替代。
@@ -72,7 +75,7 @@ API Token 只存 GitHub Secret，不放普通变量、代码或命令行输入
设置自定义域名时关闭备用 `workers.dev` 入口，所有部署关闭 preview URL。Cloudflare 模式校验 Access JWT；GitHub 模式使用 state、PKCE 和签名 HttpOnly Cookie。缺少认证不降级为匿名 SSH。
## 可选配置
## 其他可选配置
| 名称 | GitHub 位置 | 默认/示例 |
| --- | --- | --- |
@@ -81,7 +84,6 @@ API Token 只存 GitHub Secret，不放普通变量、代码或命令行输入
| `WORKER_NAME` | Variable | `edgessh` |
| `D1_DATABASE_NAME` | Variable | `<Worker 名>-accounts` |
| `D1_DATABASE_ID` | Variable | 指定已有 D1 UUID，不填则按名称查找 |
| `CUSTOM_DOMAIN` | Variable，兼容 Secret | `ssh.example.com`；Secret 优先；`*.workers.dev` 不可填 |
| `ACCESS_IDP_IDS` | Variable | 新应用采用的 IdP UUID，多个用逗号分隔 |
| `ENCRYPTION_KEY` | Secret，仅恢复/迁移使用 | 仅 Worker 尚无密钥时使用；已有密钥不会覆盖 |
README.md
+11 -8
View File
@@ -101,30 +101,34 @@ SSH 握手、密钥交换、认证与通道逻辑在 Worker 内完成。浏览
- Node.js **22.12.0 或更高版本**，以及 npm。
- 可使用 Workers、Durable Objects 与 D1 的 Cloudflare 账户。
- 选择 Cloudflare Access 或原生 GitHub OAuth。GitHub 模式不需要开通 Zero Trust，自定义域名可选。
- 准备一个由同一 Cloudflare 账户管理的自定义域名（推荐），或使用自动分配的 `workers.dev` 地址。
- 选择 Cloudflare Access 或原生 GitHub OAuth。GitHub 模式不需要开通 Zero Trust。
- 一台你有权访问的公网 SSH 服务器。
### 一次运行，自动配置认证与部署
在 Fork 的 **Settings > Secrets and variables > Actions** 设置 `AUTH_PROVIDER` Variable，二选一；未填写时默认 `cloudflare`，兼容旧部署。两种模式都将应用部署到 Cloudflare Workers，**不是选择云服务商**。
在 Fork 的 **设置（Settings）> 机密和变量（Secrets and variables）> Actions** 设置 `AUTH_PROVIDER` Variable，二选一；未填写时默认 `cloudflare`，兼容旧部署。两种模式都将应用部署到 Cloudflare Workers，**不是选择云服务商**。
| 配置 | GitHub 位置 | `cloudflare` | `github` |
| --- | --- | --- | --- |
| `AUTH_PROVIDER` | Variable | `cloudflare` | `github` |
| `CLOUDFLARE_API_TOKEN` | Secret | 必填 | 必填，不需要 Access 权限 |
| `CUSTOM_DOMAIN` | Variable | 推荐，如 `ssh.example.com` | 推荐，如 `ssh.example.com` |
| `ADMIN_EMAIL` | Variable | 管理员邮箱，也可在 Run workflow 输入 | 不填 |
| `GITHUB_CLIENT_ID` | Variable | 不填 | OAuth App 的 Client ID |
| `GITHUB_CLIENT_SECRET` | Secret | 不填 | OAuth App 的 Client Secret |
| `GITHUB_ADMIN` | Variable | 不填 | 唯一允许登录的 GitHub 用户名 |
**Cloudflare 模式**：先启用 Zero Trust，然后运行 Action，自动配置 Access 应用、邮箱 Allow 策略和 OTP。
`CUSTOM_DOMAIN` 只填主机名，不带 `https://`、路径或通配符。域名需要由部署账户的 Cloudflare Zone 管理，Token 需要该 Zone 的 Workers Routes 编辑和 Zone 读取权限；Action 会自动绑定 Worker，Cloudflare 负责 DNS 与证书。确实使用 `workers.dev` 时才将它留空，且不要把 `*.workers.dev` 填进去。
**GitHub 模式**：先在 GitHub **Settings > Developer settings > OAuth Apps** 创建一个 OAuth App，回调地址填 `https://你的入口/auth/callback`。工作流会自动解析管理员数字 ID，跳过全部 Zero Trust 配置。入口尚不确定时，可先使用占位回调地址，部署后从 Action 摘要复制正式地址，再回 GitHub 更新。详情见[部署指南](DEPLOYMENT.md)。
**Cloudflare 模式**：先在 Cloudflare 控制台启用 Zero Trust，然后运行 Action，自动配置 Access 应用、邮箱 Allow 策略和 OTP。
**GitHub 模式**：先在 GitHub **设置（Settings）> 开发者设置（Developer settings）> OAuth 应用（OAuth Apps）** 创建一个 OAuth App，回调地址填 `https://你的入口/auth/callback`。工作流会自动解析管理员数字 ID，跳过全部 Zero Trust 配置。入口尚不确定时，可先使用占位回调地址，部署后从 Action 摘要复制正式地址，再回 GitHub 更新。详情见[部署指南](DEPLOYMENT.md)。
```text
选择登录方式 + 填写对应变量/Secret
确定自定义域名（或使用 workers.dev）+ 选择登录方式 + 填写对应变量/Secret
↓ Run workflow
发现账户与 workers.dev 子域 → 仅配置所选认证方式
发现账户并绑定自定义域名（或获取 workers.dev 子域）→ 仅配置所选认证方式
→ 创建/复用 D1 → 保留管理员资料归属 → 首次生成加密密钥
→ 数据库迁移 → 写入 Worker Secrets → 部署 Worker
↓
@@ -143,7 +147,7 @@ cd EdgeSSH
npm ci
```
### 可选配置
### 其他可选配置
以下通常都可以留空，保存为 Actions Variable：
@@ -154,7 +158,6 @@ npm ci
| `WORKER_NAME` | `my-edgessh` | 默认 `edgessh` |
| `D1_DATABASE_NAME` | `my-edgessh-accounts` | 默认 `<Worker 名>-accounts` |
| `D1_DATABASE_ID` | `00000000-0000-4000-8000-000000000001` | 复用明确指定的数据库 |
| `CUSTOM_DOMAIN` | `ssh.example.com` | 真正的自定义域名；`*.workers.dev` 必须留空；兼容 Secret，Secret 优先 |
| `ACCESS_IDP_IDS` | `一个或多个 IdP UUID，以逗号分隔` | 创建新应用时使用已有 GitHub/其他 IdP，而非自动配置 OTP |
`ENCRYPTION_KEY` 由部署流程管理并持久保存在 **Cloudflare Worker Secrets**；Cloudflare 模式另存 `ACCESS_TEAM_DOMAIN`、`ACCESS_AUD`，GitHub 模式同步 `GITHUB_CLIENT_SECRET`。不需要用户复制自动生成的值回 GitHub。加密密钥只在首次部署生成，后续保留，即使 GitHub 留有旧值也不会覆盖线上密钥。不要删除 Worker 或其加密密钥；Cloudflare 不提供密钥明文读回，丢失后无法解密已有资料。