唯杰地图 logo唯杰地图
VJMAP
EN

概述（Overview）

vjmap-service/references/overview.md 6.2 KB95 行
原文

vjmap 后端 REST 接口文档 — 面向二次开发者的版本（vjmapservice/）。

后端SDK下载 python、nodejs、swagger服务。下载地址：http://vjmap.com/download/vjmapservice.zip

image-20260425205121562

1. 产品定位

vjmap 是一套以 CAD/GIS 图档为中心的服务端系统，核心能力包括：

  • 上传 DWG / DXF / 图片等源文件，在服务端解析成数据库
  • 以栅格瓦片或 MVT 矢量瓦片的形式提供 Web 地图访问
  • 基于 cmd 指令完成元数据查询、样式切换、几何分析、表格/中心线提取、文件导出等
  • 存储用户 KV 数据、工作区、符号库、全文索引等辅助能力
  • 支持 Python / Node.js SDK 直接对接；

典型使用场景：

  • 将单位内部 DWG 档案转成 Web 可浏览地图
  • 需要把 CAD 图与 WMS / MVT 图层混合使用
  • 针对 DWG 做图形分析（比较、表格提取、中心线）并导出 PDF / DXF
  • 在业务系统里存储轻量 KV 配置或自定义属性

2. 系统架构

┌────────────────┐   JWT      ┌──────────────────────┐ HTTP 反向代理    ┌──────────────────────────┐
│ Client (Web/   │ ─────────► │ web服务       │ ───────────────► │ 图形引擎服务     │
│ Python / Node) │            │ :27660               │                  │ geom / render / export    │
└────────────────┘ ◄───────── │ router + handler  │ ◄─────────────── │ appCmd / mapPsCmd / ...   │
        ▲                     │ + 缓存 / 限流 / 权限 │                  │  持久化        │
        │ REST / HTTP         └──────────────────────┘                  └──────────────────────────┘
        │                              │
        │                              ├── Workspace（多租户命名空间）
        │                              ├── Full-text search
        │                              ├── 符号库
        │                              └── AI / 向量检索（可选）
        │
        └── Tile 通过 CDN / HTTP 缓存直接给前端
  • web服务：入口；做 JWT 鉴权、路由转发、缓存清理、工作区路由改写。/api/v1/map/* 由 Go 网关 HTTP 反向代理到图形服务进程的本机端口（http://localhost:<ProxyPort>；命名工作区各有自己的进程与端口），不是 stdin/stdout 管道。
  • **图形服务 **：实际的 CAD 解析/渲染/分析。
  • 数据存储：默认工作区根为 {appdir}/data（命名工作区为 data/workspace/{workDir}，workDir 为空时与 name 一致），其下 mapinfos/{mapid}.ini 按版本记录 db/filename/grouplayers 等键，mapfiles/ 存源文件、rastertiles/+vectortiles/ 存瓦片缓存；每张图各版本对应一个 .db 数据库文件（元数据、样式、缓存瓦片都在里面）；另有全局 KV、工作区、符号库等独立存储。
  • 可选 AI服务：/ai/*、/aimcp/*、/aiagent/* 三套子服务通过反代挂载；不是所有部署都启用。

3. 常用接口分 13 大类

# 分类 典型接口 文档
1 地图管理 upload / openmap / metadata / listmaps / thumbnail api/01-map-management.md
2 瓦片/样式 tile / mvt / wms / createMapStyle / switchlayer api/02-tiles-styles.md
3 要素查询 queryFeatures / createEntityGeoData api/03-query.md
4 图形分析 mapDiff / mapCompare / extractTable / centerLines api/04-analysis.md
5 组合/导出 composeNewMap / exportPdf / exportDxf api/05-compose-export.md
6 WebCAD listWebcadDraws / saveWebcadPatch（可选） api/06-webcad.md
7 工作区 getWorkspace / workspaceCreate api/07-workspace.md
8 KV 存储 data/{key} / datas / datakeys api/08-data-storage.md
9 全文搜索 fullsearch/search / add / delete api/09-fullsearch.md
10 符号库 symbol/categories / symbol/list api/10-symbols.md
11 系统 heart / version / runstatus / viewlogs api/11-system.md
12 /service 杂项 qrcode / fonts / uploadImg api/12-service-misc.md
13 AI（可选） vectorSearch / chatFaq / vectorDocs api/13-ai.md

4. 该怎么读这份文档？

按兴趣从下面挑一条路径：

  1. 第一次接触 vjmap：先过 01-getting-started.md 把 Python 或 Node SDK 跑起来。
  2. 看得懂 curl 就够：直接翻 api/01-map-management.md，里面每个接口都有 curl + Python + Node 三列。

5. 命名与术语

术语 含义
mapid 图唯一 ID；通常是业务名或 _ 占位
version 图版本号；默认 v1
layer/layers 图层/样式名；不同 cmd 键名不同——switchlayer 用 visibleLayer（数组），createMapStyle/updateStyle 用 layeron/layeroff，slicelayer 用 layer，wms/瓦片路径用 layers（逗号分隔）
fileid 源文件 ID，一般等于 md5 前缀
secretKey / accessKey 加密图的访问密钥（前者 16 字符，后者 ak 开头 18 字符）
workspace 命名工作区；默认工作区等价于 ""（空）
geom render 图形服务子进程，负责几何渲染/切片

6. 约定（Conventions）速览

  • 所有 /api/v1/map/... 接口需要 token=<JWT>（query 或 header）
  • 95 % 的 cmd 接口既接受 GET 也接受 POST；SDK 统一走 POST
  • 成功响应结构两类：
    • 网关包装 {code:0, msg:"", data:{...}}
    • 图形服务 JSON（直接是 {...} 或数组）；SDK 自动识别并 unwrap
  • 错误：HTTP 非 2xx → 抛 VjmapError；网关 {code≠0} 也视为错误抛出
  • 详细规则见 02-conventions.md