NomadFlow · 数字游民旅居平台

全栈数字游民旅居指南，采用 Next.js + FastAPI + PocketBase 架构。
品牌：NomadFlow — 用一行代码环游世界 🌏

技术栈

层级	技术	说明
前端	Next.js 16 + React 19	SSR/ISR、组件化 UI、Turbopack
后端	FastAPI	REST API、业务逻辑
数据库	PocketBase	数据持久化、管理后台
图表	Chart.js (CDN)	数据可视化
部署	Vercel + Railway + Docker	前后端分离部署

项目结构

nomadweb/
├── frontend/              # Next.js 前端应用
│   ├── src/app/           # 页面路由 (App Router)
│   ├── src/components/    # UI 组件 (30+)
│   └── src/lib/           # API 客户端、Auth、Toast
├── backend/               # FastAPI 后端
│   ├── app/routers/       # API 路由
│   ├── app/services/      # PocketBase、Auth 服务
│   └── app/data/          # Mock 降级数据
├── pocketbase/            # PocketBase 数据目录
├── scripts/               # 开发启动脚本 (dev.ps1 / dev.sh)
├── docker-compose.yml     # 一键启动全部服务
├── index.html             # 原始静态版（保留）
└── README.md

快速开始

方式一：本地开发（推荐）

1. 启动 PocketBase（可选）

# 下载: https://pocketbase.io/docs/
# 或使用 Docker:
docker run -d -p 8090:8090 -v ./pocketbase/pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest

访问 http://localhost:8090/_/ 创建管理员（可选，不启动则自动使用 Mock 数据）。

2. 启动 FastAPI 后端

cd backend
pip install -r requirements.txt
cp .env.example .env   # 按需修改
uvicorn app.main:app --reload --port 8000

API 文档: http://localhost:8000/docs

3. 启动 Next.js 前端

cd frontend
cp .env.local.example .env.local
npm install --legacy-peer-deps
npm run dev

访问 http://localhost:3000

方式二：一键脚本（Windows）

.\scripts\dev.ps1

方式三：Docker Compose

docker compose up -d

服务	地址
前端	http://localhost:3000
API	http://localhost:8000/docs
PocketBase	http://localhost:8090/_/

功能特性

首页核心板块

板块	说明
🗺️ 世界地图	交互式 SVG 热力图，点击查看城市详情
🌍 目的地	筛选/搜索/排序，收藏，最多 4 城对比
🎯 智能匹配	4 步问卷，推荐最适合的旅居城市
🕐 时区看板	实时时钟 + 与国内团队工作时间重叠分析
🗓️ 行程规划	多城市规划，预算汇总，分享/导入链接
🧮 费用计算器	按目的地、住宿档次、月数估算预算
💱 多币种换算	CNY/USD/EUR/THB 等 8 种货币互转
📊 就绪度测评	5 题评估你的数字游民准备程度
💻 生活方式	交互式「游民一天」时间轴
📋 签证指南	难度筛选 + 进度条可视化
📝 博客	文章列表 + 阅读进度条详情页
❓ FAQ	手风琴问答

交互与体验

• ✨ Canvas 粒子背景 + 品牌加载动画
• 🌓 深色/浅色主题切换（localStorage 持久化）
• 🔍 全局搜索 Ctrl+K（目的地/博客/签证/FAQ）
• 🧭 右侧浮动章节导航
• 📊 顶部滚动进度条
• ⚖️ 可视化城市对比（评分圆环 + 条形图）
• 🔔 全局 Toast 通知
• ⌨️ 快捷键：M 智能匹配、? 帮助面板
• 📱 响应式布局，移动端适配

用户系统

• 🔐 登录 / 注册 / 一键演示账号
• ❤️ 收藏目的地（同步 API）
• 👤 用户中心：统计、收藏、行程展示
• 演示账号：demo@nomadflow.io / demo123

后端 API

端点	方法	说明
/api/v1/destinations	GET	目的地列表（region/search/sort）
/api/v1/destinations/{slug}	GET	目的地详情
/api/v1/destinations/compare	POST	城市对比（2–4 城）
/api/v1/calculator	POST	费用计算
/api/v1/search	GET	全局搜索
/api/v1/blog	GET	博客列表
/api/v1/blog/{slug}	GET	博客详情
/api/v1/auth/register	POST	注册
/api/v1/auth/login	POST	登录
/api/v1/auth/demo	GET	演示登录
/api/v1/auth/favorites	GET/POST	收藏管理
/api/v1/charts/*	GET	图表数据
/api/v1/subscribe	POST	邮件订阅

PocketBase 不可用时，API 自动降级到 backend/app/data/mock_data.py。

页面路由

路径	说明
/	首页（全部板块）
/login	登录 / 注册
/profile	用户中心
/destinations/[slug]	目的地详情（城市画像、加入行程）
/blog/[slug]	博客详情（阅读进度）

环境变量

Backend (backend/.env)

POCKETBASE_URL=http://127.0.0.1:8090
POCKETBASE_ADMIN_EMAIL=admin@nomadflow.io
POCKETBASE_ADMIN_PASSWORD=admin123456
CORS_ORIGINS=http://localhost:3000

Frontend (frontend/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1

部署

前端 → Vercel

1. 导入 frontend/ 目录
2. 环境变量：NEXT_PUBLIC_API_URL=https://your-api.example.com/api/v1
3. 自动构建部署

后端 → Railway

1. 连接 backend/ 目录
2. 配置 POCKETBASE_URL、CORS_ORIGINS
3. 读取 railway.toml 自动部署

全栈 → Docker Compose

docker compose up -d

快捷键

按键	功能
Ctrl+K	全局搜索
M	智能目的地匹配
?	快捷键帮助
Esc	关闭弹窗

License

MIT