---
title: 鉴权与加密图（Authentication）
source: https://vjmap.com/guide/service/03-authentication.html
---

# 鉴权与加密图（Authentication）

## 1. JWT Token

- vjmap 后端用 **标准 HS256 JWT** 做鉴权
- Claims 里包含 `ID` / `Username` / `AuthorityId` / `BufferTime` / `exp` / `iss=vjmap`
- 过期时间：默认 `BufferTime=86400 秒`；`exp` 远期刷新由 `{UpdateTokenRoute}` 负责
- 生产环境拿 token 的方式：通过业务登录接口；开发环境可直接从 vjmap 后台复制

### 1.1 Token 放哪里

三种都接受，**优先级从高到低**：

1. HTTP Header：`token: eyJ...`
2. Query：`?token=eyJ...`
3. Form：`token=eyJ...`（仅个别接口）

SDK 默认走 **Query**（便于 curl 排障）；如果你的反代会剥 query，可传 `header=True`（Python）/`{headers:{token}}` 客户端自行覆盖。

### 1.2 Token 的 5 分钟内测

```bash
TOKEN="eyJhbG..."
curl -s "http://127.0.0.1:27660/version?token=$TOKEN"
curl -s "http://127.0.0.1:27660/api/v1/map/cmd/runstatus/_/v1?token=$TOKEN&detail=true"
```

### 1.3 常见错误

| 现象 | 原因 |
|------|------|
| `HTTP 401` | token 过期 / 签名不匹配 |
| `{code: 10006, msg: "..."}`（网关响应） | token 合法但权限不够（例如不是 root）|
| `HTTP 200` 但业务字段异常 | token OK，但参数错误 |

## 2. 加密图（secretKey / accessKey）

vjmap 允许对图设置访问密钥，打开/瓦片/元数据请求都要带。

### 2.1 secretKey（每图一把，16 字符）

- 创建/上传图时可通过 `secretKey` 字段设置
- 明文密码 → `secretKey` 算法（与 Service.ts `pwdToSecretKey` 一致）：
  - 连续 4 次 md5 后取前 16 字符
  - 空串 → 空串
  - 长度 == 18 且以 `ak` 开头 → 视为 accessKey，原样返回
- SDK：`compute_secret_key(pwd)` / `computeSecretKey(pwd)`

### 2.2 accessKey（全局，18 字符 `ak...`）

- 跨图通用的"超级密钥"，典型用途：服务端代为访问所有图
- 放在请求头/query 里的字段也叫 `secretKey`，但值是 18 位 ak 串
- SDK 识别：如果密钥串长度 == 18 且前缀 `ak`，不再 md5 拼装，直接透传

### 2.3 多密钥传递

一个请求可能同时携带多个 secretKey（覆盖多张图）：

- Header: `secretKey: key1_;_key2_;_ak1234...abcd`
- Query: 用多个 `secret_key=` 或一个 `secret_key=key1_;_key2`

SDK Python：

```python
svc._secret_keys = ["<16chars>", "<16chars>", "ak........"]
# 后续请求会自动拼 header
```

SDK Node：

```javascript
svc._secretKeys = [ '16chars...', 'ak........' ];
```

### 2.4 加密图典型流程

```python
svc = Vjmap(base, token)
svc._secret_keys = [compute_secret_key("myPass123")]
svc.open_map(mapid="finance_map", version="v1", mapopenway="GeomRender",
             secretKey="myPass123")   # 打开时也可带明文
meta = svc.metadata()                  # 会自动 carry secretKey
```

## 3. Super Key（运维视角）

`.env` 里的 `VJMAP_MAP_SUPER_KEY` 本质是一把 **accessKey**，含义是：

- 整个实例的所有加密图都接受它
- 二次开发一般不需要它；**只有**测试框架需要跑加密场景时才用

## 4. CSRF / 同源

- 后端不强制 CSRF token；依赖 JWT 签名
- 浏览器侧调用请注意 CORS：网关默认允许 `Origin: *`；如果在受限部署里碰到 CORS，需要运维修改 `ReqMiddlewareCors`

## 5. 速率限制

- **默认无全局速率限制**
- 单个 cmd 的并发由 `runstatus.maxParallelProcessGeomNum`（几何渲染）控制，典型值 2-4
- 超并发请求会被排队，不会报错但会"看起来卡住"

## 6. 过期 Token 的自动刷新

网关里有一个 `{UpdateTokenRoute}`（常见为 `/api/v1/map/updateToken`）。