From 43b375f9ac611ce3101c47e5310b83b8c3a99c12 Mon Sep 17 00:00:00 2001
From: 3452078359-xuexue <3452078359@qq.com>
Date: Thu, 30 Jul 2026 10:20:13 +0800
Subject: [PATCH] docs: add AMap setup guide for teammates

---
 README.md                   |   5 +-
 docs/高德地图API配置说明.md | 110 ++++++++++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+), 2 deletions(-)
 create mode 100644 docs/高德地图API配置说明.md

diff --git a/README.md b/README.md
index 7bd5412..763ce75 100644
--- a/README.md
+++ b/README.md
@@ -37,8 +37,8 @@ flowchart LR
 需要先安装并启动 Docker Desktop。
 
 ```bash
-git clone https://github.com/3452078359-xuexue/travel-knowledge-graph.git
-cd travel-knowledge-graph
+git clone https://git.nianxx.cn/xuelong/Cloud-Tour-to-Libo.git
+cd Cloud-Tour-to-Libo
 docker compose up -d --build
 ```
 
@@ -133,6 +133,7 @@ docker compose exec falkordb redis-cli -p 6379 GRAPH.LIST
 | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Docker 部署、端口、环境变量和常见问题 |
 | [docs/DATA_SNAPSHOTS.md](docs/DATA_SNAPSHOTS.md) | 数据快照、恢复、重导出和校验 |
 | [docs/API_REFERENCE.md](docs/API_REFERENCE.md) | API 分组、常用接口和调用示例 |
+| [docs/高德地图API配置说明.md](docs/高德地图API配置说明.md) | 同事下载后配置高德地图 Key、启动验证和常见问题 |
 | [docs/MAINTENANCE.md](docs/MAINTENANCE.md) | 维护流程、发布检查和仓库边界 |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发参与和提交规范 |
 | [SECURITY.md](SECURITY.md) | 演示账号、密钥和生产安全建议 |
diff --git a/docs/高德地图API配置说明.md b/docs/高德地图API配置说明.md
new file mode 100644
index 0000000..f054716
--- /dev/null
+++ b/docs/高德地图API配置说明.md
@@ -0,0 +1,110 @@
+# 云游荔波：高德地图 API 配置说明
+
+本文供项目同事在下载“云游荔波”代码后配置高德地图使用。仓库不会保存真实 Key，请由项目负责人通过私密渠道单独提供。
+
+## 1. 地图展示需要的配置
+
+`http://localhost:8102/admin/plaza/overview` 中的荔波地图使用高德 Web 端（JS API）Key，需要同时配置：
+
+```dotenv
+AMAP_JS_KEY=你的高德Web端JS_API_Key
+AMAP_SECURITY_JSCODE=该Key对应的安全密钥
+```
+
+两个值必须来自同一个高德 Web 端（JS API）应用。只填写其中一个、Key 类型错误或安全密钥不匹配，地图都会加载失败。
+
+项目还保留了下面这个配置：
+
+```dotenv
+AMAP_WEB_KEY=你的高德Web服务_Key
+```
+
+`AMAP_WEB_KEY` 用于服务端 POI 搜索、行政区查询和路径规划等采集任务，不是打开现有地图页面的必需项。只需要查看荔波地图时可以暂时留空。
+
+## 2. 同事下载后的配置步骤
+
+```bash
+git clone https://git.nianxx.cn/xuelong/Cloud-Tour-to-Libo.git
+cd Cloud-Tour-to-Libo
+cp .env.example .env
+```
+
+打开项目根目录下的 `.env`，填写：
+
+```dotenv
+AMAP_JS_KEY=
+AMAP_SECURITY_JSCODE=
+```
+
+然后启动项目：
+
+```bash
+docker compose up -d --build
+```
+
+如果项目已经启动，只修改了高德配置，可重新创建 API 容器：
+
+```bash
+docker compose up -d --force-recreate api
+```
+
+打开：
+
+```text
+http://localhost:8102/admin/plaza/overview
+```
+
+进入“云游荔波”项目后，应能看到荔波县底图、POI 点位、公交路线和详情侧栏。
+
+## 3. 高德控制台要求
+
+在高德开放平台创建 Key 时应选择 Web 端（JS API），并取得该 Key 对应的安全密钥。若配置了域名白名单，请至少允许实际访问系统使用的域名；本地开发通常需要包含：
+
+```text
+localhost
+127.0.0.1
+```
+
+如果同事使用局域网 IP、测试域名或线上域名访问，还需要把对应域名加入高德控制台允许范围。
+
+## 4. 常见问题
+
+### 页面显示“高德 JS API Key 未配置”
+
+检查 `.env` 是否位于项目根目录，并确认变量名完全一致：
+
+```dotenv
+AMAP_JS_KEY=
+AMAP_SECURITY_JSCODE=
+```
+
+修改后重新创建 `api` 容器。
+
+### 页面有地图容器，但底图为空
+
+依次检查：
+
+1. Key 是否为 Web 端（JS API）类型。
+2. `AMAP_SECURITY_JSCODE` 是否与当前 Key 配套。
+3. 高德控制台域名白名单是否包含当前访问域名。
+4. 浏览器是否能访问 `https://webapi.amap.com`。
+5. 浏览器开发者工具中是否出现 `INVALID_USER_KEY`、安全密钥错误或域名未授权提示。
+
+### 地图能显示，但服务端采集不能运行
+
+地图展示和服务端采集使用不同类型的 Key。服务端采集还需填写：
+
+```dotenv
+AMAP_WEB_KEY=
+```
+
+并确认该 Key 已开通相应的 Web 服务 API 配额。
+
+## 5. 密钥安全
+
+- 不要把真实 Key 写入本文件、`.env.example`、聊天截图或提交记录。
+- `.env` 已被 Git 忽略，只保留在使用者本机。
+- 同事所需真实值应通过密码管理器或其他私密渠道传递。
+- 如 Key 曾经被提交到仓库或公开发送，应立即在高德控制台更换。
+- 正式环境建议为开发、测试、生产分别创建 Key，并分别配置允许域名和调用额度。
+