# 镜像同步方案（外部代码库 → git.vanusys.com）

> 版本：v1 · 2026-08-16 · 状态：**待评审**
> 目标：把我们关注的 GitHub 等外部代码库**定期镜像**到 git.vanusys.com，让内部服务器（宁波、局域网等无法直连 GitHub 的环境）也能直接拉取，并在合集中用子模块统一引用。

## 架构

```
GitHub (facebook/astryx 等上游)
      │  ① 定期 fetch（香港服务器可直连 / 或本机 openssl 后端）
      ▼
镜像工作区 mirrors/<name>.git（本机或香港服务器上的裸仓库）
      │  ② push --mirror
      ▼
git.vanusys.com/VanuSystems/<mirror 命名>（内部镜像仓库）
      │  ③ submodule 引用
      ▼
codebase-collection（合集，内部全链路可达）
```

- **镜像层**：每个关注仓库一个镜像，与上游保持全量历史同步（`git push --mirror` 同步所有分支/标签）。
- **合集层**：`codebase-collection` 的 submodule **只指向内部镜像地址**，不直接指向 GitHub，保证国内/内网 clone 合集时无需外网。
- 子模块默认记录某个提交引用；需要跟随上游时在合集中执行 `git submodule update --remote` 并提交（手动，避免自动漂移）。

## 同步脚本（草案）

### 方式 A：本机 Windows 计划任务（推荐先用这个）

`tools/sync-mirrors.ps1`（见下），配合 Windows 任务计划程序每日/每周运行。
注意：本机 schannel 后端在受限环境有 TLS 问题，脚本统一显式指定 `-c http.sslBackend=openssl`。

### 方式 B：香港服务器 cron（154.21.200.211，可直连 GitHub）

待服务器上配置 git 凭据（专用镜像账号或 token）后，用 bash 版脚本 + cron（如每天 03:00）：

```bash
# 示例：/root/mirror-sync/astryx.sh
cd /root/mirror-sync/astryx.git
git fetch --prune origin '+refs/*:refs/*'
git push --mirror https://<token>@git.vanusys.com/VanuSystems/facebook-astryx.git
```

## 待确认事项

1. **git.vanusys.com 服务类型**（Gitea / GitLab / 其他）：
   - 若支持**平台原生镜像**（Gitea 迁移/镜像、GitLab mirroring），可直接在网页上建镜像仓库并启用"定时同步"，无需自建脚本 —— 这是最省事的路径，需确认。
   - 若不支持，采用上述脚本方案。
2. **镜像仓库归属与命名**：`VanuSystems/facebook-astryx` 还是单独 `mirrors/` 组织？命名是否用 `facebook-astryx` 格式？
3. **同步频率**：每日 / 每周 / 手动？
4. **执行位置**：本机计划任务（先跑通）还是香港服务器 cron（长期更稳）？
5. **首次建仓**：需要有人登录 git.vanusys.com 网页创建空镜像仓库（我的执行环境无法完成 HTTPS 认证）。

## 收录清单登记表

| 上游仓库 | 镜像地址（计划） | 分类 | 状态 |
|---------|----------------|------|------|
| https://github.com/facebook/astryx | git.vanusys.com/VanuSystems/facebook-astryx | frontend | 待建远程镜像 |