旅行足迹地图

一款私人的旅行足迹记录工具，帮助你在地图上标记去过的城市和景点，上传旅行照片，撰写旅行游记。

功能特性

• 地图展示 — 高德地图集成，城市标记、行程路线、照片地图模式
• 旅行管理 — 创建/编辑/删除旅行，添加地点，拖拽排序
• 照片管理 — 上传/删除照片，自动生成缩略图，全屏预览
• 游记撰写 — Markdown 编辑器，实时预览
• 时间线 — 按年月分组回顾旅行足迹
• 统计分析 — 年度/月度统计，城市排行榜
• 全局搜索 — 搜索旅行、地点、城市
• 分享功能 — 生成分享链接（30天过期）
• 导入导出 — JSON/Markdown 格式，支持批量导入
• 深色模式 — 自动跟随系统或手动切换
• 响应式设计 — 适配桌面端和移动端

技术栈

层级	技术
前端	Vue 3 + TypeScript + Vite + Element Plus + Pinia
后端	Python FastAPI + SQLAlchemy + Pillow
数据库	SQLite
地图	高德地图 JS API v2.0
测试	pytest (后端) + Vitest (前端) + Playwright (E2E)
部署	Docker Compose（nginx + uvicorn）

快速开始

1. 克隆仓库

git clone https://github.com/baoxinwen/footprint.git
cd footprint

2. 配置环境变量

cp .env.example .env
# 编辑 .env，至少设置 JWT_SECRET

3. Docker 部署

docker compose pull
docker compose up -d

4. 访问应用

• 前端：http://localhost:8001
• 后端 API：http://<NAS 的 IP>:8002（对局域网开放）
• API 文档：http://<NAS 的 IP>:8002/docs

8001 默认是明文 HTTP，并发布到宿主机所有网络接口。局域网或公网部署时应在其前方配置 HTTPS 反向代理和防火墙，不要直接暴露到公网；外层代理也应关闭 /api/shares/view/ 路径的访问日志，避免分享 token 进入日志。

本地开发

后端

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

前端

cd frontend
npm install
npm run dev

测试

# 后端测试
cd test
pip install -r requirements-test.txt
pip install -r ../backend/requirements.txt
pytest

# 前端测试
cd frontend
npm run test

# E2E 测试 (需要启动后端和前端服务)
npx playwright test

项目结构

├── backend/               # FastAPI 后端
│   └── app/
│       ├── api/           # 路由模块 (auth, trips, photos, shares, stats, timeline, export_import, amap, account, search)
│       ├── core/          # 配置、数据库、安全
│       ├── models/        # SQLAlchemy 模型 (user, trip, location, photo, share)
│       ├── schemas/       # Pydantic 请求/响应模型
│       └── utils/         # 工具函数 (image, rate_limit, escape, zip_utils, storage, upload, data_dir)
├── frontend/              # Vue 3 前端
│   ├── src/
│   │   ├── api/           # API 请求封装
│   │   ├── views/         # 页面组件 (10 个页面)
│   │   ├── components/    # 共享组件 (PhotoViewer, EmptyState, AuthenticatedImage)
│   │   ├── stores/        # Pinia 状态管理
│   │   ├── composables/   # 组合式函数 (useTheme, useAuthenticatedImage)
│   │   ├── utils/         # 工具函数 (format, markdown, authSession, tripDraft, authenticatedImage)
│   │   └── router/        # Vue Router
│   └── e2e/               # Playwright E2E 测试 (13 个测试文件)
├── test/                  # 后端 pytest 测试
│   ├── unit/              # 单元测试 (13 个文件)
│   ├── integration/       # 集成测试 (13 个文件)
│   ├── e2e/               # 端到端测试 (完整流程 test_e2e_flow.py)
│   └── test_deployed.py   # Docker 部署实例集成测试
├── docker-compose.yml     # Docker 部署配置
└── .github/workflows/     # CI/CD 自动构建

环境变量

变量	必填	说明
JWT_SECRET	是	JWT 签名密钥
FOOTPRINT_DATA_DIR	否	单一持久化数据根目录，默认 ./data
PUID / PGID	否	后端写入持久化目录时使用的非 root 宿主机 UID/GID，必须大于 0，默认 1000
AMAP_KEY	否	高德地图 API Key（POI 搜索功能需要）
AMAP_SECURITY_CODE	否	高德地图 JS API 的浏览器端安全密钥

数据持久化

• 数据库：./data/db/footprint.db
• 上传文件：./data/uploads/
• 导出临时文件：./data/tmp/（响应结束后自动删除）

License

MIT