TREK数据库设计全解析：SQLite Schema、171步迁移机制与种子数据完整指南

TREK数据库设计全解析SQLite Schema、171步迁移机制与种子数据完整指南【免费下载链接】TREKA self-hosted travel/trip planner with real-time collaboration, interactive maps, PWA support, SSO, budgets, packing lists, and more.项目地址: https://gitcode.com/GitHub_Trending/nomad22/TREKTREK是一款自托管旅行规划器支持实时协作、互动地图、PWA、SSO 登录、预算管理和行李清单等。它的后端只依赖一个 SQLite 文件就把整套系统撑了起来本文将带你完整看懂它的数据库设计SQLite Schema 如何组织 50 张表、171 步迁移机制如何保证老数据平滑升级以及种子数据如何在首次启动时自动就绪。一个文件搞定SQLite WAL 的极简架构TREK 使用 better-sqlite3 中启动时依次执行三件事建表调用 schema.ts 中的createTables用CREATE TABLE IF NOT EXISTS幂等地创建全部表结构迁移执行 migrations.ts 中的版本化升级播种运行 seeds.ts 写入种子数据数据库连接做了三项关键配置database.tsPRAGMA 配置作用journal_mode WAL写前日志读写并发不阻塞适合多人协作场景busy_timeout 5000遇到锁定时最多等待 5 秒避免并发冲突直接报错foreign_keys ON开启外键约束保证数据完整性在 Docker 部署时只需把./data挂载为卷见 docker-compose.yml数据库文件就被持久化在宿主机上备份时直接复制这个文件即可。测试与生产环境的路径策略也很聪明NODE_ENVtest时每个测试进程使用独立的内存数据库:memory:避免并行测试互相干扰E2E 测试可通过TREK_DB_FILE环境变量指向一次性数据库database.ts。核心表结构从 users 到 trips、places整个 Schema 定义在 schema.ts 中按业务域可以分成 6 大块。1️⃣ 用户与安全域users表是系统的地基除了username、email、password_hash外还内嵌了大量集成凭证字段地图 API Key、天气 Key、Immich 相册、群晖 NAS 等。围绕它的安全相关表包括password_reset_tokens密码重置令牌存哈希而非明文webauthn_credentialsPasskey 公钥凭据mfa_enabled/mfa_backup_codes两步验证与备用码直接在 users 表上2️⃣ 行程核心域这是整个应用的中枢关系链是trips行程→ days天数→ day_assignments日程安排→ places地点trips行程主表含起止日期、货币、封面图、提醒天数days按UNIQUE(trip_id, day_number)保证一天不重复places地点表携带经纬度、Google Places ID、交通方式、预订状态等 20 字段day_assignments把地点挂到某天order_index控制当天顺序trip_membersUNIQUE(trip_id, user_id)实现多人协作删除语义经过精心设计删行程会ON DELETE CASCADE级联清理全部子数据而地点上的分类外键用ON DELETE SET NULL删分类不会误伤地点。3️⃣ 费用与文档域budget_items记录每笔花费分类、金额、分摊人数、天数配合budget_item_members实现谁付款、谁已付平的 AA 制结算photos和trip_files则分别管理行程照片和文档文件还可以关联到具体的预订reservations或日程项。4️⃣ 协作域Collab 插件四张collab_*表支撑实时协作便签、投票含collab_poll_votes投票记录、聊天消息及表情回应。每条表都通过trip_id外键隔离到具体行程并建有按行程查询的索引5️⃣ 插件化扩展域addons表用id enabled控制功能开关packing、budget、collab、vacay、atlas 等都注册在此这让管理员可以按实例禁用不需要的功能。Vacay假期日历、Collections地点收藏夹等功能则各有一组独立表遵循插件自带表的惯例。6️⃣ 系统域audit_log记录审计日志、notifications存储可交互通知支持简单消息、是/否询问、跳转三种类型、app_settings是键值对全局配置表。此外所有高频查询字段都建了索引schema.ts比如notifications(recipient_id, is_read, created_at DESC)直接服务于未读通知列表页。迁移机制171 步版本化升级事务保护不丢数据migrations.ts 是 TREK 数据库演进的核心目前累积了171 个迁移步骤。它的工作方式非常经典且稳健① 版本追踪schema_version表记录当前已执行的版本号。首次启动时系统会通过探测users表是否已有unsplash_api_key列来猜老库的初始版本实现老版本数据库的自动接入。② 顺序执行 事务保护从当前版本开始逐步执行到最新版本。每个迁移都在db.transaction()中运行任何一步失败都会自动回滚并以退出码 1 终止进程绝不让数据库停在半迁移状态migrations.ts[DB] Running migration 42/171 [DB] Migrations complete — schema version 171③ 防御式写法大量迁移用try/catch吞掉 duplicate column name 错误保证在不同基线版本上重跑都安全建表则统一用IF NOT EXISTS。④ 不只是加列还做数据搬运。例如第 22 步把预订信息从places表迁移到day_assignments表地点的预订和日程的预订合并第 83 步把trip_photos整表重建为带provider字段的通用结构——用建新表 → 拷数据 → 删旧表 → 改名的四板斧完成平滑重构。⑤ 安全加固也走迁移把app_settings里明文的 OIDC 客户端密钥、SMTP 密码以及users表里明文的 Immich API Key 统一加密为enc:v1:前缀格式migrations.ts。对新手来说这套机制意味着你从任何旧版本升级 TREK数据都会自动、安全地迁移到最新结构无需手动动 SQL。种子数据首次启动一切自动就绪建表和迁移完成后seeds.ts 的runSeeds会注入三类种子数据。管理员账户first-run admin如果users表为空seeds.ts配置了ADMIN_EMAILADMIN_PASSWORD→ 用你的凭据创建未配置 → 自动生成随机密码邮箱为admintrek.local并在控制台用醒目边框打印出来账户带must_change_password1标记首次登录后强制改密配置了OIDC_ONLYtrue→ 跳过创建第一个 SSO 登录的用户自动成为管理员默认地点分类10 个开箱即用的分类Hotel 、Restaurant ️、Attraction ️、Shopping ️、Transport 、Activity 、Bar/Cafe ☕、Beach ️、Nature 、Other 每个都带颜色和图标建行程时点选地点即可直接使用。插件与照片源seedAddons把 13 个插件写入addons表packing、budget、documents、vacay、atlas、collab 等默认开启MCP、journey、AirTrail 默认关闭并注册 Immich 与 Synology Photos 两个照片源及其配置字段定义——插件表单因此完全数据驱动无需改代码。Demo 模式一键体验设置DEMO_MODEtrue后demo-seed.ts 会接管创建admin和demo两个演示用户密码分别为admin12345/demo12345关闭注册并写入东京与京都等完整示例行程——包含天数、地点、打包清单、预算项、预订和协作便签让你不配置任何数据就能完整体验全部功能。备份与运维一个文件的底气正因为所有状态都收敛在travel.db备份异常简单WAL checkpoint 后复制该文件即可TREK 内置的备份功能正是这样做的运维场景操作要点备份复制data/travel.dbWAL 模式下建议先触发 checkpoint升级版本直接换新镜像迁移自动执行无需手工 SQL重置管理员运行 reset-admin.js 即可换机迁移挂载新卷 → 拷入 db 文件 → 启动总结TREK 的数据库设计堪称自托管项目的范本SQLite 单文件 WAL 并发模型让部署门槛降到最低幂等建表 171 步事务化迁移让版本升级对数据零风险种子数据则保证首次启动即有管理员、分类和插件生态可用。对于想学习如何给 Node.js 应用设计可演进的数据库的开发者server/src/db/ 目录下的四个文件schema.ts、migrations.ts、seeds.ts、database.ts值得逐行精读。【免费下载链接】TREKA self-hosted travel/trip planner with real-time collaboration, interactive maps, PWA support, SSO, budgets, packing lists, and more.项目地址: https://gitcode.com/GitHub_Trending/nomad22/TREK创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考