ework-web 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ework-web",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "ework-web — standalone multi-project issue tracker. Local SQLite-backed, no external API dependency. Bun + TypeScript + SSR HTML.",
   "license": "MIT",

package/src/db-admin.ts

@@ -0,0 +1,566 @@
+// DB-backend UI — Phase 1 (pure logic, no HTTP).
+//
+// Three primitives for the migration wizard: testMysqlConnection (probe a
+// target without side effects), migrateSqliteToMysql (copy every table from
+// the running sqlite driver into a throwaway mysql pool), writeMysqlEnv
+// (forward-fill .env). Design spec: docs/db-backend-ui.md §4.1 + §4.3.
+//
+// The throwaway-pool pattern is load-bearing: every function opens a NEW
+// mysql2 pool with caller-supplied creds and closes it before returning. The
+// running driver (getDB(), opened once at boot) is never touched, so the
+// wizard can fail/retry without affecting live traffic.
+
+import { createPool, type Pool, type PoolConnection } from "mysql2/promise";
+import { Database, type SQLQueryBindings } from "bun:sqlite";
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "fs";
+import { join } from "path";
+import { getDB } from "./db";
+
+export interface MysqlTargetOpts {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  /** Optional table prefix for the target. Empty = no prefix. Validated
+   *  against the same identifier rule as WORK_DB_PREFIX in db.ts so generated
+   *  SQL can't be SQL-injected via the prefix. */
+  prefix?: string;
+}
+
+export type TestMysqlResult =
+  | { ok: true; serverVersion: string; databaseExists: boolean }
+  | { ok: false; error: string; hint?: string };
+
+export type MigrateResult =
+  | { ok: true; tables: { table: string; rows: number }[] }
+  | { ok: false; error: string; partial?: string[] };
+
+export type WriteEnvResult = { written: string[]; envPath: string };
+
+// FK-safe copy order (parents before children). `config` lives first — it's
+// created in db.ts (not in schema.sql), has no FK deps, and holds the
+// migration wizard's own settings. We additionally SET FOREIGN_KEY_CHECKS=0
+// during the copy as belt-and-suspenders; keeping the array FK-ordered still
+// matches what a manual dump/restore would do.
+//
+// When adding a table, update this list AND schema.sql + schema-mysql.sql —
+// otherwise migrate() silently skips the new table.
+export const MIGRATION_TABLE_ORDER = [
+  "config",
+  "users",
+  "projects",
+  "model_cache",
+  "issues",
+  "labels",
+  "comments",
+  "issue_labels",
+  "reactions",
+  "attachments",
+  "webhooks",
+  "personal_access_tokens",
+  "project_members",
+  "webhook_deliveries",
+] as const;
+
+/** Rewrite {{token}} -> prefix+token. Mirrors db.ts:applyPrefix but takes a
+ *  caller-supplied prefix — the target may differ from the running driver's
+ *  (module-private) prefix, and importing DB_PREFIX would couple this module
+ *  to the boot-time env. */
+function applyTargetPrefix(sql: string, prefix: string): string {
+  if (!sql.includes("{{")) return sql;
+  return sql.replace(/\{\{(\w+)\}\}/g, (_m, name: string) => prefix + name);
+}
+
+function validatePrefix(p: string): string {
+  const v = (p ?? "").trim();
+  if (v && !/^[A-Za-z_][A-Za-z0-9_]{0,31}$/.test(v)) {
+    throw new Error(
+      `Invalid DB prefix "${v}": must match ^[A-Za-z_][A-Za-z0-9_]{0,31}$`
+    );
+  }
+  return v;
+}
+
+/** Redact password-shaped substrings from connection-string-like output.
+ *  Covers URL-style `://user:pw@host`, querystring `?password=...` /
+ *  `&password=...`, and shell `password='...'` / `password="..."`. */
+function redactPassword(s: string): string {
+  return s
+    .replace(/(:\/\/[^:/@]*):[^@/]*@/g, "$1:***@")
+    .replace(/[?&]password=[^&\s]*/gi, (m) => m.charAt(0) + "password=***")
+    .replace(/password\s*=\s*'[^']*'/gi, "password='***'")
+    .replace(/password\s*=\s*"[^"]*"/gi, 'password="***"');
+}
+
+function chunk<T>(arr: readonly T[], size: number): T[][] {
+  if (size < 1) throw new Error("chunk size must be >= 1");
+  const out: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) {
+    out.push(arr.slice(i, i + size) as T[]);
+  }
+  return out;
+}
+
+/** Strip `--` comment lines BEFORE splitting on `;` — comment lines may
+ *  contain `;` and corrupt the split (same trick as db.ts:MysqlDriver.create). */
+function readSchemaMysqlStatements(prefix: string): string[] {
+  const raw = readFileSync(join(import.meta.dir, "schema-mysql.sql"), "utf8");
+  const stripped = raw
+    .split("\n")
+    .filter((l) => !l.trimStart().startsWith("--"))
+    .join("\n");
+  const out: string[] = [];
+  for (const stmt of stripped.split(";").map((s) => s.trim()).filter((s) => s.length > 0)) {
+    out.push(applyTargetPrefix(stmt, prefix));
+  }
+  return out;
+}
+
+function hintForError(msg: string): string | undefined {
+  const lc = msg.toLowerCase();
+  if (lc.includes("econnrefused") || lc.includes("enotfound") || lc.includes("etimedout")) {
+    return "Check host and port; is MySQL running and reachable from this host?";
+  }
+  if (lc.includes("access denied") || lc.includes("error 1045") || lc.includes("er_access_denied")) {
+    return "Bad username or password.";
+  }
+  if (lc.includes("unknown database") || lc.includes("error 1049")) {
+    return "Create the database first, or grant CREATE to the user so migrate() can create it.";
+  }
+  if (lc.includes("ssl") || lc.includes("tls")) {
+    return "TLS/SSL handshake failed — check MySQL's TLS config and the client's ssl mode.";
+  }
+  return undefined;
+}
+
+/** Backtick-quote a SQL identifier. Doubles internal backticks per the MySQL
+ *  escape rule. */
+function ident(name: string): string {
+  return "`" + name.replace(/`/g, "``") + "`";
+}
+
+export async function testMysqlConnection(opts: MysqlTargetOpts): Promise<TestMysqlResult> {
+  let pool: Pool | null = null;
+  let conn: PoolConnection | null = null;
+  try {
+    // No database selected at handshake — we may be probing a DB that doesn't
+    // exist yet (user has CREATE but hasn't run it). Selecting a non-existent
+    // DB at connect time would fail the handshake.
+    pool = createPool({
+      host: opts.host,
+      port: opts.port,
+      user: opts.user,
+      password: opts.password,
+      waitForConnections: true,
+      connectionLimit: 2,
+      charset: "utf8mb4",
+      connectTimeout: 10_000,
+    });
+
+    conn = await pool.getConnection();
+    // A real query, NOT mysqladmin ping — the mysql:8.0 entrypoint races a
+    // temp socket-only server during init; ping succeeds during the temp
+    // phase and races the restart. See scripts/test-mysql.sh.
+    const [versionRowsRaw] = await conn.query("SELECT VERSION() AS v");
+    const versionRows = versionRowsRaw as { v: string }[];
+    const version0 = versionRows[0];
+    const serverVersion = version0?.v ?? "unknown";
+
+    const [dbRowsRaw] = await conn.query(
+      "SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = ?",
+      [opts.database]
+    );
+    const dbRows = dbRowsRaw as { SCHEMA_NAME: string }[];
+    const databaseExists = dbRows.length > 0;
+
+    // Best-effort privilege check. We can't cleanly ask "do I have CREATE on
+    // a not-yet-existent DB?" without parsing SHOW GRANTS (the GRANT syntax
+    // has many shapes). If the DB doesn't exist, require CREATE anywhere in
+    // the user's grants. False negatives are fine — the user can create the
+    // DB by hand; false positives get caught at migrate().
+    let hasCreate = true;
+    if (!databaseExists) {
+      const [grantsRaw] = await conn.query("SHOW GRANTS FOR CURRENT_USER()");
+      const grantsRows = grantsRaw as Record<string, string>[];
+      const grants = grantsRows
+        .map((r) => Object.values(r)[0])
+        .filter((v): v is string => typeof v === "string");
+      hasCreate = grants.some((g) => /\bCREATE\b/i.test(g));
+    }
+
+    if (!databaseExists && !hasCreate) {
+      return {
+        ok: false,
+        error: `Database "${opts.database}" does not exist and user "${opts.user}" has no CREATE privilege`,
+        hint: "Create the database first (CREATE DATABASE ... CHARACTER SET utf8mb4) or grant CREATE on it to the user.",
+      };
+    }
+
+    return { ok: true, serverVersion, databaseExists };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+      ok: false,
+      error: redactPassword(msg),
+      hint: hintForError(msg),
+    };
+  } finally {
+    if (conn) {
+      try { conn.release(); } catch (e) { console.warn("[db-admin] conn.release failed:", e); }
+    }
+    if (pool) {
+      try { await pool.end(); } catch (e) { console.warn("[db-admin] pool.end failed:", e); }
+    }
+  }
+}
+
+export async function migrateSqliteToMysql(opts: MysqlTargetOpts): Promise<MigrateResult> {
+  const prefix = validatePrefix(opts.prefix ?? "");
+  let pool: Pool | null = null;
+  let conn: PoolConnection | null = null;
+  const completed: { table: string; rows: number }[] = [];
+
+  try {
+    // Pool WITHOUT `database`: if the target DB doesn't exist yet (the common
+    // migration-wizard case), selecting it at handshake would fail with
+    // "Unknown database". We CREATE + USE on a single held connection below.
+    //
+    // Holding ONE connection for the whole migrate() is load-bearing:
+    // USE, FOREIGN_KEY_CHECKS, and transactions are all session-scoped. With
+    // a pool, sequential pool.query() calls can land on different underlying
+    // connections, so session state set on one wouldn't apply to the next.
+    // One held connection makes that state deterministic.
+    pool = createPool({
+      host: opts.host,
+      port: opts.port,
+      user: opts.user,
+      password: opts.password,
+      waitForConnections: true,
+      connectionLimit: 2,
+      charset: "utf8mb4",
+    });
+
+    conn = await pool.getConnection();
+
+    await conn.query(
+      `CREATE DATABASE IF NOT EXISTS ${ident(opts.database)} CHARACTER SET utf8mb4`
+    );
+    await conn.query(`USE ${ident(opts.database)}`);
+
+    // The `config` table is created in db.ts:SqliteDriver.create at boot but
+    // is missing from schema-mysql.sql (pre-existing gap — MysqlDriver.create
+    // doesn't create it either, so a plain mysql boot has no config table).
+    // Recreate the same shape here so migrate() can copy config rows. `key`
+    // is a MySQL reserved word — must be backticked. VARCHAR(255) on the PK
+    // because MySQL TEXT can't be a PRIMARY KEY without a prefix length.
+    await conn.query(
+      applyTargetPrefix(
+        "CREATE TABLE IF NOT EXISTS {{config}} (" +
+          "`key` VARCHAR(255) PRIMARY KEY," +
+          "value TEXT NOT NULL," +
+          "updated_at VARCHAR(40) NOT NULL" +
+          ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4",
+        prefix
+      )
+    );
+
+    // Apply schema-mysql.sql. CREATE INDEX lacks IF NOT EXISTS in MySQL, so
+    // tolerate ER_DUP_KEYNAME (1061) for re-runs.
+    for (const stmt of readSchemaMysqlStatements(prefix)) {
+      try {
+        await conn.query(stmt);
+      } catch (e) {
+        if (
+          e && typeof e === "object" && "errno" in e &&
+          (e as { errno: number }).errno === 1061
+        ) {
+          continue;
+        }
+        throw e;
+      }
+    }
+
+    // Idempotent re-run: TRUNCATE resets data + AUTO_INCREMENT. FK_CHECKS=0
+    // lets us TRUNCATE tables that are referenced by others (TRUNCATE
+    // otherwise refuses even on empty data). Stays 0 for the whole copy
+    // phase; reset to 1 once every table has been inserted + verified.
+    await conn.query("SET FOREIGN_KEY_CHECKS = 0");
+    for (const t of MIGRATION_TABLE_ORDER) {
+      await conn.query(`TRUNCATE TABLE ${ident(prefix + t)}`);
+    }
+
+    const sqlite = getDB();
+    for (const table of MIGRATION_TABLE_ORDER) {
+      const rows = await sqlite.all<Record<string, unknown>>(
+        `SELECT * FROM {{${table}}}`
+      );
+      if (rows.length === 0) {
+        completed.push({ table, rows: 0 });
+        continue;
+      }
+      const first = rows[0];
+      if (!first) {
+        // Unreachable given length>0; noUncheckedIndexedAccess forces the guard.
+        completed.push({ table, rows: 0 });
+        continue;
+      }
+      const cols = Object.keys(first);
+      if (cols.length === 0) {
+        completed.push({ table, rows: rows.length });
+        continue;
+      }
+
+      // `INSERT INTO t (a,b) VALUES ?` with a 2D array — mysql2 expands the
+      // nested arrays into a comma-separated value list. undefined → null
+      // (sqlite rows shouldn't have undefined fields, but JS-side defaults
+      // sometimes do; mysql2 rejects undefined).
+      const insertSql =
+        `INSERT INTO ${ident(prefix + table)}` +
+        ` (${cols.map(ident).join(",")}) VALUES ?`;
+
+      // Per-table transaction: a bad batch rolls back THIS table's inserts
+      // without touching earlier tables. (DDL above already auto-committed;
+      // only the INSERTs are transactional.)
+      try {
+        await conn.beginTransaction();
+        for (const batch of chunk(rows, 500)) {
+          const matrix: unknown[][] = batch.map((r) =>
+            cols.map((c) => {
+              const v = r[c];
+              return v === undefined ? null : v;
+            })
+          );
+          await conn.query(insertSql, [matrix]);
+        }
+        await conn.commit();
+      } catch (e) {
+        try { await conn.rollback(); } catch (rollbackErr) {
+          console.warn("[db-admin] rollback failed for", table, ":", rollbackErr);
+        }
+        throw e;
+      }
+
+      const [cntRowsRaw] = await conn.query(
+        `SELECT COUNT(*) AS c FROM ${ident(prefix + table)}`
+      );
+      const cntRows = cntRowsRaw as { c: number }[];
+      const cnt0 = cntRows[0];
+      const mysqlCount = cnt0?.c ?? -1;
+      if (mysqlCount !== rows.length) {
+        throw new Error(
+          `Row-count mismatch for ${prefix}${table}: sqlite=${rows.length} mysql=${mysqlCount}`
+        );
+      }
+      completed.push({ table, rows: rows.length });
+    }
+
+    await conn.query("SET FOREIGN_KEY_CHECKS = 1");
+    return { ok: true, tables: completed };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // DDL above auto-committed (MySQL implicit commit on DDL), so ROLLBACK
+    // wouldn't undo CREATE TABLE. Explicitly DROP every half-built table so
+    // the next migrate() call starts from a clean target.
+    if (conn) {
+      try {
+        await conn.query("SET FOREIGN_KEY_CHECKS = 0");
+        for (const t of MIGRATION_TABLE_ORDER) {
+          await conn.query(`DROP TABLE IF EXISTS ${ident(prefix + t)}`);
+        }
+        await conn.query("SET FOREIGN_KEY_CHECKS = 1");
+      } catch (cleanupErr) {
+        // The migrate() failure is the primary signal. A cleanup failure
+        // leaves stale tables; the next migrate() run will TRUNCATE them.
+        console.warn("[db-admin] cleanup DROP TABLES failed:", cleanupErr);
+      }
+    }
+    return {
+      ok: false,
+      error: redactPassword(msg),
+      partial: completed.map((c) => `${c.table}=${c.rows}`),
+    };
+  } finally {
+    if (conn) {
+      try { conn.release(); } catch (e) { console.warn("[db-admin] conn.release failed:", e); }
+    }
+    if (pool) {
+      try { await pool.end(); } catch (e) { console.warn("[db-admin] pool.end failed:", e); }
+    }
+  }
+}
+
+export async function writeMysqlEnv(
+  envPath: string,
+  opts: MysqlTargetOpts
+): Promise<WriteEnvResult> {
+  const prefix = validatePrefix(opts.prefix ?? "");
+
+  // PASSWORD is written verbatim — the .env file is mode 0600 (deploy.sh
+  // enforces) and the existing .env format is bare KEY=VALUE (see
+  // .env.example). If a password contains '#' or whitespace, the user must
+  // hand-quote; we don't try to be smart about shell quoting because Bun's
+  // env loader / systemd EnvironmentFile is the source of truth.
+  const desired: Record<string, string> = {
+    WORK_DB_DRIVER: "mysql",
+    WORK_DB_HOST: opts.host,
+    WORK_DB_PORT: String(opts.port),
+    WORK_DB_USER: opts.user,
+    WORK_DB_PASSWORD: opts.password,
+    WORK_DB_NAME: opts.database,
+  };
+  if (prefix) desired.WORK_DB_PREFIX = prefix;
+
+  const linesIn = existsSync(envPath)
+    ? readFileSync(envPath, "utf8").split(/\r?\n/)
+    : [];
+
+  const written: string[] = [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+
+  // First pass: update existing keys in place (preserves comments + order).
+  // Matches the project's .env style: `KEY=VALUE`, no surrounding quotes.
+  for (const line of linesIn) {
+    const m = line.match(/^([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/);
+    if (m) {
+      const key = m[1] ?? "";
+      if (key in desired) {
+        out.push(`${key}=${desired[key] ?? ""}`);
+        written.push(key);
+        seen.add(key);
+        continue;
+      }
+    }
+    out.push(line);
+  }
+
+  // Second pass: append missing keys under a legible banner.
+  const missing = Object.keys(desired).filter((k) => !seen.has(k));
+  if (missing.length > 0) {
+    if (out.length > 0 && out[out.length - 1] !== "") out.push("");
+    out.push("# ework-web: MySQL backend (written by db-admin migration)");
+    for (const k of missing) {
+      out.push(`${k}=${desired[k] ?? ""}`);
+      written.push(k);
+    }
+  }
+
+  writeFileSync(envPath, out.join("\n") + "\n", "utf8");
+  return { written, envPath };
+}
+
+// Reverse migration: MySQL → SQLite. Creates a fresh SQLite file at targetPath,
+// applies schema.sql, copies all 14 tables from the running MySQL driver.
+// Used as the safety net when the MySQL switch goes wrong.
+export async function migrateMysqlToSqlite(targetPath: string): Promise<MigrateResult> {
+  const target = new Database(targetPath, { create: true, readwrite: true });
+  const completed: { table: string; rows: number }[] = [];
+
+  try {
+    target.exec("PRAGMA journal_mode = WAL");
+    target.exec("PRAGMA foreign_keys = ON");
+
+    // config table (same shape as db.ts:144 — not in schema.sql).
+    // `key` is NOT reserved in SQLite (unlike MySQL).
+    target.exec(
+      applyTargetPrefix(
+        "CREATE TABLE IF NOT EXISTS {{config}} (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL)",
+        ""
+      )
+    );
+
+    // schema.sql — bun:sqlite's exec handles the whole file (comments + multi-statement).
+    const schema = readFileSync(join(import.meta.dir, "schema.sql"), "utf8");
+    target.exec(applyTargetPrefix(schema, ""));
+
+    const source = getDB();
+    for (const table of MIGRATION_TABLE_ORDER) {
+      const rows = await source.all<Record<string, unknown>>(`SELECT * FROM {{${table}}}`);
+      if (rows.length === 0) {
+        completed.push({ table, rows: 0 });
+        continue;
+      }
+      const first = rows[0];
+      if (!first) {
+        completed.push({ table, rows: 0 });
+        continue;
+      }
+      const cols = Object.keys(first);
+      if (cols.length === 0) {
+        completed.push({ table, rows: rows.length });
+        continue;
+      }
+
+      const placeholders = cols.map(() => "?").join(",");
+      const insertSql = `INSERT INTO ${table} (${cols.join(",")}) VALUES (${placeholders})`;
+
+      target.transaction(() => {
+        for (const row of rows) {
+          const vals = cols.map((c) => {
+            const v = (row as Record<string, unknown>)[c];
+            return v === undefined ? null : v;
+          });
+          target.query(insertSql).run(...(vals as SQLQueryBindings[]));
+        }
+      })();
+
+      const countRow = target.query(`SELECT COUNT(*) AS c FROM ${table}`).get() as { c: number } | null;
+      const count = countRow?.c ?? -1;
+      if (count !== rows.length) {
+        throw new Error(`Row-count mismatch for ${table}: mysql=${rows.length} sqlite=${count}`);
+      }
+      completed.push({ table, rows: rows.length });
+    }
+
+    target.close();
+    return { ok: true, tables: completed };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    try { target.close(); } catch { /* already closed */ }
+    try { unlinkSync(targetPath); } catch { /* file may not exist */ }
+    return { ok: false, error: redactPassword(msg), partial: completed.map((c) => `${c.table}=${c.rows}`) };
+  }
+}
+
+export async function writeSqliteEnv(envPath: string, dbPath: string): Promise<WriteEnvResult> {
+  const desired: Record<string, string> = {
+    WORK_DB_DRIVER: "sqlite",
+    WORK_DB_PATH: dbPath,
+  };
+
+  const linesIn = existsSync(envPath)
+    ? readFileSync(envPath, "utf8").split(/\r?\n/)
+    : [];
+
+  const written: string[] = [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+
+  for (const line of linesIn) {
+    const m = line.match(/^([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/);
+    if (m) {
+      const key = m[1] ?? "";
+      if (key in desired) {
+        out.push(`${key}=${desired[key] ?? ""}`);
+        written.push(key);
+        seen.add(key);
+        continue;
+      }
+    }
+    out.push(line);
+  }
+
+  const missing = Object.keys(desired).filter((k) => !seen.has(k));
+  if (missing.length > 0) {
+    if (out.length > 0 && out[out.length - 1] !== "") out.push("");
+    out.push("# ework-web: revert to SQLite (written by db-admin migration)");
+    for (const k of missing) {
+      out.push(`${k}=${desired[k] ?? ""}`);
+      written.push(k);
+    }
+  }
+
+  writeFileSync(envPath, out.join("\n") + "\n", "utf8");
+  return { written, envPath };
+}

package/src/index.ts

@@ -1,9 +1,13 @@
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { readFileSync, appendFileSync } from "fs";
+import { readFileSync, appendFileSync, existsSync } from "fs";
+import { spawn } from "child_process";
+import { homedir } from "os";
 import { loadConfig, DB_OVERRIDABLE, parseOverride, resolveTtsBackend } from "./config";
 import type { Config } from "./config";
 import { setConfig, initDB } from "./db";
+import { testMysqlConnection, migrateSqliteToMysql, writeMysqlEnv, migrateMysqlToSqlite, writeSqliteEnv } from "./db-admin";
+import type { MysqlTargetOpts } from "./db-admin";
 import { checkAuth, makeAuthCookieHeader, clearAuthCookieHeader, loginHTML, sanitizeNext, ensureBootstrapAdmin, ensureBootstrapSystem, isReservedSystemLogin } from "./auth";
 import { OpencodeClient, OpencodeError } from "./opencode";
 import { renderMarkdown } from "./render/markdown";
@@ -172,6 +176,98 @@ function html(body: string, status = 200): Response {
   });
 }
 
+// The prefix regex below must match db.ts:WORK_DB_PREFIX exactly — if the API
+// accepts a prefix that boot rejects, the wizard writes a .env that restarts
+// into a crash. Any change here must be mirrored in db.ts + db-admin.ts.
+function parseDbTargetOpts(payload: unknown): MysqlTargetOpts | { error: string } {
+  if (typeof payload !== "object" || payload === null) return { error: "invalid body" };
+  const p = payload as Record<string, unknown>;
+  const host = typeof p.host === "string" ? p.host.trim() : "";
+  const portNum = Number(p.port);
+  const user = typeof p.user === "string" ? p.user.trim() : "";
+  const password = typeof p.password === "string" ? p.password : "";
+  const database = typeof p.database === "string" ? p.database.trim() : "";
+  const prefix = typeof p.prefix === "string" ? p.prefix.trim() : "";
+  if (!host) return { error: "host required" };
+  if (!user) return { error: "user required" };
+  if (!database) return { error: "database required" };
+  if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) {
+    return { error: "port must be an integer 1-65535" };
+  }
+  if (prefix && !/^[A-Za-z_][A-Za-z0-9_]{0,31}$/.test(prefix)) {
+    return { error: "prefix must match ^[A-Za-z_][A-Za-z0-9_]{0,31}$" };
+  }
+  const opts: MysqlTargetOpts = { host, port: portNum, user, password, database };
+  if (prefix) opts.prefix = prefix;
+  return opts;
+}
+
+// Two restart paths depending on how this process was launched. Both run
+// AFTER the HTTP response is sent (caller schedules this last):
+//   systemd (INVOCATION_ID set): exit → the unit's Restart=always brings us back
+//   PID-file mode (ework-aio start): `ework-aio restart web` SIGTERMs us via the
+//     pidfile and spawns a fresh process that re-reads the updated .env.
+// The ework-aio spawn is UNSAFE under systemd — it would start a second process
+// on the same port — so the INVOCATION_ID gate is load-bearing.
+function scheduleRestart(): void {
+  if (process.env.INVOCATION_ID) {
+    setTimeout(() => process.exit(0), 750);
+    return;
+  }
+  const child = spawn("ework-aio", ["restart", "web"], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.on("error", () => {
+    // ework-aio not on PATH (dev mode) — best-effort exit; if no supervisor
+    // is watching, the admin restarts manually.
+    setTimeout(() => process.exit(0), 750);
+  });
+  child.unref();
+}
+
+// The daemon's `issues` table (thin ref) collides with the web's `issues`
+// table (full content) if they share a database. The daemon MUST use a
+// different prefix. We append "d_" to whatever the web uses so both can
+// coexist in one database without the operator having to plan prefixes.
+function daemonPrefix(webPrefix: string): string {
+  return webPrefix + "d_";
+}
+
+function daemonEnvPath(): string | null {
+  const dataDir = process.env.WORK_DAEMON_DATA_DIR;
+  if (dataDir) {
+    const p = join(dataDir, ".env");
+    return existsSync(p) ? p : null;
+  }
+  const conventional = join(homedir(), ".local", "share", "ework-daemon", ".env");
+  return existsSync(conventional) ? conventional : null;
+}
+
+function spawnDaemonRestart(): void {
+  try {
+    const child = spawn("ework-aio", ["restart", "daemon"], { detached: true, stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // best-effort — the manual fallback path covers this
+  }
+}
+
+function daemonManualInstructions(opts: MysqlTargetOpts): string {
+  return [
+    "将以下内容追加到 daemon 的 .env，然后运行 ework-aio restart daemon：",
+    "",
+    `WORK_DB_DRIVER=mysql`,
+    `WORK_DB_HOST=${opts.host}`,
+    `WORK_DB_PORT=${opts.port}`,
+    `WORK_DB_USER=${opts.user}`,
+    "WORK_DB_PASSWORD=<daemon密码>",
+    `WORK_DB_NAME=${opts.database}`,
+    `WORK_DB_PREFIX=${opts.prefix ?? ""}`,
+  ].join("\n");
+}
+
 const REPO_ISSUE_RE = /^\/([^/]+)\/([^/]+)\/issues\/(\d+)$/;
 const REPO_LIST_RE = /^\/([^/]+)\/([^/]+)\/issues$/;
 const REPO_NEW_RE = /^\/([^/]+)\/([^/]+)\/issues\/new$/;
@@ -274,6 +370,7 @@ function chunkTextTTS(text: string, max = 120): string[] {
 
 async function handle(req: Request, url: URL, ip: string, ctx: { authed: boolean; user: UserRow | null }): Promise<Response> {
   if (url.pathname === "/static/app.js") return staticAsset("app.js", "text/javascript; charset=utf-8", req);
+  if (url.pathname === "/static/db-wizard.js") return staticAsset("db-wizard.js", "text/javascript; charset=utf-8", req);
   if (url.pathname === "/static/session.js") return staticAsset("session.js", "text/javascript; charset=utf-8", req);
   if (url.pathname === "/static/file.js") return staticAsset("file.js", "text/javascript; charset=utf-8", req);
   if (url.pathname === "/static/tts.js") return staticAsset("tts.js", "text/javascript; charset=utf-8", req);
@@ -605,6 +702,68 @@ async function handle(req: Request, url: URL, ip: string, ctx: { authed: boolean
     return new Response(stream, { status: 200, headers });
   }
 
+  if (req.method === "POST" && url.pathname === "/api/db/test") {
+    if (!ctx.user || ctx.user.is_admin !== 1) return json({ error: "admin required" }, 403);
+    if (!rateLimit(`db-test:${ip}`, 5, 5 / 60)) return json({ error: "rate limited" }, 429);
+    const payload = await req.json().catch(() => ({}));
+    const parsed = parseDbTargetOpts(payload);
+    if ("error" in parsed) return json(parsed, 400);
+    const result = await testMysqlConnection(parsed);
+    return json(result, result.ok ? 200 : 422);
+  }
+
+  if (req.method === "POST" && url.pathname === "/api/db/migrate") {
+    if (!ctx.user || ctx.user.is_admin !== 1) return json({ error: "admin required" }, 403);
+    if (!rateLimit(`db-migrate:${ip}`, 2, 2 / 3600)) return json({ error: "rate limited" }, 429);
+    const payload = await req.json().catch(() => ({}));
+    const parsed = parseDbTargetOpts(payload);
+    if ("error" in parsed) return json(parsed, 400);
+    const result = await migrateSqliteToMysql(parsed);
+    return json(result, result.ok ? 200 : 422);
+  }
+
+  if (req.method === "POST" && url.pathname === "/api/db/enable") {
+    if (!ctx.user || ctx.user.is_admin !== 1) return json({ error: "admin required" }, 403);
+    if (!rateLimit(`db-enable:${ip}`, 3, 3 / 3600)) return json({ error: "rate limited" }, 429);
+    const payload = await req.json().catch(() => ({}));
+    const parsed = parseDbTargetOpts(payload);
+    if ("error" in parsed) return json(parsed, 400);
+    const envResult = await writeMysqlEnv(join(process.cwd(), ".env"), parsed);
+    scheduleRestart();
+    return json({ ok: true, ...envResult, restarting: true });
+  }
+
+  if (req.method === "POST" && url.pathname === "/api/db/daemon-config") {
+    if (!ctx.user || ctx.user.is_admin !== 1) return json({ error: "admin required" }, 403);
+    if (!rateLimit(`db-daemon:${ip}`, 3, 3 / 3600)) return json({ error: "rate limited" }, 429);
+    const rawPayload = await req.json().catch(() => ({}));
+    const parsed = parseDbTargetOpts(rawPayload);
+    if ("error" in parsed) return json(parsed, 400);
+    const daemonOpts: MysqlTargetOpts = { ...parsed, prefix: daemonPrefix(parsed.prefix ?? "") };
+    const envPath = daemonEnvPath();
+    if (!envPath) {
+      return json({ ok: false, configured: false, manual: daemonManualInstructions(daemonOpts) });
+    }
+    try {
+      const written = await writeMysqlEnv(envPath, daemonOpts);
+      spawnDaemonRestart();
+      return json({ ok: true, configured: true, envPath, written: written.written });
+    } catch (e) {
+      return json({ ok: false, configured: false, error: errMsg(e), manual: daemonManualInstructions(daemonOpts) });
+    }
+  }
+
+  if (req.method === "POST" && url.pathname === "/api/db/revert") {
+    if (!ctx.user || ctx.user.is_admin !== 1) return json({ error: "admin required" }, 403);
+    if (!rateLimit(`db-revert:${ip}`, 2, 2 / 3600)) return json({ error: "rate limited" }, 429);
+    const targetPath = join(process.cwd(), "ework.sqlite");
+    const result = await migrateMysqlToSqlite(targetPath);
+    if (!result.ok) return json(result, 422);
+    await writeSqliteEnv(join(process.cwd(), ".env"), targetPath);
+    scheduleRestart();
+    return json({ ...result, targetPath, restarting: true });
+  }
+
   if (url.pathname === "/settings") {
     if (req.method === "GET") {
       return html(buildSettingsPage(cfg, url.searchParams.get("saved") === "1", ctx.user!, await listCachedModels()).html);

package/src/static/db-wizard.js

@@ -0,0 +1,106 @@
+// DB-backend migration wizard (settings page). External file because CSP
+// script-src 'self' blocks inline scripts — see index.ts SEC_HEADERS.
+(function () {
+  if (!document.getElementById('db-test')) return;
+  var R = document.getElementById('db-result');
+
+  function get(id) { return document.getElementById(id).value; }
+  function gather() {
+    return JSON.stringify({
+      host: get('db-host').trim(),
+      port: Number(get('db-port')),
+      user: get('db-user').trim(),
+      password: get('db-password'),
+      database: get('db-database').trim(),
+      prefix: get('db-prefix').trim()
+    });
+  }
+  function setBtns(d) {
+    document.querySelectorAll('.db-controls button').forEach(function (b) { b.disabled = d; });
+  }
+
+  async function act(action) {
+    if (action === 'enable' && !confirm('确认启用 MySQL 并重启？确保已完成 ① 测试 + ② 迁移。')) return;
+    setBtns(true);
+    R.className = 'db-result db-loading';
+    R.textContent = action === 'enable' ? '正在写入 .env，进程即将重启…' : '处理中…';
+    try {
+      var res = await fetch('/api/db/' + action, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: gather()
+      });
+      var data = await res.json();
+      if (action === 'enable' && data.ok) {
+        R.className = 'db-result db-ok';
+        R.textContent = '✓ .env 已写入。进程重启中，等待恢复…';
+        setTimeout(poll, 3000);
+        return;
+      }
+      if (action === 'daemon-config') {
+        R.className = 'db-result ' + (data.configured ? 'db-ok' : 'db-err');
+        R.textContent = data.configured
+          ? '✓ daemon 已写入 .env 并重启:\n  ' + data.envPath
+          : '⚠ daemon 无法自动配置（.env 未找到）。请手动操作:\n\n' + (data.manual || data.error || '');
+        return;
+      }
+      R.className = 'db-result ' + (data.ok ? 'db-ok' : 'db-err');
+      if (!data.ok) {
+        var m = '✗ ' + (data.error || '未知错误');
+        if (data.hint) m += '\n💡 ' + data.hint;
+        R.textContent = m;
+      } else if (data.tables) {
+        R.textContent = '✓ 迁移完成（' + data.tables.length + ' 张表）:\n' +
+          data.tables.map(function (t) { return '  ' + t.table + ': ' + t.rows + ' 行'; }).join('\n');
+      } else if (data.serverVersion) {
+        R.textContent = '✓ 连接成功 · MySQL ' + data.serverVersion +
+          (data.databaseExists ? '' : '（库不存在，迁移时自动创建）');
+      }
+    } catch (e) {
+      R.className = 'db-result db-err';
+      R.textContent = '✗ ' + (e.message || String(e));
+    } finally {
+      if (action !== 'enable') setBtns(false);
+    }
+  }
+
+  async function poll() {
+    try { await fetch('/'); location.href = '/settings?saved=1'; }
+    catch (e) { setTimeout(poll, 2000); }
+  }
+
+  document.getElementById('db-test').onclick = function () { act('test'); };
+  document.getElementById('db-migrate').onclick = function () { act('migrate'); };
+  document.getElementById('db-daemon').onclick = function () { act('daemon-config'); };
+  document.getElementById('db-enable').onclick = function () { act('enable'); };
+
+  var revertBtn = document.getElementById('db-revert');
+  if (revertBtn) {
+    revertBtn.onclick = async function () {
+      if (!confirm('确认切回 SQLite？将创建新的 SQLite 文件并迁移数据，然后重启。')) return;
+      var Rr = document.getElementById('db-revert-result');
+      Rr.className = 'db-result db-loading';
+      Rr.textContent = '正在迁移到 SQLite…';
+      try {
+        var res = await fetch('/api/db/revert', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: '{}'
+        });
+        var data = await res.json();
+        if (data.ok) {
+          Rr.className = 'db-result db-ok';
+          Rr.textContent = '✓ 已迁移到 ' + data.targetPath + '。进程重启中…';
+          setTimeout(poll, 3000);
+        } else {
+          Rr.className = 'db-result db-err';
+          Rr.textContent = '✗ ' + (data.error || '未知错误') +
+            (data.partial ? '\n部分完成: ' + data.partial.join(', ') : '');
+        }
+      } catch (e) {
+        Rr.className = 'db-result db-err';
+        Rr.textContent = '✗ ' + (e.message || String(e));
+      }
+    };
+  }
+})();

package/src/views/settings.ts

@@ -38,6 +38,35 @@ function fieldInput(group: SettingGroup, cfg: Config, models: CachedModel[]): st
     .join("");
 }
 
+function buildDbSection(viewer: UserRow): string {
+  if (viewer.is_admin !== 1) return "";
+  const driver = process.env.WORK_DB_DRIVER || "sqlite";
+  const isMysql = driver === "mysql";
+  const currentTarget = isMysql
+    ? `${process.env.WORK_DB_HOST ?? "?"}:${process.env.WORK_DB_PORT ?? "3306"}/${process.env.WORK_DB_NAME ?? "?"}`
+    : `SQLite · ${process.env.WORK_DB_PATH ?? "默认路径"}`;
+  return `<section class="sg db-section">
+<h2>数据库后端</h2>
+<p class="db-badge">当前后端: <strong>${escapeHtml(driver.toUpperCase())}</strong> · ${escapeHtml(currentTarget)}</p>
+<div class="db-warn">⚠ 切换到 MySQL 后 Web 进程会重启并以 MySQL 为存储。若 MySQL 不可达，进程无法启动——需手动编辑 <code>.env</code> 将 <code>WORK_DB_DRIVER</code> 改回 <code>sqlite</code> 才能恢复。流程：先 ① 测试连接、再 ② 迁移数据、最后 ③ 启用。</div>
+<label class="sf"><span>MySQL 主机</span><input type="text" id="db-host" placeholder="127.0.0.1" autocomplete="off"></label>
+<label class="sf"><span>端口</span><input type="number" id="db-port" value="3306" min="1" max="65535" autocomplete="off"></label>
+<label class="sf"><span>用户名</span><input type="text" id="db-user" placeholder="ework" autocomplete="off"></label>
+<label class="sf"><span>密码</span><input type="password" id="db-password" placeholder="••••••" autocomplete="new-password"></label>
+<label class="sf"><span>数据库名</span><input type="text" id="db-database" placeholder="ework" autocomplete="off"></label>
+<label class="sf"><span>表前缀（可选）</span><input type="text" id="db-prefix" placeholder="留空 = 无前缀" autocomplete="off"></label>
+<div class="db-controls">
+<button type="button" id="db-test">① 测试连接</button>
+<button type="button" id="db-migrate" class="secondary">② 迁移数据</button>
+<button type="button" id="db-daemon" class="secondary">③ 配置 daemon</button>
+<button type="button" id="db-enable" class="secondary">④ 启用并重启</button>
+</div>
+<div id="db-result" class="db-result"></div>
+${isMysql ? `<hr style="border:0;border-top:1px solid var(--border);margin:1rem 0"><div class="db-controls"><button type="button" id="db-revert" class="secondary">⚠ 切回 SQLite（安全网）</button></div><div id="db-revert-result" class="db-result"></div>` : ""}
+<script src="/static/db-wizard.js"></script>
+</section>`;
+}
+
 export function buildSettingsPage(cfg: Config, saved: boolean, viewer: UserRow, models: CachedModel[]): { html: string } {
   const groups = SETTINGS_GROUPS.map(
     (g) =>
@@ -70,6 +99,16 @@ h1{font-size:18px;margin:0 0 .4rem}
 button{padding:.5rem 1.2rem;border:0;border-radius:6px;background:var(--accent);color:#fff;font-size:13px;cursor:pointer}
 button.secondary{background:transparent;color:var(--text-muted);border:1px solid var(--border)}
 .a-back{color:var(--text-muted);font-size:13px}
+.db-badge{font-size:13px;color:var(--text-muted);margin:0 0 .5rem}
+.db-badge strong{color:var(--text)}
+.db-warn{background:rgba(255,193,7,.12);color:#d4a942;padding:.5rem .7rem;border-radius:6px;font-size:12px;margin:0 0 .7rem;line-height:1.5}
+.db-warn code{background:var(--bg);padding:.1rem .3rem;border-radius:3px;font-size:11px}
+.db-controls{display:flex;gap:.6rem;flex-wrap:wrap;margin-top:.6rem}
+.db-result{margin-top:.6rem;padding:.5rem .7rem;border-radius:6px;font-size:13px;white-space:pre-wrap;min-height:1.2rem;line-height:1.5}
+.db-result:empty{display:none}
+.db-result.db-loading{background:var(--bg);color:var(--text-muted)}
+.db-result.db-ok{background:rgba(40,167,69,.15);color:#5eb88a}
+.db-result.db-err{background:rgba(220,53,69,.15);color:#e87c7c}
 </style></head><body>
 <header class="nav"><a href="/" style="color:var(--header-text)">🏠 ework-web</a><span style="opacity:.8"> · 设置</span></header>
 <main class="wrap">
@@ -81,6 +120,7 @@ ${banner}
 </form>
 ${modelRefreshForm}
 ${ttsLink}
+${buildDbSection(viewer)}
 </main></body></html>`;
   return { html };
 }