Marmot 0.11.1 配置参数详解

本文逐项拆解 Marmot 0.11.1 的配置体系：config.yaml 与环境变量两层来源、优先级实测、全部官方配置键的默认值与含义，并对 server、database、logging、auth、search、metrics、pipelines、plugins、ui、telemetry 等关键项做改配生效验证（每项均为真实环境实测回显）。环境基于《Marmot 0.11.1 Docker Compose 部署指南》的在跑栈；概念与选型见《Marmot 数据目录：介绍与选型指南》；命令行操作见《Marmot 0.11.1 常用 CLI 命令详解》。

一、环境与版本信息

⚠️ 网络说明：2026-11-02 实查版本时 GitHub REST API 直连返回 API rate limit exceeded（未认证限流），改用 https://github.com/marmotdata/marmot/releases/latest 页面重定向取证，经代理 192.168.1.72:7897 可用：

$ curl -s -x http://192.168.1.72:7897 -o /dev/null -w 'releases/latest -> HTTP %{http_code}, %{redirect_url}\n' https://github.com/marmotdata/marmot/releases/latest
releases/latest -> HTTP 302, https://github.com/marmotdata/marmot/releases/tag/v0.11.1

二、前置条件

1. 已按 B2 篇完成部署：Marmot 服务与 PostgreSQL 在跑，http://<服务器>:8141/ 返回 200，admin 已改密；
2. 持有登录 token 或 API Key（签发方法见 B2 篇第五节），本文示例以 $KEY 代指 API Key；
3. 宿主可执行 marmot 二进制（marmot version 回显 marmot v0.11.1），或直接用编排层的 compose 一次性任务；
4. 改配置需要重启服务进程生效（Marmot 不支持热加载；实测通过修改 compose 的 environment: 后 docker compose up -d 重建服务完成）。

三、配置分层与参数查看、修改方式

3.1 三层配置来源

官方 Configure 文档（2026-11-01 版）明确：Marmot 用 YAML 配置文件或环境变量配置，所有键都有合理默认值，只需覆盖要改的项。实际生效来源自低到高共三层：

1. 内置默认值——不写任何配置也能跑（默认监听 0.0.0.0:8080、连 localhost:5432 的 postgres/postgres）；
2. 配置文件——默认查找当前目录下的 config.yaml，可用全局参数 --config <路径> 指定其他文件；
3. 环境变量——所有配置项都能用 MARMOT_ 前缀的环境变量设置，嵌套键用下划线分隔：database.host → MARMOT_DATABASE_HOST，server.tls.cert_path → MARMOT_SERVER_TLS_CERT_PATH；列表值用逗号分隔。

服务启动时会在日志第一行说明配置来源（实测回显）：

marmot-0.11.1-server  | No config file found, using defaults and environment variables

3.2 配置文件格式

官方文档给出的最小示例结构（键名与本文参数总览一致）：

database:
  host: localhost
  port: 5432
  user: postgres
  password: secret
  name: marmot
server:
  host: 0.0.0.0
  port: 8080
logging:
  level: info
  format: json

3.3 优先级实测：文件 > 默认，环境变量 > 文件

用宿主二进制做两组对照实验。测试配置 cfgtest/config.yaml 故意把数据库主机写成不存在的 db-not-exist：

database:
  host: db-not-exist
  port: 5432
  user: marmot
  password: q1w2e3r4
  name: marmot
server:
  host: 127.0.0.1
  port: 18080
logging:
  level: info
  format: console

实验一：只给配置文件（环境变量不设数据库主机），看报错连的是哪个主机——

$ timeout 8 ./bin/marmot run --config cfgtest/config.yaml
Starting Marmot...
Error: Failed to initialize database: pinging database: failed to connect to `user=marmot database=marmot`: hostname resolving error: lookup db-not-exist on 127.0.0.53:53: server misbehaving

报错解析的主机是 db-not-exist，证明配置文件覆盖了内置默认值 localhost。

实验二：同一配置文件，外加环境变量 MARMOT_DATABASE_HOST=env-wins-host——

$ MARMOT_DATABASE_HOST=env-wins-host timeout 8 ./bin/marmot run --config cfgtest/config.yaml
Starting Marmot...
Error: Failed to initialize database: pinging database: failed to connect to `user=marmot database=marmot`: hostname resolving error: lookup env-wins-host on 127.0.0.53:53: server misbehaving

报错主机变成 env-wins-host，证明环境变量覆盖配置文件。结论：优先级为 环境变量 > config.yaml > 内置默认值，与官方文档描述一致。这也是 B2 篇 compose 全部用 MARMOT_* 环境变量注入配置的依据。

3.4 查看当前生效配置

Marmot 没有「打印全量配置」的命令（marmot run --help 只有全局参数，无配置转储子命令），实测可用的观察通道：

• 启动日志：No config file found... 行确认是否加载了文件；Server started 行带实际监听地址：

$ docker compose logs marmot | grep 'Server started'
marmot-0.11.1-server  | {"level":"info","address":"0.0.0.0:8080","swagger_ui":"http://0.0.0.0:8080/swagger/index.html","time":"2026-11-02T00:41:48Z","message":"Server started"}

• GET /api/v1/ui/config：无需鉴权即返回部分运行时配置（banner、加密、table_preview、语言），实测回显：

$ curl -s http://localhost:8141/api/v1/ui/config
{"banner":{"enabled":false,"dismissible":true,"variant":"info","message":"","id":"banner-1"},"encryption_configured":true,"allow_unencrypted":false,"table_preview_enabled":false,"default_language":""}

• 编排层环境变量清单：如 docker compose config 可渲染最终注入的 MARMOT_* 集合。

四、参数总览

下表为官方 Configure 文档（Version 0.11，2026-11-01 查询）全量键、说明与默认值；「实测」列标注本文第五节是否做了改配生效验证。

五、核心参数分类详解（改配生效实测）

以下实验统一操作方式：修改 compose 的 marmot 服务 environment: 增加对应变量 → docker compose up -d 重建 → 验证 → 全部复原。为控制重启次数，本文把观察性不冲突的项合并注入：

    environment:
      # ...B2 篇原有变量不动...
      MARMOT_LOGGING_FORMAT: console
      MARMOT_METRICS_ENABLED: "true"
      MARMOT_UI_BANNER_ENABLED: "true"
      MARMOT_UI_BANNER_MESSAGE: "Scheduled maintenance 02:00-03:00"
      MARMOT_UI_BANNER_VARIANT: warning
      MARMOT_AUTH_ANONYMOUS_ENABLED: "true"
      MARMOT_SERVER_ROOT_URL: http://localhost:8141
      MARMOT_EXPERIMENTAL_TABLE_PREVIEW: "true"
    ports:
      - "8141:8080"
      - "8149:9090"   # 临时把指标端口映射出来验证 metrics.port

$ docker compose up -d
 Container marmot-0.11.1-server Recreated 
 Container marmot-0.11.1-db Waiting 
 Container marmot-0.11.1-db Healthy 
 Container marmot-0.11.1-server Starting 
 Container marmot-0.11.1-server Started 

5.1 server：监听、root_url 与加密密钥

• server.host/server.port 控制 HTTP 监听，实测启动日志 "address":"0.0.0.0:8080"（见 3.4）。对外端口由编排层映射（本例 8141）决定，与这两个键无关。
• server.root_url 是实例对用户的可访问 URL。官方硬性约束：使用 OAuth/OIDC 登录或 CLI marmot login 时必须设置，用于生成回调地址与登录后跳转。本次注入 MARMOT_SERVER_ROOT_URL=http://localhost:8141 后服务正常启动、登录接口不受影响（实测 POST /api/v1/users/login 返回 200 与 access_token）。生产应写用户真实访问的 https 域名。
• server.encryption_key：32 字节 base64 密钥（marmot generate-encryption-key 生成），加密目录中保存的数据源凭据。生效观测点在 GET /api/v1/ui/config 的 encryption_configured 字段——本栈已设置密钥，实测为 true（见 3.4）。
• server.allow_unencrypted：默认 false，即没有加密密钥时拒绝明文存储凭据；实测 ui/config 中 allow_unencrypted:false。仅在明确接受凭据明文入库的开发环境才设 true。
• server.tls.*：服务端直接终止 TLS（证书/私钥/CA，支持 mTLS）。本环境 TLS 由前置代理终结，未实测；生产裸跑时按官方 TLS 文档配置三路径即可。
• server.custom_response_headers：给所有响应追加安全头（如 CSP），仅配置文件支持、无对应环境变量——这是「文件/env 双通道」的一个例外，注意别踩。

5.2 database：连接与连接池

• 必需 PostgreSQL 14+，账号需建表/建索引权限。五要素与 sslmode 的覆盖行为已在 3.3 用错误主机名实测（报错逐行照抄）。
• 连接池三项默认 max_conns:50 / idle_conns:25 / conn_lifetime:5。生效可用 Prometheus 指标 marmot_db_connections 观测——开启 metrics 后实测回显：

$ curl -s http://localhost:8149/metrics | grep '^marmot_db_connections'
marmot_db_connections 0

• 本栈经 compose 环境变量注入 MARMOT_DATABASE_*（值见 B2 篇），未走配置文件——与 3.3 的优先级结论自洽。

5.3 logging：level 与 format

默认 json（生产友好，可被日志采集器解析）。设 MARMOT_LOGGING_FORMAT=console 重建后，日志变为带颜色的单行人类可读格式（实测节选，ANSI 色码略）：

marmot-0.11.1-server  | 12:40AM INF Database schema is up to date version=53
marmot-0.11.1-server  | 12:40AM INF Anonymous telemetry enabled — learn more: https://marmotdata.io/docs/configure/telemetry — disable with telemetry.enabled: false or MARMOT_TELEMETRY_ENABLED=false
marmot-0.11.1-server  | 12:40AM INF Singleton task started interval=300000 lock_id=146787504315505105 task=asset-statistics-refresh
marmot-0.11.1-server  | 12:40AM INF Metrics service started (array-based storage, no aggregation jobs)
marmot-0.11.1-server  | 12:40AM INF Worker pool started max_workers=5 pool=notification-fanout queue_size=200

version=53 同时表明 schema 迁移已到最新版本。logging.level 支持 trace/debug/info/warn/error/fatal/panic，默认 info；排障时临时调 debug，生产保持 info。复原后日志回到 JSON 格式（实测 {"level":"info",...,"message":"Server started"} 行，见 3.4）。

5.4 auth：匿名访问与 SSO

• auth.anonymous.enabled 默认 false：匿名调 API 被拒（实测基线）：

$ curl -s -w '\nHTTP %{http_code}\n' 'http://localhost:8141/api/v1/search?q=orders'
{"error":"Authentication required"}

HTTP 401

设 MARMOT_AUTH_ANONYMOUS_ENABLED=true 重建后，同一请求免鉴权成功：

$ curl -s -o /dev/null -w 'anon /api/v1/search HTTP %{http_code}\n' 'http://localhost:8141/api/v1/search?q=orders'
anon /api/v1/search HTTP 200

• 复原变量并重建后，匿名请求回到 HTTP 401（实测），确认匿名开关即时随重启生效。
• auth.anonymous.role 决定匿名身份拿到的角色（默认 user），生产开匿名务必把该角色权限收敛到只读。
• SSO 八家 provider + 通用 OIDC 统一在 auth.<provider>.* 下，公共键 enabled/client_id/client_secret/url/redirect_url/scopes/allow_signup/team_sync/group_mapping（默认值见第四节总表）。redirect_url 要与 IdP 侧登记一致，且依赖 server.root_url 正确。本环境无外部 IdP，未做 SSO 端到端实测。
• auth.dcr.allowed_redirect_hosts：为空时动态注册（DCR）的 OAuth 客户端只允许 loopback 回调——这是给 claude.ai 之类托管 MCP 客户端留的口子，放开前想清楚。

5.5 search：超时与 Elasticsearch 后端

• search.timeout 默认 10 秒，作用于搜索查询。全文检索默认由 PostgreSQL（pg_trgm）承担，本环境实测搜索毫秒级返回（5.4 的匿名请求即证据），未触发超时。
• search.elasticsearch.* 为可选增强（深度模糊匹配）。未配置时的行为可用 CLI 管理命令实测：

$ ./bin/marmot admin reindex-status --host http://localhost:8141 --api-key "$KEY"
ES Configured: false
Running:       false
$ ./bin/marmot admin reindex --host http://localhost:8141 --api-key "$KEY"
Error: marmot: Elasticsearch is not configured

即：不配 ES 时检索走 PG，admin reindex 明确报错而不是静默；配了 ES 后 reindex 才有意义。

5.6 metrics：Prometheus 端点

默认 metrics.enabled:false、metrics.port:9090。设 MARMOT_METRICS_ENABLED=true 并临时映射 8149→9090 后实测：

$ curl -s -o /dev/null -w 'metrics HTTP %{http_code}\n' http://localhost:8149/metrics
metrics HTTP 200
$ curl -s http://localhost:8149/metrics | grep '^marmot_' | head -8
marmot_active_users 0
marmot_assets{has_schema="false",owner="marmot",provider="PostgreSQL",type="Database"} 3
marmot_assets{has_schema="false",owner="marmot",provider="PostgreSQL",type="Table"} 142
marmot_assets{has_schema="false",owner="marmot",provider="PostgreSQL",type="View"} 77
marmot_db_connections 0
marmot_db_queries_total{operation="unified_search",status="success"} 1
marmot_db_query_duration_seconds_bucket{operation="unified_search",status="success",le="0.001"} 0

（输出为节选；除 marmot_* 业务指标外还有 Go/进程运行时指标与 centrifuge 实时通道指标。）marmot_assets 按 provider/type 维度直接反映目录资产构成，可接 Grafana 告警。metrics.owner_metadata_fields 默认 owner, ownedBy, owningTeam，决定归属类统计读哪些元数据字段；metrics.schemas.excluded_asset_types 默认排除 Service 类型不计入模式覆盖率。复原变量后指标端口不再监听（实测 curl 连接被拒），确认默认关闭。

5.7 pipelines：摄取管道调度

四个键控制服务端管道执行：max_workers（默认 10，本实例并发处理上限）、scheduler_interval（默认 60 秒扫一次到期运行）、lease_expiry（默认 300 秒， abandoned 运行租约回收）、claim_expiry（默认 30 秒，未启动认领过期）。多实例高可用部署时这几个键是核心：租约机制保证同一 cron 运行只被一个实例执行。本环境单实例、管道稀少，重启日志可见调度器就绪（实测）：

{"level":"info","time":"2026-11-02T00:41:49Z","message":"Scheduler received plugin-ready signal; dispatching enabled"}

即调度分发要等插件加载完成后才开启（与 B2 篇排障四的 503 同源）。

5.8 plugins：注册表与自动安装

• plugins.autoinstall 默认 true：启动时从 ghcr.io/marmotdata/plugins 逐个拉取全部核心插件，首启代价见 B2 篇第六节（本环境直连 ghcr 每个插件约 1.5–2 分钟）。
• 本栈设 MARMOT_PLUGINS_AUTOINSTALL=false 并挂载预置缓存目录，实测重启后插件秒级就绪：

$ curl -s -H "Authorization: Bearer $KEY" http://localhost:8141/api/v1/plugins | head -c 150
{"plugins":[{"id":"nats","name":"NATS","description":"Discover JetStream streams from NATS servers","icon":"nats","c
$ curl -s -H "Authorization: Bearer $KEY" http://localhost:8141/api/v1/plugins | python3 -c "import json,sys;d=json.load(sys.stdin);print('count=',len(d['plugins']),'loading=',d['loading'])"
count= 71 loading= False

71 个插件全部从本地缓存加载、loading:false，无网络拉取。

• plugins.registry：把核心插件来源指向内网 OCI 镜像命名空间（离线环境必配），列表值逗号分隔。

5.9 ui：横幅与语言

设 MARMOT_UI_BANNER_ENABLED=true、MARMOT_UI_BANNER_MESSAGE、MARMOT_UI_BANNER_VARIANT=warning 后，免鉴权的 ui/config 立即反映（实测回显）：

$ curl -s http://localhost:8141/api/v1/ui/config
{"banner":{"enabled":true,"dismissible":true,"variant":"warning","message":"Scheduled maintenance 02:00-03:00","id":"banner-1"},"encryption_configured":true,"allow_unencrypted":false,"table_preview_enabled":true,"default_language":""}

variant 支持 info/warning/error/success；dismissible:true 时用户可关闭，ui.banner.id 是记忆关闭状态的标识——换文案记得同步换 id，否则老用户的「已关闭」状态会延续到新公告。ui.default_language 空值=跟随浏览器探测。

5.10 telemetry、experimental 与其他

• telemetry.enabled 默认 true（匿名使用遥测，端点 https://telemetry.marmotdata.io/v1/ingest，每 86400 秒上报）。实测启动日志直接给出关闭方法（console 格式日志原文）：

12:40AM INF Anonymous telemetry enabled — learn more: https://marmotdata.io/docs/configure/telemetry — disable with telemetry.enabled: false or MARMOT_TELEMETRY_ENABLED=false

内网/合规环境应显式 MARMOT_TELEMETRY_ENABLED=false。

• experimental.table_preview 默认 false；本次设 MARMOT_EXPERIMENTAL_TABLE_PREVIEW=true 后 ui/config 中 table_preview_enabled:true（见 5.9 回显），资产详情页出现样例行入口——该功能会直连数据源取样，开启前确认凭据与网络暴露面。
• operator.*（K8s operator 同步管道调度）、openlineage.auth.enabled（默认 true，OpenLineage 事件端点强制鉴权）、rate_limit.enabled（默认 false，进程内 API 限流）：本环境非 K8s、无 OpenLineage 事件源、单实例低并发，三项未做改配实测，语义以官方文档为准。

六、生产配置模板

以下为建议的生产 config.yaml 基线（键与默认值取自官方文档；内存/磁盘按 2C4G 小型自托管、目录资产 <10 万估算；注释标明场景取舍）：

server:
  host: 0.0.0.0
  port: 8080
  root_url: https://marmot.example.com        # 必填：OAuth/CLI 登录依赖；写用户真实访问 URL
  encryption_key: ${MARMOT_ENCRYPTION_KEY}    # 32 字节 base64，generate-encryption-key 生成；与备份同存
  # custom_response_headers:                  # 仅配置文件支持，如追加 CSP/X-Frame-Options
  #   Content-Security-Policy: "frame-ancestors 'none'"

database:
  host: db.example.com
  port: 5432
  user: marmot
  password: ${MARMOT_DB_PASSWORD}
  name: marmot
  sslmode: require                            # 跨主机连接务必 require/verify-full
  max_conns: 50                               # 默认即可；多实例部署按 实例数×50 核对 PG max_connections
  idle_conns: 25
  conn_lifetime: 5

logging:
  level: info
  format: json                                # 生产保持 json，采集器友好

auth:
  anonymous:
    enabled: false                            # 默认拒绝匿名；确需公开浏览再开并收紧角色

metrics:
  enabled: true                               # 生产显式打开，接 Prometheus/Grafana
  port: 9090

pipelines:
  max_workers: 10                             # 摄取量大时上调，同时核对数据源侧连接承受
  scheduler_interval: 60

plugins:
  registry: harbor.internal/marmotdata/plugins  # 内网镜像；离线环境必配
  autoinstall: false                          # 预置缓存后关闭，避免首启 2 小时级拉取（见 B2 篇）

telemetry:
  enabled: false                              # 合规/内网环境关闭匿名遥测

ui:
  banner:
    enabled: false

对应环境变量注入写法（与 3.3 优先级规则配套，compose 场景直接替换）：MARMOT_SERVER_ROOT_URL、MARMOT_DATABASE_SSLMODE、MARMOT_METRICS_ENABLED=true、MARMOT_PLUGINS_REGISTRY、MARMOT_TELEMETRY_ENABLED=false 等，列表值逗号分隔。

七、常见问题

7.1 改了 config.yaml 不生效？

确认文件在服务进程的工作目录下（默认查找当前目录的 config.yaml），或用 --config 显式指定；再看同名环境变量是否已设置——环境变量优先级更高（3.3 实测），compose 里的 MARMOT_* 会整体压过文件值。

7.2 嵌套键的环境变量名怎么拼？

全大写、前缀 MARMOT_、层级用下划线：server.tls.cert_path → MARMOT_SERVER_TLS_CERT_PATH。拿不准就对照第四节总表的键名机械转换；例外：server.custom_response_headers 无 env 通道。

7.3 不配 encryption_key 会怎样？

server.allow_unencrypted 默认 false，凭据存储被拒绝；ui/config 的 encryption_configured 为 false。密钥丢失等于目录内所有加密凭据作废，必须与数据库备份同存（见 B2 篇运维要点）。

7.4 匿名开关为什么 API 和网页表现不同？

auth.anonymous.enabled 只影响鉴权中间件；匿名身份拿 auth.anonymous.role（默认 user）的权限。开匿名后务必核对 user 角色权限面，敏感元数据场景保持 false（5.4 实测 401/200 切换）。

7.5 metrics 开了但 Prometheus 抓不到？

metrics.enabled 只是让服务进程在 metrics.port（默认 9090）起独立监听，编排/防火墙层要单独放行该端口——本环境实测未映射时宿主 curl 连接被拒，映射 8149→9090 后 HTTP 200（5.6）。

7.6 首启卡在插件下载、接口 503？

plugins.autoinstall 默认 true 时全量拉 70+ 插件，慢网络下可达小时级；期间摄取相关接口 503。方案见 B2 篇第六节（预置缓存 + MARMOT_PLUGINS_AUTOINSTALL=false，实测秒级就绪、71 插件 loading:false）。

7.7 配置改动需要重启吗？

需要。Marmot 无热加载，实测所有生效验证都经 docker compose up -d 重建完成；服务重启秒级、schema 自动校验（日志 Database schema is up to date version=53）。

八、参考链接

• 官方配置文档：https://marmotdata.io/docs/Configure （Version 0.11，Last updated Nov 1, 2026）
• 遥测说明：https://marmotdata.io/docs/configure/telemetry
• TLS / 匿名访问 / 横幅 / Elasticsearch 专题：marmotdata.io/docs 对应 Configure 子页
• 版本发布：https://github.com/marmotdata/marmot/releases （2026-11-02 实查 latest=v0.11.1）
• 站内：《Marmot 数据目录：介绍与选型指南》、《Marmot 0.11.1 Docker Compose 部署指南》、《Marmot 0.11.1 常用 CLI 命令详解》