@kne/fastify-app-manager 0.1.1 → 0.1.3

package/README.md

@@ -23,6 +23,8 @@ npm i --save @kne/fastify-app-manager
 适用场景：内网/堡垒机上的业务应用集中托管；不负责多机编排、硬磁盘配额或 WebSocket 升级。
 
 > **关键设计**：子应用前端通过部署时注入的 `runtimePublicUrl` / `runtimeApiUrl` 感知对外前缀；网关对路径模式剥前缀反代，并改写 Location / Cookie / 文本 body 兜底。Scheme B（子进程挂 `APP_BASE_PATH`）已弃用。
+>
+> **存储隔离**：同时注入 `window.__LOCAL_STORAGE_PREFIX="<应用名>"`，`@kne/local-storage`（≥0.1.2，`@kne/token-storage` 底层依赖）读到后自动给 key 加 `<应用名>:` 前缀，避免同源挂载的子应用与宿主、其它子应用互相覆盖登录 token 等本地存储。
 
 #### 核心架构与流程
 
@@ -48,7 +50,7 @@ Client / Admin UI
 | Domain gateway | Host 精确匹配且状态为 `running` 时透明反代，不改写路径 |
 | Path gateway | `/app/{name}` 剥前缀；改写绝对路径 Location、Cookie Path、文本类 body |
 | PM2 | 每应用一进程，名 `app-manager__{name}`；stdout/stderr 落 `appsRoot/{name}/logs` |
-| Bootstrap | `onReady` 连接 PM2、挂 log bus、对 `running`/`deploying` 做 reconcile |
+| Bootstrap | `onReady` 连接 PM2、挂 log bus；**异步**对托管应用做 `syncAllStatuses`（不阻塞父应用 ready） |
 
 ##### 部署时序
 
@@ -98,9 +100,14 @@ deploy(versionId)
 | 来源 | 优先级与规则 |
 |------|----------------|
 | 宿主 `passthroughEnvKeys` | 仅注入白名单键的当前值；API **不回传**宿主值，只暴露键名列表 |
-| 应用 `env` | 覆盖透传键；响应中匹配 `secretEnvKeyPattern` 的键显示为 `********` |
+| 应用 `env` | 覆盖透传键；响应中匹配 `secretEnvKeyPattern` **或**显式 `secretEnvKeys` 的键显示为 `********` |
 | `PORT` | 始终强制为分配端口，不可被 app.env 覆盖 |
 | `save-env` patch | `null` 删除键；`********` 对 secret 键表示保持原值 |
+| 显式密钥 | 存于 `options.secretEnvKeys`；`save-env` 可传 `secretEnvKeys` 将普通键标为密钥；响应顶层回传合并后的键名列表（不含明文） |
+| 默认托管库 | `defaultAppDb`（默认 `appsRoot/_shared/apps-data.sqlite`），与宿主主库强制分离；应用未配 `DB_*` 时注入 |
+| 应用自有库 | 应用 `env` 含完整 `DB_*` 时为独享库（`dbScope=dedicated`） |
+| 共享库表前缀 | 启动时注入 `DB_TABLE_PREFIX=t_{appName}_`（应用可显式覆盖）；子应用 sequelize 须读取该变量建表 |
+| 表归属 | `options.ownedTables`；共享库启动就绪后按前缀自动认领，亦可 `sync-owned` 扫描；运维仅限归属表 |
 
 ##### SQL 迁移
 
@@ -111,11 +118,12 @@ deploy(versionId)
 | 特性 | 说明 |
 |------|------|
 | 版本上传 | Zip Slip 防护、条目数/体积上限、Fullstack 包格式校验、server 生产依赖安装 |
-| 短部署 | `deploy` 立即返回 `deploying`，后台健康检查切 `running`/`error`；可用 SSE 看日志 |
-| 生命周期 | `start` / `stop` / `restart` / `remove`；启动时 reconcile 丢失的 PM2 进程 |
+| 短部署 | `deploy` / `start` / `restart` 立即返回 `deploying`，后台按 PM2 真实状态 + healthCheck 写回 `running`/`error`/`stopped` |
+| 生命周期 | `start` / `stop` / `restart` / `remove`；父应用重启后异步 `syncAllStatuses` 对齐 PM2 |
 | 双通道访问 | 自定义域名透明反代 + `/app/{name}` 剥前缀反代 |
-| 日志 | 文件落盘 + 历史分页 + SSE（含回放行与心跳） |
+| 日志 | 文件落盘 + 历史分页（`beforeLine` 上滚、每页最多 100 行）+ SSE（含回放行与心跳） |
 | 鉴权 | `createAuthenticate` 可注入；默认尝试 `fastify.account.authenticate.admin` |
+| 数据运维 | 归属表浏览、行 CRUD、只读 query SQL、导出 zip、cleanup（无权限返回 SQL） |
 
 #### 使用方法
 
@@ -179,7 +187,9 @@ await fastify.listen({ port: 3000 });
 | `portMax` | number | 否 | `7999` | 端口池上限（含） |
 | `pathPrefix` | string | 否 | `'/app'` | 路径访问前缀（无尾斜杠亦可） |
 | `passthroughEnvKeys` | array | 否 | `[]` | 允许注入子进程的宿主 env 键名 |
-| `secretEnvKeyPattern` | RegExp | 否 | `/(SECRET\|PASSWORD\|TOKEN\|KEY\|PRIVATE)/i` | 响应脱敏匹配 |
+| `secretEnvKeyPattern` | RegExp | 否 | `/(SECRET\|PASSWORD\|TOKEN\|KEY\|PRIVATE)/i` | 按键名正则脱敏；与显式 `secretEnvKeys` 取并集 |
+| `defaultAppDb` | object | 否 | `appsRoot/_shared/apps-data.sqlite` | 托管应用默认库（须与宿主主库分离） |
+| `dbQueryMaxRows` | number | 否 | `500` | 只读 query SQL 最大返回行数 |
 | `pm2Defaults` | object | 否 | 见下表 | 全局 PM2 默认；可被应用 `pm2Config` 覆盖 |
 | `createAuthenticate` | function | 否 | 见说明 | 返回 `onRequest` 钩子数组；默认尝试 admin |
 | `healthCheckPath` | string | 否 | `'/'` | 部署后就绪探测路径 |
@@ -231,9 +241,9 @@ await fastify.listen({ port: 3000 });
 | description | string | 否 | - | 描述 |
 | env | object | 否 | `{}` | 应用自有环境变量 |
 | pm2Config | object | 否 | `{}` | PM2 覆盖项 |
-| options | object | 否 | `{}` | 扩展字段 |
+| options | object | 否 | `{}` | 扩展字段；可含 `secretEnvKeys: string[]` 显式密钥键名 |
 
-返回脱敏后的应用对象（含 `port`、`pathUrl`、`passthroughEnvKeys`、`status: 'idle'` 等）。
+返回脱敏后的应用对象（含 `port`、`pathUrl`、`passthroughEnvKeys`、`secretEnvKeys`、`status: 'idle'` 等）。
 
 ##### POST `{prefix}/app/save`
 
@@ -246,12 +256,49 @@ await fastify.listen({ port: 3000 });
 
 ##### POST `{prefix}/app/save-env`
 
-仅合并环境变量。
+仅合并环境变量；可选更新显式密钥键列表。
 
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
 | name | string | 是 | 应用 slug |
 | env | object | 是 | patch：`null` 删键；secret 键值为 `********` 时保持原值 |
+| secretEnvKeys | array | 否 | 显式密钥键名；传入则整体替换并写入 `options.secretEnvKeys`（仅保留仍存在于 env 的键）；省略则沿用原列表 |
+
+> **关键设计**：密钥判定 = 键名匹配 `secretEnvKeyPattern` **或** 出现在 `options.secretEnvKeys`。响应顶层 `secretEnvKeys` 为二者并集，便于管理端把普通变量标成密钥而不改键名。
+
+##### 数据运维与表生命周期
+
+解析后的应用库：应用 `env` 的 `DB_*` 优先，否则注入 `defaultAppDb`。共享库（未自配 `DB_*`）仅能操作 `options.ownedTables`。
+
+> **关键设计**：共享库启动时注入 `DB_TABLE_PREFIX=t_{appName}_`（可用应用 env 覆盖）。子应用若使用 `@kne/fastify-sequelize@>=4.0.4`，存在该环境变量时默认 `forcePrefix`，连接上所有模型（含 account/message/tenant）表名必须以该前缀开头，无法被 `addModels({ prefix })` 覆盖。就绪后按该前缀自动认领表。
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `{prefix}/app/db/tables` | 归属表 + 列/主键摘要；`scope=all` 仅独享库 |
+| POST | `{prefix}/app/db/tables/register` | 登记 `ownedTables`（`mode`: `union`/`replace`） |
+| POST | `{prefix}/app/db/tables/sync-owned` | 扫描库表并登记归属（共享库优先领取本应用前缀表；无前缀命中时再领取未被其它应用占用的表） |
+| POST | `{prefix}/app/db/tables/unregister` | 取消登记 |
+| GET | `{prefix}/app/db/rows` | 分页行；`filter` 为 JSON（等值或 `{ $gte,$lte,$gt,$lt }` 范围）；`keyword` 在字符串列上 OR LIKE；`sort` 为 JSON `[{ name, sort: ASC\|DESC }]` |
+| GET | `{prefix}/app/db/row` | 按 `id` 或 `pk` JSON 查一行 |
+| POST | `{prefix}/app/db/row/save` | 按主键 upsert；可选 `autoGenerate`（主键字段 → boolean）空值时用宿主 `sequelize.generateId` 雪花填充 |
+| POST | `{prefix}/app/db/row/remove` | 按主键删除 |
+| POST | `{prefix}/app/db/row/restore` | 按主键恢复软删除（清空 deleted_at） |
+| POST | `{prefix}/app/db/query` | **只读** SQL（`SELECT`/`WITH`/`EXPLAIN`/`SHOW`/`DESCRIBE`/`PRAGMA`）；共享库引用表须归属 |
+| POST | `{prefix}/app/db/export` | 导出归属表为 zip（`mode=file` 仅独享 sqlite） |
+| POST | `{prefix}/app/db/cleanup` | `DROP` 归属表；失败项进入 `sql[]`，`manualRequired` |
+
+##### POST `{prefix}/app/remove`
+
+删除应用。默认先导出再清理所属表；清理不完整则默认**不删**元数据。
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| name | string | 是 | - | 应用 slug |
+| exportBeforeRemove | boolean | 否 | `true` | 删除前导出 |
+| cleanupData | boolean | 否 | `true` | 删除前 cleanup |
+| allowRemoveIfCleanupIncomplete | boolean | 否 | `false` | 允许在 `manualRequired` 时仍删管控侧 |
+| force | boolean | 否 | `false` | 跳过导出 |
+| removeSqliteFile | boolean | 否 | `false` | 独享 sqlite 清理成功后删除文件 |
 
 ##### POST `{prefix}/app/version/upload`
 
@@ -349,21 +396,23 @@ await fastify.listen({ port: 3000 });
 
 ##### GET `{prefix}/app/logs`
 
-读取日志文件尾部分页（较新页在前）。
+读取日志文件尾部分页（较新页在前）。`perPage` 上限 100。停止实时后前端可用 `beforeLine` 向上滚动加载更早日志。
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
 | name | string | 是 | - | 应用 slug |
 | stream | string | 否 | `'out'` | `out` / `err` |
-| perPage | number | 否 | `100` | 每页行数 |
-| currentPage | number | 否 | `1` | 页码（1=最新一页） |
+| perPage | number | 否 | `100` | 每页行数（最大 100） |
+| currentPage | number | 否 | `1` | 页码（1=最新一页；与 `beforeLine` 二选一） |
+| beforeLine | number | 否 | - | 取行号 `< beforeLine` 的尾部至多 `perPage` 行（上滚历史） |
 
 返回：
 
 ```json
 {
   "pageData": [{ "line": 12, "content": "..." }],
-  "totalCount": 12
+  "totalCount": 12,
+  "hasMore": true
 }
 ```
 
@@ -395,13 +444,16 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 |----------|------|
 | `create(data)` | 同 create 接口 |
 | `save({ name, ... })` | 同 save |
-| `saveEnv({ name, env })` | 同 save-env |
+| `saveEnv({ name, env, secretEnvKeys? })` | 同 save-env |
 | `list({ filter, perPage, currentPage })` | 列表 |
 | `detail({ name })` | 详情（脱敏） |
 | `uploadVersion({ name, version, label, zipBuffer })` | 上传版本 |
 | `listVersions({ name, perPage, currentPage })` | 版本列表 |
-| `deploy({ name, versionId, version, runMigration })` | 部署 |
-| `start` / `stop` / `restart` / `remove` (`{ name }`) | 生命周期 |
+| `deploy({ name, versionId, version, runMigration })` | 部署；立即 `deploying`，后台 `syncRealStatus` |
+| `start` / `stop` / `restart` | 生命周期；`start`/`restart` 立即 `deploying`，后台按 PM2+health 写回真实状态 |
+| `syncStatus({ name, recoverIfMissing? })` | 同步单个应用真实状态并返回公开对象 |
+| `syncAllStatuses({ recoverIfMissing? })` | 批量同步（父应用启动 reconcile 使用） |
+| `remove({ name, exportBeforeRemove?, cleanupData?, ... })` | 删除；默认可导出+清理所属表 |
 | `logs({ name, stream, perPage, currentPage })` | 读日志文件 |
 | `findByHost(host)` | 网关：按 domain + `running` 查找 |
 | `findByPathName(name)` | 网关：按 name + `running` 查找 |
@@ -410,13 +462,22 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 | `getLogHub()` | 获取 EventEmitter |
 | `toPublicApp(app)` / `mountPrefix(name)` | 序列化辅助 |
 
+##### services.dbops
+
+| 方法签名 | 说明 |
+|----------|------|
+| `listTables` / `registerTables` / `unregisterTables` | 表归属 |
+| `listRows` / `getRow` / `saveRow` / `removeRow` | 行级运维 |
+| `runQuery({ name, sql, replacements? })` | 只读 SQL |
+| `exportData` / `cleanup` | 导出与清理 |
+
 ##### services.bootstrap
 
 | 方法签名 | 说明 |
 |----------|------|
-| `onReady()` | 连接 PM2、挂 log bus、reconcile（由插件 `onReady` 调用） |
+| `onReady()` | 连接 PM2、挂 log bus，并 **setImmediate** 异步 `reconcile`（不阻塞父应用 ready） |
 | `onClose()` | 断开 bus / PM2（由插件 `onClose` 调用） |
-| `reconcile()` | 对 DB 中 `running`/`deploying` 但 PM2 未 online 的应用尝试 start |
+| `reconcile()` | 调用 `app.syncAllStatuses({ recoverIfMissing: true })`：按 PM2 真实状态写回 DB；`running`/`deploying` 且进程缺失时尝试拉起 |
 
 #### 数据模型
 
@@ -434,7 +495,7 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 | description | string / null | 描述 |
 | env | object | 自有环境变量 |
 | pm2Config | object | PM2 覆盖 |
-| options | object | 扩展字段 |
+| options | object | 扩展字段；`secretEnvKeys` 为显式密钥键名列表 |
 | port | number | 分配端口 |
 | status | string | `idle` / `deploying` / `running` / `stopped` / `error` |
 | currentVersionId | string / null | 当前部署版本 id |
@@ -484,3 +545,5 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 ```
 pickHostEnv(passthroughEnvKeys) → app.env → PORT=分配端口（强制）
 ```
+
+API 响应脱敏：`secretEnvKeyPattern` ∪ `options.secretEnvKeys`；明文密钥不回传，顶层 `secretEnvKeys` 只暴露键名。

package/index.js

@@ -1,15 +1,18 @@
 const fp = require('fastify-plugin');
 const path = require('node:path');
+const fs = require('fs-extra');
+const { assertDefaultAppDbSeparated } = require('./libs/utils/dbIdentity');
 
 module.exports = fp(
   async (fastify, options) => {
+    const appsRoot = options.appsRoot || path.join(process.cwd(), 'managed-apps');
     options = Object.assign(
       {},
       {
         dbTableNamePrefix: 't_app_manager_',
         name: 'appManager',
         prefix: '/api/v1/app-manager',
-        appsRoot: path.join(process.cwd(), 'managed-apps'),
+        appsRoot,
         portMin: 4000,
         portMax: 7999,
         pathPrefix: '/app',
@@ -27,6 +30,15 @@ module.exports = fp(
         secretEnvKeyPattern: /(SECRET|PASSWORD|TOKEN|KEY|PRIVATE)/i,
         sqlPath: 'sql',
         migrateBeforeStart: false,
+        defaultAppDb: {
+          dialect: 'sqlite',
+          storage: path.join(appsRoot, '_shared', 'apps-data.sqlite'),
+          logging: false
+        },
+        dbQueryMaxRows: 500,
+        dbQueryTimeoutMs: 15000,
+        /** 宿主 fastify-sequelize 命名连接，用于默认托管库（推荐，复用宿主 pg 等驱动） */
+        defaultAppDbConnection: null,
         pm2Defaults: {
           exec_mode: 'fork',
           instances: 1,
@@ -47,6 +59,22 @@ module.exports = fp(
       options
     );
 
+    if (!options.defaultAppDb) {
+      options.defaultAppDb = {
+        dialect: 'sqlite',
+        storage: path.join(options.appsRoot, '_shared', 'apps-data.sqlite'),
+        logging: false
+      };
+    }
+
+    if (fastify.sequelize?.instance) {
+      assertDefaultAppDbSeparated(options.defaultAppDb, fastify.sequelize.instance);
+    }
+
+    if (options.defaultAppDb?.dialect === 'sqlite' && options.defaultAppDb.storage) {
+      await fs.ensureDir(path.dirname(options.defaultAppDb.storage));
+    }
+
     await fastify.register(require('@fastify/multipart'), {
       limits: {
         fileSize: options.maxZipSize

package/libs/controllers/app.js

@@ -66,7 +66,8 @@ module.exports = fp(async (fastify, options) => {
           required: ['name', 'env'],
           properties: {
             name: { type: 'string' },
-            env: { type: 'object' }
+            env: { type: 'object' },
+            secretEnvKeys: { type: 'array', items: { type: 'string' } }
           }
         }
       }
@@ -183,7 +184,7 @@ module.exports = fp(async (fastify, options) => {
     async request => services.app.detail(request.query)
   );
 
-  for (const action of ['start', 'stop', 'restart', 'remove']) {
+  for (const action of ['start', 'stop', 'restart']) {
     fastify.post(
       `${options.prefix}/app/${action}`,
       {
@@ -201,6 +202,29 @@ module.exports = fp(async (fastify, options) => {
     );
   }
 
+  fastify.post(
+    `${options.prefix}/app/remove`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '删除应用（默认可先导出并清理所属表）',
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            exportBeforeRemove: { type: 'boolean', default: true },
+            cleanupData: { type: 'boolean', default: true },
+            allowRemoveIfCleanupIncomplete: { type: 'boolean', default: false },
+            force: { type: 'boolean', default: false },
+            removeSqliteFile: { type: 'boolean', default: false }
+          }
+        }
+      }
+    },
+    async request => services.app.remove(request.body)
+  );
+
   fastify.get(
     `${options.prefix}/app/logs`,
     {
@@ -213,8 +237,12 @@ module.exports = fp(async (fastify, options) => {
           properties: {
             name: { type: 'string' },
             stream: { type: 'string', enum: ['out', 'err'], default: 'out' },
-            perPage: { type: 'number', default: 100 },
-            currentPage: { type: 'number', default: 1 }
+            perPage: { type: 'number', default: 100, maximum: 100 },
+            currentPage: { type: 'number', default: 1 },
+            beforeLine: {
+              type: 'number',
+              description: 'Load up to perPage lines with line number < beforeLine (for scroll-up history)'
+            }
           }
         }
       }

package/libs/controllers/dbops.js

@@ -0,0 +1,268 @@
+const fp = require('fastify-plugin');
+
+module.exports = fp(async (fastify, options) => {
+  const { services } = fastify[options.name];
+  const auth = () => options.createAuthenticate();
+
+  fastify.get(
+    `${options.prefix}/app/db/tables`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '列出应用所属数据表',
+        query: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            scope: { type: 'string', enum: ['owned', 'all'] }
+          }
+        }
+      }
+    },
+    async request => services.dbops.listTables(request.query)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/tables/register`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '登记应用所属表',
+        body: {
+          type: 'object',
+          required: ['name', 'tables'],
+          properties: {
+            name: { type: 'string' },
+            tables: { type: 'array', items: { type: 'string' } },
+            mode: { type: 'string', enum: ['union', 'replace'] }
+          }
+        }
+      }
+    },
+    async request => services.dbops.registerTables(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/tables/sync-owned`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '扫描数据库并登记本应用可管理表（共享库仅领取未被其它应用登记的表）',
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => services.dbops.syncOwnedFromDatabase(request.body)
+  );
+
+  fastify.get(
+    `${options.prefix}/app/db/rows`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '分页查询表数据',
+        query: {
+          type: 'object',
+          required: ['name', 'table'],
+          properties: {
+            name: { type: 'string' },
+            table: { type: 'string' },
+            currentPage: { type: 'number', default: 1 },
+            perPage: { type: 'number', default: 20 },
+            filter: { type: 'string', description: 'JSON object: equality or range { $gte,$lte,$gt,$lt }' },
+            includeDeleted: { type: 'boolean', default: false },
+            keyword: { type: 'string', description: 'Fuzzy search across string columns (OR LIKE)' },
+            sort: {
+              type: 'string',
+              description: 'JSON array of { name, sort: ASC|DESC } for ORDER BY'
+            }
+          }
+        }
+      }
+    },
+    async request => {
+      const query = { ...request.query };
+      if (typeof query.filter === 'string' && query.filter) {
+        try {
+          query.filter = JSON.parse(query.filter);
+        } catch (e) {
+          const err = new Error('filter must be valid JSON');
+          err.statusCode = 400;
+          throw err;
+        }
+      }
+      if (typeof query.sort === 'string' && query.sort) {
+        try {
+          query.sort = JSON.parse(query.sort);
+        } catch (e) {
+          const err = new Error('sort must be valid JSON array');
+          err.statusCode = 400;
+          throw err;
+        }
+      }
+      return services.dbops.listRows(query);
+    }
+  );
+
+  fastify.get(
+    `${options.prefix}/app/db/row`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '按主键查询一行',
+        query: {
+          type: 'object',
+          required: ['name', 'table'],
+          properties: {
+            name: { type: 'string' },
+            table: { type: 'string' },
+            id: {},
+            pk: { type: 'string', description: 'JSON primary key object' }
+          }
+        }
+      }
+    },
+    async request => {
+      const query = { ...request.query };
+      if (typeof query.pk === 'string' && query.pk) {
+        query.pk = JSON.parse(query.pk);
+      }
+      return services.dbops.getRow(query);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/row/save`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '插入或更新一行（autoGenerate 可对主键走雪花自动生成）',
+        body: {
+          type: 'object',
+          required: ['name', 'table', 'data'],
+          properties: {
+            name: { type: 'string' },
+            table: { type: 'string' },
+            data: { type: 'object' },
+            autoGenerate: {
+              type: 'object',
+              additionalProperties: { type: 'boolean' },
+              description: '主键字段名 → 是否用 snowflake generateId 自动填充（仅空值时）'
+            }
+          }
+        }
+      }
+    },
+    async request => services.dbops.saveRow(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/row/remove`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '按主键软删除一行（默认写 deleted_at；hard=true 才物理删除）',
+        body: {
+          type: 'object',
+          required: ['name', 'table'],
+          properties: {
+            name: { type: 'string' },
+            table: { type: 'string' },
+            id: {},
+            pk: { type: 'object' },
+            hard: { type: 'boolean', default: false }
+          }
+        }
+      }
+    },
+    async request => services.dbops.removeRow(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/row/restore`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '按主键恢复软删除行（清空 deleted_at）',
+        body: {
+          type: 'object',
+          required: ['name', 'table'],
+          properties: {
+            name: { type: 'string' },
+            table: { type: 'string' },
+            id: {},
+            pk: { type: 'object' }
+          }
+        }
+      }
+    },
+    async request => services.dbops.restoreRow(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/query`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '执行只读查询 SQL',
+        body: {
+          type: 'object',
+          required: ['name', 'sql'],
+          properties: {
+            name: { type: 'string' },
+            sql: { type: 'string' },
+            replacements: { type: 'object' },
+            maxRows: { type: 'number' }
+          }
+        }
+      }
+    },
+    async request => services.dbops.runQuery(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/export`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '导出应用所属表数据',
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            tables: { type: 'array', items: { type: 'string' } },
+            mode: { type: 'string', enum: ['json', 'file'] }
+          }
+        }
+      }
+    },
+    async request => services.dbops.exportData(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/db/cleanup`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '清理应用所属表（失败时返回手工 SQL）',
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            dryRun: { type: 'boolean' },
+            removeSqliteFile: { type: 'boolean' }
+          }
+        }
+      }
+    },
+    async request => services.dbops.cleanup(request.body)
+  );
+});