TREK 用户设置完全指南从外观主题到地图引擎的个性化配置【免费下载链接】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 的设置页Settings Page是整款自托管旅行规划器中唯一一处集中管理个人偏好的入口覆盖界面外观、地图引擎、通知渠道、离线行为与账户安全等全部维度。本文以官方用户文档 wiki/User-Settings.md 为骨架结合客户端源码逐一拆解每个标签页的配置项、默认值与底层实现帮助你快速上手从切换 Leaflet / Mapbox GL / MapLibre GL 三种地图引擎到配置 MFA、OAuth 客户端与离线缓存读完即可完整掌握 TREK 的个人化配置能力。如何进入设置页打开顶部导航栏中的用户菜单选择Settings即可进入页面默认停留在General常规标签页。若你的账户需要完成 MFA 设置TREK 会通过 URL 参数?mfarequired自动跳转到Account标签页。这一行为可以在源码中直接印证在 client/src/pages/settings/useSettings.ts 中useSettings钩子监听查询参数mfa当值为required时自动把激活标签切换为account。除此之外它还支持?tabplugins这类深链参数用于让系统内其他位置例如插件通知渠道提示直接指向设置页中的对应标签。设置页本身是纯粹的“装配容器”组件位于 client/src/pages/SettingsPage.tsx它从useSettings()读取插件/Addon 状态与应用版本据此动态决定哪些标签页可见并通过PageSidebar渲染左侧标签导航栏底部还会显示v{版本号} · self-hosted的版本标识。标签页总览标签页用途显示条件General货币、语言、温度单位、距离单位、时间格式、预订路线标签、地图 POI 胶囊、模糊预订码始终显示Appearance颜色模式、配色方案/强调色、可读性透明、减少动画、密度、字号、仪表盘组件始终显示Map地图提供方Leaflet、Mapbox GL 或 MapLibre GL、瓦片预设、地图样式与 Mapbox Token、3D 建筑、高质量模式始终显示Notifications邮件、Webhook、ntfy、应用内通知偏好始终显示Integrations照片提供方Immich、Synology 等与 MCP OAuth 客户端 / API Token仅当启用 Memories 或 MCP Addon 时显示Plugins已安装插件的每用户设置仅当至少安装一个插件时显示Offline缓存行程、待同步变更、重新同步与清除缓存始终显示Account用户名、邮箱、密码、MFATOTP 备份码、头像、删除账户始终显示About应用版本、Ko-fi / Buy Me a Coffee / Discord / GitHub问题反馈与功能请求/ Wiki 链接仅当获取到版本元数据时显示其中“Integrations”与“Plugins”标签的显隐完全由运行时状态驱动hasIntegrations取决于 Memories、MCP、Airtrail、LLM Parsing 等 Addon 是否启用hasPlugins取决于 pluginStore 中已加载插件的数量About标签则只在成功获取appConfig.version后渲染见 SettingsPage.tsx。General 标签语言、区域与旅行偏好General 标签下所有偏好修改后都会立即保存即时写入服务端无需点击保存按钮。界面按“语言与区域”“旅行与地图”两个分组组织对应组件为 client/src/components/Settings/DisplaySettingsTab.tsx。语言与区域Currency货币—— 你的显示货币。选择Trip currency默认空值时每个行程会按自身币种展示而不是被强制统一换算成某一种显示货币在源码 settingsStore.ts 中default_currency的默认值为空字符串注释明确说明“空值 无个人偏好成本页面回退到行程自身币种”。更多币种规则参见 wiki/Currencies.md。Language语言—— 桌面端以按钮网格展示移动端自动降级为下拉选择器源码中通过hidden sm:flex/sm:hidden两套 DOM 实现响应式切换。语言偏好会写入localStorage的app_language键并在服务器端持久化见 settingsStore.ts。TREK 支持语言列表见 wiki/Languages.md。Temperature unit温度单位—— 摄氏度°C Celsius或华氏度°F Fahrenheit默认celsius。Distance unit距离单位—— 公制km Metric或英制mi Imperial默认metric。Time format时间格式—— 24 小时制14:30或 12 小时制2:30 PM默认24h。以上默认值均可在 client/src/store/settingsStore.ts 的DEFAULT_SETTINGS对象中查到该对象同时被 UI 组件作为回退值引用从而保证“store 默认值”与“界面回退值”不会漂移。旅行与地图Booking route labels预订路线标签—— 在预订路线端点标记上显示或隐藏车站/机场名称对应设置项map_booking_labels。Always show booking routes—— 始终显示预订路线map_always_show_routes。Explore places on the map地图 POI 胶囊—— 在行程地图上显示一个 POI 分类胶囊用于从 OpenStreetMap 查找附近地点对应map_poi_pill_enabled默认开启源码中判断条件为settings.map_poi_pill_enabled ! false。Blur booking codes模糊预订码—— 模糊化确认码与参考编号在共享屏幕时非常实用对应blur_booking_codes。Optimize route from accommodation—— 是否从住宿地开始优化路线对应optimize_from_accommodation默认开启。更详细的字段说明参见 wiki/Display-Settings.md。Appearance 标签主题、配色与可读性Appearance 标签负责视觉层面的个性化组件位于 client/src/components/Settings/AppearanceSettingsTab.tsx。与 General 的“即改即存”不同这里的修改会先即时应用到 DOM 进行实时预览再经过约 350ms 的防抖后异步持久化到服务端见update()函数中的persistTimer逻辑。颜色模式与配色方案Color mode颜色模式—— Light浅色、Dark深色或 Auto跟随操作系统/浏览器偏好。源码通过window.matchMedia((prefers-color-scheme: dark))判断系统偏好dark_mode字段同时兼容布尔值与light | dark | auto字符串。Color scheme配色方案—— 内置预设强调色或选择Custom自定义浅色/深色两套强调色。预设方案定义在 client/src/theme/schemes.ts 的APPEARANCE_SCHEMES中UI 上以色块网格展示。选择 Custom 后会出现浅色/深色两个取色器以及一组CUSTOM_ACCENT_PRESETS预设色块。值得一提的实现细节自定义强调色面板会实时计算该强调色与白色背景的WCAG 对比度并给出“Good contrast / Low contrast含对比度比值”提示若低于 4.5:1 则显示警告色——这是从 AppearanceSettingsTab.tsx 中内置的relLuminance/contrastRatio工具函数完成的可帮助用户避免选择难以阅读的强调色。可读性实验性Transparency透明度—— 玻璃拟态半透明表面关闭后背景更实、对比度更高。Reduce motion减少动画—— 最小化动画与过渡效果。Density密度—— Comfortable舒适或 Compact紧凑紧凑模式收紧间距与内边距让屏幕容纳更多内容。Text size字号—— 提供全局缩放滑块fontScale与按字号级别大标题 Large、副标题 Medium、正文 Normal、说明文字 Small分别调节的滑块每个滑块都带实时字号百分比与示例文本。缩放范围由 shared 包中的APPEARANCE_SCALE_MIN/APPEARANCE_SCALE_MAX约束。仪表盘组件可分别针对桌面端与移动端独立配置仪表盘上显示的组件桌面端Hero 下方的 Atlas/国家数、行程总数、旅行天数、飞行距离右侧边栏带主开关关闭后仪表盘居中内的货币、收藏集、时区、即将到来的预订。移动端Hero 下方的行程总数、旅行天数页面底部的货币、收藏集、时区、即将到来的预订。所有配置结构由AppearanceConfig[dashboard]定义统一保存在appearance设置字段中。详细说明见 wiki/Appearance-Settings.md。Map 标签三种地图引擎的选择Map 标签是设置页中唯一需要显式点击Save按钮才生效的页面其余标签均即时保存。对应组件为 client/src/components/Settings/MapSettingsTab.tsx页内还内嵌了一个约 200px 高的地图实时预览固定以巴黎 [48.8566, 2.3522] 为中心、zoom 16方便在保存前直接看到样式效果。Provider地图提供方Leaflet—— 经典 2D 栅格瓦片。内置预设包括 OpenStreetMap、OpenStreetMap DE、CartoDB Light/Dark、Stadia Smooth实际 URL 模板见 MapSettingsTab.tsx也可以直接输入自定义瓦片 URL 模板例如https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png。不需要任何 Token。Mapbox GL实验性—— 矢量瓦片支持 3D 建筑与地形。需要公开的 Mapbox access tokenpk.*开头。内置样式预设见 client/src/components/Map/glProviders.tsMapbox Standard、Standard Satellite、Streets、Outdoors、Light、Dark、Satellite、Satellite Streets、Navigation Day、Navigation Night也支持自定义mapbox://styles/USER/ID样式 URL。额外的选项3D Buildings Terrain3D 建筑与地形—— 倾斜视角与真实的 3D 建筑挤出效果适用于包括卫星图在内的所有样式源码注释说明纯卫星图会回退到 mapbox-streets-v8 瓦片集作为建筑数据源因此supports3d恒为true。High Quality Mode高质量模式实验性—— 抗锯齿 球面投影globe边缘更锐利低端设备上可能影响性能。MapLibre GL—— 使用OpenFreeMap的矢量瓦片选择它的核心理由是无需任何 access token。内置 OpenFreeMap Liberty、Bright、Positron 三种样式见 glProviders.ts或任意https://tiles.openfreemap.org/…样式 URL。3D 与高质量开关是 Mapbox 专属能力在 MapLibre 下不会显示。一个容易被忽略但很实用的设计每个 GL 提供方各自保存独立的样式槽位Mapbox 存mapbox_styleMapLibre 存maplibre_style因此来回切换 Mapbox GL 与 MapLibre GL 不会互相覆盖对方的样式选择见 MapSettingsTab.tsx 与 glProviders.ts。注意Atlas 页面无论设置中的 provider 是什么始终使用 Leaflet 渲染。Opening view打开视角—— 设置页没有“默认地图中心点/缩放级别”的概念。每一张地图都会根据其展示的地点自行取景framing相关机制见 wiki/Map-Settings.md。另外GL 底图的地名语言会自动跟随 TREK 的 UI 语言例如 TREK 的br巴西葡萄牙语会映射为底图所需的pt、zh映射为zh-Hans、zhTw映射为zh-Hant见 glProviders.ts。Notifications 标签Notifications 标签组件 client/src/components/Settings/NotificationsTab.tsx用于配置邮件、Webhook、ntfy 与应用内通知的偏好。需要注意的是这里的通知“偏好”与 TREK 管理员在服务器端配置的全局通知通道见 server/src/services/notificationService.ts是两层概念本标签控制的是当前用户希望以哪些方式收到哪些事件。详细用法参见 wiki/Notifications.md。Integrations 标签照片服务与 MCP 接入Integrations 标签仅在Memories或MCPAddon 启用时可见hasIntegrations还会额外包含 Airtrail 与 LLM Parsing见 useSettings.ts。组件为 client/src/components/Settings/IntegrationsTab.tsx。Photo Providers照片提供方—— 配置 Immich、Synology Photos 等照片集成只要该标签可见就始终展示对应 PhotoProvidersSection.tsx。MCP 区域仅当启用 MCP Addon 时出现显示 MCP 服务器端点 URL。OAuth Clients 子标签—— 创建和管理 OAuth 2.1 客户端含重定向 URI 与授权范围。内置了针对Claude.ai、Claude Desktop、Cursor、VS Code、Windsurf、Zed的快速填充预设见 IntegrationsTab.tsx预设已按客户端类型预置重定向地址与合理的 scope 集合如 VS Code 预设仅授予:read结尾的只读权限其余默认排除:delete权限。这里还能查看并撤销活跃的 OAuth 会话。API Tokens 子标签已弃用 —— 创建和管理用于直接访问 MCP 的个人 Bearer Token。关于 MCP 权限模型与工具的进一步说明可参考 wiki/MCP-Overview.md 与 wiki/MCP-Addon-Tools.md。Plugins 标签Plugins 标签仅在至少安装了一个插件时出现组件为 client/src/components/Settings/PluginSettingsTab.tsx。它列出已安装插件并展示每个插件的每用户设置项由插件 manifest 声明另外包含一个 PluginActivityPanel.tsx 用于查看插件活动。TREK 插件体系与开发方式参见 wiki/Plugin-Development.md 和 plugin-sdk 目录。Offline 标签离线模式与缓存管理Offline 标签组件 client/src/components/Settings/OfflineTab.tsx负责离线能力的全部控制核心能力包括Offline mode强制离线—— 一个 force-offline 开关先完整下载所需数据然后把应用路由切换到缓存 变更队列mutation queue模式底层由 sync/networkMode.ts 与 sync/mutationQueue.ts 支撑。Prepare for offline为离线做准备—— 一次带进度跟踪的完整下载tripSyncManager.prepare进度通过PrepareProgress反馈。What to store—— 地图瓦片缓存开关 按行程逐项启用的离线缓存。Sync conflicts同步冲突—— keep-mine / keep-theirs 冲突解决器以及默认冲突策略见 sync/offlinePrefs.ts 的ConflictStrategy。Cache stats clear—— 查看缓存统计已缓存行程、待同步变更数、失败数等以及清除全部缓存或单行程数据。离线模式的整体机制参见 wiki/Offline-Mode-and-PWA.md。Account 标签账户、安全与 MFAAccount 标签组件 client/src/components/Settings/AccountTab.tsx集中管理账户与安全包括编辑用户名与邮箱地址。修改密码—— 当服务器以OIDC-only 模式运行时该区域会隐藏组件通过authApi.getAppConfig()读取oidc_only_mode判断见 AccountTab.tsx参见 wiki/OIDC-SSO.md。双因素认证TOTP—— 启用/禁用 MFA。启用流程包含二维码QR与密钥展示启用后备份码仅显示一次可复制、下载下载文件名为trek-mfa-backup-codes.txt或打印。备份码会临时存入sessionStorage键trek_mfa_backup_codes_pending刷新后即不可再取。完整流程参见 wiki/Two-Factor-Authentication.md。上传或移除个人头像。删除账户—— 不可逆操作如果你是该实例唯一的 admin删除会被阻止。若账户是通过 SSO 关联的角色旁边会出现SSO徽标其下方显示 OIDC 签发方域名。若账户启用了 Passkeys通行密钥本标签还会通过 PasskeysSection.tsx 提供密钥管理入口相关机制见 wiki/Passkeys.md。About 标签About 标签在成功获取到应用版本后显示未获取到时整页不渲染该标签展示当前版本号并提供指向 Ko-fi / Buy Me a Coffee / Discord / GitHub问题反馈与功能请求/ Wiki 的链接。底层实现设置如何被保存理解设置页背后的一套机制有助于排查“改了不生效”类问题前端 Storeclient/src/store/settingsStore.ts 基于 Zustand 实现loadSettings()从settingsApi.get()拉取服务端设置并与本地默认值合并updateSetting()做乐观更新先改本地状态再请求服务端失败时抛出错误并由 UI 弹出 toast。默认值兜底DEFAULT_SETTINGSmap_tile_url: 、dark_mode: false、default_currency: 、temperature_unit: celsius、distance_unit: metric、time_format: 24h、map_provider: leaflet、mapbox_3d_enabled: true、mapbox_quality_mode: false等既作用于全新用户的初始界面也是 UI 回退值的来源。服务端合并逻辑从源码结构看服务器端 settingsService.ts 负责按管理员默认值Admin User Defaults合并用户设置未设置项会继承实例级默认因此设置页展示的是“管理员默认 个人覆盖”的最终效果。语言的特殊性语言偏好额外写localStorage并提供setLanguageLocal/setLanguageTransient两个方法区分“用户显式选择持久化”与“会话内自动检测不持久化”。相关文档wiki/Display-Settings.md —— 显示与区域设置详情wiki/Appearance-Settings.md —— 外观设置详情wiki/Map-Settings.md —— 地图设置详情wiki/Notifications.md —— 通知偏好wiki/Offline-Mode-and-PWA.md —— 离线模式wiki/Two-Factor-Authentication.md —— 双因素认证wiki/Languages.md —— 语言支持wiki/Currencies.md —— 币种与汇率wiki/OIDC-SSO.md —— OIDC 单点登录【免费下载链接】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），仅供参考