Ubuntu 24.04 安装 Graphweaver 2.24.1 指南

Ubuntu 24.04 服务器安装 Graphweaver 2.24.1 的实操篇：NodeSource 安装 Node 22 与 pnpm 9，npm 全局、npx 直跑、项目内依赖三种安装方案实测对比，init 脚手架与开发双端口验证，生产构建与 systemd 托管全流程，附 tsc not found、MikroORM 版本校验、GraphQL CSRF 头等五则实测排障与卸载清理。

Graphweaver安装Node.jsGraphQLsystemd2026/10/24

Ubuntu 24.04 安装 Graphweaver 2.24.1 指南

目标：在一台 Ubuntu 24.04 服务器上从零安装 Graphweaver 2.24.1，跑通"安装 → 创建项目 → 开发启动 → 生产构建 → systemd 托管"的完整链路。本文全部命令与回显均为 2026-10-24 在 Ubuntu 24.04 LTS（x86_64）服务器上的实测记录，连接的 PostgreSQL 5432 端口已有 gwdemo 业务库；工具定位与选型背景见《Graphweaver 2.24.1 介绍与选型指南》（https://www.quzuo.net/document/iU0iIHHNlNsS）。

一、环境信息

实测服务器与软件基线：

项目值
操作系统Ubuntu 24.04 LTS（x86_64）
内核系列6.8.x
Node.jsv22.23.4（NodeSource 官方源安装）
npm10.9.9（随 Node.js 22 附带）
pnpm9.15.9（npm 全局安装）
目标软件Graphweaver 2.24.1（npm latest，2026-10-24 实查）
数据库PostgreSQL（已有 gwdemo 库，用户 gwuser，含 customer/orders/product 表）

Graphweaver 对运行时有硬性要求：Node.js > 22、pnpm > 9（官方 Quick Start 口径，选型篇有详细说明）。Ubuntu 24.04 官方源的 nodejs 包版本偏旧，直接 apt install nodejs 无法满足要求，因此本文用 NodeSource 源安装 Node 22。

二、前置条件

  1. 一台可访问外网的 Ubuntu 24.04 服务器，具备 sudo 权限；
  2. 服务器需能访问 npm registry（安装阶段下载约 1600 个包）；
  3. 如需连接既有 PostgreSQL/MySQL 数据库，准备好主机、端口、库名、账号；
  4. curl 与 build-essential 基础工具（Ubuntu 24.04 默认已带 curl）。

三、版本选型

安装前先实查 npm 上的当前版本，确认 2.24.1 就是最新稳定版：

npm view graphweaver version

实测回显：

2.24.1

结论：2.24.1 即 npm latest 标签指向的版本（发布于 2026-09-22），直接安装即可，无需挑旧版。Graphweaver 的版本节奏与依赖关系（CLI 包 graphweaver 与核心库 @exogee/graphweaver 同步发版）在《Graphweaver 2.24.1 介绍与选型指南》（https://www.quzuo.net/document/iU0iIHHNlNsS）有完整梳理。

四、方案 A：npm 全局安装（推荐）

4.1 安装 Node.js 22

使用 NodeSource 的官方配置脚本：

curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/ns.sh && bash /tmp/ns.sh

脚本尾部实测回显：

Repository configured successfully.
To install Node.js, run: apt install nodejs -y

按提示安装：

apt-get install -y nodejs

本机此前已装过，apt 给出确认性回显：

nodejs is already the newest version (22.23.4-1nodesource1).

验证版本：

node -v
npm -v

实测回显：

v22.23.4
10.9.9

4.2 安装 pnpm 9

官方要求 pnpm > 9，用 npm 全局安装指定版本：

npm install -g pnpm@9.15.9

实测回显：

added 1 package in 2s

1 package is looking for funding
  run `npm fund` for details

pnpm --version

实测回显：

9.15.9

4.3 安装 Graphweaver CLI

npm install -g graphweaver@2.24.1

实测回显（节选）：

npm warn deprecated @opentelemetry/sdk-trace-base@2.5.1: Use @opentelemetry/sdk-trace package

added 1608 packages in 31s

270 packages are looking for funding
  run `npm fund` for details

要点：一次性安装 1608 个包、耗时 31 秒；@opentelemetry/sdk-trace-base 的 deprecated 警告来自上游依赖声明，不影响功能。

4.4 安装验证

graphweaver --version
npm ls -g --depth=0

实测回显：

2.24.1
/usr/lib
├── corepack@0.36.0
├── graphweaver@2.24.1
├── npm@10.9.9
└── pnpm@9.15.9

全局 CLI 就绪，命令名即 graphweaver。

五、方案 B：npx 免安装直跑

不污染全局环境、临时试用首选 npx：

npx -y graphweaver@2.24.1 --version

实测回显：

2.24.1

npx 会把包缓存到本地缓存目录后执行，--version 立即返回。所有子命令（init/import/build/start 等）都可以用 npx -y graphweaver@2.24.1 <子命令> 的形式执行。适合快速验证与一次性脚手架；长期开发仍建议方案 A 或 C，避免每次解析 npx 缓存。

六、方案 C：项目内安装（devDependencies）

graphweaver init 生成的项目脚手架默认把 graphweaver 写入 devDependencies（见第八节实测的 package.json），因此进入项目目录执行 pnpm install 后，项目内就有一份独立于全局的 CLI。配合 pnpm start、pnpm build 等 npm scripts 使用时，CLI 与项目依赖版本严格一致——这是生产构建的推荐形态，原因见第十一节排障第 1 则。

七、三种方案对比

维度方案 A npm 全局方案 B npx 直跑方案 C 项目内依赖
安装动作npm install -g graphweaver@2.24.1无（npx 缓存即用）随项目 pnpm install
版本管理全局单一版本每次命令指定每项目锁定
适用场景服务器常驻开发/运维机临时试用、CI 冒烟项目开发与生产构建
实测体积1608 packages / 31s同（走缓存）与项目依赖一并安装
注意点升级需手动 reinstall每次需 -y 确认需经 npm scripts 调用（见排障）

三者可以共存：全局装一份做日常脚手架（init），项目内依赖做构建与启动（build/start），npx 做版本探针（npx -y graphweaver@2.24.1 --version）。

八、项目创建与运行验证

8.1 init 创建脚手架

graphweaver init --name gwdemo --backend sqlite

实测回显：

Initialising a new Graphweaver project...
Project Name: gwdemo
Backends: Sqlite
All Done!
Make sure you cd to the new project directory, then run pnpm install and pnpm start.

--backend 支持 postgres / mssql / mysql / rest / sqlite（可多选，详见 CLI 篇）；本文先用 sqlite 起一个零依赖项目，生产段再连 PostgreSQL。

init 生成的目录结构（ls -la 实测）：

total 28
drwxr-xr-x  4 root root   4096 Oct 24 10:12 .
drwxr-xr-x  8 root root   4096 Oct 24 10:11 ..
-rw-r--r--  1 root root    127 Oct 24 10:12 .gitignore
-rw-r--r--  1 root root     28 Oct 24 10:12 README.md
-rw-r--r--  1 root root    849 Oct 24 10:12 package.json
drwxr-xr-x  3 root root   4096 Oct 24 10:12 src
-rw-r--r--  1 root root    518 Oct 24 10:12 tsconfig.json

五件套：.gitignore、README.md、package.json（849 字节，devDependencies 内含 graphweaver、typescript）、src/（前后端源码）、tsconfig.json。

8.2 安装依赖并前台启动

cd /srv/gwdemo
pnpm install
pnpm start

pnpm start 启动成功后的日志尾部实测：

The Graphweaver server has started. 😀😀
The GraphQL API is available at http://localhost:9001/
/Admin UI is available at http://localhost:9000/ 🚀
If you are new here, start with Admin UI.

开发模式双端口：Admin UI 9000（Vite 托管），GraphQL API 9001（--port 默认 9000，前端占用 9000、后端自动 +1）。开发模式下服务默认监听回环地址，远程访问需 pnpm start -- --host 0.0.0.0（start 命令的 --host/--port 参数见 CLI 篇）。

8.3 端点验证

Admin UI（HTTP 200，返回 Vite 单页应用）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9000/
curl -s http://localhost:9000/ | grep -o "<title>[^<]*</title>"

实测回显：

200
<title>Graphweaver - Admin UI</title>

GraphQL API：

curl -s -X POST -H "content-type: application/json" \
  -d '{"query":"{__typename}"}' http://127.0.0.1:9001/graphql

实测回显：

{"data":{"__typename":"Query"}}

九、生产构建与 systemd 托管

9.1 连接既有 PostgreSQL 并导入实体

生产项目 gwpgdemo 使用 PostgreSQL 数据源创建，并修改 src/backend/database.ts，把连接四要素改为环境变量注入（带开发默认值回退）：

export const connection = {
  connectionManagerId: 'postgres',
  mikroOrmConfig: {
    driver: PostgreSqlDriver,
    entities,
    dbName: process.env.DATABASE_NAME || 'gwdemo',
    user: process.env.DATABASE_USER || 'gwuser',
    password: process.env.DATABASE_PASSWORD || 'q1w2e3r4',
    host: process.env.DATABASE_HOST || '127.0.0.1',
    port: process.env.DATABASE_PORT ? parseInt(process.env.DATABASE_PORT) : 5432,
  },
};

连接既有库导入表实体的 graphweaver import 交互流程与 MikroORM 版本排障，见 CLI 篇；全部环境变量逐项说明见配置篇。

9.2 pnpm build 生产构建

cd /srv/gwpgdemo
pnpm build

实测回显（关键步骤行）：

Building backend...
Appending start command.
Checking Typescript types...
Backend Build Finished!
Generating Types...
Typescript types passed.

随后是 Vite 前端构建资产清单，尾部：

(!) Some chunks are larger than 500 kB after minification. Consider:
- Using dynamic import() to code-split the application
- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollup.org/configuration-options/#output-manualchunks
- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.
✓ built in 5.20s
Build complete!

产物落在 dist/backend/index.js（独立服务器 bundle，单文件即可运行）。Admin UI 静态资源由 Vite 产出，生产如需托管界面需另行部署静态资源，仅跑 API 时无需理会。

9.3 systemd 单元

写入 /etc/systemd/system/graphweaver.service：

[Unit]
Description=Graphweaver GraphQL API Service
After=network.target postgresql.service
Wants=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/srv/gwpgdemo
Environment=NODE_ENV=production
Environment=GRAPHWEAVER_API_PORT=9000
Environment=MIKRO_ORM_ALLOW_VERSION_MISMATCH=1
Environment=DATABASE_HOST=10.89.74.2
Environment=DATABASE_NAME=gwdemo
Environment=DATABASE_USER=gwuser
Environment=DATABASE_PASSWORD=q1w2e3r4
ExecStart=/usr/bin/node /srv/gwpgdemo/dist/backend/index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable --now graphweaver

9.4 服务状态与生产端点验证

systemctl is-active graphweaver
systemctl status graphweaver --no-pager | head -12

实测回显：

active
● graphweaver.service - Graphweaver GraphQL API Service
     Loaded: loaded (/etc/systemd/system/graphweaver.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-10-24 11:02:31 UTC; 5min ago
   Main PID: 6557 (node)
      Tasks: 11 (limit: 2279)
     Memory: 143.6M (peak: 148.2M)
        CPU: 2.806s
     CGroup: /system.slice/graphweaver.service
             └─6557 /usr/bin/node /srv/gwpgdemo/dist/backend/index.js

健康检查（生产形态下 GraphQL 挂在根路径）：

curl -s http://127.0.0.1:9000/health

实测回显：

{"status":"ok"}

GraphQL 查询既有库的 product 表：

curl -s -X POST -H "content-type: application/json" \
  -H "x-apollo-operation-name: MyQuery" \
  -d '{"query":"{ products { id name price stock } }"}' \
  http://127.0.0.1:9000/

实测回显：

{"data":{"products":[{"id":"1","name":"Mechanical Keyboard","price":"329.00","stock":50},{"id":"2","name":"4K Monitor","price":"1999.00","stock":20}]}}

两个生产要点：

  1. 端口语义：systemd 单元里 GRAPHWEAVER_API_PORT=9000 让 API 监听 9000；若不设置该变量，前台直跑 node dist/backend/index.js 实测监听 9001（日志 Starting standalone server on :::9001），且 /health 同样可用；
  2. CSRF 防护：生产 Apollo 服务端要求非浏览器请求携带 x-apollo-operation-name 或 apollo-require-preflight 头之一，缺失时报 GraphQL CSRF 保护错误——这是 curl/Postman 调试时最容易踩的坑。

十、配置说明

安装与运行涉及的配置集中在三处，逐项细节（含实测验证过的生效方式）见《Graphweaver 2.24.1 配置参数详解》（https://www.quzuo.net/document/ylmKf3FKzYcO）：

配置位内容本文涉及
环境变量GRAPHWEAVER_API_PORT、DATABASE_*、MIKRO_ORM_ALLOW_VERSION_MISMATCH、NODE_ENV 等systemd 单元（9.3 节）
项目源码src/backend/database.ts 连接配置、src/backend/index.ts 实体注册9.1 节
CLI 参数init --name/--backend、start --host/--port、build --adminUiBase第八、九节

十一、常见问题（实测排障）

1. 全局 CLI 在项目内跑 start/build 报 Missing "./regenerator" specifier in "@babel/runtime" 或 tsc: not found

全局 CLI 与项目 pnpm 布局不兼容所致。实测两种报错：开发启动报 Error: Missing "./regenerator" specifier in "@babel/runtime" package（Vite 前端起不来）；构建/打印 Schema 报 /bin/sh: 1: tsc: not found 后 Error: Typescript types failed check.。结论：进入项目目录一律用项目内 CLI——pnpm start、pnpm build、pnpm exec graphweaver print-schema（npm scripts 会把 node_modules/.bin 注入 PATH）。全局 CLI 只用于 init 与 --version。

2. 生产启动报 Bad @mikro-orm/knex version ... All official @mikro-orm/* packages need to have the exact same version

MikroORM 的严格同版本校验被 bundle 打包触发。实测报错尾部还提示 Maybe you want to check, or regenerate your yarn.lock or package-lock.json file?。两步修复：项目内 pnpm up @mikro-orm/knex @mikro-orm/core @mikro-orm/postgresql 对齐版本后重新 build；并在运行环境注入 MIKRO_ORM_ALLOW_VERSION_MISMATCH=1（本机 systemd 单元已带，见 9.3 节）。依赖对齐的前后对比与根因分析见《Graphweaver 2.24.1 配置参数详解》（https://www.quzuo.net/document/ylmKf3FKzYcO）。

3. 开发模式远程机器打不开 Admin UI

开发服务默认监听回环地址（Vite 绑定 ::1）。启动时加 pnpm start -- --host 0.0.0.0，或将生产 API 端口直接暴露给调用方。

4. curl 调生产 GraphQL 报 CSRF 相关错误

见 9.4 节要点 2：补 x-apollo-operation-name 头即可。浏览器端不受影响（Apollo 预检机制自动处理）。

5. Node 版本不满足

Graphweaver 要求 Node > 22。Ubuntu 24.04 用本文 4.1 节的 NodeSource 方式安装 Node 22，勿用发行版源。版本联动关系与官方要求的出处见选型篇。

十二、卸载与清理

npm uninstall -g graphweaver

实测回显：

removed 1608 packages in 2s

项目目录直接 rm -rf /srv/gwdemo /srv/gwpgdemo；systemd 托管形态先 systemctl disable --now graphweaver 再删除单元文件与 daemon-reload。Node.js/pnpm 如无其他用途可一并卸载（apt-get purge nodejs + npm uninstall -g pnpm）。

十三、参考链接

  1. 本系列选型与定位：《Graphweaver 2.24.1 介绍与选型指南》 https://www.quzuo.net/document/iU0iIHHNlNsS
  2. Graphweaver 官方 Quick Start：https://graphweaver.com/docs/quick-start （查询日期 2026-10-24）
  3. NodeSource Node.js 安装脚本：https://deb.nodesource.com/setup_22.x （本文 4.1 节使用）
  4. npm 包 graphweaver：https://www.npmjs.com/package/graphweaver （版本 2.24.1，2026-10-24 实查）
  5. 环境变量与连接配置逐项解析：《Graphweaver 2.24.1 配置参数详解》 https://www.quzuo.net/document/ylmKf3FKzYcO
  6. 子命令逐参数实测：《Graphweaver 2.24.1 常用 CLI 命令与工具详解》 https://www.quzuo.net/document/K2dsMswn44U0