数据库维护自动停启PM2网关

Author: javazys

AGENTS.md

@@ -52,7 +52,7 @@ bun run dev -- db check  # 检查数据库完整性与业务统计
 - 数据库初始化时启用 WAL、创建 `gateway_lock` 并自动执行 `drizzle/` migrations。
 - Gateway 用 SQLite `BEGIN IMMEDIATE` + `gateway_lock` 保证单实例；Dashboard 默认只监听 `127.0.0.1:4680`。
 - Gateway 仅在 Worker、Scheduler、Watchdog 和 Dashboard 启动完成后写入 `gateway_lock.ready_at`；PM2 `online` 不能单独作为就绪依据，进程 PID 必须匹配新鲜 ready 锁。
-- 数据库检查、备份、清空和恢复统一经过 `DatabaseMaintenanceService`；CLI 清空/恢复必须显式确认并拒绝活跃 Gateway 或运行中任务，清空/恢复前必须自动创建校验通过的安全备份。
+- 数据库检查、备份、清空和恢复统一经过 `DatabaseMaintenanceService`；CLI 清空/恢复必须显式确认并拒绝运行中任务，且只可自动停启 PID 与当前数据库新鲜 ready 锁一致的 PM2 Gateway；前台或无法确认归属的进程必须拒绝误杀。清空/恢复前必须自动创建校验通过的安全备份，默认在操作失败时也恢复原 Gateway 状态，`--keep-stopped` 除外。
 - Dashboard 清空只能豁免当前 Gateway PID，仍必须服务端确认、拒绝运行中任务并在同一事务内先备份后删除；不得恢复为直接 `DELETE` 三张表的路由实现。
 - Dashboard 的浏览器写请求必须通过同源检查，数据库字符串进入 HTML 前必须调用 `esc`；API 的 ID、状态和配置不得直接断言类型。
 

README.md

@@ -13,7 +13,13 @@ Documentation: [current architecture](docs/architecture.md) · [operations and t
 
 ### Quick Install
 
-Add the plugin to `~/.config/opencode/opencode.json`:
+Install the CLI globally:
+
+```bash
+npm install -g opencode-supertask
+```
+
+Then add the plugin to `~/.config/opencode/opencode.json`:
 
 ```json
 {
@@ -36,13 +42,14 @@ The plugin never installs global dependencies by itself. Without a running Gatew
 2. Remove `"opencode-supertask"` from `~/.config/opencode/opencode.json`
 3. Restart OpenCode
 
-To clear all task data safely, stop the Gateway and use the backup-first database command:
+To clear all task data safely, use the backup-first database command:
 
 ```bash
-pm2 stop supertask-gateway
 supertask db clear --confirm CLEAR
 ```
 
+If the matching Gateway is managed by PM2, the CLI stops it first and restarts it after maintenance.
+
 ### CLI Install / Uninstall
 
 ```bash
@@ -114,11 +121,11 @@ supertask template enable --id 1
 # Database maintenance
 supertask db check
 supertask db backup [--output /path/to/tasks-backup.db]
-supertask db clear --confirm CLEAR
-supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE
+supertask db clear --confirm CLEAR [--keep-stopped]
+supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE [--keep-stopped]
 ```
 
-`db backup` creates and validates a standalone SQLite snapshot. `db clear` and `db restore` refuse to run while another Gateway or task is active; both create a safety backup before changing data. Stop the PM2 Gateway before using the destructive CLI commands.
+`db backup` creates and validates a standalone SQLite snapshot. For `db clear` and `db restore`, the CLI automatically stops a PM2 Gateway whose PID matches the current database's fresh ready lock, then restores its previous running state. Both commands create a safety backup before changing data and still refuse active tasks or an unverified/foreground Gateway. Use `--keep-stopped` to leave a previously running PM2 Gateway stopped.
 
 ### Duration Format
 
@@ -214,7 +221,13 @@ SuperTask 是一个基于 SQLite 的 AI Agent 任务调度系统，专为 [OpenC
 
 ### 安装
 
-在 `~/.config/opencode/opencode.json` 中添加：
+先安装全局 CLI：
+
+```bash
+npm install -g opencode-supertask
+```
+
+然后在 `~/.config/opencode/opencode.json` 中添加：
 
 ```json
 {
@@ -240,10 +253,11 @@ supertask gateway   # 前台运行：不需要 pm2
 安全清理所有任务数据：
 
 ```bash
-pm2 stop supertask-gateway
 supertask db clear --confirm CLEAR
 ```
 
+若当前数据库对应的 Gateway 由 PM2 管理，CLI 会自动停止并在维护结束后恢复运行。
+
 ### 定时任务
 
 支持友好的时间格式：
@@ -274,11 +288,11 @@ supertask template add --type cron --cron "0 9 * * *" ...
 ```bash
 supertask db check
 supertask db backup [--output /path/to/tasks-backup.db]
-supertask db clear --confirm CLEAR
-supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE
+supertask db clear --confirm CLEAR [--keep-stopped]
+supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE [--keep-stopped]
 ```
 
-`db backup` 会生成并校验可独立恢复的 SQLite 快照。CLI 清空和恢复会拒绝活跃 Gateway 或运行中任务，并在修改数据前自动保留安全备份；执行这两个危险命令前应先停止 PM2 Gateway。
+`db backup` 会生成并校验可独立恢复的 SQLite 快照。CLI 清空和恢复会先确认 PM2 PID 与当前数据库的新鲜 ready 锁一致，再自动停止并按原状态重启 Gateway；操作失败时也会尝试恢复 Gateway。它们仍会拒绝运行中任务、前台 Gateway 或无法确认归属的进程，并在修改数据前自动保留安全备份。传入 `--keep-stopped` 可让原本运行的 PM2 Gateway 保持停止。
 
 ### 数据位置
 

docs/architecture.md

@@ -2,7 +2,7 @@
 
 > 状态：当前有效
 > 最后核对：2026-07-15
-> 适用版本：源码 `main` 分支，当前开发基线 0.1.24
+> 适用版本：源码 `main` 分支，当前开发基线 0.1.25
 
 ## 结论与适用边界
 
@@ -124,14 +124,14 @@ pending / running / failed ──cancel──> cancelled
 | 持久化 | SQLite WAL | 零服务依赖，适合单机队列 | 多机消费、高写入并发或 HA 时 |
 | 配置错误 | 校验失败并拒绝启动 | 避免错误配置被默认值掩盖 | 不改变；可增加更友好的诊断 |
 | 调度补偿 | 不回放全部错过周期 | 避免恢复时瞬间制造积压 | 业务明确要求补账并定义上限时 |
-| 数据库维护 | Service 统一检查、备份、清空和恢复 | 避免 CLI、Dashboard 各自实现不完整的危险 SQL | 存储迁移到外部数据库时重做维护协议 |
+| 数据库维护 | Service 统一数据安全；CLI 编排匹配当前 ready 锁的 PM2 Gateway 自动停启 | 避免各入口实现不完整的危险 SQL，并防止维护命令误停另一套实例 | 存储迁移到外部数据库时重做维护协议 |
 | Dashboard | 嵌入 Gateway，仅监听 loopback | 少一个常驻进程，默认不暴露网络面 | 需要公网/团队访问时拆分并加鉴权 |
 
 ## 安全边界
 
 Dashboard 只绑定 `127.0.0.1`，浏览器写请求检查 `Sec-Fetch-Site` 和同源 `Origin`，数据库字符串输出到 HTML 前转义。这是本机可信用户边界，不是完整鉴权系统；不要通过反向代理或端口转发直接暴露到不可信网络。
 
-数据库危险操作集中在 `DatabaseMaintenanceService`：备份通过 SQLite 序列化得到一致快照，并转换成无需 WAL sidecar 的独立文件；清空在 `BEGIN IMMEDIATE` 内完成备份和三张业务表删除；恢复先校验来源、备份当前库，再暂存、替换、迁移和复检。CLI 清空/恢复拒绝活跃 Gateway 和运行中任务，Dashboard 清空只允许当前 Gateway 且仍拒绝运行中任务。恢复会清理运行时锁，并把快照中的遗留运行状态收敛为可重新调度的状态。
+数据库危险操作集中在 `DatabaseMaintenanceService`：备份通过 SQLite 序列化得到一致快照，并转换成无需 WAL sidecar 的独立文件；清空在 `BEGIN IMMEDIATE` 内完成备份和三张业务表删除；恢复先校验来源、备份当前库，再暂存、替换、迁移和复检。CLI 层只对“PM2 PID 与当前数据库新鲜 ready 锁一致”的 Gateway 自动停启，并在操作失败时恢复原运行状态；其他活跃 Gateway 仍由 Service 拒绝，避免误杀另一套实例。Dashboard 清空只允许当前 Gateway 且仍拒绝运行中任务。恢复会清理运行时锁，并把快照中的遗留运行状态收敛为可重新调度的状态。
 
 ## 已知限制与后续触发点
 

docs/operations.md

@@ -198,24 +198,22 @@ supertask db backup --output ~/supertask-backup/tasks.db
 清空全部任务、执行记录和调度模板：
 
 ```bash
-pm2 stop supertask-gateway
 supertask db clear --confirm CLEAR
-pm2 start supertask-gateway
 ```
 
-`db clear` 会拒绝活跃 Gateway 和任何 `running` 任务/执行记录，在一个 `BEGIN IMMEDIATE` 事务内先生成 `pre-clear` 备份，再删除三张业务表；任一步失败都会回滚事务。它保留数据库结构、迁移记录、配置和自增序列。Dashboard 的“清空数据库”复用同一服务，要求服务端确认并拒绝运行中任务；因为 Dashboard 本身位于当前 Gateway 内，它只豁免当前 Gateway PID，不豁免其他进程。
+`db clear` 会先核对 PM2 进程 PID 与当前数据库的新鲜 ready 锁；匹配时自动优雅停止 Gateway，维护结束后按原状态重启并等待新的 ready 锁，数据库操作失败时也会尝试恢复运行。传入 `--keep-stopped` 会让原本运行的 PM2 Gateway 保持停止。前台 Gateway、陈旧锁或无法确认归属的进程不会被自动终止，命令会拒绝操作并要求人工停止。
+
+清空仍会拒绝任何 `running` 任务/执行记录，在一个 `BEGIN IMMEDIATE` 事务内先生成 `pre-clear` 备份，再删除三张业务表；任一步失败都会回滚事务。它保留数据库结构、迁移记录、配置和自增序列。若数据库维护已完成但 PM2 重启失败，CLI 会明确报告“数据库维护已完成”，此时按错误提示检查 `pm2 logs supertask-gateway`，不要重复清空。Dashboard 的“清空数据库”复用同一服务，要求服务端确认并拒绝运行中任务；因为 Dashboard 本身位于当前 Gateway 内，它只豁免当前 Gateway PID，不豁免其他进程。
 
 从备份恢复：
 
 ```bash
-pm2 stop supertask-gateway
 supertask db restore --from ~/.local/share/opencode/tasks.pre-clear-<time>-<id>.db --confirm RESTORE
-pm2 start supertask-gateway
 supertask db check
 curl -fsS http://127.0.0.1:4680/health
 ```
 
-恢复会先校验来源文件并自动创建当前库的 `pre-restore` 安全备份，然后用同目录暂存文件替换数据库、自动执行缺失 migration，再复检完整性。备份中遗留的 `running` 任务会恢复为 `pending`，对应运行记录关闭为 `failed`，旧 `gateway_lock` 不会继续生效。恢复失败时会尝试原子回滚，并在错误信息中给出安全备份路径。
+恢复使用与清空相同的 PM2 自动停启和 `--keep-stopped` 语义。它会先校验来源文件并自动创建当前库的 `pre-restore` 安全备份，然后用同目录暂存文件替换数据库、自动执行缺失 migration，再复检完整性。备份中遗留的 `running` 任务会恢复为 `pending`，对应运行记录关闭为 `failed`，旧 `gateway_lock` 不会继续生效。恢复失败时会尝试原子回滚，并在错误信息中给出安全备份路径。
 
 不要在 Gateway 运行时删除或只复制 `tasks.db`；WAL 模式下最新事务可能还在 `tasks.db-wal`。配置文件仍需单独备份：
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "opencode-supertask",
-    "version": "0.1.24",
+    "version": "0.1.25",
     "description": "AI Agent 任务调度系统 — OpenCode 插件 + CLI + Gateway 常驻进程",
     "type": "module",
     "main": "dist/plugin/supertask.js",

src/cli/index.ts

@@ -5,7 +5,11 @@ import { DatabaseMaintenanceService } from '@core/services/database-maintenance.
 import { closeDb } from '@core/db';
 import { parseDuration } from '@core/duration';
 import type { TaskStatus, ScheduleType } from '@core/db/schema';
-import { getPackageVersion } from '../daemon/pm2';
+import {
+    getPackageVersion,
+    restartGatewayAfterMaintenance,
+    stopGatewayForMaintenance,
+} from '../daemon/pm2';
 
 async function withDb<T>(fn: () => Promise<T>): Promise<T> {
     try {
@@ -19,6 +23,56 @@ async function withDb<T>(fn: () => Promise<T>): Promise<T> {
     }
 }
 
+interface GatewayMaintenanceReport {
+    wasRunning: boolean;
+    restarted: boolean;
+    keptStopped: boolean;
+}
+
+function messageOf(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+function runDestructiveDatabaseMaintenance<T extends object>(
+    keepStopped: boolean,
+    operation: () => T,
+): T & { gateway: GatewayMaintenanceReport } {
+    const gatewayState = stopGatewayForMaintenance();
+    let result: T;
+    try {
+        result = operation();
+    } catch (error) {
+        if (gatewayState.wasRunning && !keepStopped) {
+            try {
+                restartGatewayAfterMaintenance(gatewayState);
+            } catch (restartError) {
+                throw new Error(
+                    `${messageOf(error)}；Gateway 自动恢复也失败：${messageOf(restartError)}`,
+                );
+            }
+        }
+        throw error;
+    }
+
+    let restarted = false;
+    if (gatewayState.wasRunning && !keepStopped) {
+        try {
+            restarted = restartGatewayAfterMaintenance(gatewayState);
+        } catch (error) {
+            throw new Error(`数据库维护已完成，但 Gateway 自动重启失败：${messageOf(error)}`);
+        }
+    }
+
+    return {
+        ...result,
+        gateway: {
+            wasRunning: gatewayState.wasRunning,
+            restarted,
+            keptStopped: gatewayState.wasRunning && keepStopped,
+        },
+    };
+}
+
 const program = new Command();
 
 program
@@ -362,23 +416,33 @@ databaseCommand
     .command('clear')
     .description('备份后事务性清空任务、执行记录和调度模板')
     .option('--confirm <word>', '危险操作确认，必须填写 CLEAR')
-    .action(async (options: { confirm?: string }) => withDb(async () => {
+    .option('--keep-stopped', '维护结束后不重启原本由 PM2 管理的 Gateway')
+    .action(async (options: { confirm?: string; keepStopped?: boolean }) => withDb(async () => {
         if (options.confirm !== 'CLEAR') {
             throw new Error('清空数据库必须显式传入 --confirm CLEAR');
         }
-        console.log(JSON.stringify(DatabaseMaintenanceService.clear(), null, 2));
+        const result = runDestructiveDatabaseMaintenance(
+            options.keepStopped ?? false,
+            () => DatabaseMaintenanceService.clear(),
+        );
+        console.log(JSON.stringify(result, null, 2));
     }));
 
 databaseCommand
     .command('restore')
     .description('自动备份当前库后，从指定备份恢复数据库')
     .requiredOption('--from <path>', '要恢复的 SQLite 备份文件')
     .option('--confirm <word>', '危险操作确认，必须填写 RESTORE')
-    .action(async (options: { from: string; confirm?: string }) => withDb(async () => {
+    .option('--keep-stopped', '维护结束后不重启原本由 PM2 管理的 Gateway')
+    .action(async (options: { from: string; confirm?: string; keepStopped?: boolean }) => withDb(async () => {
         if (options.confirm !== 'RESTORE') {
             throw new Error('恢复数据库必须显式传入 --confirm RESTORE');
         }
-        console.log(JSON.stringify(DatabaseMaintenanceService.restore(options.from), null, 2));
+        const result = runDestructiveDatabaseMaintenance(
+            options.keepStopped ?? false,
+            () => DatabaseMaintenanceService.restore(options.from),
+        );
+        console.log(JSON.stringify(result, null, 2));
     }));
 
 program.addCommand(databaseCommand);

src/core/services/database-maintenance.service.ts

@@ -404,7 +404,7 @@ export class DatabaseMaintenanceService {
         if (!lock || !isProcessAlive(lock.pid)) return;
         if (allowCurrentGateway && lock.pid === process.pid) return;
         throw new DatabaseMaintenanceConflictError(
-            `Gateway PID ${lock.pid} 仍在运行，请先执行 pm2 stop supertask-gateway`,
+            `Gateway PID ${lock.pid} 仍在运行，但未确认由当前数据库对应的 PM2 进程管理；请先停止该 Gateway（PM2 可执行 pm2 stop supertask-gateway）`,
         );
     }
 

src/daemon/pm2.ts

@@ -22,6 +22,10 @@ export type EnsureGatewayResult =
     | { ok: true; action: "already-running" | "started" | "restarted" }
     | { ok: false; reason: "pm2-not-installed" };
 
+export interface GatewayMaintenanceState {
+    wasRunning: boolean;
+}
+
 export function getPackageVersion(): string {
     const envVersion = process.env.npm_package_version;
     if (envVersion) return envVersion;
@@ -270,6 +274,35 @@ function waitForGatewayReady(pid: number): boolean {
     return isGatewayReady(pid);
 }
 
+export function stopGatewayForMaintenance(): GatewayMaintenanceState {
+    if (!isPm2Installed()) return { wasRunning: false };
+
+    const proc = pm2JsonList().find((item) => item.name === PROCESS_NAME);
+    const managedCurrentDatabase = proc?.pm2_env?.status === "online"
+        && typeof proc.pid === "number"
+        && isGatewayReady(proc.pid);
+    if (!managedCurrentDatabase) return { wasRunning: false };
+
+    requirePm2(["stop", PROCESS_NAME], "pm2 stop Gateway for database maintenance");
+    return { wasRunning: true };
+}
+
+export function restartGatewayAfterMaintenance(state: GatewayMaintenanceState): boolean {
+    if (!state.wasRunning) return false;
+
+    requirePm2(["start", PROCESS_NAME], "pm2 restart Gateway after database maintenance");
+    const started = pm2JsonList().find((item) => item.name === PROCESS_NAME);
+    if (started?.pm2_env?.status !== "online") {
+        throw new Error(
+            `[supertask] Gateway 数据库维护后未恢复 online（状态：${started?.pm2_env?.status ?? "missing"}）`,
+        );
+    }
+    if (typeof started.pid !== "number" || !waitForGatewayReady(started.pid)) {
+        throw new Error("[supertask] Gateway 数据库维护后已 online，但未在限定时间内就绪；请查看 pm2 logs supertask-gateway");
+    }
+    return true;
+}
+
 function findBunPath(): string {
     const override = process.env.SUPERTASK_BUN_BIN;
     if (override) return override;