feat: 数据库导出文档

2026-10-20 17:29:10 +08:00
parent 48c45ada89
commit 69ec885803
9 changed files with 2299 additions and 4 deletions
@@ -2,6 +2,115 @@

 独立 Node.js 脚本项目，使用官方 qiniu SDK 7.15.2。入口命令在 doodle-store 根目录执行。只复制本地文件到已存在的七牛空间，不创建空间、不删除/覆盖远端对象、不修改数据库或业务 URL。

+## 前置步骤：通过 tcb 下载云存储备份
+
+更新日期：2026-10-20。本节记录日后重新导出资源的操作流程；本次编写文档未登录云环境或执行下载。已有备份位于 `/Users/joey-xd/sites/doodle/doodle-assets/cloud_backup`，无需为了使用同步工具重复下载。
+
+流程为：`原小程序云存储 → tcb 下载到本地 → SOURCE_DIR 指向备份根目录 → asset-sync 上传七牛 → 按需回填数据库`。这里下载的是云存储文件，不是数据库记录、云函数代码或完整环境备份。
+
+当前线上版小程序仍使用旧云开发，原预拉取模式、地址、生成链路和全部旧云函数必须保留。本流程只读取源文件，不删除源文件、不调整存储权限、不停用云函数或定时任务；后续的七牛同步也不会替代旧线上服务。
+
+### 1. 安装并检查 CloudBase CLI
+
+本机已安装 `@cloudbase/cli`，本次通过版本及帮助命令核对的版本为 **3.8.7**。新机器可安装同一版本复现操作；已有 tcb 时先检查版本，不必重复安装：
+
+```bash
+# 仅新机器未安装时执行
+pnpm add -g @cloudbase/cli@3.8.7
+
+tcb --version
+tcb storage download --help
+```
+
+使用当前的空格形式 `tcb storage download`；旧文档可能使用冒号形式 `tcb storage:download`。升级 CLI 后先重新查看帮助。参考 [官方安装说明](https://docs.cloudbase.net/cli-v1/install)。
+
+### 2. 登录并确认原云环境
+
+以下 tcb 命令在 `doodle-mini` 目录执行，七牛同步命令则在 `doodle-store` 根目录执行：
+
+```bash
+cd /Users/joey-xd/sites/doodle/doodle-mini
+
+# 按终端提示在浏览器中完成授权
+tcb login
+
+# 核对账号能访问的环境
+tcb env list
+
+# 显式指定原小程序环境，避免误用其他项目的默认环境
+tcb storage list -e cloud1-9gifs7a2756e2c87
+```
+
+环境 ID 来自 `doodle-mini/cloudbaserc.json`。如果更换源环境，应重新核对并替换下列命令中的 ID；不要直接复制 `cloud://` 文件 ID 作为环境 ID。
+
+授权账号必须能管理原小程序云环境的云存储。微信 AppSecret 和七牛 AK/SK 均不是 tcb 登录凭据。若列表中看不到原环境，先核对账号权限及环境所在地域；必要时按实际地域使用全局 `--region` 参数，不为下载另建环境或改变权限。
+
+### 3. 下载全部资源
+
+每次新备份使用独立目录，保留已有 `cloud_backup`。在同一个终端依次执行：
+
+```bash
+DOODLE_CLOUD_BACKUP="/Users/joey-xd/sites/doodle/doodle-assets/cloud_backup-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$DOODLE_CLOUD_BACKUP"
+
+tcb storage download / "$DOODLE_CLOUD_BACKUP" --dir -e cloud1-9gifs7a2756e2c87
+```
+
+`/` 表示下载云存储全部文件，`--dir` 表示目录下载。云端路径使用相对对象路径，不使用临时 HTTPS 链接。命令依据 [官方云存储下载说明](https://docs.cloudbase.net/cli-v1/storage)。本项目源端为旧小程序云环境，不因新后端采用 PostgreSQL 就改用 `storage objects` 等 PG 环境命令。
+
+如果只补下载题型预览，可改用目录下载，目标仍保留 `assets/previews` 层级；这是全量下载的替代方式，无需两者都执行：
+
+```bash
+mkdir -p "$DOODLE_CLOUD_BACKUP/assets/previews"
+tcb storage download assets/previews "$DOODLE_CLOUD_BACKUP/assets/previews" --dir -e cloud1-9gifs7a2756e2c87
+```
+
+其他目录按实际云端清单选择，例如 `assets/fonts`、`assets/materials`、`content`、`user-avatars`。云端仍在写入，目录下载不是某个时间点的原子快照；下载失败或重试后都要核对实际文件，不把命令退出成功等同于完整备份，也不将旧目录混入新备份来掩盖缺失。
+
+### 4. 核对目录并连接七牛同步
+
+备份根目录应保留云端相对路径，例如：
+
+```text
+cloud_backup-<时间>/
+├── assets/
+│   ├── fonts/
+│   ├── materials/
+│   └── previews/
+│       ├── chinese/
+│       ├── english/
+│       ├── math/
+│       ├── papers/
+│       ├── pinyin/
+│       └── puzzle/
+├── content/
+│   └── page-config.json
+└── user-avatars/
+```
+
+这只是路径示例，不代表每个目录必有文件；以本次云端列表和下载结果为准。不要多套一层环境 ID、重复的 previews 目录，或直接把文件平铺到备份根目录，否则七牛对象 key 会变化。
+
+抽查图片能打开、字体文件非空、`content/page-config.json` 能解析，并对照云端列表核对数量和大小。历史备份为 62 个文件，其中预览 51 个、头像 7 个、字体/素材/首页配置/demo 各 1 个；这是旧备份基线，不是未来下载必须满足的固定数量。demo 等其他对象也应保留原路径，不限于上方示例目录。
+
+检查完成后，将 `packages/asset-sync/.env` 的 `SOURCE_DIR` 手动改为新备份的实际绝对路径；继续使用已有备份时保持原值：
+
+```dotenv
+SOURCE_DIR=/Users/joey-xd/sites/doodle/doodle-assets/cloud_backup
+```
+
+不要把包含 `$DOODLE_CLOUD_BACKUP` 的字符串直接写进 `.env`；该配置需要实际路径。`SOURCE_DIR` 指向包含 `assets`、`content`、`user-avatars` 的根目录，不是 `assets/previews` 子目录。备份目录不应存放下载日志、清单或报告，这些普通文件也可能被同步工具扫描上传。
+
+回到 `doodle-store`，先预演并核对报告中的相对路径、目标 key 和文件数量，再正式上传：
+
+```bash
+cd /Users/joey-xd/sites/doodle/doodle-store
+
+pnpm assets:sync
+pnpm assets:sync --apply
+```
+
+本项目当前使用 `QINIU_KEY_PREFIX=doodle-assets/`，补同步已有资源时应保持该值，并与 server 配置一致；下方配置段中的 `doodle/` 是工具默认示例，不能在补同步时误换前缀。同步与数据库回填是独立步骤，详见本文末尾。
+
 ## 配置

 已生成本机 `packages/asset-sync/.env`，源目录配置为：