第3章 快速开始：默认配置与最小化示例

本章目标

• 掌握 Fast-Follow 模块默认配置文件的完整结构与各字段含义
• 能够编写一份最小化配置文件并正确启动服务
• 学会使用 curl / 浏览器验证模块是否正常运行
• 理解配置加载优先级与常见调试手段

核心原理

Fast-Follow 模块采用分层配置机制：内置默认配置 → 环境变量覆盖 → 用户配置文件覆盖。默认配置定义在 `fast_follow_defaults.yaml` 中，模块启动时首先加载该文件，再读取用户指定的 `config.yaml`（或通过 `--config` 参数指定路径），相同键以用户配置为准。最小化示例只需提供必须的 listen_port、data_dir、log_level 三个字段，其余全部使用默认值。

配置步骤

1. 默认配置文件结构

以下为完整默认配置的关键层级（省略注释）：

一级键	二级键	默认值	说明
server	listen_port	8080	HTTP 监听端口
server	bind_address	0.0.0.0	绑定地址
server	max_connections	1000	最大并发连接
storage	data_dir	./data	持久化数据目录
storage	sync_interval	5s	磁盘同步间隔
logging	log_level	info	日志级别
logging	log_file	stdout	日志输出目标
auth	enabled	false	是否启用身份认证

2. 编写最小化配置文件

在项目根目录创建 config.yaml，内容如下：

server:
  listen_port: 9090

storage:
  data_dir: ./ff_data

logging:
  log_level: debug

关键点：未指定的字段（如 bind_address、max_connections、auth等）会自动继承默认值。

3. 启动命令

启动 Fast-Follow 模块的两种方式：

• 方式一（推荐）：直接指定配置文件路径

./fast_follow --config config.yaml

• 方式二：使用环境变量覆盖部分字段后再启动（完整配置仍为默认 + 文件）

export FF_LISTEN_PORT=9090
export FF_DATA_DIR=./ff_data
export FF_LOG_LEVEL=debug
./fast_follow

启动后终端应输出类似以下信息：

[INFO] Loading default config from built-in defaults
[INFO] Loading user config from config.yaml
[INFO] Server listening on 0.0.0.0:9090
[DEBUG] Data directory initialized: ./ff_data

4. 验证运行

模块启动后，通过 HTTP 请求验证健康状态接口：

curl -s http://127.0.0.1:9090/health | jq .

预期返回 JSON：

{
  "status": "ok",
  "uptime_seconds": 12,
  "version": "1.2.0"
}

若返回 status: "ok"，则证明默认配置 + 最小化示例已正确运行。

常见错误与解决方法

现象	可能原因	解决方法
启动时报 cannot find config file	指定路径不合法或文件不存在	使用路径或确认当前工作目录包含 config.yaml
端口占用错误 address already in use	指定端口已被其他进程占用	更换 listen_port 或关闭占用进程
健康检查返回 403 Forbidden	配置中启用了 auth 但未设置正确令牌	在配置中设置 auth.enabled: false（默认即 false）
启动后立即退出无日志	data_dir 指向的路径无写入权限	创建目录或使用系统临时目录（如 ./data）
环境变量未生效	变量名前缀不正确或启动时未 export	Fast-Follow 的环境变量统一以 FF_ 开头，如 FF_LISTEN_PORT

验收检查清单

• ✅ 已阅读默认配置表，理解至少 5 个关键字段
• ✅ 成功编写 config.yaml 并保存到 Fast-Follow 二进制所在目录
• ✅ 使用 ./fast_follow --config config.yaml 启动，无错误退出
• ✅ 从终端日志中看到 Server listening on 0.0.0.0:9090 字样
• ✅ curl http://127.0.0.1:9090/health 返回 {"status":"ok"}
• ✅ 了解默认配置与用户配置的合并优先级