TREK 加密密钥轮换实战指南：AES-256-GCM 静态加密与零停机密钥迁移

TREK 加密密钥轮换实战指南AES-256-GCM 静态加密与零停机密钥迁移【免费下载链接】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本篇指南聚焦 TREK 自托管旅行规划器中的静态加密体系ENCRYPTION_KEY如何通过 SHA-256 派生密钥并用 AES-256-GCM 保护数据库中的敏感配置API Key、SMTP/OIDC 凭据、MFA 种子等、密钥解析顺序与丢失后果以及如何借助scripts/migrate-encryption.ts在不丢失任何数据的前提下完成密钥轮换。读完你能够独立完成密钥的定位、备份、轮换与升级迁移并理解其背后的源码实现原理。一、加密密钥保护什么TREK 静态加密的数据范围TREK 将敏感配置在数据库中以AES-256-GCM算法静态加密存储而非明文落盘。从官方文档与源码可以确认以下数据全部处于加密保护范围内按用户维度users 表 / settings 表Google Maps API Key每用户Mapbox access token每用户OpenWeather API Key每用户Immich API Key每用户Synology Photos 的密码、session ID、device ID每用户Webhook URL 与 ntfy 通知 tokensettings 表每用户全局维度app_settings 表OIDC client secretSMTP 密码Admin webhook URL 与 admin ntfy token其他敏感数据所有用户的 MFATOTP种子Synology 共享链接相册的 passphrasetrek_photos表以及trip_album_links表的 passphrase关键设计加密时并不直接使用原始ENCRYPTION_KEY而是通过 SHA-256 对ENCRYPTION_KEY加按密钥类型区分的域后缀后派生实际密钥因此原始ENCRYPTION_KEY值永远不会写入数据库。这一点在 server/src/services/apiKeyCrypto.ts 中可直接印证const ENCRYPTED_PREFIX enc:v1:; function get_key() { return crypto.createHash(sha256).update(${ENCRYPTION_KEY}:api_keys:v1).digest(); }而 MFA 种子使用独立的域后缀:mfa:v1见 server/src/services/mfaCrypto.ts。这种一主密钥、多派生密钥的设计让 API Key 类数据与 MFA 种子互不串用也便于未来单独升级某一类数据的加密方案。密文格式说明API Key 类密文以enc:v1:前缀标识由 apiKeyCrypto.ts 定义其内部结构为IV(12字节) GCM认证标签(16字节) 密文整体 Base64 编码。GCM 模式的认证标签可校验密文完整性解密失败密钥错误或数据被篡改会抛出异常并被上层捕获返回null见 apiKeyCrypto.ts。MFA 种子密文则不带前缀直接存储 Base64 的IV tag ciphertext。二、密钥解析顺序ENCRYPTION_KEY 从哪来TREK 服务启动时会按固定顺序解析加密密钥逻辑完整实现在 server/src/config.tsENCRYPTION_KEY环境变量——显式指定永远拥有最高优先级。一旦设置其值还会被写入./data/.encryption_key文件权限0o600这样即使后续移除环境变量容器重启后密钥仍然存活见 config.ts。./data/.encryption_key文件——任何至少启动过一次的安装都会存在该文件。./data/.jwt_secret文件——面向老版本安装的一次性回退方案。当既没有环境变量也没有专用密钥文件时会用 JWT 密钥作为加密密钥并立即持久化到./data/.encryption_key从而保证后续轮换 JWT 密钥不会破坏既有密文的可解密性见 config.ts。自动生成——全新安装且以上都不存在时生成随机的 32 字节 hex 密钥并写入./data/.encryption_key见 config.ts。启动日志中会打印Encryption key persisted to ...或相关 WARNING可用于确认当前生效的是哪种来源。三、密钥丢失的后果如果ENCRYPTION_KEY丢失所有加密配置将永久不可读TREK 无法解密 API Key、SMTP 密码、OIDC secret、MFA 种子、通知 token 等用户必须在密钥恢复或更换后手动重新录入这些值。需要特别注意的是MFA 种子同样被加密——密钥丢失意味着所有用户的 TOTP 双因素绑定可能失效需要重新完成 MFA 绑定。好消息是未加密数据行程、地点、用户、文件等完全不受影响丢失密钥不会造成主体业务数据损坏。四、密钥的备份与数据备份分离存放TREK 的备份 ZIP不包含加密密钥因此密钥必须与备份分开保存——例如放入密码管理器或专门的 secrets manager。从源码看备份打包逻辑在 server/src/services/backupService.ts 中有更细致的处理仅当ENCRYPTION_KEY不是通过环境变量提供、且./data/.encryption_key文件存在时该文件才会被一并打入备份 ZIP源码注释明确警告这会使备份文件与密钥本身同等敏感必须安全传输与存放。也就是说显式通过环境变量配置密钥的安装备份 ZIP 中不会含有密钥文件依赖文件持久化的安装备份中可能携带密钥请务必注意备份的存放安全。文档层面的建议始终一致——把密钥视为与备份同级别的机密单独管理。查看当前生效密钥的方式检查部署环境中的ENCRYPTION_KEY环境变量或直接读取./data/.encryption_key文件。五、轮换密钥migrate-encryption 脚本详解轮换密钥的核心工具是 server/scripts/migrate-encryption.ts它可以在应用不运行、零停机的情况下将所有已存储密文从旧密钥重新加密到新密钥无需手动重新录入任何配置。5.1 运行方式Docker 环境docker exec -it trek node --import tsx scripts/migrate-encryption.ts宿主机环境需在 server/ 目录下执行cd server node --import tsx scripts/migrate-encryption.ts若数据库位于非标准路径可通过DB_PATH环境变量指定脚本默认使用server/data/travel.db见 migrate-encryption.ts。5.2 脚本执行流程脚本的运行步骤与安全保障机制如下对照源码逐条印证交互式收集新旧密钥通过静默输入muted prompt读取键入/粘贴的内容不回显到终端也不会进入 shell 历史、进程参数或日志见 migrate-encryption.ts。输入为空会直接报错退出新旧密钥相同则提示nothing to do并正常退出L159-L172。修改前确认必须输入yes才会继续否则中止L175-L180。时间戳备份修改任何数据前先将数据库复制为travel.db.backup-毫秒时间戳例如travel.db.backup-1713484800000L183-L185。全表重加密迁移范围覆盖app_settingsoidc_client_secret、smtp_pass、admin_webhook_url、admin_ntfy_tokenL240-L248users每用户maps_api_key、openweather_api_key、immich_api_key、synology_password、synology_sid、synology_did以及使用 MFA 派生密钥的mfa_secretL250-L273settings每用户webhook_url、ntfy_token、mapbox_access_tokenL274-L286trip_album_linkspassphrasetrek_photospassphrase整个迁移过程包裹在 SQLite 事务中执行L239保证原子性。统计报告迁移结束时输出四类计数——migrated成功迁移、alreadyMigrated已是新密钥加密无需改动、skipped空值或非enc:v1:前缀的旧版明文跳过、errors新旧密钥均无法解密的失败项。L310-L323值得注意的健壮性设计脚本对每条密文都会先尝试用旧密钥解密失败后再尝试用新密钥解密——若新密钥能解开说明该值已经迁移过直接跳过。这意味着脚本天然具备幂等性重复执行也不会损坏数据。5.3 迁移完成后的收尾迁移脚本成功完成后还需要两步让新密钥真正生效将环境中的ENCRYPTION_KEY更新为新值重启 TREK密钥在启动时一次性解析进内存见 config.ts。失败处理如果存在任何无法迁移的密文脚本会以非零状态码退出且原始数据库备份travel.db.backup-时间戳会被完整保留供人工排查后重试。六、老版本升级JWT 密钥回退与自动迁移早于专用ENCRYPTION_KEY引入的旧安装曾经直接使用./data/.jwt_secret作为加密来源。升级时无需人工干预启动时的密钥解析链会自动读取 JWT 密钥、立即写入./data/.encryption_key随后 JWT 轮换即可安全进行而不破坏任何密文config.ts 中实现了这一逻辑并打印 WARNING 提示。源码注释同样强调了ENCRYPTION_KEY与JWT_SECRET分离的意义保持两者分离意味着你可以轮换会话 token 而不会使所有已加密数据失效反之亦然config.ts。这是 TREK 密钥管理架构的核心设计原则。七、备份与恢复场景下的密钥联动密钥轮换与备份/恢复功能存在紧密联动理解这一点可以避免恢复后无法解密的尴尬备份 ZIP 可能携带.encryption_key见 backupService.ts恢复备份时若归档内含有.encryption_keyTREK 会将其恢复到data/目录使恢复后的数据库中的加密数据可被解密backupService.ts但文件恢复后内存中的密钥是启动时读取的因此必须重启服务才能生效源码注释明确指出the in-memory key was read at startup, so a restart is required for it to take effect且显式设置的ENCRYPTION_KEY环境变量仍会覆盖文件值。这与文档 Backups 中的提醒一致插件数据与加密密钥均在重启后才生效。因此无论是轮换密钥还是恢复含密钥的备份都要安排一次服务重启。八、最佳实践清单综合文档与源码实现给出可落地的密钥管理建议显式设置ENCRYPTION_KEY官方环境变量文档建议显式配置以便独立于数据卷备份该密钥环境变量在轮换场景下语义最清晰。密钥与备份分开存放将密钥存入密码管理器或 secrets manager与备份 ZIP 物理隔离。轮换前先做手工备份TREK 官方在 Backups 中明确要求更新前先创建备份轮换前同样建议手动备份一次配合脚本自动生成的时间戳备份形成双保险。轮换后验证报告确认Errors: 0再更新环境变量并重启若有错误保留备份并排查对应条目。旧版升级放心重启首次升级到含专用密钥的版本时JWT 回退逻辑会自动完成密钥持久化无需手工干预。注意 MFA 影响密钥丢失或轮换失败会波及所有用户的 TOTP 绑定生产环境务必提前通知用户并准备重新绑定流程。参考链接Encryption-Key-Rotation 官方文档Environment-Variables 环境变量文档Security-Hardening 安全加固指南User-Settings 用户设置文档Backups 备份指南密钥解析与持久化实现server/src/config.tsAPI Key 加解密实现server/src/services/apiKeyCrypto.tsMFA 种子加解密实现server/src/services/mfaCrypto.ts密钥迁移脚本server/scripts/migrate-encryption.ts备份打包/恢复中的密钥处理server/src/services/backupService.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），仅供参考