feat: 后端 SQLite→PostgreSQL 迁移(双驱动)——codes/showcase/sync/chibi/payment/security 全链路支持 pg,修复 grant 保留字,schema 双 DDL 导出

This commit is contained in:
Sisyphus committed 2026-08-19 19:12:26 +08:00
1 parent 346f41d391
commit 605af4cdd3
17 files changed
+1516 -2202

No files matched your search

+191 -33
View File
@@ -1,29 +1,73 @@
import Database from "better-sqlite3";
import { Pool } from "pg";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { SCHEMA_SQL } from "./schema.js";
import { SCHEMA_SQL_SQLITE, SCHEMA_SQL_PG } from "./schema.js";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
let _db: Database.Database | null = null;
/**
* 默认 PostgreSQL 连接串:test2 环境,库名 perler_lab。
* 可用 DATABASE_URL 环境变量覆盖。
*/
export const DEFAULT_DATABASE_URL =
"postgres://pgsql:XGYnJPysCNJsLeea@172.16.0.11:54322/perler_lab";
export interface DbConfig {
// ---------------------------------------------------------------------------
// DB 类型联合:业务代码同时支持 SQLite(测试/本地)与 PostgreSQL(生产)。
// tests 继续用 better-sqlite3 内存库(同步 API);生产链路走 pg Pool(异步)。
// ---------------------------------------------------------------------------
export type SqliteDb = Database.Database;
export type PgDb = Pool;
export type Db = SqliteDb | PgDb;
/** 类型守卫:pg Pool 拥有 query 方法,better-sqlite3 没有。 */
export function isPgDb(db: Db): db is PgDb {
return typeof (db as Readonly<{ query?: unknown }>).query === "function";
}
/** SQLite 连接配置(createTestDatabase 之外的本地文件/迁移模式)。 */
export interface SqliteConfig {
/** Path to the SQLite database file. Default: <project-root>/data/perler-lab.db */
dbPath?: string;
/** Enable WAL mode for better concurrent read performance. Default: true */
wal?: boolean;
}
/** PostgreSQL 连接配置。connectionString 缺省取 DATABASE_URL,再回退 DEFAULT_DATABASE_URL。 */
export interface PgConfig {
connectionString?: string;
}
export type DbConfig = SqliteConfig | PgConfig;
let _pool: PgDb | null = null;
let _sqlite: SqliteDb | null = null;
/**
* Initialize the database: open connection, run migrations, set pragmas.
* Idempotent — safe to call multiple times.
* Initialize the database — idempotent, safe to call multiple times.
*
* - 传入 dbPath / 不传 connectionString 的纯 SqliteConfig → 打开 SQLite 文件库(同步返回 Database),
* 供迁移测试与本地回退使用。
* - 否则(默认 / 传 connectionString)→ 创建 PostgreSQL 连接池并跑迁移(异步返回 Pool)。
*/
export function initDatabase(config?: DbConfig): Database.Database {
if (_db) return _db;
export function initDatabase(config?: SqliteConfig): SqliteDb;
export function initDatabase(config?: PgConfig): Promise<PgDb>;
export function initDatabase(config?: DbConfig): SqliteDb | Promise<PgDb> {
if (config === undefined || "connectionString" in config) {
return initPg(config as PgConfig | undefined);
}
return initSqlite(config as SqliteConfig);
}
/** 打开并迁移 SQLite 文件库(保留此路径供 showcase 迁移测试与本地开发)。 */
function initSqlite(config: SqliteConfig): SqliteDb {
if (_sqlite) return _sqlite;
const dbPath =
config?.dbPath ??
config.dbPath ??
process.env["DB_PATH"] ??
path.resolve(__dirname, "..", "..", "data", "perler-lab.db");
@@ -34,31 +78,63 @@ export function initDatabase(config?: DbConfig): Database.Database {
const db = new Database(dbPath);
// Performance & safety pragmas
db.pragma("journal_mode = WAL");
if (config.wal !== false) db.pragma("journal_mode = WAL");
db.pragma("foreign_keys = ON");
db.pragma("busy_timeout = 5000");
db.pragma("synchronous = NORMAL");
// Run migrations
runMigrations(db);
runSqliteMigrations(db);
_db = db;
_sqlite = db;
return db;
}
/**
* Run all pending migrations. Currently just applies the schema DDL.
*/
function runMigrations(db: Database.Database): void {
db.exec(SCHEMA_SQL);
migrateShowcaseSpec(db);
/** 创建 PostgreSQL 连接池并跑迁移。 */
async function initPg(config?: PgConfig): Promise<PgDb> {
if (_pool) return _pool;
const connectionString =
config?.connectionString ?? process.env["DATABASE_URL"] ?? DEFAULT_DATABASE_URL;
const pool = new Pool({
connectionString,
max: 10,
idleTimeoutMillis: 30_000,
connectionTimeoutMillis: 5_000,
});
pool.on("error", (err) => {
console.error("PostgreSQL pool error:", err);
});
await runPgMigrations(pool);
_pool = pool;
return pool;
}
/** SQLite 迁移:整段 DDL + showcase_works 规格列补齐(幂等)。 */
function runSqliteMigrations(db: SqliteDb): void {
db.exec(SCHEMA_SQL_SQLITE);
migrateShowcaseSpecSqlite(db);
}
/** PostgreSQL 迁移:逐条执行 DDL + showcase_works 规格列补齐(information_schema)。 */
async function runPgMigrations(pool: PgDb): Promise<void> {
// 单条 query 不能同时执行多条语句,逐条拆分执行;DDL 无参数,简单协议即安全。
const statements = SCHEMA_SQL_PG.split(";")
.map((s) => s.trim())
.filter((s) => s.length > 0);
for (const stmt of statements) {
await pool.query(stmt);
}
await migrateShowcaseSpecPg(pool);
}
/**
* 为 T-099~T-102 期间创建的旧 showcase_works 表补齐规格列。
* 为 T-099~T-102 期间创建的旧 showcase_works 表补齐规格列(SQLite 版)。
* 新库由 SCHEMA_SQL 一次性建全列;旧库逐列 ALTER TABLE ADD COLUMN(幂等)。
*/
function migrateShowcaseSpec(db: Database.Database): void {
function migrateShowcaseSpecSqlite(db: SqliteDb): void {
const columns = new Set(
(db.prepare("PRAGMA table_info(showcase_works)").all() as Array<{ name: string }>).map(
(col) => col.name,
@@ -78,34 +154,116 @@ function migrateShowcaseSpec(db: Database.Database): void {
}
}
/** PostgreSQL 版规格列补齐:information_schema 查询列,缺列逐列 ALTER(幂等)。 */
async function migrateShowcaseSpecPg(pool: PgDb): Promise<void> {
const reg = await pool.query("SELECT to_regclass('public.showcase_works') AS reg");
if (reg.rows[0]?.reg === null) return; // 表不存在:新库将由 SCHEMA_SQL_PG 建全列
const cols = await pool.query(
"SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'showcase_works'",
);
const columns = new Set(
(cols.rows as ReadonlyArray<{ column_name: string }>).map((c) => c.column_name),
);
const additions: ReadonlyArray<[name: string, declaration: string]> = [
["width", "INTEGER"],
["height", "INTEGER"],
["brand", "TEXT"],
["materials", "TEXT"],
];
for (const [name, declaration] of additions) {
if (!columns.has(name)) {
await pool.query(`ALTER TABLE showcase_works ADD COLUMN ${name} ${declaration}`);
}
}
}
/**
* Get the active database instance. Throws if not initialized.
* 生产返回 pg Pool;sqlite 文件模式返回 Database。
*/
export function getDb(): Database.Database {
if (!_db) {
throw new Error("Database not initialized. Call initDatabase() first.");
}
return _db;
export function getDb(): Db {
if (_pool) return _pool;
if (_sqlite) return _sqlite;
throw new Error("Database not initialized. Call initDatabase() first.");
}
/**
* Close the database connection gracefully.
* 同时关闭 pg 连接池与 sqlite 文件句柄(幂等)。
*/
export function closeDatabase(): void {
if (_db) {
_db.close();
_db = null;
export async function closeDatabase(): Promise<void> {
if (_pool) {
await _pool.end();
_pool = null;
}
if (_sqlite) {
_sqlite.close();
_sqlite = null;
}
}
/**
* Create an in-memory database for testing. Returns the db instance.
* Does NOT affect the global _db singleton.
* Create an in-memory SQLite database for testing. Returns the db instance.
* Does NOT affect the global singleton.
*/
export function createTestDatabase(): Database.Database {
export function createTestDatabase(): SqliteDb {
const db = new Database(":memory:");
db.pragma("journal_mode = WAL");
db.pragma("foreign_keys = ON");
db.exec(SCHEMA_SQL);
db.exec(SCHEMA_SQL_SQLITE);
return db;
}
// ---------------------------------------------------------------------------
// 统一查询辅助:路由层同一查询同时给出 sqlite(? 占位符)与 pg($n 占位符)
// 两个版本,仅方言不同;始终异步返回,调用方统一 await。
// ---------------------------------------------------------------------------
export interface DualSql {
sqlite: string;
pg: string;
}
/** 查询单行(可能为空)。pg 版把 COUNT(*) 等 bigint 列按调用方类型返回。 */
export async function dbGet<T>(
db: Db,
sql: DualSql,
params?: readonly unknown[],
): Promise<T | undefined> {
if (isPgDb(db)) {
const res = await db.query(sql.pg, params as unknown[]);
return res.rows[0] as T | undefined;
}
return (params === undefined ? db.prepare(sql.sqlite).get() : db.prepare(sql.sqlite).get(...params)) as
| T
| undefined;
}
/** 查询多行。 */
export async function dbAll<T>(
db: Db,
sql: DualSql,
params?: readonly unknown[],
): Promise<T[]> {
if (isPgDb(db)) {
const res = await db.query(sql.pg, params as unknown[]);
return res.rows as T[];
}
return (params === undefined
? db.prepare(sql.sqlite).all()
: db.prepare(sql.sqlite).all(...params)) as T[];
}
/** 执行写入。 */
export async function dbRun(db: Db, sql: DualSql, params?: readonly unknown[]): Promise<void> {
if (isPgDb(db)) {
await db.query(sql.pg, params as unknown[]);
return;
}
if (params === undefined) {
db.prepare(sql.sqlite).run();
} else {
db.prepare(sql.sqlite).run(...params);
}
}
+122 -13
View File
@@ -1,15 +1,13 @@
/**
* SQLite database schema for PERLER LAB.
* Database schema for PERLER LAB.
*
* DB choice: better-sqlite3
* - Synchronous API (no async overhead for SQLite): simpler code, faster local operations.
* - Well-typed TypeScript bindings via @types/better-sqlite3.
* - Mature, widely used, zero-dependency native bindings.
* - No external server process needed — database is a single file.
* Two DDL exports:
* SCHEMA_SQL_SQLITE — SQLite DDL (used by tests + legacy sqlite file mode)
* SCHEMA_SQL_PG — PostgreSQL DDL (used by production initDatabase)
*/
/** All DDL statements for creating tables. */
export const SCHEMA_SQL = `
/** All DDL statements for creating tables on SQLite. */
export const SCHEMA_SQL_SQLITE = `
-- 兑换码表
CREATE TABLE IF NOT EXISTS codes (
code TEXT PRIMARY KEY,
@@ -108,10 +106,6 @@ CREATE TABLE IF NOT EXISTS download_grants (
CREATE INDEX IF NOT EXISTS idx_download_grants_code ON download_grants(code);
-- chibi Showcase 作品表
-- title: 作品标题;image_data: base64 dataURL 或 http(s) URL;
-- tags: 标签数组 JSON 文本(如 '["宠物","猫"]');source: 作品来源(如 chibi/manual)
-- 规格列(T-131 详情页需要):width/height 图纸宽高(格);brand 材料品牌(如 MARD);
-- materials 用料清单 JSON 文本(如 '[{"code":"A7","count":980}]',name 可选),缺省为 NULL
CREATE TABLE IF NOT EXISTS showcase_works (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
@@ -127,4 +121,119 @@ CREATE TABLE IF NOT EXISTS showcase_works (
-- 索引:按创建时间倒序查询作品列表(Showcase 展示页主路径)
CREATE INDEX IF NOT EXISTS idx_showcase_works_created_at ON showcase_works(created_at DESC, id DESC);
`;
`;
/** All DDL statements for creating tables on PostgreSQL. */
export const SCHEMA_SQL_PG = `
-- 兑换码表
CREATE TABLE IF NOT EXISTS codes (
code TEXT PRIMARY KEY,
package_type TEXT NOT NULL,
total_uses INTEGER NOT NULL CHECK(total_uses > 0),
used_uses INTEGER NOT NULL DEFAULT 0 CHECK(used_uses >= 0),
status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'used', 'disabled')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
expired_at TEXT
);
-- 订单表
CREATE TABLE IF NOT EXISTS orders (
order_no TEXT PRIMARY KEY,
package_name TEXT NOT NULL,
amount_cents INTEGER NOT NULL CHECK(amount_cents > 0),
payment_method TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'paid', 'failed')),
access_code TEXT REFERENCES codes(code),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
paid_at TIMESTAMPTZ
);
-- 核销日志表
CREATE TABLE IF NOT EXISTS redemption_logs (
id SERIAL PRIMARY KEY,
code TEXT NOT NULL REFERENCES codes(code),
action TEXT NOT NULL CHECK(action IN ('redeem', 'consume')),
used_delta INTEGER NOT NULL DEFAULT 0 CHECK(used_delta >= 0),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- AI 生成记录表
CREATE TABLE IF NOT EXISTS chibi_generations (
id SERIAL PRIMARY KEY,
code TEXT NOT NULL REFERENCES codes(code),
category TEXT NOT NULL,
subtype TEXT NOT NULL,
grid_size INTEGER NOT NULL,
color_count INTEGER NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 索引:按 code 查询日志
CREATE INDEX IF NOT EXISTS idx_redemption_logs_code ON redemption_logs(code);
-- 索引:按状态查询兑换码
CREATE INDEX IF NOT EXISTS idx_codes_status ON codes(status);
-- 索引:按 order_no 查询订单
CREATE INDEX IF NOT EXISTS idx_orders_order_no ON orders(order_no);
-- 设备绑定表(云端同步权益)
CREATE TABLE IF NOT EXISTS device_bindings (
device_id TEXT NOT NULL,
code TEXT NOT NULL REFERENCES codes(code),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (device_id, code)
);
-- 索引:按 code 反查绑定设备
CREATE INDEX IF NOT EXISTS idx_device_bindings_code ON device_bindings(code);
-- 安全事件表
CREATE TABLE IF NOT EXISTS security_events (
id SERIAL PRIMARY KEY,
ip TEXT,
code TEXT NOT NULL,
action TEXT NOT NULL,
event_type TEXT NOT NULL CHECK(event_type IN ('redeem_ok', 'redeem_fail', 'code_disabled')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 索引:按兑换码查询安全事件
CREATE INDEX IF NOT EXISTS idx_security_events_code ON security_events(code, event_type, created_at);
-- 索引:按 IP 查询安全事件
CREATE INDEX IF NOT EXISTS idx_security_events_ip ON security_events(ip, event_type, created_at);
-- 下载授权表
CREATE TABLE IF NOT EXISTS download_grants (
"grant" TEXT PRIMARY KEY,
code TEXT NOT NULL REFERENCES codes(code),
order_no TEXT,
used INTEGER NOT NULL DEFAULT 0 CHECK(used IN (0, 1)),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 索引:按兑换码查询下载授权
CREATE INDEX IF NOT EXISTS idx_download_grants_code ON download_grants(code);
-- chibi Showcase 作品表
CREATE TABLE IF NOT EXISTS showcase_works (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
image_data TEXT NOT NULL,
tags TEXT NOT NULL DEFAULT '[]',
source TEXT NOT NULL DEFAULT 'manual',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
width INTEGER,
height INTEGER,
brand TEXT,
materials TEXT
);
-- 索引:按创建时间倒序查询作品列表
CREATE INDEX IF NOT EXISTS idx_showcase_works_created_at ON showcase_works(created_at DESC, id DESC);
`;
/** 保留旧名以便渐进切换(SQLite DDL,用于 createTestDatabase)。 */
export const SCHEMA_SQL = SCHEMA_SQL_SQLITE;