docs: prefer Cloudflare dashboard configuration
This commit is contained in:
gdz66601 committed
1 parent
dd7c106748
commit
082c458897
4 files changed
+101
-58
No files matched your search
+1
-1
@@ -3,4 +3,4 @@ CONNECT_TIMEOUT_MS=10000
|
||||
# Zero Trust 团队域名（不带 https://）及此应用的 audience，不能使用测试绕过开关。
|
||||
ACCESS_TEAM_DOMAIN=your-team.cloudflareaccess.com
|
||||
ACCESS_AUD=your-access-application-audience
|
||||
# ENCRYPTION_KEY 必须为 32 字节安全随机数的 Base64；本地写入 .dev.vars，生产使用 wrangler secret put。
|
||||
# ENCRYPTION_KEY 必须为 32 字节安全随机数的 Base64；本文件只用于本地开发，生产值在 Cloudflare Worker 控制台中保存为 Secret。
|
||||
+71
-16
@@ -13,23 +13,78 @@
|
||||
|
||||
## 必需配置
|
||||
|
||||
| 名称 | 配置方式 | 含义 |
|
||||
| 名称 | 配置位置 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| `DB` | D1 binding | `edgessh-accounts` 数据库，优先复用已有资源 |
|
||||
| `ACCESS_TEAM_DOMAIN` | **Worker Secret** | 团队域名，例如 `my-team.cloudflareaccess.com`，不含协议或路径 |
|
||||
| `ACCESS_AUD` | **Worker Secret** | 此 Access 应用的 Application Audience (AUD) Tag |
|
||||
| `ENCRYPTION_KEY` | **Worker Secret** | 32 字节安全随机数的标准 Base64 |
|
||||
| `SSH_SESSIONS` | Durable Object binding | 保留上游 DO 类及迁移历史 |
|
||||
| `DB` | `wrangler.toml` 的 D1 binding | 主机资料数据库，优先复用已有资源 |
|
||||
| `SSH_SESSIONS` | `wrangler.toml` 的 Durable Object binding | SSH 会话隔离，保留现有类名及迁移历史 |
|
||||
| `ASSETS` | `wrangler.toml` 的静态资源 binding | 前端构建产物，不需要手动创建 |
|
||||
| `ACCESS_TEAM_DOMAIN` | Cloudflare Worker Secret | 团队域名，例如 `my-team.cloudflareaccess.com`，不含协议或路径 |
|
||||
| `ACCESS_AUD` | Cloudflare Worker Secret | 此 Access 应用的 Application Audience (AUD) Tag |
|
||||
| `ENCRYPTION_KEY` | Cloudflare Worker Secret | 32 字节安全随机数的标准 Base64 |
|
||||
| `CONNECT_TIMEOUT_MS` | 可选普通变量 | 建连超时；仓库默认 `10000`，通常不要额外配置 |
|
||||
|
||||
### 部署顺序
|
||||
`DB`、`SSH_SESSIONS` 与 `ASSETS` 是绑定，不是环境变量。生产环境实际需要手动填写的运行时值只有三个 Worker Secret。
|
||||
|
||||
1. 检查 Cloudflare 已有 Worker、D1；确认目标应用为本项目，避免覆盖其他项目。不自动读取或配置 Zero Trust。
|
||||
2. 复用或创建 `edgessh-accounts`，将目标环境的真实 `database_id` 写入 `wrangler.toml`；仓库当前配置的是线上数据库。
|
||||
3. Zero Trust 应用、域名及单管理员 Allow 策略由用户自行配置，本项目部署过程不代为创建或修改。
|
||||
4. 用户配置 Access 后，分别通过 `wrangler secret put ACCESS_TEAM_DOMAIN` 与 `wrangler secret put ACCESS_AUD` 注入。所有账号、主机与连接 API 均需 Access 保护；`workers.dev` 只允许固定测试 IP 的无敏感信息诊断。缺少这两个 Secret 时可先部署，但受保护 API 会返回 503，不能操作主机或连接 SSH。
|
||||
5. **只在首次部署时生成密钥**，通过标准输入执行 `wrangler secret put ENCRYPTION_KEY` 注入。不要在命令参数、源码、日志或明文配置里输出密钥。已有 Secret 必须复用，不可随意覆盖。
|
||||
6. 执行 `npx wrangler d1 migrations apply DB --remote`，仅添加 schema，不清空或重置数据。
|
||||
7. 执行 `npm run check`，然后 `npm run deploy`，通过实际 Access 入口验收。
|
||||
## Cloudflare 控制台配置
|
||||
|
||||
### 1. 创建 D1 数据库
|
||||
|
||||
1. 打开 Cloudflare Dashboard 的 D1 页面；新版界面通常位于 `Storage & databases > D1`，菜单名称可能随控制台更新而变化。
|
||||
2. 复用本项目已有数据库，或创建一个新的数据库；不要为每次部署重复创建。
|
||||
3. 将数据库名称和 ID 写入 `wrangler.toml` 的 `[[d1_databases]]`，binding 保持为 `DB`。
|
||||
4. 数据表不需要在控制台手动建立。GitHub Actions 会执行远程 migration，只添加项目所需 schema，不清空已有数据。
|
||||
|
||||
### 2. 配置 Zero Trust Access
|
||||
|
||||
1. 进入 `Zero Trust > Access > Applications`，添加一个 `Self-hosted` 应用。
|
||||
2. 应用域名填写最终访问 EdgeSSH 的自定义域名，并保证该域名与 `wrangler.toml` 的 route 一致。
|
||||
3. 添加 Allow 策略，只包含管理员的明确邮箱或身份。不要使用 `Everyone`、`Bypass` 或允许整个邮箱域的宽泛规则。
|
||||
4. 在 Zero Trust 的团队设置中找到 Team Domain，保存不带 `https://` 和路径的域名，例如 `my-team.cloudflareaccess.com`。
|
||||
5. 在 Access 应用详情中复制 Application Audience (AUD) Tag。不要把应用 ID、Client ID 或策略 ID 当作 AUD。
|
||||
|
||||
### 3. 创建部署用 API Token
|
||||
|
||||
1. 在 Cloudflare 个人资料的 `API Tokens` 页面创建 Token，选择官方 `Edit Cloudflare Workers` 模板作为起点。
|
||||
2. 在模板权限之外补充 Account 的 `D1: Edit`，供 workflow 执行远程 migration。
|
||||
3. 保留模板中的 Worker 与目标 Zone 权限，用于部署脚本及 `custom_domain = true` 的自定义域名；不需要添加 KV、R2 等本项目未使用资源的额外权限。
|
||||
4. Account Resources 和 Zone Resources 都只选择实际部署所用的账户与域名，不要使用全账户、全站点范围。
|
||||
5. Token 创建后只会完整显示一次，将它直接保存为 GitHub Actions Secret，不要写进仓库或 Cloudflare Worker 变量。
|
||||
|
||||
Cloudflare 账户 ID 可在 Dashboard 的账户概览或 Worker 概览中复制。它不是 Secret，可保存为 GitHub Actions Variable。
|
||||
|
||||
### 4. 配置 GitHub Actions
|
||||
|
||||
在 GitHub 仓库进入 `Settings > Secrets and variables > Actions`：
|
||||
|
||||
| 名称 | GitHub 类型 | 值 |
|
||||
| --- | --- | --- |
|
||||
| `CLOUDFLARE_ACCOUNT_ID` | Variable | Cloudflare 账户 ID |
|
||||
| `CLOUDFLARE_API_TOKEN` | Secret | 上一步创建的最小权限 API Token |
|
||||
|
||||
进入 `Actions > Deploy > Run workflow` 完成首次部署。workflow 会安装依赖、检查项目、迁移 D1 并创建或更新 Worker。首次运行时尚未配置运行时 Secret，受保护 API 暂时返回 503 属于预期现象。
|
||||
|
||||
### 5. 在 Worker 界面添加运行时 Secret
|
||||
|
||||
首次部署完成后，进入 `Workers & Pages > edgessh > Settings > Variables and Secrets`，依次添加以下三项，并将类型选择为 **Secret**：
|
||||
|
||||
| 名称 | 填写内容 |
|
||||
| --- | --- |
|
||||
| `ACCESS_TEAM_DOMAIN` | Zero Trust Team Domain，不带协议和路径 |
|
||||
| `ACCESS_AUD` | Access 应用详情中的 Application Audience (AUD) Tag |
|
||||
| `ENCRYPTION_KEY` | 32 字节安全随机数的标准 Base64，只在首次部署时生成 |
|
||||
|
||||
保存后按控制台提示部署新版本。不要在 GitHub Actions 中重复保存这三项，也不要为 `DB`、`SSH_SESSIONS` 或 `ASSETS` 创建同名变量。`CONNECT_TIMEOUT_MS` 已由 `wrangler.toml` 设置为 `10000`，只有确实需要调整 2,000 至 30,000 毫秒的建连超时时才在配置中修改。
|
||||
|
||||
`ENCRYPTION_KEY` 应由可信的密码管理器或本机安全随机数工具生成，解码后必须正好为 32 字节。不要使用普通密码、UUID、示例值或在线随机字符串网页。密钥丢失将无法解密现有资料；当前版本不支持直接轮换，后续部署必须复用原值。
|
||||
|
||||
## 部署顺序
|
||||
|
||||
1. 检查 Cloudflare 已有 Worker、D1 与 Access 应用，确认资源属于本项目，避免覆盖其他项目。
|
||||
2. 配置 D1、Access 与最小权限 API Token，再将两个部署值保存到 GitHub Actions。
|
||||
3. 手动运行一次 `Deploy` workflow，让 GitHub Actions 自动迁移 D1 并创建或更新 Worker。
|
||||
4. 在 Worker 的 `Variables and Secrets` 界面添加三个运行时 Secret，保存并部署。
|
||||
5. 以后只需推送到 `main`；workflow 会复用原有资源和 Secret 自动发布，不需要在本地执行 Wrangler 部署命令。
|
||||
6. 通过实际 Access 入口验收。所有账号、主机与连接 API 均需 Access 保护；缺少 Access Secret 时会返回 503，不能操作主机或连接 SSH。
|
||||
|
||||
密钥丢失将无法解密现有资料。更换密钥必须设计旧密钥解密、新密钥重加密的迁移，不可直接覆盖 Secret。当前版本不提供自动轮换。更换 Access 团队或身份导致 `sub` 改变时，也需要显式的数据迁移。
|
||||
|
||||
@@ -44,7 +99,7 @@
|
||||
| `CLOUDFLARE_ACCOUNT_ID` | Actions Variable | 目标 Cloudflare 账户 ID |
|
||||
| `CLOUDFLARE_API_TOKEN` | Actions Secret | 限定到目标账户，并具备 Workers 部署与 D1 迁移权限 |
|
||||
|
||||
三个运行时 Worker Secret 不进入 GitHub Actions。首次部署或主动轮换时仍使用 `wrangler secret put` 单独管理；日常自动部署只复用 Cloudflare 中已有值。
|
||||
三个运行时 Worker Secret 不进入 GitHub Actions，统一在 Cloudflare Worker 的 `Variables and Secrets` 界面管理；日常自动部署只复用 Cloudflare 中已有值。不要把本地 `.dev.vars` 或 `wrangler secret put` 作为普通用户的生产配置流程。
|
||||
|
||||
## 验收清单（5.6 SOL 执行）
|
||||
|
||||
@@ -83,4 +138,4 @@
|
||||
|
||||
- 正式入口：`https://ssh.dltwcnm.ccwu.cc`
|
||||
- `workers.dev` 作为诊断入口保留；Worker 仍在应用层强制校验所有生产账号与连接 API，不允许绕过自定义域名上的 Access 策略。
|
||||
- Access 应用与策略由用户在 Cloudflare 控制台维护；部署流程只注入 Team Domain 与应用 AUD。
|
||||
- Access 应用、策略与三个运行时 Secret 均由用户在 Cloudflare 控制台维护；GitHub Actions 只负责迁移与部署代码。
|
||||
@@ -109,7 +109,7 @@ SSH 握手、密钥交换、认证与通道逻辑在 Worker 内完成。浏览
|
||||
EdgeSSH 没有独立的本地登录系统，正式入口必须先经过 Cloudflare Zero Trust Access。首次部署时请先完成：
|
||||
|
||||
1. 在 **Zero Trust > Access controls（访问控制）> Applications（应用程序）** 创建 **Self-hosted and private（自托管和私有）** 应用，并绑定 EdgeSSH 的自定义域名。
|
||||
2. 添加一条 **Allow（允许）** 策略，使用 **Include> Emails** 明确填写管理员邮箱；不要使用 `Everyone（所有人）` 或 `Bypass（绕过）`。
|
||||
2. 添加一条 **Allow（允许）** 策略，使用 **Include > Emails** 明确填写管理员邮箱；不要使用 `Everyone（所有人）` 或 `Bypass（绕过）`。
|
||||
3. 选择 **Identity Provider（标识提供程序）**。个人部署可使用 **One-time PIN（一次性 PIN）**；新建 Zero Trust 组织若没有该选项，需要先到 **Integrations（集成）> Identity providers（标识提供程序）** 手动添加。
|
||||
4. 从 Access 应用中取得 **Application Audience (AUD) Tag（应用程序受众 (AUD) 标签）**，并从 Zero Trust **Settings（设置）** 取得 **Team Domain（团队域）**。
|
||||
5. 将它们分别写入 `ACCESS_AUD` 与 `ACCESS_TEAM_DOMAIN` Worker Secret。
|
||||
@@ -129,32 +129,24 @@ npm ci
|
||||
> [!IMPORTANT]
|
||||
> 本项目面向**单管理员**使用。Access 策略应仅允许管理员的明确身份，不要配置 Everyone 或 Bypass。缺少 Access 配置时，受保护 API 会拒绝访问，不会降级为匿名网关。
|
||||
|
||||
1. 调整 `wrangler.toml` 中的 Worker 名称、自定义域名与 D1 绑定，**不要直接使用仓库中原部署环境的资源 ID**。
|
||||
2. 复用已有 D1 或创建自己的数据库，将其绑定为 `DB`，保留 Durable Object 类与迁移配置。
|
||||
3. 创建并配置 Access 应用，通过 Wrangler 注入下列 Secret。
|
||||
4. 应用数据库迁移，完成检查后部署。
|
||||
1. 在 Cloudflare 控制台复用或创建 D1 数据库，并调整 `wrangler.toml` 中的 Worker 名称、自定义域名与 D1 `database_id`，**不要直接使用仓库中原部署环境的资源 ID**。
|
||||
2. 在 Zero Trust 控制台创建 Self-hosted Access 应用，只允许管理员的明确邮箱或身份，并记下 Team Domain 与 Application Audience (AUD) Tag。
|
||||
3. 在 GitHub 配置一个 Actions Variable 和一个 Actions Secret，首次运行 `Deploy` workflow；它会自动检查项目、迁移 D1 并创建或更新 Worker。
|
||||
4. Worker 首次出现后，在 Cloudflare 控制台的 `Workers & Pages > 你的 Worker（默认 edgessh）> Settings > Variables and Secrets` 中添加三个运行时 Secret。保存并部署这些设置后即可通过 Access 入口验收。
|
||||
|
||||
| 配置 | 用途 |
|
||||
| --- | --- |
|
||||
| `DB` | 保存加密主机资料的 D1 绑定 |
|
||||
| `SSH_SESSIONS` | 隔离 SSH 会话的 Durable Object 绑定 |
|
||||
| `ASSETS` | 提供前端静态资源 |
|
||||
| `ACCESS_TEAM_DOMAIN` | Access 团队域名，通过 Secret 注入 |
|
||||
| `ACCESS_AUD` | Access 应用 Audience，通过 Secret 注入 |
|
||||
| `ENCRYPTION_KEY` | 32 字节安全随机密钥的标准 Base64，通过 Secret 注入 |
|
||||
| `CONNECT_TIMEOUT_MS` | TCP 建连超时，默认 `10000` 毫秒 |
|
||||
| 配置 | 类型与位置 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `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`，通常无需填写 |
|
||||
|
||||
```bash
|
||||
npx wrangler login
|
||||
npx wrangler secret put ACCESS_TEAM_DOMAIN
|
||||
npx wrangler secret put ACCESS_AUD
|
||||
npx wrangler secret put ENCRYPTION_KEY
|
||||
npx wrangler d1 migrations apply DB --remote
|
||||
npm run check
|
||||
npm run deploy
|
||||
```
|
||||
生产运行时只需在 Cloudflare 控制台填写 `ACCESS_TEAM_DOMAIN`、`ACCESS_AUD` 与 `ENCRYPTION_KEY` 三个 Worker Secret。`DB`、`SSH_SESSIONS` 与 `ASSETS` 是部署时创建的绑定，不是环境变量；`CONNECT_TIMEOUT_MS` 已有默认配置，也无需重复添加。
|
||||
|
||||
**首次部署才生成加密密钥，后续部署复用已有 Secret。** 丢失或直接替换密钥会导致已有资料无法解密。密钥不要写入源码、配置文件或提交记录。
|
||||
**首次部署才生成 `ENCRYPTION_KEY`，后续部署始终复用原值。** 丢失或直接替换密钥会导致已有资料无法解密。密钥只粘贴到 Cloudflare 的 Secret 输入框，不要写入源码、`wrangler.toml`、GitHub Actions 或提交记录。
|
||||
|
||||
完整配置顺序、安全边界与验收清单见 [部署指南](DEPLOYMENT.md)。
|
||||
|
||||
@@ -167,7 +159,7 @@ npm run deploy
|
||||
| `CLOUDFLARE_ACCOUNT_ID` | Variable | Cloudflare 账户 ID |
|
||||
| `CLOUDFLARE_API_TOKEN` | Secret | 具备 Workers 部署和 D1 迁移权限的 API Token |
|
||||
|
||||
Action 只需要这两项部署凭据。`ACCESS_TEAM_DOMAIN`、`ACCESS_AUD` 与 `ENCRYPTION_KEY` 继续作为 Worker Secret 保存在 Cloudflare，普通部署不会读取或覆盖它们。API Token 属于敏感信息，必须使用 GitHub Secret，不能保存为普通 Variable。
|
||||
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。
|
||||
|
||||
## 本地开发
|
||||
|
||||
|
||||
+12
-16
@@ -113,24 +113,20 @@ my-team.cloudflareaccess.com
|
||||
Cloudflare 官方获取 AUD 的说明：
|
||||
https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/
|
||||
|
||||
## 写入 Worker Secret
|
||||
## 在 Cloudflare 控制台保存 Worker Secret
|
||||
|
||||
在 EdgeSSH 项目目录运行：
|
||||
先按 [部署指南](../DEPLOYMENT.md) 配置 GitHub Actions，并手动运行一次 `Deploy` workflow。首次部署完成、Worker 出现在 Cloudflare 后：
|
||||
|
||||
```bash
|
||||
npx wrangler secret put ACCESS_TEAM_DOMAIN
|
||||
npx wrangler secret put ACCESS_AUD
|
||||
```
|
||||
1. 打开 Cloudflare Dashboard，进入 `Workers & Pages`。
|
||||
2. 选择你的 EdgeSSH Worker（默认名称为 `edgessh`）。
|
||||
3. 进入 `Settings（设置）> Variables and Secrets（变量与机密）`。
|
||||
4. 添加 `ACCESS_TEAM_DOMAIN`，类型选择 **Secret**，粘贴前面取得的 Team Domain。
|
||||
5. 添加 `ACCESS_AUD`，类型选择 **Secret**，粘贴前面取得的 Application Audience (AUD) Tag。
|
||||
6. 按控制台提示保存并部署新版本。
|
||||
|
||||
分别粘贴刚才取得的值。
|
||||
不要把这两个值保存为 GitHub Actions Secret。GitHub Actions 只需要 `CLOUDFLARE_ACCOUNT_ID` 和 `CLOUDFLARE_API_TOKEN` 两项部署凭据；Access 参数属于 Worker 运行时 Secret，应始终留在 Cloudflare 中。
|
||||
|
||||
然后继续完成项目部署：
|
||||
|
||||
```bash
|
||||
npx wrangler d1 migrations apply DB --remote
|
||||
npm run check
|
||||
npm run deploy
|
||||
```
|
||||
EdgeSSH 还需要一个 `ENCRYPTION_KEY` Worker Secret。它与上述两项在同一个控制台页面配置，生成要求和密钥保管注意事项见 [部署指南](../DEPLOYMENT.md#5-在-worker-界面添加运行时-secret)。生产部署不需要在本地执行 Wrangler Secret 或 Worker 部署命令。
|
||||
|
||||
## 验证配置
|
||||
|
||||
@@ -148,9 +144,9 @@ npm run deploy
|
||||
|
||||
检查：
|
||||
|
||||
- `ACCESS_TEAM_DOMAIN` 是否已经通过 Wrangler Secret 写入。
|
||||
- `ACCESS_TEAM_DOMAIN` 是否已经在 Worker 的 `Variables and Secrets` 页面保存为 Secret，并部署到当前版本。
|
||||
- Team Domain 是否为 `xxx.cloudflareaccess.com`，且没有 `https://`。
|
||||
- `ACCESS_AUD` 是否已经写入。
|
||||
- `ACCESS_AUD` 是否已在同一页面保存为 Secret，且值来自当前 Access 应用。
|
||||
|
||||
### 登录后提示“Access 登录已失效”
|
||||
|
||||
|
||||
Reference in new issue
Block a user