GeneralAndroid 公网 MinIO 接入与远程 Clone 长期方案

整理时间：2026-05-11

1. 目标

本文用于解决一个当前已经明确暴露的问题：

现在的 MinIO 迁移流程已经在本机验证通过，但依赖本机 mc alias local -> http://127.0.0.1:9000。远程机器或外网同事重新 clone 仓库后，如何稳定恢复大文件？

当前目标分为两层：

公网长期恢复链路
- 远程机器 clone 后可以恢复 manifest 中登记的大文件
- 不依赖本机 mc alias local
- 通过公网 MinIO API 长期可用
- 尽量复用现有脚本体系，降低改造成本
与后续最小 clone 兼容
- 在公网恢复链路稳定后，再推进 git filter-repo / BFG 历史清理
- 最终实现“新同事重新 clone 时尽可能接近最小下载”

2. 当前现状（基于已确认信息）

2.1 现有 MinIO 本体

根据 main/blog/minio/MinIO 部署现状与维护调研.md 已确认：

MinIO 已部署在本机，并通过 systemd 管理
启动命令实际监听：0.0.0.0:9000
本机真实可用 API 入口：http://127.0.0.1:9000
MinIO root 凭证当前配置在 /etc/default/minio
当前正式配置关闭了 MinIO Console：MINIO_BROWSER=off

2.2 当前公网 MinIO API 入口

根据 main/blog/minio/MinIO 外网访问与 mc 使用说明.md 已确认：

当前外网可用 MinIO API 地址：

http://tx2.898311.xyz:9010/

这是通过 frpc 将本机 127.0.0.1:9000 映射出去的真实 MinIO API
已通过 mc 实测可用

2.3 当前不能用的域名

已确认：

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

当前返回的是 自定义上传页 HTML，不是 S3 API 响应。

结论：

minio.898311.xyz 当前不能作为 mc、SDK、或远程恢复脚本的 MinIO API endpoint 使用
外网机器如果直接把这个域名配置给 mc，会失败

2.4 当前仓库侧能力

当前仓库已经具备：

scripts/upload_assets.py
scripts/download_assets.py
scripts/bootstrap_repo.sh
assets/resource_manifest.json
本地 hook / GitLab CI 大文件约束
TOP40 范围内目标对象已全部迁入 MinIO 并登记进 manifest

这意味着：

现在缺的不是“迁移机制”本身
而是“把本机 local alias 模型改成可被远程机器复用的公网 alias 模型”

3. 主方案结论

3.1 主方案

当前推荐主方案为：

公网 mc 直连 + 受限普通账号 + bootstrap 自动 alias 配置

即：

远程机器通过公网地址 http://tx2.898311.xyz:9010 访问 MinIO API
使用受限普通账号，而不是 root 账号
clone 后由仓库脚本通过环境变量自动配置 mc alias
继续复用现有 download_assets.py 通过 mc cp 恢复对象

3.2 为什么它现在优先于预签名服务

基于现有文档和实测，这个方案已经具备：

公网 endpoint 已实测可用
- http://tx2.898311.xyz:9010
普通账号已存在且权限受限
- 不是 root
- 权限边界已经通过策略文件表达
现有脚本体系本来就是 mc 驱动
- scripts/bootstrap_repo.sh
- scripts/download_assets.py
- scripts/upload_assets.py
改造成本显著低于新增预签名服务
- 只需把“硬编码 local alias”改成“可注入 alias/endpoint/credential”
- 不需要先开发新的公网下载服务

因此：

主方案：公网 mc 直连 + 受限账号 + bootstrap 基于环境变量自动建 alias
增强方案：未来若觉得凭证分发不可接受，再升级为预签名服务

4. 如何与现有 MinIO 打通

4.1 与现有 MinIO 本体的关系

当前 MinIO 不需要重装，也不需要为远程 clone 先新增一个签名服务才能使用。

即：

MinIO 本体保留现状
- systemd 服务保留
- 数据目录保留
- 9000 API 端口保留
- Console 继续关闭可接受
远程机器通过现有 frpc 出口接入
- 外网 API：http://tx2.898311.xyz:9010
- 本机 API：http://127.0.0.1:9000

所以当前与现有 MinIO 打通的方式不是“新增一套完全新的下载服务”，而是：

保留本机 MinIO 服务
直接复用现有 frpc 暴露口
让仓库脚本改成支持公网 alias 自动配置

4.2 与现有上传页的关系

当前 minio.898311.xyz 是自定义上传页入口，并暴露：

/upload/api/buckets
/upload/api/upload

建议：

保持上传页现状，不强制改造上传页去兼容 S3 API
继续把它视为“上传页入口”，不是 MinIO API 入口
远程 clone / mc / 仓库恢复流程统一走：
- http://tx2.898311.xyz:9010

这样风险最低，也最利于长期维护。

5. 权限设计

5.1 为什么不能继续让远程机器用 root 账号

当前 root 凭证在 /etc/default/minio 中明文存在：

权限过大
一旦泄露，后果是全桶失控
不适合长期分发给外网开发机

因此：

root 账号只保留给本机运维和桶管理
远程 clone 恢复主方案必须使用普通受限账号

5.2 当前普通账号

已存在最小权限普通账号：

用户名：uploadrw0511a
授权桶：
- generalandroid
- blogfile
- upload
- tmp-image

对应策略文件：

main/blog/minio/minio-upload-rw-policy.json

该策略允许：

桶级权限

s3:ListBucket
s3:GetBucketLocation
s3:ListBucketMultipartUploads

对象级权限

s3:GetObject
s3:PutObject
s3:DeleteObject
s3:AbortMultipartUpload
s3:ListMultipartUploadParts

结论：

这个账号已经具备远程对象级恢复与维护所需的最小权限集合
不是只读账号，而是读写删均可
当前更接近“远程迁移/恢复统一账号”模型

5.3 当前已验证与未验证的权限边界

已实际验证成功：

mc ls uploadrw
向 tmp-image 上传对象
读取该对象
删除该对象

已实际验证失败：

mc ls uploadrw/blogimg
返回 Access Denied

这说明：

账号权限边界正在生效
该账号并不是全桶万能账号

5.4 当前必须补齐的最后验证

这一节原本用于定义把 uploadrw0511a 作为 GeneralAndroid 远程 clone 恢复主账号 之前所需的最后验证。

当前状态：这组验证已经完成，并已通过。

已执行过的关键命令包括：

1. 列桶对象

mc ls uploadrw/generalandroid

2. 上传测试对象

printf 'ga-check-2026-05-11\n' | mc pipe uploadrw/generalandroid/external-check/minio-uploadrw0511a-ga-test.txt

3. 读取测试对象

mc cat uploadrw/generalandroid/external-check/minio-uploadrw0511a-ga-test.txt

4. 删除测试对象

mc rm uploadrw/generalandroid/external-check/minio-uploadrw0511a-ga-test.txt

5. 权限边界回归检查

mc ls uploadrw/blogimg

5.5 验收结果与结论

本次外网实测结果如下：

列桶成功
- mc ls uploadrw/generalandroid 正常返回：books/ media/ releases/ tools/ traces/
上传成功
- 新的小测试文件成功写入：
  - generalandroid/external-check/minio-uploadrw0511a-ga-test.txt
读取成功
- mc cat 读回内容：
  - ga-check-2026-05-11
删除成功
- mc rm 成功
- 因桶开启版本化，返回为创建 delete marker，属于正常行为
权限边界仍然成立
- mc ls uploadrw/blogimg 继续返回 Access Denied

通过后可以正式下结论：

uploadrw0511a 已经满足远程机器对 generalandroid 桶的列、读、写、删需求，可以作为 GeneralAndroid 远程 clone 恢复主账号使用。

5.6 bootstrap 端到端验收结果

在脚本支持环境变量自动建 alias 后，已执行一轮真正的公网 bootstrap 端到端验收。

验收方式：

使用全新 alias：tempbootstrap
不依赖已有 local alias
通过环境变量提供：
- GENERALANDROID_MC_ALIAS
- GENERALANDROID_MC_ENDPOINT
- GENERALANDROID_MC_ACCESS_KEY
- GENERALANDROID_MC_SECRET_KEY
执行：

bash ./scripts/bootstrap_repo.sh

验收结果：

alias 自动创建成功：
- creating mc alias: tempbootstrap -> http://tx2.898311.xyz:9010
bootstrap 成功进入真实下载流程
至少一个真实大文件已经通过公网 endpoint 成功恢复：
- GPU负载优化.webm
该文件下载量约：488.76 MiB
下载耗时约：12m34s
实测速度约：662.98 KiB/s

结论：

公网 mc 主方案已经不仅是“权限上可行”，而且脚本链路也已跑通
当前剩余问题主要是外网下载性能优化，而不是接入可行性

6. 客户端恢复流程

6.1 远程机器体验目标

远程机器 clone 后，执行：

bash scripts/bootstrap_repo.sh

即可自动：

配置 mc alias
校验 MinIO 连接
恢复 manifest 中的大文件
校验 SHA256
校验当前大文件规则

6.2 建议的环境变量

GENERALANDROID_MC_ALIAS=uploadrw
GENERALANDROID_MC_ENDPOINT=http://tx2.898311.xyz:9010
GENERALANDROID_MC_ACCESS_KEY=uploadrw0511a
GENERALANDROID_MC_SECRET_KEY=<secret>

说明：

这些变量用于远程 clone 恢复，以及需要公网访问时的对象下载/维护
GENERALANDROID_MC_ALIAS 未设置时，脚本仍回退到现有 local 工作流
不再要求开发者预先手工执行 mc alias set local ...

6.3 `bootstrap_repo.sh` 改造方向

关键文件：

scripts/bootstrap_repo.sh

当前问题：

写死检查 mc alias local
写死提示 http://127.0.0.1:9000

建议改造为：

检查 python3
检查 mc
配置 core.hooksPath
读取环境变量：
- GENERALANDROID_MC_ALIAS
- GENERALANDROID_MC_ENDPOINT
- GENERALANDROID_MC_ACCESS_KEY
- GENERALANDROID_MC_SECRET_KEY

如果 alias 不存在，则自动执行：

mc alias set "$GENERALANDROID_MC_ALIAS" "$GENERALANDROID_MC_ENDPOINT" "$GENERALANDROID_MC_ACCESS_KEY" "$GENERALANDROID_MC_SECRET_KEY"

再调用：

python3 scripts/download_assets.py --all --alias "$GENERALANDROID_MC_ALIAS"

最后执行现有 validate_large_files.py

6.4 `download_assets.py` 改造方向

关键文件：

scripts/download_assets.py

当前问题：

默认 alias=local
不理解 endpoint/credential，只能消费已存在 alias

建议改造为：

保留 --alias 能力
新增环境变量回退逻辑：
- 如果用户没显式传 --alias
- 默认取 GENERALANDROID_MC_ALIAS
- 再没有才退回 local
不必把 endpoint/secret 直接塞给下载脚本
- alias 配置由 bootstrap 负责
- download 脚本只负责：
  - 读 manifest
  - mc cp
  - SHA256 校验

6.5 `upload_assets.py` 改造方向

关键文件：

scripts/upload_assets.py

建议：

继续保留当前运维上传用途
增加通过环境变量覆盖 alias 的能力
让运维机可以：
- 用本机 local
- 或外网 uploadrw / 更高权限专用 alias

7. 文档与配置收口

需要统一更新的关键文件

main/blog/gitlab/minio_migration_plan.md
- 将“公网长期方案”主路线改为：公网 mc 直连 + 受限账号
- 预签名服务降级为未来安全增强路线
main/blog/gitlab/minio_migration_progress.md
- 把“远程恢复尚未验证”的结论更新为：
  - 外网 mc 已通过真实 endpoint 验证
  - 当前只差 generalandroid 桶的对象级读写删除补验证
main/blog/gitlab/git_minimal_clone_plan.md
- 把阶段 A 的前提补充为：
  - 外网 mc 恢复链路稳定
  - generalandroid 桶远程对象级验证通过
main/blog/minio/MinIO 外网访问与 mc 使用说明.md
- 已经是当前最关键事实源
- 后续继续补充 generalandroid 桶实际验证结果
main/blog/minio/MinIO 部署现状与维护调研.md
- 明确：
  - minio.898311.xyz 是上传页
  - tx2.898311.xyz:9010 才是当前可用外网 API
scripts/bootstrap_repo.sh
- 从“本机 local alias”方案改为“公网 alias 自动配置”方案
scripts/download_assets.py
- 接受环境变量默认 alias

8. 推荐的分阶段实施

阶段 1：补齐 `generalandroid` 桶外网验证

先执行本文第 5.4 节中的 4 条命令，并按第 5.5 节标准验收。

这是把该方案定为长期主方案前的最后关键验证。

阶段 2：仓库脚本改造

改 bootstrap_repo.sh
改 download_assets.py
必要时改 upload_assets.py
把 alias/endpoint/credential 改为环境变量注入

阶段 3：远程 clone 恢复验证

在一台满足以下条件的机器验证：

没有 mc alias local
不依赖 127.0.0.1:9000
只通过：http://tx2.898311.xyz:9010

执行：

git clone <repo>
cd GeneralAndroid
export GENERALANDROID_MC_ALIAS=uploadrw
export GENERALANDROID_MC_ENDPOINT=http://tx2.898311.xyz:9010
export GENERALANDROID_MC_ACCESS_KEY=uploadrw0511a
export GENERALANDROID_MC_SECRET_KEY=<secret>
bash scripts/bootstrap_repo.sh

通过标准：

alias 自动配置成功
manifest 中对象恢复成功
SHA256 校验通过
不要求人工手敲 mc alias set local ...

阶段 4：再推进最小 clone

只有当公网 mc 直连恢复稳定后，才推进：

从当前工作区逐步移除已迁移大文件本体
最终执行 git filter-repo / BFG 历史瘦身

9. 未来增强方案（不是当前主线）

如果后续出现这些问题：

凭证分发难管理
需要更细粒度审计
不希望客户端持有任何 MinIO 密钥
要把“下载”和“上传/维护”权限进一步隔离

再进入增强路线：

新增预签名下载服务
客户端改为通过短时有效 URL 下载
普通开发机不再持有 MinIO 账号密码

但基于当前事实，这条路线应视为第二阶段升级方案，而不是第一阶段必须做的前提。

10. 最终结论

当前最关键的不是再额外设计一套全新的下载服务，而是：

确认 uploadrw0511a 对 generalandroid 桶的真实外网对象级权限
把当前脚本从本机 local alias 模型改成公网 alias 自动配置模型
在公网 mc 直连恢复稳定后，再推进历史清理，实现最小 clone

这样做的好处是：

完全复用现有 MinIO 与 mc 脚本体系
不推倒当前已经跑通的迁移流程
不向开发者发 root 凭证
改造成本低，见效快
仍为未来预签名服务保留升级空间

Quartz 4

Explorer

public_minio_remote_clone_plan

GeneralAndroid 公网 MinIO 接入与远程 Clone 长期方案

1. 目标

2. 当前现状（基于已确认信息）

2.1 现有 MinIO 本体

2.2 当前公网 MinIO API 入口

2.3 当前不能用的域名

2.4 当前仓库侧能力

3. 主方案结论

3.1 主方案

3.2 为什么它现在优先于预签名服务

4. 如何与现有 MinIO 打通

4.1 与现有 MinIO 本体的关系

4.2 与现有上传页的关系

5. 权限设计

5.1 为什么不能继续让远程机器用 root 账号

5.2 当前普通账号

桶级权限

对象级权限

5.3 当前已验证与未验证的权限边界

5.4 当前必须补齐的最后验证

1. 列桶对象

2. 上传测试对象

3. 读取测试对象

4. 删除测试对象

5. 权限边界回归检查

5.5 验收结果与结论

5.6 bootstrap 端到端验收结果

6. 客户端恢复流程

6.1 远程机器体验目标

6.2 建议的环境变量

6.3 bootstrap_repo.sh 改造方向

6.4 download_assets.py 改造方向

6.5 upload_assets.py 改造方向

7. 文档与配置收口

需要统一更新的关键文件

8. 推荐的分阶段实施

阶段 1：补齐 generalandroid 桶外网验证

阶段 2：仓库脚本改造

阶段 3：远程 clone 恢复验证

阶段 4：再推进最小 clone

9. 未来增强方案（不是当前主线）

10. 最终结论

Graph View

Table of Contents

6.3 `bootstrap_repo.sh` 改造方向

6.4 `download_assets.py` 改造方向

6.5 `upload_assets.py` 改造方向

阶段 1：补齐 `generalandroid` 桶外网验证