Auris Flow

让每一条业务洞察，都能回到它的音频证据

面向音频质检、标注、评测与洞察的可追溯工作台。
一条链路连接音频、转写、标签、模型、任务、人和最终业务结论。

5 分钟启动 · 能力导览 · 系统架构 · 验证门禁 · 发行状态 · 生产候选部署

_{Audio evidence · quality evaluation · governed AI workflows · explainable insight}

---

Important

当前仓库是 Auris Flow v1.0.0 的候选实现（Release Candidate），适合产品评审、前后端联调和工程 验证；它尚未完成正式 Release 审批，也尚未获得生产支持承诺。项目状态和剩余门禁见 发行状态。

从音频到行动，不丢失上下文

传统音频质检系统把音频、转写、标签、评测和报表拆成互不相干的页面。Auris Flow 把它们建模为 同一条证据链：每次运行、人工判断、版本变更和业务结论都绑定 tenant_id、project_id 与 trace_id。

进入系统	形成证据	做出判断	推动行动
连接器、批次、音频资产	转写、说话人、片段、人工标注	标签版本、评测集、校准、复核	洞察报告、实验、发布、回滚
对象身份与内容哈希	原始对象与派生结果可追溯	规则、模型与人保持版本绑定	结果可回到证据和执行记录

flowchart LR
    A["音频与业务对象"] --> B["转写 / 说话人 / 片段"]
    B --> C["调听与证据标注"]
    C --> D["标签版本与事实集"]
    D --> E["评测 / 校准 / 人工复核"]
    E --> F["洞察报告与行动"]
    F --> G["实验 / 发布 / 回滚"]

    T["tenant · project · trace_id"] -. 贯穿 .-> A
    T -. 贯穿 .-> C
    T -. 贯穿 .-> E
    T -. 贯穿 .-> G

Loading

🎧 我想先体验产品工作台

启动本地环境后，从任务画布进入完整演示链路：

1. 在数据资产查看音频、转写、派生对象和血缘。
2. 在调听工作台使用波形、说话人、转写和片段证据协同复核。
3. 在标签中心查看标签定义、样本、版本、发布和生命周期统计。
4. 在评测中心执行评测，追踪指标、badcase、校准与人工复核。
5. 在知识库查看证据引用、派生向量索引和召回解释。
6. 在洞察中心把指标、归因、报告和后续行动重新绑定到源证据。

🔌 我想联调 API

• 业务接口统一位于 /api/v1/*，资源使用复数与 kebab-case。
• OpenAPI：http://127.0.0.1:8000/docs
• 存活检查：/healthz
• 强依赖就绪检查：/readyz
• 错误响应使用稳定 envelope，并携带 request ID 与 trace ID。
• 前端只访问 BFF，不直连 MySQL、Redis、对象存储、Qdrant 或 Dagster。

完整契约从 后端规格入口 开始阅读。

🏭 我想评估单机生产候选

生产候选由 FastAPI BFF、异步 Worker、MySQL、Redis、MinIO、Qdrant、真实 Dagster、Keycloak 参考 IdP、反向代理和可观测性组件组成。它只面向一台 64 位 Linux 主机，不宣称节点级高可用或 宿主机故障自动容灾。

不要直接复用本地示例凭据。先阅读 生产候选安装与支持边界，再按 备份恢复和升级回滚完成演练。

5 分钟启动本地工作台

需要什么

• Python 3.12（代码兼容 >=3.11）
• uv 0.10.x
• Node.js 22
• 正在运行的 Docker Engine / Docker Desktop

安装并启动

git clone https://github.com/g5n-dev/auris_flow.git
cd auris_flow

(cd backend && uv sync --frozen --all-extras --python 3.12)
npm ci --prefix prototype/auris-flow-ui --ignore-scripts

PYTHON="$PWD/backend/.venv/bin/python" bash scripts/dev_up.sh

dev_up.sh 会启动本地 MySQL、Redis、MinIO、Qdrant，执行迁移和演示数据初始化，再托管 BFF、 Outbox Worker 与 Vite。按 Ctrl + C 可停止应用进程；基础依赖容器仍会保留， 方便下次快速启动。

入口	地址
工作台	http://127.0.0.1:5173
BFF	http://127.0.0.1:8000
OpenAPI	http://127.0.0.1:8000/docs
Readiness	http://127.0.0.1:8000/readyz
MinIO Console	http://127.0.0.1:9001

本地演示登录：

邮箱    demo.operator@auris.local
密码    auris-demo
租户    aurora_auto
项目    sales_qa

Caution

这个账户和 ALLOW_DEV_AUTH=true 只允许出现在 local/test/ci。生产配置发现 demo credential、 弱签名密钥、通配 CORS、开发认证或 fake adapter 时会 fail closed。

手动分三步启动

1. 基础依赖

docker compose -f docker/local/docker-compose.yml up -d

2. BFF 与 Worker

cd backend
uv sync --frozen --all-extras --python 3.12
uv run alembic upgrade head
uv run python -m app.seed local_demo

APP_ENV=local ALLOW_DEV_AUTH=true \
  uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload --no-access-log

在另一个终端：

cd backend
APP_ENV=local ALLOW_DEV_AUTH=true uv run python -m app.workers.outbox_worker

3. 前端

cd prototype/auris-flow-ui
npm ci --ignore-scripts
npm run dev

系统架构

flowchart TB
    USER["浏览器"] --> EDGE["Edge / TLS / security headers"]
    EDGE --> UI["React 工作台"]
    EDGE --> BFF["FastAPI BFF<br/>/api/v1/*"]
    IDP["通用 OIDC IdP<br/>Keycloak 仅作参考"] --> BFF

    subgraph truth["权威事实"]
        MYSQL[("MySQL<br/>业务状态 / 审计 / Outbox")]
        OBJECTS[("MinIO / S3 / OBS / OSS<br/>音频与证据对象")]
    end

    subgraph derived["派生索引与运行辅助"]
        REDIS[("Redis<br/>限流 / 锁 / 运行辅助")]
        QDRANT[("Qdrant<br/>派生语义索引")]
    end

    BFF --> MYSQL
    BFF --> OBJECTS
    BFF --> REDIS
    BFF --> QDRANT

    MYSQL --> OUTBOX["Transactional Outbox"]
    OUTBOX --> WORKER["异步 Worker"]
    WORKER --> DAGSTER["Dagster<br/>底层执行引擎"]
    DAGSTER --> CALLBACK["签名 completion / 状态同步"]
    CALLBACK --> BFF

    BFF -. traces / metrics .-> OTEL["OpenTelemetry Collector"]
    WORKER -. traces / metrics .-> OTEL
    DAGSTER -. traces / metrics .-> OTEL
    OTEL --> OBS["Prometheus · Tempo · Grafana · Alertmanager"]

Loading

不可跨越的边界

边界	约束
权威数据	MySQL 是权威业务存储；对象存储保存权威对象。Redis 与 Qdrant 不能成为唯一业务事实来源。
执行引擎	Dagster 只承担后台执行，不作为业务 API 语言，也不在产品界面暴露为“Dagster 画布”。
前端访问	浏览器只访问 Edge/BFF，不持有长期 bearer token，不直连基础设施。
洞察路径	第一阶段使用 MySQL 聚合/预计算、Redis 辅助和 Qdrant 召回解释，不引入 ClickHouse。
部署边界	首发目标是 Linux 单机 Docker Compose；不承诺自动故障转移或节点级高可用。

技术基线

层	组件	主要职责
Web	React 18、TypeScript、Vite	模块化工作台、可见交互反馈、BFF 联调
API	FastAPI、Pydantic、SQLAlchemy、Alembic	认证、业务契约、强表、迁移
Data	MySQL 8.4、Redis 7.4	权威状态、审计、Outbox、限流与运行辅助
Object	MinIO / S3 / OBS / OSS	音频、转写、证据包、报告与导出
Recall	Qdrant	知识、证据、样本和 badcase 的派生语义索引
Execution	Dagster	提交、状态同步、取消、超时、重试与恢复
Observability	OpenTelemetry、Prometheus、Tempo、Grafana	Trace、Metrics、Dashboard 与告警

音频为什么可以拖动播放：HTTP Range 链路

浏览器原生媒体元素可以直接使用短期 playback grant 请求 GET /api/v1/audio-playback?grant=…，无需把长期 Authorization header 暴露给媒体组件。

sequenceDiagram
    participant UI as Browser
    participant BFF as FastAPI BFF
    participant OBJ as Object Storage

    UI->>BFF: 申请短期 playback grant
    BFF-->>UI: /api/v1/audio-playback?grant=…
    UI->>BFF: GET + Range: bytes=…
    BFF->>OBJ: Provider-signed ranged GET
    OBJ-->>BFF: 206 + Content-Range
    BFF-->>UI: 206 + Accept-Ranges + ETag

Loading

• 支持 GET / HEAD、闭区间、开放区间、suffix range 和 If-Range。
• 合法部分请求返回 206；不可满足或多区间请求稳定返回 416。
• MinIO、S3、华为云 OBS 与阿里云 OSS 的 provider 签名不会交叉复用配置。
• Edge 对该精确 playback location 关闭 access log，避免 query 中的短期 grant 落盘；上游 WAF、 LB 与 APM 也必须遵守同一约束。

可信运行基线

写操作从一开始就按多租户生产系统约束建模：

• 身份：OIDC Authorization Code + PKCE；浏览器只持有 Secure Cookie 中的不透明 HttpOnly 浏览器会话。
• 授权：资源级 default-deny，租户、项目、角色与对象范围同时校验。
• 浏览器防护：Cookie 写请求校验 CSRF token 与可信 Origin。
• 幂等与审计：写入口、任务提交和回写都记录主体、作用域、结果、request ID 与 trace_id。
• 可靠异步：事务 Outbox、租约、fencing、退避、死信与人工重放形成闭环。
• 安全回写：HMAC key id、时间窗、nonce、幂等键、重放防护和轮换窗口。
• Secret：生产值只允许通过 Docker secret 或外部 secret file/reference 注入。
• 可观测性：业务 trace_id 与 OTel trace/span 关联，日志执行字段级脱敏。

安全问题请按 SECURITY.md 私下报告，不要创建公开 Issue。运维处置见 安全事件响应 Runbook。

验证与质量门禁

日常开发使用同一个入口：

PYTHON="$PWD/backend/.venv/bin/python" bash scripts/verify_fast.sh

它覆盖规格与 OpenAPI、secret scan、Ruff、mypy、Alembic 升降级、后端单元/契约/集成测试、 前端架构与构建、bundle budget 和 UI smoke。

要证明什么	命令
日常工程反馈	bash scripts/verify_fast.sh
干净克隆可复现	bash scripts/verify_clean_clone.sh
浏览器与 BFF 闭环	AURIS_RUN_E2E=1 bash scripts/verify_all.sh
MySQL / Redis / MinIO / Qdrant	bash scripts/verify_real_stack.sh
真实 Dagster 引擎	bash scripts/verify_real_dagster.sh
BFF → Outbox → Dagster → 回写	bash scripts/verify_product_dagster_path.sh
镜像前发行门禁	bash scripts/verify_release.sh --pre-image
签名候选证据聚合	使用官方 tag workflow 产出的 recovery JSON、Sigstore sidecar 与同一签名 deployment，设置 AURIS_BACKUP_RESTORE_EVIDENCE、AURIS_BACKUP_RESTORE_EVIDENCE_SIGSTORE_BUNDLE、AURIS_RELEASE_BUNDLE_ROOT、AURIS_RELEASE_TAG 后运行 bash scripts/verify_release.sh；仍须满足 RELEASE_CHECKLIST.md 中独立的 rebuild-required、外部 RC 与人工门禁

为什么“真实栈通过”不等于“真实 Dagster 通过”

scripts/verify_real_stack.sh 的 Dagster 端点由 scripts/fake_dagster_graphql_server.py 提供，用来 验证开发协议、对象存储、Qdrant 与故障恢复；它不能替代 bash scripts/verify_real_dagster.sh。

后者启动生产 Compose 的真实 Dagster，并验证 SAFE_TERMINATE 取消语义。该证明仍只覆盖 Dagster 引擎层；产品级 BFF、Outbox、状态回写与签名 callback 由 bash scripts/verify_product_dagster_path.sh 独立验收。

为什么本地全绿仍不能直接发布

公开 Release 证据必须全部绑定同一个干净 commit，并同时满足：

• 不可变且独立审批的前端 bundle 与 Linux 视觉基线；
• 真实依赖 E2E、备份恢复演练与告警演练；
• 固定镜像 digest、SBOM、漏洞扫描、签名与 checksum；
• 权利人授权、最终 NOTICE 和第三方依赖许可结论；
• 外部维护者在干净主机上的安装、升级、回滚与恢复验证。

因此发布门禁刻意 fail closed，不接受“把 PENDING 手工改成 APPROVED”。

仓库地图

.
├── backend/                   # FastAPI BFF、领域服务、迁移与测试
├── prototype/auris-flow-ui/  # React + TypeScript 产品工作台
├── docker/local/             # 本地 MySQL、Redis、MinIO、Qdrant
├── production/               # 单机生产候选、Dagster、Edge、可观测性
├── doc/backend-spec/         # API、模型、RBAC、状态机与事件契约
├── doc/runbooks/             # 安装、升级、恢复、轮换与事件响应
├── scripts/                  # 验证、审计、E2E 与发行证据工具
└── plans/                    # 设计决策与闭环演进计划

我在找……	从这里开始
产品与交互	产品设计 · UI 设计 · Agentic 设计
API 与领域模型	后端规格 · API 契约 · 领域模型
权限与异步事件	RBAC 矩阵 · 状态机 · 事件契约
部署与运维	生产候选 · 运维手册 · 备份恢复
参与协作	贡献指南 · 行为准则 · 支持范围
发行治理	Release Checklist · 版本策略 · CHANGELOG

发行状态

当前定位：Open-source Release Candidate，尚无正式 v1.0.0 Release。

严格就绪度检查当前为 10/12。自动化工程项已通过，剩余门禁必须由真实授权或受保护环境产生， 不能由代码侧伪造：

门禁	当前状态	完成条件
工程与发布树	通过	OpenAPI、迁移、secret scan、运行源码、Compose 与发布工具受 Git 约束
权利人 / NOTICE	PENDING	权利人确认 Apache-2.0 授权、真实版权主体、最终 NOTICE 与审批证据
前端 bundle / 视觉基线	PENDING	Linux 不可变制品生成、密码学验证、独立审核与受保护环境 promotion
第三方依赖许可	部分待法律结论	对 mysql-connector-python 的 GPLv2 + FOSS exception 作授权结论，或更换依赖
正式发行演练	未完成	外部干净安装、升级/回滚、备份恢复、签名 RC 与正式审批

可在本地复核前两项聚合门禁：

backend/.venv/bin/python scripts/check_platform_readiness.py --release

Warning

仓库包含 Apache License 2.0 标准文本和候选 NOTICE，但在权利主体授权完成前，不应把当前 candidate 描述为“正式开源发布完成”或“已通过生产部署验收”。

进度以 Release Checklist 和 Open-source Release Readiness 为准。

参与贡献

欢迎围绕契约、前后端联调、可观测性、安全、测试和文档提出改进。开始前请阅读 CONTRIBUTING.md，提交前至少运行：

PYTHON="$PWD/backend/.venv/bin/python" bash scripts/verify_fast.sh

English overview

Auris Flow is an evidence-first workspace for audio quality operations. It connects audio assets, transcripts, human review, label versions, evaluations, knowledge retrieval and business insights through tenant-, project- and trace-scoped workflows.

The repository currently represents a v1.0.0 release candidate. Its target production baseline is a single Linux host running Docker Compose with FastAPI, MySQL, Redis, object storage, Qdrant, Dagster, a standards-compatible OIDC provider and an observable edge. It does not claim node-level high availability or a completed public release.

Start with the local quickstart, the API specification, or the production candidate guide.

---

Auris Flow
_{Evidence in. Decisions out. Traceability throughout.}