setting-up-devbox

设置 PostHog 开发机

开发机是用于 PostHog 开发的 EC2 上的 Coder 工作区。 通过 hogli devbox:* 操作它，不要重新实现这些命令的功能。 新建的开发机包含位于 ~/posthog、处于 master 分支的仓库、预热好的依赖项和已安装的 Claude Code。 hogli devbox:<command> --help 提供当前可用的标志。 本指南介绍操作顺序，以及帮助文本未说明的内容。

开发机的用途各不相同：用于常规开发的 shell 或编辑器、供本地检出版本使用的远程目标，或运行中的 PostHog 应用的主机。 先确认用户想要哪一种；除非用户要求运行应用，否则不要启动 PostHog 堆栈。

获取开发机

复制此清单并跟踪进度：

- [ ] 1. hogli devbox:doctor: the tailnet and control plane checks are ok
- [ ] 2. hogli devbox:setup has run on this machine
- [ ] 3. hogli devbox:start: the box is running
- [ ] 4. The user is connected the way they asked for
- [ ] 5. hogli devbox:stop when the user is done

1. 检查访问权限

hogli devbox:doctor 是只读命令：它不会提示输入，也不会更改主机配置。 连接开发机的命令都会先执行相同的可达性检查，因此如果此处检查失败，请先解决问题。

• 当前活动的 tailnet 必须是 posthog.com。Doctor 会显示当前 tailnet，并指出 tailnet 不正确是原因。
• 每位 PostHog 员工都可以通过 tailnet 策略中的 group:employees 路由到 Coder 控制平面。无需提交 PR 申请访问权限。
• 如果 doctor 报告控制平面无法连接，请先阅读 references/access-troubleshooting.md，再进行任何更改。
• [missing] Commit signing agent 不会阻止启动或使用开发机。它仅影响在开发机上创建的签名提交。

2. 一次性设置此计算机

hogli devbox:setup 是交互式命令，因此请让用户在自己的终端中运行。 它会将与服务器版本一致的 Coder CLI 安装到 ~/.hogli/bin、登录、安装供 devbox:sync 使用的固定版本 mutagen 二进制文件，并写入 devbox:ssh 和 devbox:exec 使用的 coder.* SSH 主机条目。 ~/.hogli/bin 不在 PATH 中，因此如果某个步骤需要直接使用 coder，请将其作为 ~/.hogli/bin/coder 调用。 每个可选步骤都有对应的 --configure-<step> 和 --skip-configure-<step> 标志：ssh、git-identity、git-signing、region、dotfiles、claude。 如果命令显示 Coder CLI vX does not match server vY，请重新运行该命令，因为它会重新安装匹配版本的 CLI。

在 Linux 上，可达性检查可能会运行 sudo tailscale set --accept-routes 并提示输入密码。 在让 Agent 无人值守地运行开发机命令之前，请先手动交互式运行一次设置。

3. 启动开发机

hogli devbox:start

首次使用时，此命令会创建开发机；开发机停止后，它会将其恢复运行。 命令会等待开发机启动脚本执行完毕后才返回，因此此时开发机已可连接。devbox:restart、devbox:update 和 devbox:clone 也会以相同方式等待。如果脚本失败或等待超时，开发机仍会继续运行，hogli 会打印警告并提示运行 hogli devbox:logs。 只有工作区设置了 --start-app 时，它才会启动 PostHog 堆栈；详情请参阅运行 PostHog 应用。 --disk（100 或 200 GiB）仅在创建开发机时生效。 --region（us-east-1 或 eu-central-1）会启动该区域的默认开发机，并在其不存在时创建它，因此恢复现有开发机时不要使用此标志。 开发机所在的区域无法更改。

默认开发机名称为 devbox-<coder-user>，带标签的开发机名称为 devbox-<coder-user>-<label>。 位于 eu-central-1 的开发机名称会添加 -eu 后缀，例如 devbox-<coder-user>-eu。 hogli devbox:list 会显示准确名称。 在操作指定标签的开发机时，请在命令中使用 -n <label>。

4. 连接

根据用户的需求选择：

• Shell： hogli devbox:ssh。
• 编辑器： hogli devbox:open --vscode、--cursor 或 --web。
• 通过 Agent 执行命令： 使用 hogli devbox:exec，详见在开发机上运行命令。
• 在本地编辑，在开发机上运行： 使用 hogli devbox:sync 前，请先阅读 references/sync.md。
• 运行中的应用： 按照运行 PostHog 应用中的说明操作。

5. 完成后停止

hogli devbox:stop 会保留磁盘并停止计费。 停止、启动和 devbox:update 都会保留 /home。 hogli devbox:destroy 会将其删除，因此不要只在开发箱中保存任何无法替代的内容。

在开发箱上运行命令

hogli devbox:exec -- <command> 会通过 SSH 运行一条命令并返回其退出码。 请用 bash -lc '...' 包装命令。 非登录 shell 不一定会加载 shell 配置文件，因此 ~/.local/bin 等登录 shell PATH 中的工具会报错“command not found”。 请在 hogli 的标志和命令自身之间加上 --。 在 devbox:setup 写入 SSH 配置之前，devbox:exec 和 devbox:ssh 都无法连接。

运行 PostHog 应用

仅当用户需要应用时才使用本节，例如为某项变更做 QA 或分享链接。

启动服务栈

• 新开发箱： hogli devbox:start --start-app。该设置会保留在工作区中，因此之后每次启动都会在后台启动服务栈。此标志仅在 hogli 创建开发箱时生效；对于现有开发箱，hogli 会拒绝该标志，因为 Coder CLI 会保留参数上次构建时的值。要在现有开发箱中更改此设置，请前往 Coder 控制面板中的工作区参数。
• 正在运行的开发箱： hogli devbox:exec -- bash -lc 'cd ~/posthog && ./bin/hogli up -d -y'。

等待服务启动

启动命令返回后，服务栈仍会继续启动。 请在限定次数的循环中轮询，直到输出 200 或 302。 000 或 502 表示服务栈仍在启动。

hogli devbox:exec -- bash -lc "curl -s -o /dev/null -w '%{http_code}' --max-time 10 http://127.0.0.1:8010/"

在现有开发箱上恢复 QA 时，请先检查应用，再重新创建同步、重启服务栈或新建开发箱：

hogli devbox:status
hogli devbox:exec -- bash -lc 'cd ~/posthog && git status --short --branch && git rev-parse --short HEAD'
hogli devbox:sync --json

当应用提供预期的分支和 SHA、目标路由能够加载且其 API 正常工作时，即可继续。 请记录无关进程的降级情况，不要为追求全面健康而继续排查。

向用户提供 URL

该模板会将应用作为 Coder 子域名应用公开，只有开发箱所有者可以打开：

https://app--<workspace>--<coder-user>.<coder-host>

<coder-host> 是 hogli devbox:doctor 中 Coder URL 的主机名，hogli devbox:list 会显示工作区名称。 例如，coder.dev.posthog.dev 上由 jane-d 所有的 devbox-jane-d，其 URL 为 https://app--devbox-jane-d--jane-d.coder.dev.posthog.dev。 用户必须位于 tailnet 上，并且浏览器会先通过 Coder 登录。

交付链接前请先验证。 Coder 会对应用运行模板的健康检查，因此请读取该状态，而不要使用用户的会话令牌发送请求：

~/.hogli/bin/coder list --output json | jq -r '.[] | select(.name=="<workspace>") | .latest_build.resources[]?.agents[]?.apps[]? | select(.slug=="app") | .health'

healthy 表示 Coder 会将 URL 路由到正常运行的应用。 initializing 表示检查尚未通过，unhealthy 表示检查持续失败。

如果用户需要 localhost，可以改用 hogli devbox:forward。 它会将开发箱的端口 8010 隧道转发到 localhost:8010，并一直占用终端，直到停止。 如果本地服务栈已占用 8010，请传入 --port 8011。

其他任务

• 在开发箱中使用令牌： 将令牌存储为 Coder 用户密钥，这些密钥会传递到用户拥有的每个开发箱。hogli devbox:secret:set GH_TOKEN 会从隐藏提示或 --file 读取值。切勿将令牌放在命令行或对话中。密钥只会传递到设置密钥后启动的开发箱，因此请对正在运行的开发箱执行 hogli devbox:restart。模板记录了 CLAUDE_CODE_OAUTH_TOKEN、GH_TOKEN、ANTHROPIC_API_KEY、OPENAI_API_KEY 和 POSTHOG_GIT_SIGNING_KEY，其中 POSTHOG_GIT_SIGNING_KEY 由 hogli devbox:setup --configure-git-signing 设置。devbox:secret:list 会显示名称、环境变量和说明，不会显示密钥值。
• 创建状态相同的第二个开发箱： hogli devbox:clone --as <label> 会将正在运行的开发箱的整个磁盘（包括其中的任何密钥）复制到源开发箱所在区域的 devbox-<coder-user>-<label>。为确保副本一致，请先停止源开发箱上的工作栈。此操作会要求确认，因此只有在用户同意后才传入 -y。只有所有者才能克隆开发箱。
• 模板更新： 如果开发箱使用的模板不是最新版本，hogli devbox:update 会应用最新模板。启动过时的开发箱时，devbox:start 也会更新它。通过 devbox:start 和 devbox:clone 创建的开发箱已启用 Coder 的自动更新，因此从 Web UI 或自动启动时，以及执行 hogli devbox:restart 时，也会更新到最新模板。开发箱持续运行期间，Coder 不会更新它；但重启过时的开发箱会执行完整的模板更新，并可能触发一次性依赖重新安装，devbox:update 会对此发出警告。
• 磁盘已满： hogli devbox:cleanup:disk -n <label> 会清理带标签的开发箱。如果没有工作区，则改为清理这台机器；默认开发箱没有标签，因此请使用 hogli devbox:exec -- bash -lc 'cd ~/posthog && ./bin/hogli devbox:cleanup:disk' 清理默认开发箱。--docker 还会清理已停止的容器；--cargo 还会删除 Rust 构建输出，这会导致完整重建。
• 共享访问： hogli devbox:share --user <coder-user> --role use 会授予访问权限，devbox:users 会列出用户名。devbox:unshare 只有在执行 hogli devbox:restart 后才会移除访问权限。
• 构建和 Agent 日志： hogli devbox:logs -f。
• 个性化设置： 开箱即用即可正常使用。对开发箱所做的更改会在停止和更新后保留。hogli devbox:setup --configure-dotfiles 会保存一个 dotfiles 仓库，开发箱启动时会应用该仓库并运行其中可执行的 install.sh。保存的仓库 URL 会应用到 hogli 创建的开发箱。要在现有开发箱上更改该设置，请在 Coder 控制面板中编辑工作区的参数。

注意事项

• 切勿将密钥值输出到对话记录、日志、PR 或命令行中。
• code-server（devbox:open --web）不支持 SSH Agent 转发，因此无法在其中签署提交。请使用 VS Code Desktop、Cursor 或通过 SSH 连接的 JetBrains 来签署提交。