足迹 on CHEN 的博客

足迹后台的实现：设备互联、地点解析与自动发布

Fri, 11 Sep 2026 12:05:00 +0800

上一篇文章里，我写了足迹公开页是怎么做出来的：Hugo 读取 data/footprints.yaml，把地点数据嵌进页面，再交给 TypeScript 初始化腾讯地图、地点列表和照片灯箱。

这篇讲它后面的管理功能。整个功能的核心入口不是公网域名，而是 Tailscale：我的手机、电脑和服务器登录同一个 Tailscale 账户，设备之间先通过 tailnet 互联，然后手机才能进入服务器上的足迹管理页面。这样做的好处是，管理入口不需要暴露在博客公网域名上。

公开页做完之后，真正麻烦的部分才开始出现：我不想每次拿手机拍完照片，都要先把文件传到电脑，再手动处理图片、填写 YAML、重新构建博客。于是我把上传、地点解析、数据更新和发布串成了一条只服务于自己生活记录的技术链路。

它看起来是一个上传页面，实际上是一条小型发布流水线：手机通过 Tailscale 进入私有入口，输入或读取照片地点，服务处理图片，修改 Hugo 数据，构建并发布站点。中间任何一环出错，都应该明确告诉我，而不是给我一个“好像上传成功了”的按钮状态。

我没有把上传接口放到公网

后台的第一个约束是：它不应该成为博客的公开功能。

博客公开页面仍然由 Nginx 提供，足迹上传服务则是一个单独的 Flask 进程，默认只监听本机回环地址：

127.0.0.1:8791

systemd 单元里明确写了运行用户和监听方式：

[Service]
User=ubuntu
Group=ubuntu
EnvironmentFile=/etc/footprints-upload.env
ExecStart=/usr/bin/python3 /home/ubuntu/blog-src/scripts/footprints_upload.py

这里有两个好处。

第一，公网 Nginx 根本无法把这个端口暴露出去。第二，上传服务不是 root 进程，即使代码出现问题，默认权限也被限制在博客用户和指定图片目录内。

我还在公网 Nginx 里显式拒绝了这两个路径：

location ^~ /footprints-admin/ { return 404; }
location ^~ /api/footprints/ { return 404; }

之前 Nginx 对未知路径会回退到首页，访问后台路径虽然看不到后台内容，却会返回 200。这不算真正的泄露，但会让排查和安全判断变得模糊，所以我最后让它明确返回 404。

Tailscale 解决的是“谁能碰到后台”

只监听 127.0.0.1 之后，手机自然访问不到。这里我没有给后台再做一个公网域名，而是使用 Tailscale Serve：

https://tokyo-exit-node.tailde6fbb.ts.net:8443/footprints-admin/

Tailscale 在这条链路里的价值，不只是“有一个 VPN IP”。它把后台入口限制在我的 tailnet 内：手机必须先登录同一个 Tailscale 网络，外部互联网用户即使知道 URL，也无法建立这条私有连接。

但我很快遇到一个实际问题：博客的 Nginx 已经占用了公网 443 端口。最初我把 Serve 配到 443，配置状态看起来是成功的，服务器本机访问却仍然命中了 Nginx，手机端表现为页面卡住。

最后我把 Serve 改到 8443：

tailscale serve --bg --https=8443 http://127.0.0.1:8791

改完以后，用完整端口访问，服务端返回才稳定命中 Flask 后台。这里的经验很直接：看到 tailscale serve status 显示 proxy，并不等于你从实际客户端访问时一定经过了它，端口占用和本机网络路径都需要验证。

Tailscale 不是唯一一道门

Tailscale 解决的是网络范围，但我仍然给后台加了独立账号密码。

Flask 在 /footprints-admin/ 和 /api/footprints 前做 Basic Auth，密码只以 Werkzeug 哈希保存在：

/etc/footprints-upload.env

这个文件是 root:root、0600 权限，仓库里不保存明文密码。上传接口还要求：

X-Requested-With: XMLHttpRequest

这不是完整的复杂会话系统，但可以挡住普通跨站表单直接提交；后台页面通过同源 fetch 自己带上这个请求头。

所以现在的访问链路是两层：

手机登录 Tailscale
        ↓
进入 tailnet 私有 HTTPS
        ↓
Basic Auth 账号密码
        ↓
后台页面和上传 API

对我这种单用户、低频、只给自己用的后台来说，这比把上传接口直接挂在博客公网域名下更合适。它减少了公网攻击面，也不需要先为一个小工具搭完整的用户系统。

每张图片都要有自己的地点

最初的上传页只有一个文件选择框。第一次实际用手机测试时，我发现“文件上传成功”不等于“足迹完成了”。图片目录里有了 WebP，但地图完全没有变化。

原因很简单：地图读取的是 data/footprints.yaml，它需要地点、坐标、日期和照片之间的关系。单独把图片放到 static/images/footprints/，Hugo 不会凭空知道它应该落在哪个坐标。

所以现在上传页会为每张图片生成一个地点输入框：

照片 A   地点：泸沽湖
照片 B   地点：
照片 C   地点：香港大学梅堂

后台接收的地点数组和图片顺序一一对应：

images    = [a.jpg, b.jpg, c.jpg]
locations = ["泸沽湖", "", "香港大学梅堂"]

手动填写地点时，服务端调用腾讯位置服务的地址解析接口，将文字转换为经纬度和省市信息。留空时，后台读取照片的 EXIF GPS；像最初那张香港大学梅堂的照片，就可以直接从原图拿到：

date: 2017-01-16
lat: 22.282116...
lng: 114.139808...

这两个分支的优先级很明确：

手动地点
    ↓ 有
腾讯地理编码

手动地点为空
    ↓ 有
EXIF GPS

两者都没有
    ↓
这一张失败，其他图片继续

“其他图片继续”很重要。批量上传 10 张照片时，不能因为其中一张没有 GPS，就把另外 9 张也全部回滚。接口现在会返回成功图片、失败文件名和失败原因，前端再用弹窗告诉我本次是全部成功还是部分成功。

图片处理和地点数据现在是一件事

每张图片成功后，后台会完成几步处理：

检查扩展名、MIME 类型和真实文件签名；
根据 EXIF 修正方向；
生成最长边 2560 像素的展示图；
生成最长边 640 像素的缩略图；
删除公开版本中的 EXIF 和 GPS；
生成随机图片 ID；
组合地点、日期、坐标和照片 URL 的 YAML。

现在返回的 YAML 已经不是单独的一段图片地址，而是可以直接进入 locations 数组的完整地点：

- id: fp-example
  name: "泸沽湖"
  date: ""
  lat: 27.6894
  lng: 100.7798
  country: "中国"
  province: "云南省"
  city: "丽江市"
  category: ""
  category_name: ""
  description: ""
  cover: /images/footprints/2026/09/fp-example-thumb.webp
  photos:
    - src: /images/footprints/2026/09/fp-example.webp
      thumb: /images/footprints/2026/09/fp-example-thumb.webp
      alt: "泸沽湖"
      caption: ""

上传成功之后，为什么还要自动发布

一开始我认为“把 YAML 片段返回给我，手动粘贴一下”也可以。但既然已经决定用手机管理图片，再让我回电脑改数据、跑 Hugo，就等于把最麻烦的步骤留在了后台之外。

所以现在成功上传后，服务会自动把地点追加到：

data/footprints.yaml

然后依次执行：

检查文章是否有未来发布时间
        ↓
Hugo 构建 public/
        ↓
root-only helper 同步 /var/www/blog/
        ↓
线上足迹地图读取新的地点数据

这里没有给上传服务通用的 root 权限。它只能通过 sudoers 调用一个 root-owned helper，而这个 helper 只做一件事：

rsync -a --delete /home/ubuntu/blog-src/public/ /var/www/blog/

上传服务本身不能执行任意 root 命令，也不会自动提交 Git。这样做的代价是发布链路更长，但权限边界更清楚。

过程中踩到的坑

第一个坑是上传按钮看起来没有反应。实际上服务已经返回了 200，只是页面没有弹窗，也没有把结果滚动到视野内。我连续点了几次，结果同一批照片被上传了三遍。

后来我按内容哈希清理了重复文件，并给前端加上了：

上传中状态；
按钮禁用；
120 秒超时；
成功、部分成功、失败弹窗；
自动滚动到 URL 和 YAML 结果。

第二个坑是腾讯位置服务的 WebService 配额。腾讯地图 JavaScript SDK 能正常加载，并不代表同一个 Key 的服务端地址解析额度一定够用。测试“泸沽湖”时，我手动输入地点后直接报错，排查才发现：在腾讯位置服务控制台创建 Key 还不够，还需要给这个 Key 对应的 WebService 能力分配调用额度。没有额度时，接口明确返回每日调用量已达到上限。

这类错误不能被吞掉。现在它会作为某一张图片的地点解析失败返回，其他带 EXIF GPS 或已经解析成功的图片仍然可以继续。等配额恢复，或者调整 Key 的 WebService 配额，手动地点解析就可以继续使用。

第三个坑是“图片上传成功”和“地图出现地点”其实是两个不同的成功标准。前者只说明文件被处理了，后者还要求地点数据成功写入、Hugo 构建成功、静态站点同步成功。现在后台把自动发布失败单独返回并弹窗提示，不再把“图片已写入磁盘”冒充成“地图已经上线”。

最后

这个后台最后没有变成一个很大的系统：没有数据库，没有用户注册，也没有把公开足迹页改成动态服务。

它只是把几个边界清楚的组件串了起来：

手机照片
  ↓
Tailscale 私有入口
  ↓
Basic Auth 后台
  ↓
EXIF / 腾讯地理编码
  ↓
WebP 图片处理
  ↓
footprints.yaml
  ↓
Hugo + root-only 发布 helper
  ↓
公开足迹地图

我现在对这类后台的判断也变得更具体了：真正难的不是加一个上传按钮，而是把“上传成功”“数据正确”“权限合理”“发布完成”这几件事连成一条可以验证的链路。

如果其中任何一步只能靠我凭感觉确认，那它就还没有真正做完。

腾讯地图接入实录：我如何给博客增加足迹功能

Fri, 11 Sep 2026 11:40:00 +0800

最近我给博客增加了一个“足迹”板块。最初的想法很简单：把我拍过的照片放到地图上，让照片和地点对应起来。

以前照片只是文章里的附件，放在某篇文章下面。这样虽然能保存照片，但过一段时间之后，很难快速回忆“这张照片是在什么地方拍的”。所以我想做一个单独的页面，用地图记录地点，再用照片补充记忆。

先把一张照片放到地图上

第一条样例足迹使用的是一张 2017 年在香港大学梅堂拍摄的照片。

这张照片原本带有 EXIF 信息，里面包括拍摄日期、照片方向和 GPS 坐标。我先从原图中读取这些信息，再把它们整理成足迹数据：

locations:
  - id: hku-may-hall
    name: 香港大学 · 梅堂
    date: "2017-01-16"
    lat: 22.282117
    lng: 114.139808
    country: 中国
    province: 香港
    city: 香港
    category: architecture
    category_name: 建筑
    description: 在香港大学梅堂前留下的一张照片。
    cover: /images/footprints/hong-kong-2017-thumb.webp
    photos:
      - src: /images/footprints/hong-kong-2017.webp
        thumb: /images/footprints/hong-kong-2017-thumb.webp
        alt: 2017 年在香港大学梅堂前的留影
        caption: 香港大学 · 梅堂

目前地点数据放在 Hugo 的 data/footprints.yaml 中。这样做的好处是结构清晰，新增地点时只需要增加一段数据，不需要修改页面模板。

页面使用 Hugo 和原生 TypeScript

足迹页面没有引入数据库，也没有使用 React 或 Vue，而是继续沿用博客现有的 Hugo 结构。

主要文件包括：

data/footprints.yaml：地点和照片数据；
layouts/page/footprints.html：生成页面结构；
assets/ts/footprints.ts：处理地图和交互；
assets/scss/footprints.scss：处理样式和响应式布局；
config.toml：配置腾讯地图 Web Key。

Hugo 构建页面时，会把 YAML 数据写进 HTML：

<script type="application/json" data-footprints-data>
  ...
</script>

浏览器加载页面后，TypeScript 再读取这段 JSON，完成搜索、筛选、地图标记和照片浏览。

整体运行逻辑是：

footprints.yaml
        ↓
Hugo 生成静态 HTML
        ↓
页面内嵌地点 JSON
        ↓
TypeScript 读取数据
        ↓
腾讯地图显示坐标
        ↓
用户进行筛选和照片浏览

腾讯位置服务怎么获取

地图部分使用腾讯地图 JavaScript API GL。

申请流程大致是：

注册或登录腾讯位置服务控制台；
进入“应用管理”中的“我的应用”；
创建一个应用；
在应用中添加 Key；
启用 JavaScript API GL；
配置博客域名白名单；
按控制台要求分配调用额度；
将 Key 配置到博客中。

腾讯官方文档说明，Key 用于识别开发者身份，不同产品能力可以单独启用。WebService API 文档

我在 Hugo 页面中这样加载地图 SDK：

{{ with .Site.Params.footprints.tencentMapKey }}
    <script src="https://map.qq.com/api/gljs?v=1.exp&key={{ . | urlquery }}"></script>
{{ end }}

然后在 TypeScript 中初始化地图：

map = new TMap.Map(root.querySelector('[data-map]'), {
    center: new TMap.LatLng(first.lat, first.lng),
    zoom: 12,
    minZoom: 3,
    maxZoom: 18
});

这里需要注意，前端地图使用的 Web Key 会出现在脚本地址里，因此重点不是完全隐藏它，而是配置正确的域名白名单和调用权限。真正的服务端密钥、签名密钥不能写入公开页面。

之前参考的地图示例中还包含本地代理配置，例如：

window._TMapSecurityConfig = {
    serviceHost: 'http://127.0.0.1:...'
};

这种地址只适合本地环境。正式部署后，127.0.0.1 指向的是访问者自己的设备，不能继续使用。线上必须使用真实域名和对应的 Key。

地图上的标记使用照片缩略图

我没有使用普通图钉，而是让每个地点的封面缩略图直接作为地图标记。

locations.forEach((location) => {
    styles[location.id] = new TMap.MarkerStyle({
        width: 52,
        height: 52,
        anchor: { x: 26, y: 52 },
        src: location.cover
    });
});

然后通过 TMap.MultiMarker 批量添加：

markerLayer = new TMap.MultiMarker({
    map,
    styles,
    geometries: []
});

这样用户看到地图时，可以直接通过图片判断这个地点对应的内容。

但这也带来一个性能问题：如果标记直接使用原图，地图初始化时就会加载很多大文件。

所以图片会处理成两种尺寸：

展示图：最长边 2560 像素；
缩略图：最长边 640 像素。

地图标记和地点列表使用缩略图，用户点击照片后，灯箱才加载展示图。

图片处理还解决了方向和隐私问题

手机照片不一定真的按照最终方向存储，有些照片只是依赖 EXIF 信息告诉浏览器如何旋转。

如果直接转换成 WebP，可能出现图片横向或倒置的问题。因此处理图片时，先根据 EXIF 修正方向，再进行压缩。

公开展示版本还会删除 EXIF 和 GPS 信息，避免把不必要的拍摄位置暴露出去。

目前图片处理流程是：

上传原图
  ↓
检查扩展名、MIME 和真实文件签名
  ↓
读取并修正 EXIF 方向
  ↓
生成展示图和缩略图
  ↓
删除公开版本中的 EXIF/GPS
  ↓
写入静态图片目录

文件名也不会继续使用用户原始文件名，而是由服务端生成随机 ID，避免重名和覆盖已有文件。

搜索、筛选和地图联动

页面目前支持：

地点名称搜索；
城市筛选；
年份筛选；
场景类型筛选；
地图和照片视图切换；
点击地点卡片定位地图；
点击照片打开大图；
在灯箱中切换上一张和下一张照片。

筛选时，TypeScript 会对本地地点数组进行过滤：

const filtered = locations.filter((location) =>
    matchesFilters(location) && inMapBounds(location)
);

过滤结果会同时更新地点列表和地图标记。

点击地点卡片时，地图会移动到对应坐标：

map.easeTo({
    center: new TMap.LatLng(location.lat, location.lng),
    zoom: 16,
    duration: 600
});

照片浏览部分没有引入第三方轮播库，因为需求并不复杂。记录当前照片数组和索引，再根据索引更新灯箱中的图片即可。

过程中遇到的问题

第一个问题是图片不能直接使用原图。原图太大，不适合作为地图标记，也会影响首屏加载，所以必须生成缩略图。

第二个问题是本地地图配置不能直接部署到线上。本地代理地址和正式域名的加载方式不同，必须重新申请 Key，并配置域名白名单。

第三个问题是地点和照片之间的关系需要提前设计。如果只保存图片地址，后面还要补地点、日期、分类和说明。因此我最后把地点作为一级数据，照片作为地点下面的数组。

第四个问题是部署后的资源缓存。足迹页面同时包含 Hugo 模板、SCSS、TypeScript、地图 SDK 和图片。不能只看本地构建成功，还要检查线上页面是否引用了最新的 CSS、JS 哈希，以及图片地址是否能够正常访问。

目前照片先通过服务器后台上传一张 Demo 图片，生成展示图和缩略图，再把返回的 YAML 手动写入足迹数据。后面我准备做一个管理后台，让我可以直接用手机上传照片，具体实现放到下一篇。

SQLite 会不会更好

这取决于足迹模块之后会不会变成一个需要频繁维护的内容系统。

以目前的规模来看，YAML 反而更合适：

地点数量少；
数据结构简单；
内容主要由自己维护；
Hugo 可以直接生成静态页面；
不需要运行数据库；
Git 可以直接记录每次数据变化。

如果现在直接引入 SQLite，就需要额外处理数据库备份、权限、接口、部署和数据同步，复杂度会增加。

但如果下一步要做手机管理后台，SQLite 就会变得很有价值。它适合这种单用户、小规模、低并发的管理系统。

比较合理的结构是：

手机管理后台
        ↓
Python API
        ↓
SQLite 保存地点和照片元数据
        ↓
图片文件保存到静态目录
        ↓
公开足迹页读取数据

SQLite 中只保存元数据，不建议把图片本身塞进数据库：

locations
- id
- name
- date
- lat
- lng
- city
- category
- description

photos
- id
- location_id
- src
- thumb
- caption
- sort_order

图片依然保存为 WebP 文件，数据库只保存图片路径、所属地点和排序信息。

我的建议是：当前阶段继续使用 YAML，把公开页先做稳定；管理后台第一版也可以继续生成 YAML。等以后需要手机新增地点、修改坐标、调整照片顺序、删除照片，再把 SQLite 作为后台的数据源。

SQLite 不是现在一定更好，而是当管理需求增加后会更合适。对于目前这个只有少量地点的个人足迹页，YAML 更简单；对于下一阶段的手机管理后台，SQLite 会是一个不错的选择。