# Backup Service 实施指导

## 1. 概述

### 1.1 服务定位

`backup-service` 是 RWA Durian 平台的 MPC 备份分片存储服务，负责安全存储用户的 Backup Share (Party 2)。

**核心职责：**
- 安全存储 MPC 2-of-3 的第三个分片 (Backup Share)
- 提供分片的存取 API
- 支持用户账户恢复时的分片验证和获取
- 审计日志记录

### 1.2 安全要求

**关键安全原则：必须部署在与 identity-service 不同的物理服务器上！**

```
┌──────────────────────────────────────────────────────────────────┐
│                    MPC 分片物理隔离架构                           │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  物理服务器 A              物理服务器 B           用户设备        │
│  ┌─────────────────┐      ┌─────────────────┐   ┌────────────┐  │
│  │identity-service │      │ backup-service  │   │Flutter App │  │
│  │Server Share (0) │      │Backup Share (2) │   │Client (1)  │  │
│  └─────────────────┘      └─────────────────┘   └────────────┘  │
│                                                                  │
│  任意单点被攻破，攻击者只能获得 1 个分片，无法重建私钥            │
└──────────────────────────────────────────────────────────────────┘
```

如果 Server Share 和 Backup Share 在同一台物理服务器，攻击者攻破该服务器后可获得 2 个分片，直接重建私钥，**MPC 安全性完全失效**！

### 1.3 技术栈

与 identity-service 保持一致：
- **框架**: NestJS 10.x
- **语言**: TypeScript 5.x
- **数据库**: PostgreSQL 15+ (独立数据库实例)
- **ORM**: Prisma 5.x
- **缓存**: Redis (可选)
- **消息队列**: Kafka (可选，用于接收 identity-service 的事件)

---

## 2. 目录结构

参考 identity-service 的 DDD + Hexagonal 架构：

```
backup-service/
├── prisma/
│   ├── schema.prisma              # 数据库模型
│   └── migrations/                # 数据库迁移
├── src/
│   ├── api/                       # 接口层 (Adapters - Driving)
│   │   ├── controllers/
│   │   │   └── backup-share.controller.ts
│   │   ├── dto/
│   │   │   ├── request/
│   │   │   │   ├── store-share.dto.ts
│   │   │   │   └── retrieve-share.dto.ts
│   │   │   └── response/
│   │   │       └── share-info.dto.ts
│   │   └── api.module.ts
│   │
│   ├── application/               # 应用层 (Use Cases)
│   │   ├── commands/
│   │   │   ├── store-backup-share/
│   │   │   │   ├── store-backup-share.command.ts
│   │   │   │   └── store-backup-share.handler.ts
│   │   │   └── revoke-share/
│   │   │       ├── revoke-share.command.ts
│   │   │       └── revoke-share.handler.ts
│   │   ├── queries/
│   │   │   └── get-backup-share/
│   │   │       ├── get-backup-share.query.ts
│   │   │       └── get-backup-share.handler.ts
│   │   ├── services/
│   │   │   └── backup-share-application.service.ts
│   │   └── application.module.ts
│   │
│   ├── domain/                    # 领域层 (Core Business Logic)
│   │   ├── entities/
│   │   │   └── backup-share.entity.ts
│   │   ├── repositories/
│   │   │   └── backup-share.repository.interface.ts
│   │   ├── services/
│   │   │   └── share-encryption.domain-service.ts
│   │   ├── value-objects/
│   │   │   ├── share-id.vo.ts
│   │   │   └── encrypted-data.vo.ts
│   │   └── domain.module.ts
│   │
│   ├── infrastructure/            # 基础设施层 (Adapters - Driven)
│   │   ├── persistence/
│   │   │   ├── prisma/
│   │   │   │   └── prisma.service.ts
│   │   │   └── repositories/
│   │   │       └── backup-share.repository.impl.ts
│   │   ├── crypto/
│   │   │   └── aes-encryption.service.ts
│   │   └── infrastructure.module.ts
│   │
│   ├── shared/                    # 共享模块
│   │   ├── guards/
│   │   │   └── service-auth.guard.ts  # 服务间认证
│   │   ├── filters/
│   │   │   └── global-exception.filter.ts
│   │   └── interceptors/
│   │       └── audit-log.interceptor.ts
│   │
│   ├── config/
│   │   └── index.ts
│   ├── app.module.ts
│   └── main.ts
│
├── test/
│   ├── unit/
│   └── e2e/
│       └── backup-share.e2e-spec.ts
│
├── .env.example
├── .env.development
├── package.json
├── tsconfig.json
├── nest-cli.json
└── Dockerfile
```

---

## 3. 数据库设计

### 3.1 Prisma Schema

```prisma
// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// 备份分片存储
model BackupShare {
  shareId           BigInt   @id @default(autoincrement()) @map("share_id")

  // 用户标识 (来自 identity-service)
  userId            BigInt   @unique @map("user_id")
  accountSequence   BigInt   @unique @map("account_sequence")

  // MPC 密钥信息
  publicKey         String   @unique @map("public_key") @db.VarChar(130)
  partyIndex        Int      @default(2) @map("party_index")  // Backup = Party 2
  threshold         Int      @default(2)
  totalParties      Int      @default(3) @map("total_parties")

  // 加密的分片数据 (AES-256-GCM 加密)
  encryptedShareData String  @map("encrypted_share_data") @db.Text
  encryptionKeyId    String  @map("encryption_key_id") @db.VarChar(64)  // 密钥轮换支持

  // 状态管理
  status            String   @default("ACTIVE") @db.VarChar(20)  // ACTIVE, REVOKED, ROTATED

  // 访问控制
  accessCount       Int      @default(0) @map("access_count")  // 访问次数限制
  lastAccessedAt    DateTime? @map("last_accessed_at")

  // 时间戳
  createdAt         DateTime @default(now()) @map("created_at")
  updatedAt         DateTime @updatedAt @map("updated_at")
  revokedAt         DateTime? @map("revoked_at")

  // 索引
  @@index([publicKey], name: "idx_backup_public_key")
  @@index([status], name: "idx_backup_status")
  @@index([createdAt], name: "idx_backup_created")
  @@map("backup_shares")
}

// 访问审计日志
model ShareAccessLog {
  logId             BigInt   @id @default(autoincrement()) @map("log_id")

  shareId           BigInt   @map("share_id")
  userId            BigInt   @map("user_id")

  action            String   @db.VarChar(20)  // STORE, RETRIEVE, REVOKE, ROTATE
  sourceService     String   @map("source_service") @db.VarChar(50)  // identity-service, recovery-service
  sourceIp          String   @map("source_ip") @db.VarChar(45)

  success           Boolean  @default(true)
  errorMessage      String?  @map("error_message") @db.Text

  createdAt         DateTime @default(now()) @map("created_at")

  @@index([shareId], name: "idx_log_share")
  @@index([userId], name: "idx_log_user")
  @@index([action], name: "idx_log_action")
  @@index([createdAt], name: "idx_log_created")
  @@map("share_access_logs")
}
```

---

## 4. API 设计

### 4.1 存储备份分片

**POST /backup-share/store**

由 identity-service 在创建账户时调用。

```typescript
// Request DTO
class StoreBackupShareDto {
  @IsNotEmpty()
  userId: string;           // identity-service 的用户ID

  @IsNotEmpty()
  accountSequence: number;  // 账户序列号

  @IsNotEmpty()
  publicKey: string;        // MPC 公钥

  @IsNotEmpty()
  encryptedShareData: string;  // 已加密的分片数据

  @IsOptional()
  threshold?: number;       // 默认 2

  @IsOptional()
  totalParties?: number;    // 默认 3
}

// Response
{
  "success": true,
  "shareId": "123",
  "message": "Backup share stored successfully"
}
```

### 4.2 获取备份分片

**POST /backup-share/retrieve**

用于账户恢复场景，需要额外的身份验证。

```typescript
// Request DTO
class RetrieveBackupShareDto {
  @IsNotEmpty()
  userId: string;

  @IsNotEmpty()
  publicKey: string;

  @IsNotEmpty()
  recoveryToken: string;    // 恢复令牌 (由 identity-service 签发)

  @IsOptional()
  deviceId?: string;        // 新设备ID
}

// Response
{
  "success": true,
  "encryptedShareData": "...",
  "partyIndex": 2,
  "publicKey": "..."
}
```

### 4.3 撤销分片

**POST /backup-share/revoke**

用于密钥轮换或账户注销。

```typescript
// Request DTO
class RevokeShareDto {
  @IsNotEmpty()
  userId: string;

  @IsNotEmpty()
  publicKey: string;

  @IsNotEmpty()
  reason: string;           // ROTATION, ACCOUNT_CLOSED, SECURITY_BREACH
}
```

---

## 5. 服务间认证

### 5.1 认证机制

backup-service 不对外公开，只接受来自内部服务的请求。使用 **服务间 JWT** 或 **mTLS** 进行认证。

```typescript
// src/shared/guards/service-auth.guard.ts

import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as jwt from 'jsonwebtoken';

@Injectable()
export class ServiceAuthGuard implements CanActivate {
  constructor(private configService: ConfigService) {}

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const serviceToken = request.headers['x-service-token'];

    if (!serviceToken) {
      throw new UnauthorizedException('Missing service token');
    }

    try {
      const secret = this.configService.get<string>('SERVICE_JWT_SECRET');
      const payload = jwt.verify(serviceToken, secret) as { service: string };

      // 只允许特定服务访问
      const allowedServices = ['identity-service', 'recovery-service'];
      if (!allowedServices.includes(payload.service)) {
        throw new UnauthorizedException('Service not authorized');
      }

      request.sourceService = payload.service;
      return true;
    } catch (error) {
      throw new UnauthorizedException('Invalid service token');
    }
  }
}
```

### 5.2 identity-service 调用示例

在 identity-service 中添加调用 backup-service 的客户端：

```typescript
// identity-service/src/infrastructure/external/backup/backup-client.service.ts

@Injectable()
export class BackupClientService {
  private readonly backupServiceUrl: string;
  private readonly serviceToken: string;

  constructor(
    private readonly httpService: HttpService,
    private readonly configService: ConfigService,
  ) {
    this.backupServiceUrl = this.configService.get('BACKUP_SERVICE_URL');
    this.serviceToken = this.generateServiceToken();
  }

  async storeBackupShare(params: {
    userId: string;
    accountSequence: number;
    publicKey: string;
    encryptedShareData: string;
  }): Promise<void> {
    await firstValueFrom(
      this.httpService.post(
        `${this.backupServiceUrl}/backup-share/store`,
        params,
        {
          headers: {
            'Content-Type': 'application/json',
            'X-Service-Token': this.serviceToken,
          },
        },
      ),
    );
  }

  private generateServiceToken(): string {
    const secret = this.configService.get<string>('SERVICE_JWT_SECRET');
    return jwt.sign(
      { service: 'identity-service', iat: Math.floor(Date.now() / 1000) },
      secret,
      { expiresIn: '1h' },
    );
  }
}
```

---

## 6. 核心实现

### 6.1 领域实体

```typescript
// src/domain/entities/backup-share.entity.ts

export class BackupShare {
  private constructor(
    private readonly _shareId: bigint | null,
    private readonly _userId: bigint,
    private readonly _accountSequence: bigint,
    private readonly _publicKey: string,
    private readonly _partyIndex: number,
    private readonly _threshold: number,
    private readonly _totalParties: number,
    private _encryptedShareData: string,
    private _encryptionKeyId: string,
    private _status: BackupShareStatus,
    private _accessCount: number,
    private readonly _createdAt: Date,
  ) {}

  static create(params: {
    userId: bigint;
    accountSequence: bigint;
    publicKey: string;
    encryptedShareData: string;
    encryptionKeyId: string;
  }): BackupShare {
    return new BackupShare(
      null,
      params.userId,
      params.accountSequence,
      params.publicKey,
      2, // Backup = Party 2
      2, // threshold
      3, // totalParties
      params.encryptedShareData,
      params.encryptionKeyId,
      BackupShareStatus.ACTIVE,
      0,
      new Date(),
    );
  }

  recordAccess(): void {
    if (this._status !== BackupShareStatus.ACTIVE) {
      throw new DomainError('Cannot access revoked share');
    }
    this._accessCount++;
  }

  revoke(reason: string): void {
    if (this._status === BackupShareStatus.REVOKED) {
      throw new DomainError('Share already revoked');
    }
    this._status = BackupShareStatus.REVOKED;
  }

  rotate(newEncryptedData: string, newKeyId: string): void {
    this._encryptedShareData = newEncryptedData;
    this._encryptionKeyId = newKeyId;
    this._status = BackupShareStatus.ACTIVE;
  }

  // Getters...
  get shareId(): bigint | null { return this._shareId; }
  get userId(): bigint { return this._userId; }
  get publicKey(): string { return this._publicKey; }
  get encryptedShareData(): string { return this._encryptedShareData; }
  get status(): BackupShareStatus { return this._status; }
  get accessCount(): number { return this._accessCount; }
}

export enum BackupShareStatus {
  ACTIVE = 'ACTIVE',
  REVOKED = 'REVOKED',
  ROTATED = 'ROTATED',
}
```

### 6.2 应用服务

```typescript
// src/application/services/backup-share-application.service.ts

@Injectable()
export class BackupShareApplicationService {
  private readonly logger = new Logger(BackupShareApplicationService.name);

  constructor(
    @Inject(BACKUP_SHARE_REPOSITORY)
    private readonly repository: BackupShareRepository,
    private readonly encryptionService: AesEncryptionService,
    private readonly auditService: AuditLogService,
  ) {}

  async storeBackupShare(command: StoreBackupShareCommand): Promise<string> {
    this.logger.log(`Storing backup share for user: ${command.userId}`);

    // 检查是否已存在
    const existing = await this.repository.findByUserId(BigInt(command.userId));
    if (existing) {
      throw new ApplicationError('Backup share already exists for this user');
    }

    // 二次加密 (identity-service 已加密一次，这里再加密一次)
    const { encrypted, keyId } = await this.encryptionService.encrypt(
      command.encryptedShareData,
    );

    // 创建实体
    const share = BackupShare.create({
      userId: BigInt(command.userId),
      accountSequence: BigInt(command.accountSequence),
      publicKey: command.publicKey,
      encryptedShareData: encrypted,
      encryptionKeyId: keyId,
    });

    // 保存
    const saved = await this.repository.save(share);

    // 记录审计日志
    await this.auditService.log({
      shareId: saved.shareId!,
      userId: BigInt(command.userId),
      action: 'STORE',
      sourceService: command.sourceService,
      sourceIp: command.sourceIp,
      success: true,
    });

    this.logger.log(`Backup share stored: shareId=${saved.shareId}`);
    return saved.shareId!.toString();
  }

  async retrieveBackupShare(query: GetBackupShareQuery): Promise<BackupShareDto> {
    this.logger.log(`Retrieving backup share for user: ${query.userId}`);

    const share = await this.repository.findByUserIdAndPublicKey(
      BigInt(query.userId),
      query.publicKey,
    );

    if (!share) {
      throw new ApplicationError('Backup share not found');
    }

    if (share.status !== BackupShareStatus.ACTIVE) {
      throw new ApplicationError('Backup share is not active');
    }

    // 记录访问
    share.recordAccess();
    await this.repository.save(share);

    // 解密
    const decrypted = await this.encryptionService.decrypt(
      share.encryptedShareData,
      share.encryptionKeyId,
    );

    // 记录审计日志
    await this.auditService.log({
      shareId: share.shareId!,
      userId: BigInt(query.userId),
      action: 'RETRIEVE',
      sourceService: query.sourceService,
      sourceIp: query.sourceIp,
      success: true,
    });

    return {
      encryptedShareData: decrypted,
      partyIndex: share.partyIndex,
      publicKey: share.publicKey,
    };
  }
}
```

---

## 7. 环境配置

### 7.1 .env.example

```bash
# Database (必须是独立的数据库实例，不能与 identity-service 共享！)
DATABASE_URL="postgresql://postgres:password@backup-db-server:5432/rwa_backup?schema=public"

# Server
APP_PORT=3002
APP_ENV="development"

# Service Authentication
SERVICE_JWT_SECRET="your-super-secret-service-jwt-key"
ALLOWED_SERVICES="identity-service,recovery-service"

# Encryption (用于二次加密备份分片)
BACKUP_ENCRYPTION_KEY="your-256-bit-encryption-key-in-hex"
BACKUP_ENCRYPTION_KEY_ID="key-v1"

# Rate Limiting
MAX_RETRIEVE_PER_DAY=3        # 每用户每天最多获取 3 次
MAX_STORE_PER_MINUTE=10       # 每分钟最多存储 10 个

# Audit
AUDIT_LOG_RETENTION_DAYS=365  # 审计日志保留 365 天

# Monitoring
PROMETHEUS_ENABLED=true
PROMETHEUS_PORT=9102
```

---

## 8. 部署要求

### 8.1 物理隔离

**强制要求：**

```yaml
# docker-compose.yml (仅供参考架构，生产环境必须分开部署)

# ❌ 错误示例 - 同一台机器
services:
  identity-service:
    ...
  backup-service:  # 不能在这里！
    ...

# ✅ 正确示例 - 分开部署
# 机器 A: docker-compose-main.yml
services:
  identity-service:
    ...

# 机器 B: docker-compose-backup.yml (异地机房)
services:
  backup-service:
    ...
```

### 8.2 网络安全

```yaml
# backup-service 的网络策略
- 只允许来自 identity-service 的入站连接
- 禁止任何公网访问
- 使用 VPN 或专线连接主机房和备份机房
```

### 8.3 数据库安全

```
- 使用独立的 PostgreSQL 实例
- 启用 TLS 加密连接
- 定期备份到第三方存储
- 启用审计日志
```

---

## 9. 测试

### 9.1 E2E 测试

```typescript
// test/e2e/backup-share.e2e-spec.ts

describe('BackupShare (e2e)', () => {
  let app: INestApplication;
  let serviceToken: string;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();

    // 生成测试用的服务令牌
    serviceToken = jwt.sign(
      { service: 'identity-service' },
      process.env.SERVICE_JWT_SECRET,
    );
  });

  describe('POST /backup-share/store', () => {
    it('should store backup share successfully', async () => {
      const response = await request(app.getHttpServer())
        .post('/backup-share/store')
        .set('X-Service-Token', serviceToken)
        .send({
          userId: '12345',
          accountSequence: 1001,
          publicKey: '02' + 'a'.repeat(64),
          encryptedShareData: 'encrypted-share-data-base64',
        })
        .expect(201);

      expect(response.body.success).toBe(true);
      expect(response.body.shareId).toBeDefined();
    });

    it('should reject duplicate share', async () => {
      // First store
      await request(app.getHttpServer())
        .post('/backup-share/store')
        .set('X-Service-Token', serviceToken)
        .send({
          userId: '99999',
          accountSequence: 9999,
          publicKey: '02' + 'b'.repeat(64),
          encryptedShareData: 'data',
        });

      // Duplicate
      await request(app.getHttpServer())
        .post('/backup-share/store')
        .set('X-Service-Token', serviceToken)
        .send({
          userId: '99999',
          accountSequence: 9999,
          publicKey: '02' + 'b'.repeat(64),
          encryptedShareData: 'data',
        })
        .expect(400);
    });

    it('should reject unauthorized service', async () => {
      await request(app.getHttpServer())
        .post('/backup-share/store')
        .set('X-Service-Token', 'invalid-token')
        .send({})
        .expect(401);
    });
  });

  describe('POST /backup-share/retrieve', () => {
    it('should retrieve backup share with valid recovery token', async () => {
      // Setup: store a share first
      const storeResponse = await request(app.getHttpServer())
        .post('/backup-share/store')
        .set('X-Service-Token', serviceToken)
        .send({
          userId: '77777',
          accountSequence: 7777,
          publicKey: '02' + 'c'.repeat(64),
          encryptedShareData: 'test-encrypted-data',
        });

      // Retrieve
      const response = await request(app.getHttpServer())
        .post('/backup-share/retrieve')
        .set('X-Service-Token', serviceToken)
        .send({
          userId: '77777',
          publicKey: '02' + 'c'.repeat(64),
          recoveryToken: 'valid-recovery-token',
        })
        .expect(200);

      expect(response.body.encryptedShareData).toBeDefined();
      expect(response.body.partyIndex).toBe(2);
    });
  });
});
```

---

## 10. 与 identity-service 的集成

### 10.1 修改 identity-service

在 identity-service 的 `autoCreateAccount` 中添加调用 backup-service：

```typescript
// identity-service/src/application/services/user-application.service.ts

// 在保存服务端分片后，调用 backup-service 存储备份分片
await this.mpcKeyShareRepository.saveServerShare({...});

// 新增: 调用 backup-service 存储备份分片
if (mpcResult.backupShareData) {
  try {
    await this.backupClient.storeBackupShare({
      userId: account.userId.toString(),
      accountSequence: account.accountSequence.value,
      publicKey: mpcResult.publicKey,
      encryptedShareData: mpcResult.backupShareData,
    });
    this.logger.log(`Backup share stored to backup-service for user: ${account.userId}`);
  } catch (error) {
    this.logger.error(`Failed to store backup share: ${error.message}`);
    // 根据业务需求决定是否回滚或继续
    // 建议: 记录失败，后续通过补偿任务重试
  }
}
```

### 10.2 配置更新

在 identity-service 的 `.env` 中添加：

```bash
# Backup Service
BACKUP_SERVICE_URL="http://backup-server:3002"
SERVICE_JWT_SECRET="your-super-secret-service-jwt-key"
```

---

## 11. 监控和告警

### 11.1 关键指标

```
- backup_share_store_total          # 存储总数
- backup_share_retrieve_total       # 获取总数
- backup_share_revoke_total         # 撤销总数
- backup_share_store_latency_ms     # 存储延迟
- backup_share_retrieve_latency_ms  # 获取延迟
- backup_share_error_total          # 错误总数
```

### 11.2 告警规则

```yaml
# 异常访问告警
- alert: HighBackupShareRetrieveRate
  expr: rate(backup_share_retrieve_total[5m]) > 10
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Backup share retrieve rate is high"

# 服务不可用告警
- alert: BackupServiceDown
  expr: up{job="backup-service"} == 0
  for: 1m
  labels:
    severity: critical
```

---

## 12. 开发步骤

### 12.1 初始化项目

```bash
# 1. 创建 NestJS 项目
cd backend/services/backup-service
npx @nestjs/cli new . --skip-git

# 2. 安装依赖
npm install @nestjs/config @prisma/client class-validator class-transformer
npm install -D prisma

# 3. 初始化 Prisma
npx prisma init

# 4. 复制 schema 并生成客户端
npx prisma generate
npx prisma migrate dev --name init
```

### 12.2 开发顺序

1. **基础设施层** - Prisma 配置、数据库连接
2. **领域层** - BackupShare 实体、Repository 接口
3. **应用层** - 存储/获取/撤销命令处理
4. **接口层** - REST API Controller
5. **安全层** - ServiceAuthGuard、审计日志
6. **测试** - 单元测试、E2E 测试

---

## 13. 检查清单

开发完成后，确保以下事项：

- [ ] 数据库部署在独立服务器
- [ ] 服务间认证已实现
- [ ] 分片数据已二次加密
- [ ] 审计日志已启用
- [ ] 访问频率限制已实现
- [ ] E2E 测试通过
- [ ] 与 identity-service 集成测试通过
- [ ] 监控指标已配置
- [ ] 告警规则已配置
- [ ] 生产环境部署在异地机房