第4章 配置项详解：基础参数（host、port、log_level）
本章目标
- 理解 host、port、log_level 三个基础参数的作用域与生效机制
- 掌握三种配置修改方式（配置文件、环境变量、命令行）及其优先级规则
- 能够独立完成 fast-follow 模块的基础网络绑定与日志级别配置
- 熟练使用验证命令确认配置已正确加载并生效
核心原理
fast-follow 模块启动时，必须明确三个基础参数才能完成网络初始化与日志系统建立。这三个参数分别控制模块的监听地址、通信端口以及日志输出粒度。它们的取值来源按优先级从高到低依次为：命令行参数 > 环境变量 > 配置文件 > 编译期默认值。
参数作用域速览
host — 决定模块监听哪个网络接口，默认
port — 决定模块对外服务的 TCP 端口，默认
log_level — 控制日志输出详细程度，可选
host — 决定模块监听哪个网络接口，默认
0.0.0.0 表示绑定所有可用接口；port — 决定模块对外服务的 TCP 端口，默认
8080；log_level — 控制日志输出详细程度，可选
debug、info、warn、error，默认 info。
下图展示了从配置源到模块运行的完整参数生效链路：
配置步骤
方式一：通过配置文件设置
fast-follow 模块启动时默认读取 fastfollow.yaml（或 fastfollow.json），基础参数位于配置文件的顶层字段：
# fastfollow.yaml
host: "0.0.0.0"
port: 8080
log_level: "info"启动时指定配置文件路径：
fast-follow --config /etc/fastfollow/fastfollow.yaml方式二：通过环境变量覆盖
环境变量命名规则为 FASTFOLLOW_<参数名大写>。设置后启动模块会自动读取：
export FASTFOLLOW_HOST="0.0.0.0"
export FASTFOLLOW_PORT="8080"
export FASTFOLLOW_LOG_LEVEL="debug"
fast-follow
提示：环境变量的优先级高于配置文件。当配置文件和环境变量同时存在时，环境变量的值会覆盖配置文件中的值。
方式三：通过命令行参数覆盖
命令行参数的优先级最高，适合临时调试或容器化部署场景：
fast-follow --host 0.0.0.0 --port 8080 --log-level debug支持简写形式（单横线短参数）：
fast-follow -H 0.0.0.0 -p 8080 -l debug验证配置是否生效
模块启动后，通过以下命令验证基础参数的实际加载结果：
# 检查监听地址与端口
ss -tlnp | grep 8080
# 通过健康检查接口验证
curl -s http://127.0.0.1:8080/health | jq .
# 查看启动日志确认日志级别
journalctl -u fast-follow --no-pager | grep "log_level"预期输出示例：
LISTEN 0 128 0.0.0.0:8080 0.0.0.0:* users:(("fast-follow",pid=1234))
{"status":"ok","host":"0.0.0.0","port":8080,"log_level":"info"}
2025-04-01 10:00:00 [INFO] fast-follow started, log_level=info常见错误与解决方法
| 错误现象 | 原因 | 解决方法 |
|---|---|---|
模块启动失败，日志提示 address already in use |
port 被其他进程占用 | 更换端口，或使用 lsof -i:8080 找到占用进程并停止 |
| 模块启动成功但无法从外部访问 | host 绑定为 127.0.0.1（仅本地回环） |
将 host 改为 0.0.0.0 或目标网卡 IP |
| 日志输出过多或过少 | log_level 设置错误或未生效 | 检查命令行参数是否拼写正确（如 --log-level 而非 --loglevel） |
| 环境变量不生效 | 变量名大小写错误或未 export | 使用 echo $FASTFOLLOW_HOST 确认变量已导出 |
注意：当同时使用三种配置方式时，务必牢记优先级规则：命令行 > 环境变量 > 配置文件。调试时建议先查看启动日志中的最终参数值，确认实际生效的是哪个来源。
验收检查清单
- ☐ 使用
ss -tlnp确认模块已在预期的 host:port 上监听 - ☐ 使用
curl访问健康检查接口，返回的 host、port、log_level 与实际配置一致 - ☐ 分别验证三种配置方式（配置文件、环境变量、命令行）均能独立生效
- ☐ 验证优先级规则：同时设置时，高优先级来源正确覆盖低优先级来源
- ☐ 修改 log_level 并重启模块，确认日志输出粒度随之变化（如从 info 改为 debug 后出现调试日志）
- ☐ 确认模块启动日志中无
address already in use或invalid log level等错误