60 lines
3.7 KiB
Markdown
60 lines
3.7 KiB
Markdown
# Bell 事件存储、审计与 Brain 事件入口
|
||
|
||
Bell 当前实现 M3 的事件域基础、Sense 审计 relay 与默认关闭的 Brain 事件 ingress：
|
||
|
||
- Bell 在可信 ingress 内为不含 `id` 的候选事实生成 `evt_` ULID。
|
||
- 最终事件同时通过冻结 v0.1 JSON Schema 与六项代码级断言。
|
||
- PostgreSQL `bell.events` 保存不可变事实；后续 outcome 追加到 `bell.event_outcomes`。
|
||
- `bell_runtime` 对事件、outcome、全局审计和 Brain 来源收据只有 `SELECT/INSERT`，没有 `UPDATE/DELETE/TRUNCATE` 或 migration owner 权限；只可清理两张短期 nonce 收据表。
|
||
- `cmd/bell-api` 默认只监听 `127.0.0.1:8081`，接收 HMAC 签名的 `/internal/v1/audit-events:batch`，把脱敏设备操作事实追加到 `bell.audit_events`。
|
||
- `(key_id, nonce)` 收据保存 10 分钟；相同摘要重放原结果，不同摘要返回冲突。非回环监听必须配置 TLS 证书和私钥。
|
||
- T-019 可选 `/internal/v1/event-candidates` 把 HMAC key 绑定到一个 `producer_id`，通过 `event_ingress_bindings` 解析数字事件身份并复查当前 Site/Area/Sense Device；缺失、删除、Area 不一致或 `non_imaging_only` 均失败关闭。
|
||
- `(producer_id, source_event_id)` 永久收据、最终事件和成功 nonce 响应同事务提交；相同 canonical candidate 返回原 Bell ID，不同 candidate 返回 `source_event_conflict`。
|
||
|
||
公共认证/事件 API、规则、Alert 和证据对象存储仍需后续任务冻结。两条 HMAC ingress 都是内部适配器，不得当成 Bell 公共协议或共用 key。
|
||
|
||
启动内部 receiver 前必须私下设置 `BELL_DB_DSN` 和仓库外绝对路径 `BELL_AUDIT_KEYS_FILE`。远端监听还必须设置 `BELL_TLS_CERT_FILE`、`BELL_TLS_KEY_FILE`；仓库不保存 DSN、key 或证书：
|
||
|
||
```powershell
|
||
go -C Bell run ./cmd/bell-api
|
||
```
|
||
|
||
事件 ingress 默认关闭。启用前，管理员先在专用数据库执行 `001`～`017` migration，并用受控 SQL 创建与现有 Bell Site/Area、Sense Device 一致的绑定；运行角色不能写绑定。然后私下设置：
|
||
|
||
```powershell
|
||
$env:BELL_EVENT_INGRESS_ENABLED = 'true'
|
||
$env:BELL_EVENT_INGRESS_KEYS_FILE = 'D:\private\brain-event-keys.json'
|
||
$env:BELL_EVIDENCE_FORBIDDEN_NAMES_FILE = 'D:\private\forbidden-evidence-names.txt'
|
||
go -C Bell run ./cmd/bell-api
|
||
```
|
||
|
||
forbidden-names 文件每行一个不得出现在证据 URI 的租户/客户标记，至少一行、最多 256 行。key 文件格式见 `docs/contracts/README.md`。仓库不提供真实 secret、DSN、绑定或客户名称；绑定只能引用已经存在且同 Area/modality 的设备。
|
||
|
||
管理员在事务中核对逻辑资源后，可按下列列签名配置一条视频绑定；数字 ID 是冻结事件契约使用的稳定正整数，不是把文本 ID 强转为数字：
|
||
|
||
```sql
|
||
INSERT INTO bell.event_ingress_bindings(
|
||
producer_id, tenant_id, site_id, device_id,
|
||
logical_tenant_id, logical_site_id, logical_device_id, logical_area_id,
|
||
modality, enabled
|
||
) VALUES (
|
||
'brain-main', 1, 1, 1,
|
||
'tenant-logical-id', 'site-logical-id', 'device-logical-id', 'area-logical-id',
|
||
'video', true
|
||
);
|
||
```
|
||
|
||
外键只负责资源存在；runtime 还会复查 Area 属于同 Site、设备当前 Area/modality 一致、Site/Area 未删除且策略允许成像。换绑或停用由管理员显式更新/删除 binding，不能修改永久来源收据。
|
||
|
||
## 验证
|
||
|
||
```powershell
|
||
go -C Bell mod download
|
||
go -C Bell test ./...
|
||
go -C Bell vet ./...
|
||
go -C Bell build ./...
|
||
./scripts/test_postgres.ps1 -PgRoot D:\pgsql17
|
||
```
|
||
|
||
隔离 PostgreSQL harness 会创建临时 `bell_runtime` 登录成员，运行真实 repository、幂等冲突和不可变权限测试，然后停止并删除临时集群；不会读取或修改现有 `D:\pgsql17\data` 或 5432 服务。
|