DeployAngel

面向 Python 的 DeployAngel

适用于 Django、FastAPI、Starlette 和 Flask 的 DeployAngel Agent，支持 Celery 和 RQ 任务。它会监视你的应用在生产环境中的运行情况，并为每个进程每分钟 报告一份精简的聚合数据。DeployAngel 会用这些数据验证每次部署，并在某个版本 通过验证、你可以停止监视时，通知你（或你的编码 Agent）。

安装

需要 Python 3.10 或更高版本。此软件包本身没有依赖项。

pip install deployangel

请在生产环境中为每个进程（包括 Web 服务器和任务工作进程）设置此项：

DEPLOYANGEL_TOKEN=da_live_...           # an ingestion token with the telemetry scope

在 Heroku 上，DeployAngel 插件会自动为你设置。

Django

支持 Django 4.2 或更高版本。

# settings.py
INSTALLED_APPS = [
    # ...
    "deployangel.django",
]

就这么简单。该应用会将 DeployAngel 的中间件放在 MIDDLEWARE 顶部 （如需自行指定位置，请手动添加），在 WSGI 和 ASGI 下记录请求，并在安装了 Celery 时对其进行检测。DEBUG 关闭时会启用报告。

FastAPI 和 Starlette

支持 FastAPI 0.100 和 Starlette 0.27 或更高版本。

import deployangel.fastapi

app = FastAPI()
deployangel.fastapi.init(app)      # deployangel.starlette.init(app) for Starlette

请在创建应用时调用它，并在应用开始处理请求之前完成调用。

Flask

支持 Flask 2.3 或更高版本。

import deployangel.flask

app = Flask(__name__)
deployangel.flask.init_app(app)

Celery

支持 Celery 5.3 或更高版本。在 Django 中会自动启用。在其他环境中，请在创建 Celery 应用时调用 init，以便工作进程启动 Agent：

import deployangel.celery

app = Celery("shop")
deployangel.celery.init(app)

RQ

支持 RQ 1.16 或更高版本。请使用 DeployAngel 的工作进程类运行工作进程：

rq worker -w deployangel.rq.Worker               # or deployangel.rq.SimpleWorker
python manage.py rqworker --worker-class deployangel.rq.Worker   # django-rq

RQ 会在分叉进程中运行每个任务，并在任务结束后立即退出，因此工作进程会在每个 任务完成后，根据 RQ 保存在 Redis 中的信息记录该任务。这包括失败任务的回溯信息， 但不包括 RQ 重试的任务尝试所产生的异常。

正在运行的版本

Agent 必须知道自己运行的是哪个版本。它会按以下顺序查找：

1. DEPLOYANGEL_REVISION（提交 SHA）和 DEPLOYANGEL_RELEASE_VERSION（如果你设置了）
2. Heroku dyno 元数据。使用 heroku labs:enable runtime-dyno-metadata 和 heroku labs:enable runtime-dyno-build-metadata 启用；两者都会在下次部署时生效
3. Kamal：KAMAL_VERSION
4. Render：RENDER_GIT_COMMIT
5. Fly.io：从 FLY_IMAGE_REF 获取部署的镜像标签。Fly.io 不会设置提交信息，因此 请传入提交信息以便按提交跟踪更改（在 Dockerfile 中使用 ENV DEPLOYANGEL_REVISION=$GIT_SHA，并添加 --build-arg GIT_SHA=$(git rev-parse HEAD)）
6. Railway：RAILWAY_GIT_COMMIT_SHA 或 RAILWAY_DEPLOYMENT_ID
7. Coolify：SOURCE_COMMIT。Dokku：GIT_REV
8. 应用根目录中的 REVISION 文件
9. git 工作区检出版本：读取 .git 中 HEAD 所指向的提交；.git 可位于应用根目录中， 也可位于其上方最多 3 层目录中，且不会运行 git。这适用于通过 git pull、Fabric 或 Ansible 部署的服务器
10. ECS（包括 Fargate）：从 ECS 提供的元数据端点获取容器镜像（启动时发送一次本地请求）
11. 代码指纹：使用 code: 加上 Agent 已发送的文件摘要（见下文）哈希的前 12 个字符， 不包含提交信息。相同代码会生成相同指纹，因此重新部署未更改的代码不会被视为新版本。 指纹会在报告器启动时于后台计算，而不是在启动时计算，并且需要启用文件摘要。 如果没有提交信息，DeployAngel 仍会显示某个版本中发生更改的文件，但不会显示其提交和 拉取请求，因此 Agent 会记录警告：条件允许时请设置 DEPLOYANGEL_REVISION

对于其他 Docker 部署方式，请将提交信息写入镜像： deployangel install docker 会在 Dockerfile 末尾添加 ARG GIT_SHA 和 ENV DEPLOYANGEL_REVISION=$GIT_SHA，不会使缓存层失效；构建时请添加 --build-arg GIT_SHA=$(git rev-parse HEAD)。在 DigitalOcean App Platform 上，请在 应用规范中设置 DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH}。

发送的数据

• HTTP 请求数、按状态码统计的 4xx/5xx 数量、未处理的异常，以及延迟直方图；分别按应用和路由统计。
• 路由记录为框架匹配的模式（GET /users/<int:pk>/、GET /items/{item_id}），绝不记录原始路径。每个负载最多发送 100 条路由，其余路由归入 __other__。
• 后台任务：按任务统计尝试次数、失败次数、丢弃的任务、执行时长和队列延迟。为计算队列延迟，Celery 任务消息会携带一个额外的标头 deployangel_published_at，记录消息发送时间。
• 每分钟结束时仍在运行的任务，以及每类任务中运行时间最长的任务已运行多久，以便发现卡住的任务。
• 发布标识、运行时版本，以及每个进程的实例 ID。
• 异常：稳定的指纹、异常类、消息的首行，以及仅包含应用代码的调用栈帧（文件路径和函数名）。消息中的数字、ID、电子邮件地址、UUID、长十六进制字符串、引号中的值以及请求主机名都会替换为占位符。其他文字会保留：Payment failed for Jane Doe 会原样发送。如果应用的消息可能包含个人或健康数据，请关闭消息。
• 每个进程只发送一次：路由表（包含每个视图的模块和文件）、任务名称和文件、Celery Beat 中声明的定期计划（在设置中或 django-celery-beat 的表中）、关键工作流，以及文件摘要（相对路径和哈希值，绝不包含文件内容），以便 DeployAngel 判断发布中哪些路由发生了变化。可通过 DEPLOYANGEL_FILE_DIGESTS=false 禁用摘要。

不会发送请求正文、参数、标头、Cookie、SQL、日志或用户数据。

数据与定价

• 所有数据都会发送到 DeployAngel 的托管服务，该服务运行在美国的 DigitalOcean 上。没有可自托管的版本，也无法选择区域。
• 遥测数据保留 21 天；发布历史则根据套餐保留 7、30 或 90 天。隐私政策中列有详细信息以及 DeployAngel 使用的服务。
• Beta 期间 DeployAngel 免费，付费套餐开始前会提前通知。请参阅定价。

安全性

• 请求或任务执行期间不会进行任何网络操作。记录数据时只会更新内存计数器。
• 负载由后台线程每分钟发送一次，并设有较短的超时时间。
• 如果无法连接 DeployAngel，缓冲区大小有限（最多 10 个负载，以 gzip 压缩的 JSON 格式保存），并会丢弃最旧的数据。应用绝不会因此阻塞或失败。
• 支持安全地使用 fork（Gunicorn、Celery 的 prefork 池、uWSGI），并会在关闭时刷新当前分钟的数据。使用 uWSGI 时，请启用线程（enable-threads = true）。

python bench/overhead.py 可用于测量开销。在搭载 Python 3.14 的 Apple M 系列笔记本电脑上，记录一个请求会增加约 1.7 µs；当路由、任务、检查点和异常列表都达到上限时，Agent 占用约 0.5 MB，其中包括 10 分钟尚未发送的数据。

配置

对于大多数应用，环境变量就足够了。在 Django 中，设置项放在 DEPLOYANGEL 字典中；在其他环境中，在调用 init 之前调用 deployangel.configure：

# settings.py
DEPLOYANGEL = {
    "environments": ["production", "staging"],   # default: production only
}

# or anywhere else
deployangel.configure(environments=["production", "staging"])

Agent 会在所列环境中上报。Python 框架不会命名环境，因此如果设置了 DEPLOYANGEL_ENVIRONMENT，就使用该值；否则，框架的调试模式开启时为 development，关闭时为 production。DEPLOYANGEL_ENABLED=true|false 可在 任何环境中强制开启或关闭上报。DEPLOYANGEL_URL 可覆盖 API 端点（默认为 https://api.deployangel.com）。

文件路径相对于应用根目录；默认情况下是工作目录 （在 Heroku 和大多数容器中，是仓库根目录）。如果进程从其他位置启动， 请设置 DEPLOYANGEL_ROOT。

关键流程（例如注册或密码重置）始终会列在通行报告中：

DEPLOYANGEL = {
    "critical_flows": {"password_reset": ["POST /password-reset/", "job:accounts.tasks.send_reset_email"]},
}

健康检查不会被记录：负载均衡器和正常运行时间监控器会频繁调用它们，而且它们总是能快速响应，因此会让你的应用看起来比实际页面更繁忙、状态更好。无论挂载在哪里，Agent 都能识别 django-health-check、django-alive 和 django-watchman，以及常见路径上的任何路由（/up、/health、/healthz、/healthcheck、/health_check、/livez、/readyz、/statusz、/ping、/ht、/alive）。如果你的健康检查位于其他路径，请按仪表板中的显示方式列出。对这些路径的 HEAD 请求也不会被纳入：

DEPLOYANGEL = {"ignored_routes": ["GET /status/"]}

异常消息

如果要发送不含任何消息的异常，仅包含异常类、指纹和应用代码帧：

DEPLOYANGEL = {"exception_messages": False}   # or DEPLOYANGEL_EXCEPTION_MESSAGES=false

由于指纹从不使用消息，分组、新异常检测和判定的工作方式保持不变。你将无法在仪表板、通知和 AI 调查中看到消息文本。

已处理的异常

你的代码捕获的异常不会被发现。如需提供上下文并上报某个异常（已处理的异常绝不会导致发布失败）：

try:
    sync_inventory()
except UpstreamError as error:
    deployangel.notify(error)

定期任务

DeployAngel 需要按计划声明定期任务。它会读取 Celery Beat 的 beat_schedule（crontab 和间隔任务，间隔从 Beat 启动时开始计算），并使用 Celery 所用的时区；如果安装了 django_celery_beat，还会读取其中启用的定期任务。它不会读取太阳时计划，也不会读取 RQ 的调度器，因为其任务只存储在 Redis 中。DeployAngel 也会根据任务历史记录学习定期任务。

Cron、Heroku Scheduler 和 django-crontab

由应用外部按计划启动的工作（例如 cron、Heroku Scheduler 或 Kubernetes CronJob）不会被 Celery Beat 发现。请使用它运行时的名称进行声明，并提供 cron 行或类似 "every day at 4am" 的文字；除非指定时区，否则使用服务所在时区 （"0 3 * * * America/New_York"）：

DEPLOYANGEL = {
    "recurring_jobs": {
        "shop.tasks.send_receipts": "0 3 * * *",            # a Celery or RQ task
        "manage.py send_invoices": "every day at 4am",      # python manage.py send_invoices
        "nightly import": "30 2 * * *",                     # deployangel.task("nightly import")
    },
}

• 任务 无论在哪里运行，都会被记录。

• Django 管理命令 如果命名为 "manage.py <command>"，无需修改代码即可记录。

• 任何其他代码 在进行包装后才会被记录。异常会被记录并重新抛出：

  with deployangel.task("nightly import"):
      run_import()
  
  @deployangel.task("nightly import")
  def run_import(): ...
  

安装了 django_crontab 时，会自动读取 django-crontab 的 CRONJOBS 设置：系统会按服务所在时区的计划检查每个任务，其运行情况无需修改任务即可记录（调用 call_command 的任务会记录为 manage.py <command>）。

检查点

错误和延迟无法发现那些悄无声息停止发生的工作。只需一行代码，即可统计重要的业务事件：

deployangel.checkpoint("order.created")
deployangel.checkpoint("webhook.stripe.processed", count=len(events))

DeployAngel 会根据流量学习每个检查点的正常发生频率，并在检查点大幅下降或停止发生后判定发布失败，即使每个请求和作业仍然成功也不例外。只有下降才会触发标记；流量不足的检查点不会阻止发布通过。检查点也可以成为关键流程的一部分（checkpoint:order.created）。

Agent 还会记录每个检查点是在处理 HTTP 请求时发生，还是在运行作业时发生（Celery 任务或 RQ 作业，包括在请求中即时运行的作业），因此 DeployAngel 会将其与正确的流量进行比较：在请求中记录的检查点对比请求量，在作业中记录的检查点对比作业运行次数。

可以在任何位置安全调用：它绝不会引发异常、不会访问网络，并且在报告环境之外会被忽略。名称可使用字母、数字以及 . _ : -（最多 100 个字符）；请使用固定的一组名称，不要包含 ID，因为每分钟最多统计 100 个不同名称。

注册部署

DeployAngel 会在 Agent 首次报告新版本时发现新发布，并从那时起进行验证，无需进行任何设置。在 Heroku 上，附加组件还会为你注册每个发布。

如需从 CI 注册部署（这样也能捕获从未启动的发布），请在控制面板中创建一个用于 CI deploys 的 API 令牌。在 GitHub Actions 中，请在部署步骤之后添加 DeployAngel/verify-release：它会注册部署、等待判定结果，并在发布失败时使该步骤失败。

- uses: DeployAngel/verify-release@v1
  with:
    api-token: ${{ secrets.DEPLOYANGEL_API_TOKEN }}

在其他任何环境中，提交 commit：

curl -fsS https://api.deployangel.com/api/v1/deployments \
  -H "Authorization: Bearer $DEPLOYANGEL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"commit\": \"$GIT_SHA\"}"

命令行和编码 Agent

此软件包包含 deployangel 命令（也可使用 python -m deployangel）以及供编码 Agent 使用的 MCP 服务。它们只与 DeployAngel 的 API 通信：绝不会启动 Agent 或加载你的应用，因此只要安装了此软件包，就可以在任何地方运行；也可以通过 uvx deployangel 在未安装任何内容的情况下运行。将令牌设为 DEPLOYANGEL_API_TOKEN：使用 “CLI & coding agents” 令牌可读取判定结果；使用 “CI deploys” 令牌还可注册部署并报告检查结果。

若要让编码 Agent 帮你设置 DeployAngel，请在 DeployAngel 中打开应用页面并选择 “Set up with your coding agent”：此操作会提供一次性设置代码，而非令牌。deployangel setup --code=CODE 会兑换该代码，并将应用令牌和 “CI deploys” 令牌保存到 .deployangel/credentials.json；该文件仅你可读，并会排除在 git 之外，且不会打印任何令牌。如果未设置 DEPLOYANGEL_API_TOKEN，此后该命令和 MCP 服务会使用已保存的令牌。deployangel token app（或 api）会输出已保存的令牌，供你传入主机或 CI 的密钥中，因此令牌不会显示在屏幕上，也不会出现在 Agent 的对话中：

fly secrets set DEPLOYANGEL_TOKEN=$(deployangel token app)
deployangel token api | gh secret set DEPLOYANGEL_API_TOKEN

deployangel verify --wait                   # current git HEAD, until a verdict
deployangel verify --wait --until=initial   # return at the 15-minute initial check
deployangel status                          # latest deployment
deployangel plan                            # what to exercise so a release clears sooner
deployangel exercise --url=https://example.com  # send the plan's read-only requests to production
deployangel release --commit=$SHA           # register a deploy (manual or CI)
deployangel check --name="smoke: signup" --status=pass --covers=registration
deployangel install kamal                   # a Kamal post-deploy hook that registers each deploy
deployangel install docker                  # bake the commit into the image as DEPLOYANGEL_REVISION
deployangel install agents                  # set up Claude Code, Cursor, and Codex in this project
deployangel doctor                          # check the setup

deployangel doctor 会检查此代码库（项目依赖中的 Agent，以及生产环境将如何获知发布），并在提供令牌时检查 DeployAngel 已获知的应用信息：哪些进程会报告信息及其运行的发布版本、Agent 报告的路由、作业类和计划作业，以及设置问题和对应的处理方法。它不会加载你的应用，因此 Celery Beat、django-celery-beat、django-crontab 和 recurring_jobs 的计划会根据运行中的 Agent 所报告的信息进行检查。只有发生错误时（令牌被拒绝、服务器无法访问、依赖项中没有 Agent）才会以状态码 5 退出；警告会以状态码 0 退出，因此可安全用于 CI。它会读取 DEPLOYANGEL_API_TOKEN，或应用运行环境中的 DEPLOYANGEL_TOKEN，因此 heroku run deployangel doctor 也会显示该进程所报告的发布版本。 在终端中输出文本；通过管道传递时输出 JSON（--format=text|json）。退出代码：0 表示已清除，1 表示失败，2 表示尚未清除，3 表示仍在验证或已超时，4 表示未找到部署，5 表示用法、身份验证或网络错误，6 表示初始检查时暂未发现问题（尚未清除），7 表示初始检查时存在警告。在 GitHub Actions 中，verify 还会将判定结果写入任务摘要。

对于编码 Agent，在项目中运行 deployangel install agents。它会将 MCP 服务添加到 .mcp.json（Claude Code）、.cursor/mcp.json（Cursor）和 .codex/config.toml（Codex 仅会在你信任的项目中读取此配置），并将部署后等待判定结果的说明写入 AGENTS.md，同时创建一个导入该文件的 CLAUDE.md。在 uv 或 Poetry 项目中，它会通过 uv run 或 poetry run 运行 deployangel。它不会替换现有条目，重复运行时只会更新自己的说明。提交这些文件；令牌保留在你的环境中。

或者自行添加服务：

claude mcp add deployangel -- deployangel mcp        # Claude Code (or: -- uvx deployangel mcp)

对于 Codex，在 ~/.codex/config.toml 中：

[mcp_servers.deployangel]
command = "deployangel"     # or "uvx", with args = ["deployangel", "mcp"]
args = ["mcp"]

其他任何 MCP 客户端（Cursor、VS Code、Zed 等）都会运行相同的命令。服务需要在其启动环境中设置 DEPLOYANGEL_API_TOKEN。

这些工具包括 get_verification、wait_for_verification、get_exercise_plan、list_deployments、get_exception、list_late_regressions，以及在令牌允许时使用的 register_deployment。它们都无法更改生产环境。发布尚未获准时，deployangel plan（或 get_exercise_plan）会说明获准还需要满足哪些条件，以及应针对生产环境测试什么内容，才能更快获准。它会区分获准所需满足的条件，以及仅值得运行的已更改路径和很少使用的路径。会更改数据的路由会标记出来；请对这些路由使用测试账号，或先行询问。deployangel exercise --url=<production URL> 会执行只读部分：它会请求计划中没有路径参数的 GET 路由，将任何未完成的请求数量分摊到这些路由上（最多 200 个请求，每秒约 5 个请求），并将发送的请求记录到发布中，页面会在“Exercised from your side”下列出这些请求。它会跳过并列出会更改数据或需要路径参数的路由；遇到某个页面的第一个 404 后就会停止请求该页面，并将该页面对应的请求份额分配给成功响应的页面。--dry-run 会显示它将发送的内容。

该命令及其输出与 Ruby gem 的 deployangel 命令一致，因此两者均适用相应的文档和 Agent 说明。

开发

python -m venv .venv
.venv/bin/pip install -e . django djangorestframework django-celery-beat fastapi httpx flask celery rq fakeredis pytest pytest-asyncio
.venv/bin/pytest

RQ_REDIS_URL=redis://localhost:6379/15 也可以让 RQ 的分叉工作进程连接真实的 Redis 运行。

该 Agent 使用 DeployAngel Agent Protocol v1：每个进程每分钟向 POST /api/v1/telemetry 发送一个 gzip 压缩的 JSON 负载，并在每个进程启动时向 POST /api/v1/application_metadata 发送一次应用元数据。 src/deployangel/core/protocol.py 和 src/deployangel/metadata.py 会构建这些内容。