mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-09-18 06:34:54 +08:00
docs: update current document status
This commit is contained in:
@@ -192,7 +192,7 @@ pub struct ParserRegistry {
|
||||
|
||||
---
|
||||
|
||||
### 4. 翻译系统 (目标设计，Go)
|
||||
### 4. 翻译系统（目标扩展，Go；当前 worker 由 Rust `bat` 承担）
|
||||
|
||||
当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、
|
||||
lease/retry 和结果落库；Translation Memory、Glossary 和完整 Provider 体系仍属
|
||||
@@ -214,7 +214,11 @@ type TranslationProvider interface {
|
||||
}
|
||||
```
|
||||
|
||||
**实现**：
|
||||
**当前实现**：
|
||||
- Rust `bat` 的 mock provider worker
|
||||
- Rust `bat` 的 Crowdin provider worker
|
||||
|
||||
**目标 Provider**：
|
||||
- DeepL Provider
|
||||
- OpenAI Provider
|
||||
- Anthropic Provider
|
||||
@@ -233,7 +237,7 @@ type TranslationProvider interface {
|
||||
**职责**：生成和应用补丁
|
||||
|
||||
**支持的 Patch 类型**：
|
||||
1. **Binary Patch**：使用 bsdiff 算法
|
||||
1. **Binary Patch**：确定性 Binary hunk diff/apply（当前实现）
|
||||
2. **JSON Patch**：RFC 6902 标准
|
||||
3. **Text Patch**：基于 diff 算法
|
||||
|
||||
|
||||
+72
-121
@@ -4,98 +4,78 @@
|
||||
|
||||
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
|
||||
|
||||
1. **本地开发模式**：代码在本地，连接本地或远程数据库。
|
||||
1. **本地开发模式**：当前 Rust `bat` 和 Go `bat-api` 不依赖 PostgreSQL/Redis；
|
||||
本地资源状态使用文件和 SQLite。
|
||||
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat --watch` 或 RPC/daemon 模式。
|
||||
3. **bat-api 资源 bootstrap / 分发服务**：当前可用，和 Rust `bat` 在同一服务器/容器环境运行，经 `bat.sock` RPC 获取当前 `resource_root`。
|
||||
4. **完整单机/分布式部署**：尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
|
||||
4. **可选数据库开发环境**：PostgreSQL/Redis 只服务于未来的 Go 服务层、Translation
|
||||
Memory、Glossary 和完整 Provider 扩展，不是当前 `bat` / `bat-api` 的生产运行依赖。
|
||||
5. **完整单机/分布式部署**：尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
|
||||
|
||||
---
|
||||
|
||||
## 模式 1：本地开发 + 远程数据库
|
||||
## 模式 1：本地开发（当前推荐）
|
||||
|
||||
适用场景：本地开发，数据库部署在有公网 IP 的远程服务器
|
||||
|
||||
### 步骤
|
||||
|
||||
#### 1. 在远程服务器上部署数据库
|
||||
当前实现不要求启动 PostgreSQL 或 Redis。建议先运行 Rust/Go 自身的门禁：
|
||||
|
||||
```bash
|
||||
# SSH 登录到服务器
|
||||
ssh user@your.server.com
|
||||
|
||||
# 创建部署目录
|
||||
mkdir -p ~/bat/deployments
|
||||
cd ~/bat/deployments
|
||||
|
||||
# 上传配置文件（在本地执行）
|
||||
scp -r deployments/* user@your.server.com:~/bat/deployments/
|
||||
|
||||
# 配置环境变量
|
||||
cp .env.example .env
|
||||
nano .env # 设置强密码
|
||||
|
||||
# 启动数据库
|
||||
docker compose -f docker-compose.remote-db.yml up -d
|
||||
|
||||
# 查看状态
|
||||
docker compose -f docker-compose.remote-db.yml ps
|
||||
cargo check --workspace --locked
|
||||
make test-go-api
|
||||
make build-go-api
|
||||
make check-docs
|
||||
```
|
||||
|
||||
#### 2. 配置防火墙
|
||||
只有在开发未来 Go 服务层或目标数据库适配时，才需要启动可选的本地数据库：
|
||||
|
||||
```bash
|
||||
# 开放 PostgreSQL 端口
|
||||
sudo ufw allow 5432/tcp
|
||||
|
||||
# 开放 Redis 端口
|
||||
sudo ufw allow 6379/tcp
|
||||
|
||||
# 查看状态
|
||||
sudo ufw status
|
||||
docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
|
||||
```
|
||||
|
||||
#### 3. 本地连接配置
|
||||
本地数据库端口默认只绑定 `127.0.0.1`，不应改为 `0.0.0.0`。
|
||||
|
||||
在本地项目根目录创建 `.env`：
|
||||
---
|
||||
|
||||
## 模式 2：可选数据库开发环境（目标能力）
|
||||
|
||||
PostgreSQL 和 Redis 不是当前 `bat` / `bat-api` 的生产运行依赖。本模式只用于未来
|
||||
服务层、Translation Memory、Glossary 或 Provider 扩展的开发验证，不能作为当前
|
||||
资源同步或资源分发的部署前置条件。
|
||||
|
||||
### 远程开发连接
|
||||
|
||||
远程开发默认使用私网地址、VPN 或 SSH tunnel。不要为开发方便把 PostgreSQL
|
||||
`5432` 或 Redis `6379` 暴露到公网；尤其不得把 Redis 公网暴露作为推荐方案。
|
||||
|
||||
在远程主机上启动可选数据库后，优先通过 SSH tunnel 连接：
|
||||
|
||||
```bash
|
||||
ssh -N \
|
||||
-L 15432:127.0.0.1:5432 \
|
||||
-L 16379:127.0.0.1:6379 \
|
||||
user@db-host
|
||||
```
|
||||
|
||||
本地开发进程只连接 tunnel 的回环端口：
|
||||
|
||||
```env
|
||||
DB_HOST=your.server.ip.address
|
||||
DB_PORT=5432
|
||||
DB_USER=bat_user
|
||||
DB_PASSWORD=your_secure_password
|
||||
DB_NAME=bluearchive_toolkit
|
||||
|
||||
REDIS_HOST=your.server.ip.address
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=15432
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=16379
|
||||
```
|
||||
|
||||
#### 4. 测试连接
|
||||
如果使用 VPN 或私网直连，应限制数据库服务仅监听明确的私网接口和允许的来源
|
||||
网段，并继续使用认证与 TLS。不要添加面向全网的 `5432` / `6379` 防火墙放行规则。
|
||||
|
||||
远程主机上的可选 Compose 服务：
|
||||
|
||||
```bash
|
||||
# 测试 PostgreSQL 连接
|
||||
psql -h your.server.ip.address -U bat_user -d bluearchive_toolkit
|
||||
|
||||
# 测试 Redis 连接
|
||||
redis-cli -h your.server.ip.address -p 6379 -a your_redis_password ping
|
||||
docker compose -f deployments/docker-compose.remote-db.yml up -d
|
||||
docker compose -f deployments/docker-compose.remote-db.yml ps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模式 2：本地数据库（开发）
|
||||
|
||||
适用场景：完全本地开发，不需要远程服务器
|
||||
|
||||
```bash
|
||||
# 启动本地数据库
|
||||
docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
|
||||
|
||||
# 配置 .env
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
该 Compose 配置默认仅在远程主机回环地址发布端口，远程访问应通过 SSH tunnel、
|
||||
VPN 或受控私网，不通过公网端口直连。
|
||||
|
||||
---
|
||||
|
||||
@@ -504,71 +484,42 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
|
||||
|
||||
---
|
||||
|
||||
## 数据库备份
|
||||
## 可选数据库环境的备份与监控
|
||||
|
||||
### 手动备份
|
||||
以下内容只适用于未来服务层使用的可选 PostgreSQL/Redis 环境，不属于当前
|
||||
`bat` / `bat-api` 生产部署步骤。
|
||||
|
||||
### 备份
|
||||
|
||||
备份应在数据库主机或受控私网内执行，也可以通过 SSH 在远程主机上运行容器内工具：
|
||||
|
||||
```bash
|
||||
# PostgreSQL
|
||||
pg_dump -h your.server.com -U bat_user -d bluearchive_toolkit > backup.sql
|
||||
|
||||
# Redis
|
||||
redis-cli -h your.server.com -p 6379 -a password BGSAVE
|
||||
```
|
||||
|
||||
### 自动备份
|
||||
|
||||
启动备份服务：
|
||||
```bash
|
||||
ssh user@db-host \
|
||||
'docker exec bat-postgres pg_dump -U bat_user bluearchive_toolkit' \
|
||||
> backup.sql
|
||||
docker compose -f deployments/docker-compose.remote-db.yml --profile backup up -d
|
||||
```
|
||||
|
||||
备份文件位置：`deployments/backups/`
|
||||
Redis 备份使用数据库主机或容器内的受控备份工具。不要在脚本或文档中使用带公网
|
||||
主机名的 `redis-cli -h ... -p 6379` 连接，也不要把密码放进公开命令行参数或提交文件。
|
||||
|
||||
---
|
||||
|
||||
## 监控
|
||||
|
||||
### 查看日志
|
||||
### 监控
|
||||
|
||||
```bash
|
||||
# 数据库日志
|
||||
docker logs bat-postgres
|
||||
|
||||
# Redis 日志
|
||||
docker logs bat-redis
|
||||
ssh user@db-host 'docker compose -f deployments/docker-compose.remote-db.yml ps'
|
||||
ssh user@db-host 'docker logs bat-postgres'
|
||||
ssh user@db-host 'docker logs bat-redis'
|
||||
```
|
||||
|
||||
### 健康检查
|
||||
### 故障排查
|
||||
|
||||
```bash
|
||||
# 检查容器状态
|
||||
docker compose -f deployments/docker-compose.remote-db.yml ps
|
||||
当前 `bat` / `bat-api` 无需数据库连接；资源同步故障应先检查 `bat.sock`、发布目录、
|
||||
SQLite 索引和 Rust daemon 状态。未来服务层出现数据库连接问题时，按以下顺序检查：
|
||||
|
||||
# 检查 PostgreSQL
|
||||
docker exec bat-postgres pg_isready -U bat_user
|
||||
|
||||
# 检查 Redis
|
||||
docker exec bat-redis redis-cli ping
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 无法连接数据库
|
||||
|
||||
1. 检查防火墙是否开放端口
|
||||
2. 检查 `pg_hba.conf` 配置
|
||||
3. 检查密码是否正确
|
||||
4. 检查数据库是否启动
|
||||
|
||||
### 性能问题
|
||||
|
||||
1. 查看数据库连接数
|
||||
2. 检查慢查询日志
|
||||
3. 优化索引
|
||||
4. 调整数据库参数
|
||||
1. 私网、VPN 或 SSH tunnel 是否可用；
|
||||
2. 本地连接端口是否为 tunnel 映射或受控私网端口；
|
||||
3. 数据库认证、TLS 和允许网段配置；
|
||||
4. 数据库容器是否运行。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# 解析模块维护冻结（历史记录）
|
||||
|
||||
**状态**：历史记录，已解除
|
||||
**生效时间**：2026-07-30
|
||||
**解除时间**：2026-09-04
|
||||
|
||||
本文保留解析模块维护冻结期间的原始规则和例外说明。冻结已于
|
||||
2026-09-04 解除，以下内容不构成当前开发约束；当前解析开发以源码、测试、
|
||||
`CURRENT_STATUS.md` 和 `docs/architecture/assetbundle.md` 为准。
|
||||
|
||||
---
|
||||
|
||||
## 原冻结记录
|
||||
|
||||
原记录发布时状态：**生效中**
|
||||
|
||||
冻结目标：停止继续扩大 UnityFS / AssetBundle / Addressables / TypeTree 解析能力，把当前工作重心切换到运行稳定性、代码审核问题、文档一致性和发布链路可靠性。
|
||||
|
||||
## 冻结范围
|
||||
|
||||
冻结覆盖以下 Rust 解析相关模块和对外入口：
|
||||
|
||||
- `crates/bat-assetbundle`
|
||||
- `adapters/src/unity*`
|
||||
- `infrastructure/src/official_parse.rs`
|
||||
- `infrastructure/src/resources.rs` 中解析缓存、TextUnit 索引和解析状态相关逻辑
|
||||
- `unityfs.*`、`parse.*`、`text.*` 相关 RPC / CLI 契约
|
||||
- Addressables catalog、UnityFS、serialized file、TypeTree、TextUnit、AssetBundle patch 相关文档声明
|
||||
|
||||
## 允许变更
|
||||
|
||||
冻结期只允许以下解析相关变更：
|
||||
|
||||
- 修复编译失败、格式化失败、clippy 报错和测试失败。
|
||||
- 修复真实运行中已经复现的 panic、错误状态污染、重复解析、缓存失效、状态不一致或诊断误导。
|
||||
- 补充回归测试，前提是测试覆盖的是已存在能力的稳定性问题，不宣称新增解析能力。
|
||||
- 修正文档、CLI 帮助、RPC 参考和状态文件中与当前实现不一致的解析能力声明。
|
||||
- 改善错误信息、日志字段、状态记录和失败恢复，但不得改变解析输出契约，除非是修复错误契约且同步迁移说明。
|
||||
|
||||
## issue 43 的明确例外
|
||||
|
||||
本次 issue 43 经用户明确授权，允许新增 `bat` 的工作流编排入口：
|
||||
|
||||
- `parse run` 只刷新已有解析输出、TextUnit 索引和翻译队列；
|
||||
- `parse repack` 只调用已有 TextAsset、TypeTree string 和受支持语义字段 patch 实现；
|
||||
- `i18n` 工作台和 `publish` 只消费已有 TextUnit 输出，并发布独立汉化 release。
|
||||
|
||||
该例外不解冻解析器，不新增 UnityFS/AssetBundle/Addressables/TypeTree 解析类型、字段覆盖、catalog 结构或合成 fixture 能力。后续任何扩大解析覆盖的变更仍需单独解冻授权。
|
||||
|
||||
## issue 2/3 的开发例外
|
||||
|
||||
授权时间：2026-08-19
|
||||
|
||||
用户明确授权将 issue #2/#3 作为解析开发进展继续推进。本次例外允许：
|
||||
|
||||
- Addressables JSON/compact catalog 的 provider、bundle name、hash、size、CRC、资源类型和依赖关系字段补全，以及对应 SQLite/fixture 回归；
|
||||
- UnityFS 已有 header、block、directory、压缩和 alignment 能力的校验加固，以及隔离真实 bundle 回归；
|
||||
- 更新解析路线图、状态和 RPC/CLI 资源索引字段说明。
|
||||
|
||||
本次例外不包含发布级复杂对象重打包、完整 Unity 版本兼容承诺或新的汉化发布控制面；这些仍按后续 Patch/发布路线单独验收。
|
||||
|
||||
## 禁止变更
|
||||
|
||||
冻结期禁止以下解析相关变更：
|
||||
|
||||
- 新增 TypeTree 语义类型、字段族、managed reference 变体、Unity 内建结构体覆盖或 Addressables catalog 结构覆盖。
|
||||
- 用纯合成 fixture 推进“完整解析”并把它记录为已支持能力。
|
||||
- 开放新的写入型 `unityfs.*` / `patch.*` RPC 或 CLI。
|
||||
- 修改解析结果 schema、TextUnit schema、patch field JSON 语义或缓存状态格式，除非它是阻断级 bug 修复并附带兼容策略。
|
||||
- 将解析器和官方同步、汉化发布、Go API、Crowdin 或客户端流程进一步耦合。
|
||||
|
||||
## 解冻条件
|
||||
|
||||
解析扩展重新启动前必须同时满足：
|
||||
|
||||
- Rust `bat` 官方同步、daemon、status、校验、断点续传、增量更新和解析缓存链路稳定。
|
||||
- 当前 P0/P1 维护 issue 已关闭或被明确降级。
|
||||
- `bat-api` 与 Rust RPC / CLI 契约完成字段统一和联调验证。
|
||||
- 真实资源 fixture、验证命令和验收标准已写入文档，不能只依赖合成样本。
|
||||
|
||||
## 冻结期验证
|
||||
|
||||
解析相关维护变更至少运行：
|
||||
|
||||
```bash
|
||||
cargo fmt --check
|
||||
cargo test -p bat-assetbundle --locked
|
||||
cargo clippy -p bat-assetbundle --all-targets --locked -- -D warnings
|
||||
```
|
||||
|
||||
如果变更影响 `bat` CLI、RPC、官方解析缓存或 TextUnit 索引，还必须补充对应 `bat-infrastructure` 测试或说明未运行原因。
|
||||
@@ -1,6 +1,8 @@
|
||||
# 历史报告归档说明
|
||||
|
||||
本目录只保存追溯资料，不代表当前项目状态。当前状态以根目录 `CURRENT_STATUS.md`、`PROJECT_PLAN.md`、`DOCS_INDEX.md` 和 `docs/reports/CURRENT_GAPS.md` 为准。
|
||||
本目录只保存追溯资料，不代表当前项目状态。当前实现以源码、测试、根目录
|
||||
`CURRENT_STATUS.md` 和对应专项状态文档为准；`PROJECT_PLAN.md` 只描述目标和路线图，
|
||||
`DOCS_INDEX.md` 只负责文档分类，`docs/reports/CURRENT_GAPS.md` 只记录当前缺口。
|
||||
|
||||
归档分类：
|
||||
|
||||
@@ -10,5 +12,6 @@
|
||||
- `quality/`：早期质量状态报告。
|
||||
- `build-logs/`：历史构建、测试和 Clippy 输出。
|
||||
- `nested-docs/`：从误嵌套 `docs/docs` 移出的历史报告。
|
||||
- `PARSER_FREEZE.md`：2026-07-30 生效、2026-09-04 解除的解析模块维护冻结记录。
|
||||
|
||||
新增运行产物、smoke 输出、质量扫描输出和本地分析报告不要放入本目录；这些文件应写入 `/tmp`、显式的隔离输出目录，或被 `.gitignore` 覆盖的本地生成报告目录。
|
||||
|
||||
Reference in New Issue
Block a user