update: README.md

2026-08-14 19:30:25 +08:00
parent 139f2c02c1
commit 76af0f763c
2 changed files with 328 additions and 100 deletions
@@ -0,0 +1,242 @@
+# Handover — 近期变更与待办
+
+面向接手运维 / 二次开发的人。记录最近几次 commit 的动机、改动范围、未尽事项，
+以及「线上有旧数据时怎么过渡」。详细架构见 `ARCHITECTURE.md`；本仓库的开发规约
+见 `DEVELOP.md`。
+
+---
+
+## 1. 最近 5 个 commit（按时间倒序）
+
+### `139f2c0` — fix: delete error（trash 路径统一 + 删除后 DB 字段更新）
+
+**背景**：删除文件统一改为移动到 trash 桶后，存在三个连锁 bug：
+
+1. **local 模式 trash 路径双重 `data`**：`trash_key = f"{item.bucket_name}/{item.object_key}"`。
+   local 模式下 `bucket_name` 是绝对路径（如 `/data/workspace`），最终落到
+   `data/trash/data/workspace/{ws_id}/{user_id}/...`。
+2. **s3 模式桶名 / 路径名错位**：`.env` 之前是 `S3_WORKSPACE_BUCKET=workspaces`（复数），
+   代码 default / `PURPOSE_BUCKETS` / `USAGE_TYPE_TO_PURPOSE` 全部是单数 `workspace`。
+   跨环境部署产生 `KeyError: 'workspaces'`（软删时 `object_stores[item.bucket_name]` 抛错）。
+3. **软删后 `storage_objects` 路径字段未更新**：只翻 `trash_key` / `object_status` /
+   `deleted_at` / `is_deleted`，`bucket_name` / `object_key` / `storage_uri` 仍指向源，
+   与物理位置不一致，`purge_trash_object` 必须读旧 `trash_key` 才能定位 trash 文件。
+
+**改动**（5 个文件，44+/24-）：
+
+| 文件 | 改动 |
+|---|---|
+| `backend/src/backend/services/storage.py` | `trash_key = f"{source_purpose}/{item.object_key}"`；软删成功后更新 `bucket_name` / `object_key` / `storage_uri` 指向 trash 位置 |
+| `backend/src/backend/storage_api.py` | `restore_object` 用 `item.object_key` 直接定位 trash，按 `/` 拆 `source_purpose`，写回源桶，更新 DB 字段指回 source；`purge_trash_object` 用 `(actual_bucket_name("trash"), item.object_key)` 删除，加 `bucket_name != trash` 的 409 防御 |
+| `common/src/common/storage/factory.py` | 引入 `USAGE_TYPE_TO_PURPOSE` 字典（替代 `storage_api.py` 的本地定义） |
+| `common/src/common/storage/__init__.py` | 导出 `USAGE_TYPE_TO_PURPOSE` |
+| `.env.example` | `S3_WORKSPACE_BUCKET=workspaces` → `workspace`、`S3_VERSION_BUCKET=versions` → `version`、`S3_RUN_LOG_BUCKET=run-logs` → `run-log`（统一单数） |
+
+**注意点**：
+
+- `workspaces_root()` 函数名 / `WORKSPACES_ROOT` 环境变量名不动（这是 path 概念，不是 bucket 名）。
+- `Workspaces` 数据库表名 / `auth.py` 的 `"workspaces"` JSON key（API 响应）不动（这些不是桶名）。
+- `visibility="workspace"` 是 ACL Literal，不动。
+
+### `2e070fa` — fix: pre check（前端 script 创建/上传前置校验）
+
+`CreateScriptModal.tsx`（+25 行）— 文件名 / workspace_id / 类型前置校验。
+`ScriptsPage.tsx`（+1）/ `scriptWorkspaceStore.ts`（+19/-10）— store action 增加
+`precheck` 步骤，提前拦截无效请求。
+
+### `5c5dec9` — fix: allows_same_name_different_parent
+
+允许同名 script 出现在不同父目录下。`scripts.py`（+32/-?）、`services/storage.py`、
+`storage_api.py` 微调；`test_scripts.py` 新增 57 行回归测试。
+
+### `5d49ff5` — fix: file upload error（大重写）
+
+修复 file upload 路径上一连串 schema / API / 上传流程的不一致。改动面最大
+（14 个文件，872+/604-）：
+
+- 新增索引 / 调整唯一约束（去掉了 scripts 和 data_resources 的旧 unique index）
+- 把多个小 migration 合并进 `e1f2a3b4c5d6_rebuild_baseline.py` 一份大 baseline
+- `resources.py` / `scripts.py` 上传流程对齐
+- `test_resources.py` / `test_scripts.py` 大量回归
+- `API.md` 增加 3 行
+
+### `c65d6dc` — fix: build error
+
+`backend/Dockerfile` 单行修复（镜像构建报错）。
+
+---
+
+## 2. Trash 修复详解（commit `139f2c0`）
+
+### 2.1 修复后的语义
+
+- **trash_key**：`f"{source_purpose}/{item.object_key}"`。`source_purpose` 来自
+  `USAGE_TYPE_TO_PURPOSE[item.usage_type]`，与 `item.bucket_name` 解耦 —
+  避免 local 模式绝对路径泄漏 + 命名错位风险。
+- **软删后 `storage_objects` 行的 7 个字段同步**：
+
+  | 字段 | 软删前 | 软删后 |
+  |---|---|---|
+  | `bucket_name` | 源桶 | trash 桶 |
+  | `object_key` | 源 key | trash key |
+  | `trash_key` | NULL | trash key |
+  | `storage_uri` | 源 URI | trash URI（`build_storage_uri` 重建） |
+  | `object_status` | `available` | `deleted` |
+  | `is_deleted` | `0` | `1` |
+  | `deleted_at` | NULL | `<utcnow>` |
+
+- **物理文件落点**：
+
+  | 模式 | 源文件（被删） | trash 文件（新落） |
+  |---|---|---|
+  | S3 | `s3://<source_bucket>/<key>` | `s3://trash/<source_purpose>/<key>` |
+  | local | `<LOCAL_STORAGE_BASE_DIR>/<source_purpose>/<key>` | `<LOCAL_STORAGE_BASE_DIR>/trash/<source_purpose>/<key>` |
+
+  `source_purpose` ∈ `{workspace, version, run_log}`。
+
+### 2.2 `restore_object` 反向流程
+
+```python
+data = await object_stores[trash_bucket].get(item.object_key)        # 从 trash 读
+source_purpose, _, source_key = item.object_key.partition("/")       # 拆 source_purpose
+target_bucket = actual_bucket_name(source_purpose)                    # 还原目标桶
+await object_stores[target_bucket].put(source_key, data)              # 写回源
+
+item.bucket_name = target_bucket
+item.object_key  = source_key
+item.storage_uri = build_storage_uri(target_bucket, source_key)
+# trash_key 保留不动 → 未来 reaper 可据此清理 trash 里的 orphan 副本
+item.object_status = "available"
+item.deleted_at = None
+```
+
+**trash 文件不会被 restore 主动删除**（保留现有安全语义：restore 失败时
+数据仍在 trash 里有兜底）。未实现的 reaper 未来可扫
+`object_status='available' AND trash_key IS NOT NULL` 清理 orphan。
+
+### 2.3 `purge_trash_object` 防御
+
+加 409 防御：`if item.bucket_name != actual_bucket_name("trash"): raise 409`。
+避免误删源数据（用 `item.object_key` 直接删 trash 文件，不再读旧 `trash_key`）。
+
+### 2.4 USAGE_TYPE_TO_PURPOSE 提升到 common 层
+
+`backend/storage_api.py` 与 `backend/services/storage.py` 都依赖这个映射。
+提到 `common/storage/factory.py` 后两边都 `from common.storage import USAGE_TYPE_TO_PURPOSE`，
+避免互相 import 循环。
+
+---
+
+## 3. 线上数据兼容（重要）
+
+修复后**新行为对 DB 里已有的旧行不感知**。如果部署环境之前是
+`S3_WORKSPACE_BUCKET=workspaces`（复数）且已上传过文件，
+`storage_objects.bucket_name` 列里会有复数残留。新代码 default 是单数，
+`object_stores` dict key 也是单数，访问旧行仍会 `KeyError: 'workspaces'`。
+
+**部署新代码前必须先跑一次数据修复 SQL**（先 SELECT 看数量，确认是同一个 deployment）：
+
+```sql
+-- 1. 先看现状（按 backend 区分）
+SELECT storage_backend, bucket_name, COUNT(*)
+FROM storage_objects
+WHERE object_status = 'available'
+GROUP BY storage_backend, bucket_name
+ORDER BY storage_backend, bucket_name;
+
+-- 2a. S3 部署：把复数残留修正成单数
+UPDATE storage_objects
+SET bucket_name = 'workspace'
+WHERE bucket_name = 'workspaces'
+  AND object_status = 'available';
+
+-- 2b. local 部署：把绝对路径里的复数残留修正成单数
+UPDATE storage_objects
+SET bucket_name = '/data/workspace'
+WHERE bucket_name = '/data/workspaces'
+  AND object_status = 'available';
+```
+
+> **只改 `available` 行**；`deleted` 行已经在 trash 里、bucket_name 会被新代码改写，无需处理。
+> 如果同时改 `version` / `run_log` 桶残留，按相同模式跑。
+
+---
+
+## 4. 本地验收清单
+
+```bash
+# 1. 语法
+uv run python -m compileall common/src backend/src runtime/src schedule/src
+
+# 2. 测试
+uv run --package backend pytest backend/tests -q
+# 期望：30 passed
+
+# 3. 命名一致性
+grep -rn '"workspaces"\|"versions"\|"run-logs"' \
+  --include='*.py' --include='*.yml' --include='*.env*' \
+  backend/src common/src docker-compose.yml .env .env.example 2>/dev/null
+# 期望：除 `__tablename__ = "workspaces"`（DB 表名）和 `auth.py` 的 JSON key 外，零结果
+
+# 4. 单复数对齐
+grep -n 'S3_WORKSPACE_BUCKET\|S3_VERSION_BUCKET\|S3_RUN_LOG_BUCKET\|S3_TRASH_BUCKET' \
+  .env.example
+# 期望：全部 = 单数（workspace / version / run-log / trash）
+```
+
+---
+
+## 5. 回归测试覆盖
+
+| 场景 | 触发方式 | 期望 |
+|---|---|---|
+| 同名 script 不同父目录 | `test_soft_delete_object_sets_is_deleted` 旁边的新测试 | 两条 row 同名共存 |
+| 软删 → 物理文件落到 trash 桶的 `source_purpose/{key}` | 手工：上传 → 删 → `mc ls s3/trash/` | 文件在；源桶里已删 |
+| 软删后 `storage_objects` 7 字段同步 | 软删后 `SELECT * FROM storage_objects WHERE storage_object_id=...` | 见 §2.1 表格 |
+| `restore_object` 把 trash 文件写回源桶 | 软删 → restore → 查源桶 | 源桶恢复；trash 文件保留（orphan） |
+| `purge_trash_object` 拒绝误删源数据 | 手工：把 `bucket_name` 改成源桶后调 purge | 409 |
+
+---
+
+## 6. 监控项（建议加）
+
+1. `storage_objects` 行 `bucket_name` 与 `actual_bucket_name(purpose)` 不一致的比例
+   （按 `usage_type` 分组 COUNT）。生产环境应长期趋近于 0。
+2. `object_status='deleted'` 但 `bucket_name != actual_bucket_name('trash')` 的行数 —
+   应为 0（软删失败回滚残留）。
+3. trash 桶目录大小 vs `object_status='deleted'` 行数（孤儿文件比例）。
+   没实现 reaper 前这个会单调上升。
+
+---
+
+## 7. 已知未实现项
+
+- **Trash reaper**：`s3_trash_retention_days` 已声明，但代码没有扫表清理。
+  `restore_object` 故意保留 trash 文件作 orphan，等 reaper 兜底。
+  第一次实现建议在 `schedule/src/schedule/` 加一个 tick job：
+  ```sql
+  SELECT storage_object_id FROM storage_objects
+  WHERE deleted_at < UTC_TIMESTAMP() - INTERVAL :retention_days DAY
+    AND object_status = 'deleted'
+  LIMIT 100;
+  ```
+  然后调 `/internal/v1/admin/trash/purge`。
+- **跨 backend trash 兼容**：当前只在 `item.storage_backend == settings.storage_backend`
+  的行上做物理移动。异构 backend 的旧行（少）软删时只翻 DB 状态，trash 文件实际没移动。
+  远程 8.153.151.51:8890 应该都是同一 backend，目前无影响。
+- **历史 trash_key 兼容读**：新代码用 `item.object_key` 读 trash，**不**回退到
+  `item.trash_key`。如果迁移前有按旧 `trash_key = f"{bucket_name}/{object_key}"`
+  写入的已删行，`object_key` 还是源 key，restore 会找不到 trash 文件（404）。
+  处理：在 `restore_object` 加 fallback — 先按 `item.object_key` 试，失败再按 `item.trash_key`
+  试一次（兼容窗口期）。建议在 reaper 上线后删除 fallback。
+
+---
+
+## 8. 仍未合并到 develop 的本地改动
+
+```text
+M frontend/vite.config.ts       (4+/2-)
+?? data/                        (untracked — 本地 docker volume 残留，可忽略)
+```
+
+`frontend/vite.config.ts` 的改动不在本次 trash 修复范围内，等下次 commit 一起提。