鉴权与加密图（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 分钟内测

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 常见错误

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：

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

SDK Node：

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

2.4 加密图典型流程

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）。