Prepare build-time static asset syncing without touching page templates

Constraint: Static images need to come from remote sources before log sync and build
Rejected: Per-file source mapping | directory-grouped manifests are easier to maintain
Confidence: high
Scope-risk: narrow
Directive: Prefer grouped target_dir manifests and keep page-facing paths stable
Tested: npm run assets:sync; npm run build; bash -n scripts/deploy-homepage.sh; npx tsc --noEmit --pretty false --project tsconfig.json
Not-tested: Real Seafile download against production URLs

docs/linux-cron-deploy.md

@@ -2,8 +2,10 @@
 
 适用于当前这套流程：
 
+- 静态图片可由远端 URL 拉取
 - log 由另一个服务生成
 - log 落到宿主机目录
+- 宿主机先按清单同步静态资源到仓库目标目录
 - 宿主机定时任务复制 log 到 homepage 仓库
 - 宿主机执行 `npm run rebuild`
 - 宿主机执行 `docker compose up -d --build homepage`
@@ -23,11 +25,13 @@ scripts/deploy-homepage.sh
 | 变量 | 默认值 | 说明 |
 |---|---|---|
 | `LOG_SOURCE_DIR` | `/home/basil/bot/data/git-summary` | 日志生成服务写入的源目录 |
+| `STATIC_ASSET_MANIFEST` | `src/content/static-assets/index.json` | 静态资源下载清单 |
 | `SITE_DIR` | `/home/basil/source/personal-homepage` | 个人主页仓库根目录 |
 | `LOG_TARGET_DIR` | `$SITE_DIR/src/content/logs` | 复制后的日志目标目录 |
 | `DOCKER_COMPOSE_FILE` | `$SITE_DIR/docker-compose.yml` | Compose 文件 |
 | `DOCKER_SERVICE_NAME` | `homepage` | 要重建/重启的服务名 |
 | `RSYNC_DELETE` | `false` | 同步时默认不删除旧日志 |
+| `RUN_STATIC_ASSET_SYNC` | `true` | 默认先按清单同步静态资源 |
 | `RUN_LOCAL_REBUILD` | `true` | 默认先在宿主机执行 `npm run rebuild` |
 | `LOCK_FILE` | `/tmp/personal-homepage-deploy.lock` | 防止重复执行的锁文件 |
 
@@ -41,9 +45,10 @@ scripts/deploy-homepage.sh
 
 1. 检查目录与命令是否存在
 2. 获取锁文件，避免重复执行
-3. 把 `LOG_SOURCE_DIR` 同步到 `LOG_TARGET_DIR`
-4. 进入 `SITE_DIR` 执行 `npm run rebuild`
-5. 进入 `SITE_DIR` 执行：
+3. 按 `STATIC_ASSET_MANIFEST` 下载静态资源到目标目录
+4. 把 `LOG_SOURCE_DIR` 同步到 `LOG_TARGET_DIR`
+5. 进入 `SITE_DIR` 执行 `npm run rebuild`
+6. 进入 `SITE_DIR` 执行：
 
 ```bash
 docker compose -f "$DOCKER_COMPOSE_FILE" up -d --build "$DOCKER_SERVICE_NAME"
@@ -68,6 +73,12 @@ RSYNC_DELETE=true \
 ./scripts/deploy-homepage.sh
 ```
 
+如果这次不想拉远端图片：
+
+```bash
+RUN_STATIC_ASSET_SYNC=false ./scripts/deploy-homepage.sh
+```
+
 如果你只想做 log 同步 + Docker 重建，不想先在宿主机跑一次 `npm run rebuild`：
 
 ```bash
@@ -114,6 +125,7 @@ RUN_LOCAL_REBUILD=false ./scripts/deploy-homepage.sh
 
 当前建议：
 
+- 静态图片清单维护在 `src/content/static-assets/index.json`
 - `LOG_SOURCE_DIR` 作为日志服务的宿主机挂载目录
 - `SITE_DIR` 直接指向 homepage 仓库根目录
 - 优先先手动跑通一次：
@@ -123,3 +135,28 @@ RUN_LOCAL_REBUILD=false ./scripts/deploy-homepage.sh
 ```
 
 确认没问题后再挂 cron。
+
+静态资源清单推荐写成按目录分组的格式：
+
+```json
+[
+  {
+    "target_dir": "public/images/projects",
+    "files": [
+      {
+        "url": "https://example.com/seafile-cover.png",
+        "filename": "personal-homepage.png"
+      }
+    ]
+  },
+  {
+    "target_dir": "public/images/gallery",
+    "files": [
+      {
+        "url": "https://example.com/seafile-gallery-1.jpg",
+        "filename": "gallery-1.jpg"
+      }
+    ]
+  }
+]
+```