giovannibrees/travel-roamradar

# ✈️ RoamRadar - 你的个人旅行枢纽 [](LICENSE)   

一款单页面的旅行应用，你可以**自行托管**，完全免费地部署在你自己的 Cloudflare 账户上。它会将你的所有行程汇聚在一起，并（可选地）从你的 **Google Calendar** 和 **Gmail** 中自动提取并补充详细信息，同时提供更多扩展功能： 年度日历、“足迹”世界地图、单次行程的天气、货币、插头类型、紧急联系电话，以及一键“添加到任意日历”功能。 ## 内部预览 | 行程一览 | 年度概览 + 旅行天数 | “足迹”地图 | |:---:|:---:|:---:| |  |  |  | _{这是一个“里斯本”行程示例。应用会自动获取每个目的地的照片。} ## ✨ 核心功能 **行程与计划** - 🧳 **单次行程计划** — 为任意行程添加航班、酒店、接送服务和自由文本备注；手动添加的计划绝不会在同步时被覆盖。 - ✍️ **手动添加或自动填充** — 几秒钟即可输入一次行程，或者连接 Google 账户（见下文），让预订信息自动流入。 - 🛟 **你的手动计划神圣不可侵犯** — 任何自动同步都不会更改或删除你手动添加的计划。 **规划与概览** - 🗓️ **日历概览** — 提供 3 / 6 / 12 个月的视图，精确显示你的外出时间，每一天的旅行日程都会被标记出来。 - 📊 **年度旅行天数** — 查看每个自然年（1 月 1 日至 12 月 31 日）的总旅行天数；点击某一年可查看按行程划分的明细，让任何一个数字都只需轻点一下即可了解“原因”。 - 🌍 **“足迹”世界地图** — 在世界地图上填满你踏足过的每一个国家，并带有**访问次数**（即使是微小的岛国也不遗漏）。 - 🛫 **即将进行 / 过去 / 心愿单** 标签页，并附带票价监控心愿单，专为那些你梦寐以求的行程打造。 **一目了然的目的地情报**（按行程自动填充） - 🌦️ 根据你的旅行日期提供**天气**预报（如果日期较远，则提供典型的气候信息）。 - 💱 **货币**汇率，同时显示与**欧元和美元**的实时汇率。 - 🔌 **插头类型和电压**，让你带上正确的转换器。 - 🆘 **当地紧急联系电话**。 - 🖼️ 你的目的地**真实照片**。 **专属于你手机上的私人应用** - 🔗 **分享行程** — 一键复制一个私有的只读链接，让旅行同伴查看实时行程（包括酒店门锁密码），且无需登录。 - 🎉 **年度回顾** — 翻转分享卡片即可查看你的年度回顾：行程数、旅行天数、国家数、距离 — 随时可分享成故事。 - 📅 **添加到任意日历** — 一键导出 `.ics` 文件，适用于 Apple / Google / Outlook，此外还提供一个所有行程的私有 URL 订阅源，并保持实时更新。 - 🩹 **每周快照** — 每周日自动进行完整备份（保留 4 周，且在执行任何破坏性操作前都会额外备份一次），只需一键即可恢复。 - 📱 **像原生应用一样安装** — 在 iPhone 或 Android 上添加到主屏幕，全屏打开，离线可用（它是一个 PWA）。*(下方有详细步骤。)* - 🔐 **你的专属密码** — 只需设置一次，每台设备可保持登录状态 30 天。 - 🗄️ **备份与导入** — 将你所有的行程导出为 JSON 格式，随时可以重新导入。 - 🛡️ **100% 属于你的数据** — 所有数据都存储在*你的* Cloudflare 账户中；其他任何人（即使是代码仓库的作者）都无法查看你的行程。 ## 部署你自己的应用（约 5 分钟，免费） ### 1. 点击按钮 [](https://deploy.workers.cloudflare.com/?url=https://github.com/giovannibrees/travel-roamradar) 这会将代码仓库复制到**你的** GitHub 中，在你的 Cloudflare 账户中创建 Worker，并**自动创建所需的 KV namespace**。（免费套餐完全够用。）完成后，你会得到一个类似 `https://travel-roamradar.<你>.workers.dev` 的 URL。 ### 2. 打开应用并设置密码 打开你的新 URL。**第一个**登录的人需要设置邮箱和密码 — 所以请立即进行此操作。（可以使用任意邮箱；它仅用于登录。） ### 3. 开始添加行程 这就是你所需要做的全部操作 — 添加一个带有日期的行程，其他所有信息（天气、 货币、地图、日历）都会自动填充。想让你的预订信息自动导入吗？请在下方的**自动导入**部分连接 Google。 ### 4. 将其固定在手机主屏幕上 请查看下方**“📱 添加到主屏幕”**部分，获取针对不同手机的具体操作步骤。 大功告成。🎉 ## 📱 添加到主屏幕 这款应用是一个 **PWA** — 一旦将其添加到主屏幕，它就会以全屏模式打开，带有 独立图标，没有浏览器地址栏，并且像普通应用一样运行（对于不需要网络的部分，甚至可以离线使用）。 ### iPhone / iPad (Safari) 1. 在 **Safari** 中打开你的应用 URL（例如 `https://travel-roamradar.<你>.workers.dev`） — 在 iOS 上必须是 Safari，而不是 Chrome。 2. 点击 **Share（分享）** 按钮（带有向上箭头的方形图标）。 3. 向下滑动并点击 **Add to Home Screen（添加到主屏幕）**。 4. 如果需要，可以修改名称 → 点击右上角的 **Add（添加）**。 5. 从新图标打开应用。登录一次；它将保持登录状态 30 天。 ### Android (Chrome) 1. 在 **Chrome** 中打开你的应用 URL。 2. 点击右上角的 **⋮** 菜单。 3. 点击 **Add to Home screen（添加到主屏幕）**（如果出现 **Install app（安装应用）** 选项，也可以选择该选项）。 4. 确认 **Add / Install（添加 / 安装）**。 5. 从新图标打开应用并登录。

更喜欢使用命令行？（可选）

``` git clone https://github.com/giovannibrees/travel-roamradar && cd travel-roamradar npm i -g wrangler && wrangler login wrangler kv namespace create TRIPS # paste the id into wrangler.toml wrangler deploy ```

## 自动导入（可选） 这款应用完全可以手动使用。如果想让行程自动填充，请从应用内部（Settings）连接以下 服务 — 无需使用 Cloudflare dashboard： - **Google Calendar & Gmail** — 在 console.cloud.google.com 上进行一次性设置 （创建项目，启用 Calendar + Gmail APIs，创建 OAuth client； 应用会显示你需要粘贴的专属 origin/redirect 值）。然后在 Settings → **Connect Google**。行程会被写入你的日历，日历上的预订信息也会自动附加到对应行程中。 - **邮件 → 行程解析（通过 Claude）** — 在 Settings 中粘贴你自己的 Anthropic API key。 收件箱中的预订确认邮件（Booking.com、Airbnb、航空公司、 Uber…）会被自动解析为计划 — 带有门锁 PIN 码的酒店、带有航班号和起降时间的航班、接送车辆信息等。应用关闭时，**每小时的后台检查**也会处理新邮件；每日同步会执行全面检查。 - **转发任何内容**：将任何确认邮件发送给你自己，在 @ 符号前加上 **+trip** （例如 `you+trip@yourdomain.com`），它会在一小时内被归档处理 — 无论发件人是谁。如果还没有匹配的行程，转发的 **酒店预订或返程票会自动创建行程**。归档功能具备地理感知能力（例如丰沙尔的酒店会被归入你的“马德拉群岛”行程），甚至没有明确日期的酒店消息（比如一条门锁密码通知）也会根据目的地归入正确的行程。应用内的 **Help** 会显示你的个人转发地址。 - 支持 **Calendly** 作为 Worker secret（参见 `docs/dev.vars.example`）。 相比于应用内的 key，更喜欢使用 dashboard secrets？所有凭证也都可以通过 `wrangler secret put` 进行设置 — dashboard secret 的优先级始终高于应用内的副本。 ## 工作原理 - `travel-app.html` / `public/index.html` — 前端（单文件，vanilla JS）。 - `worker.js` — Cloudflare Worker：提供应用服务，通过密码进行保护， 运行可选的 Google Calendar + Gmail 导入功能，并将 所有数据存储在一个 KV namespace (`TRIPS`) 中。 - `wrangler.toml` — Worker 配置：包含 KV 绑定，每天执行一次全面同步 (18:00 UTC) 以及每小时的邮件专项检查 — 应用内的 **Sync** 按钮可按需运行完整任务。 ``` Trip: { id, from, to, start (YYYY-MM-DD), end, label, notes, segments[] } ``` ## 隐私 所有数据都存储在**你的** Cloudflare 账户中：你的行程存储在你的 KV 中，你的 key 位于 你的 Worker 上，并受密码保护。此代码仓库的维护者无法 访问你的实例或你的数据。 ### 匿名安装计数 唯一的例外是一个很小的情况：在首次设置时（即你创建密码的那一刻），你的实例可能会发送 **一次** 匿名 ping — 实际上就是 `{ "id": "<一个随机的 128 位数字>" }`，除此之外不包含任何其他信息 — 发送给维护者运行的 一个小型计数器 Worker，仅仅是为了让他们大致了解有多少人在使用这个模板。 事情的全部就是这样。**不发送、不跟踪、不记录任何行程、邮件、key、姓名、位置 — 除了那个随机数字之外，绝没有任何其他数据在任何时间、出于任何原因被发送或提供给任何人。** 该 id 无法追踪到你；它的存在只是为了防止你的实例被重复计数。 要查看当前的总数，请在浏览器中打开 `https://.workers.dev/count?key=` — 这是一个纯文本页面，只显示数字，没有其他可解析的内容。 双方的代码都是公开的：ping 操作是 `worker.js` 中的 `pingInstallCount()`，而接收它的 计数器代码就是 `counter/counter-worker.js` 的全部内容 — 区区五行代码，用于存储 id 和总数， 别无其他。 它**默认是关闭的** — `TELEMETRY_URL` 在 `wrangler.toml` 中默认留空， 这意味着绝对不会产生任何网络调用，除非你自己部署了计数器并将它的 URL 填进去。如果你是从某个公开克隆的代码仓库部署的，且该仓库已经有人（例如维护者）填入了这一行，这意味着你的实例也会参与统计；将该行留空，或者删除 `worker.js` 中的那个 `ctx.waitUntil (pingInstallCount(env))` 调用，即可完全退出 — 无论如何，应用中的其他任何功能都不依赖于它。 ## 常见问题解答 **RoamRadar 是免费的吗？** 是的。它是开源且自托管的 - 你可以在自己的 Cloudflare 账户上运行自己的副本，个人使用完全免费。 **我的旅行数据存储在哪里？** 存储在你自己的 Cloudflare KV 中，受你自己的密码保护。不会向任何共享服务器发送任何数据，代码仓库作者也无法查看你的行程。 **我必须连接我的邮箱或日历吗？** 不需要。RoamRadar 完全可以手动使用。连接 Google Calendar 和 Gmail 是 可选的，仅仅是为了让你的行程根据现有的预订信息自动填充。 **RoamRadar 是用什么构建的？** 由单个 Cloudflare Worker 提供的 vanilla-JavaScript 前端，并使用了一个 KV namespace 进行存储。没有框架，没有构建步骤。 **谁开发了 RoamRadar？** [Giovanni Brees](https://www.giovannibrees.com)，一位创始人和 AI-first 创业者。 他的 AI 开发 agent 从零开始构建了这款应用，并由 Claude Fable 和 Codex 进行了代码审查，Claude 负责了视觉设计。 ## 作者 由 **[Giovanni Brees](https://www.giovannibrees.com)** 创建 - 他是一位创始人和 致力于在 AI agents 与自动化前沿领域进行开发和写作的 AI-first 创业者。RoamRadar 是他利用 AI agents 开发完整且实用软件的实验之一。 - Website: https://www.gannibrees.com - LinkedIn: https://www.linkedin.com/in/giovannibrees/ - Podcast, *The Zero-Employee Company*: https://open.spotify.com/show/033TuF4FmEurDDvBZlOAYr ## 许可证 [PolyForm Noncommercial 1.0.0](LICENSE) — 可免费运行、修改和自托管，仅限于 任何**非商业**用途。不得将其出售或用于商业用途。

标签：AI代理, 后端开发, 旅行应用, 时间线, 程序员工具, 自托管, 高对比度