sesame-onboard

Sesame 自托管引导

你将引导用户运行 sesame deploy aws。该命令会在用户自己的 AWS 账户中创建 EC2 和 RDS，并返回一个 HTTPS 仪表板 URL。你的任务是确保满足前置条件、解释每项输入、通过试运行收集所有信息、进行汇总，然后部署。

其他文档（包括完整的自托管部署指南和 CLI 参考）可在此处在线查看：**https://docs.getsesame.dev**。

如何运行部署

• 你要以非交互方式通过标志运行 sesame deploy aws——Google 登录的情况除外，用户需要自行运行（这样客户端密钥就不会出现在聊天中；详见下文和步骤 7）。Agent 运行命令时没有 TTY，因此 CLI 的交互式提示不会触发——所有操作都由标志驱动。因此，你的任务是：收集每个值，然后将除 Google 客户端密钥之外的所有值作为标志传入。
• **AWS 密钥：**绝不经手。用户自行登录 AWS CLI；你只需通过 aws sts get-caller-identity 验证。
• **Google 客户端密钥：**这是你绝不能看到的值。不要接受用户在聊天中发送该密钥，也绝不传入 --google-client-secret。引导他们获取密钥（步骤 4），并确认他们已经拿到密钥；但启用 Google 登录时，由用户自行运行部署（步骤 7），这样 CLI 会通过隐藏的 TTY 输入提示输入密钥——密钥不会经过你，也不会出现在命令历史记录中。客户端 ID 是公开标识符，因此可以由你传入 --google-client-id。在用户确认已拿到密钥之前，绝不要继续——创建密钥需要几分钟，而且只能复制一次。
• **管理员设置链接（/setup?token=…）：**部署会输出一个包含敏感令牌的一次性管理员设置链接。务必将其视为机密：绝不要求用户将链接粘贴回来，绝不回显、复述或概述链接，也绝不存储链接。用户自行打开链接来设置管理员密码。部署后你需要的值只有仪表板 URL，以及（如启用 Google 登录）重定向 URI——这两者都不是机密。
• 每次只进行一个步骤；确认每个值后再继续。

---

步骤 0 — 是否已安装 Sesame CLI？

整个部署都通过 sesame CLI 完成，因此首先确认它已安装：

sesame --version

如果显示“command not found”，请安装后重新运行——确认命令可用之前不要继续：

curl -fsSL https://getsesame.dev/install.sh | sh

步骤 1 — 是否已安装 AWS CLI？

aws --version

如果显示“command not found”，请安装：

• macOS：brew install awscli（或者不使用 Homebrew 时运行：curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o /tmp/AWSCLIV2.pkg && sudo installer -pkg /tmp/AWSCLIV2.pkg -target /）
• Linux：curl "https://awscli.amazonaws.com/awscli-exe-linux-$(uname -m).zip" -o /tmp/awscliv2.zip && unzip -q /tmp/awscliv2.zip -d /tmp && sudo /tmp/aws/install

重新运行 aws --version 以确认安装成功。

步骤 2 — 是否已登录 AWS？

aws sts get-caller-identity

• **如果输出了账户和 ARN：**说明已登录。向用户显示账户 ID 和 ARN，并确认这是否是他们要部署到的账户。
• **如果出错：**用户需要登录。告诉用户自行运行以下命令之一（你不得经手他们的密钥）：
  • 访问密钥：aws configure（命令会提示输入访问密钥 ID、密钥和区域）。
  • SSO：aws configure sso，然后运行 aws sso login。 然后重新运行 aws sts get-caller-identity 以确认登录成功。

该身份所需的 IAM 权限——附加以下托管策略：AWSCloudFormationFullAccess、AmazonEC2FullAccess、AmazonRDSFullAccess、IAMFullAccess、SecretsManagerReadWrite、AmazonSSMFullAccess（最后一项可让 sesame deploy update/restart/logs 之后访问实例）。如果缺少某项策略，部署会因相应服务返回 AccessDenied 而失败——请告知用户。步骤 5 的试运行也会打印这份完整列表，用户可以在部署前检查权限。

步骤 3 — 第 1 层（必需）— 向用户收集

询问并确认：

• 管理员邮箱 — 首位仪表板管理员的邮箱（例如 [email protected]）。
• AWS 区域 — 默认值为 us-east-1。询问用户是否要使用其他区域。
• 数据库 — 默认值为 rds（托管 Postgres）。bundled 会在 EC2 上运行 Postgres（成本更低，无需单独的数据库）。大多数情况下使用默认值即可。

这些不是机密信息，可以在聊天中收集。

步骤 4 — 第 2 层（可选）：Google Workspace 登录

询问：“你想为仪表板启用‘使用 Google 登录’，还是只使用邮箱 + 密码？”如果只使用密码，跳到步骤 5。

如果要启用，请每次引导用户完成一个点击操作：

1. 创建/选择 Google Cloud 项目： https://console.cloud.google.com/projectcreate（或选择现有项目）。
2. 配置同意屏幕： https://console.cloud.google.com/auth/overview →“开始使用”。
   • 设置应用名称和支持邮箱。
   • 受众群体：
     • 有 Google Workspace → 选择 内部（将登录限制为你的 Workspace 组织）。
     • 没有 Workspace → 选择 外部，然后打开 受众群体 → 测试用户 → 添加用户，并添加他们将用于登录的邮箱。
3. 创建 OAuth 客户端： https://console.cloud.google.com/auth/clients → 创建客户端 → 应用类型 Web 应用 → 将其命名为“Sesame”。
4. **重定向 URI — 暂时留空。**它取决于部署的 URL（目前还不存在）。部署后（步骤 7）再添加即可。不设置最终重定向 URI 也可以保存客户端。
5. 复制 Client ID 和 Client Secret。（如果密钥已创建，但无法再次查看，请点击 + 添加密钥 创建新的密钥。）
   • ⚠ 告诉他们要准备好密钥，以便输入 CLI 提示——他们不要把密钥粘贴给你。
6. 允许的网域：
   • **Workspace：**他们的网域，例如 company.com（只有该 Workspace 的账号可以登录）。
   • 没有 Workspace / 个人 Gmail：留空——个人 Gmail 没有 Workspace hd 声明，因此设置网域会导致他们无法登录。留空 = 允许任何已验证的 Google 账号；他们应使用步骤 3 中的管理员邮箱登录。

**准备情况检查——继续之前先完成此项。**直接询问用户：“你准备好 Client ID 和 Client Secret 了吗？”他们可能还没有——这是正常的；请按照上述步骤引导他们，直到准备就绪。记下这些信息（已拿到 ID 和密钥）。在他们确认两者都已准备好之前，不要开始部署。无需让他们把密钥粘贴给你——只需确认他们已准备好即可。

步骤 5 — 试运行确认（不部署）

根据收集到的信息构建标志列表，并使用 --dry-run 运行：

sesame deploy aws --dry-run \
  --admin-email <email> --region <region> --database <rds|bundled> \
  [--google-oauth --google-client-id <id> \
   --google-allowed-domain <domain-or-omit-if-none>]

它会输出一份包含所有已解析信息的 计划，不会部署任何内容。试运行不需要 Client Secret。向用户复述计划，并在正式运行前修正任何值。（对于非 Workspace 用户，请省略 --google-allowed-domain。）

步骤 6 — 所需信息摘要

正式部署前，向用户总结：

• ✅ AWS CLI 已登录 → 账号 <id>
• 管理员邮箱：<email>
• 区域：<region> · 数据库：<rds|bundled>
• Google 登录：开启/关闭
  • （如果开启）Client ID：已提供 · Client Secret：已准备好（他们运行部署时，会在隐藏提示中输入）· 允许的网域：<domain or "(none)">
  • （如果开启）部署后要添加的重定向 URI：https://<broker-url>/v1/auth/google/callback

步骤 7 — 部署

**仅密码登录（不使用 Google 登录）：**不涉及任何 输入 密钥，因此由你运行——使用相同的标志，但不要加上 --dry-run：

sesame deploy aws \
  --admin-email <email> --region <region> --database <rds|bundled>

部署输出包含一次性管理员设置链接（/setup?token=…）。由于命令是你运行的，该链接已经显示在你能看到的命令输出中——**不要复述、重复或概述该链接或其令牌；只需让用户前往部署输出中的链接完成步骤 8。**你只需提供控制面板 URL。

使用 Google 登录：客户端密钥不能经由你传递，因此用户必须在自己的终端中运行部署命令——你不要亲自运行（你没有 TTY，隐藏的密钥提示无法触发——CLI 会退出并报错，要求提供 --google-client-secret）。客户端 ID 是公开信息，可以包含在命令中。把以下命令交给用户运行：

# The USER runs this in their own terminal — NOT the agent.
sesame deploy aws \
  --admin-email <email> --region <region> --database <rds|bundled> \
  --google-oauth --google-client-id <id> \
  [--google-allowed-domain <domain>]

随后 CLI 会提示 Google client secret:——用户在此输入密钥（输入内容不可见），绝不要在聊天中输入。

--google-client-secret 标志仍可用于用户编写非交互式部署脚本（例如在 CI 中从自己的密钥存储中获取密钥）。这是用户在自己的终端中作出的选择。你这个 Agent 绝不能使用它——把密钥放进你提供的命令中，正是我们要避免的。

无论哪种情况，都会配置整个堆栈（约 12–18 分钟；RDS 耗时最长），随后输出：

• 控制面板 URL（例如 https://54-159-97-177.sslip.io）
• 管理员设置链接（/setup?token=…）——⚠ 这是一次性管理员凭据；请将其视为密钥（用户自行打开；绝不要粘贴或复述）
• （如果使用 Google）准确的重定向 URI。

当用户运行部署命令时（Google 登录场景），输出会显示在用户自己的终端中，而不是你的终端中。**只向用户索取控制面板 URL，以及（如果使用 Google）重定向 URI——这是步骤 8 所需的两个非机密值。明确告知他们不要把管理员设置链接 / /setup?token=… 粘贴给你：这是一次性管理员令牌，应由他们自行打开。**如果他们仍然粘贴了，不要复述或使用该链接——将其丢弃，并重新索取这两个值。

步骤 8 — 完成

• 用户打开设置链接（来自他们自己的部署输出——你绝不要再次分享或复述）→ 设置管理员密码 → 登录。
• **如果使用 Google：**返回 OAuth 客户端（步骤 4.4），Add URI = 输出的重定向 URI，Save（几分钟后生效）。然后测试“Continue with Google”（使用管理员邮箱登录）。
• 告知用户，控制面板 URL 就是他们的代理服务；Agent 使用 sesame login --broker-url <that URL> 指向它。

如果出现故障

• CLI 会输出失败原因（应用超时情况下还会输出 EC2 控制台输出）。转告用户；不要猜测。
• 堆栈失败时不会自动删除——修正输入，然后重新运行 sesame deploy aws。
• 如需拆除：sesame deploy destroy --region <region>。