img

一个码农

Python, Quant

Oliver

个人站

欢迎来到我的个人站~

本地开发环境设置指南

本地开发环境设置指南

已完成的文件创建

✅ 以下文件已经创建完成：

  1. package.json - Node.js 依赖配置
  2. vercel.json - Vercel 部署配置
  3. api/add-city.js - 添加城市的 Serverless API
  4. admin.html - 足迹管理界面
  5. .env.local - 本地环境变量（需要配置）
  6. .gitignore - 已更新，忽略 node_modules 等

本地测试方案

由于完整的 Vercel 环境需要登录，这里提供两种本地测试方案：

方案 1：仅查看管理界面（推荐快速预览）

  1. 启动 Jekyll 服务器（如果已安装 Jekyll）： 
    bundle install
bundle exec jekyll serve

  2. 访问管理界面： 打开浏览器访问：http://localhost:4000/admin.html

  3. 查看现有足迹地图： 访问：http://localhost:4000/footprint.html

注意：此方案下 API 功能不可用，但可以查看界面效果

方案 2：完整功能测试（使用 Vercel CLI）

  1. 登录 Vercel： 
    npx vercel login

    按提示完成登录

  2. 配置环境变量： 编辑 .env.local 文件，填入实际的值： 
    GITHUB_TOKEN=ghp_你的GitHub_Token
API_AUTH_TOKEN=你的管理密码

    获取 GitHub Token：

    • 访问：https://github.com/settings/tokens
    • Generate new token (classic)
    • 勾选 repo 权限
    • 生成并复制 token
  3. 启动 Vercel 开发服务器： 
    npx vercel dev
  4. 访问本地站点：
    • 管理界面：http://localhost:3000/admin.html
    • 足迹地图：http://localhost:3000/footprint.html
  5. 测试添加城市功能：
    • 打开 admin.html
    • 填写表单
    • 输入管理密码（.env.local 中的 API_AUTH_TOKEN）
    • 提交测试

方案 3：直接部署到 Vercel 在线测试

如果本地环境配置困难，可以直接部署到 Vercel：

  1. 访问 Vercel：https://vercel.com

  2. 导入 GitHub 仓库：
    • New Project
    • Import Git Repository
    • 选择 pea1ce.github.io
  3. 配置构建设置：
    • Framework Preset: Other
    • Build Command: bundle install && bundle exec jekyll build
    • Output Directory: _site
  4. 添加环境变量： 在 Vercel 项目设置中添加： 
    GITHUB_TOKEN=你的GitHub_Token
API_AUTH_TOKEN=你的管理密码
GITHUB_OWNER=pea1ce
GITHUB_REPO=pea1ce.github.io
GITHUB_BRANCH=master
  5. 部署并测试：
    • 等待部署完成
    • 访问 https://your-project.vercel.app/admin.html
    • 测试添加城市功能

功能说明

管理界面 (admin.html)

功能包括：

  • ✅ 用户友好的表单界面
  • ✅ Token 认证（首次输入后保存在浏览器）
  • ✅ 输入验证和错误提示
  • ✅ 支持添加国内城市（三级结构）
  • ✅ 支持添加国外国家
  • ✅ 添加游记链接和备注

API 功能 (api/add-city.js)

  • ✅ Token 认证保护
  • ✅ 从 GitHub 读取现有数据
  • ✅ 智能合并新数据到 JSON
  • ✅ 自动提交到 GitHub
  • ✅ 输入清理（防止 XSS）
  • ✅ 错误处理和重试机制

工作流程

用户在 admin.html 填写表单
    ↓
提交到 /api/add-city（带 Token）
    ↓
API 验证 Token
    ↓
从 GitHub 读取 travel_cities.json
    ↓
添加新城市到 JSON
    ↓
提交更新回 GitHub（自动 commit）
    ↓
GitHub webhook 触发 Vercel 重新部署
    ↓
2-3 分钟后地图显示新数据

测试示例

添加国内城市

用户: oliver
国家: China
省份: 江苏
城市: 苏州市
备注: 2024-03-10，周末游

添加国外国家

用户: oliver
国家: Thailand
省份: (留空)
城市: (留空)
备注: 2023-12-20，泰国之旅

常见问题

Q: 本地测试时 API 调用失败？

A: 确保：

  1. 已启动 vercel dev
  2. .env.local 中配置了正确的环境变量
  3. GitHub Token 有 repo 权限

Q: 提交后地图没有更新？

A: 这是正常的，因为：

  1. 数据已提交到 GitHub（可以检查仓库）
  2. Vercel 需要重新部署（2-3 分钟）
  3. 刷新页面前等待部署完成

Q: 忘记了管理密码？

A: 打开浏览器控制台，执行：

localStorage.removeItem('apiToken')

然后刷新页面，重新输入密码

下一步

如果一切正常，你可以：

  1. ✅ 添加更多城市测试
  2. ✅ 自定义 admin.html 的样式
  3. ✅ 在 footprint.html 添加”管理”按钮
  4. ✅ 配置自定义域名 (heyiping.cn)
  5. ✅ 添加更多功能（批量导入、照片墙等）

文件清单

mysite/
├── api/
│   └── add-city.js          ✅ 已创建
├── admin.html               ✅ 已创建
├── vercel.json              ✅ 已创建
├── package.json             ✅ 已创建
├── .env.local               ✅ 已创建（需配置）
├── .gitignore               ✅ 已更新
└── LOCAL_SETUP.md           ✅ 本文档

祝你使用愉快！🎉