# 云游荔波：高德地图 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，并分别配置允许域名和调用额度。