docs: 同步 P1/P2——DATA_MODEL 重写引擎/建表/迁移/唯一索引/覆盖清单章节，ARCHITECTURE 更新装配顺序与数据库决策
- DATA_MODEL §1: 引擎改为「MySQL（正式）/SQLite（回退）」+ 连接参数 + 环境与库名绑定表； 表清单注明 12 张全部是 ORM 模型（原 5 张裸表已并入） - §4 重写: 建表/补列以模型为准（create_all + _sync_columns），补 §4.2.1 说明 排序规则为何必须 utf8mb4_bin；唯一索引补 MySQL 的「生成列 + 唯一索引」方案 - §5 补 deployment_env/deployment_id/deployment_claimed_at 三个键 - §6 覆盖清单改为「由 metadata 派生」，红线只剩补 TABLE_LABELS - ARCHITECTURE: 装配阶段 B/C/D 更新（db_config 装配 + 环境校验横幅）、 §3.2 并发描述按方言改写、§7 数据库决策表改写
This commit is contained in:
+6
-6
@@ -75,9 +75,9 @@
|
||||
|
||||
| 阶段 | 位置 | 做了什么 |
|
||||
|------|------|---------|
|
||||
| **B** | `:28-41` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；`SQLALCHEMY_DATABASE_URI=sqlite:///data/users.db`；`LoginManager` + `login_view="auth.login"` |
|
||||
| **C** | `:43-50` | **恢复任务消费** `consume_pending_restore()` —— 必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）。失败只记日志，不阻塞启动 |
|
||||
| **D** | `:53-61` | `init_db(app)`（建表 → 版本化迁移 → 默认管理员 → 旧 JSON 迁移）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
|
||||
| **B** | `:28-58` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；**数据库目标由 `core/db_config` 装配**（`.env` 的 `DEPLOY_ENV`/`DB_*` → URI + 引擎参数），配置错直接 `SystemExit(2)`；`LoginManager` + `login_view="auth.login"` |
|
||||
| **C** | `:60-67` | **恢复任务消费** `consume_pending_restore()`。SQLite 时代它必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）；改用 MySQL 后这一步的语义会变成"启动期事务替换"，见 §7 |
|
||||
| **D** | `:69-80` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
|
||||
|
||||
### 2.3 阶段 E~G：蓝图、巡检调度器、真正启动
|
||||
|
||||
@@ -123,7 +123,7 @@
|
||||
| `_scan_lock` / `_stop_event` | `core/device_discovery.py` | 定时/手动扫描互斥 | `acquire(blocking=False)` |
|
||||
| `_status_cache_lock` | `core/task_manager.py` | 状态缓存（TTL 5s） | 避免 `/api/status` 每次都查库 + adb |
|
||||
|
||||
**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context + SQLite WAL + `busy_timeout=5000`"。
|
||||
**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。
|
||||
|
||||
### 3.3 错峰与心跳
|
||||
|
||||
@@ -319,14 +319,14 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
|
||||
|
||||
| 决策 | 为什么 | 代价 / 注意 |
|
||||
|------|--------|------------|
|
||||
| **SQLite + WAL** 而非 MySQL/PG | 单机部署、零运维；WAL 支持多线程读写 | 写并发有限；必须设 `busy_timeout`；`data/` 不入 git |
|
||||
| **数据库走 MySQL，SQLite 仅作回退** | 多环境（dev 库 / 正式库）需要同一套代码指向不同库；备份/恢复也不再受"文件被占用"掣肘 | 多一套连接配置与防混库校验（`core/db_config.py`）；`DB_HOST` 为空时回退 SQLite，生产禁止静默回退 |
|
||||
| **threading 而非 asyncio** | uiautomator2 是同步阻塞库；每设备一线程模型直观 | 线程数随设备数增长；跨线程访问 DB 必须自推 app context |
|
||||
| **状态放内存** 而非落库 | 状态每秒都变，落库纯属浪费 | 重启丢失运行中状态（进程重启 = 任务终止） |
|
||||
| **蓝图按功能域拆包** | `web_server.py` 只做装配，路由就近维护 | 拆包易出现 import 遗漏 → 用 `scripts/regression_test.py` 兜底 |
|
||||
| **单页应用 + 全局脚本** | 无构建步骤、无 npm 依赖，改完强刷即生效 | 11 个文件共享全局作用域，需手工维护加载顺序 |
|
||||
| **任务类型注册表** | 新增任务类型不动调度器 | 删改类型要做兼容（未知类型必须显式报错，不能静默） |
|
||||
| **自建设备池**（不用 STF） | 规避共享 adb transport 的历史坑，清单可控 | 需自己处理在线状态、型号、自动发现 |
|
||||
| **备份"重启生效"** | Windows 无法替换被持有的 db；调度器/worker 持有内存态 | 导入后必须重启（在 `init_db` 之前消费恢复任务） |
|
||||
| **备份"重启生效"** | 调度器 / worker / 设备池都把任务与设备**缓存在内存**里，整库替换后内存副本全部失效 | 导入后必须重启（重启时消费恢复任务）。SQLite 时代还有"Windows 无法替换被持有的文件"这层原因，改用 MySQL 后只剩内存态这一层 |
|
||||
| **uiautodev 独立子进程** | 元素抓取是重活，隔离崩溃、可单独重启 | 固定端口 20242；PID 文件防重复拉起（杀之前必须校验 cmdline，防误杀同容器进程） |
|
||||
| **MCP 独立端口** | 外部 AI 用标准协议接入，不侵入 Web 会话 | MCP 端点自身无鉴权，靠网络隔离；写操作用开关门控 |
|
||||
|
||||
|
||||
+96
-65
@@ -2,7 +2,7 @@
|
||||
|
||||
> 适用读者：改后端 / 排数据问题的开发者与运维。
|
||||
> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（运行时架构）、[DEPLOY.md](DEPLOY.md) §数据备份（备份覆盖红线）、[API.md](API.md)（消费这些数据的接口）。
|
||||
> **表结构以 `core/models.py` 与各模块的建表 SQL 为准**，本文是它们的映射说明。
|
||||
> **表结构以 `core/models.py` 的 ORM 模型为唯一准**（2026-09-13 起各模块的裸建表 SQL 已全部并入模型），本文是它们的映射说明。
|
||||
|
||||
---
|
||||
|
||||
@@ -10,32 +10,49 @@
|
||||
|
||||
| 项 | 值 |
|
||||
|----|----|
|
||||
| 引擎 | SQLite（单文件 `data/users.db`） |
|
||||
| driver | Flask-SQLAlchemy（SQLAlchemy 2.x） |
|
||||
| 连接 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL` |
|
||||
| 建表方式 | ① 模型表：`db.create_all()`；② 版本化迁移 `SCHEMA_MIGRATIONS`；③ 幂等原生 `CREATE TABLE IF NOT EXISTS` |
|
||||
| 主库文件 | `data/users.db`（运行时另有 `-wal` / `-shm`） |
|
||||
| 当前 schema 版本 | `app_meta.schema_version = 4` |
|
||||
| 引擎 | MySQL（正式用法；目标由 `.env` 的 `DEPLOY_ENV` + `DB_*` 决定）／SQLite（回退模式，`DB_HOST` 为空时） |
|
||||
| driver | Flask-SQLAlchemy（SQLAlchemy 2.x）+ PyMySQL |
|
||||
| 连接参数 | 见 `core/db_config.py`：utf8mb4、排序规则 `utf8mb4_bin`、`pool_pre_ping`、`pool_recycle=1800`、隔离级别 READ COMMITTED、`sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION` |
|
||||
| SQLite 回退时的 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL`（监听器按连接类型守卫，MySQL 连接不会执行） |
|
||||
| 建表方式 | **唯一真相是模型**：`db.create_all()`（建缺表）+ `_sync_columns()`（补缺列）；`SCHEMA_MIGRATIONS` 只作版本账本与数据回填 |
|
||||
| 库位置 | MySQL：由 `DB_HOST/DB_NAME` 指定；SQLite：`data/users.db` |
|
||||
| 当前 schema 版本 | `app_meta.schema_version = 6` |
|
||||
|
||||
**表清单（12 张业务表 + 1 张 SQLite 内部表）**
|
||||
**环境与库的绑定**（防混库，见 [DEPLOY.md](DEPLOY.md) §2.2）
|
||||
|
||||
| # | 表 | 来源 | 用途 |
|
||||
|---|---|------|------|
|
||||
| 1 | `user` | 模型 | 登录用户与权限 |
|
||||
| 2 | `device_group` | 模型 | 设备分组（JSON 存 serial 列表） |
|
||||
| 3 | `task_job` | 模型 | 任务计划 |
|
||||
| 4 | `custom_action` | 模型 | 自定义动作（可复用步骤包） |
|
||||
| 5 | `apk_file` | 模型 | APK 记录 |
|
||||
| 6 | `device` | 模型 + 迁移 v2/v3 | 设备池 |
|
||||
| 7 | `pending_device` | 模型 + 迁移 v4 | 待确认的发现设备 |
|
||||
| 8 | `app_meta` | 原生（迁移前建） | KV 配置（schema 版本、AI 配置、发现配置） |
|
||||
| 9 | `agent_conversation` | 原生（`web/agent_api.py`） | AI 控制台会话 |
|
||||
| 10 | `agent_experience` | 原生（`web/agent_api.py`） | 经验库（任务级配方） |
|
||||
| 11 | `experience_audit` | 原生（`web/agent_api.py`） | 经验巡检结论 |
|
||||
| 12 | `agent_action` | 原生（`web/agent_api.py`） | 动作库（命名动作） |
|
||||
| — | `sqlite_sequence` | SQLite 内部 | `AUTOINCREMENT` 的附带产物（备份自检时按 `sqlite_` 前缀排除） |
|
||||
| `DEPLOY_ENV` | 期望库名 | 用途 |
|
||||
|---|---|---|
|
||||
| `dev` | `auto_control_dev` | 本地开发 |
|
||||
| `prod` | `auto_control` | 正式环境（220 容器） |
|
||||
|
||||
> **没有外键、没有关系（relationship）、没有索引**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的 **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
|
||||
启动时校验「`.env` 声明」与「库名」「库中登记的 `app_meta.deployment_env`」三方一致，不符**拒绝启动**。
|
||||
|
||||
**表清单（12 张，全部是 `core/models.py` 里的 ORM 模型）**
|
||||
|
||||
| # | 表 | 用途 |
|
||||
|---|---|------|
|
||||
| 1 | `user` | 登录用户与权限 |
|
||||
| 2 | `device_group` | 设备分组（JSON 存 serial 列表） |
|
||||
| 3 | `task_job` | 任务计划 |
|
||||
| 4 | `custom_action` | 自定义动作（可复用步骤包） |
|
||||
| 5 | `apk_file` | APK 记录 |
|
||||
| 6 | `device` | 设备池 |
|
||||
| 7 | `pending_device` | 待确认的发现设备 |
|
||||
| 8 | `app_meta` | KV 配置（schema 版本、AI 配置、发现配置、库环境标签） |
|
||||
| 9 | `agent_conversation` | AI 控制台会话 |
|
||||
| 10 | `agent_experience` | 经验库（任务级配方） |
|
||||
| 11 | `experience_audit` | 经验巡检结论 |
|
||||
| 12 | `agent_action` | 动作库（命名动作） |
|
||||
|
||||
> 2026-09-13 之前，`app_meta` 与 4 张 `agent_*` 表是各模块里的裸 `CREATE TABLE`
|
||||
> （不进模型层）。迁 MySQL 时那批 SQL 的 `AUTOINCREMENT`/`TEXT DEFAULT ''`/`TEXT PRIMARY KEY`
|
||||
> 全都建不出来，而异常被 `except: pass` 吞掉 —— 表现为「经验库/动作库静默失灵」。
|
||||
> 现在全部升为模型，建表只有一条路径。
|
||||
|
||||
> **没有外键、没有关系（relationship）**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的
|
||||
> **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
|
||||
>
|
||||
> **唯一索引只有两个**（设备名 / 指纹，见 §4.2），且都是「空值不参与唯一约束」的语义。
|
||||
|
||||
---
|
||||
|
||||
@@ -140,50 +157,64 @@
|
||||
| `experience_audit` | `id`(PK) · `exp_id` · `verdict`(keep/delete) · `score`(REAL) · `reason` · `hits` · `action`(pending/kept/deleted) · `audited_at` |
|
||||
| `agent_action` | `id`(PK) · `name` · `app` · `aliases`(JSON) · `params`(JSON) · `steps`(JSON) · `preconditions` · `hits` · `source_prompt` · `created_at` · `updated_at` |
|
||||
|
||||
> ⚠️ 这四张表**不走 `SCHEMA_MIGRATIONS`，无版本管理**，由各模块首次使用时 `CREATE TABLE IF NOT EXISTS` 幂等创建；建表失败会被 `except: pass` 吞掉（后续 SQL 才会报错）。新增此类表时，务必同时登记进备份覆盖清单（§6）。
|
||||
> 2026-09-13 起这四张表**已升为 ORM 模型**（见 §1 的说明），建表统一走 `db.create_all()`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 迁移机制
|
||||
|
||||
### 4.1 版本化迁移 `SCHEMA_MIGRATIONS`
|
||||
### 4.1 建表与补列（以模型为准）
|
||||
|
||||
| 版本 | 内容 | SQL 幂等性 |
|
||||
|------|------|-----------|
|
||||
| 1 | `user` 增加 `perms` | `ALTER TABLE`（非幂等，靠 duplicate column 兜底） |
|
||||
| 2 | 建 `device` 表（**无 `model` 列**） | 幂等（`IF NOT EXISTS`） |
|
||||
| 3 | `device` 增加 `model` | `ALTER TABLE`（同上兜底） |
|
||||
| 4 | 建 `pending_device` 表 | 幂等 |
|
||||
| 5 | `device` 增加 `fingerprint`（设备指纹） | `ALTER TABLE`（靠 duplicate column 兜底） |
|
||||
| 6 | `pending_device` 增加 `fingerprint` | 同上 |
|
||||
**模型定义是唯一真相**。启动时：
|
||||
|
||||
执行器 `_migrate_schema()`：
|
||||
| 步骤 | 做什么 | 幂等性 |
|
||||
|------|--------|--------|
|
||||
| `db.create_all()` | 建**缺的表**（模型里有的都在） | 幂等 |
|
||||
| `_sync_columns()` | 用 `sqlalchemy.inspect` 比对模型与实表，**补实表缺的列** | 幂等 |
|
||||
| `_migrate_schema()` | 维护 `app_meta.schema_version` 账本 + 执行数据回填 | 幂等 |
|
||||
| `_ensure_unique_indexes()` | 建设备名/指纹唯一索引（见 §4.2） | 幂等 |
|
||||
| `_ensure_default_admin()` | 首次创建 `admin/admin123` | 幂等 |
|
||||
| `_migrate_old_json()` | 旧 `groups.json`/`jobs.json` 一次性迁移 | 见 §4.3 |
|
||||
|
||||
1. 先 `CREATE TABLE IF NOT EXISTS app_meta(...)`（幂等）
|
||||
2. 读 `app_meta.schema_version`（缺省 0）
|
||||
3. 只执行 `version > current` 的迁移；**SQL 报 `duplicate column name` 时回滚该语句但仍记版本号**（自愈：`create_all` 已建列而版本未记录时不再卡住），其它异常才抛出
|
||||
4. 每条迁移后 `INSERT OR REPLACE app_meta('schema_version', v)` 并提交
|
||||
5. 整体包 try：失败只记 error 日志，**不阻塞启动**
|
||||
> 2026-09-13 之前，补列靠 `ALTER TABLE` 报错文本里有没有 `duplicate column name` 来判断
|
||||
> 「列已存在」——那是 SQLite 时代的写法，换方言（MySQL 的错误码/文本都不同）就失效了。
|
||||
> 现在改为直接读数据库元数据比对，**缺什么补什么，两种方言一套代码**。
|
||||
|
||||
### 4.2 唯一索引（设备身份）
|
||||
|
||||
`_migrate_schema()` 末尾会补建两个**部分唯一索引**（幂等，与版本号无关，老库升级时也会补）：
|
||||
两个「空值不参与唯一约束」的唯一索引，与版本号无关，每次启动都补建：
|
||||
|
||||
| 索引 | 作用 |
|
||||
|------|------|
|
||||
| `ux_device_name` | 设备**名称唯一**（`WHERE name <> ''`，兼容历史空名） |
|
||||
| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（`WHERE fingerprint <> ''`） |
|
||||
| `ux_device_name` | 设备**名称唯一**（空名不参与，兼容历史未命名设备） |
|
||||
| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（空指纹不参与） |
|
||||
|
||||
实现按方言分叉（`_ensure_unique_indexes()`）：
|
||||
|
||||
- **SQLite**：直接用带 `WHERE name <> ''` 的**部分索引**
|
||||
- **MySQL 5.7**：不支持过滤索引，改用「**虚拟生成列 + 唯一索引**」——
|
||||
生成列把空值映射成 `NULL`（`IF(col IS NULL OR col='', NULL, col)`），
|
||||
而唯一索引允许多个 `NULL`，正好等于「空值不参与唯一」。生成列名 `name_uq` /
|
||||
`fingerprint_uq`，**只由 DDL 添加、不进 ORM 模型**（进了 `create_all` 会尝试写入
|
||||
它并报 Error 3105）。
|
||||
|
||||
> 用**部分索引**而不是表级约束：历史数据可能有空名称/空指纹，`<> ''` 让它们不参与唯一性判断。
|
||||
> 若历史数据里已有重复（建索引失败），只告警不回滚、不阻塞启动——约束从此刻起对新数据生效，
|
||||
> 老的重复行由管理页「改名」处理。
|
||||
|
||||
### 4.2.1 排序规则为什么必须是 `utf8mb4_bin`
|
||||
|
||||
SQLite 的文本比较是**逐字节**的（大小写敏感）。MySQL 默认的 `utf8mb4_general_ci`
|
||||
是大小写**不**敏感，会让 `Admin`/`admin`、`Phone1`/`phone1` 被判成重复，唯一索引和
|
||||
等值查询语义全变。所以库、表、连接三处都统一用 `utf8mb4_bin`（逐码点比较，对合法
|
||||
UTF-8 等价于字节序）。
|
||||
|
||||
唯一的语义差异：`LIKE` 在 `_bin` 下是大小写敏感的（SQLite 对 ASCII 默认不敏感）。
|
||||
当前代码里没有任何 `LIKE`/`ilike` 查询，暂无影响。
|
||||
|
||||
### 4.3 旧 JSON 迁移（一次性）
|
||||
|
||||
启动时若存在 `data/groups.json` / `data/jobs.json`：对应表为空则导入，随后把文件重命名为 `<name>.json.migrated` 归档。**库非空但 JSON 仍在 → 直接归档**，防止"用户删空数据后重启又复原"。
|
||||
|
||||
`init_db(app)` 顺序：`db.init_app` → `create_all()` → `_migrate_schema()` → `_ensure_default_admin()`（首次创建 `admin/admin123`）→ `_migrate_old_json()`。
|
||||
|
||||
---
|
||||
|
||||
## 5. `app_meta` 键清单
|
||||
@@ -200,37 +231,37 @@
|
||||
| `discovery_subnets` | 扫描网段 JSON 数组 | 同上 |
|
||||
| `discovery_interval` | 扫描周期秒（10-3600） | 同上 |
|
||||
| `discovery_port` | adb 探测端口（1-65535） | 同上 |
|
||||
| `discovery_auto_claim` | 指纹匹配时自动认领（`"1"`/`"0"`，默认关） | 同上 |
|
||||
| `deployment_env` | **库环境标签**（`dev`/`prod`），启动时与 `.env` 比对 | `core/db_config.py`（首次连接）/ 迁移脚本 |
|
||||
| `deployment_id` | 库唯一标识（uuid），用于识别"这份备份来自哪个库" | 同上 |
|
||||
| `deployment_claimed_at` | 标签写入时间 | 同上 |
|
||||
|
||||
> ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
|
||||
> `app_meta` 的列名 `key` 在 MySQL 里是保留字，**不要直接拼裸 SQL**，统一走
|
||||
> `core/db_config.meta_get / meta_set`（方言中立、自动加引号）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 备份覆盖清单（红线）
|
||||
|
||||
`core/system_backup.py` 的 `SUMMARY_TABLES`（12 张，与库中实际业务表一一对应）：
|
||||
`core/system_backup.py` 的 `SUMMARY_TABLES` **由模型元数据派生**：
|
||||
|
||||
| 表 | 中文标签 |
|
||||
|----|---------|
|
||||
| `app_meta` | 系统配置(app_meta) |
|
||||
| `user` | 用户 |
|
||||
| `device_group` | 设备分组 |
|
||||
| `task_job` | 任务计划 |
|
||||
| `custom_action` | 自定义动作 |
|
||||
| `apk_file` | APK 记录 |
|
||||
| `device` | 设备池 |
|
||||
| `pending_device` | 待连接设备 |
|
||||
| `agent_conversation` | AI 会话 |
|
||||
| `agent_experience` | 经验库 |
|
||||
| `experience_audit` | 经验巡检 |
|
||||
| `agent_action` | 动作库 |
|
||||
```python
|
||||
SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
|
||||
```
|
||||
|
||||
也就是说——**新增一张 ORM 表，自动就进备份覆盖清单**，不可能再漏。
|
||||
`TABLE_LABELS`（预览页的中文标签）仍是手工维护，缺标签时回退显示表名。
|
||||
|
||||
**双向自检**：
|
||||
|
||||
- **导出侧**：登记在 `SUMMARY_TABLES` 但快照里缺失 → 写入 `manifest.coverage_missing` + 日志告警
|
||||
- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警"请登记进 `core/system_backup.py` 的覆盖清单"（字段 `extra_tables`）
|
||||
- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入
|
||||
- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警（字段 `extra_tables`）
|
||||
- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）
|
||||
|
||||
> **红线**：**新增任何持久化表（含原生建表的 agent 类表），必须同时登记进 `SUMMARY_TABLES` 与 `TABLE_LABELS`**，并更新 [DEPLOY.md](DEPLOY.md) §数据备份。历史教训：`agent_action` 曾漏登记，导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
|
||||
> **红线**：新增持久化表时**同时补 `TABLE_LABELS` 的中文标签**并更新 [DEPLOY.md](DEPLOY.md) §数据备份。
|
||||
> 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：`agent_action` 曾漏登记，
|
||||
> 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
|
||||
|
||||
---
|
||||
|
||||
@@ -238,7 +269,7 @@
|
||||
|
||||
| 路径 | 内容 | 进 git |
|
||||
|------|------|--------|
|
||||
| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库 | 否 |
|
||||
| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库（**仅回退模式用**；连 MySQL 时这些文件不被读写，可留作历史归档） | 否 |
|
||||
| `data/apks/*.apk` | 上传的 APK | 否 |
|
||||
| `data/backups/` | 导出临时 zip、`pre_restore_*.db`（导入前安全网）、`restore_failed_*` | 否 |
|
||||
| `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |
|
||||
|
||||
Reference in New Issue
Block a user