Quartz 4

🔍 搜索

remote_bootstrap_validation

7 min read

GeneralAndroid 外网同事验收说明

本文档用于给外网 / 非局域网同事执行最终验收，目标是验证：

  • clone 仓库后是否可以通过统一入口完成初始化
  • 是否可以自动创建 mc alias
  • 是否可以从 MinIO 恢复已迁移的大文件
  • 当前 MinIO 大文件工作流在远程环境下是否可用

1. 验收目标

同事完成本说明后，应该能够确认以下事项：

  1. 可以 clone 仓库并进入项目目录
  2. 可以通过一条命令执行初始化：
    • bash scripts/bootstrap_repo.sh
    • 或在 Claude Code 中执行 /clone-init
  3. 如果本地没有预先配置 mc alias，bootstrap 也可以通过环境变量自动创建
  4. 可以从 MinIO 恢复 manifest 中登记的大文件
  5. 如果恢复成功，说明当前远程环境接入链路已经打通

2. 重要背景说明

2.1 当前大文件工作流

仓库中的大文件不再直接依赖 Git 本体，而采用：

  • Git：维护清单和元数据
  • MinIO：保存大文件实体

当前关键文件：

  • 主清单：assets/resource_manifest.json
  • 阅读视图：assets/resource_manifest.md
  • 校验文件：assets/assets_sha256.txt
  • 操作历史：assets/asset_history.jsonl

2.2 当前初始化入口

clone 后统一入口为：

bash scripts/bootstrap_repo.sh

如果在 Claude Code 中协作，也可以使用：

/clone-init

2.3 当前外网 MinIO API 入口

当前已确认外网接入应使用：

http://tx2.898311.xyz:9010

注意：

  • http://minio.898311.xyz/
  • https://minio.898311.xyz/

当前更像上传页入口，不是 mc 应使用的 MinIO API endpoint。

3. 前置条件

同事机器上需要具备：

  1. git
  2. python3
  3. mc（MinIO Client）

可选：

  1. Claude Code（如果想用 /clone-init）

4. Clone 后的执行步骤

4.1 clone 仓库

git clone <仓库地址>
cd GeneralAndroid

4.2 使用环境变量执行 bootstrap

请将下面命令中的 <ACCESS_KEY> 和 <SECRET_KEY> 替换成实际可用凭证：

GENERALANDROID_MC_ALIAS=uploadrw \
GENERALANDROID_MC_ENDPOINT=http://tx2.898311.xyz:9010 \
GENERALANDROID_MC_ACCESS_KEY=<ACCESS_KEY> \
GENERALANDROID_MC_SECRET_KEY=<SECRET_KEY> \
GENERALANDROID_ASSET_DOWNLOAD_JOBS=4 \
bash scripts/bootstrap_repo.sh

如果使用 Claude Code，也可以在项目目录内执行：

/clone-init

但如果 /clone-init 需要远程 alias 自动创建，仍然建议在执行前让终端环境具备上述环境变量。

5. 预期行为

执行 bootstrap 时，预期会发生：

  1. 检查 python3
  2. 检查 mc
  3. 配置 .githooks
  4. 检查 alias 是否存在
  5. 如果 alias 不存在，则使用环境变量自动创建
  6. 调用下载脚本，按 manifest 恢复缺失的大文件
  7. 校验仓库大文件规则
  8. 输出最终状态

6. 预期输出示例

成功时，终端应看到类似：

[bootstrap] repo root: ...
[bootstrap] configured core.hooksPath=...
[bootstrap] creating mc alias: uploadrw -> http://tx2.898311.xyz:9010
[bootstrap] validating manifest download flow
...
restored: <某个大文件路径>
summary: downloaded=N skipped=M failed=0
[bootstrap] validating large file policy
[bootstrap] completed successfully

如果 alias 已存在，也可能看到：

[bootstrap] using existing mc alias: uploadrw

7. 验收通过标准

满足以下条件则视为通过：

  1. bootstrap_repo.sh 可以正常执行结束
  2. alias 能成功创建或成功复用
  3. 至少一个缺失的大文件能被恢复
  4. 下载 summary 中：
    • failed=0
  5. 最后看到：
[bootstrap] completed successfully

8. 推荐重点检查项

建议同事在验收时重点留意：

8.1 alias 是否成功创建

看日志中是否出现：

[bootstrap] creating mc alias: ...

或：

[bootstrap] using existing mc alias: ...

8.2 是否有真实文件恢复

看是否出现：

restored: <repo-relative-path>

如果全部都是：

skip verified existing: ...

说明本地文件原本就存在，但这并不等于恢复链路失败，只是没有缺失文件需要下载。

8.3 summary 是否正常

应重点看：

summary: downloaded=... skipped=... failed=0

9. 失败时怎么反馈

如果同事执行失败，请把以下信息完整回传：

  1. 执行命令（可隐藏密钥）
  2. 全部终端输出
  3. 当前网络环境说明：
    • 公司内网 / 家庭网络 / 手机热点 / VPN 等
  4. 当前 mc 版本：
mc --version
  1. 当前 Python 版本：
python3 --version

10. 常见问题

10.1 mc 不存在

表现：

[bootstrap] missing dependency: mc

处理：

  • 先安装 MinIO Client，再重新执行

10.2 alias 缺失且未提供环境变量

表现：

[bootstrap] missing mc alias: ...

处理：

  • 补齐以下环境变量再执行：
    • GENERALANDROID_MC_ALIAS
    • GENERALANDROID_MC_ENDPOINT
    • GENERALANDROID_MC_ACCESS_KEY
    • GENERALANDROID_MC_SECRET_KEY

10.3 endpoint 配错成 minio.898311.xyz

表现：

  • mc 无法正确访问对象 API
  • bootstrap 卡在恢复阶段或直接失败

处理：

  • 改用：
http://tx2.898311.xyz:9010

10.4 有文件失败，但不是全部失败

如果启用了继续处理模式，可能看到：

  • 部分文件 restored
  • 部分文件 failed

处理：

  • 把 summary 和失败列表完整回传
  • 重点看是否是网络波动导致

11. 额外说明

11.1 当前“断点恢复”的真实含义

当前工作流支持的不是自定义 chunk 级断点续传，而是：

  • 中断后重跑时
  • 已完成且校验通过的文件会跳过
  • 未完成或缺失的文件继续下载

也就是一种适合当前仓库的 resumable rerun 机制。

11.2 当前“多线程”的真实含义

当前支持的是：

  • 多文件并发下载
  • 多文件并发上传（通过批量脚本）

不是自研的字节级分块上传器。

12. 验收结论模板

同事执行后，可按下面模板回传：

【外网验收结果】
- 环境：
- 是否成功创建/复用 alias：
- 是否成功恢复大文件：
- summary：
- 是否通过：
- 备注：

13. 当前验收结论的意义

如果同事按本文档执行并通过，则说明：

  • 当前 MinIO 外网恢复链路可用
  • bootstrap 作为统一入口在远程环境下成立
  • 这轮大文件治理不仅能在本机用，也能给远程协作者使用

Graph View