br-acc技术架构深度解析：从公开数据源到Neo4j、FastAPI与React的完整数据流

br-acc（World Transparency Graph）是一个开源的图数据库基础设施项目，它将巴西数十个政府公开数据源——公司登记、选举数据、政府采购、财政审计等——统一清洗后加载进 Neo4j 图数据库，再通过 FastAPI 后端和 React 前端，让任何人都能搜索企业、探索关联网络。这篇文章带你完整走一遍它的技术架构与数据流。

一、整体架构：一张图看懂 br-acc 的数据流

br-acc 的架构可以概括为一条单向数据流水线，共 5 个环节：

公开数据源 → ETL 管道 → Neo4j 图数据库 → FastAPI 后端 → React 前端 / 公共 API

官方架构速览见 README.md。

二、第一站：ETL 管道如何吞下公开数据源 📥

1. 45+ 条管道，统一抽象

所有 ETL 逻辑位于 etl/src/bracc_etl/ 目录。每条数据源对应一个管道模块（如 CNPJ 公司注册、TSE 选举、ComprasNet 政府采购），共 40 多条，全部继承同一个抽象基类 Pipeline：

• extract()—— 从政府门户下载原始数据
• transform()—— 规范化、去重、脱敏
• load()—— 批量写入 Neo4j（默认每批 5 万行）

这种设计的好处是：新增一个数据源，只需写一个管道类，下载脚本与加载逻辑即可复用。

2. 每次运行都可审计 🔍

Pipeline.run() 在执行前后会在图里写入一条IngestionRun节点，记录状态（running / loaded / quality_fail）、行数与错误信息——每一次数据加载都有据可查。

3. 数据源全景

完整的数据源清单与节点规模统计表在 docs/data-sources.md，例如：

三、第二站：Neo4j 图数据库层 🕸️

Neo4j 是整个系统的数据中枢。生产快照约为1.41 亿节点、9200 万关系，覆盖 35 种节点标签与 33 种关系类型（docs/data-sources.md）。

关键基础设施文件：

• 容器编排：infra/docker-compose.yml 配置了 Neo4j 5 容器、APoC 插件与 3G 页缓存内存
• 初始化脚本：infra/neo4j/init.cypher
• 开发种子数据：infra/scripts/seed-dev.sh 可加载确定性演示图
• 演示数据集：data/demo/synthetic_graph.json

图的价值在于"连接"：一家公司（Company）可以通过SOCIO_DE（股东）关联到个人，通过VENCEU（中标）关联到政府采购合同，通过SANCIONADA（被处罚）关联到 TCU 审计处罚——单看任何一张表都发现不了的关联，在图里一查即现。

四、第三站：FastAPI 后端 API 🔌

1. 应用组装与中间件

后端入口是 api/src/bracc/main.py，启动时依次组装了：

启动生命周期 还会做两件"安全门禁"：拒绝弱 JWT 密钥和拒绝 Neo4j 默认密码，生产环境配置不达标会直接抛错退出。

2. 查询即文件：Cypher 与代码分离 📄

一个很优雅的设计——所有 Cypher 查询不以字符串散落在 Python 代码里，而是独立存放在 api/src/bracc/queries/ 目录，如 search.cypher、entity_connections.cypher。服务层通过 CypherLoader 按需加载并缓存，再由 execute_query() 带参执行。修改查询逻辑无需碰 Python 代码。

3. 公共模式守卫（隐私优先）🛡️

br-acc 的核心原则是"只呈现事实，不做指控"。public_guard.py 实现了公共模式策略：

• Person类节点在公共部署中默认隐藏
• cpf、doc_raw等敏感属性在返回前被剥离
• 内部标签（User / Investigation 等）仅限登录用户访问

配套的合规文档见 docs/legal/public-compliance-pack.md。

4. 主要 API 端点

完整文档在本地启动后访问http://localhost:8000/docs查看。

五、第四站：React 前端 🖥️

前端位于 frontend/，技术栈为Vite + React 19 + TypeScript，页面通过 App.tsx 组织路由。核心页面：

• Search（Search.tsx）—— 全局实体搜索
• GraphExplorer（GraphExplorer.tsx）—— 交互式关系网络画布
• EntityAnalysis（EntityAnalysis.tsx）—— 实体关联与时间线分析
• Patterns（Patterns.tsx）—— 公开风险模式卡片
• Investigations（Investigations.tsx）—— 标注与调查工作区（需登录）

前端状态用 Zustand 管理（frontend/src/stores/），API 调用统一走 api/client.ts。生产部署时由 frontend/nginx.conf 做静态托管并反代 API。

六、端到端数据流：一次查询是怎么发生的 ⚡

把四层串起来，一个典型请求的生命周期如下：

1. 数据入库：bracc-etl run --source cnpj之类的命令触发管道，runner.py 中注册了全部 40 余条管道的映射表
2. 图存储：清洗后的节点与关系写入 Neo4j，IngestionRun记录留痕
3. API 查询：用户请求GET /api/v1/public/graph/company/XXX，FastAPI 路由加载对应.cypher文件执行
4. 隐私过滤：public_guard剥离敏感属性，中间件掩码 CPF
5. 前端渲染：React 图谱画布把返回的节点/关系渲染为可交互网络

七、本地快速启动（可选上手）🚀

cp .env.example .env docker compose up -d --build bash infra/scripts/seed-dev.sh

启动后验证地址：

• API 健康检查：http://localhost:8000/health
• 前端：http://localhost:3000
• Neo4j Browser：http://localhost:7474

如需运行全量历史数据编排（耗时数小时，注意磁盘与带宽），可参考 docs/bootstrap_all.md 与make bootstrap-all（Makefile）。

八、总结：br-acc 架构的三个亮点 ✨

1. 管道化 ETL：45+ 数据源共享同一套 extract → transform → load 抽象，新增源成本极低
2. 查询与代码分离：Cypher 文件化 + 缓存加载，图查询可独立演进与审计
3. 隐私优先的公共守卫：从中间件脱敏到节点级策略，默认"公共安全"，合规文档齐全

无论你是想了解图数据库在真实公开数据场景中的落地，还是想学习 FastAPI + Neo4j + React 的三层协作模式，br-acc 的代码组织（api/ · etl/ · frontend/ · infra/）都值得一读。