Graphweaver 2.24.1 配置参数详解
Graphweaver 2.24.1 配置参数的逐项实测篇：三层配置体系（环境变量/项目源码/CLI 旗标）、GRAPHWEAVER_API_PORT 四组对照实验（默认 9001、systemd 与 shell 注入生效而 .env 不生效）、DATABASE_* 连接参数与回退模式、MikroORM 版本校验开关与依赖对齐、dotenv 与 .env.vault 机制边界、生产端点 CSRF 行为与 systemd 注释模板。
Graphweaver 2.24.1 配置参数详解
目标：把 Graphweaver 2.24.1 在 Ubuntu 24.04 服务器上落地所需的全部配置参数讲透——服务端环境变量、数据库连接参数、MikroORM 系列开关、dotenv 机制、生产端点与安全行为。本文所有"生效/不生效"结论均来自 2026-10-24 在 Ubuntu 24.04 服务器上对 2.24.1 生产 bundle 的对照实测，安装背景见《Ubuntu 24.04 安装 Graphweaver 2.24.1 指南》（https://www.quzuo.net/document/ttTs2hhrdek9），工具定位见[《Graphweaver 2.24.1 介绍与选型指南》](https://www.quzuo.net/document/iU0iIHHNlNsS)（https://www.quzuo.net/document/iU0iIHHNlNsS）。
一、配置体系总览
Graphweaver 2.24.1 的配置分三层，作用域与优先级实测如下：
| 层 | 载体 | 典型内容 | 实测结论 |
|---|---|---|---|
| 进程环境变量 | systemd Environment=、shell 前缀、.env 文件 | GRAPHWEAVER_API_PORT、DATABASE_*、MIKRO_ORM_* | systemd/shell 注入实测全部生效；.env 对服务端口不生效（见 3.2 节） |
| 项目源码 | src/backend/database.ts、src/backend/index.ts | 连接四要素、实体注册、exports.connection | 代码里普遍写成 process.env.X || '默认值' 的回退模式 |
| CLI 参数 | graphweaver 子命令旗标 | init --name/--backend、start --host/--port | 一次性动作，参数详见 CLI 篇 |
三层的关系：环境变量是生产托管（systemd）的主要注入面；源码回退值决定"不设变量时的行为"；CLI 参数只影响当次命令。理解这个分层后，所有参数都可以归位。
二、服务端核心环境变量
以下变量名均经 2.24.1 产物源码引用核查（出现次数标注），生效行为经实测验证。
2.1 GRAPHWEAVER_API_PORT —— 服务监听端口（最高频）
源码引用 2 处，控制独立服务器（standalone server）的监听端口。默认值 9001。
三组对照实测（同一份生产 bundle dist/backend/index.js，连接同一 PostgreSQL）：
| 注入方式 | 实测日志 | 监听端口 | /health 探活 |
|---|---|---|---|
| 不设任何变量 | Starting standalone server on :::9001 | 9001 | {"status":"ok"} |
.env 文件写 GRAPHWEAVER_API_PORT=9100 | Starting standalone server on :::9001 | 9001（未生效） | 9100 无响应 |
shell 前缀 GRAPHWEAVER_API_PORT=9100 node dist/backend/index.js | Starting standalone server on :::9100 | 9100 | {"status":"ok"} |
systemd Environment=GRAPHWEAVER_API_PORT=9000 | 生产服务 API 验证通过 | 9000 | {"status":"ok"} |
结论：该变量在进程启动路径上先于 dotenv 注入被读取，必须用 systemd Environment= 或 shell 环境变量的方式设置，写进项目 .env 文件改变不了监听端口。::: 前缀表示同时绑定 IPv6 与 IPv4 通配地址。
2.2 GRAPHWEAVER_API_HOST / GRAPHWEAVER_API_PATH
两者在 2.24.1 产物源码中各出现 1 次，属低频可选项：GRAPHWEAVER_API_HOST 覆盖监听地址（默认通配），GRAPHWEAVER_API_PATH 覆盖 API 挂载路径（生产独立服务器默认把 GraphQL 挂在根路径 /，实测 POST http://127.0.0.1:9000/ 直接响应 GraphQL 查询）。生产实践中两者的默认行为已够用，未设置即可。
2.3 GRAPHWEAVER_DISABLE_ASYNC_LOCAL_STORAGE
源码引用 2 处。AsyncLocalStorage 是 Node.js 的请求上下文追踪机制，Graphweaver 用它串联一次 GraphQL 请求内的日志与钩子上下文。设为真值可关闭该机制——仅在排查内存/上下文泄漏类疑难问题时临时使用，常规部署不要动。
2.4 NODE_ENV
源码引用 11 处，事实上的行为开关。生产 systemd 单元固定 NODE_ENV=production（安装篇 9.3 节单元模板）；不设时服务仍能运行，但依赖它的库（Express/Fastify 生态惯例）可能走开发分支（更详细的错误对象、缓存策略差异）。
2.5 Node.js 运行时通用变量
产物源码中引用的通用变量：NODE_OPTIONS（6 处）、UV_THREADPOOL_SIZE（8 处）、DEBUG（8 处）、NODE_DEBUG（4 处）。生产部署关注两个：
UV_THREADPOOL_SIZE：libuv 线程池大小，影响数据库驱动等阻塞 IO 的并发上限，高并发查询时可从默认 4 调大；DEBUG：调试命名空间开关（如DEBUG='graphweaver:*'），排障时临时开启。
三、数据库连接参数
3.1 DATABASE_* 五件套
DATABASE_HOST（3 处）、DATABASE_NAME（3 处）、DATABASE_PASSWORD（3 处）、DATABASE_PORT（6 处）以及 DATABASE_USER，是 PostgreSQL/MySQL 项目模板预留的连接参数。项目模板 src/backend/database.ts 的标准写法（实测生产项目原文）：
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,
三个要点：
- 回退模式：每个变量都有代码内默认值，环境变量未设置时用默认值——所以 systemd 单元里只设生产值即可覆盖；
- PORT 是字符串：
parseInt处理说明环境变量进来的端口是字符串类型，自己改这段代码时注意类型； - 日志脱敏：启动日志的
connectionParams会显式移除 password 字段（实测日志原文：Connecting to database using MikroORM. Note: connectionParams have password removed for security.），凭据不会泄进日志。
3.2 实测：环境变量注入与端口联动
完整生产启动命令（前台验证形态）：
cd /srv/gwpgdemo
DATABASE_HOST=10.89.74.2 DATABASE_NAME=gwdemo DATABASE_USER=gwuser \
DATABASE_PASSWORD=q1w2e3r4 GRAPHWEAVER_API_PORT=9100 \
MIKRO_ORM_ALLOW_VERSION_MISMATCH=1 node dist/backend/index.js
启动日志实测：
Starting server on port: 9100
{"level":30,"time":1792820531424,"pid":8893,"name":"graphweaver","msg":"Graphweaver start called"}
{"level":30,"time":1792820531424,"pid":8893,"name":"graphweaver","msg":"Starting standalone server on :::9100"}
{"level":30,"time":1792820531424,"pid":8893,"name":"graphweaver","connectionParams":{"host":"10.89.74.2","port":5432,"dbName":"gwdemo","entities":[null,null,null],"user":"gwuser"},"msg":"Connecting to database using MikroORM. Note: connectionParams have password removed for security."}
探活：
$ curl -s http://127.0.0.1:9100/health
{"status":"ok"}
日志逐行信息量：第一行回显最终端口（配置是否生效的最快验证点）；connectionParams 里的 host/port/dbName/user 即环境变量注入结果，entities 数组为序列化后的实体占位。
四、MikroORM 系列参数
Graphweaver 的数据库层基于 MikroORM 6，相关参数分两组。
4.1 MIKRO_ORM_ALLOW_VERSION_MISMATCH（生产必带）
MikroORM 有严格的同版本校验：所有 @mikro-orm/* 官方包必须与 @mikro-orm/core 版本完全一致（例外：nestjs、sql-highlighter、mongo-highlighter）。esbuild 打包后 bundle 内嵌的 core 读不到真实版本号，校验必然误报——实测不设该变量时的启动报错：
Error: Bad @mikro-orm/knex version 6.6.17.
All official @mikro-orm/* packages need to have the exact same version as @mikro-orm/core (0.1.0).
Only exceptions are packages that don't live in the 'mikro-orm' repository: nestjs, sql-highlighter, mongo-highlighter.
Maybe you want to check, or regenerate your yarn.lock or package-lock.json file?
报错里的 core (0.1.0) 正是 bundle 内版本探测失真的证据。生产部署两步走：
- 项目内对齐依赖版本（
pnpm up @mikro-orm/knex @mikro-orm/core @mikro-orm/postgresql），实测对齐输出：
dependencies:
- @mikro-orm/core 6.6.2
+ @mikro-orm/core 6.6.17 (7.2.5 is available)
- @mikro-orm/knex 6.6.2
+ @mikro-orm/knex 6.6.17
- @mikro-orm/postgresql 6.6.2
+ @mikro-orm/postgresql 6.6.17 (7.2.5 is available)
Done in 5.2s using pnpm v9.15.9
- 运行环境注入
MIKRO_ORM_ALLOW_VERSION_MISMATCH=1跳过 bundle 内校验（安装篇 systemd 单元已带）。该项目内graphweaver import内省同样会触发此校验，排障实录见《Graphweaver 2.24.1 常用 CLI 命令与工具详解》（https://www.quzuo.net/document/K2dsMswn44U0）。
4.2 MIKRO_ORM_CLI_* 与运行时映射
产物源码引用的 CLI 配置变量：MIKRO_ORM_CLI_CONFIG（3 处，指定配置文件路径，.ts 结尾会自动启用 ts-node）、MIKRO_ORM_CLI_USE_TS_NODE、MIKRO_ORM_CLI_ALWAYS_ALLOW_TS、MIKRO_ORM_CLI_VERBOSE、MIKRO_ORM_CLI_TS_CONFIG_PATH。这组只影响 import/print-schema 等 CLI 动作，常驻服务不需要。
另一组是 MikroORM 固有的环境变量映射（源码 loadEnvironmentVars 逐项核对）：MIKRO_ORM_HOST、MIKRO_ORM_PORT、MIKRO_ORM_USER、MIKRO_ORM_PASSWORD、MIKRO_ORM_DB_NAME、MIKRO_ORM_DEBUG、MIKRO_ORM_ENTITIES、MIKRO_ORM_SCHEMA 等，在项目没有显式 database.ts 配置时充当兜底连接参数。Graphweaver 模板走 database.ts + DATABASE_* 路线，这组变量仅作认知储备。
五、dotenv 机制与 .env 文件
2.24.1 生产 bundle 内嵌了 dotenv，源码引用可见完整能力面：DOTENV_KEY（6 处，配合 .env.vault 加密 vault 的解密密钥）、DOTENV_CONFIG_QUIET（6 处，关闭 dotenv 的注入日志）、DOTENV_CONFIG_DEBUG。即官方支持两种环境文件形态：
- 明文
.env（工作目录下，dotenv 默认读取路径）； - 加密
.env.vault+DOTENV_KEY（dotenv://:key@dotenvx.com/vault/...格式，适合把加密后的环境文件直接入库）。
但结合 2.1 节实测必须强调：dotenv 的注入发生在 Graphweaver 读取服务端口之后（dotenv 也不会覆盖已存在的进程环境变量），所以 .env 适合放数据库连接这类"业务参数"，不适合放 GRAPHWEAVER_API_PORT 这类"启动参数"。生产托管一律走 systemd Environment=，单一注入面，避免排查时在两层间来回怀疑。
六、生产端点与安全行为
生产独立服务器（node dist/backend/index.js）的对外行为实测：
- GraphQL 挂根路径：
POST http://127.0.0.1:9000/即 GraphQL 端点（开发模式则是 9001 端口的/graphql路径，两种形态别混）； - 健康检查：
GET /health→{"status":"ok"}，可直接做 systemd 健康探针或负载均衡探针； - CSRF 防护：非浏览器请求必须携带
x-apollo-operation-name或apollo-require-preflight头之一，缺失时报 GraphQL CSRF 保护错误。实测可用查询：
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}]}}
- 资源占用基线：生产服务常驻内存实测约 143.6M（systemd status 口径），容量规划可按单实例 150M 估。
七、systemd 配置模板（逐行注释）
生产托管推荐单元（安装篇 9.3 节同款，此处补注释）：
[Unit]
Description=Graphweaver GraphQL API Service
After=network.target postgresql.service ; 数据库就绪后再起
Wants=network.target
[Service]
Type=simple
User=root ; 生产建议降权为专用用户
WorkingDirectory=/srv/gwpgdemo ; bundle 相对路径基于此目录
Environment=NODE_ENV=production
Environment=GRAPHWEAVER_API_PORT=9000 ; 端口必须在此注入（见 2.1 节）
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 ; 生产改用 EnvironmentFile 挂 600 权限文件
ExecStart=/usr/bin/node /srv/gwpgdemo/dist/backend/index.js
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
安全增强建议：凭据行抽到 /etc/graphweaver.env（属主 root、权限 600）并以 EnvironmentFile=/etc/graphweaver.env 引入；User= 降权到只读项目目录、仅可访问数据库的专用账号。
八、CLI 参数速查
配置篇视角下与"配置注入"相关的 CLI 旗标（完整子命令逐参数实测见《Graphweaver 2.24.1 常用 CLI 命令与工具详解》 https://www.quzuo.net/document/K2dsMswn44U0）：
| 命令 | 旗标 | 作用 | 默认值 |
|---|---|---|---|
start | --host | 开发服务监听地址 | 回环地址 |
start | --port | 基础端口（前端 port、后端 port+1） | 9000 |
build | --adminUiBase | Admin UI 挂载基路径 | / |
build | 位置参数 environment | backend/frontend/all | all |
print-schema | -o, --output | Schema 输出到文件（缺省 stdout） | stdout |
init | --useVersion | 指定脚手架使用的 Graphweaver 版本 | latest |
九、常见问题
1. 改了 .env 里的端口为什么没生效？ 见 2.1 节对照实测：端口在 dotenv 注入前读取，改用 systemd Environment= 或 shell 前缀。
2. 启动报 Bad @mikro-orm/knex version ...？ 见 4.1 节：项目内对齐依赖 + 注入 MIKRO_ORM_ALLOW_VERSION_MISMATCH=1。
3. curl 报 CSRF 错误？ 见第六节：补 x-apollo-operation-name 头。
4. 日志里能看到数据库密码吗？ 不能。connectionParams 打日志前显式移除 password（3.1 节第 3 点）。
5. 想给 GraphQL 换路径或绑定内网地址？ GRAPHWEAVER_API_PATH/GRAPHWEAVER_API_HOST（2.2 节），或外层用 Nginx 反代收敛。
十、参考链接
- 安装与托管背景：《Ubuntu 24.04 安装 Graphweaver 2.24.1 指南》 https://www.quzuo.net/document/ttTs2hhrdek9
- 定位与选型：《Graphweaver 2.24.1 介绍与选型指南》 https://www.quzuo.net/document/iU0iIHHNlNsS
- MikroORM 环境变量官方文档：https://mikro-orm.io/docs/configuration （查询日期 2026-10-24）
- dotenv vault 机制：https://dotenvx.com/docs （查询日期 2026-10-24）
- 子命令与旗标全集：《Graphweaver 2.24.1 常用 CLI 命令与工具详解》 https://www.quzuo.net/document/K2dsMswn44U0