@xcsmartdatabase/core

v0.0.13

Published

3 days ago

XcSmartDatabase Core

0High
0Medium
0Low

XcSmartDatabase

该项目是一个名为 @xcsmartdatabase/xcsmartdatabase 的地图引擎/地理信息系统（GIS）框架，采用 TypeScript 开发。它不仅包含前端地图渲染核心，还集成了丰富的命令行工具（CLI）、后端服务以及 Docker 部署配置。

核心结构分析

src/ (核心源码)
- 地图引擎核心: src/map/ 包含地图主类 (map.ts)、场景管理 (scene.ts) 和 UI 组件。
- 渲染引擎: src/render/ 包含 WebGL 渲染实现，负责高性能地图绘制。
- 数据源管理: src/source/ 是最庞大的模块之一，支持 OGC 标准、矢量瓦片、栅格瓦片、S57 海图、数据库连接等多种数据来源。
- 基础模块: 包含坐标系转换 (crs/)、几何计算 (geometry/)、格式解析 (format/)、算法 (algorithm/) 和工具类 (util/)。
- 多端支持: src/index.ts (浏览器), src/node.ts (Node.js), src/webworker.ts (Web Worker) 表明该引擎可运行在多种环境。
cli/ (工具链)
- 提供了极其丰富的地理数据处理脚本，包括：
  - 瓦片处理: 瓦片爬取 (tilecrawling.js)、合并 (tilecombine.js)、校验、裁剪等。
  - 格式转换: GeoPDF 转 GeoTIFF、OSM 导入 PostGIS、S52/S57 海图处理。
  - 网格系统: 支持北斗网格、GeoSOT 等多种网格划分。
  - QGIS 集成: 与 QGIS 样式和数据转换相关的工具。

CLI 工具

XcSmartDatabase 提供了一个统一的 CLI 工具，用于访问各种地理空间处理脚本。

安装

npm install -g @xcsmartdatabase/xcsmartdatabase

使用方法

xcsmartdatabase-cli <command> [options]

有关可用命令的完整列表，请参阅 CLI README。

示例

# 查看所有可用命令
xcsmartdatabase-cli --help

# 运行瓦片合并命令
xcsmartdatabase-cli tile-combine --input input_dir --output output_dir

# 运行 OSM 到 PostGIS 导入命令
xcsmartdatabase-cli osm-to-postgis --host localhost --database gis --file data.osm

service/ & docker/ (后端与部署)
- service/: 包含 server (后端 API) 和 website (前端展示/文档) 的实现。
- docker/: 提供了完整的容器化方案，支持不同操作系统环境（CentOS, Kylin 等）的部署配置。
- prisma/: 使用 Prisma 作为 ORM 框架，管理数据库 Schema。
rollup/ (构建配置)
- 针对不同环境（Web, Node.js, Worker, Auth, MapGIS）定义了多套 Rollup 打包策略，支持 CJS 和 UMD 格式。

技术栈总结

语言: TypeScript
渲染: WebGL, Canvas
后端: Node.js (Express), Prisma (PostgreSQL/SQLite)
构建: Rollup, Webpack (via react-app-rewired)
地理库: 依赖了 d3, gl-matrix, ogr2ogr, wkx 等。

总结

这是一个功能完备的地图平台，涵盖了从底层渲染、数据转换工具到后端服务及自动化部署的全生命周期。其特点是高度的工具化（大量的 CLI 脚本）和广泛的数据兼容性。

基于对代码结构、构建配置、核心逻辑以及 CLI 工具的深入分析，该项目虽然功能非常全面，但在工程化、性能和代码质量方面存在以下优化空间：

OpenCode Server

opencode serve --port 4096 --hostname 192.168.1.16 --mdns false --cors ["*"]

本地双仓开发

当前推荐的本地开发模式是不直接启动 xcsmartdatabase 自己的服务端，而是配合 opencode 仓库的开发服务：

启动顺序

启动本地 PostgreSQL 和 Martin（例如 xcsmartdatabase-postgres、xcsmartdatabase-martin）
在 opencode 仓库启动 OpenCode 开发服务：

cd /home/maptex/Code/xcsmartdatabase/opencode
npm run dev:server

在 xcsmartdatabase-skill-website 仓库启动前后端开发服务：

cd /home/maptex/Code/xcsmartdatabase/xcsmartdatabase-skill-website
npm run dev

环境约定

opencode npm run dev:server 默认监听 http://127.0.0.1:14097
xcsmartdatabase-skill-website/.env 中的 VITE_AI_URL 应指向 http://127.0.0.1:14097
xcsmartdatabase 的技能/CLI 本地开发默认优先读取 .env.development
xcsmartdatabase 的 Docker/容器环境默认优先读取 .env.docker

技能目录

运行中的 OpenCode 会从以下路径加载 XcSmartDatabase 技能：

/home/maptex/Code/xcsmartdatabase/xcsmartdatabase/.claude/skills

因此即使不启动 xcsmartdatabase 服务端，只要 opencode 开发服务正常运行，网站中的 slash command / skill chain 仍然会调用这里的技能实现。

1. 工程化与构建优化

Monorepo 架构迁移: 目前 src (核心库), cli (工具链), service (后端/网站) 全部混在一个根目录下。建议使用 pnpm workspaces 或 Lerna 将其拆分为多个子包（如 @xcsmartdatabase/core, @xcsmartdatabase/cli, @xcsmartdatabase/server），实现更好的模块解耦和依赖管理。
构建工具升级: rollup.config-web.ts 中存在大量重复的配置块。可以提取公共配置，并考虑引入 Vite 或 esbuild 来加速开发环境的构建。
依赖精简: package.json 中同时存在 react-scripts 和 rollup，且依赖项非常杂乱（如 openai, prisma, mapbox-gl, canvas 等全部混在一起）。拆分包后可以按需声明依赖，减小最终产物的体积。

2. 代码质量与规范

TypeScript 严格模式增强: 虽然开启了 strict: true，但代码中仍存在不少 @ts-ignore（如 map.ts 中的 logo 处理逻辑）。应尽量通过类型定义解决，而非忽略。
ESLint 覆盖范围: 目前的 eslint.config.js 仅针对 .js, .jsx 文件，未包含 .ts, .tsx。需要配置 @typescript-eslint/parser 以覆盖核心源码。
统一模块规范: 项目中混合了 CommonJS 和 ESM，建议全面转向 ESM，并利用 exports 字段在 package.json 中定义清晰的入口。

3. 核心逻辑与性能优化

渲染循环优化: map.ts 中的 throttle 实现较为简单。对于地图这种高频更新的应用，建议使用 requestAnimationFrame (rAF) 来管理渲染帧，确保与显示器刷新率同步，避免不必要的计算。
Web Worker 的深度利用: 虽然有 webworker.ts，但大量地理计算（如 DouglasPeuker, GrahamScan）在 src/index.ts 中是同步导出的。可以将这些重计算逻辑默认封装在 Worker 中执行，避免阻塞主线程。
资源管理: FontManager 和 ThreadManager 的初始化是硬编码在 Map 构造函数中的。建议采用插件化或依赖注入的方式，允许用户按需加载功能模块。

4. CLI 工具链优化

工具标准化: cli/ 目录下有大量的独立 .js 脚本。建议封装成一个统一的 CLI 入口（如 xcsmartdatabase-cli <command>），并使用 commander 或 yargs 提供更好的交互体验和帮助文档。
代码复用: 许多 CLI 脚本直接操作文件系统或数据库，部分逻辑与 src/ 中的算法有重叠。应将通用逻辑提取到 @xcsmartdatabase/util 或 @xcsmartdatabase/data-process 中。

5. 部署与运维

Docker 镜像瘦身: 现有的 Dockerfile 可能因为包含所有依赖而非常庞大。通过 Monorepo 拆分后，可以为 server 和 website 构建更精简的镜像。
环境变量管理: .env 文件过多（development, docker, production, windows, kylin...）。建议简化配置逻辑，使用统一的配置中心或更标准的加载方式。

实施建议（优先级排序）

第一阶段: 完善 ESLint 对 TS 的支持，清理代码中的 any 和 @ts-ignore。
第二阶段: 引入 Monorepo 结构，拆分核心库与工具链。
第三阶段: 优化 Map 类的渲染调度机制（引入 rAF）。
第四阶段: 整合 CLI 工具，提供统一的命令行界面。

您是否希望我针对其中某一个具体的点（例如 Monorepo 迁移或渲染性能优化）提供更详细的实施方案？

Browser

使用 nodejs 模式的时候需要将package.json里面的 type 删除 ~~~"type": "module"~~~

{
  // "type": "module" 删除
}

Browser Web Worker

由于 web worker 的特殊性，其只能支持一些基础的语法，一些涉及 DOM 的 api 语法可能无效，因此针对 web-worker 的地方需要做如下处理

src/threads/threadmanager.ts 里面,目前是没有放开 module 的使用方式，使用的是 ES5 的方式，这么处理的原因如下
1. 针对@mapgis/pbf 的 ES5 使用方式做了妥协，如果需要使用 ES6 则必须使用 protobuf 替代，工作量极大
2. 针对"@mapbox/vector-tile"的 ES5 使用方式做了妥协，改造 ES6，工作量一般
```
const worker = new Worker(defaultTileThread /* , { type: "module" } */);
```

由于特殊的 importScripts 语法，导致了该脚本必须放到公共资源目录下

importScripts('./pbf.js'); // 该./指的是public/maptex的目录，不是src的当前目录
// 上面实际上等于
importScripts('http://localhost:8088/xcsmartdatabase/threads/pbf.js');

由于这些脚本是放到动态资源下的，因此打包的时候就需要放到打包后的 dist/xcsmartdatabase 目录下，因此对应的 rollup.config-web.ts 打包结构如下所示:

{
 input: ["src/index.ts"],
 output: {
   file: "dist/xcsmartdatabase/xcsmartdatabase.umd.min.js",
   name: "xcsmartdatabase",
   format: "umd",  //cjs umd amd
 },
 plugins: [
   copy({
     targets: [
       { src: 'src/docs/public/xcsmartdatabase/*', dest: 'dist/xcsmartdatabase' }
     ]
   })
 ],
}

Nodejs

使用 nodejs 模式的时候需要将package.json里面的 type 为 module

{
  "type": "module"
}

编译 nodejs 的运行库
```
npm run build-nodejs
```
执行脚本
```
npm run start-cli
```
由于一些三方库是没有支持typescript或者还是按照es5的方式导出的因此，如sqlite3 icon-lite，因此需要如下特殊处理
```
import * as sqlite3 from 'sqlite3';
const Database = sqlite3.default.Database;
//使用的时候类似
let db = new Database();
```

Service

配置文件 config.js

service/express/config.json 文件

{
  "APP_IP": "127.0.0.1", // ip
  "APP_PORT": 8088, // 端口
  "tilemapservice": {
    // TMS服务
    "cesium-stk-terrain": "/usr/xcsmartdatabase-data/nautical/stk",
    "cesium-heightmap-terrain": "/usr/xcsmartdatabase-data/nautical/stk"
  },
  "vectortileservice": {
    // VectorTile服务
    "tile": "/usr/xcsmartdatabase-data/nautical/vectortile/mbtiles",
    "sprite": "/usr/xcsmartdatabase-data/nautical/vectortile/sprite",
    "font": "/usr/xcsmartdatabase-data/nautical/vectortile/fonts",
    "style": "/usr/xcsmartdatabase-data/nautical/vectortile/style",
    "worker": "/usr/xcsmartdatabase-data/nautical/vectortile/worker",
    "dynamictiles": "/usr/xcsmartdatabase-data/nautical/vectortile/dynamictiles"
  },
  "rastertileservice": {
    // 栅格瓦片服务
    "tile": "/usr/xcsmartdatabase-data/nautical/rastertile/mbtiles"
  },
  "s52_s57_service": {
    // 海图服务
    "s57-origin-folder": "/usr/xcsmartdatabase-data/nautical/s52_s57/ENC_ROOT",
    "s57-gpkg-folder": "/usr/xcsmartdatabase-data/nautical/s52_s57/gpkg",
    "s57-metadata-database": "/usr/xcsmartdatabase-data/nautical/s52_s57/database/metadata.sqlite",
    "grid": "/usr/xcsmartdatabase-data/nautical/s52_s57/grid"
  },
  "postgres": {
    // PostGIS 服务配置
    "ip": "127.0.0.1",
    "port": 5432
  }
}

环境配置

env

执行 npm run start, 使用的是.env.development 环境文件
执行 npm run build, 使用的是.env 环境文件

请使用 npm run service-website-release 命令执行，清理下整个环境

nodejs

"module": "commonjs", /* Specify what module code is generated. */

web

"module": "esnext", /* Specify what module code is generated. */

操作系统

Windows 安装

环境设置，设置环境变量 path/to/QGIS_3_22/bin

env_window_path

Linux 安装

环境依赖
系统必要的 C++ 内核依赖
| 操作系统 | 安装依赖 | | :------- | :----------------------------------------------------------------------------------------------------- | | Ubuntu | sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev | | Fedora | sudo yum install gcc-c++ cairo-devel pango-devel libjpeg-turbo-devel giflib-devel |
Nodejs 推荐大于 14
nodejs 全局安装环境
1. http-server 执行命令 npm install -g http-server

Docker

环境

必须管理员或者 sudo 启动

安装对应操作系统下的 Docker

Window Docker Desktop Installer.exe 其他注意事项
1. 更新WSL
```
wsl --update
```
2. 检查WSL版本
```
wsl --version
```
3. 网络问题 A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.

docker login

国内源

{
  "registry-mirrors": ["http://hub-mirror.c.163.com"],
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false
}

C:\Users\Administrator.docker\config.json 修改如下或者删除config.json

{
  "auths": {
    "https://index.docker.io/v1/": {}
  },
  "credStore": "desktop",
  "currentContext": "desktop-linux",
  "plugins": {
    "-x-cli-hints": {
      "enabled": "true"
    },
    "debug": {
      "hooks": "exec"
    },
    "scout": {
      "hooks": "pull,buildx build"
    }
  },
  "features": {
    "hooks": "true"
  }
}

setx DOCKER_BUILDKIT 1
setx COMPOSE_DOCKER_CLI_BUILD 1
Linux linux-install
Mac mac-install

编译（开发人员）

由于在编译-nodejs 的时候需要一些本地的 C++库和一些前置环境
1. canvas
  1. 160.3 npm ERR! node-pre-gyp WARN Hit error response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/v2.11.2/canvas-v2.11.2-node-v120-linux-musl-x64.tar.gz
  2. 160.3 npm ERR! node-pre-gyp ERR! System Linux 5.15.133.1-microsoft-standard-WSL2
  3. 如果删除了 canvas 依赖，那么代码就必须屏蔽 NodeCanvas，不将其对外导出，否则出现下面实际使用的时候报错
2. libpng libjpeg libsvg
因此使用 package-docker.json 中的内容替代 package.json
1. 移除了[email protected]的依赖
2. 移除了[email protected]的依赖

必须使用 package-docker.json 中的内容替代 package.json，不然一些 C++的环境在 linux 上确实不太好编译

版本对不上
依赖太过复杂
二进制动态库/运行时网络资源下载/无法访问

测试

cd path/to/XcSmartDatabase
docker run -p 8088:8088 xcsmartdatabase

桌面端
1. 运行好后，需要修改 service/express/conifg.json。文件来指定对应的路径来适配才行查看运行的 containid
2. 进入命令行
3. 正常的 linux 编辑命令
  1. cd /usr/xcsmartdatabase/service/express
  2. vi config.json
  3. 改变默认的路径为实际物理地址，保存退出
4. 拷贝数据到容器里面 docker cp foo.txt :/foo.txt
5. 重启 docker 服务，发现路径产生了变化

服务端

启用远程 shell

# docker exec -it <container> bash
docker exec -it bf60922437d2 bash

拷贝数据到容器里面

# docker cp foo.txt <container>:/foo.txt
# docker cp data-folder <container>:/data-folder
docker cp foo.txt bf60922437d2:/foo.txt

发布

xcsmartdatabase-datavolume

准备数据

   cd D:\Code\XcSmartDatabase\XcSmartDatabase-Data

压缩数据

   # cd D:\Code\XcSmartDatabase\XcSmartDatabase-Data
   tar -cvzf xcsmartdatabase-data.tar .

拷贝数据

docker volume create xcsmartdatabase-data
docker volume create xcsmartdatabase-minio
docker volume create xcsmartdatabase-oss
docker volume create xcsmartdatabase-database
# docker run -d --name xcsmartdatabase-data --mount source=xcsmartdatabase-data,target=/opt/xcsmartdatabase-data parndeedlit/xcsmartdatabase-server:latest

xcsmartdatabase-website

发布到公网

cd path/to/XcSmartDatabase
npm run tsconfig-commonjs
npm run service-website-release
npm run build-website
docker build -t xcsmartdatabase-website .
docker tag xcsmartdatabase-website parndeedlit/xcsmartdatabase-website
docker push parndeedlit/xcsmartdatabase-website

# 导出到本地
docker save -o xcsmartdatabase-website.tar xcsmartdatabase-website:latest
# 从本地导入
docker load -i xcsmartdatabase-website.tar
# 第一次配置端口
docker run -p 8087:8087 --dns 114.114.114.114 --dns 114.114.115.115 docker-image-id

xcsmartdatabase-server

发布到公网

cd path/to/XcSmartDatabase
npm run service-server-release
sudo docker build -t xcsmartdatabase-server .
sudo docker tag xcsmartdatabase-server parndeedlit/xcsmartdatabase-server
sudo docker push parndeedlit/xcsmartdatabase-server

# 导出到本地
docker save -o xcsmartdatabase-server.tar xcsmartdatabase-server:latest
# 从本地导入
docker load -i xcsmartdatabase-server.tar
# 第一次配置端口
docker run -p 8088:8088 --dns 114.114.114.114 --dns 114.114.115.115 docker-image-id
# 查看信息
docker container inspect container-id

数据迁移

docker run --rm --volumes-from xcsmartdatabase -v $(pwd):/backup ubuntu tar cvfz /backup/backup_maptex.tar.gz /var/lib/postgresql/data

docker run --rm --volumes-from dbstore2 -v $(pwd):/backup ubuntu bash -c "cd /dbdata && tar xvf /backup/backup.tar --strip 1"
docker run --rm --volumes-from <container> -v $(pwd):/backup ubuntu sh -c "cd <container-path> && tar xvfz /backup/backup.tar.gz --strip 1"

编排

dibian => docker compose
centos => docker-compose

# 启动
sudo docker compose -p xcsmartdatabase up -d
# 预执行操作，必须不断执行，知道写入完毕，第一次初始化后，后续不需要重复执行
# 1 开发模式
sudo docker compose exec maptexserver npx prisma migrate dev --name init
# 2 生产模式
sudo docker compose exec maptexserver npx prisma migrate deploy

编译结果如下 build-layer

这里如果反复多次失败，检查失败的依赖屏蔽即可.第一次编译的时候也是尝试了 5 次才成功

运维/部署

安装对应操作系统下的 Docker
1. Window Docker Desktop Installer.exe
2. 阿里云安装 Docker
启动 DockerDesktop，公网搜索下载对应的仓库
1. XcSmartDatabase-Docker仓库
2. 搜索对应的仓库

启动命令

# 进入命令行
docker run -p 127.0.0.1:8088:8088 <image_name>

进入docker shell
```
docker exec -it <container_name> sh
```
测试公网地址
| 名称 | 映射名称 | 映射类型 | 外网地址 | 内网地址 | | :--------- | :----------------------- | :------- | :------------------------ | :-------------- | | 网站 | XcSmartDatabase-Website | HTTPS | https://www.maptex.top | 127.0.0.1:18087 | | 服务器 | XcSmartDatabase-Server | HTTPS | https://server.maptex.top | 127.0.0.1:18088 | | 数据库地址 | XcSmartDatabase-Database | SSH | http://auth.maptex.top | 127.0.0.1:20485 |

公网拉取后续修改

server

/usr/xcsmartdatabase .env

ENV_DEVELOPMENT=false
# for docker inner ip/host - service/website
REACT_APP_WEBSITE_PROTO=http
REACT_APP_WEBSITE_IP="127.0.0.1"
REACT_APP_WEBSITE_PORT=18087
# for docker inner ip/host - service/server
REACT_APP_SERVER_PROTO=http
REACT_APP_SERVER_IP="127.0.0.1"
REACT_APP_SERVER_PORT=18088

DOCKER_DATA_VOLUME_ENABLE=true
DOCKER_DATA_VOLUME_FOLDER="/opt/xcsmartdatabase-data"


REACT_APP_WEBSITE_IP="www.xcsmartdatabase.top"
REACT_APP_WEBSITE_PORT=443
REACT_APP_SERVER_IP="3ya95746ua03.vicp.fun"
REACT_APP_SERVER_PORT=443
REACT_APP_MAPTEX_INNER_DEBBUGER=false
REACT_APP_CORS_LIST="https://www.xcsmartdatabase.top,https://3ya95746ua03.vicp.fun"

AUTH_GITEE_AUTH2_CLIENT_ID="7e2fdbfe38be4946f634b8211fc12782c9f1d3ae291a7b8add17c66a47a3e5cb"
AUTH_GITEE_AUTH2_CLIENT_SECRET="5e41fa5ca5856a09979e232b88ef14d240595b708d1d5b75c35bf9d5ed2ca003"
AUTH_GITEE_AUTH2_REDIECT_URL="https://www.xcsmartdatabase.top/auth_callback"
AUTH_GITEE_AUTH2_CLIENT_URL="https://www.xcsmartdatabase.top"

POSTGRESQL_ROOT_DATABASE="postgres"
POSTGRESQL_ROOT_USER="postgres"
POSTGRESQL_ROOT_PASSWORD="postgres"
POSTGRESQL_IP="127.0.0.1"
POSTGRESQL_PORT="5432"

REDIS_IP="redis"
REDIS_PORT=18086

Debug

S57

SET S57_CSV=E:\\data\\XcSmartDatabase-Data\\local\\s52_s57\\dictionary
set OGR_S57_OPTIONS = "SPLIT_MULTIPOINT=ON,ADD_SOUNDG_DEPTH=ON,RETURN_PRIMITIVES=ON,RETURN_LINKAGES=ON,LNAM_REFS=ON,LIST_AS_STRING=OFF"