mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:15:14 +08:00
401 lines
11 KiB
Markdown
401 lines
11 KiB
Markdown
# BlueArchive Toolkit 架构设计
|
||
|
||
## 概述
|
||
|
||
BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
|
||
|
||
当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力只有 Rust 官方资源同步任务。API Server、Web、Provider 编排和完整 Go CLI 仍未实现，实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||
|
||
当前已经可用的官方资源入口包括：
|
||
|
||
- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步正式入口，构建为 `bat`，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
|
||
- `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`。
|
||
- `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. 官方资源同步器 (Rust 当前实现，Go 后续编排)
|
||
|
||
**职责**：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。
|
||
|
||
**当前实现**：
|
||
|
||
- `OfficialUpdateService`：auto-discover、snapshot、marker diff、本地 manifest audit/repair。
|
||
- `OfficialResourcePullService`：官方 URL 校验、`.part` 断点续传、重试、下载 manifest、官方 seed `.hash` 校验。
|
||
- `bat`：正式 binary，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
|
||
|
||
**当前数据流**：
|
||
|
||
```
|
||
官方 metadata → GameMainConfig → server-info → discovery endpoints
|
||
↓
|
||
seed catalog → inventory → pull plan → staging → versions/<id>
|
||
↓
|
||
current symlink → official-sync-snapshot.json + official-download-manifest.json
|
||
```
|
||
|
||
**已具备特性**：
|
||
|
||
- 不安装、不执行官方 launcher。
|
||
- 默认平台 `Windows + Android`。
|
||
- `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。
|
||
- `--watch` / `--daemon` 常驻检查，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制刷新一次。
|
||
- `refresh --force` 可手动强制刷新；`verify` 只读校验当前官方计划、本地 manifest 和官方 seed hash；`repair` 尝试修复异常资源。
|
||
- 非 dry-run 同步先写 `.staging/<id>`，校验完成后发布 `versions/<id>` 并原子切换 `current` symlink。
|
||
- `--daemon` 使用状态目录下的 `bat.sock` 作为 Unix socket JSON-RPC live control plane；PID、状态和日志文件是快照与 fallback，`bat-events.jsonl` 是结构化轮转日志。
|
||
- `status`、`logs`、`reload`、`stop` 和默认形态的 `refresh` 优先通过 RPC 管理后台进程；控制命令通过 `bat-control.lock` 串行化；`restart` 负责重启或替换启动参数；live daemon 会阻止前台写命令直接修改同一资源目录；`doctor` 做运行时诊断；`clean-stable` 清理临时文件和失效/损坏状态。
|
||
- 远端 marker 无变化且本地 manifest clean 时不下载。
|
||
- 本地文件损坏时 repair。
|
||
- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。
|
||
|
||
**后续 Go 职责**：
|
||
|
||
- 提供最小稳定 CLI。
|
||
- 包装或调用 Rust 同步入口，需要机器输出时使用 `--json` 并转发结构化 report。
|
||
- 编排 API Server、任务队列、Provider 和用户配置。
|
||
|
||
---
|
||
|
||
### 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)
|
||
- [API 设计](../api/README.md)
|
||
|
||
待创建的详细设计文档：
|
||
|
||
- `docs/architecture/cas.md`
|
||
- `docs/architecture/assetbundle.md`
|
||
- `docs/architecture/translation.md`
|