RecordPlatform

Enterprise-grade file attestation platform powered by blockchain and distributed storage

中文文档 · Documentation · API Reference

---

What is RecordPlatform?

RecordPlatform is an open-source, enterprise-grade file attestation platform that combines blockchain immutability with fault-domain-aware distributed storage. Upload files, have their metadata recorded on-chain via FISCO BCOS, and share them securely — with cryptographic proof of origin, integrity, and full access audit.

Built for teams that need:

• 📜 Auditable provenance — every upload, share, and download tracked and verifiable on-chain
• 🏢 Multi-tenant isolation — separate storage, cache, and data paths per tenant
• 🔒 End-to-end encryption — AES-GCM/ChaCha20-Poly1305 with per-chunk key chains
• ✅ Independent public verification — signed proof ZIP v2 SDK, CLI, and standalone Web verifier with live status/chain checks

---

✨ Features

🔐 Attestation & Security Blockchain Attestation — file metadata stored on FISCO BCOS, immutable and traceable File Encryption — AES-GCM / ChaCha20-Poly1305, per-chunk independent key chains RBAC + Ownership — fine-grained resource-level access control ID Obfuscation — AES-256-CTR external↔internal ID mapping

📦 Storage & Transfer Distributed Storage — 1~N active fault domains, quorum writes, N-1 fault tolerance, auto-promotion from standby Chunked Upload — resumable, concurrent, dynamic chunk sizing Bounded Download — File System Access + Streams for files over the 64 MiB memory fallback ceiling; transactional abort on failure File Version Chain — track history, derive new versions from existing files

👥 Collaboration & Sharing File Sharing — generate share codes with access limits and expiry; the current model has no share-password field Share Audit & Provenance — multi-level chain tracking (A→B→C), full access logs Friend System — direct file sharing with friends, real-time SSE notifications Support Tickets — built-in ticket system with categories, priorities, admin management

📊 Governance & Observability Quota Governance — per-user and per-tenant limits, SHADOW/ENFORCE modes, gradual rollout Real-time Notifications — SSE push for file attestation, tickets, friend events, announcements Storage Capacity API — cluster/domain/node capacity aggregates with degraded+source semantics Multi-tenancy — DB, cache, and storage path isolation per tenant Storage Integrity Check — scheduled verification of S3 files against blockchain records Distributed Tracing — OpenTelemetry auto-instrumentation with Jaeger visualization SLO/SLI Observability — Prometheus recording rules, burn-rate alerting, Grafana SLO dashboard

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────────┐
│                       Infrastructure                            │
│     Nacos  MySQL  RabbitMQ  Redis  S3 Cluster  OTel  Jaeger     │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              │         platform-api          │
              │    (Shared Dubbo Interfaces)  │
              └───────────────┬───────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    │                    ▼
┌─────────────────┐           │           ┌─────────────────┐
│ platform-fisco  │           │           │ platform-storage│
│ Blockchain Svc  │           │           │ Storage Service │
│ (Port 8091)     │           │           │ (Port 8092)     │
└────────┬────────┘           │           └────────┬────────┘
         │         Dubbo RPC  │  Dubbo RPC         │
         │                    ▼                    │
         │          ┌─────────────────┐            │
         │          │ platform-backend│            │
         │          │ REST API :8000  │            │
         │          └─────────────────┘            │
         │                                         │
         ▼                                         ▼
  ┌─────────────┐                        ┌────────────────┐
  │ FISCO BCOS  │                        │   S3 Cluster   │
  │    Node     │                        │ (MinIO / S3)   │
  └─────────────┘                        └────────────────┘

For detailed architecture with Mermaid diagrams and data flow sequences, see Architecture Guide

---

⚡ Quick Start

1. Prerequisites

Ensure the following services are running before starting:

Service	Port	Purpose
Nacos	8848	Service discovery & config
MySQL	3306	Database
Redis	6379	Cache & distributed locks
RabbitMQ	5672	Message queue
S3-compatible storage	9000	Object storage
FISCO BCOS	20200	Blockchain node
OTel Collector	4317	Trace & metrics pipeline
Jaeger	16686	Tracing UI

Start infrastructure with Docker Compose:

docker compose -f docker-compose.infra.yml up -d

Copy .env.example to .env and configure JWT_KEY, S3_*, and FISCO_* before starting services:

cp .env.example .env
# Edit .env before continuing.
set -a
source .env
set +a

2. Build

# Install shared interfaces (required first)
mvn -f platform-api/pom.xml clean install

# Build and test the independent public verifier
mvn -f platform-verifier/pom.xml clean install

# Build all backend services
mvn -f platform-backend/pom.xml clean package -DskipTests
mvn -f platform-fisco/pom.xml clean package -DskipTests
mvn -f platform-storage/pom.xml clean package -DskipTests

3. Run

# Start in order: providers before consumer
java -jar "$(ls platform-storage/target/platform-storage-*.jar)" --spring.profiles.active=local
java -jar "$(ls platform-fisco/target/platform-fisco-*.jar)" --spring.profiles.active=local
java -jar "$(ls platform-backend/backend-web/target/backend-web-*.jar)" --spring.profiles.active=local

# Frontend dev server
cd platform-frontend && pnpm install && pnpm dev

Or use the unified start script:

./scripts/start.sh start all

Verify the installation at:

• Swagger UI: http://localhost:8000/record-platform/swagger-ui.html
• Health check: http://localhost:8000/record-platform/actuator/health
• Frontend: http://localhost:5173

Note: The /record-platform context path is only active under the prod profile. With --spring.profiles.active=local (as shown above), the URLs are http://localhost:8080/swagger-ui.html and http://localhost:8080/actuator/health (port and context path depend on profile and SERVER_PORT configuration).

For detailed setup, see Getting Started Guide

---

🧱 Tech Stack

Category	Technology	Version
Backend	Java + Spring Boot + Virtual Threads	21, 3.5.16
Microservices	Apache Dubbo (Triple protocol), Nacos	3.3.6
Blockchain	FISCO BCOS, Solidity	3.8.0, ^0.8.11
Storage	S3-compatible (AWS SDK v2), MySQL, Redis (Redisson)	2.x, 8.0+, 7.0+
Frontend	Svelte 5 (Runes), SvelteKit, Vite, Tailwind CSS 4, bits-ui	5.55+, 2.59+, 7.3+, 4.3+
Resilience	Resilience4j (circuit breaker, retry)	2.4.0
Monitoring	Micrometer, Prometheus, OpenTelemetry, Jaeger	—
Testing	JUnit 5, Mockito, Testcontainers, Vitest	—

---

📚 Documentation

Guide	Description
Getting Started	Prerequisites, installation, configuration
Public Verifier	Verify signed proof ZIPs through SDK, CLI, or standalone Web service
Architecture	System overview, distributed storage, blockchain, security
P0/P1/P2/P3 Delivery Evidence	Implementation, automated-test, exact-main CI, and residual-risk matrix
Chunk Manifest	Canonical chunk evidence, historical classification, and reference-safe cleanup
Deployment	Docker Compose, production setup, monitoring
API Reference	REST endpoints, authentication, error codes
Development	Contributing, local dev, testing strategy
Troubleshooting	Common issues and solutions

---

🗂 Project Structure

RecordPlatform/
├── platform-api/          # Shared Dubbo interface definitions
├── platform-verifier/     # Public proof SDK, CLI, and standalone Web verifier (:8093)
├── platform-backend/      # REST API service (Dubbo Consumer, :8000)
│   ├── backend-web/       # Controllers, JWT filters, rate limiting
│   ├── backend-service/   # Business logic, Saga orchestration, Outbox
│   ├── backend-dao/       # MyBatis Plus mappers and entities
│   ├── backend-api/       # Internal interface definitions
│   └── backend-common/    # Shared utilities and constants
├── platform-fisco/        # Blockchain service (Dubbo Provider, :8091)
├── platform-storage/      # Storage service (Dubbo Provider, :8092)
├── platform-frontend/     # Svelte 5 + SvelteKit frontend
├── scripts/               # Start/stop scripts, env-check
├── tools/                 # k6 load tests, security PoC, doc consistency
├── docs/                  # VitePress documentation site (en/zh)
└── docker-compose.infra.yml  # Infrastructure services (Nacos, MySQL, Redis, RabbitMQ, MinIO)

---

🛠 Contributing

We welcome contributions! Please read the Contributing Guide before getting started.

# 1. Fork and clone the repository
git clone https://github.com/<your-fork>/RecordPlatform.git

# 2. Create a feature branch
git checkout -b feat/your-feature

# 3. Make changes, run tests
mvn -f platform-backend/pom.xml test

# 4. Open a Pull Request against main

Branch naming: feat/, fix/, refactor/, docs/, chore/

All PRs must pass CI gates: backend tests, frontend tests, contract consistency check, and build verification. See CI Gates for details.

---

📄 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.