TREK：一款支持实时协作与交互地图的自托管旅行规划工具

这是什么

TREK 是一个自托管（Self-hosted）、支持实时协作的旅行规划工具。它由 mauriceboe 开发，主要使用 TypeScript 编写，旨在让用户完全掌控自己的旅行数据。

该项目不仅仅是一个简单的行程记录本，而是一个集成了地图可视化、预算追踪、打包清单、旅行日志以及内置 AI 助手的综合性平台。TREK 采用 Progressive Web App (PWA) 架构，无需安装原生应用，即可在浏览器中提供类似原生应用的沉浸式体验。其核心设计理念是隐私优先与数据自主，所有数据均存储在用户自己的服务器或本地环境中。

解决的问题

传统的旅行规划往往面临以下痛点，TREK 试图通过技术手段予以解决：

1. 数据孤岛与隐私泄露：主流在线旅行工具（如 TripIt、Google Trips 等）通常将用户数据存储在云端服务商的服务器上，存在隐私泄露风险，且一旦服务停止，数据可能无法迁移。TREK 通过自托管模式，确保数据完全掌握在用户手中。
2. 协作困难：多人共同规划旅行时，通常依赖分散的聊天记录、Excel 表格或纸质笔记，信息同步滞后且混乱。TREK 基于 WebSocket 实现实时同步，允许多个用户同时编辑行程、更新预算或查看地图，体验如同在线文档。
3. 功能碎片化：用户通常需要在多个应用间切换——用地图 App 看路线，用笔记 App 写攻略，用计算器算预算。TREK 将地图、预算、清单、日志整合在一个统一的界面中，减少上下文切换的成本。
4. 离线与跨平台限制：许多原生 App 受限于操作系统，而纯 Web 应用又缺乏离线能力和原生交互体验。TREK 作为 PWA，既能在移动端全屏运行，又能通过 Service Worker 提供一定的离线访问能力。

核心功能

• 实时协作与同步： 利用 WebSocket 技术，支持多用户实时同步行程变更。后端基于 NestJS 11 构建，状态管理使用 Zustand，确保高并发下的响应速度和数据一致性。
• 智能地图集成： 基于 Leaflet 和 Mapbox GL 构建交互式地图。地图的国家及次国家级（省/县）边界数据源自 geoBoundaries，符合 CC BY 4.0 协议。用户可以在地图上直观地规划路线、标记兴趣点。
• 全面的行程管理：
  • 预算追踪：实时计算旅行总预算及各项支出。
  • 打包清单：支持创建、勾选和管理行李物品。
  • 旅行日志：记录旅行中的点滴，支持图文混排。
• AI 辅助规划： 内置 AI 功能，可协助用户生成行程建议、优化路线或提供目的地信息（具体模型依赖配置，但文档强调其内置 AI 能力）。
• 强大的认证与安全体系： 支持 JWT、OAuth 2.1、OIDC（OpenID Connect）、Passkeys (WebAuthn) 以及 TOTP 多因素认证（MFA）。这意味着用户可以无缝集成企业 SSO 或家庭身份提供商。
• PWA 原生体验： 支持 iOS 和 Android 的“添加到主屏幕”功能，启动后全屏运行，拥有独立图标，体验接近原生应用。
• 自动化备份与恢复： 提供手动和自动备份功能，支持配置保留策略。数据存储在 SQLite 数据库中，便于本地管理和迁移。

亮点 / 与同类相比

• 极致的安全与隐私配置： TREK 在 Docker 部署上提供了业界罕见的默认安全配置示例。包括 read_only: true、no-new-privileges、cap_drop: ALL 等最小权限原则设置。此外，它支持通过环境变量轻松配置 HTTPS 重定向、HSTS 和 CSP，适合对安全性有极高要求的用户。
• 灵活的部署架构： 不仅支持标准的 Docker Compose，还提供了 Helm Chart，方便在 Kubernetes 集群中部署。对于不想使用容器的用户，也提供了简单的 docker run 命令。
• 数据所有权与迁移友好： 所有数据（数据库、上传文件、日志）均通过挂载卷（Volumes）持久化。升级或更换容器时，只需挂载相同的卷路径，数据即可无缝保留。官方还提供了加密密钥轮换脚本，确保在密钥变更时数据可平滑迁移。
• 轻量级且无外部依赖（部分）： 天气数据使用 Open-Meteo，无需 API Key；地图基础图层开源。相比许多需要绑定特定云服务或付费 API 的旅行应用，TREK 降低了长期运营成本和隐私顾虑。
• 开源协议明确： 采用 AGPL v3 许可证。允许个人和企业内部免费使用，但若修改后作为网络服务提供给第三方，则必须开源修改后的代码。这保证了社区的贡献能回馈给项目，同时也明确了商业使用的边界。

适合谁用 / 上手

适合人群：

• 技术爱好者与开发者：熟悉 Docker 和 Linux 基础操作，希望完全掌控数据隐私的用户。
• 注重隐私的个人或家庭：不希望旅行数据被大型科技公司追踪或用于广告画像的用户。
• 小型团队或企业：需要内部协作规划商务旅行或团建活动，且希望集成现有 SSO 系统的团队。
• PWA 爱好者：喜欢尝试新技术，希望在不安装 App Store 应用的情况下获得原生体验的用户。

上手指南：

1. 环境准备： 确保服务器已安装 Docker 和 Docker Compose。
2. 快速启动： 生成加密密钥并运行容器：

   ENCRYPTION_KEY=$(openssl rand -hex 32)
   docker run -d -p 3000:3000 \
   -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
   -v ./data:/app/data -v ./uploads:/app/uploads mauriceboe/trek
   

3. 首次访问： 打开浏览器访问 http://localhost:3000。首次启动时，系统会生成一个管理员账户。如果未设置 ADMIN_EMAIL 和 ADMIN_PASSWORD，凭据将打印在容器日志中（使用 docker logs trek 查看）。
4. 生产环境部署建议：
   • 反向代理：强烈建议在 TREK 前配置 Nginx 或 Caddy 作为 TLS 终止的反向代理，以启用 HTTPS。
   • WebSocket 支持：确保代理服务器正确配置 /ws 路径的 WebSocket 升级头（Upgrade/Connection）。
   • 持久化存储：务必挂载 ./data 和 ./uploads 目录，切勿挂载 /app，否则会导致应用代码被覆盖而无法启动。
5. 进阶配置： 可通过环境变量配置 OIDC 认证、时区、日志级别等。对于 Kubernetes 用户，可参考 charts/README.md 使用 Helm 进行部署。