MAN-GL-0042-2X · 参数手册 · 适用 guanlan-agent 2.6.x · 密级 内部

观澜采集代理(guanlan-agent)参数手册

版本 v2.6.3  ·  更新 2026-10-18  ·  维护 zhou.qi(观澜组) ·  复核 xu.mo  ·  文档编号 MAN-GL-0042-2X

本手册列出 guanlan-agent 2.6.x 的全部公开配置参数、环境变量映射、错误码与排障附录。参数表由启动时的参数注册表导出,与代码版本严格一致;手工维护的说明文字可能滞后于最新补丁版本,以注册表为准。文中主机名、地址与示例数据均为内部命名与合成值。

1. 配置加载与合并顺序

代理按固定顺序加载配置,后加载的层覆盖先加载的层。合并是逐键进行的,列表类型整体替换而不是追加。启动日志会打印每一层的来源文件与最终生效的键数量,排障时先看这行日志。

  1. 编译内置默认值:参数注册表中的默认值,任何情况下都存在。
  2. 主配置文件:/etc/guanlan/agent.yaml,安装时生成,不建议手改敏感字段。
  3. 片段目录:/etc/guanlan/conf.d/*.yaml,按文件名字典序加载,适合按数据集拆配置。
  4. 环境变量:GL_ 前缀,见第 3 节;适合容器化部署与密钥注入。
  5. 命令行参数:仅限少数运行期参数(--config、--mode、--dry-run),优先级最高。
合并示例:主配置写 source.s3.max_conns: 32,片段目录写 max_conns: 48,环境变量再设 GL_SRC_S3_MAX_CONNS=64,最终生效值为 64。启动日志中的 cfg_layers 字段会标出每层贡献的键数。

热加载只覆盖标注为 reloadable 的参数(约占参数总数的三分之一),其余参数修改后需要重启。热加载失败的配置会被整体拒绝,代理继续使用上一份有效配置,同时 guanlan_agent_config_error 置 1。

2. 参数总表

共 13 组、约 300 个参数。表中「起始」列是该参数首次出现的版本;更早的配置文件里出现这些参数会被视为未知键,在 misc.config_strict=true 时导致启动失败。「约束 / 备注」列给出取值范围与工程注意事项,未标注者表示没有额外限制。

2.1 核心运行参数

进程、目录、实例与生命周期相关的参数。生产环境通常只需要关注 agent.max_workers、agent.data_dir 与 agent.shutdown_grace 三项。

参数类型默认值起始说明约束 / 备注
agent.idstringgz-agent-011.0.0代理实例标识,安装脚本默认写入主机名长度 1–64,需全局唯一
agent.modeenumdaemon1.0.0运行模式:daemon 常驻、once 单次执行后退出、check 只做配置校验升级前建议先跑 check
agent.instancestring空2.1.0同主机多实例时的实例名,参与锁文件与指标标签仅小写字母、数字和连字符
agent.tagsstring-list[]1.2.0自定义标签,随指标与日志上报键值对数量不超过 32
agent.data_dirpath/var/lib/guanlan1.0.0状态、offset 与本地缓存根目录需可写,剩余空间不小于 10GiB
agent.run_dirpath/run/guanlan1.0.0pid、锁文件与临时套接字的目录可放在 tmpfs
agent.log_dirpath/var/log/guanlan1.0.0日志根目录按 100MiB 滚动,保留 7 份
agent.workspacepath/data/workspace1.1.0下载与转换使用的临时工作区建议独立磁盘,容量不小于 200GiB
agent.max_workersint81.0.0采集工作协程数,决定并发任务上限不超过 CPU 核数的 2 倍
agent.thread_pool_sizeint322.0.0IO 线程池大小,源端与目标端共享高延迟链路可上调到 64
agent.process_priorityint02.2.0进程 nice 值,正值降低优先级负值仅 root 可设
agent.shutdown_graceduration45s1.0.0收到 SIGTERM 后等待任务收尾的时长超时后强制退出
agent.pid_filepath/run/guanlan/agent.pid1.0.0pid 文件路径多实例必须分别指定
agent.userstringguanlan1.0.0运行用户,需对 data_dir 有写权限不建议用 root 运行
agent.groupstringguanlan1.0.0运行用户组与 user 保持一致
agent.umaskstring00271.0.0新建文件的权限掩码过于宽松的值会被拒绝启动
agent.timezonestringAsia/Shanghai1.0.0日志与调度使用的时区影响 cron 表达式解释
agent.localestringzh_CN.UTF-81.0.0排序与字符处理使用的 locale容器内需安装对应 locale
agent.fs_syncbooltrue1.3.0写完检查点后是否 fsync关闭可提吞吐,但断电会丢状态
agent.file_lockenumflock1.0.0单实例锁实现:flock 或 pidpid 方式已不推荐
agent.lock_timeoutduration10s1.0.0获取实例锁的等待上限超时退出码为 12
agent.daemonizebooltrue1.0.0是否后台化运行容器内建议 false,由 entrypoint 托管
agent.health_addraddr10.42.7.23:91202.2.0健康检查监听地址仅监听内网地址
agent.health_liveness_pathstring/healthz2.2.0存活探针路径返回 200 表示进程存活
agent.health_readiness_pathstring/ready2.2.0就绪探针路径有任务运行也返回就绪
agent.admin_enabledboolfalse2.3.0是否开启本机管理接口默认关闭,排障时才打开
agent.admin_addraddrloopback:91212.3.0管理接口监听地址不要绑定到所有网卡
agent.plugin_dirpath/usr/lib/guanlan/plugins2.0.0插件目录只加载白名单内插件
agent.plugin_whiteliststring-list[s3,posix]2.0.0允许加载的插件名修改后需重启生效
agent.config_reload_intervalduration60s2.4.0配置热加载检查间隔仅部分参数支持热加载
agent.config_dump_on_startboolfalse2.5.0启动时打印合并后的配置(已脱敏)含敏感引用时不要开启
agent.crash_dump_dirpath/var/crash/guanlan2.5.2panic 转储目录空间不足时会自动关闭转储

2.2 source.s3 — 源端对象存储

北辰智能、云雀数据等合作方以 S3 协议提供共享桶,源端参数较长,与网络质量、源端实现差异相关。2.6.0 新增的分片列举参数用于规避北辰列举分页不稳定的问题。

参数类型默认值起始说明约束 / 备注
source.s3.endpointstring必填1.0.0源端 S3 兼容服务地址,形如 beichen.internal:9000不带协议前缀
source.s3.bucketstring必填1.0.0源桶名需在合作协议约定的共享桶范围内
source.s3.regionstringcn-north-71.0.0区域标识,北辰只提供单一区域写错不报错,会落到默认池
source.s3.path_stylebooltrue1.0.0是否使用路径风格寻址北辰必须为 true
source.s3.access_key_refstringenv:GL_SRC_ACCESS_KEY1.1.0访问键引用,支持 env: 与 file: 前缀禁止内联明文
source.s3.secret_key_refstringenv:GL_SRC_SECRET_KEY1.1.0密钥引用同上
source.s3.session_token_refstring空1.4.0临时密钥的会话令牌引用留空表示使用长期键
source.s3.prefixstring空1.0.0起始前缀,只采集该前缀下的对象末尾不加斜杠也可以
source.s3.include_patternsstring-list["*.parquet","*.json"]1.0.0包含匹配规则只支持 fnmatch 通配
source.s3.exclude_patternsstring-list["_SUCCESS","*.tmp"]1.0.0排除匹配规则优先于包含匹配
source.s3.connect_timeoutduration5s1.0.0建连超时跨机房建议 8s
source.s3.read_timeoutduration60s1.3.0单次读超时大对象可放宽到 120s
source.s3.max_retriesint31.0.0源端失败重试次数0 表示不重试
source.s3.retry_backoff_minduration200ms2.1.0退避下限不得小于 50ms
source.s3.retry_backoff_maxduration30s2.1.0退避上限不得小于退避下限
source.s3.retry_jitterfloat0.22.1.0退避抖动比例取值 0 到 1
source.s3.max_connsint321.0.0最大连接数单代理建议不超过 64
source.s3.max_idle_connsint161.2.0空闲连接上限不超过 max_conns
source.s3.idle_conn_timeoutduration90s1.2.0空闲连接回收时间短于源端 keepalive 时会更频繁建连
source.s3.part_sizebytes64MiB1.0.0分片大小对象大于 1GiB 时上调
source.s3.max_concurrencyint81.0.0单任务对象并发数过高容易触发源端限流
source.s3.checksumenumsha2561.2.0对象校验算法:sha256、md5、crc32北辰的 ETag 不能当 MD5 使用
source.s3.verify_on_readboolfalse1.5.0读时校验,代价较高排障时可临时开启
source.s3.shard_listboolfalse2.6.0按前缀分片列举,规避北辰分页不稳定北辰源建议设为 true
source.s3.shard_prefix_bytesint22.6.0分片前缀字节数,2 对应 256 个分片取值 1 到 3
source.s3.verify_object_countboolfalse2.6.0列举完成后用对象总数校验完整性需要桶级读权限
source.s3.list_page_sizeint10001.0.0单次列举返回条数北辰上限 1000
source.s3.list_max_pagesint02.4.0列举最大页数,0 表示不限用于防止异常桶导致死循环
source.s3.stat_before_readboolfalse2.5.0读前先 HEAD 获取对象大小可减少无效读与 404
source.s3.range_sizebytes16MiB2.2.0Range 读块大小与 read_buffer 独立
source.s3.read_bufferbytes1MiB1.3.0读缓冲大小大对象可调到 4MiB
source.s3.tls.enabledbooltrue1.1.0源端是否走 TLS北辰内网同样强制 TLS
source.s3.tls.ca_filepath/etc/guanlan/tls/ca.pem1.1.0CA 证书文件需与源端证书链匹配
source.s3.tls.server_namestring空1.2.0SNI 名称,留空则用 endpoint证书为多域名时必填
source.s3.tls.min_versionenumTLS1_22.2.0最低 TLS 版本TLS1_0 与 TLS1_1 已禁用
source.s3.tls.insecure_skip_verifyboolfalse1.1.0跳过证书校验,仅联调时临时使用生产开启会触发审计告警
source.s3.proxystring空2.3.0内网代理地址(只写主机与端口)仅隔离网段需要
source.s3.rate_limit_qpsuint02.4.0源端请求限速,0 表示不限按实例计算
source.s3.rate_limit_burstuint02.4.0限速突发桶大小为 0 时取 QPS 的 3 倍
source.s3.follow_redirectsboolfalse2.5.2是否跟随重定向对象存储一般不需要
source.s3.user_agentstringguanlan-agent/2.6.31.4.0请求的 User-Agent便于源端侧识别调用来源
source.s3.secret_headerstringX-Beichen-Sign2.6.0签名头名称北辰兼容层不支持 query 签名

2.3 source.posix — 源端 POSIX 文件系统

息壤 POSIX 网关挂载到本机时使用。注意 read_only 与 move_after_read 存在冲突,生产建议只读。

参数类型默认值起始说明约束 / 备注
source.posix.rootpath/xiran/inbox1.0.0POSIX 源根目录必须为已挂载的息壤导出路径
source.posix.read_onlybooltrue1.0.0是否只读打开源文件建议保持 true
source.posix.follow_symlinksboolfalse1.1.0是否跟随符号链接安全考虑默认禁止
source.posix.max_open_filesint20481.2.0单进程打开文件上限需与系统 ulimit 同步
source.posix.read_bufferbytes4MiB1.3.0顺序读缓冲大小大文件可调到 16MiB
source.posix.dir_batch_sizeint50001.4.0目录遍历单批返回条数超大目录建议降到 2000
source.posix.ignore_hiddenbooltrue1.0.0忽略点文件与点目录—
source.posix.ignore_patternsstring-list[".nfs*","*.swp"]1.0.0忽略规则NFS 临时文件多时可加 "*~"
source.posix.sort_orderenumname1.5.0遍历顺序:name 或 mtime断点续采建议用 mtime
source.posix.scan_intervalduration300s1.2.0周期性扫描间隔配合 rescan 模式使用
source.posix.stability_waitduration30s1.6.0文件大小稳定判定等待写入中的大文件必需
source.posix.stability_checksint21.6.0稳定性检查次数两次间隔为 stability_wait
source.posix.owner_checkboolfalse1.7.0是否校验文件所有者跨部门共享盘建议开启
source.posix.mount_checkbooltrue2.0.0启动时校验挂载点是否有效防止采集到空目录
source.posix.mount_timeoutduration10s2.0.0挂载点检测超时—
source.posix.checksum_algorithmenumsha2561.2.0校验算法需与目标端一致
source.posix.checksum_workersint41.8.0校验并发线程数属 IO 密集,不宜过大
source.posix.sparse_handlingenumskip1.9.0稀疏文件处理:skip 跳过或 zero 补零skip 可能导致大小不一致
source.posix.xattr_readboolfalse2.1.0是否读取扩展属性作为元数据息壤网关不保证支持
source.posix.move_after_readboolfalse2.3.0读完后移动到 done 子目录需要写权限,与只读模式冲突
source.posix.max_file_sizebytes01.9.0单文件大小上限,0 表示不限防止误采超大镜像
source.posix.min_file_sizebytes02.2.0小于该值的文件跳过标注小文件可设 1KiB
source.posix.inode_checkboolfalse2.4.0是否记录 inode 防止重复采集在 NFS 上不可靠,默认关闭

2.4 transform — 转换与归一化

schema 校验、字段映射、脱敏、分区与压缩。转换阶段参数较多,误配会直接影响下游查询,建议变更前在测试数据集上跑 check。

参数类型默认值起始说明约束 / 备注
transform.enabledbooltrue1.0.0是否启用转换阶段关闭时源格式直传
transform.format_detectenumauto1.0.0格式识别:auto 按扩展名与文件头判断自动识别失败会回退扩展名
transform.schema_registrypath/etc/guanlan/schema/2.0.0schema 注册目录,每个数据集一个 yaml—
transform.strict_schemaboolfalse2.1.0schema 不匹配时是否直接失败生产建议开启
transform.drop_unknown_fieldsbooltrue2.1.0是否丢弃 schema 之外的字段关闭则原样透传
transform.field_caseenumkeep2.2.0字段名大小写策略:keep、lower、snake变更会影响下游查询
transform.timestamp_columnstringcapture_time1.2.0时间戳列名,用于分区与排序—
transform.timestamp_formatstringrfc33391.2.0时间戳解析与输出格式也支持 unix_seconds
transform.timezone_convertbooltrue1.5.0是否统一转换为 Asia/Shanghai跨时区源需要开启
transform.encrypt_fieldsstring-list[]2.3.0需要加密的字段名列表使用所内对称密钥加密
transform.mask_rules_filepath空2.3.0脱敏规则文件路径规则语法见附录 C
transform.dedup_enabledbooltrue1.8.0是否按主键去重大数据集代价较高
transform.dedup_windowduration24h1.8.0去重窗口0 表示全量窗口
transform.dedup_keysstring-list[sample_id]1.8.0去重主键必须存在于 schema 中
transform.aggregation_enabledboolfalse2.0.0是否做预聚合仅统计类数据集需要
transform.aggregation_intervalduration1h2.0.0预聚合时间窗—
transform.filter_expressionstring空2.2.0行过滤表达式(受限语法)不允许子查询与函数调用
transform.row_limituint01.9.0单任务最大行数,0 表示不限防止误采超大表
transform.column_whiteliststring-list[]2.4.0只保留的列与黑名单互斥
transform.column_blackliststring-list[]2.4.0排除的列优先于白名单
transform.rename_mapmap{}2.4.0字段重命名映射,键为源字段名目标字段名需唯一
transform.partition_bystring-list[site,capture_date]1.3.0输出分区键应为低基数字段
transform.max_partitionsint20001.7.0单任务分区数上限超过时需按时间拆分任务
transform.compressionenumzstd2.0.0中间结果压缩:zstd、snappy、none下游需要能解压
transform.compression_levelint32.0.0压缩级别 1 到 9高并发时建议降到 1
transform.batch_rowsint655361.1.0每批转换行数内存紧张时降低
transform.batch_bytesbytes64MiB1.1.0每批字节上限与 batch_rows 同时生效
transform.dictionary_encodebooltrue2.2.0低基数字段是否字典编码—
transform.timeoutduration3600s1.4.0单批转换超时超大文件可放宽到 7200s
transform.on_errorenumfail1.6.0错误处理:fail、skip、quarantine生产建议 fail 或 quarantine
transform.quarantine_dirpath/var/lib/guanlan/quarantine2.5.0隔离区目录skip 与 quarantine 时使用
transform.parquet_row_group_sizeint2621441.9.0parquet row group 行数—
transform.parquet_page_sizebytes1MiB1.9.0parquet 页大小—
transform.source_encodingstringutf-82.1.0文本类源的字符编码转换失败会写入隔离区

2.5 sink — 目标端写入

写入息壤对象存储。2.6.0 起增加写队列与在途字节限制,起因是 2026-09-11 的 OOM 扩散事件中写队列被检查点重试打满。

参数类型默认值起始说明约束 / 备注
sink.typeenums31.0.0目标类型:s3 或 posix优先使用 s3 接口
sink.endpointstringxiran.internal:90001.0.0目标端地址不带协议前缀
sink.bucketstringxiran-prod1.0.0目标桶名—
sink.regionstringcn-north-71.0.0目标区域—
sink.path_templatestringguanlan/{dataset}/{yyyyq}/1.0.0目标路径模板,支持占位符模板变量见 2.14 节
sink.path_stylebooltrue1.0.0是否路径风格寻址—
sink.access_key_refstringenv:GL_SINK_ACCESS_KEY1.1.0访问键引用—
sink.secret_key_refstringenv:GL_SINK_SECRET_KEY1.1.0密钥引用—
sink.part_sizebytes64MiB1.0.0分片大小不得小于 8MiB
sink.multipart_thresholdbytes128MiB1.0.0启用分片上传的阈值—
sink.max_concurrencyint81.0.0并发上传数受网络带宽约束
sink.max_retriesint51.0.0上传失败重试次数—
sink.retry_backoff_minduration500ms2.1.0退避下限—
sink.retry_backoff_maxduration60s2.1.0退避上限—
sink.retry_on_5xxbooltrue2.1.05xx 是否重试—
sink.retry_on_4xxboolfalse2.1.04xx 是否重试默认不重试,避免无效循环
sink.connect_timeoutduration5s1.0.0建连超时—
sink.write_timeoutduration120s1.0.0单次写超时大分片建议 180s
sink.checksumenumsha2561.2.0上传校验算法—
sink.verify_after_writeboolfalse2.2.0写后读回校验代价高,排障时使用
sink.checksum_metadatabooltrue2.3.0是否写入自定义校验元数据元数据总大小不超过 2KB
sink.idempotent_keysbooltrue2.4.0同名对象覆盖而非重复依赖对象名确定性
sink.staging_prefixstring_staging/2.4.0上传中转前缀完成后原子移动
sink.atomic_commitbooltrue2.4.0是否启用中转加移动语义—
sink.lifecycle_tierenumstandard2.5.0存储层级:standard、archivearchive 不可即时读取
sink.bucket_quota_checkbooltrue2.6.0写入前检查桶配额使用率到 90% 时告警
sink.bucket_quota_warn_ratiofloat0.92.6.0配额告警阈值取值 0 到 1
sink.max_inflight_bytesbytes2GiB2.6.0同时在途字节上限防止打满存储网关
sink.write_queue_depthint2562.6.0写队列深度来自 2026-09 事件的调优值
sink.backpressure_waitduration30s2.6.0队列满时等待时长超时后暂停任务
sink.notify_topicstringguanlan-ingest2.2.0写完成后通知的内部消息主题不使用站外地址
sink.notify_onstring-list[success,failure]2.2.0通知时机—
sink.cleanup_stagingbooltrue2.5.0完成后清理中转对象—

2.6 checkpoint — 检查点与断点续传

断点续传依赖检查点与任务锁。检查点写坏是本代理最常见的故障来源,排障时先看 checkpoint 目录与 GL-E-5xxx 错误码。

参数类型默认值起始说明约束 / 备注
checkpoint.enabledbooltrue1.0.0是否启用断点续传—
checkpoint.dirpath/var/lib/guanlan/ckpt1.0.0检查点目录需持久化磁盘
checkpoint.intervalduration30s1.0.0检查点写入间隔—
checkpoint.records_intervaluint5000001.0.0按记录数触发检查点与时间间隔取先到条件
checkpoint.max_sizebytes512MiB2.0.0单个检查点文件上限超限会触发压缩
checkpoint.compressbooltrue2.1.0检查点是否 zstd 压缩—
checkpoint.keepint31.0.0保留的历史检查点个数滚动删除最旧
checkpoint.keep_daysint142.2.0检查点保留天数与 keep 共同生效
checkpoint.fsyncbooltrue1.3.0写入后是否落盘依赖 agent.fs_sync
checkpoint.atomic_writebooltrue1.4.0使用临时文件加 rename 原子写—
checkpoint.upload_to_sinkboolfalse2.3.0是否把检查点同步到目标桶—
checkpoint.upload_prefixstring_ckpt/{agent_id}/2.3.0检查点上传前缀—
checkpoint.lock_ttlduration120s2.0.0任务锁有效期—
checkpoint.lock_renewduration30s2.0.0锁续期间隔需小于 lock_ttl 的一半
checkpoint.orphan_scan_intervalduration600s2.4.0孤儿任务扫描间隔—
checkpoint.orphan_ttlduration86400s2.4.0孤儿任务回收时间—
checkpoint.resume_modeenumoffset1.5.0恢复方式:offset、records、restartoffset 最精确
checkpoint.max_resume_attemptsint32.2.0同一任务的恢复尝试上限超过后转 failed
checkpoint.state_file_modestring06002.1.0状态文件权限—
checkpoint.backup_on_resumebooltrue2.5.0恢复前是否备份检查点—
checkpoint.hash_verifyboolfalse2.5.2恢复时校验 offset 一致性—
checkpoint.flush_on_shutdownbooltrue2.5.4退出前强制写检查点—
checkpoint.pause_on_backlogbooltrue2.6.0写队列积压时暂停检查点来自 2026-09 复盘改进项
checkpoint.backlog_thresholdint40962.6.0积压判定条数与 sink.write_queue_depth 联动

2.7 retry — 重试与退避

2.6.0 起重试有上限(默认 5 次),这是一次不兼容调整:老配置文件里写 retry.retry_forever=true 的会在启动时被拒绝,需手工迁移。

参数类型默认值起始说明约束 / 备注
retry.enabledbooltrue1.0.0全局重试开关—
retry.policyenumexponential1.0.0策略:fixed、exponential、linear—
retry.max_attemptsint51.0.0最大尝试次数,包含首次2.6.0 起由无限重试改为有上限
retry.initial_intervalduration1s1.0.0初始间隔—
retry.multiplierfloat2.01.0.0指数倍数—
retry.max_intervalduration60s1.0.0最大间隔—
retry.jitterfloat0.22.1.0抖动比例0 到 1
retry.retryable_codesstring-list[]2.2.0额外视为可重试的错误码按 GL-E 编号填写
retry.non_retryable_codesstring-list[]2.2.0显式不可重试的错误码优先于 retryable_codes
retry.max_elapsedduration1800s2.3.0总重试时长上限—
retry.reset_on_progressbooltrue2.3.0有进度时是否重置计数—
retry.on_exhaustedenumfail2.0.0重试耗尽后动作:fail、skip、quarantine—
retry.notify_on_exhaustedbooltrue2.4.0耗尽时是否发通知通知走站内工单主题
retry.concurrent_limitint642.4.0重试并发上限避免重试风暴
retry.retry_unsafe_opsboolfalse2.5.0是否重试非幂等写操作默认禁止
retry.backoff_cap_factorfloat3.02.6.0退避上限相对 max_interval 的倍数—

2.8 tls — 证书与传输安全

内部链路也要求 TLS。跳过校验的参数仅用于联调,生产环境开启会触发审计告警。

参数类型默认值起始说明约束 / 备注
tls.enabledbooltrue1.0.0全局 TLS 开关内部链路也建议开启
tls.ca_filepath/etc/guanlan/tls/ca.pem1.0.0CA 证书—
tls.cert_filepath/etc/guanlan/tls/agent.crt1.0.0客户端证书,双向认证时使用—
tls.key_filepath/etc/guanlan/tls/agent.key1.0.0客户端私钥权限必须为 0600
tls.min_versionenumTLS1_22.0.0最低 TLS 版本—
tls.cipher_suitesstring-list[]2.0.0允许的套件列表留空使用库默认值
tls.server_namestring空1.2.0SNI 名称多域名证书时必填
tls.insecure_skip_verifyboolfalse1.0.0跳过证书校验生产禁用
tls.reload_intervalduration02.3.0证书热加载间隔,0 表示关闭—
tls.ocsp_enabledboolfalse2.4.0是否做 OCSP 检查内网无 OCSP 服务,保持关闭
tls.verify_hostnamebooltrue2.2.0是否校验证书主机名—
tls.client_authboolfalse2.1.0是否要求客户端证书仅内部双向认证链路

2.9 scheduler — 调度与时间窗

代理内置轻量调度器,负责扫描、拆分与时间窗控制。若接入外部调度(如 Airflow),建议把 scheduler.enabled 设为 false。

参数类型默认值起始说明约束 / 备注
scheduler.enabledbooltrue1.0.0是否启用内置调度器—
scheduler.scan_intervalduration60s1.0.0源目录或桶的扫描间隔—
scheduler.max_tasksint321.0.0并行任务数上限受 agent.max_workers 约束
scheduler.task_queue_sizeint2561.2.0任务队列长度—
scheduler.lease_ttlduration120s2.0.0任务租约时长—
scheduler.lease_renewduration40s2.0.0租约续期间隔—
scheduler.cronstring空1.3.0定时触发表达式,5 字段时区由 agent.timezone 决定
scheduler.window_startstring空2.2.0允许执行的时间窗起点形如 22:00
scheduler.window_endstring空2.2.0允许执行的时间窗终点形如 05:00
scheduler.max_window_lagduration600s2.2.0错过时间窗的补跑上限—
scheduler.task_split_recordsuint200000001.4.0超过该记录数时拆分任务与 v2 单任务上限一致
scheduler.task_split_bytesbytes512GiB2.1.0按字节拆分任务的阈值—
scheduler.rebalance_intervalduration300s2.3.0任务重平衡检查间隔—
scheduler.sticky_partitionbooltrue2.3.0分片是否粘性绑定到代理—
scheduler.blackout_datesstring-list[]2.4.0禁跑日期,ISO 日期格式—
scheduler.priority_classesmap{}2.4.0任务优先级分类配置键为任务名前缀
scheduler.lower_priority_whenduration02.5.0运行超过该时长后降级0 表示不降级
scheduler.pause_on_source_errorbooltrue2.5.0源端连续失败时是否暂停扫描—
scheduler.source_error_thresholdint102.5.0连续失败次数阈值—
scheduler.dst_adjustbooltrue2.6.0是否做夏令时调整仅海外合作方源需要

2.10 resource — 资源限制

与 cgroup 协作的资源限制参数。容器部署时部分参数会被编排层覆盖,以实际 cgroup 为准。

参数类型默认值起始说明约束 / 备注
resource.cpu_limitstring空2.0.0软 CPU 限制,写入 cgroup容器内由编排层覆盖
resource.memory_limitstring空2.0.0软内存限制—
resource.memory_warn_ratiofloat0.852.2.0内存告警水位—
resource.memory_reservebytes2GiB2.4.0预留内存,避免本进程被 OOM—
resource.disk_warn_ratiofloat0.82.1.0工作区磁盘告警水位—
resource.disk_critical_ratiofloat0.922.1.0磁盘危险水位,触发暂停—
resource.max_temp_filesint2000002.3.0工作区临时文件数量上限—
resource.temp_gc_intervalduration300s2.3.0临时文件回收间隔—
resource.max_file_descriptorsint655352.0.0文件描述符上限不得超过系统 ulimit
resource.io_weightint5002.4.0cgroup IO 权重1 到 1000
resource.cpu_weightint5002.4.0cgroup CPU 权重1 到 10000
resource.network_bandwidth_limitstring空2.6.0网络带宽限制,如 400MiB跨机房链路使用
resource.network_burstbytes64MiB2.6.0带宽突发桶—
resource.pause_on_memory_pressurebooltrue2.6.0内存压力时是否暂停新任务—

2.11 metrics — 指标暴露

指标前缀与标签直接影响重明侧的基数。新开标签前先估算基数,超过 5000 会被丢弃。

参数类型默认值起始说明约束 / 备注
metrics.enabledbooltrue1.0.0是否暴露指标端点—
metrics.addraddr10.42.7.23:91091.0.0指标监听地址仅内网地址
metrics.pathstring/metrics1.0.0指标拉取路径—
metrics.intervalduration15s2.2.0内部聚合间隔—
metrics.prefixstringguanlan_agent1.0.0指标前缀变更会影响看板
metrics.labelsmap{}1.2.0附加标签注意标签基数
metrics.task_labelsbooltrue2.3.0是否按任务打标签任务多时基数较高
metrics.max_label_cardinalityint50002.4.0标签基数上限超限后丢弃新标签
metrics.histogram_bucketsstring-list[]2.2.0直方图桶边界留空使用默认值
metrics.include_runtime_metricsbooltrue1.0.0是否包含运行时指标—
metrics.expose_checkpoint_sizeboolfalse2.3.0是否暴露检查点大小—
metrics.expose_source_latencybooltrue2.2.0源端延迟指标—
metrics.expose_sink_latencybooltrue2.2.0目标端延迟指标—
metrics.push_gatewaystring空2.5.0推送网关地址,留空为拉取模式—
metrics.push_intervalduration60s2.5.0推送间隔—
metrics.profile_enabledboolfalse2.3.0是否开启性能采样接口仅排障时临时开启
metrics.profile_addraddrloopback:91102.3.0性能采样监听地址—

2.12 log — 日志与审计

日志与审计分离;审计日志不随普通日志滚动策略清理,需定期归档。

参数类型默认值起始说明约束 / 备注
log.levelenuminfo1.0.0日志级别:debug、info、warn、error排障时临时开 debug
log.formatenumtext1.0.0格式:text 或 json采集到重明建议 json
log.filepath/var/log/guanlan/agent.log1.0.0日志文件路径—
log.max_sizebytes100MiB1.0.0单文件滚动阈值—
log.max_backupsint71.0.0保留份数—
log.max_ageint141.0.0保留天数—
log.compressbooltrue1.2.0滚动后是否压缩—
log.sanitizebooltrue2.0.0是否脱敏访问键与令牌生产必须开启
log.sanitize_fieldsstring-list[secret,token,authorization]2.0.0额外脱敏字段名—
log.include_task_idbooltrue2.1.0日志中是否带任务 ID—
log.samplingboolfalse2.2.0是否采样输出高吞吐时段可开启
log.sample_ratiofloat0.12.2.0采样比例0 到 1
log.consolebooltrue1.0.0是否输出到标准输出容器部署保持 true
log.console_formatenumtext2.1.0控制台输出格式—
log.audit_filepath/var/log/guanlan/audit.log2.3.0审计日志文件记录配置变更与权限操作
log.audit_levelenuminfo2.3.0审计日志级别—

2.13 misc — 其他

干跑、版本检查、排障包等杂项参数。

参数类型默认值起始说明约束 / 备注
misc.dry_runboolfalse1.0.0干跑模式,只扫描不写入首次接入建议开启
misc.exit_code_on_warnboolfalse2.2.0存在 warning 时是否返回非零退出码CI 场景使用
misc.usage_stats_enabledboolfalse1.5.0是否上报内部使用统计仅上报到重明本机端点
misc.usage_stats_endpointstringchongming.internal:43171.5.0统计上报端点内部地址
misc.version_checkboolfalse2.0.0是否检查版本兼容性离线环境关闭
misc.expected_versionstring2.6.32.0.0期望版本,不匹配时告警—
misc.experimental_featuresstring-list[]2.4.0开启的实验特性生产禁用
misc.env_prefixstringGL_1.1.0环境变量前缀—
misc.config_strictbooltrue2.3.0未知配置项是否报错建议 true
misc.watch_configbooltrue2.4.0是否监听配置文件变化—
misc.metrics_flush_on_exitbooltrue2.5.0退出前是否刷新指标—
misc.notify_channelenumticket2.2.0通知渠道:ticket 或 none—
misc.support_bundle_dirpath/var/lib/guanlan/support2.5.0排障包输出目录—
misc.support_bundle_redactbooltrue2.5.0排障包是否脱敏—
misc.clock_skew_warnduration5s2.6.0时钟偏差告警阈值签名场景需要

2.14 sink.path_template 占位符

目标路径模板支持以下占位符,渲染时按 UTC 与 agent.timezone 分别取值;拼写错误的占位符会原样保留并给出 warning,不会导致任务失败。

占位符含义示例
{dataset}数据集名,与 source 配置中的 dataset 一致camera-calib-2026q4
{dataset_id}数据集内部 ID,v2 为字符串 slugcamera-calib-2026q4
{yyyy}四位年份2026
{yyyyq}年份加季度2026q4
{yyyymm}年月202610
{yyyymmdd}年月日20261014
{agent_id}代理实例标识gz-agent-01
{task_id}任务 IDcj_7f3a91
{partition}分区表达式渲染结果site=yehang-a
{shard}分片序号,补零到 4 位0003

3. 环境变量映射

下表中的环境变量优先级高于配置文件。容器部署时,密钥类字段必须通过环境变量注入,不得写进镜像或配置文件。环境变量只在进程启动时读取一次,运行期修改需要重启(热加载不覆盖环境变量)。

环境变量对应参数说明
GL_AGENT_IDagent.id实例标识,优先于配置文件
GL_AGENT_MODEagent.mode运行模式
GL_AGENT_DATA_DIRagent.data_dir状态目录
GL_AGENT_MAX_WORKERSagent.max_workers并发工作协程数
GL_AGENT_TAGSagent.tags标签,逗号分隔
GL_LOG_LEVELlog.level日志级别
GL_LOG_FORMATlog.format日志格式
GL_METRICS_ADDRmetrics.addr指标监听地址
GL_SRC_S3_ENDPOINTsource.s3.endpoint源端地址
GL_SRC_S3_BUCKETsource.s3.bucket源桶
GL_SRC_S3_REGIONsource.s3.region源端区域
GL_SRC_ACCESS_KEYsource.s3.access_key_ref源端访问键(引用目标是密钥本身)
GL_SRC_SECRET_KEYsource.s3.secret_key_ref源端密钥
GL_SRC_S3_PREFIXsource.s3.prefix源前缀
GL_SRC_S3_MAX_CONNSsource.s3.max_conns源端连接数
GL_SRC_S3_SHARD_LISTsource.s3.shard_list是否分片列举
GL_SRC_POSIX_ROOTsource.posix.rootPOSIX 源根目录
GL_SINK_ENDPOINTsink.endpoint目标端地址
GL_SINK_BUCKETsink.bucket目标桶
GL_SINK_REGIONsink.region目标区域
GL_SINK_ACCESS_KEYsink.access_key_ref目标端访问键
GL_SINK_SECRET_KEYsink.secret_key_ref目标端密钥
GL_SINK_PATH_TEMPLATEsink.path_template目标路径模板
GL_SINK_PART_SIZEsink.part_size分片大小
GL_CHECKPOINT_DIRcheckpoint.dir检查点目录
GL_CHECKPOINT_INTERVALcheckpoint.interval检查点间隔
GL_RETRY_MAX_ATTEMPTSretry.max_attempts最大重试次数
GL_TLS_CA_FILEtls.ca_fileCA 证书路径
GL_SCHEDULER_CRONscheduler.cron定时表达式
GL_SCHEDULER_WINDOW_STARTscheduler.window_start时间窗起点
GL_DRY_RUNmisc.dry_run干跑模式
GL_CONFIG_STRICTmisc.config_strict严格配置模式
GL_EXPECTED_VERSIONmisc.expected_version期望版本
GL_SUPPORT_BUNDLE_DIRmisc.support_bundle_dir排障包目录

4. 错误码总表

错误码前缀 GL-E-,1 到 7 开头的千位号段分别对应配置与接口、源端、转换、目标端、检查点、调度与资源、内部未归类。错误码会同时写入日志与任务状态,提工单时请附上错误码与任务 ID。

错误码含义处置建议
GL-E-1001配置解析失败,通常是 YAML 缩进或引号错误按提示行号检查;可用 agent.mode=check 复现
GL-E-1002配置校验失败,字段取值不在允许范围对照本手册该参数的约束列
GL-E-1003未知配置项2.3.0 起默认报错;确实需要时临时关闭 misc.config_strict
GL-E-1004配置引用无法解析,如 env: 变量未设置检查环境变量或 file: 引用路径
GL-E-1005运行目录不可写确认 agent.data_dir 权限与磁盘挂载
GL-E-1006磁盘空间不足清理工作区或扩容;磁盘水位见 resource.disk_critical_ratio
GL-E-1007本机时钟偏差超过阈值同步 NTP;签名与检查点依赖时间
GL-E-1008实例锁被占用确认没有重复启动;旧进程残留时检查 pid 与锁文件
GL-E-1009插件不在白名单内先把插件名加入 agent.plugin_whitelist
GL-E-1010插件加载失败看插件 ABI 版本是否与代理匹配
GL-E-1011代理版本与期望版本不一致核对 misc.expected_version
GL-E-1012权限不足,常见于源端或目标端访问键按最小权限原则补充授权
GL-E-1013优雅退出超时,被强制终止检查长时间阻塞的源端读写任务
GL-E-1014配置文件监听失败确认 inotify 上限与目录权限
GL-E-2001源端不可达先验证网络与源端状态页,再检查 source.s3.endpoint
GL-E-2002源端认证失败检查访问键、密钥与会话令牌;注意 90 天轮换
GL-E-2003源桶不存在确认桶名拼写与共享范围
GL-E-2004源前缀下没有匹配对象检查 prefix 与 include_patterns
GL-E-2005源端列举分页不稳定北辰源请开启 shard_list 与 verify_object_count
GL-E-2006处理中对象被源端删除属正常竞态,任务会跳过该对象并记录
GL-E-2007源端读取超时上调 source.s3.read_timeout,检查链路质量
GL-E-2008源对象校验失败重试;连续失败时检查源对象是否损坏
GL-E-2009触发源端限流降低 max_concurrency 或设置 rate_limit_qps
GL-E-2010源端 TLS 证书校验失败检查 CA 文件与证书链,不要跳过校验
GL-E-2011源端区域不匹配北辰只有 cn-north-7 一个区域
GL-E-2012源端不支持路径风格寻址路径风格是北辰唯一支持的寻址方式
GL-E-2013列举游标失效重新扫描该前缀;分片模式下会自动处理
GL-E-2014对象数校验不一致先查源端是否有对象在列举期间新增
GL-E-2015列举权限不足需要桶级 ListBucket 权限
GL-E-2016POSIX 挂载点不可用检查息壤网关状态与 mount 参数
GL-E-2017文件稳定性检查超时大文件写入中,等待后重试或调大 stability_wait
GL-E-3001schema 文件缺失确认 transform.schema_registry 下有对应 yaml
GL-E-3002schema 校验失败按错误提示的字段名修正源数据或 schema
GL-E-3003必填字段缺失字段为空或已被 rename_map 改名
GL-E-3004时间戳解析失败检查 timestamp_format 与源数据时区
GL-E-3005字符编码不支持源文件不是 UTF-8 时设置 source_encoding
GL-E-3006压缩算法不支持目标端可能不认识 zstd,改为 snappy 或 none
GL-E-3007分区数超过上限按时间拆分任务或降低分区基数
GL-E-3008行过滤表达式非法只支持比较与逻辑组合,不支持函数
GL-E-3009字段名冲突,常见于 rename_map确保目标字段名唯一
GL-E-3010脱敏规则文件语法错误按附录 C 的规则语法检查
GL-E-3011转换超时调大 transform.timeout 或降低 batch_rows
GL-E-3012转换阶段内存超限降低 batch_bytes 与压缩级别
GL-E-3013parquet 写入失败检查磁盘空间与 row group 配置
GL-E-3014去重主键不存在dedup_keys 必须在 schema 中
GL-E-3015字段加密失败确认密钥版本可用
GL-E-4001目标端不可达检查 sink.endpoint 与息壤网关状态
GL-E-4002目标端认证失败检查目标访问键与权限
GL-E-4003目标桶配额不足清理历史数据或申请扩容
GL-E-4004分片上传失败检查 part_size 与网络稳定性后重试
GL-E-4005写入后校验不一致重传该对象;连续出现需检查网关
GL-E-4006写入超时上调 sink.write_timeout
GL-E-4007目标端限流降低 sink.max_concurrency
GL-E-4008自定义元数据超限校验元数据总大小超过 2KB
GL-E-4009中转对象清理失败不影响数据,下次启动会重试清理
GL-E-4010幂等键冲突同一对象名但内容不同,属异常,需人工确认
GL-E-4011目标区域不匹配按息壤提供的区域填写
GL-E-4012目标处于归档层级,不可写检查 lifecycle_tier
GL-E-4013写队列积压,暂停写入等积压下降;连续出现请联系存储组
GL-E-4014目标桶生命周期策略拒绝写入同 4012,多为归档策略导致
GL-E-5001检查点文件损坏删除该检查点后从上一个恢复
GL-E-5002恢复时 offset 不一致开启 hash_verify 后重跑定位问题
GL-E-5003任务锁过期检查 checkpoint.lock_ttl 与 GC 停顿
GL-E-5004恢复次数超过上限转人工判断是否从头执行
GL-E-5005检查点目录不可写检查磁盘权限与空间
GL-E-5006孤儿任务回收失败多为锁文件残留,清理后重启
GL-E-5007检查点版本不兼容升级后首次启动会重建,属正常
GL-E-5008检查点上传失败同步到目标桶失败,检查 sink 相关错误
GL-E-6001任务队列已满调大 task_queue_size 或降低扫描频率
GL-E-6002不在允许的时间窗内检查 scheduler.window_start 与 window_end
GL-E-6003内存压力暂停等待恢复或降低并发
GL-E-6004磁盘水位危险清理工作区后自动恢复
GL-E-6005并发任务超限调整 scheduler.max_tasks
GL-E-6006租约争抢失败多代理同任务时会竞争,属正常
GL-E-6007任务拆分失败检查拆分阈值与源端目录结构
GL-E-6008代理正在退出,不再接受新任务等重启完成
GL-E-7001内部空指针,属缺陷保留日志与排障包,提工单
GL-E-7002panic 恢复,进程继续运行看 crash dump 目录;频繁出现提工单
GL-E-7003资源泄漏告警重启代理并保留排障包
GL-E-7004指标注册冲突检查是否加载了重复插件
GL-E-7005日志脱敏失败,已阻塞输出不要绕过,立即提工单
GL-E-7006未归类错误记录 request id 与时间,提工单

5. 默认值变更记录

只记录会影响行为的默认值变化,纯文档修订不在此列。升级前请对照本表检查是否有依赖旧默认值的配置。

版本日期参数旧默认值新默认值原因
2.6.32026-10-18source.s3.list_page_size5001000北辰分页上限实测为 1000,调大以减少列举轮次
2.6.02026-08-30retry.max_attempts0(无限)5修复无限重试导致的放大效应
2.6.02026-08-30sink.write_queue_depth新参数256配合积压保护
2.6.02026-08-30checkpoint.pause_on_backlog新参数true来自 2026-09 事件的改进项
2.6.02026-08-30source.s3.shard_list新参数false北辰分页不稳定规避
2.6.02026-08-30misc.clock_skew_warn新参数5s签名场景需要
2.5.42026-05-11checkpoint.flush_on_shutdown新参数true减少异常退出丢进度
2.5.22026-04-02source.s3.follow_redirects新参数false—
2.5.02026-02-10sink.lifecycle_tier新参数standard配合息壤分层存储
2.5.02026-02-10misc.support_bundle_redact新参数true排障包脱敏
2.4.02025-12-01scheduler.blackout_dates新参数[]年报季禁跑
2.4.02025-12-01source.s3.rate_limit_qps新参数0源端限流保护
2.4.02025-12-01metrics.max_label_cardinality新参数5000控制指标基数
2.4.02025-12-01sink.staging_prefix新参数_staging/原子提交
2.3.02025-09-15sink.checksum_metadata新参数true下游校验
2.3.02025-09-15log.audit_file新参数见默认值审计要求
2.3.02025-09-15agent.admin_enabled新参数false本机管理接口
2.3.02025-09-15retry.max_elapsed新参数1800s限制总重试时长
2.2.02025-06-20source.s3.secret_header新参数X-Beichen-Sign兼容层要求
2.2.02025-06-20transform.field_case新参数keep下游字段统一
2.2.02025-06-20metrics.interval新参数15s—
2.1.02025-03-08agent.instance新参数空多实例部署
2.1.02025-03-08transform.strict_schema新参数false—
2.1.02025-03-08retry.jitter新参数0.2减少重试风暴
2.0.02024-11-02source.s3.tls.min_versionTLS1_0TLS1_2安全基线
2.0.02024-11-02agent.plugin_whitelist新参数[s3,posix]插件安全
2.0.02024-11-02log.sanitize新参数true日志脱敏
2.0.02024-11-02transform.compressiongzipzstd压缩率与速度平衡
1.9.02024-08-19source.posix.sparse_handling新参数skip—
1.9.02024-08-19transform.row_limit新参数0防止误采
1.8.02024-06-03transform.dedup_enabled新参数true去重需求
1.7.02024-04-11source.posix.owner_check新参数false共享盘场景
1.6.02024-02-26source.posix.stability_wait10s30s写入中的大文件误采
1.5.02023-12-18checkpoint.resume_moderecordsoffset精确恢复
1.4.02023-11-07source.s3.session_token_ref新参数空临时密钥支持
1.3.02023-09-25sink.verify_after_write新参数false—
1.2.02023-08-14source.s3.max_idle_conns新参数16连接复用
1.1.02023-06-30agent.workspace新参数/data/workspace大对象临时区
1.0.02023-05-12首批参数——代理首个版本,共 46 个参数

6. 指标目录

代理暴露的指标前缀为 guanlan_agent,默认由重明采集。指标基数的注意事项见第 2 节 metrics 组。

指标名称类型标签说明保留期
guanlan_agent_infogaugeversion、mode代理版本与模式,恒为 130d
guanlan_agent_task_totalcounterstate任务计数,按成功失败等状态90d
guanlan_agent_task_duration_secondshistogramdataset任务耗时分布90d
guanlan_agent_task_inflightgaugedataset运行中任务数90d
guanlan_agent_source_read_bytes_totalcountersource、dataset源端读取字节数30d
guanlan_agent_source_read_errors_totalcountersource、code源端读取错误计数90d
guanlan_agent_source_latency_secondshistogramsource源端请求延迟30d
guanlan_agent_transform_rows_totalcounterdataset转换行数30d
guanlan_agent_transform_errors_totalcounterdataset、code转换错误计数90d
guanlan_agent_transform_batch_secondshistogramdataset单批转换耗时30d
guanlan_agent_sink_write_bytes_totalcounterbucket、dataset写入字节数30d
guanlan_agent_sink_write_errors_totalcounterbucket、code写入错误计数90d
guanlan_agent_sink_latency_secondshistogrambucket写入延迟30d
guanlan_agent_sink_queue_depthgauge—写队列深度30d
guanlan_agent_sink_inflight_bytesgauge—在途字节数30d
guanlan_agent_checkpoint_write_secondshistogram—检查点写入耗时30d
guanlan_agent_checkpoint_age_secondsgaugedataset距最近检查点的时间30d
guanlan_agent_checkpoint_errors_totalcountercode检查点错误计数90d
guanlan_agent_retry_totalcounterstage、code重试次数90d
guanlan_agent_quarantine_totalcounterstage进入隔离区的对象数90d
guanlan_agent_worker_busy_ratiogaugeworker工作协程繁忙比例30d
guanlan_agent_memory_bytesgaugetype进程内存占用30d
guanlan_agent_disk_used_ratiogaugemount工作区磁盘使用率30d
guanlan_agent_config_reload_totalcounterresult配置热加载次数90d
guanlan_agent_config_errorgauge—配置错误标记,1 表示有问题90d
guanlan_agent_clock_skew_secondsgauge—本机时钟偏差30d
guanlan_agent_scheduler_scanned_totalcountersource扫描到的对象数30d
guanlan_agent_scheduler_pendinggaugesource待处理对象数90d
guanlan_agent_api_requests_totalcounterendpoint、code管理接口请求数90d

7. 附录 A:配置文件示例

以下三份示例分别对应单机小规模、夜航大规模与跨机房受限带宽三种场景。示例中的密钥全部以环境变量引用,主机名与桶名为内部命名。

A.1 单机小规模(日增 500 万条以内)

agent:
  id: gz-agent-single-01
  mode: daemon
  data_dir: /var/lib/guanlan
  workspace: /data/workspace
  max_workers: 4

source:
  type: posix
  posix:
    root: /xiran/inbox
    read_only: true
    scan_interval: 300s
    ignore_patterns: [".nfs*", "*.swp"]

transform:
  schema_registry: /etc/guanlan/schema/
  partition_by: [site, capture_date]
  compression: zstd
  batch_rows: 32768

sink:
  type: s3
  endpoint: xiran.internal:9000
  bucket: xiran-prod
  path_template: guanlan/{dataset}/{yyyyq}/
  access_key_ref: env:GL_SINK_ACCESS_KEY
  secret_key_ref: env:GL_SINK_SECRET_KEY

scheduler:
  scan_interval: 120s
  max_tasks: 8

log:
  level: info
  sanitize: true

A.2 夜航大规模(16 个 worker,日增 2 亿条)

agent:
  id: gz-agent-yeahang-17
  instance: yh-a
  data_dir: /data/guanlan/state
  workspace: /data/guanlan/work
  max_workers: 16
  thread_pool_size: 64
  shutdown_grace: 120s

source:
  type: s3
  s3:
    endpoint: beichen.internal:9000
    bucket: beichen-share
    region: cn-north-7
    path_style: true
    prefix: calib/
    shard_list: true
    verify_object_count: true
    max_conns: 64
    max_concurrency: 16
    access_key_ref: env:GL_SRC_ACCESS_KEY
    secret_key_ref: env:GL_SRC_SECRET_KEY

transform:
  strict_schema: true
  partition_by: [site, capture_date]
  max_partitions: 4000
  compression: zstd
  compression_level: 1
  batch_bytes: 128MiB
  on_error: quarantine

sink:
  endpoint: xiran.internal:9000
  bucket: xiran-prod
  part_size: 128MiB
  max_concurrency: 16
  max_inflight_bytes: 8GiB
  write_queue_depth: 1024
  retry_on_5xx: true

checkpoint:
  interval: 30s
  records_interval: 1000000
  keep: 5
  pause_on_backlog: true

resource:
  memory_limit: 12GiB
  memory_reserve: 3GiB
  network_bandwidth_limit: 900MiB

metrics:
  task_labels: false
  max_label_cardinality: 3000

A.3 跨机房受限带宽(北辰源到夜航)

agent:
  id: gz-agent-relay-03
  max_workers: 8

source:
  type: s3
  s3:
    endpoint: beichen.internal:9000
    bucket: beichen-inbox
    path_style: true
    connect_timeout: 8s
    read_timeout: 120s
    rate_limit_qps: 300
    rate_limit_burst: 600
    tls:
      enabled: true
      ca_file: /etc/guanlan/tls/beichen-ca.pem
      min_version: TLS1_2
    access_key_ref: env:GL_SRC_ACCESS_KEY
    secret_key_ref: env:GL_SRC_SECRET_KEY

transform:
  compression: snappy
  compression_level: 1
  batch_bytes: 32MiB

sink:
  endpoint: xiran.internal:9000
  bucket: xiran-prod
  part_size: 32MiB
  max_concurrency: 4
  write_timeout: 180s

resource:
  network_bandwidth_limit: 400MiB
  network_burst: 64MiB

scheduler:
  window_start: "22:00"
  window_end: "05:00"
  max_window_lag: 900s

retry:
  max_attempts: 8
  max_elapsed: 3600s

8. 附录 B:日志采样

下面是 2026-10-14 凌晨一次正常回灌的日志采样(已脱敏、已截断),用于对照格式与关键字段。日志字段顺序为时间戳、级别、组件、消息;正式采集到重明时使用 json 格式。

2026-10-14T01:58:02.113+08:00 INFO  agent.core        配置加载完成 cfg=/etc/guanlan/agent.yaml files=3 reload=false
2026-10-14T01:58:02.140+08:00 INFO  agent.health      健康检查监听 addr=10.42.7.23:9120
2026-10-14T01:58:02.151+08:00 INFO  agent.metrics     指标端点就绪 path=/metrics
2026-10-14T01:58:02.377+08:00 INFO  scheduler         扫描开始 window=22:00-05:00
2026-10-14T01:58:03.901+08:00 INFO  scheduler         发现新批次 batch=calib-2026q4 objects=1842 prefix=calib/2026/q4/
2026-10-14T01:58:03.912+08:00 INFO  scheduler         拆分任务 tasks=4 split_by=records threshold=20000000
2026-10-14T01:58:04.226+08:00 INFO  task.cj_7f3a  task_start dataset=camera-calib-2026q4 records=0
2026-10-14T01:59:18.557+08:00 WARN  source.s3     src_retry attempt=1 code=GL-E-2009 detail=slow_down wait=200ms
2026-10-14T01:59:31.882+08:00 INFO  source.s3     src_list shard=0x7f page=3 objects=1000
2026-10-14T01:59:58.104+08:00 INFO  transform     schema_loaded dataset=camera-calib-2026q4 version=7 fields=23
2026-10-14T02:00:12.447+08:00 INFO  transform     batch_done batch=1 rows=65536 bytes=61234691 elapsed=8.4s
2026-10-14T02:00:14.019+08:00 INFO  sink.s3       upload_ok bucket=xiran-prod key=guanlan/camera-calib/2026q4/part-0001.parquet size=28634312
2026-10-14T02:03:47.771+08:00 WARN  checkpoint    ckpt_slow elapsed=2.4s size=479MiB reason=fsync
2026-10-14T02:05:02.663+08:00 INFO  checkpoint    ckpt_written shard=1 records=500000 offset=500000
2026-10-14T02:11:27.338+08:00 WARN  sink.s3       queue_depth=213 inflight=1427112345 inflight_limit=2147483648
2026-10-14T02:11:29.902+08:00 INFO  scheduler      scan_round_skipped reason=window_busy pending=12
2026-10-14T02:14:47.190+08:00 ERROR source.s3     src_read_failed code=GL-E-2007 key=calib/2026/q4/batch-0091/0007.parquet retry=2
2026-10-14T02:14:53.512+08:00 INFO  source.s3     src_read_ok key=calib/2026/q4/batch-0091/0007.parquet size=48219033
2026-10-14T02:22:33.804+08:00 INFO  task.cj_7f3a  task_progress processed=16821190 total=20000000 percent=84.1
2026-10-14T02:31:09.229+08:00 WARN  transform     field_deprecated field=intrinsic_hash deprecated_after=2027-03-01
2026-10-14T02:33:18.951+08:00 INFO  sink.s3       upload_ok bucket=xiran-prod key=guanlan/camera-calib/2026q4/part-0002.parquet size=29441770
2026-10-14T02:36:00.102+08:00 INFO  task.cj_7f3a  task_done state=succeeded elapsed=2313s rows=20000000
2026-10-14T02:36:00.448+08:00 INFO  checkpoint    ckpt_cleanup removed=1 keep=3
2026-10-14T02:36:00.501+08:00 INFO  scheduler      batch_done batch=calib-2026q4 tasks=4 failed=0
2026-10-14T02:36:00.533+08:00 INFO  audit          op=notify topic=guanlan-ingest dataset=camera-calib-2026q4 result=ok

9. 附录 C:压测基线

数据来自 2026-09 在夜航 A 区三台节点上的压测,单代理实例、数据集为相机标定与标注快照混合负载。结果只用于容量估算,实际表现受源端与合作方链路影响。

场景规模 / 负载吞吐CPU(实测峰值)内存(RSS 峰值)延迟备注
小对象回灌单批 200 万个小 JSON18400 文件/分钟6 核4.1GiBp95 单文件 38ms与对象大小强相关
大文件顺序读单对象 8GiB1.7GiB/s8 核2.6GiBp95 读 210ms受网关带宽限制
parquet 转换1000 万行、40 列约 9 分 40 秒8 核9.8GiBp99 批 6.1szstd 级别 3
写入息壤单批 500GiB620MiB/s8 核3.2GiBp95 片 240ms4 个并发上传
检查点写入512MiB 状态每次 1.9s2 核——含 fsync
断点恢复中断于 62%恢复约 40 秒4 核1.1GiB—offset 模式
列举 100 万对象北辰共享桶单轮约 6 分钟2 核——分页 1000、8 并发
列举 100 万对象(分片)北辰共享桶单轮约 4 分 20 秒2 核——256 分片
跨机房回灌400MiB 带宽限制382MiB/s8 核3.0GiBp95 片 310ms北辰到夜航

容量估算经验值:按日增 1 亿行、单行 1.2KiB 估算,落盘后约 1.1TiB/天;建议单代理不超过 3 个并行大任务,超过后拆分代理或错峰。

10. 附录 D:现场排查清单

按顺序核对,多数现场问题能在前 10 条内定位。清单同时用于新节点验收。

  1. 启动前确认 agent.data_dir 与 agent.workspace 不在同一块盘上,避免检查点与临时文件互相挤占。
  2. 用 agent.mode=check 先跑一遍配置校验,再以 daemon 启动。
  3. 确认源端访问键没有写进配置文件,只以 env: 或 file: 形式引用。
  4. 首次接入开启 misc.dry_run,确认扫描到的对象数与源端控制台账单一致后再关闭。
  5. 北辰源必须设置 source.s3.path_style=true 与 secret_header=X-Beichen-Sign。
  6. 北辰源建议同时开启 shard_list 与 verify_object_count,尤其在桶内对象持续变化时。
  7. 确认源端 TLS 证书链完整,不要用跳过校验来临时绕过。
  8. 时间同步:chronyc tracking 的偏差应远小于 misc.clock_skew_warn。
  9. 检查系统 ulimit,确保 resource.max_file_descriptors 不超过实际限制。
  10. 转换阶段变更后,先在测试数据集运行一次并比对 schema 版本。
  11. 检查点目录使用持久化磁盘,不要放在 tmpfs 或容器临时层。
  12. 多实例同主机部署时,每个实例必须独立的 data_dir、run_dir 与 pid_file。
  13. 确认 scheduler.window_start 与 window_end 与实际业务时窗一致,避免与训练回灌抢带宽。
  14. 接入外部调度器时把 scheduler.enabled 设为 false,避免双调度重复采集。
  15. 设置 sink.bucket_quota_warn_ratio,桶接近配额时提前收到告警。
  16. 检查 sink.max_inflight_bytes 是否与网关承载能力匹配。
  17. 日志级别默认 info,排障时才临时开 debug,并设置自动恢复时间。
  18. 确认 log.sanitize=true,避免访问键进入日志。
  19. 审计日志单独归档,不随普通日志滚动清理。
  20. 升级前备份 /etc/guanlan 与检查点目录的元数据文件。
  21. 升级后第一次启动会做检查点版本迁移,不要在业务高峰执行。
  22. 用排障包(misc.support_bundle_dir)收集现场信息,不要手工拷贝敏感配置。
  23. 确认插件版本与代理 ABI 匹配,插件目录权限不可写。
  24. 内存紧的节点降低 transform.batch_bytes,不要只调 batch_rows。
  25. 监控 guanlan_agent_sink_queue_depth,持续走高说明目标端承压。
  26. 监控 guanlan_agent_checkpoint_age_seconds,突然增大说明检查点卡住。
  27. 确认 misc.config_strict=true,避免拼写错误的参数被静默忽略。
  28. 变更后用 agent.mode=check 验证配置,再滚动重启。

11. 附录 E:常见问题

retry.max_attempts 默认从无限改成 5 次,老配置会怎样
启动校验会拒绝 retry.retry_forever=true 的旧写法,按报错行改成 retry.max_attempts 即可,行为变化是任务失败更快暴露。
为什么 2.6.0 之后偶尔出现 GL-E-4013
写队列积压保护触发。先看 guanlan_agent_sink_queue_depth 与网关状态,持续出现联系存储组。
北辰源列举对象比实际少
开启 source.s3.shard_list 与 verify_object_count;北辰分页在桶内容变化时不保证稳定。
检查点能不能关掉换性能
不建议。关闭后异常退出需要整任务重跑;如果确实要关,至少保留 retry 与告警。
同一批数据重复采集了两次
多为调度器与外部调度同时开启,二选一;另外确认 checkpoint 目录是否被清理。
容器里 daemonize 要设 false 吗
要。容器内由编排层托管进程,daemonize=true 会导致容器立即退出。
内存占用持续上涨但任务正常
看是否开了 metrics.task_labels 导致标签基数过大;再看排障包里的堆采样。
TLS 报证书过期但别人能用
检查本机时间与 CA 文件版本;证书轮换后需确认 reload_interval 或重启。
转换阶段报 GL-E-3006
目标端不支持 zstd,把 transform.compression 改成 snappy 或 none。
恢复后进度比中断时还少
检查点间隔内的数据会重采,属预期;offset 模式最多回退一个检查点间隔。
能不能跳过 schema 校验加快导入
可以但不建议,strict_schema=false 会让坏数据流到下游,排查成本更高。
日志里出现脱敏失败告警
不要绕过。立即提工单,保留排障包,说明出现时间与任务 ID。
跨机房带宽怎么限制
用 resource.network_bandwidth_limit 与 network_burst,配合 sink.max_concurrency 控制。
多实例能共享一个 data_dir 吗
不能。会导致锁冲突与检查点互相覆盖。
agent.mode=once 适合什么场景
一次性回灌或 CI 验证,跑完即退出;常驻采集用 daemon。
排障包里包含密钥吗
默认脱敏(misc.support_bundle_redact=true),提交前仍建议人工检查一遍。
提示 GL-E-6002 但时间窗是对的
检查 agent.timezone 与调度器的解释时区,跨时区节点容易出错。
升级后指标前缀变了
2.6.0 指标前缀保持 guanlan_agent 不变;如果看板断图,检查 metrics.prefix 是否被配置覆盖。
任务一直 queued
看 scheduler.max_tasks 与当前运行任务数;也可能在时间窗外。
代理重启后大量重试
先确认源端状态页;重启时正在进行的任务会按重试策略恢复。

12. 附录 F:缩略语

缩写全称 / 中文说明
agent采集代理运行在数据源侧或数据落地侧的执行进程
BML北冥机器学习加速卡型号前缀所内统一命名,具体型号见硬件清单
ckptcheckpoint检查点,记录任务进度的状态文件
CFGconfiguration配置
dataset数据集逻辑数据集合,对应一个 schema 序列
E2Eend-to-end端到端
fsyncfile sync文件落盘同步
GLguanlan观澜产品代号
GL-Eguanlan error观澜错误码前缀
IPinternet protocol网络协议
JSONjavascript object notation数据交换格式
KBknowledge base知识库
MLU寒武纪加速卡型号本所评测机使用
NFSnetwork file system网络文件系统
NPUneural processing unit神经网络处理器
OOMout of memory内存耗尽
p95/p99percentile延迟分位数
parquet列式存储格式数据落地常用格式
posix可移植操作系统接口此处指 POSIX 文件语义源
PVCpersistent volume claim持久卷声明
RBACrole based access control基于角色的访问控制
RSSresident set size常驻内存
S3simple storage service对象存储协议
SLAservice level agreement服务等级约定
SLOservice level objective服务等级目标
SNIserver name indicationTLS 服务器名称指示
SSOsingle sign-on统一登录
TLStransport layer security传输层安全
TTLtime to live有效期
UUIDuniversally unique identifier通用唯一标识符
yamlyaml aint markup language配置格式
Zstdzstandard压缩算法
IAMidentity and access management身份与访问管理

13. 文档维护与反馈

本手册随 guanlan-agent 版本发布更新;补丁版本只修正错误,不新增章节。发现参数说明与代码不一致时,在本仓库提工单(标签 docs,同时 @ 观澜组值班),不要在共享文档里直接改参数默认值——默认值以参数注册表为准,文档只是描述。

相关文档:观澜数据服务 API 参考 v2.6.3 · 星槎部署手册 · OOM 扩散事件复盘 · 运维手册库 · 文档中心