TeamMapper 0.4.0 配置参数详解

目标：把 TeamMapper 0.4.0 的全部配置面——环境变量、三层 settings JSON、功能开关、协作限流参数——逐项讲清默认值与影响，并给出生产配置模板。所有默认值取自官方 docker-compose-prod.yml、.env.default 与后端 config.service.ts/yjsLimits.ts 源码（仓库 main 分支，查询日期 2026-11-02），生效行为在 Ubuntu 26.04 实测环境逐项验证。

一、环境信息

• 部署形态：Docker Compose（ghcr.io/b310-digital/teammapper:latest + postgres:15-alpine），端口 8144，部署步骤见本专栏《TeamMapper 0.4.0 Docker Compose 部署指南》
• 后端：NestJS，配置读取入口 teammapper-backend/src/config.service.ts
• 配置文件：镜像内置 config/settings.prod.json（75 行）+ 可挂载 settings.override.json
• 实测验证方式：GET /api/settings 返回体、应用重启后行为对照

二、前置条件

• 已完成 Compose 部署且服务健康：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8144/

HTTP 200

• 已获取源码或可查官方文档（参数含义以源码为准）：

git clone --depth 1 https://github.com/b310-digital/teammapper.git

三、参数查看与修改方式

TeamMapper 配置分两个通道，修改方式与生效条件不同：

查看当前生效的系统/用户设置（前端初始化时也调它）：

curl -s http://127.0.0.1:8144/api/settings

实测返回节选（完整结构见 systemSettings + userSettings 两段）：

{
  "systemSettings": {
    "info": { "name": "TeamMapper", "version": "0.1.9", "aiModel": null },
    "urls": {
      "pictogramApiUrl": "/arasaac/api/pictograms",
      "pictogramStaticUrl": "/arasaac/images/pictograms"
    },
    "featureFlags": { "pictograms": false, "ai": false, "arrows": false }
  },
  "userSettings": {
    "general": { "language": "en", "darkMode": false, "displayName": "" },
    "mapOptions": {
      "centerOnResize": false, "autoBranchColors": true, "showLinktext": false,
      "branchStyle": "tapered", "fontMaxSize": 70, "fontMinSize": 15, "fontIncrement": 5,
      "defaultNode": { "...": "节点默认颜色/字体/图片" }
    }
  }
}

💡 说明：info.version 显示 0.1.9 是镜像内 package.json 字段未随 release tag 同步的上游事实，不代表部署的是 0.1.9 版；版本以 release tag（v0.4.0-1）与镜像 digest 为准。

settings.override.json 覆盖生效实测：写入 systemSettings.urls.imprintUrl 后重启，/api/settings 即返回该值：

cat > config/settings.override.json <<'EOF'
{
  "systemSettings": {
    "urls": {
      "imprintUrl": "http://127.0.0.1:8144/imprint",
      "privacyUrl": "http://127.0.0.1:8144/privacy"
    }
  }
}
EOF
docker compose restart app_prod
curl -s http://127.0.0.1:8144/api/settings | python3 -c "import sys,json;d=json.load(sys.stdin);print('imprintUrl:',d['systemSettings']['urls'].get('imprintUrl'))"

imprintUrl: http://127.0.0.1:8144/imprint

四、参数总览

后端源码（config.service.ts 读取 process.env）实际消费的环境变量共 44 个，按域归类：

五、核心参数分类详解

5.1 运行模式与数据库连接

5.2 保留期与清理

5.3 功能开关（feature flags）

三个开关控制前端功能可见性，/api/settings 的 featureFlags 段实测返回 {"pictograms": false, "ai": false, "arrows": false}：

FEATURE_YJS_RATE_LIMITING：是否启用 Yjs 消息限流（配合下节参数排障用）。

5.4 协作与限流参数（Yjs/WebSocket 网关）

网关对「每连接」「每图」「每 IP」三层限额（源码 yjsLimits.ts/config.service.ts 实测核对）：

💡 说明：单条 WS 消息硬上限 1 MiB（WS_MAX_PAYLOAD，源码常量，不可配）；导图典型 sync 消息 1–50 KB，正常协作不会触碰限流线，仅防滥用。

5.5 图片与导图复制限额

5.6 AI/LLM 参数

AI_ENABLED=true 后生效，对接 OpenAI 兼容接口：AI_LLM_URL（接口地址）、AI_LLM_TOKEN（API Key，用 ${VAR} 注入勿明文）、AI_LLM_PROVIDER/AI_LLM_MODEL、AI_LLM_RPM/TPM/TPD（每分钟/每日请求与 token 配额）、AI_LLM_MAX_OUTPUT_TOKENS、AI_LLM_TIMEOUT_MS。未配置时 /api/settings 的 info.aiModel 为 null（实测）。

5.7 userSettings（前端用户默认值）

settings.*.json 的 userSettings 段是前端初始默认（语言、暗色模式、分支样式 tapered、字号区间 15–70、步长 5、新节点/根节点默认颜色字体）。定位：系统设置（systemSettings）由后端下发、前端不缓存；用户设置（userSettings）用户在前端改后存浏览器本地，覆盖系统默认。改 override 文件只影响新访客的初始值。

六、生产配置模板

适用场景：16GB 内存 / 50GB SSD 单机、部门级协作（≤50 并发编辑者）、数据不出内网：

    environment:
      MODE: PROD
      BINDING: "0.0.0.0"
      POSTGRES_HOST: postgres_prod
      POSTGRES_PORT: 5432
      POSTGRES_DATABASE: teammapper-db
      POSTGRES_USER: teammapper-user
      POSTGRES_PASSWORD: q1w2e3r4
      POSTGRES_SSL: "false"
      POSTGRES_QUERY_TIMEOUT: 100000
      POSTGRES_STATEMENT_TIMEOUT: 100000
      DELETE_AFTER_DAYS: 365          # 内网知识资产不按 30 天清理
      LOG_LEVEL: warn
      JWT_SECRET: tm-jwt-9f3a7c2e5b8d1460   # 生产请换 32 字节随机串并用 ${VAR} 注入
      WS_GLOBAL_MAX_CONNECTIONS: 200
      YJS_MAP_MAX_BYTES: 8388608      # 大图团队放宽到 8 MiB

要点：DELETE_AFTER_DAYS 按数据主权策略定；JWT_SECRET 必须设否则「我的导图」不可用；对外发布务必配反向代理 TLS（官方 docs/deployment.md 有 Nginx 示例）。

七、常见问题

Q1：改了 settings.override.json 没生效？ 该文件只在启动时读取，需 docker compose restart app_prod；并确认挂载路径是 /home/node/app/teammapper/config/settings.override.json（本文《TeamMapper 0.4.0 Docker Compose 部署指南》已挂载）。挂载前宿主机文件不存在会被挂成目录（见《TeamMapper 0.4.0 Docker Compose 部署指南》第十章 Q3）。

Q2：pictograms 图标开关为什么没有环境变量？ 官方 README 明确该 flag 必须 build-time 写进 JSON（关闭时后端根本不挂代理路由），运行期改不了。

Q3：协作时连接被 1008 关闭？ 触发 YJS_MESSAGE_* 限流（窗口 10s 内 >100 条 sync 消息或 >5 MiB）。多人拖拽大图的极端场景可放宽 YJS_MESSAGE_MAX_COUNT/YJS_MESSAGE_MAX_BYTES，或临时 LOG_LEVEL=debug 观察被拒消息。

Q4：想禁用匿名复制导图的滥用？ 调低 DUPLICATE_MAP_RATE_LIMIT（默认每分钟 5 次）；该端点自带 Throttle 守卫，无需改代码。

Q5：数据库连接池/超时如何影响协作？ 持久化走防抖写库，POSTGRES_*_TIMEOUT 过小会导致大图保存失败进而触发图重置；保持默认 100000ms 即可。

八、参考链接

• 官方 README「Default Settings / Environment variable overrides」：https://github.com/b310-digital/teammapper
• 后端配置源码：teammapper-backend/src/config.service.ts、src/map/utils/yjsLimits.ts（main 分支，2026-11-02）
• 部署与挂载步骤：见本专栏《TeamMapper 0.4.0 Docker Compose 部署指南》
• 配置生效的接口侧验证：见本专栏《TeamMapper 0.4.0 API 使用详解》