nyaKazuha/BlueArchiveToolkit

Fork 0

mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-07-22 07:06:43 +08:00

Files

T

nyaKazuha b2d6871926 fix: harden official resource sync retries

2026-07-07 01:14:54 +08:00

10 KiB

Raw Blame History

BlueArchive Toolkit 架构设计

概述

BlueArchive Toolkit 采用 Monorepo + 多语言混合 架构，旨在构建一个可持续维护十年以上的工业级开源项目。

当前文档描述目标架构和已经落地的关键边界。实际实现状态以根目录 CURRENT_STATUS.md 和 PROJECT_PLAN.md 为准。

当前已经可用的官方资源入口包括：

infrastructure/src/bin/bat_official_sync.rs：Linux 官方资源同步正式入口，支持 one-shot 和 --watch 常驻更新。
infrastructure/src/official_update.rs：官方自动更新核心服务，负责 auto-discover、snapshot、marker diff、本地 audit/repair。
infrastructure/examples/official_pull_plan.rs：开发/审计用 pull plan 入口。
infrastructure/examples/official_update_check.rs：历史/开发入口，生产优先使用 bat-official-sync。
infrastructure/examples/official_launcher_bootstrap.rs：显式开发/审计辅助路径，用于核查官方 launcher metadata，不是生产运行依赖。
docs/guides/official-resource-test-pull.md

已接受的架构决策：

adr/0001-engine-and-application-boundaries.md：Rust 引擎与 Go 应用层边界。
adr/0002-cas-v1-design-boundary.md：CAS V1 设计边界。
adr/0003-cas-core-interface-and-error-boundary.md：CAS 核心接口与错误边界冻结。

设计原则

1. 模块化与解耦

高内聚、低耦合：每个模块职责明确，依赖关系清晰
接口优先：通过接口定义模块边界，支持多种实现
插件化：核心功能稳定，扩展功能通过插件实现

2. 语言选型

模块	语言	理由
CLI、API Server、服务编排	Go	并发模型优秀、部署简单、生态成熟
官方资源同步核心、AssetBundle 解析、Patch 引擎、CAS 引擎	Rust	零成本抽象、内存安全、性能和二进制处理更可靠
Web 管理后台	Vue 3 + TypeScript	渐进式、类型安全、生态完善

3. 数据流设计

用户请求 → CLI/API → Go 业务层 → Rust 核心/同步层 → CAS 存储 → 数据库
         ↓                    ↓
      Web UI              缓存层 (Redis)

核心模块

1. CAS 存储引擎 (Rust)

职责：内容寻址存储，实现去重、引用计数、垃圾回收

接口：

pub trait Storage {
    fn put(&self, data: &[u8]) -> Result<Hash>;
    fn get(&self, hash: &Hash) -> Result<Vec<u8>>;
    fn exists(&self, hash: &Hash) -> bool;
    fn delete(&self, hash: &Hash) -> Result<()>;
}

pub trait RefCounter {
    fn incr(&self, hash: &Hash) -> Result<u64>;
    fn decr(&self, hash: &Hash) -> Result<u64>;
    fn get_count(&self, hash: &Hash) -> Result<u64>;
}

存储结构：

cas/
├── objects/
│   ├── ab/
│   │   └── cdef1234... (内容)
│   └── cd/
│       └── ef567890...
├── refs.db (SQLite: 引用计数)
└── metadata.db (元数据)

特性：

基于 BLAKE3 的快速 Hash 计算
使用 SQLite 管理引用计数和元数据
支持并发读写（通过文件锁）
自动垃圾回收（引用计数为 0 的对象）

2. 官方资源同步器 (Rust 当前实现，Go 后续编排)

职责：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。

当前实现：

OfficialUpdateService：auto-discover、snapshot、marker diff、本地 manifest audit/repair。
OfficialResourcePullService：官方 URL 校验、.part 断点续传、重试、下载 manifest、官方 seed .hash 校验。
bat-official-sync：正式 binary，支持 one-shot 和 --watch。

当前数据流：

官方 metadata → GameMainConfig → server-info → discovery endpoints
     ↓
seed catalog → inventory → pull plan → downloader → output directory
     ↓
official-sync-snapshot.json + official-download-manifest.json

已具备特性：

不安装、不执行官方 launcher。
默认平台 Windows + Android。
--auto-discover 自动获取 app-version、connection-group 和 server-info。
--watch 常驻检查，正常检查默认 1 小时，失败重试默认 60 秒。
远端 marker 无变化且本地 manifest clean 时不下载。
本地文件损坏时 repair。
官方 seed .hash 强校验；Addressables catalog_*.hash 作为变更 marker。

后续 Go 职责：

提供最小稳定 CLI。
包装或调用 Rust 同步入口，转发 JSON report。
编排 API Server、任务队列、Provider 和用户配置。

3. AssetBundle 解析器 (Rust)

职责：解析 Unity AssetBundle，提取资源

插件化架构：

pub trait AssetParser {
    fn name(&self) -> &str;
    fn supported_types(&self) -> Vec<AssetType>;
    fn parse(&self, bundle: &AssetBundle) -> Result<Vec<Asset>>;
}

// 插件注册
pub struct ParserRegistry {
    parsers: HashMap<AssetType, Box<dyn AssetParser>>,
}

内置解析器：

TextAsset Parser
Localization Parser
MonoBehaviour Parser
ScriptableObject Parser

扩展机制：

动态加载 .so/.dll 插件
通过配置文件注册自定义解析器

4. 翻译系统 (Go)

架构：

Text Extractor → Translation Memory (查询) → AI Provider → Glossary (术语替换) → Output
                       ↓                          ↓
                   PostgreSQL                  审核队列

Provider 抽象：

type TranslationProvider interface {
    Name() string
    Translate(ctx context.Context, req *TranslateRequest) (*TranslateResponse, error)
    SupportedLanguages() []Language
}

实现：

DeepL Provider
OpenAI Provider
Anthropic Provider
Google Translate Provider
Azure Translator Provider

翻译记忆库：

精确匹配：100% 匹配直接使用
模糊匹配：使用相似度算法（Levenshtein Distance）
上下文匹配：根据前后文提高匹配准确度

5. Patch 引擎 (Rust)

职责：生成和应用补丁

支持的 Patch 类型：

Binary Patch：使用 bsdiff 算法
JSON Patch：RFC 6902 标准
Text Patch：基于 diff 算法

Patch 结构：

patch/
├── metadata.json (版本信息、文件列表)
├── binary/
│   ├── file1.bpatch
│   └── file2.bpatch
└── json/
    └── config.jpatch

特性：

增量更新（只传输差异）
完整性校验（Hash 验证）
回滚支持（保留历史版本）
压缩传输（gzip/zstd）

6. API Server (Go)

框架：Gin 或 Echo

架构：

HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Repository → Database
                    ↓
                 Cache (Redis)

API 设计原则：

RESTful 风格
版本控制（/api/v1/...）
统一错误码
统一响应结构
OpenAPI 文档自动生成

核心 API：

/api/v1/translations - 翻译管理
/api/v1/glossary - 术语管理
/api/v1/sync - 资源同步
/api/v1/patches - 补丁管理
/api/v1/assets - 资源查询

7. Web 后台 (Vue 3)

技术栈：

Vue 3 + Composition API
TypeScript
Pinia (状态管理)
Vue Router
Axios
Element Plus / Ant Design Vue

模块：

Dashboard（统计概览）
翻译审核（Translation Review）
术语管理（Glossary Manager）
资源浏览（Asset Browser）
用户管理（User Management）

数据库设计

PostgreSQL Schema

-- 翻译记忆库
CREATE TABLE translation_memory (
    id BIGSERIAL PRIMARY KEY,
    source_text TEXT NOT NULL,
    target_text TEXT NOT NULL,
    source_lang VARCHAR(10) NOT NULL,
    target_lang VARCHAR(10) NOT NULL,
    provider VARCHAR(50),
    status VARCHAR(20) DEFAULT 'pending',
    reviewed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 术语库
CREATE TABLE glossary (
    id BIGSERIAL PRIMARY KEY,
    term VARCHAR(255) NOT NULL,
    translation VARCHAR(255) NOT NULL,
    source_lang VARCHAR(10) NOT NULL,
    target_lang VARCHAR(10) NOT NULL,
    category VARCHAR(50),
    priority INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 资源版本管理
CREATE TABLE resource_versions (
    id BIGSERIAL PRIMARY KEY,
    version VARCHAR(50) NOT NULL UNIQUE,
    manifest_hash VARCHAR(64) NOT NULL,
    released_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 更多表结构见 migrations/

部署架构

本地开发模式

开发机器 (本地)
├── CLI (Go)
├── Rust 库
└── 连接 → 远程数据库服务器 (裸金属)
            ├── PostgreSQL
            └── Redis

生产部署模式

负载均衡器
    ↓
API Server (多实例)
    ↓
├── PostgreSQL (主从)
├── Redis (Sentinel/Cluster)
└── CAS 存储 (分布式文件系统)

安全设计

认证：JWT Token
授权：RBAC (Role-Based Access Control)
数据传输：HTTPS/TLS
数据库连接：SSL 加密
密码存储：bcrypt/argon2
API 限流：基于 Redis 的 Token Bucket

性能优化

缓存策略：
- Redis 缓存热点数据
- 浏览器缓存静态资源
- CAS 内容天然去重
并发控制：
- Go 协程池
- Rust Tokio 异步运行时
- 数据库连接池
数据库优化：
- 索引优化
- 查询优化
- 分区表

监控与日志

日志：结构化日志（JSON 格式）
指标：Prometheus + Grafana
追踪：OpenTelemetry
告警：Alertmanager

未来扩展

支持更多游戏：插件化架构便于扩展
分布式存储：CAS 可扩展到对象存储（S3/MinIO）
机器学习：翻译质量评估、自动术语提取
协作功能：多人实时翻译、冲突解决

更多详细设计文档：

待创建的详细设计文档：

docs/architecture/cas.md
docs/architecture/assetbundle.md
docs/architecture/translation.md

10 KiB Raw Blame History Unescape Escape