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