TREK Journey Journal 旅行日记功能完全指南照片优先的跨行程叙事与公开分享【免费下载链接】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/TREKJourney Journal 是 TREK 中一个照片优先的旅行日记travel journal模块每本日记journey可关联一个或多个行程trip并按天沉淀文字、照片、心情与天气最终还能通过只读分享链接对外展示。本文以 Journey-Journal.md 为主体结合客户端组件与 Nest 服务端实现完整讲解 Journey 的启用、创建、条目编辑、移动端时间线、地图视图、插件扩展与公开分享机制读完即可上手使用并理解其底层数据与权限模型。什么是 JourneyJourney 让你可以沿着行程计划trip plan同步书写一段叙事性的旅行记录。与行程规划中的日程day plan不同Journey 的条目entry天然与具体日期绑定可以包含叙述性正文Story支持 Markdown 排版照片Photos心情评级Mood天气状况Weather正反面评价卡片Pros / Cons自由标签Tags、地图定位Location与时刻Time。完成后的日记可生成只读公开链接对外分享。在数据模型上Journey 是横跨多个行程的独立实体一条 Journey 通过journey_trips关联多个 Trip并通过journey_entries、journey_photos、journey_contributors分别承载条目、照片与协作者见 server/src/services/journeyService.ts 中的查询与写入逻辑。启用 JourneyAdmin 前提Journey 是一个可开关的 Addon默认不启用。需要在管理后台的 Addons 页面中开启参见 Admin-Addons.md。服务端会为此做两层防护添加守卫JourneyAddonGuardserver/src/nest/journey/journey-addon.guard.ts未启用时所有/api/journeys请求直接返回 404JourneyService.journeyAddonEnabled()调用isAddonEnabled(ADDON_IDS.JOURNEY)检查server/src/nest/journey/journey.service.ts。启用后主导航会出现Journey入口。Journey 列表页以卡片形式展示你的全部日记每张卡片包含封面图cover image以及条目数、照片数、地点数等统计——这些统计在服务端由listJourneys的子查询实时聚合见 server/src/services/journeyService.ts。创建一本 Journey在 Journey 列表页点击Create journey只需填写字段说明Title必填日记标题服务端会 trim 并拒绝空标题400Subtitle可选副标题Linked trips选择一个或多个已有行程关键机制是行程关联勾选行程后TREK 会把该行程中已排入日程的地点place导入为条目的位置锚点并自动生成对应日期的骨架条目skeleton entry。从源码看创建时逐个调用addTripToJourney内部做canAccessTrip访问校验防止把无权访问的行程拉进自己的日记造成跨租户泄露随后syncTripPlaces为每个地点生成骨架条目并继承首个真实关联行程的封面图server/src/services/journeyService.ts。骨架条目是日记与行程之间的活链接行程地点的新增、调整日期/时间、删除都会通过onPlaceCreated/onPlaceUpdated/onPlaceDeleted与reconcileTripSkeletons同步到日记幂等无变化时不产生写操作骨架条目没有故事时被删除一旦你为它补充了内容它会被提升为正式条目promoteSkeletonIfNeeded、updateEntry中写入 story 即触发 type 提升删除已填写内容的条目时服务端会把它还原为骨架而不是彻底删除deleteEntry。行程也可以在之后随时从日记设置journal settings中追加关联对应的 API 为POST /api/journeys/:id/trips与DELETE /api/journeys/:id/trips/:tripIdserver/src/nest/journey/journey.controller.ts。条目编辑器详解每条目对应旅程中的一天编辑器client/src/components/Journey/JourneyDetailPageEntryEditor.tsx提供以下字段标题与故事Title一天的短标题。Story自由文本支持 Markdown。移动端卡片预览时会通过stripMarkdown去除 Markdown 符号再展示摘要见 client/src/components/Journey/stripMarkdown.ts。心情Mood原文档给出了四档心情。结合前端常量表 client/src/components/Journey/moodConfig.ts实现中的完整取值如下tired与文档表格略有出入以源码为准IDLabelColoramazingAmazingPink#E8654AgoodGoodAmber#EF9F27neutralNeutralGrey#94928CtiredTiredBlue#6B9BD2roughRoughViolet#9B8EC4心情会以图标形式渲染在桌面端条目卡片与移动端时间线卡片上。天气Weather原文档列出六种天气前端实现实际支持八种多了 Snowy 与 Hot见 moodConfig.tssunnySunny、partlyPartly cloudy、cloudyCloudy、rainyRainy、stormyStormy、snowySnowy、hotHot、coldCold每种都有对应的 Lucide 图标。照片与 HEIC 自动转换条目可附加多张照片第一张照片会作为列表视图中的卡片缩略图。上传接口为POST /api/journeys/entries/:entryId/photos服务端做了多重校验server/src/nest/journey/journey.controller.ts只接受image/*MIME 且拒绝 SVG文件扩展名必须在系统允许列表内getAllowedExtensions()默认包含jpg,jpeg,png,gif,webp,heic等见 server/src/services/fileService.ts单个文件上限 20 MB文件以crypto.randomUUID()重命名落盘到uploads/journey目录。HEIC 兼容性说明HEIC 是苹果独占格式许多浏览器与平台无法识别。为此 TREK 在前端上传前用heic-to库将 HEIC/HEIF 自动转换为 JPEG质量 0.92文件名后缀同步改为.jpg实现见 client/src/utils/convertHeic.ts。需要留意的是这种转换可能导致内嵌元数据EXIF如 GPS 坐标、相机信息等丢失。此外日记还支持图库gallery概念——POST /api/journeys/:id/gallery/photos上传到日记级图库POST /api/journeys/:id/gallery/video支持上传视频与封面帧poster 强制存为.jpg视频按MAX_VIDEO_SIZE限流并以 HTTP Range 流式播放见 journey.controller.ts。Pros / Cons 评价卡片可选的评价卡片向Pros列表大拇指朝上或Cons列表大拇指朝下添加条目用来总结旅途中的亮点与遗憾。它们在数据库中以 JSON 存储于条目的pros_cons字段结构为{ pros: string[], cons: string[] }服务端createEntry/updateEntry仅在数组非空时序列化见 server/src/services/journeyService.ts。标签、位置与时间Tags自由形式的标签如 hidden gem、best meal。前端对已知标签提供预设配色见 moodConfig.ts 中的TAG_STYLES服务端以 JSON 数组存储Location将条目固定到地图上的一个位置location_namelocation_lat/location_lngTime可选地记录一天中的某个时刻entry_time。创建条目的 API 合约要求entry_date必填否则 400其余字段走 allow-list 白名单更新journey.controller.ts、journeyService.ts。完整的请求体校验定义可参考 shared/src/journey/journey.schema.ts如journeyCreateRequestSchema、journeyShareLinkRequestSchema等 Zod 合约。移动端时间线在手机上条目以横向滚动的时间线卡片呈现卡片显示首张照片没有照片则显示定位占位图、日期、天数编号、心情图标与天气图标。点击卡片会在模态面板中打开完整条目视图相关组件见 client/src/components/Journey/MobileEntryCard.tsx 与 MobileEntryView.tsx。天数编号的背景色取自 30 色轮换的DAY_COLORS常量client/src/components/Journey/dayColors.ts保证相邻天数视觉上可区分。地图视图Journey 详情页包含一张地图桌面端地图位于右侧移动端则是地图与时间线整合的视图MobileMapTimeline展示全部条目的定位点以及关联行程的地点。地图组件见 client/src/components/Journey/JourneyMap.tsx 与 JourneyDetailPageMapView.tsx。条目的location_name、location_lat、location_lng在关联行程地点变化时也会被静默同步更新onPlaceUpdated仅更新位置不动用户已撰写的故事见 journeyService.ts。通过插件扩展条目行已安装的插件可以通过journalEntryProviderhook为日记条目卡片增加额外的信息行。插件返回形如{ label, value?, url? }的行数据TREK 会以原生方式渲染在条目下方不使用 iframe。该机制由 server/src/nest/plugins/journal-entry-rows.controller.ts 实现GET /api/journal-entry-rows/:entryId具备完整的加性additive与故障安全fail-safe设计要求 Journey addon 已启用且调用者对条目所属日记具备访问权限与读取日记使用同一套canAccessJourney校验只允许http:/https:/mailto:链接杜绝javascript:/data:造成的点击型 XSS行数据在服务端统一归一化label最长 60 字符、value最长 200 字符均会剥离 emoji每插件最多 12 行每个 provider 在 5 秒超时内运行出错或超时的插件被直接跳过绝不拖垮整页。调用插件需要hook:journal-entry-provider权限hook 契约详见 Plugin-Development.md。公开分享你可以用只读公开链接分享整本日记。生成链接时可独立开关三个区块的可见性开关可见内容Timeline条目与故事entries and storiesGallery照片photosMap地图访客只能看到你开启的区块且无需 TREK 账号。对应的共享设置接口为POST /api/journeys/:id/share-link参数share_timeline/share_gallery/share_map见 journey.controller.ts读取 token 同样需要具备日记访问权限。公开读取走独立的无鉴权通道GET /api/public/journey/:tokenserver/src/nest/journey/journey-public.controller.ts每个路由都以分享 token 校验为前提校验失败统一 404照片按thumbnail/original两种规格流式输出本地资源会做path.basename归一化并限定在uploads/journey目录内防目录穿越immich/synology提供商的资源则通过各自的服务代理流式传输。关于独立的日记分享 token 机制可进一步阅读 Public-Share-Links.md。权限与协作者模型从服务端代码可以提炼出 Journey 的三级权限模型journeyService.tsOwner创建者可以修改日记级设置标题、副标题、封面、状态管理行程关联、协作者与分享链接Editor协作者角色为editor可以新增、编辑、删除条目与照片Viewer协作者角色为viewer可以查看不能编辑。协作者通过POST /api/journeys/:id/contributors添加并指定roleeditor|viewer相关请求体契约见 journey.schema.ts 的journeyContributorRequestSchema。所有条目变更都会通过 WebSocket 以journey:entry:created/journey:entry:updated/journey:entries:reordered等事件广播给日记的所有者与协作者broadcastJourneyEvent实现多人实时协作x-socket-id头用于排除发起者自身的回放。相关文档Addons-Overview.md —— Addon 体系总览Admin-Addons.md —— 在管理后台启用 JourneyPublic-Share-Links.md —— 公开分享与分享 token 细节Plugin-Development.md ——journalEntryProvider插件 hook 开发指南【免费下载链接】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），仅供参考 TREK Journey Journal 旅行日记功能完全指南：照片优先的跨行程叙事与公开分享
TREK Journey Journal 旅行日记功能完全指南照片优先的跨行程叙事与公开分享【免费下载链接】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/TREKJourney Journal 是 TREK 中一个照片优先的旅行日记travel journal模块每本日记journey可关联一个或多个行程trip并按天沉淀文字、照片、心情与天气最终还能通过只读分享链接对外展示。本文以 Journey-Journal.md 为主体结合客户端组件与 Nest 服务端实现完整讲解 Journey 的启用、创建、条目编辑、移动端时间线、地图视图、插件扩展与公开分享机制读完即可上手使用并理解其底层数据与权限模型。什么是 JourneyJourney 让你可以沿着行程计划trip plan同步书写一段叙事性的旅行记录。与行程规划中的日程day plan不同Journey 的条目entry天然与具体日期绑定可以包含叙述性正文Story支持 Markdown 排版照片Photos心情评级Mood天气状况Weather正反面评价卡片Pros / Cons自由标签Tags、地图定位Location与时刻Time。完成后的日记可生成只读公开链接对外分享。在数据模型上Journey 是横跨多个行程的独立实体一条 Journey 通过journey_trips关联多个 Trip并通过journey_entries、journey_photos、journey_contributors分别承载条目、照片与协作者见 server/src/services/journeyService.ts 中的查询与写入逻辑。启用 JourneyAdmin 前提Journey 是一个可开关的 Addon默认不启用。需要在管理后台的 Addons 页面中开启参见 Admin-Addons.md。服务端会为此做两层防护添加守卫JourneyAddonGuardserver/src/nest/journey/journey-addon.guard.ts未启用时所有/api/journeys请求直接返回 404JourneyService.journeyAddonEnabled()调用isAddonEnabled(ADDON_IDS.JOURNEY)检查server/src/nest/journey/journey.service.ts。启用后主导航会出现Journey入口。Journey 列表页以卡片形式展示你的全部日记每张卡片包含封面图cover image以及条目数、照片数、地点数等统计——这些统计在服务端由listJourneys的子查询实时聚合见 server/src/services/journeyService.ts。创建一本 Journey在 Journey 列表页点击Create journey只需填写字段说明Title必填日记标题服务端会 trim 并拒绝空标题400Subtitle可选副标题Linked trips选择一个或多个已有行程关键机制是行程关联勾选行程后TREK 会把该行程中已排入日程的地点place导入为条目的位置锚点并自动生成对应日期的骨架条目skeleton entry。从源码看创建时逐个调用addTripToJourney内部做canAccessTrip访问校验防止把无权访问的行程拉进自己的日记造成跨租户泄露随后syncTripPlaces为每个地点生成骨架条目并继承首个真实关联行程的封面图server/src/services/journeyService.ts。骨架条目是日记与行程之间的活链接行程地点的新增、调整日期/时间、删除都会通过onPlaceCreated/onPlaceUpdated/onPlaceDeleted与reconcileTripSkeletons同步到日记幂等无变化时不产生写操作骨架条目没有故事时被删除一旦你为它补充了内容它会被提升为正式条目promoteSkeletonIfNeeded、updateEntry中写入 story 即触发 type 提升删除已填写内容的条目时服务端会把它还原为骨架而不是彻底删除deleteEntry。行程也可以在之后随时从日记设置journal settings中追加关联对应的 API 为POST /api/journeys/:id/trips与DELETE /api/journeys/:id/trips/:tripIdserver/src/nest/journey/journey.controller.ts。条目编辑器详解每条目对应旅程中的一天编辑器client/src/components/Journey/JourneyDetailPageEntryEditor.tsx提供以下字段标题与故事Title一天的短标题。Story自由文本支持 Markdown。移动端卡片预览时会通过stripMarkdown去除 Markdown 符号再展示摘要见 client/src/components/Journey/stripMarkdown.ts。心情Mood原文档给出了四档心情。结合前端常量表 client/src/components/Journey/moodConfig.ts实现中的完整取值如下tired与文档表格略有出入以源码为准IDLabelColoramazingAmazingPink#E8654AgoodGoodAmber#EF9F27neutralNeutralGrey#94928CtiredTiredBlue#6B9BD2roughRoughViolet#9B8EC4心情会以图标形式渲染在桌面端条目卡片与移动端时间线卡片上。天气Weather原文档列出六种天气前端实现实际支持八种多了 Snowy 与 Hot见 moodConfig.tssunnySunny、partlyPartly cloudy、cloudyCloudy、rainyRainy、stormyStormy、snowySnowy、hotHot、coldCold每种都有对应的 Lucide 图标。照片与 HEIC 自动转换条目可附加多张照片第一张照片会作为列表视图中的卡片缩略图。上传接口为POST /api/journeys/entries/:entryId/photos服务端做了多重校验server/src/nest/journey/journey.controller.ts只接受image/*MIME 且拒绝 SVG文件扩展名必须在系统允许列表内getAllowedExtensions()默认包含jpg,jpeg,png,gif,webp,heic等见 server/src/services/fileService.ts单个文件上限 20 MB文件以crypto.randomUUID()重命名落盘到uploads/journey目录。HEIC 兼容性说明HEIC 是苹果独占格式许多浏览器与平台无法识别。为此 TREK 在前端上传前用heic-to库将 HEIC/HEIF 自动转换为 JPEG质量 0.92文件名后缀同步改为.jpg实现见 client/src/utils/convertHeic.ts。需要留意的是这种转换可能导致内嵌元数据EXIF如 GPS 坐标、相机信息等丢失。此外日记还支持图库gallery概念——POST /api/journeys/:id/gallery/photos上传到日记级图库POST /api/journeys/:id/gallery/video支持上传视频与封面帧poster 强制存为.jpg视频按MAX_VIDEO_SIZE限流并以 HTTP Range 流式播放见 journey.controller.ts。Pros / Cons 评价卡片可选的评价卡片向Pros列表大拇指朝上或Cons列表大拇指朝下添加条目用来总结旅途中的亮点与遗憾。它们在数据库中以 JSON 存储于条目的pros_cons字段结构为{ pros: string[], cons: string[] }服务端createEntry/updateEntry仅在数组非空时序列化见 server/src/services/journeyService.ts。标签、位置与时间Tags自由形式的标签如 hidden gem、best meal。前端对已知标签提供预设配色见 moodConfig.ts 中的TAG_STYLES服务端以 JSON 数组存储Location将条目固定到地图上的一个位置location_namelocation_lat/location_lngTime可选地记录一天中的某个时刻entry_time。创建条目的 API 合约要求entry_date必填否则 400其余字段走 allow-list 白名单更新journey.controller.ts、journeyService.ts。完整的请求体校验定义可参考 shared/src/journey/journey.schema.ts如journeyCreateRequestSchema、journeyShareLinkRequestSchema等 Zod 合约。移动端时间线在手机上条目以横向滚动的时间线卡片呈现卡片显示首张照片没有照片则显示定位占位图、日期、天数编号、心情图标与天气图标。点击卡片会在模态面板中打开完整条目视图相关组件见 client/src/components/Journey/MobileEntryCard.tsx 与 MobileEntryView.tsx。天数编号的背景色取自 30 色轮换的DAY_COLORS常量client/src/components/Journey/dayColors.ts保证相邻天数视觉上可区分。地图视图Journey 详情页包含一张地图桌面端地图位于右侧移动端则是地图与时间线整合的视图MobileMapTimeline展示全部条目的定位点以及关联行程的地点。地图组件见 client/src/components/Journey/JourneyMap.tsx 与 JourneyDetailPageMapView.tsx。条目的location_name、location_lat、location_lng在关联行程地点变化时也会被静默同步更新onPlaceUpdated仅更新位置不动用户已撰写的故事见 journeyService.ts。通过插件扩展条目行已安装的插件可以通过journalEntryProviderhook为日记条目卡片增加额外的信息行。插件返回形如{ label, value?, url? }的行数据TREK 会以原生方式渲染在条目下方不使用 iframe。该机制由 server/src/nest/plugins/journal-entry-rows.controller.ts 实现GET /api/journal-entry-rows/:entryId具备完整的加性additive与故障安全fail-safe设计要求 Journey addon 已启用且调用者对条目所属日记具备访问权限与读取日记使用同一套canAccessJourney校验只允许http:/https:/mailto:链接杜绝javascript:/data:造成的点击型 XSS行数据在服务端统一归一化label最长 60 字符、value最长 200 字符均会剥离 emoji每插件最多 12 行每个 provider 在 5 秒超时内运行出错或超时的插件被直接跳过绝不拖垮整页。调用插件需要hook:journal-entry-provider权限hook 契约详见 Plugin-Development.md。公开分享你可以用只读公开链接分享整本日记。生成链接时可独立开关三个区块的可见性开关可见内容Timeline条目与故事entries and storiesGallery照片photosMap地图访客只能看到你开启的区块且无需 TREK 账号。对应的共享设置接口为POST /api/journeys/:id/share-link参数share_timeline/share_gallery/share_map见 journey.controller.ts读取 token 同样需要具备日记访问权限。公开读取走独立的无鉴权通道GET /api/public/journey/:tokenserver/src/nest/journey/journey-public.controller.ts每个路由都以分享 token 校验为前提校验失败统一 404照片按thumbnail/original两种规格流式输出本地资源会做path.basename归一化并限定在uploads/journey目录内防目录穿越immich/synology提供商的资源则通过各自的服务代理流式传输。关于独立的日记分享 token 机制可进一步阅读 Public-Share-Links.md。权限与协作者模型从服务端代码可以提炼出 Journey 的三级权限模型journeyService.tsOwner创建者可以修改日记级设置标题、副标题、封面、状态管理行程关联、协作者与分享链接Editor协作者角色为editor可以新增、编辑、删除条目与照片Viewer协作者角色为viewer可以查看不能编辑。协作者通过POST /api/journeys/:id/contributors添加并指定roleeditor|viewer相关请求体契约见 journey.schema.ts 的journeyContributorRequestSchema。所有条目变更都会通过 WebSocket 以journey:entry:created/journey:entry:updated/journey:entries:reordered等事件广播给日记的所有者与协作者broadcastJourneyEvent实现多人实时协作x-socket-id头用于排除发起者自身的回放。相关文档Addons-Overview.md —— Addon 体系总览Admin-Addons.md —— 在管理后台启用 JourneyPublic-Share-Links.md —— 公开分享与分享 token 细节Plugin-Development.md ——journalEntryProvider插件 hook 开发指南【免费下载链接】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），仅供参考