setup-dev

配置 Sentry 开发环境

引导用户在本地运行 Sentry。从一台空白机器开始的完整流程需要 30-45 分钟 —— 其中大部分时间用于下载依赖和 Docker 镜像。在每一步都要明确设定预期。

AL MCP：如果 al MCP 服务可用，请使用 al_search_docs 和 al_read_doc 进行详细故障排查。AL 文档深入介绍了 devenv、devservices 和常见问题。AL 服务是 devinfra-mcp 项目的一部分 —— 如果该服务尚未配置，请参阅该仓库获取安装说明。SSE 端点配置在 .pi/mcp.json（pi）或 .mcp.json / .cursor/mcp.json（Claude Code / Cursor）中。

第 1 步：检测当前状态

在执行任何操作之前，先评估已安装的内容。运行以下所有命令：

# Check OS
uname -s && uname -m

# Check shell
echo $SHELL

# Check if devenv exists
which devenv 2>/dev/null || ls ~/.local/share/sentry-devenv/bin/devenv 2>/dev/null

# Check devenv version (outdated versions cause failures)
devenv --version 2>/dev/null || ~/.local/share/sentry-devenv/bin/devenv --version 2>/dev/null

# Check Docker runtime
docker context ls 2>/dev/null
docker info --format '{{.Name}}' 2>/dev/null

# Check OrbStack
which orbctl 2>/dev/null && orbctl status 2>/dev/null

# Check Colima
which colima 2>/dev/null && colima status 2>/dev/null

# Check direnv
which direnv 2>/dev/null

# Check if repo is already set up
ls .venv/bin/sentry 2>/dev/null && ls node_modules/.bin 2>/dev/null

根据结果，跳转到相应的步骤。如果一切均已安装，直接跳到第 6 步。

第 2 步：安装前置依赖（macOS）

Xcode 命令行工具

xcode-select -p 2>/dev/null || xcode-select --install

如果未安装，用户必须完成交互式安装对话框（约 10 分钟）。请等待其完成。

Homebrew

which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Docker 运行时 —— OrbStack 或 Colima

询问用户更偏好哪一个。解释两者的取舍：

运行时	优点	缺点
Colima	Sentry 官方推荐，所有脚本都支持它	在 WiFi 切换时可能出现 DNS 问题
OrbStack	更快、资源占用更低、UI 更好	部分 Sentry 脚本假定使用 Colima —— 可能需要变通方案

如果选择 OrbStack：

brew install --cask orbstack

然后从 Applications 启动 OrbStack。验证：docker info

如果选择 Colima： Colima 会由 devenv bootstrap 安装 —— 无需单独操作。

重要：不要将 Docker Desktop 与任一运行时同时运行 —— 这会导致冲突。

第 3 步：安装 devenv

# For external (non-Sentry-employee) contributors:
# export SENTRY_EXTERNAL_CONTRIBUTOR=1

curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash

这会安装到 ~/.local/share/sentry-devenv/bin/devenv。

Shell 配置

用户的 shell 必须将 devenv 加入 PATH 并挂接 direnv。检查并修复：

# Check if already configured
grep -q "sentry-devenv" ~/.zshrc 2>/dev/null || grep -q "sentry-devenv" ~/.bashrc 2>/dev/null

如果尚未配置，请添加到相应的 shell 配置文件（zsh 为 ~/.zshrc，bash 为 ~/.bashrc）：

# devenv
export PATH="$HOME/.local/share/sentry-devenv/bin:$PATH"

# direnv
eval "$(direnv hook zsh)"   # or: eval "$(direnv hook bash)"

告诉用户在修改后重启终端（或执行 source ~/.zshrc）。

验证 devenv 版本

最低版本要求经常变化。如果已安装 devenv，请检查其是否过旧：

devenv --version

如果版本过旧（例如 < 1.22），请升级：

devenv update

如果因版本过旧导致 devenv update 本身失败，请重新安装：

curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash

第 4 步：Bootstrap（仅首次）

对于全新的配置，请先运行 bootstrap：

devenv bootstrap

这是交互式的（约 5 分钟）—— 它会提示输入 SSH 密钥、coderoot 目录等信息。它会安装 Homebrew、Colima、Docker CLI 和 direnv。

bootstrap 完成后，请关闭并重新打开终端。

第 5 步：同步环境

这是耗时最长的步骤。告诉用户：

首次运行将需要 10-20 分钟。它会安装 Python、Node、所有 pip/npm 依赖，并运行数据库迁移。后续同步会快得多（2-5 分钟）。

如果 direnv 卡住

.envrc 会运行 Docker 检查。如果 Docker 运行时未启动，direnv 将会卡住。症状：

direnv: ([...]/direnv export zsh) is taking a while to execute. Use CTRL-C to give up.

修复：先启动 Docker 运行时：

• OrbStack：打开 OrbStack.app 或执行 open -a OrbStack
• Colima：devenv colima start

然后再次执行 direnv allow。

先有鸡还是先有蛋的问题

direnv 会检查 node 版本和 sentry 安装情况。在全新配置中，这些尚不存在，因此 direnv 会失败。这是正常的。绕过 direnv，直接运行 devenv sync：

~/.local/share/sentry-devenv/bin/devenv sync

或者如果 devenv 已在 PATH 上：

devenv sync

同步完成后，direnv allow 应该就能成功。

如果 devenv sync 失败

常见原因：

1. devenv 已过时 — 执行 devenv update 或重新安装
2. Docker 未运行 — 先启动 OrbStack/Colima
3. 网络问题 — 重试；有些下载文件很大

运行 devenv doctor 进行自动诊断。

第 6 步：启动服务

首先：启动 Docker 镜像

devservices up

⏱️ 首次运行：5-10 分钟。 它会拉取大量 Docker 镜像（PostgreSQL、Redis、Kafka、ClickHouse、Snuba、Relay 等）。这是一次性开销。告诉用户：

这是在下载 Sentry 所需的全部 Docker 镜像。看起来很多——这很正常。后续启动大约需要 30 秒。

后续运行：约 30 秒。

OrbStack Socket 问题

如果 devservices up 或 devservices serve 失败并报错：

Make sure colima is running. Run `devenv colima start`.

……但用户使用的是 OrbStack，说明 devservices.py 命令只检查了 Colima socket。检查 src/sentry/runner/commands/devservices.py：

grep -n "colima\|docker.sock\|orbstack" src/sentry/runner/commands/devservices.py

_find_docker_socket() 函数需要检查多个 socket 路径。在 macOS 上应按以下顺序尝试：

1. ~/.colima/default/docker.sock（Colima）
2. ~/.orbstack/run/docker.sock（OrbStack）
3. /var/run/docker.sock（Docker Desktop / 默认）

如果只检查了 Colima，请打补丁以支持所有运行时。阅读 references/orbstack-fix.md 获取确切的模式。

然后：初始化数据库

如果是首次设置，数据库需要初始化：

.venv/bin/sentry upgrade --noinput

这会运行所有 Django 迁移，并创建默认数据（组织、角色、项目）。没有这一步，开发服务器会在每个页面上返回 500 错误。

不要只运行 sentry django migrate — 那样只会运行迁移，而不会初始化所需的默认数据。

创建超级用户

.venv/bin/sentry createuser --superuser --email [email protected] --password admin --no-input

第 7 步：启动开发服务器

devservices serve

或直接：

.venv/bin/sentry devserver

启动时会发生什么

Kafka topic 警告是正常的。 首次启动时，你会看到许多类似下面这样的行：

[WARNING] sentry.batching-kafka-consumer: Topic 'taskworker' or its partitions are not ready, retrying...

随着 Kafka 自动创建 topic，这些警告会在 30-60 秒后平息。不要惊慌。

访问开发服务器

• URL：http://dev.sentry.localhost:8000
• 登录：[email protected] / admin

必需：Sentry Cookie Sync 扩展

没有这个扩展，UI 会显示空白白屏。 安装它：

https://chromewebstore.google.com/detail/sentry-cookie-sync/kchlmkcdfohlmobgojmipoppgpedhijh

它会在 sentry.io 和 dev.sentry.localhost 之间同步认证 cookie。这不是可选项。

日常命令

初始设置完成后，日常工作流是：

cd ~/Projects/sentry    # (or wherever the repo lives)
devservices up           # start background services (~30s)
devservices serve        # start dev server
# → http://dev.sentry.localhost:8000

拉取新代码后：

devenv sync              # update dependencies + migrations (2-5 min)

重置数据库

make reset-db

Git worktree

每个 worktree 都有自己的 .venv。当你用 git worktree add 创建 worktree 时，post-checkout 钩子会在其中运行 devenv sync 来设置开发环境。否则，请在新 worktree 中运行一次 devenv sync，然后运行 direnv allow 来验证并激活它。

故障排查决策树

症状	可能原因	修复方法
direnv 卡住	Docker 运行时未运行	启动 OrbStack / Colima
devenv sync 因版本错误失败	devenv 版本过旧	devenv update 或重新安装
devservices up 提示 "colima not running"	使用的是 OrbStack，而脚本只检查 Colima	修补 devservices.py —— 参见第 6 步
服务器每个页面都返回 500	数据库未初始化数据	.venv/bin/sentry upgrade --noinput
relation "sentry_organization" does not exist	未运行迁移	.venv/bin/sentry upgrade --noinput
浏览器中白屏/空白页	缺少 Cookie Sync 扩展	安装 Chrome 扩展
启动时出现 Kafka 主题警告	首次启动的正常行为	等待 30-60 秒
端口已被占用	残留的容器	docker rm -f $(docker ps -aq) 后重试
一切都坏了	终极手段	devservices purge && devenv sync && devservices up
Docker 中的 DNS 故障	Colima DNS 缓存过期	devenv doctor 或 devenv colima restart

如需更深入的故障排查，请使用 AL MCP（如果可用）（devinfra-mcp）：

al_search_docs(query="<symptom keywords>")
al_read_doc(path="devenv/troubleshooting.md", query="<specific issue>")