pfenerty/ocidex
GitHub: pfenerty/ocidex
OCIDex 是一个软件供应链元数据目录，通过摄取 CycloneDX SBOM 为您提供全组合范围内可搜索的组件、版本和许可证清单，并支持版本间变更追踪。
Stars: 1 | Forks: 0
# OCIDex
**软件供应链的元数据目录。**
OCIDex 会摄取 [CycloneDX](https://cyclonedx.org/) SBOM，将它们与其描述的软件构件关联起来，并为您提供一个涵盖整个组合的组件、版本和许可证的可搜索清单——附带精确展示各版本间变更内容的更新日志。
## 功能特性
- **SBOM 摄取** — POST 一个 CycloneDX JSON 文档，OCIDex 会对其进行验证、解析，并存储完整的组件和依赖图数据。
- **构件追踪** — SBOM 按构件（容器镜像、库、应用程序）分组。可浏览任何构件的完整版本历史。
- **更新日志** — 精确查看某个构件的任意两个 SBOM 之间添加、删除或更改了哪些组件。
- **SBOM 差异比对** — 选择任意构件中的任意两个 SBOM，并进行并排比较。
- **组件搜索** — 在所有已摄取的 SBOM 中按名称、组或类型查找任何包。查看哪些构件使用了它以及存在多少个版本。
- **许可证清单** — 在一个地方集中展示在您的 SBOM 中发现的所有许可证，将其分类为宽松、弱 Copyleft 或 Copyleft，并提供按构件分类的摘要。
- **数据富集流水线** — 摄取后，后台 worker 会使用额外数据富集 SBOM。内置的 OCI 元数据富集器可直接从容器镜像仓库拉取镜像标签、架构和构建信息。
- **OpenAPI 文档** — API 规范在启动时通过 [huma](https://huma.rocks/) 从代码生成。可在 `/docs` 浏览。
## 快速开始
### 使用 Docker Compose
获取包含初始数据的运行实例的最快方法：
```
git clone https://github.com/pfenerty/ocidex.git
cd ocidex
docker compose up -d
```
这会启动 PostgreSQL、OCIDex API 服务器（端口 8080）和 Web 前端（端口 3000）。
要使用公共容器镜像中的真实 SBOM 填充数据：
```
# 需要 oras、syft 和 curl — 在 Flox 开发环境中可用
flox activate -- ./scripts/seed.sh
```
然后打开 [http://localhost:3000](http://localhost:3000)。
### 从源码构建
OCIDex 使用 [Flox](https://flox.dev/) 管理其开发环境（Go、Node、npm、oras、syft 和其他工具）。
```
git clone https://github.com/pfenerty/ocidex.git
cd ocidex
flox activate
# 安装 Go 工具 (sqlc, golangci-lint)
make init
# 启动 PostgreSQL (通过 docker-compose，或提供您自己的)
docker compose up -d postgres
# 配置
cp .env.example .env # edit DATABASE_URL if needed
# 运行 migrations 并构建
make migrate-up
make build
make frontend
# 启动服务器
./bin/ocidex
```
API 默认在 `:8080` 上提供服务。要进行带有热重载的前端开发：
```
make frontend-dev # Vite dev server on :3000, proxies /api/* to :8080
```
### 摄取您的第一个 SBOM
使用 [syft](https://github.com/anchore/syft) 生成 SBOM 并将其发送到 OCIDex：
```
syft registry:docker.io/library/nginx:latest -o cyclonedx-json | \
curl -X POST http://localhost:8080/api/v1/sbom \
-H "Content-Type: application/json" \
-d @-
```
## 技术栈
| 层级 | 技术 |
|-------|-----------|
| 语言 | Go |
| HTTP | [chi](https://github.com/go-chi/chi) + [huma](https://huma.rocks/) (代码优先的 OpenAPI 3.1) |
| 数据库 | PostgreSQL ([pgx](https://github.com/jackc/pgx) 驱动, [sqlc](https://sqlc.dev/) 查询生成, [goose](https://pressly.github.io/goose/) 迁移) |
| 前端 | [SolidJS](https://www.solidjs.com/) + [TanStack Query](https://tanstack.com/query) + [Tailwind CSS](https://tailwindcss.com/) |
| API 客户端 | [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) 及生成的 TypeScript 类型 |
| 测试 | [matryer/is](https://github.com/matryer/is) (单元测试), [testcontainers-go](https://golang.testcontainers.org/) (集成测试) |
| 容器 | Docker 多阶段构建 (Alpine) |
| 开发环境 | [Flox](https://flox.dev/) |
## 项目结构
```
cmd/ocidex/ Entry point, server wiring, graceful shutdown
internal/api/ HTTP handlers and routing (chi + huma)
internal/service/ Business logic interfaces and implementations
internal/repository/ Data access layer (sqlc-generated queries)
internal/enrichment/ Post-ingestion enrichment pipeline
internal/config/ Environment-based configuration
db/migrations/ SQL schema migrations (goose)
db/queries/ SQL query definitions (sqlc source of truth)
web/ SolidJS frontend (Vite + Tailwind)
tests/ Integration tests (testcontainers)
docs/ Architecture docs, ADRs, development guide
```
## API 概览
所有端点均在 `/api/v1` 下。完整的 OpenAPI 规范在 `/openapi.json` 提供，交互式文档 UI 在 `/docs` 提供。
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/v1/sbom` | 摄取 CycloneDX JSON SBOM |
| `GET` | `/api/v1/sbom` | 列出 SBOM（分页、可过滤） |
| `GET` | `/api/v1/sbom/{id}` | 获取 SBOM 详情 |
| `GET` | `/api/v1/sbom/{id}/components` | 列出 SBOM 中的组件 |
| `GET` | `/api/v1/sbom/{id}/dependencies` | 获取依赖图 |
| `GET` | `/api/v1/artifacts` | 列出已追踪的构件 |
| `GET` | `/api/v1/artifacts/{id}` | 获取构件详情 |
| `GET` | `/api/v1/artifacts/{id}/sboms` | 列出某个构件的 SBOM |
| `GET` | `/api/v1/artifacts/{id}/changelog` | 获取 SBOM 之间的更新日志 |
| `GET` | `/api/v1/artifacts/{id}/license-summary` | 最新 SBOM 的许可证明细 |
| `GET` | `/api/v1/components` | 搜索组件 |
| `GET` | `/api/v1/components/distinct` | 去重后的组件搜索 |
| `GET` | `/api/v1/licenses` | 列出所有许可证 |
| `GET` | `/api/v1/diff` | 比较任意两个 SBOM |
错误遵循 [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) 问题详情格式。
## 配置
OCIDex 通过环境变量进行配置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `PORT` | `8080` | HTTP 监听端口 |
| `DATABASE_URL` | — | PostgreSQL 连接字符串（必填） |
| `LOG_LEVEL` | `info` | 日志级别 (`debug`, `info`, `warn`, `error`) |
| `ENVIRONMENT` | `development` | 运行环境 |
| `CORS_ALLOWED_ORIGINS` | — | 逗号分隔的允许来源 |
| `ENRICHMENT_ENABLED` | `false` | 启用摄取后的数据富集流水线 |
| `ENRICHMENT_WORKERS` | `2` | 数据富集 worker goroutine 数量 |
| `ENRICHMENT_QUEUE_SIZE` | `100` | 数据富集请求队列容量 |
| `OCIDEX_MODE` | `embedded` | 部署模式：`embedded`（进程内）或 `distributed`（NATS worker） |
| `NATS_URL` | `nats://localhost:4222` | NATS 服务器 URL |
| `NATS_STREAM_NAME` | `ocidex` | JetStream 流名称 |
| `NATS_EVENT_TTL_HOURS` | `24` | 事件保留期（小时） |
| `SCANNER_ENABLED` | `false` | 启用通过 Zot webhook 实现的 OCI 镜像仓库自动扫描 |
| `ZOT_REGISTRY_ADDR` | `zot:5000` | Zot 镜像仓库地址（主机:端口） |
| `ZOT_WEBHOOK_SECRET` | — | Zot 随推送通知发送的 Bearer token |
| `SYFT_PATH` | `/usr/local/bin/syft` | syft 二进制文件的路径 |
| `SCANNER_WORKERS` | `2` | 扫描器 worker goroutine 数量 |
| `SCANNER_QUEUE_SIZE` | `50` | 扫描器请求队列容量 |
## 文档
| 文档 | 描述 |
|----------|-------------|
| [架构](docs/ARCHITECTURE.md) | 系统设计、数据模型和组件概述 |
| [开发指南](docs/DEVELOPMENT.md) | 编码模式、测试策略和技术栈示例 |
| [架构决策记录](docs/adr/) | 17 份记录每一项重大技术选择的 ADR |
| [AI 使用说明](docs/AI.md) | 关于 AI 在开发中作用的透明说明 |
## AI 致谢
本项目在显著的 AI 辅助下构建。架构决策、技术选择和代码审查由人工主导；实现、重构和文档编写为协作完成。详情请参阅 [AI 使用说明](docs/AI.md)。
## 许可证
[MIT](LICENSE)
标签：CycloneDX, EVTX分析, GPT, OCI标准, SBOM管理, 代码对比, 供应链合规, 依赖图分析, 变更日志, 容器镜像扫描, 开源许可证管理, 日志审计, 测试用例, 漏洞管理, 物料清单, 组件追踪, 请求拦截, 软件供应链安全, 软件资产管理, 远程方法调用