Release Sentinel 服务 / Service

这是 Gate A 后的 TypeScript 服务骨架。它实现可测试的领域逻辑、内存开发仓储、最小 HTTP API、HMAC webhook 验签和 PostgreSQL 初始迁移；它尚未连接真实 Vercel、GitHub 或 Sentry 账户。

运行

cd /Users/albert.liu/Projects/dsh-delivery-gate/release-sentinel/service
npm install
npm test
docker compose up -d postgres
DATABASE_URL=postgres://release_sentinel:release_sentinel@localhost:5432/release_sentinel npm run migrate
cp .env.example .env
WEBHOOK_SIGNING_SECRET=local-secret INTERNAL_API_KEY=local-key npm run dev

可用端点：

| 方法 | 路径 | 说明 | | --- | --- | --- | | GET | /health | 服务健康检查。 | | GET | /v1/projects/demo/releases | 本地 demo 项目的发布列表。 | | GET | /v1/projects/demo/alerts | 本地 demo 项目的告警列表。 | | GET | /v1/projects/demo/connections | 连接状态；响应绝不包含凭据。 | | POST | /v1/projects/demo/webhooks/vercel | 使用 x-release-sentinel-signature: sha256=<hmac> 的规范化部署事件。 | | POST | /v1/projects/demo/releases/:releaseId/signals | 仅供内部调用的聚合信号写入；需要 Authorization: Bearer <INTERNAL_API_KEY>。 | | POST | /v1/projects/demo/releases/:releaseId/evaluate | 对一个 release 执行确定性策略评估；需要内部 API key。 | | GET | /v1/projects/demo/releases/:releaseId/evaluations | 获取发布的可复现评估记录。 | | POST | /v1/projects/demo/alerts/:alertId/resolve | 告警判定；同样需要内部 API key。 |

打开 http://localhost:4302/ 可使用本地发布观察控制台。

DSH 插件

本包可作为 dsh-release-sentinel 安装。它注册只读工具 release_sentinel_query，用于查询已运行的本地服务：health、list_releases、list_alerts 与 list_connections。默认地址为 http://127.0.0.1:4300，可通过 bundle 的 serviceUrl 配置改为同一用户明确指定的 HTTP(S) 服务 origin。

插件不启动服务、不写入发布数据、不读取 Provider token，也不通过工具参数接受服务地址。运行服务与安装 bundle 后，可调用：

{
  "action": "list_releases",
  "projectId": "demo"
}

发布前应在真实 DSH host 执行一次 bundle 加载和上述只读调用；服务与 Provider 的功能完成度仍受项目 Gate 约束。

隐私与数据处理说明见 PRIVACY.md，支持与反馈见 SUPPORT.md。

Webhook 输入是内部规范化契约，不是对 Vercel 正式 webhook schema 的猜测。V-03 完成后，应由真实、脱敏的 Provider fixture 驱动适配器实现。

数据库

001_initial.sql 定义了租户、项目、Provider event、Release、信号窗口、评估和告警的初始 PostgreSQL schema。DATABASE_URL 已配置时，API 自动使用 PostgreSQL Store；未配置时使用内存仓储，便于本地 demo 和单测。用 npm run migrate 执行可重复迁移。

成功接收且精确关联的 production release 会创建 evaluate_release 任务，其运行时间为部署时间加观察窗口。用 npm run worker 启动 Worker；它以 PostgreSQL 的 FOR UPDATE SKIP LOCKED 认领任务，并对失败使用有界指数退避。

任务通过 release 级去重键避免重复排队；worker 异常退出遗留的锁将在 JOB_LOCK_TIMEOUT_MS（默认五分钟）后重试。Sentry 的 fixture-first 聚合输入边界见 SENTRY_AGGREGATE_CONTRACT.md，实际 Sentry HTTP 查询仍受 V-04 验证 Gate 约束。

架构取舍见 ADR-001。

Provider 基础

GitHub 只读关联 adapter 已实现并以 mock HTTP fixture 测试。真实 token、Vercel 的官方 webhook schema 和 Sentry 聚合查询还未写入服务配置；它们必须先完成 V-03/V-04 的账户验证。

Provider 凭据在写入 connections 表前必须使用 CREDENTIAL_ENCRYPTION_KEY 和 AES-256-GCM 加密。该密钥必须来自部署环境的密钥管理系统，不得存入仓库、数据库或日志。