数据规则运行时运维手册

适用范围：数据标准与数据流程的自然语言规则编写、不可变规则/标准版本发布、数据生产线发布，以及数据工厂中的 disabled 部署、canary、激活和回滚。

1. 不可越过的边界

自然语言和模型输出只存在于设计控制面；Runner 只接受服务端发布的 component_binding_id、execution_plan_hash 和短期任务令牌。
数据标准和数据流程共用 RuleVersion、编译器和执行证据。标准条款固定到 StandardVersion，数据流程发布时再冻结为 DataFlowVersion 包。
数据工厂只能绑定和投产已发布的 DataFlowVersion。不得修改自然语言、 RuleSpec、规则顺序或重新编译业务语义；语义变化必须回到设计态创建新版本。
DATA_FACTORY_ACTIVATION_ENABLED 默认关闭。只有本手册的发布门禁通过后，才能在目标环境显式设为 true。
不允许内联 SQL、Python、凭据、对象存储正文或数据样本。首期仅执行封闭 SQL/Polars 计划；生成 Python 不在激活路径内。

2. 依赖与健康检查

本地验收栈至少包含 PostgreSQL、Neo4j、MinIO、Kestra、Runner、Backend 和 Frontend。执行：

docker compose -f deploy/docker/docker-compose.yml ps
curl -fsS http://127.0.0.1:15500/health
curl -fsS http://127.0.0.1:15600/health
curl -fsS http://127.0.0.1:18080/api/v1/health
curl -fsS http://127.0.0.1:19000/minio/health/live

继续部署前应确认：

Alembic 已在目标 revision，且没有待执行迁移。
数据源定义可解析，但日志和请求中没有凭据。
MinIO 规则制品桶可读写，过期清理器可运行。
Kestra namespace 与 DataOps 环境一致。
/api/rules/capabilities 对未通过门禁的环境仍返回 data_factory_activation=false。

3. 识别一个生产线版本

排障和变更单必须同时记录：

rule_version_id、rule_spec_hash、模型/Prompt/上下文/候选 Hash；
standard_version_id 与固定的规则版本；
dataflow_version_id、package_hash；
deployment_id、binding_hash、schema_snapshot_hash；
每个 execution_plan_hash；
workflow_spec_hash、schedule_hash、engine_definition_hash；
correlation ID、Kestra execution ID 和 Runner rule run ID。

任一 Hash 与部署快照不一致时必须停止激活，不能现场重新生成或“修复”计划。

4. 受治理的发布和投产

以下命令中的令牌、ID 和幂等键均由调用方安全注入；示例不包含凭据。

# 能力检查
curl -fsS -H "Authorization: Bearer $DATAOPS_OPERATOR_TOKEN" \
  http://127.0.0.1:15500/api/rules/capabilities

# disabled 部署
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/deploy-disabled \
  -d '{"idempotency_key":"change-id:deploy","reason":"approved change"}'

# canary
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/canary \
  -d '{"idempotency_key":"change-id:canary","reason":"approved canary"}'

# 激活
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_ACTIVATOR_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/activate \
  -d '{"idempotency_key":"change-id:activate","reason":"canary passed"}'

# 回滚到部署快照记录的上一 active 版本
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_ROLLBACK_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/rollback \
  -d '{"idempotency_key":"incident-id:rollback","reason":"incident rollback"}'

不要复用别的操作者、动作或业务原因的幂等键。响应丢失或外部状态不明时，先调用对应 reconcile-deploy、reconcile-activate 或 reconcile-rollback，不得换键重试。

5. Canary 判定

Canary 只有同时满足下列条件才算通过：

package、binding、schema snapshot、物理计划、工作流、调度和引擎定义 Hash 与部署快照完全一致；
SQL/Polars 执行成功，输入、输出、拒绝、隔离数量可对账；
违规样本已脱敏、数量有上限、TTL 有效；
写入结果为明确 committed 或明确 rolled_back，不能是 unknown；
没有计划撤销、Schema drift、过期制品、令牌重放或连接池超预算；
canary 证据尚未过期，且由有权限的主体确认。

6. 证据查询与保留

规则版本的编译/测试证据： /api/rules/rule-versions/{id}/evidence。
目录资产证据： /api/rules/catalog/assets/{asset_type}/{id}/evidence。
Runner 的 rule_runs 记录执行状态、计数、计划 Hash、提交结果和 correlation ID。
rule_violation_samples 只保存脱敏且有界的引用，不保存秘密或完整敏感行。
rule_artifacts 保存 digest、Schema、行数、大小、过期时间和 MinIO 引用。

过期清理必须同时删除目录行和服务端拥有的 MinIO 对象，并按 correlation 范围执行。业务数据、非规则前缀对象或未过期制品不得被清理。

7. 故障处置

故障域	先检查	处置
模型	Provider 健康、超时、模型/Prompt Hash、歧义与置信度	不执行未验证输出；允许有界确定性修复，仍失败则请求澄清或切换已批准模型
编译器	算子/方言支持、Schema Hash、计划状态	不允许 best-effort 改义；回到设计态修改并发布新版本
Runner	任务令牌、计划 Hash、lease/heartbeat、提交结果	重放令牌直接拒绝；`unknown` 先对账和 reconcile，不能盲目重跑
数据源	定义版本、secret reference、连接池、Schema drift	轮换凭据只改秘密存储；重新绑定/发布，不把凭据放入请求
MinIO	digest、TTL、Schema、对象所有权、大小限制	损坏或过期制品拒绝读取；从上游受治理节点重建
Kestra	Flow Hash、execution、disabled/active 状态	重启后按服务端快照 reconcile；不得直接在 Kestra UI 修改业务 Flow
写入	幂等策略、目标唯一键、commit outcome	明确失败可按策略重试；未知提交结果先查目标与 ledger

紧急回滚仍必须走受治理 API。若激活/回滚操作 lease 丢失，旧操作者不得补偿新 owner 的 Flow；先恢复或对账持久化 operation，再继续。

8. 验收命令

PYTHONPATH=. .venv/bin/pytest -q tests/core/data_rules tests/runner
PYTHONPATH=. .venv/bin/pytest -q \
  tests/integration/test_data_rule_sql_execution.py \
  tests/integration/test_data_rule_polars_execution.py \
  tests/integration/test_data_factory_postgres_lifecycle.py
PYTHONPATH=. .venv/bin/pytest -q \
  tests/e2e/test_ai_rule_to_data_product.py \
  tests/performance/test_rule_execution_capacity.py
npm --prefix frontend run build

容量证据位于 docs/validation/data-rule-m5-capacity-evidence.json，真实本地模型证据位于 docs/acceptance/data-rule/real-qwen-authoring-evidence.json。两者均不包含凭据、完整 Prompt 或数据样本。

DATA_RULE_RUNTIME_RUNBOOK.md 7.2 KB 文件歷史 原始文件