Phase 0-2: Schema cleanup, typed relations, event-driven automation

- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
@@ -0,0 +1,264 @@
+---
+title: Obsidian Maps 瓦片代理总结与使用指南
+type: reference
+created: 2026-04-10
+tags:
+  - tools/obsidian
+  - tools/map
+  - project/完成
+  - type/指南
+para:
+  - resources
+source: "[[Obsidian Maps瓦片代理总结与使用指南]]"
+description: "本地瓦片代理方案总结：解决 Obsidian Maps 无法直接加载腾讯/高德瓦片的问题"
+---
+
+# Obsidian Maps 瓦片代理总结与使用指南
+
+> [!abstract] 一句话总结
+> 通过本地 Node.js 代理（端口 18090），透明解决腾讯地图 Y 轴翻转 + MapLibre `{-y}` 不支持查询参数的问题，让 Obsidian Maps 可以加载腾讯矢量、高德卫星、ESRI 卫星、腾讯路况四种瓦片。
+
+---
+
+## 一、问题背景
+
+Obsidian Maps（官方插件 v0.1.6）使用 MapLibre GL 渲染地图，支持自定义瓦片 URL。但在国内使用时遇到三个核心问题：
+
+| # | 问题 | 原因 |
+|---|------|------|
+| 1 | 腾讯矢量瓦片加载后地图空白 | 腾讯 Y 轴编号与标准 TMS 相反（从上往下 vs 从下往上） |
+| 2 | MapLibre `{-y}` 翻转不生效 | MapLibre 的 `{-y}` 只支持**路径格式**（`/{z}/{x}/{y}.png`），不支持**查询参数格式**（`?z=&x=&y=`） |
+| 3 | 腾讯卫星底图不可用 | 腾讯 `/sateTiles` 接口已下线，`styleid=0` 返回的仍是矢量图 |
+
+> [!failure] 直接配置腾讯 URL 的结果
+> `http://rt0.map.gtimg.com/tile?z={z}&x={x}&y={-y}&styleid=1`
+> → MapLibre 不会把 `{-y}` 替换为翻转坐标，而是发送字面量 `{-y}`，服务器返回 400 Bad Request。
+
+---
+
+## 二、解决方案：本地瓦片代理
+
+### 架构
+
+```
+Obsidian Maps (MapLibre)          本地代理 (Node.js)           瓦片服务器
+        |                              |                           |
+        | GET /tile?z=13&x=6745       |                           |
+        | &y=3124&type=vector          |                           |
+        | ──────────────────────────> |                           |
+        |                              | Y翻转: 3124 → 5067        |
+        |                              | GET rt0.../tile?          |
+        |                              | z=13&x=6745&y=5067        |
+        |                              | &styleid=1                |
+        |                              | ────────────────────────> |
+        |                              |      200 + JPEG 7KB       |
+        |                              | <──────────────────────── |
+        |      200 + JPEG 7KB          |                           |
+        | <────────────────────────── |                           |
+```
+
+### Y 轴翻转公式
+
+$$y_{腾讯} = 2^z - 1 - y_{TMS}$$
+
+| TMS y | z=13 翻换后 | 说明 |
+|-------|------------|------|
+| 0 | 8191 | 最北行 |
+| 3124 | 5067 | 故宫附近 |
+| 8191 | 0 | 最南行 |
+
+### 代理代码位置
+
+- **代理脚本**：`tools/tile-proxy.js`
+- **调试工具**：`tools/map-tile-debugger.html`
+- **静默启动**：`tools/tile-proxy-silent.vbs`
+- **开机自启安装**：`tools/install-proxy-startup.ps1`
+
+---
+
+## 三、可用瓦片源
+
+| type 参数 | 名称 | 上游服务器 | Y轴翻转 | 缓存 | 单瓦片大小 |
+|-----------|------|-----------|---------|------|-----------|
+| `vector` | 腾讯矢量 | rt0/1/2.map.gtimg.com | ✅ 是 | 24h | ~7KB |
+| `sate` | 高德卫星影像 | wprd01/02.is.autonavi.com | ❌ 否 | 24h | ~11KB |
+| `esri` | ESRI World Imagery | server.arcgisonline.com | ❌ 否 | 24h | ~20KB |
+| `traffic` | 腾讯路况 | rt0.map.gtimg.com | ✅ 是 | 24h | ~5KB |
+
+### URL 格式
+
+```
+http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=<类型>
+```
+
+### 卫星源说明
+
+> [!warning] 腾讯卫星不可用
+> 腾讯 `/sateTiles` 接口已下线，`styleid=0` 返回的仍是矢量渲染图。替代方案：
+> - **高德卫星**（`type=sate`）：中国区域优化，加载快，标注清晰
+> - **ESRI World Imagery**（`type=esri`）：全球覆盖，分辨率高，文件稍大
+
+---
+
+## 四、Obsidian Maps 配置
+
+### 配置文件
+
+`.obsidian/plugins/maps/data.json`
+
+```json
+{
+  "tileSets": [
+    {
+      "id": "tencent-vector",
+      "name": "腾讯矢量",
+      "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=vector",
+      "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=vector"
+    },
+    {
+      "id": "gaode-satellite",
+      "name": "高德卫星影像",
+      "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=sate",
+      "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=sate"
+    },
+    {
+      "id": "esri-imagery",
+      "name": "ESRI World Imagery",
+      "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=esri",
+      "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=esri"
+    },
+    {
+      "id": "tencent-traffic",
+      "name": "腾讯路况",
+      "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=traffic",
+      "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=traffic"
+    },
+    {
+      "id": "openfreemap-bright",
+      "name": "OpenFreeMap 亮色",
+      "lightTiles": "https://tiles.openfreemap.org/styles/bright",
+      "darkTiles": "https://tiles.openfreemap.org/styles/dark"
+    }
+  ]
+}
+```
+
+### tileSet 结构说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 唯一标识符 |
+| `name` | string | 显示名称（在 Maps 背景选择器中可见） |
+| `lightTiles` | string | 亮色模式瓦片 URL（支持逗号分隔多个） |
+| `darkTiles` | string | 暗色模式瓦片 URL（为空时回退到 lightTiles） |
+
+> [!tip] Maps 插件识别逻辑
+> `isTileTemplateUrl()` 检查 URL 是否包含 `{z}`、`{x}` 或 `{y}`。
+> - **包含** → 当作 raster 瓦片模板，MapLibre 自动替换坐标
+> - **不包含** → 当作 Style JSON URL，直接 fetch 获取完整样式定义
+> 查询参数格式 `?z={z}&x={x}&y={y}` 完全支持。
+
+---
+
+## 五、日常使用指南
+
+### 启动代理
+
+代理已配置为**开机自启**（Windows 启动目录快捷方式 → VBS 静默脚本）。
+
+手动操作：
+
+```powershell
+# 检查代理是否运行
+curl http://127.0.0.1:18090/status
+
+# 手动启动（前台调试）
+node D:\TC_UP\2023card\tools\tile-proxy.js 18090
+
+# 手动启动（后台静默）
+Start-Process node -ArgumentList "D:\TC_UP\2023card\tools\tile-proxy.js","18090" -WindowStyle Hidden
+```
+
+### 在 Obsidian 中使用地图
+
+1. 打开或创建一个 `.base` 文件
+2. 添加 Map 视图（视图类型选 "Map"）
+3. 确保笔记有 `location` 属性（经纬度，如 `location: [39.9042, 116.4074]`）
+4. 在地图左上角切换背景图层
+
+### 调试工具
+
+浏览器打开 `tools/map-tile-debugger.html`，可逐一测试各瓦片源是否正常加载。
+
+### 代理状态检查
+
+```powershell
+# 状态端点
+curl http://127.0.0.1:18090/status
+# 返回: {"status":"ok","sources":["vector","traffic","gaode_sate","esri","sate"],"port":18090}
+
+# 测试单个瓦片
+curl -o test.jpg http://127.0.0.1:18090/tile?z=14&x=13509&y=6218&type=vector
+```
+
+---
+
+## 六、排障指南
+
+| 症状 | 可能原因 | 解决方法 |
+|------|---------|---------|
+| 地图全空白 | 代理未启动 | `curl http://127.0.0.1:18090/status` 检查 |
+| 腾讯矢量偏移到海洋 | Y 轴未翻转 | 确认用的是代理 URL（`127.0.0.1:18090`）而非直连 |
+| 卫星图显示矢量 | 用了腾讯 styleid=0 | 改用 `type=sate`（高德卫星）或 `type=esri` |
+| ESRI 返回 500 | ESRI URL 顺序错误 | ESRI 用 `/{z}/{y}/{x}`，不是 `/{z}/{x}/{y}` |
+| 瓦片加载慢 | 网络问题 | 代理有 8s 超时，多后端自动轮询 |
+| 插件设置里看不到背景 | data.json 未生效 | 重载插件：设置 → 关闭 Maps → 重新开启 |
+
+---
+
+## 七、技术细节
+
+### 瓦片源上游 URL
+
+| 类型 | 上游 URL 格式 | 备注 |
+|------|-------------|------|
+| 腾讯矢量 | `http://rt{0-2}.map.gtimg.com/tile?z={z}&x={x}&y={flippedY}&styleid=1&scene=0` | Y需翻转 |
+| 高德卫星 | `https://wprd{01-02}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&style=6&x={x}&y={y}&z={z}` | 标准TMS |
+| ESRI 卫星 | `https://server.arcgisonline.com/…/World_Imagery/MapServer/tile/{z}/{y}/{x}` | z/y/x顺序 |
+| 腾讯路况 | `http://rt0.map.gtimg.com/tile?z={z}&x={x}&y={flippedY}&styleid=4` | Y需翻转 |
+
+### 腾讯 styleid 含义
+
+| styleid | 内容 | 用途 |
+|---------|------|------|
+| 1 | 矢量底图 | ✅ 日常使用 |
+| 2 | 深色底图 | 暗色模式 |
+| 3 | 标注层 | 叠加用 |
+| 4 | 路况 | 实时路况 |
+| 6/7 | 其他渲染风格 | 不常用 |
+
+### 代理功能
+
+- **多后端轮询**：腾讯 rt0/1/2 自动轮询，分散请求
+- **自动降级**：首选后端失败时自动尝试下一个
+- **CORS 支持**：`Access-Control-Allow-Origin: *`
+- **缓存头**：`Cache-Control: public, max-age=86400`（24小时）
+- **图片验证**：检查返回数据是否以 JPEG/PNG 魔数开头
+
+---
+
+## 八、文件清单
+
+| 文件 | 位置 | 用途 |
+|------|------|------|
+| 瓦片代理 | `tools/tile-proxy.js` | 核心代理服务 |
+| 调试工具 | `tools/map-tile-debugger.html` | 浏览器内瓦片测试 |
+| 静默启动 | `tools/tile-proxy-silent.vbs` | 无窗口启动代理 |
+| 自启安装 | `tools/install-proxy-startup.ps1` | 创建开机自启快捷方式 |
+| 插件配置 | `.obsidian/plugins/maps/data.json` | Maps 插件瓦片背景配置 |
+
+---
+
+> [!quote] 项目时间线
+> - **2026-04-10**：从问题发现 → 代理开发 → 配置完成，耗时约3小时
+> - 核心发现：MapLibre `{-y}` 不支持查询参数格式，这是整个问题的根源