本手册列出 guanlan-agent 2.6.x 的全部公开配置参数、环境变量映射、错误码与排障附录。参数表由启动时的参数注册表导出,与代码版本严格一致;手工维护的说明文字可能滞后于最新补丁版本,以注册表为准。文中主机名、地址与示例数据均为内部命名与合成值。
1. 配置加载与合并顺序
代理按固定顺序加载配置,后加载的层覆盖先加载的层。合并是逐键进行的,列表类型整体替换而不是追加。启动日志会打印每一层的来源文件与最终生效的键数量,排障时先看这行日志。
- 编译内置默认值:参数注册表中的默认值,任何情况下都存在。
- 主配置文件:
/etc/guanlan/agent.yaml,安装时生成,不建议手改敏感字段。 - 片段目录:
/etc/guanlan/conf.d/*.yaml,按文件名字典序加载,适合按数据集拆配置。 - 环境变量:
GL_前缀,见第 3 节;适合容器化部署与密钥注入。 - 命令行参数:仅限少数运行期参数(
--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.id | string | gz-agent-01 | 1.0.0 | 代理实例标识,安装脚本默认写入主机名 | 长度 1–64,需全局唯一 |
agent.mode | enum | daemon | 1.0.0 | 运行模式:daemon 常驻、once 单次执行后退出、check 只做配置校验 | 升级前建议先跑 check |
agent.instance | string | 空 | 2.1.0 | 同主机多实例时的实例名,参与锁文件与指标标签 | 仅小写字母、数字和连字符 |
agent.tags | string-list | [] | 1.2.0 | 自定义标签,随指标与日志上报 | 键值对数量不超过 32 |
agent.data_dir | path | /var/lib/guanlan | 1.0.0 | 状态、offset 与本地缓存根目录 | 需可写,剩余空间不小于 10GiB |
agent.run_dir | path | /run/guanlan | 1.0.0 | pid、锁文件与临时套接字的目录 | 可放在 tmpfs |
agent.log_dir | path | /var/log/guanlan | 1.0.0 | 日志根目录 | 按 100MiB 滚动,保留 7 份 |
agent.workspace | path | /data/workspace | 1.1.0 | 下载与转换使用的临时工作区 | 建议独立磁盘,容量不小于 200GiB |
agent.max_workers | int | 8 | 1.0.0 | 采集工作协程数,决定并发任务上限 | 不超过 CPU 核数的 2 倍 |
agent.thread_pool_size | int | 32 | 2.0.0 | IO 线程池大小,源端与目标端共享 | 高延迟链路可上调到 64 |
agent.process_priority | int | 0 | 2.2.0 | 进程 nice 值,正值降低优先级 | 负值仅 root 可设 |
agent.shutdown_grace | duration | 45s | 1.0.0 | 收到 SIGTERM 后等待任务收尾的时长 | 超时后强制退出 |
agent.pid_file | path | /run/guanlan/agent.pid | 1.0.0 | pid 文件路径 | 多实例必须分别指定 |
agent.user | string | guanlan | 1.0.0 | 运行用户,需对 data_dir 有写权限 | 不建议用 root 运行 |
agent.group | string | guanlan | 1.0.0 | 运行用户组 | 与 user 保持一致 |
agent.umask | string | 0027 | 1.0.0 | 新建文件的权限掩码 | 过于宽松的值会被拒绝启动 |
agent.timezone | string | Asia/Shanghai | 1.0.0 | 日志与调度使用的时区 | 影响 cron 表达式解释 |
agent.locale | string | zh_CN.UTF-8 | 1.0.0 | 排序与字符处理使用的 locale | 容器内需安装对应 locale |
agent.fs_sync | bool | true | 1.3.0 | 写完检查点后是否 fsync | 关闭可提吞吐,但断电会丢状态 |
agent.file_lock | enum | flock | 1.0.0 | 单实例锁实现:flock 或 pid | pid 方式已不推荐 |
agent.lock_timeout | duration | 10s | 1.0.0 | 获取实例锁的等待上限 | 超时退出码为 12 |
agent.daemonize | bool | true | 1.0.0 | 是否后台化运行 | 容器内建议 false,由 entrypoint 托管 |
agent.health_addr | addr | 10.42.7.23:9120 | 2.2.0 | 健康检查监听地址 | 仅监听内网地址 |
agent.health_liveness_path | string | /healthz | 2.2.0 | 存活探针路径 | 返回 200 表示进程存活 |
agent.health_readiness_path | string | /ready | 2.2.0 | 就绪探针路径 | 有任务运行也返回就绪 |
agent.admin_enabled | bool | false | 2.3.0 | 是否开启本机管理接口 | 默认关闭,排障时才打开 |
agent.admin_addr | addr | loopback:9121 | 2.3.0 | 管理接口监听地址 | 不要绑定到所有网卡 |
agent.plugin_dir | path | /usr/lib/guanlan/plugins | 2.0.0 | 插件目录 | 只加载白名单内插件 |
agent.plugin_whitelist | string-list | [s3,posix] | 2.0.0 | 允许加载的插件名 | 修改后需重启生效 |
agent.config_reload_interval | duration | 60s | 2.4.0 | 配置热加载检查间隔 | 仅部分参数支持热加载 |
agent.config_dump_on_start | bool | false | 2.5.0 | 启动时打印合并后的配置(已脱敏) | 含敏感引用时不要开启 |
agent.crash_dump_dir | path | /var/crash/guanlan | 2.5.2 | panic 转储目录 | 空间不足时会自动关闭转储 |
2.2 source.s3 — 源端对象存储
北辰智能、云雀数据等合作方以 S3 协议提供共享桶,源端参数较长,与网络质量、源端实现差异相关。2.6.0 新增的分片列举参数用于规避北辰列举分页不稳定的问题。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
source.s3.endpoint | string | 必填 | 1.0.0 | 源端 S3 兼容服务地址,形如 beichen.internal:9000 | 不带协议前缀 |
source.s3.bucket | string | 必填 | 1.0.0 | 源桶名 | 需在合作协议约定的共享桶范围内 |
source.s3.region | string | cn-north-7 | 1.0.0 | 区域标识,北辰只提供单一区域 | 写错不报错,会落到默认池 |
source.s3.path_style | bool | true | 1.0.0 | 是否使用路径风格寻址 | 北辰必须为 true |
source.s3.access_key_ref | string | env:GL_SRC_ACCESS_KEY | 1.1.0 | 访问键引用,支持 env: 与 file: 前缀 | 禁止内联明文 |
source.s3.secret_key_ref | string | env:GL_SRC_SECRET_KEY | 1.1.0 | 密钥引用 | 同上 |
source.s3.session_token_ref | string | 空 | 1.4.0 | 临时密钥的会话令牌引用 | 留空表示使用长期键 |
source.s3.prefix | string | 空 | 1.0.0 | 起始前缀,只采集该前缀下的对象 | 末尾不加斜杠也可以 |
source.s3.include_patterns | string-list | ["*.parquet","*.json"] | 1.0.0 | 包含匹配规则 | 只支持 fnmatch 通配 |
source.s3.exclude_patterns | string-list | ["_SUCCESS","*.tmp"] | 1.0.0 | 排除匹配规则 | 优先于包含匹配 |
source.s3.connect_timeout | duration | 5s | 1.0.0 | 建连超时 | 跨机房建议 8s |
source.s3.read_timeout | duration | 60s | 1.3.0 | 单次读超时 | 大对象可放宽到 120s |
source.s3.max_retries | int | 3 | 1.0.0 | 源端失败重试次数 | 0 表示不重试 |
source.s3.retry_backoff_min | duration | 200ms | 2.1.0 | 退避下限 | 不得小于 50ms |
source.s3.retry_backoff_max | duration | 30s | 2.1.0 | 退避上限 | 不得小于退避下限 |
source.s3.retry_jitter | float | 0.2 | 2.1.0 | 退避抖动比例 | 取值 0 到 1 |
source.s3.max_conns | int | 32 | 1.0.0 | 最大连接数 | 单代理建议不超过 64 |
source.s3.max_idle_conns | int | 16 | 1.2.0 | 空闲连接上限 | 不超过 max_conns |
source.s3.idle_conn_timeout | duration | 90s | 1.2.0 | 空闲连接回收时间 | 短于源端 keepalive 时会更频繁建连 |
source.s3.part_size | bytes | 64MiB | 1.0.0 | 分片大小 | 对象大于 1GiB 时上调 |
source.s3.max_concurrency | int | 8 | 1.0.0 | 单任务对象并发数 | 过高容易触发源端限流 |
source.s3.checksum | enum | sha256 | 1.2.0 | 对象校验算法:sha256、md5、crc32 | 北辰的 ETag 不能当 MD5 使用 |
source.s3.verify_on_read | bool | false | 1.5.0 | 读时校验,代价较高 | 排障时可临时开启 |
source.s3.shard_list | bool | false | 2.6.0 | 按前缀分片列举,规避北辰分页不稳定 | 北辰源建议设为 true |
source.s3.shard_prefix_bytes | int | 2 | 2.6.0 | 分片前缀字节数,2 对应 256 个分片 | 取值 1 到 3 |
source.s3.verify_object_count | bool | false | 2.6.0 | 列举完成后用对象总数校验完整性 | 需要桶级读权限 |
source.s3.list_page_size | int | 1000 | 1.0.0 | 单次列举返回条数 | 北辰上限 1000 |
source.s3.list_max_pages | int | 0 | 2.4.0 | 列举最大页数,0 表示不限 | 用于防止异常桶导致死循环 |
source.s3.stat_before_read | bool | false | 2.5.0 | 读前先 HEAD 获取对象大小 | 可减少无效读与 404 |
source.s3.range_size | bytes | 16MiB | 2.2.0 | Range 读块大小 | 与 read_buffer 独立 |
source.s3.read_buffer | bytes | 1MiB | 1.3.0 | 读缓冲大小 | 大对象可调到 4MiB |
source.s3.tls.enabled | bool | true | 1.1.0 | 源端是否走 TLS | 北辰内网同样强制 TLS |
source.s3.tls.ca_file | path | /etc/guanlan/tls/ca.pem | 1.1.0 | CA 证书文件 | 需与源端证书链匹配 |
source.s3.tls.server_name | string | 空 | 1.2.0 | SNI 名称,留空则用 endpoint | 证书为多域名时必填 |
source.s3.tls.min_version | enum | TLS1_2 | 2.2.0 | 最低 TLS 版本 | TLS1_0 与 TLS1_1 已禁用 |
source.s3.tls.insecure_skip_verify | bool | false | 1.1.0 | 跳过证书校验,仅联调时临时使用 | 生产开启会触发审计告警 |
source.s3.proxy | string | 空 | 2.3.0 | 内网代理地址(只写主机与端口) | 仅隔离网段需要 |
source.s3.rate_limit_qps | uint | 0 | 2.4.0 | 源端请求限速,0 表示不限 | 按实例计算 |
source.s3.rate_limit_burst | uint | 0 | 2.4.0 | 限速突发桶大小 | 为 0 时取 QPS 的 3 倍 |
source.s3.follow_redirects | bool | false | 2.5.2 | 是否跟随重定向 | 对象存储一般不需要 |
source.s3.user_agent | string | guanlan-agent/2.6.3 | 1.4.0 | 请求的 User-Agent | 便于源端侧识别调用来源 |
source.s3.secret_header | string | X-Beichen-Sign | 2.6.0 | 签名头名称 | 北辰兼容层不支持 query 签名 |
2.3 source.posix — 源端 POSIX 文件系统
息壤 POSIX 网关挂载到本机时使用。注意 read_only 与 move_after_read 存在冲突,生产建议只读。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
source.posix.root | path | /xiran/inbox | 1.0.0 | POSIX 源根目录 | 必须为已挂载的息壤导出路径 |
source.posix.read_only | bool | true | 1.0.0 | 是否只读打开源文件 | 建议保持 true |
source.posix.follow_symlinks | bool | false | 1.1.0 | 是否跟随符号链接 | 安全考虑默认禁止 |
source.posix.max_open_files | int | 2048 | 1.2.0 | 单进程打开文件上限 | 需与系统 ulimit 同步 |
source.posix.read_buffer | bytes | 4MiB | 1.3.0 | 顺序读缓冲大小 | 大文件可调到 16MiB |
source.posix.dir_batch_size | int | 5000 | 1.4.0 | 目录遍历单批返回条数 | 超大目录建议降到 2000 |
source.posix.ignore_hidden | bool | true | 1.0.0 | 忽略点文件与点目录 | — |
source.posix.ignore_patterns | string-list | [".nfs*","*.swp"] | 1.0.0 | 忽略规则 | NFS 临时文件多时可加 "*~" |
source.posix.sort_order | enum | name | 1.5.0 | 遍历顺序:name 或 mtime | 断点续采建议用 mtime |
source.posix.scan_interval | duration | 300s | 1.2.0 | 周期性扫描间隔 | 配合 rescan 模式使用 |
source.posix.stability_wait | duration | 30s | 1.6.0 | 文件大小稳定判定等待 | 写入中的大文件必需 |
source.posix.stability_checks | int | 2 | 1.6.0 | 稳定性检查次数 | 两次间隔为 stability_wait |
source.posix.owner_check | bool | false | 1.7.0 | 是否校验文件所有者 | 跨部门共享盘建议开启 |
source.posix.mount_check | bool | true | 2.0.0 | 启动时校验挂载点是否有效 | 防止采集到空目录 |
source.posix.mount_timeout | duration | 10s | 2.0.0 | 挂载点检测超时 | — |
source.posix.checksum_algorithm | enum | sha256 | 1.2.0 | 校验算法 | 需与目标端一致 |
source.posix.checksum_workers | int | 4 | 1.8.0 | 校验并发线程数 | 属 IO 密集,不宜过大 |
source.posix.sparse_handling | enum | skip | 1.9.0 | 稀疏文件处理:skip 跳过或 zero 补零 | skip 可能导致大小不一致 |
source.posix.xattr_read | bool | false | 2.1.0 | 是否读取扩展属性作为元数据 | 息壤网关不保证支持 |
source.posix.move_after_read | bool | false | 2.3.0 | 读完后移动到 done 子目录 | 需要写权限,与只读模式冲突 |
source.posix.max_file_size | bytes | 0 | 1.9.0 | 单文件大小上限,0 表示不限 | 防止误采超大镜像 |
source.posix.min_file_size | bytes | 0 | 2.2.0 | 小于该值的文件跳过 | 标注小文件可设 1KiB |
source.posix.inode_check | bool | false | 2.4.0 | 是否记录 inode 防止重复采集 | 在 NFS 上不可靠,默认关闭 |
2.4 transform — 转换与归一化
schema 校验、字段映射、脱敏、分区与压缩。转换阶段参数较多,误配会直接影响下游查询,建议变更前在测试数据集上跑 check。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
transform.enabled | bool | true | 1.0.0 | 是否启用转换阶段 | 关闭时源格式直传 |
transform.format_detect | enum | auto | 1.0.0 | 格式识别:auto 按扩展名与文件头判断 | 自动识别失败会回退扩展名 |
transform.schema_registry | path | /etc/guanlan/schema/ | 2.0.0 | schema 注册目录,每个数据集一个 yaml | — |
transform.strict_schema | bool | false | 2.1.0 | schema 不匹配时是否直接失败 | 生产建议开启 |
transform.drop_unknown_fields | bool | true | 2.1.0 | 是否丢弃 schema 之外的字段 | 关闭则原样透传 |
transform.field_case | enum | keep | 2.2.0 | 字段名大小写策略:keep、lower、snake | 变更会影响下游查询 |
transform.timestamp_column | string | capture_time | 1.2.0 | 时间戳列名,用于分区与排序 | — |
transform.timestamp_format | string | rfc3339 | 1.2.0 | 时间戳解析与输出格式 | 也支持 unix_seconds |
transform.timezone_convert | bool | true | 1.5.0 | 是否统一转换为 Asia/Shanghai | 跨时区源需要开启 |
transform.encrypt_fields | string-list | [] | 2.3.0 | 需要加密的字段名列表 | 使用所内对称密钥加密 |
transform.mask_rules_file | path | 空 | 2.3.0 | 脱敏规则文件路径 | 规则语法见附录 C |
transform.dedup_enabled | bool | true | 1.8.0 | 是否按主键去重 | 大数据集代价较高 |
transform.dedup_window | duration | 24h | 1.8.0 | 去重窗口 | 0 表示全量窗口 |
transform.dedup_keys | string-list | [sample_id] | 1.8.0 | 去重主键 | 必须存在于 schema 中 |
transform.aggregation_enabled | bool | false | 2.0.0 | 是否做预聚合 | 仅统计类数据集需要 |
transform.aggregation_interval | duration | 1h | 2.0.0 | 预聚合时间窗 | — |
transform.filter_expression | string | 空 | 2.2.0 | 行过滤表达式(受限语法) | 不允许子查询与函数调用 |
transform.row_limit | uint | 0 | 1.9.0 | 单任务最大行数,0 表示不限 | 防止误采超大表 |
transform.column_whitelist | string-list | [] | 2.4.0 | 只保留的列 | 与黑名单互斥 |
transform.column_blacklist | string-list | [] | 2.4.0 | 排除的列 | 优先于白名单 |
transform.rename_map | map | {} | 2.4.0 | 字段重命名映射,键为源字段名 | 目标字段名需唯一 |
transform.partition_by | string-list | [site,capture_date] | 1.3.0 | 输出分区键 | 应为低基数字段 |
transform.max_partitions | int | 2000 | 1.7.0 | 单任务分区数上限 | 超过时需按时间拆分任务 |
transform.compression | enum | zstd | 2.0.0 | 中间结果压缩:zstd、snappy、none | 下游需要能解压 |
transform.compression_level | int | 3 | 2.0.0 | 压缩级别 1 到 9 | 高并发时建议降到 1 |
transform.batch_rows | int | 65536 | 1.1.0 | 每批转换行数 | 内存紧张时降低 |
transform.batch_bytes | bytes | 64MiB | 1.1.0 | 每批字节上限 | 与 batch_rows 同时生效 |
transform.dictionary_encode | bool | true | 2.2.0 | 低基数字段是否字典编码 | — |
transform.timeout | duration | 3600s | 1.4.0 | 单批转换超时 | 超大文件可放宽到 7200s |
transform.on_error | enum | fail | 1.6.0 | 错误处理:fail、skip、quarantine | 生产建议 fail 或 quarantine |
transform.quarantine_dir | path | /var/lib/guanlan/quarantine | 2.5.0 | 隔离区目录 | skip 与 quarantine 时使用 |
transform.parquet_row_group_size | int | 262144 | 1.9.0 | parquet row group 行数 | — |
transform.parquet_page_size | bytes | 1MiB | 1.9.0 | parquet 页大小 | — |
transform.source_encoding | string | utf-8 | 2.1.0 | 文本类源的字符编码 | 转换失败会写入隔离区 |
2.5 sink — 目标端写入
写入息壤对象存储。2.6.0 起增加写队列与在途字节限制,起因是 2026-09-11 的 OOM 扩散事件中写队列被检查点重试打满。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
sink.type | enum | s3 | 1.0.0 | 目标类型:s3 或 posix | 优先使用 s3 接口 |
sink.endpoint | string | xiran.internal:9000 | 1.0.0 | 目标端地址 | 不带协议前缀 |
sink.bucket | string | xiran-prod | 1.0.0 | 目标桶名 | — |
sink.region | string | cn-north-7 | 1.0.0 | 目标区域 | — |
sink.path_template | string | guanlan/{dataset}/{yyyyq}/ | 1.0.0 | 目标路径模板,支持占位符 | 模板变量见 2.14 节 |
sink.path_style | bool | true | 1.0.0 | 是否路径风格寻址 | — |
sink.access_key_ref | string | env:GL_SINK_ACCESS_KEY | 1.1.0 | 访问键引用 | — |
sink.secret_key_ref | string | env:GL_SINK_SECRET_KEY | 1.1.0 | 密钥引用 | — |
sink.part_size | bytes | 64MiB | 1.0.0 | 分片大小 | 不得小于 8MiB |
sink.multipart_threshold | bytes | 128MiB | 1.0.0 | 启用分片上传的阈值 | — |
sink.max_concurrency | int | 8 | 1.0.0 | 并发上传数 | 受网络带宽约束 |
sink.max_retries | int | 5 | 1.0.0 | 上传失败重试次数 | — |
sink.retry_backoff_min | duration | 500ms | 2.1.0 | 退避下限 | — |
sink.retry_backoff_max | duration | 60s | 2.1.0 | 退避上限 | — |
sink.retry_on_5xx | bool | true | 2.1.0 | 5xx 是否重试 | — |
sink.retry_on_4xx | bool | false | 2.1.0 | 4xx 是否重试 | 默认不重试,避免无效循环 |
sink.connect_timeout | duration | 5s | 1.0.0 | 建连超时 | — |
sink.write_timeout | duration | 120s | 1.0.0 | 单次写超时 | 大分片建议 180s |
sink.checksum | enum | sha256 | 1.2.0 | 上传校验算法 | — |
sink.verify_after_write | bool | false | 2.2.0 | 写后读回校验 | 代价高,排障时使用 |
sink.checksum_metadata | bool | true | 2.3.0 | 是否写入自定义校验元数据 | 元数据总大小不超过 2KB |
sink.idempotent_keys | bool | true | 2.4.0 | 同名对象覆盖而非重复 | 依赖对象名确定性 |
sink.staging_prefix | string | _staging/ | 2.4.0 | 上传中转前缀 | 完成后原子移动 |
sink.atomic_commit | bool | true | 2.4.0 | 是否启用中转加移动语义 | — |
sink.lifecycle_tier | enum | standard | 2.5.0 | 存储层级:standard、archive | archive 不可即时读取 |
sink.bucket_quota_check | bool | true | 2.6.0 | 写入前检查桶配额 | 使用率到 90% 时告警 |
sink.bucket_quota_warn_ratio | float | 0.9 | 2.6.0 | 配额告警阈值 | 取值 0 到 1 |
sink.max_inflight_bytes | bytes | 2GiB | 2.6.0 | 同时在途字节上限 | 防止打满存储网关 |
sink.write_queue_depth | int | 256 | 2.6.0 | 写队列深度 | 来自 2026-09 事件的调优值 |
sink.backpressure_wait | duration | 30s | 2.6.0 | 队列满时等待时长 | 超时后暂停任务 |
sink.notify_topic | string | guanlan-ingest | 2.2.0 | 写完成后通知的内部消息主题 | 不使用站外地址 |
sink.notify_on | string-list | [success,failure] | 2.2.0 | 通知时机 | — |
sink.cleanup_staging | bool | true | 2.5.0 | 完成后清理中转对象 | — |
2.6 checkpoint — 检查点与断点续传
断点续传依赖检查点与任务锁。检查点写坏是本代理最常见的故障来源,排障时先看 checkpoint 目录与 GL-E-5xxx 错误码。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
checkpoint.enabled | bool | true | 1.0.0 | 是否启用断点续传 | — |
checkpoint.dir | path | /var/lib/guanlan/ckpt | 1.0.0 | 检查点目录 | 需持久化磁盘 |
checkpoint.interval | duration | 30s | 1.0.0 | 检查点写入间隔 | — |
checkpoint.records_interval | uint | 500000 | 1.0.0 | 按记录数触发检查点 | 与时间间隔取先到条件 |
checkpoint.max_size | bytes | 512MiB | 2.0.0 | 单个检查点文件上限 | 超限会触发压缩 |
checkpoint.compress | bool | true | 2.1.0 | 检查点是否 zstd 压缩 | — |
checkpoint.keep | int | 3 | 1.0.0 | 保留的历史检查点个数 | 滚动删除最旧 |
checkpoint.keep_days | int | 14 | 2.2.0 | 检查点保留天数 | 与 keep 共同生效 |
checkpoint.fsync | bool | true | 1.3.0 | 写入后是否落盘 | 依赖 agent.fs_sync |
checkpoint.atomic_write | bool | true | 1.4.0 | 使用临时文件加 rename 原子写 | — |
checkpoint.upload_to_sink | bool | false | 2.3.0 | 是否把检查点同步到目标桶 | — |
checkpoint.upload_prefix | string | _ckpt/{agent_id}/ | 2.3.0 | 检查点上传前缀 | — |
checkpoint.lock_ttl | duration | 120s | 2.0.0 | 任务锁有效期 | — |
checkpoint.lock_renew | duration | 30s | 2.0.0 | 锁续期间隔 | 需小于 lock_ttl 的一半 |
checkpoint.orphan_scan_interval | duration | 600s | 2.4.0 | 孤儿任务扫描间隔 | — |
checkpoint.orphan_ttl | duration | 86400s | 2.4.0 | 孤儿任务回收时间 | — |
checkpoint.resume_mode | enum | offset | 1.5.0 | 恢复方式:offset、records、restart | offset 最精确 |
checkpoint.max_resume_attempts | int | 3 | 2.2.0 | 同一任务的恢复尝试上限 | 超过后转 failed |
checkpoint.state_file_mode | string | 0600 | 2.1.0 | 状态文件权限 | — |
checkpoint.backup_on_resume | bool | true | 2.5.0 | 恢复前是否备份检查点 | — |
checkpoint.hash_verify | bool | false | 2.5.2 | 恢复时校验 offset 一致性 | — |
checkpoint.flush_on_shutdown | bool | true | 2.5.4 | 退出前强制写检查点 | — |
checkpoint.pause_on_backlog | bool | true | 2.6.0 | 写队列积压时暂停检查点 | 来自 2026-09 复盘改进项 |
checkpoint.backlog_threshold | int | 4096 | 2.6.0 | 积压判定条数 | 与 sink.write_queue_depth 联动 |
2.7 retry — 重试与退避
2.6.0 起重试有上限(默认 5 次),这是一次不兼容调整:老配置文件里写 retry.retry_forever=true 的会在启动时被拒绝,需手工迁移。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
retry.enabled | bool | true | 1.0.0 | 全局重试开关 | — |
retry.policy | enum | exponential | 1.0.0 | 策略:fixed、exponential、linear | — |
retry.max_attempts | int | 5 | 1.0.0 | 最大尝试次数,包含首次 | 2.6.0 起由无限重试改为有上限 |
retry.initial_interval | duration | 1s | 1.0.0 | 初始间隔 | — |
retry.multiplier | float | 2.0 | 1.0.0 | 指数倍数 | — |
retry.max_interval | duration | 60s | 1.0.0 | 最大间隔 | — |
retry.jitter | float | 0.2 | 2.1.0 | 抖动比例 | 0 到 1 |
retry.retryable_codes | string-list | [] | 2.2.0 | 额外视为可重试的错误码 | 按 GL-E 编号填写 |
retry.non_retryable_codes | string-list | [] | 2.2.0 | 显式不可重试的错误码 | 优先于 retryable_codes |
retry.max_elapsed | duration | 1800s | 2.3.0 | 总重试时长上限 | — |
retry.reset_on_progress | bool | true | 2.3.0 | 有进度时是否重置计数 | — |
retry.on_exhausted | enum | fail | 2.0.0 | 重试耗尽后动作:fail、skip、quarantine | — |
retry.notify_on_exhausted | bool | true | 2.4.0 | 耗尽时是否发通知 | 通知走站内工单主题 |
retry.concurrent_limit | int | 64 | 2.4.0 | 重试并发上限 | 避免重试风暴 |
retry.retry_unsafe_ops | bool | false | 2.5.0 | 是否重试非幂等写操作 | 默认禁止 |
retry.backoff_cap_factor | float | 3.0 | 2.6.0 | 退避上限相对 max_interval 的倍数 | — |
2.8 tls — 证书与传输安全
内部链路也要求 TLS。跳过校验的参数仅用于联调,生产环境开启会触发审计告警。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
tls.enabled | bool | true | 1.0.0 | 全局 TLS 开关 | 内部链路也建议开启 |
tls.ca_file | path | /etc/guanlan/tls/ca.pem | 1.0.0 | CA 证书 | — |
tls.cert_file | path | /etc/guanlan/tls/agent.crt | 1.0.0 | 客户端证书,双向认证时使用 | — |
tls.key_file | path | /etc/guanlan/tls/agent.key | 1.0.0 | 客户端私钥 | 权限必须为 0600 |
tls.min_version | enum | TLS1_2 | 2.0.0 | 最低 TLS 版本 | — |
tls.cipher_suites | string-list | [] | 2.0.0 | 允许的套件列表 | 留空使用库默认值 |
tls.server_name | string | 空 | 1.2.0 | SNI 名称 | 多域名证书时必填 |
tls.insecure_skip_verify | bool | false | 1.0.0 | 跳过证书校验 | 生产禁用 |
tls.reload_interval | duration | 0 | 2.3.0 | 证书热加载间隔,0 表示关闭 | — |
tls.ocsp_enabled | bool | false | 2.4.0 | 是否做 OCSP 检查 | 内网无 OCSP 服务,保持关闭 |
tls.verify_hostname | bool | true | 2.2.0 | 是否校验证书主机名 | — |
tls.client_auth | bool | false | 2.1.0 | 是否要求客户端证书 | 仅内部双向认证链路 |
2.9 scheduler — 调度与时间窗
代理内置轻量调度器,负责扫描、拆分与时间窗控制。若接入外部调度(如 Airflow),建议把 scheduler.enabled 设为 false。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
scheduler.enabled | bool | true | 1.0.0 | 是否启用内置调度器 | — |
scheduler.scan_interval | duration | 60s | 1.0.0 | 源目录或桶的扫描间隔 | — |
scheduler.max_tasks | int | 32 | 1.0.0 | 并行任务数上限 | 受 agent.max_workers 约束 |
scheduler.task_queue_size | int | 256 | 1.2.0 | 任务队列长度 | — |
scheduler.lease_ttl | duration | 120s | 2.0.0 | 任务租约时长 | — |
scheduler.lease_renew | duration | 40s | 2.0.0 | 租约续期间隔 | — |
scheduler.cron | string | 空 | 1.3.0 | 定时触发表达式,5 字段 | 时区由 agent.timezone 决定 |
scheduler.window_start | string | 空 | 2.2.0 | 允许执行的时间窗起点 | 形如 22:00 |
scheduler.window_end | string | 空 | 2.2.0 | 允许执行的时间窗终点 | 形如 05:00 |
scheduler.max_window_lag | duration | 600s | 2.2.0 | 错过时间窗的补跑上限 | — |
scheduler.task_split_records | uint | 20000000 | 1.4.0 | 超过该记录数时拆分任务 | 与 v2 单任务上限一致 |
scheduler.task_split_bytes | bytes | 512GiB | 2.1.0 | 按字节拆分任务的阈值 | — |
scheduler.rebalance_interval | duration | 300s | 2.3.0 | 任务重平衡检查间隔 | — |
scheduler.sticky_partition | bool | true | 2.3.0 | 分片是否粘性绑定到代理 | — |
scheduler.blackout_dates | string-list | [] | 2.4.0 | 禁跑日期,ISO 日期格式 | — |
scheduler.priority_classes | map | {} | 2.4.0 | 任务优先级分类配置 | 键为任务名前缀 |
scheduler.lower_priority_when | duration | 0 | 2.5.0 | 运行超过该时长后降级 | 0 表示不降级 |
scheduler.pause_on_source_error | bool | true | 2.5.0 | 源端连续失败时是否暂停扫描 | — |
scheduler.source_error_threshold | int | 10 | 2.5.0 | 连续失败次数阈值 | — |
scheduler.dst_adjust | bool | true | 2.6.0 | 是否做夏令时调整 | 仅海外合作方源需要 |
2.10 resource — 资源限制
与 cgroup 协作的资源限制参数。容器部署时部分参数会被编排层覆盖,以实际 cgroup 为准。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
resource.cpu_limit | string | 空 | 2.0.0 | 软 CPU 限制,写入 cgroup | 容器内由编排层覆盖 |
resource.memory_limit | string | 空 | 2.0.0 | 软内存限制 | — |
resource.memory_warn_ratio | float | 0.85 | 2.2.0 | 内存告警水位 | — |
resource.memory_reserve | bytes | 2GiB | 2.4.0 | 预留内存,避免本进程被 OOM | — |
resource.disk_warn_ratio | float | 0.8 | 2.1.0 | 工作区磁盘告警水位 | — |
resource.disk_critical_ratio | float | 0.92 | 2.1.0 | 磁盘危险水位,触发暂停 | — |
resource.max_temp_files | int | 200000 | 2.3.0 | 工作区临时文件数量上限 | — |
resource.temp_gc_interval | duration | 300s | 2.3.0 | 临时文件回收间隔 | — |
resource.max_file_descriptors | int | 65535 | 2.0.0 | 文件描述符上限 | 不得超过系统 ulimit |
resource.io_weight | int | 500 | 2.4.0 | cgroup IO 权重 | 1 到 1000 |
resource.cpu_weight | int | 500 | 2.4.0 | cgroup CPU 权重 | 1 到 10000 |
resource.network_bandwidth_limit | string | 空 | 2.6.0 | 网络带宽限制,如 400MiB | 跨机房链路使用 |
resource.network_burst | bytes | 64MiB | 2.6.0 | 带宽突发桶 | — |
resource.pause_on_memory_pressure | bool | true | 2.6.0 | 内存压力时是否暂停新任务 | — |
2.11 metrics — 指标暴露
指标前缀与标签直接影响重明侧的基数。新开标签前先估算基数,超过 5000 会被丢弃。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
metrics.enabled | bool | true | 1.0.0 | 是否暴露指标端点 | — |
metrics.addr | addr | 10.42.7.23:9109 | 1.0.0 | 指标监听地址 | 仅内网地址 |
metrics.path | string | /metrics | 1.0.0 | 指标拉取路径 | — |
metrics.interval | duration | 15s | 2.2.0 | 内部聚合间隔 | — |
metrics.prefix | string | guanlan_agent | 1.0.0 | 指标前缀 | 变更会影响看板 |
metrics.labels | map | {} | 1.2.0 | 附加标签 | 注意标签基数 |
metrics.task_labels | bool | true | 2.3.0 | 是否按任务打标签 | 任务多时基数较高 |
metrics.max_label_cardinality | int | 5000 | 2.4.0 | 标签基数上限 | 超限后丢弃新标签 |
metrics.histogram_buckets | string-list | [] | 2.2.0 | 直方图桶边界 | 留空使用默认值 |
metrics.include_runtime_metrics | bool | true | 1.0.0 | 是否包含运行时指标 | — |
metrics.expose_checkpoint_size | bool | false | 2.3.0 | 是否暴露检查点大小 | — |
metrics.expose_source_latency | bool | true | 2.2.0 | 源端延迟指标 | — |
metrics.expose_sink_latency | bool | true | 2.2.0 | 目标端延迟指标 | — |
metrics.push_gateway | string | 空 | 2.5.0 | 推送网关地址,留空为拉取模式 | — |
metrics.push_interval | duration | 60s | 2.5.0 | 推送间隔 | — |
metrics.profile_enabled | bool | false | 2.3.0 | 是否开启性能采样接口 | 仅排障时临时开启 |
metrics.profile_addr | addr | loopback:9110 | 2.3.0 | 性能采样监听地址 | — |
2.12 log — 日志与审计
日志与审计分离;审计日志不随普通日志滚动策略清理,需定期归档。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
log.level | enum | info | 1.0.0 | 日志级别:debug、info、warn、error | 排障时临时开 debug |
log.format | enum | text | 1.0.0 | 格式:text 或 json | 采集到重明建议 json |
log.file | path | /var/log/guanlan/agent.log | 1.0.0 | 日志文件路径 | — |
log.max_size | bytes | 100MiB | 1.0.0 | 单文件滚动阈值 | — |
log.max_backups | int | 7 | 1.0.0 | 保留份数 | — |
log.max_age | int | 14 | 1.0.0 | 保留天数 | — |
log.compress | bool | true | 1.2.0 | 滚动后是否压缩 | — |
log.sanitize | bool | true | 2.0.0 | 是否脱敏访问键与令牌 | 生产必须开启 |
log.sanitize_fields | string-list | [secret,token,authorization] | 2.0.0 | 额外脱敏字段名 | — |
log.include_task_id | bool | true | 2.1.0 | 日志中是否带任务 ID | — |
log.sampling | bool | false | 2.2.0 | 是否采样输出 | 高吞吐时段可开启 |
log.sample_ratio | float | 0.1 | 2.2.0 | 采样比例 | 0 到 1 |
log.console | bool | true | 1.0.0 | 是否输出到标准输出 | 容器部署保持 true |
log.console_format | enum | text | 2.1.0 | 控制台输出格式 | — |
log.audit_file | path | /var/log/guanlan/audit.log | 2.3.0 | 审计日志文件 | 记录配置变更与权限操作 |
log.audit_level | enum | info | 2.3.0 | 审计日志级别 | — |
2.13 misc — 其他
干跑、版本检查、排障包等杂项参数。
| 参数 | 类型 | 默认值 | 起始 | 说明 | 约束 / 备注 |
|---|---|---|---|---|---|
misc.dry_run | bool | false | 1.0.0 | 干跑模式,只扫描不写入 | 首次接入建议开启 |
misc.exit_code_on_warn | bool | false | 2.2.0 | 存在 warning 时是否返回非零退出码 | CI 场景使用 |
misc.usage_stats_enabled | bool | false | 1.5.0 | 是否上报内部使用统计 | 仅上报到重明本机端点 |
misc.usage_stats_endpoint | string | chongming.internal:4317 | 1.5.0 | 统计上报端点 | 内部地址 |
misc.version_check | bool | false | 2.0.0 | 是否检查版本兼容性 | 离线环境关闭 |
misc.expected_version | string | 2.6.3 | 2.0.0 | 期望版本,不匹配时告警 | — |
misc.experimental_features | string-list | [] | 2.4.0 | 开启的实验特性 | 生产禁用 |
misc.env_prefix | string | GL_ | 1.1.0 | 环境变量前缀 | — |
misc.config_strict | bool | true | 2.3.0 | 未知配置项是否报错 | 建议 true |
misc.watch_config | bool | true | 2.4.0 | 是否监听配置文件变化 | — |
misc.metrics_flush_on_exit | bool | true | 2.5.0 | 退出前是否刷新指标 | — |
misc.notify_channel | enum | ticket | 2.2.0 | 通知渠道:ticket 或 none | — |
misc.support_bundle_dir | path | /var/lib/guanlan/support | 2.5.0 | 排障包输出目录 | — |
misc.support_bundle_redact | bool | true | 2.5.0 | 排障包是否脱敏 | — |
misc.clock_skew_warn | duration | 5s | 2.6.0 | 时钟偏差告警阈值 | 签名场景需要 |
2.14 sink.path_template 占位符
目标路径模板支持以下占位符,渲染时按 UTC 与 agent.timezone 分别取值;拼写错误的占位符会原样保留并给出 warning,不会导致任务失败。
| 占位符 | 含义 | 示例 |
|---|---|---|
| {dataset} | 数据集名,与 source 配置中的 dataset 一致 | camera-calib-2026q4 |
| {dataset_id} | 数据集内部 ID,v2 为字符串 slug | camera-calib-2026q4 |
| {yyyy} | 四位年份 | 2026 |
| {yyyyq} | 年份加季度 | 2026q4 |
| {yyyymm} | 年月 | 202610 |
| {yyyymmdd} | 年月日 | 20261014 |
| {agent_id} | 代理实例标识 | gz-agent-01 |
| {task_id} | 任务 ID | cj_7f3a91 |
| {partition} | 分区表达式渲染结果 | site=yehang-a |
| {shard} | 分片序号,补零到 4 位 | 0003 |
3. 环境变量映射
下表中的环境变量优先级高于配置文件。容器部署时,密钥类字段必须通过环境变量注入,不得写进镜像或配置文件。环境变量只在进程启动时读取一次,运行期修改需要重启(热加载不覆盖环境变量)。
| 环境变量 | 对应参数 | 说明 |
|---|---|---|
| GL_AGENT_ID | agent.id | 实例标识,优先于配置文件 |
| GL_AGENT_MODE | agent.mode | 运行模式 |
| GL_AGENT_DATA_DIR | agent.data_dir | 状态目录 |
| GL_AGENT_MAX_WORKERS | agent.max_workers | 并发工作协程数 |
| GL_AGENT_TAGS | agent.tags | 标签,逗号分隔 |
| GL_LOG_LEVEL | log.level | 日志级别 |
| GL_LOG_FORMAT | log.format | 日志格式 |
| GL_METRICS_ADDR | metrics.addr | 指标监听地址 |
| GL_SRC_S3_ENDPOINT | source.s3.endpoint | 源端地址 |
| GL_SRC_S3_BUCKET | source.s3.bucket | 源桶 |
| GL_SRC_S3_REGION | source.s3.region | 源端区域 |
| GL_SRC_ACCESS_KEY | source.s3.access_key_ref | 源端访问键(引用目标是密钥本身) |
| GL_SRC_SECRET_KEY | source.s3.secret_key_ref | 源端密钥 |
| GL_SRC_S3_PREFIX | source.s3.prefix | 源前缀 |
| GL_SRC_S3_MAX_CONNS | source.s3.max_conns | 源端连接数 |
| GL_SRC_S3_SHARD_LIST | source.s3.shard_list | 是否分片列举 |
| GL_SRC_POSIX_ROOT | source.posix.root | POSIX 源根目录 |
| GL_SINK_ENDPOINT | sink.endpoint | 目标端地址 |
| GL_SINK_BUCKET | sink.bucket | 目标桶 |
| GL_SINK_REGION | sink.region | 目标区域 |
| GL_SINK_ACCESS_KEY | sink.access_key_ref | 目标端访问键 |
| GL_SINK_SECRET_KEY | sink.secret_key_ref | 目标端密钥 |
| GL_SINK_PATH_TEMPLATE | sink.path_template | 目标路径模板 |
| GL_SINK_PART_SIZE | sink.part_size | 分片大小 |
| GL_CHECKPOINT_DIR | checkpoint.dir | 检查点目录 |
| GL_CHECKPOINT_INTERVAL | checkpoint.interval | 检查点间隔 |
| GL_RETRY_MAX_ATTEMPTS | retry.max_attempts | 最大重试次数 |
| GL_TLS_CA_FILE | tls.ca_file | CA 证书路径 |
| GL_SCHEDULER_CRON | scheduler.cron | 定时表达式 |
| GL_SCHEDULER_WINDOW_START | scheduler.window_start | 时间窗起点 |
| GL_DRY_RUN | misc.dry_run | 干跑模式 |
| GL_CONFIG_STRICT | misc.config_strict | 严格配置模式 |
| GL_EXPECTED_VERSION | misc.expected_version | 期望版本 |
| GL_SUPPORT_BUNDLE_DIR | misc.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-2016 | POSIX 挂载点不可用 | 检查息壤网关状态与 mount 参数 |
| GL-E-2017 | 文件稳定性检查超时 | 大文件写入中,等待后重试或调大 stability_wait |
| GL-E-3001 | schema 文件缺失 | 确认 transform.schema_registry 下有对应 yaml |
| GL-E-3002 | schema 校验失败 | 按错误提示的字段名修正源数据或 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-3013 | parquet 写入失败 | 检查磁盘空间与 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-7002 | panic 恢复,进程继续运行 | 看 crash dump 目录;频繁出现提工单 |
| GL-E-7003 | 资源泄漏告警 | 重启代理并保留排障包 |
| GL-E-7004 | 指标注册冲突 | 检查是否加载了重复插件 |
| GL-E-7005 | 日志脱敏失败,已阻塞输出 | 不要绕过,立即提工单 |
| GL-E-7006 | 未归类错误 | 记录 request id 与时间,提工单 |
5. 默认值变更记录
只记录会影响行为的默认值变化,纯文档修订不在此列。升级前请对照本表检查是否有依赖旧默认值的配置。
| 版本 | 日期 | 参数 | 旧默认值 | 新默认值 | 原因 |
|---|---|---|---|---|---|
| 2.6.3 | 2026-10-18 | source.s3.list_page_size | 500 | 1000 | 北辰分页上限实测为 1000,调大以减少列举轮次 |
| 2.6.0 | 2026-08-30 | retry.max_attempts | 0(无限) | 5 | 修复无限重试导致的放大效应 |
| 2.6.0 | 2026-08-30 | sink.write_queue_depth | 新参数 | 256 | 配合积压保护 |
| 2.6.0 | 2026-08-30 | checkpoint.pause_on_backlog | 新参数 | true | 来自 2026-09 事件的改进项 |
| 2.6.0 | 2026-08-30 | source.s3.shard_list | 新参数 | false | 北辰分页不稳定规避 |
| 2.6.0 | 2026-08-30 | misc.clock_skew_warn | 新参数 | 5s | 签名场景需要 |
| 2.5.4 | 2026-05-11 | checkpoint.flush_on_shutdown | 新参数 | true | 减少异常退出丢进度 |
| 2.5.2 | 2026-04-02 | source.s3.follow_redirects | 新参数 | false | — |
| 2.5.0 | 2026-02-10 | sink.lifecycle_tier | 新参数 | standard | 配合息壤分层存储 |
| 2.5.0 | 2026-02-10 | misc.support_bundle_redact | 新参数 | true | 排障包脱敏 |
| 2.4.0 | 2025-12-01 | scheduler.blackout_dates | 新参数 | [] | 年报季禁跑 |
| 2.4.0 | 2025-12-01 | source.s3.rate_limit_qps | 新参数 | 0 | 源端限流保护 |
| 2.4.0 | 2025-12-01 | metrics.max_label_cardinality | 新参数 | 5000 | 控制指标基数 |
| 2.4.0 | 2025-12-01 | sink.staging_prefix | 新参数 | _staging/ | 原子提交 |
| 2.3.0 | 2025-09-15 | sink.checksum_metadata | 新参数 | true | 下游校验 |
| 2.3.0 | 2025-09-15 | log.audit_file | 新参数 | 见默认值 | 审计要求 |
| 2.3.0 | 2025-09-15 | agent.admin_enabled | 新参数 | false | 本机管理接口 |
| 2.3.0 | 2025-09-15 | retry.max_elapsed | 新参数 | 1800s | 限制总重试时长 |
| 2.2.0 | 2025-06-20 | source.s3.secret_header | 新参数 | X-Beichen-Sign | 兼容层要求 |
| 2.2.0 | 2025-06-20 | transform.field_case | 新参数 | keep | 下游字段统一 |
| 2.2.0 | 2025-06-20 | metrics.interval | 新参数 | 15s | — |
| 2.1.0 | 2025-03-08 | agent.instance | 新参数 | 空 | 多实例部署 |
| 2.1.0 | 2025-03-08 | transform.strict_schema | 新参数 | false | — |
| 2.1.0 | 2025-03-08 | retry.jitter | 新参数 | 0.2 | 减少重试风暴 |
| 2.0.0 | 2024-11-02 | source.s3.tls.min_version | TLS1_0 | TLS1_2 | 安全基线 |
| 2.0.0 | 2024-11-02 | agent.plugin_whitelist | 新参数 | [s3,posix] | 插件安全 |
| 2.0.0 | 2024-11-02 | log.sanitize | 新参数 | true | 日志脱敏 |
| 2.0.0 | 2024-11-02 | transform.compression | gzip | zstd | 压缩率与速度平衡 |
| 1.9.0 | 2024-08-19 | source.posix.sparse_handling | 新参数 | skip | — |
| 1.9.0 | 2024-08-19 | transform.row_limit | 新参数 | 0 | 防止误采 |
| 1.8.0 | 2024-06-03 | transform.dedup_enabled | 新参数 | true | 去重需求 |
| 1.7.0 | 2024-04-11 | source.posix.owner_check | 新参数 | false | 共享盘场景 |
| 1.6.0 | 2024-02-26 | source.posix.stability_wait | 10s | 30s | 写入中的大文件误采 |
| 1.5.0 | 2023-12-18 | checkpoint.resume_mode | records | offset | 精确恢复 |
| 1.4.0 | 2023-11-07 | source.s3.session_token_ref | 新参数 | 空 | 临时密钥支持 |
| 1.3.0 | 2023-09-25 | sink.verify_after_write | 新参数 | false | — |
| 1.2.0 | 2023-08-14 | source.s3.max_idle_conns | 新参数 | 16 | 连接复用 |
| 1.1.0 | 2023-06-30 | agent.workspace | 新参数 | /data/workspace | 大对象临时区 |
| 1.0.0 | 2023-05-12 | 首批参数 | — | — | 代理首个版本,共 46 个参数 |
6. 指标目录
代理暴露的指标前缀为 guanlan_agent,默认由重明采集。指标基数的注意事项见第 2 节 metrics 组。
| 指标名称 | 类型 | 标签 | 说明 | 保留期 |
|---|---|---|---|---|
| guanlan_agent_info | gauge | version、mode | 代理版本与模式,恒为 1 | 30d |
| guanlan_agent_task_total | counter | state | 任务计数,按成功失败等状态 | 90d |
| guanlan_agent_task_duration_seconds | histogram | dataset | 任务耗时分布 | 90d |
| guanlan_agent_task_inflight | gauge | dataset | 运行中任务数 | 90d |
| guanlan_agent_source_read_bytes_total | counter | source、dataset | 源端读取字节数 | 30d |
| guanlan_agent_source_read_errors_total | counter | source、code | 源端读取错误计数 | 90d |
| guanlan_agent_source_latency_seconds | histogram | source | 源端请求延迟 | 30d |
| guanlan_agent_transform_rows_total | counter | dataset | 转换行数 | 30d |
| guanlan_agent_transform_errors_total | counter | dataset、code | 转换错误计数 | 90d |
| guanlan_agent_transform_batch_seconds | histogram | dataset | 单批转换耗时 | 30d |
| guanlan_agent_sink_write_bytes_total | counter | bucket、dataset | 写入字节数 | 30d |
| guanlan_agent_sink_write_errors_total | counter | bucket、code | 写入错误计数 | 90d |
| guanlan_agent_sink_latency_seconds | histogram | bucket | 写入延迟 | 30d |
| guanlan_agent_sink_queue_depth | gauge | — | 写队列深度 | 30d |
| guanlan_agent_sink_inflight_bytes | gauge | — | 在途字节数 | 30d |
| guanlan_agent_checkpoint_write_seconds | histogram | — | 检查点写入耗时 | 30d |
| guanlan_agent_checkpoint_age_seconds | gauge | dataset | 距最近检查点的时间 | 30d |
| guanlan_agent_checkpoint_errors_total | counter | code | 检查点错误计数 | 90d |
| guanlan_agent_retry_total | counter | stage、code | 重试次数 | 90d |
| guanlan_agent_quarantine_total | counter | stage | 进入隔离区的对象数 | 90d |
| guanlan_agent_worker_busy_ratio | gauge | worker | 工作协程繁忙比例 | 30d |
| guanlan_agent_memory_bytes | gauge | type | 进程内存占用 | 30d |
| guanlan_agent_disk_used_ratio | gauge | mount | 工作区磁盘使用率 | 30d |
| guanlan_agent_config_reload_total | counter | result | 配置热加载次数 | 90d |
| guanlan_agent_config_error | gauge | — | 配置错误标记,1 表示有问题 | 90d |
| guanlan_agent_clock_skew_seconds | gauge | — | 本机时钟偏差 | 30d |
| guanlan_agent_scheduler_scanned_total | counter | source | 扫描到的对象数 | 30d |
| guanlan_agent_scheduler_pending | gauge | source | 待处理对象数 | 90d |
| guanlan_agent_api_requests_total | counter | endpoint、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 万个小 JSON | 18400 文件/分钟 | 6 核 | 4.1GiB | p95 单文件 38ms | 与对象大小强相关 |
| 大文件顺序读 | 单对象 8GiB | 1.7GiB/s | 8 核 | 2.6GiB | p95 读 210ms | 受网关带宽限制 |
| parquet 转换 | 1000 万行、40 列 | 约 9 分 40 秒 | 8 核 | 9.8GiB | p99 批 6.1s | zstd 级别 3 |
| 写入息壤 | 单批 500GiB | 620MiB/s | 8 核 | 3.2GiB | p95 片 240ms | 4 个并发上传 |
| 检查点写入 | 512MiB 状态 | 每次 1.9s | 2 核 | — | — | 含 fsync |
| 断点恢复 | 中断于 62% | 恢复约 40 秒 | 4 核 | 1.1GiB | — | offset 模式 |
| 列举 100 万对象 | 北辰共享桶 | 单轮约 6 分钟 | 2 核 | — | — | 分页 1000、8 并发 |
| 列举 100 万对象(分片) | 北辰共享桶 | 单轮约 4 分 20 秒 | 2 核 | — | — | 256 分片 |
| 跨机房回灌 | 400MiB 带宽限制 | 382MiB/s | 8 核 | 3.0GiB | p95 片 310ms | 北辰到夜航 |
容量估算经验值:按日增 1 亿行、单行 1.2KiB 估算,落盘后约 1.1TiB/天;建议单代理不超过 3 个并行大任务,超过后拆分代理或错峰。
10. 附录 D:现场排查清单
按顺序核对,多数现场问题能在前 10 条内定位。清单同时用于新节点验收。
- 启动前确认 agent.data_dir 与 agent.workspace 不在同一块盘上,避免检查点与临时文件互相挤占。
- 用 agent.mode=check 先跑一遍配置校验,再以 daemon 启动。
- 确认源端访问键没有写进配置文件,只以 env: 或 file: 形式引用。
- 首次接入开启 misc.dry_run,确认扫描到的对象数与源端控制台账单一致后再关闭。
- 北辰源必须设置 source.s3.path_style=true 与 secret_header=X-Beichen-Sign。
- 北辰源建议同时开启 shard_list 与 verify_object_count,尤其在桶内对象持续变化时。
- 确认源端 TLS 证书链完整,不要用跳过校验来临时绕过。
- 时间同步:chronyc tracking 的偏差应远小于 misc.clock_skew_warn。
- 检查系统 ulimit,确保 resource.max_file_descriptors 不超过实际限制。
- 转换阶段变更后,先在测试数据集运行一次并比对 schema 版本。
- 检查点目录使用持久化磁盘,不要放在 tmpfs 或容器临时层。
- 多实例同主机部署时,每个实例必须独立的 data_dir、run_dir 与 pid_file。
- 确认 scheduler.window_start 与 window_end 与实际业务时窗一致,避免与训练回灌抢带宽。
- 接入外部调度器时把 scheduler.enabled 设为 false,避免双调度重复采集。
- 设置 sink.bucket_quota_warn_ratio,桶接近配额时提前收到告警。
- 检查 sink.max_inflight_bytes 是否与网关承载能力匹配。
- 日志级别默认 info,排障时才临时开 debug,并设置自动恢复时间。
- 确认 log.sanitize=true,避免访问键进入日志。
- 审计日志单独归档,不随普通日志滚动清理。
- 升级前备份 /etc/guanlan 与检查点目录的元数据文件。
- 升级后第一次启动会做检查点版本迁移,不要在业务高峰执行。
- 用排障包(misc.support_bundle_dir)收集现场信息,不要手工拷贝敏感配置。
- 确认插件版本与代理 ABI 匹配,插件目录权限不可写。
- 内存紧的节点降低 transform.batch_bytes,不要只调 batch_rows。
- 监控 guanlan_agent_sink_queue_depth,持续走高说明目标端承压。
- 监控 guanlan_agent_checkpoint_age_seconds,突然增大说明检查点卡住。
- 确认 misc.config_strict=true,避免拼写错误的参数被静默忽略。
- 变更后用 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 | 北冥机器学习加速卡型号前缀 | 所内统一命名,具体型号见硬件清单 |
| ckpt | checkpoint | 检查点,记录任务进度的状态文件 |
| CFG | configuration | 配置 |
| dataset | 数据集 | 逻辑数据集合,对应一个 schema 序列 |
| E2E | end-to-end | 端到端 |
| fsync | file sync | 文件落盘同步 |
| GL | guanlan | 观澜产品代号 |
| GL-E | guanlan error | 观澜错误码前缀 |
| IP | internet protocol | 网络协议 |
| JSON | javascript object notation | 数据交换格式 |
| KB | knowledge base | 知识库 |
| MLU | 寒武纪加速卡型号 | 本所评测机使用 |
| NFS | network file system | 网络文件系统 |
| NPU | neural processing unit | 神经网络处理器 |
| OOM | out of memory | 内存耗尽 |
| p95/p99 | percentile | 延迟分位数 |
| parquet | 列式存储格式 | 数据落地常用格式 |
| posix | 可移植操作系统接口 | 此处指 POSIX 文件语义源 |
| PVC | persistent volume claim | 持久卷声明 |
| RBAC | role based access control | 基于角色的访问控制 |
| RSS | resident set size | 常驻内存 |
| S3 | simple storage service | 对象存储协议 |
| SLA | service level agreement | 服务等级约定 |
| SLO | service level objective | 服务等级目标 |
| SNI | server name indication | TLS 服务器名称指示 |
| SSO | single sign-on | 统一登录 |
| TLS | transport layer security | 传输层安全 |
| TTL | time to live | 有效期 |
| UUID | universally unique identifier | 通用唯一标识符 |
| yaml | yaml aint markup language | 配置格式 |
| Zstd | zstandard | 压缩算法 |
| IAM | identity and access management | 身份与访问管理 |
13. 文档维护与反馈
本手册随 guanlan-agent 版本发布更新;补丁版本只修正错误,不新增章节。发现参数说明与代码不一致时,在本仓库提工单(标签 docs,同时 @ 观澜组值班),不要在共享文档里直接改参数默认值——默认值以参数注册表为准,文档只是描述。
相关文档:观澜数据服务 API 参考 v2.6.3 · 星槎部署手册 · OOM 扩散事件复盘 · 运维手册库 · 文档中心