---
title: 概述（Overview）
source: https://vjmap.com/guide/service/00-overview.html
---

# 概述（Overview）

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

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

![image-20260425205121562](https://vjmap.com/blogimages/202604252051713.png)

## 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      ┌──────────────────────┐   stdin/stdout   ┌──────────────────────────┐
│ 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 鉴权、路由转发、缓存清理、工作区路由改写。
- **图形服务 **：实际的 CAD 解析/渲染/分析。
- **数据存储**：每张图对应一个 数据库文件（默认 `data/maps/{hash}.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-and-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-and-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`](01-getting-started.md) 把 Python 或 Node SDK 跑起来。
2. **看得懂 curl 就够**：直接翻 `api/01-map-management.md`，里面每个接口都有 `curl` + Python + Node 三列。

## 5. 命名与术语

| 术语 | 含义 |
|------|------|
| `mapid` | 图唯一 ID；通常是业务名或 `_` 占位 |
| `version` | 图版本号；默认 `v1` |
| `layer` | 图层名；多数 cmd 通过请求体 `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`](02-conventions.md)