mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-09-18 07:24:55 +08:00
450 lines
15 KiB
Markdown
450 lines
15 KiB
Markdown
# BlueArchive Toolkit 架构设计
|
||
|
||
## 概述
|
||
|
||
BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
|
||
|
||
当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力包括 Rust 官方资源同步任务和 Go `cmd/bat-api` 资源 bootstrap/分发服务。完整游戏业务 API、Web、Provider 编排和 SDK 仍未完成，实际实现状态以源码、测试和根目录 `CURRENT_STATUS.md` 为准；`PROJECT_PLAN.md` 只描述目标和路线图。
|
||
|
||
当前已经可用的官方资源入口包括：
|
||
|
||
- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步薄入口，构建为 `bat`；控制面组合与实现位于 `infrastructure/src/bin/bat/`，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
|
||
- `infrastructure/src/bin/bat/app.rs`：CLI/env、daemon/watch、RPC dispatch 与顶层流程组合。
|
||
- `infrastructure/src/bin/bat/report_output.rs`：人类可读报告、JSON 查询结果和报告格式化。
|
||
- `infrastructure/src/bin/bat/terminal_output.rs`：前台错误、帮助、启动提示、进度和结构化日志输出。
|
||
- `infrastructure/src/bin/bat/task_registry.rs`：任务注册表、任务持久化、取消和 daemon worker。
|
||
- `infrastructure/src/bin/bat/readonly_query.rs`：parse/resource/translation/localized 只读查询及 RPC 选择。
|
||
- `infrastructure/src/bin/bat/translation_query.rs`：翻译任务与 handoff 查询、worker 状态更新。
|
||
- `infrastructure/src/bin/bat/patch_commands.rs`：文件 patch 与 UnityFS 写入命令参数校验和执行。
|
||
- `infrastructure/src/bin/bat/app_tests.rs`：控制面回归测试，避免测试代码继续堆积在入口实现中。
|
||
- `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`：历史语言/层次边界决策；资源同步职责已由 ADR 0004 取代。
|
||
- `adr/0002-cas-v1-design-boundary.md`：CAS V1 设计边界。
|
||
- `adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口与错误边界冻结。
|
||
- `adr/0004-rust-bat-go-bat-api-resource-boundary.md`：当前 Rust `bat` 与 Go `bat-api`
|
||
的资源控制面边界。
|
||
|
||
---
|
||
|
||
## 设计原则
|
||
|
||
### 1. 模块化与解耦
|
||
|
||
- **高内聚、低耦合**：每个模块职责明确，依赖关系清晰
|
||
- **接口优先**：通过接口定义模块边界，支持多种实现
|
||
- **插件化**：核心功能稳定，扩展功能通过插件实现
|
||
|
||
### 2. 语言选型
|
||
|
||
| 模块 | 语言 | 当前定位 |
|
||
|------|------|------|
|
||
| 官方资源同步与运维 CLI、同步核心 | Rust | **当前实现**；`bat` 负责生产资源和长期状态 |
|
||
| 资源 bootstrap、只读分发和 Rust 管理入口 | Go | **当前实现**；`cmd/bat-api` 通过 `bat.sock` RPC 工作 |
|
||
| AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | **当前已有基础，复杂覆盖仍按路线图推进** |
|
||
| 完整 API、服务编排和 Provider | Go | **目标设计，尚未完整实现** |
|
||
| 完整 Web 协作后台 | Vue 3 + TypeScript | **目标设计**；当前只有内嵌 dashboard MVP |
|
||
|
||
### 3. 数据流设计
|
||
|
||
当前已落地的数据流：
|
||
|
||
```
|
||
官方 metadata → Rust bat / daemon → release + current + manifest
|
||
↓
|
||
bat.sock JSON-RPC
|
||
↓
|
||
Go bat-api → bootstrap / CDN / dashboard
|
||
```
|
||
|
||
目标扩展数据流（其中 Go 业务层、SDK、数据库和 Redis 尚未全部实现）：
|
||
|
||
```
|
||
用户请求 → CLI/API → Go 业务层 → bat.sock RPC / SDK → 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`、`restart`、`reload`、`stop` 和默认形态的 `refresh` 优先通过 RPC 管理后台进程；控制命令通过 `bat-control.lock` 串行化；`restart` 通过 Rust lifecycle controller 复用 CLI restart 路径重启或替换启动参数；live daemon 会阻止前台写命令直接修改同一资源目录；`doctor` 做运行时诊断；`clean-stable` 清理临时文件和失效/损坏状态。
|
||
- 远端 marker 无变化且本地 manifest clean 时不下载。
|
||
- 本地文件损坏时 repair。
|
||
- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。
|
||
|
||
**Go 当前职责**：
|
||
|
||
- `bat-api` 通过 `bat.sock` RPC 读取 Rust 已发布 release、manifest、snapshot 和状态。
|
||
- 提供资源 bootstrap、server-info 改写、只读 CDN path、readiness、OpenAPI 和白名单管理转发；
|
||
翻译任务与 TM 管理接口只通过 Rust RPC 代理，不在 Go 侧持有状态。
|
||
- 不运行另一套同步器，不直接管理官方下载、staging、version-state、CAS 或解析状态。
|
||
|
||
完整 API、服务编排、Provider 和用户配置属于目标扩展，不能从本节推断为当前已实现。
|
||
|
||
---
|
||
|
||
### 3. AssetBundle 解析器 (Rust，当前基础与目标扩展)
|
||
|
||
**职责**：解析 Unity AssetBundle，提取资源
|
||
|
||
以下插件注册和动态加载是目标扩展；当前实现以 `crates/bat-assetbundle`、
|
||
`bat-adapters` 和真实 fixture 覆盖为准。
|
||
|
||
**目标插件化架构**：
|
||
```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；当前 worker 由 Rust `bat` 承担）
|
||
|
||
当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、
|
||
lease/retry、结果落库和项目级 Translation Memory V1。TM 位于独立 SQLite，按 raw
|
||
source + 完整 context 做 trusted exact reuse，candidate 必须显式 confirm；Glossary、
|
||
模糊匹配和完整 Provider 体系仍属后续缺口。
|
||
|
||
**架构**：
|
||
```
|
||
Text Extractor → TM exact query → AI Provider → Glossary (后续) → Output
|
||
↓ ↓
|
||
PostgreSQL 审核队列
|
||
```
|
||
|
||
**Provider 抽象**：
|
||
```go
|
||
type TranslationProvider interface {
|
||
Name() string
|
||
Translate(ctx context.Context, req *TranslateRequest) (*TranslateResponse, error)
|
||
SupportedLanguages() []Language
|
||
}
|
||
```
|
||
|
||
**当前实现**：
|
||
- Rust `bat` 的 mock provider worker
|
||
- Rust `bat` 的 Crowdin provider worker
|
||
|
||
**目标 Provider**：
|
||
- DeepL Provider
|
||
- OpenAI Provider
|
||
- Anthropic Provider
|
||
- Google Translate Provider
|
||
- Azure Translator Provider
|
||
|
||
**翻译记忆库**：
|
||
- 当前 V1：raw source 完全相同、完整 context 完全相同且记录为 trusted 时自动复用。
|
||
- provider 输出写入先是 candidate；manual task result 不会自动建立 TM 或 trusted。`bat i18n memory confirm` 显式确认单条记录后才可自动复用。
|
||
- source、context、release、TextUnit、provider 和 run provenance 保存在 Rust TM SQLite 中。
|
||
- 模糊匹配、术语优先级和 PostgreSQL 服务化仍不是当前实现。
|
||
|
||
---
|
||
|
||
### 5. Patch 引擎 (Rust，当前基础与目标扩展)
|
||
|
||
**职责**：生成和应用补丁
|
||
|
||
**支持的 Patch 类型**：
|
||
1. **Binary Patch**：确定性 Binary hunk diff/apply（当前实现）
|
||
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，目标设计)
|
||
|
||
当前可用的 Go HTTP 服务是 `cmd/bat-api` 的资源 bootstrap、只读分发和 Rust 管理
|
||
入口，不是下列完整游戏业务 API。
|
||
|
||
**框架**：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，目标设计)
|
||
|
||
当前只有 `bat-api` 内嵌 dashboard MVP；登录、角色、术语管理和完整协作审核仍未实现。
|
||
|
||
**技术栈**：
|
||
- Vue 3 + Composition API
|
||
- TypeScript
|
||
- Pinia (状态管理)
|
||
- Vue Router
|
||
- Axios
|
||
- Element Plus / Ant Design Vue
|
||
|
||
**模块**：
|
||
- Dashboard（统计概览）
|
||
- 翻译审核（Translation Review）
|
||
- 术语管理（Glossary Manager）
|
||
- 资源浏览（Asset Browser）
|
||
- 用户管理（User Management）
|
||
|
||
---
|
||
|
||
## 数据库设计（目标设计）
|
||
|
||
当前 Rust 资源链路使用 SQLite 维护本地 CAS、ResourceRepository 和翻译任务状态；
|
||
PostgreSQL/Redis 业务服务端方案尚未完整落地。
|
||
|
||
### 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/
|
||
```
|
||
|
||
---
|
||
|
||
## 部署架构（目标设计）
|
||
|
||
当前可部署形态是 Rust `bat` 官方资源同步任务和同机/共享文件系统的 Go
|
||
`bat-api` 资源 bootstrap/分发服务。以下多实例 API、PostgreSQL 主从和 Redis
|
||
集群属于目标部署形态。
|
||
|
||
### 本地开发模式
|
||
|
||
```
|
||
开发机器 (本地)
|
||
├── CLI (Go)
|
||
├── Rust bat 进程 / 未来 SDK
|
||
├── 可选 bat-ffi 兼容层
|
||
└── 连接 → 远程数据库服务器 (裸金属)
|
||
├── 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)
|
||
- [资源 release 布局与分发契约](./resource-release-layout.md)
|
||
- [AssetBundle 解析与发布路线图](./assetbundle.md)
|
||
- [API 设计](../api/README.md)
|