mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 01:15:14 +08:00
nyaKazuha
789402c887
Add the production-facing official update service and bat-official-sync watch CLI for unattended resource synchronization. Support launcher-resource discovery without installing the launcher, remote marker snapshots, local manifest audit and repair, official seed hash validation, bootstrap caching, richer Addressables coverage, SQLite resource persistence, and FFI JSON helpers.
376 lines
8.9 KiB
Markdown
376 lines
8.9 KiB
Markdown
# BlueArchive Toolkit 架构设计
|
||
|
||
## 概述
|
||
|
||
BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
|
||
|
||
当前文档描述目标架构。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||
|
||
当前已经可用的官方资源入口包括：
|
||
|
||
- `infrastructure/examples/official_pull_plan.rs`：Linux 生产资源拉取路径，显式读取官方 `server-info` 输入。
|
||
- `infrastructure/examples/official_update_check.rs`：Linux 自动更新检查入口，保存 snapshot 并按需拉取。
|
||
- `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)
|
||
|
||
**职责**：内容寻址存储，实现去重、引用计数、垃圾回收
|
||
|
||
**接口**：
|
||
```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. 资源同步器 (Go)
|
||
|
||
**职责**：从游戏服务器下载资源、增量更新、完整性校验
|
||
|
||
**架构**：
|
||
```
|
||
Manifest Parser → Version Manager → Downloader → CAS Storage
|
||
↓
|
||
Task Queue (多线程)
|
||
↓
|
||
Progress Reporter
|
||
```
|
||
|
||
**特性**：
|
||
- 多线程并发下载
|
||
- 断点续传（Range 请求）
|
||
- 自动重试机制（指数退避）
|
||
- 限速支持
|
||
- Hash 校验（下载后立即验证）
|
||
|
||
---
|
||
|
||
### 3. AssetBundle 解析器 (Rust)
|
||
|
||
**职责**：解析 Unity AssetBundle，提取资源
|
||
|
||
**插件化架构**：
|
||
```rust
|
||
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 抽象**：
|
||
```go
|
||
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 类型**：
|
||
1. **Binary Patch**：使用 bsdiff 算法
|
||
2. **JSON Patch**：RFC 6902 标准
|
||
3. **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
|
||
|
||
```sql
|
||
-- 翻译记忆库
|
||
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 存储 (分布式文件系统)
|
||
```
|
||
|
||
---
|
||
|
||
## 安全设计
|
||
|
||
1. **认证**：JWT Token
|
||
2. **授权**：RBAC (Role-Based Access Control)
|
||
3. **数据传输**：HTTPS/TLS
|
||
4. **数据库连接**：SSL 加密
|
||
5. **密码存储**：bcrypt/argon2
|
||
6. **API 限流**：基于 Redis 的 Token Bucket
|
||
|
||
---
|
||
|
||
## 性能优化
|
||
|
||
1. **缓存策略**：
|
||
- Redis 缓存热点数据
|
||
- 浏览器缓存静态资源
|
||
- CAS 内容天然去重
|
||
|
||
2. **并发控制**：
|
||
- Go 协程池
|
||
- Rust Tokio 异步运行时
|
||
- 数据库连接池
|
||
|
||
3. **数据库优化**：
|
||
- 索引优化
|
||
- 查询优化
|
||
- 分区表
|
||
|
||
---
|
||
|
||
## 监控与日志
|
||
|
||
- **日志**：结构化日志（JSON 格式）
|
||
- **指标**：Prometheus + Grafana
|
||
- **追踪**：OpenTelemetry
|
||
- **告警**：Alertmanager
|
||
|
||
---
|
||
|
||
## 未来扩展
|
||
|
||
1. **支持更多游戏**：插件化架构便于扩展
|
||
2. **分布式存储**：CAS 可扩展到对象存储（S3/MinIO）
|
||
3. **机器学习**：翻译质量评估、自动术语提取
|
||
4. **协作功能**：多人实时翻译、冲突解决
|
||
|
||
---
|
||
|
||
更多详细设计文档：
|
||
|
||
- [官方资源后端说明](./official-resource-backend.md)
|
||
- [CAS 存储引擎设计](./cas-storage.md)
|
||
- [AssetBundle 解析器设计](./assetbundle-parser.md)
|
||
- [翻译系统设计](./translation-system.md)
|
||
- [API 设计](../api/README.md)
|