调试指南
本文总结 Curvine 参考仓库中的运行时文件、日志路径、默认端口以及常见调试入口。
配置文件
默认集群配置文件为:
build/dist/conf/curvine-cluster.toml源码中的示例文件位于 etc/curvine-cluster.toml。其中常见配置段包括:
[master][mds][journal][worker][client][transfer][fuse][discovery][fault_injection][log][cli]
脚本中涉及的运行时环境变量包括:
CURVINE_CONF_FILECURVINE_MASTER_HOSTNAMECURVINE_WORKER_HOSTNAMECURVINE_CLIENT_HOSTNAME
包装脚本与运行时文件
build/dist/bin/ 下的包装脚本会先 source conf/curvine-env.sh,再调用 build/dist/lib/ 下的实际二进制。
对于 master、worker、fuse,build/bin/launch-process.sh 还会统一管理:
- pid 文件:
$CURVINE_HOME/<service>.pid - stdout/stderr 输出:
$CURVINE_HOME/logs/<service>.out - 默认配置路径:
CURVINE_CONF_FILE=$CURVINE_HOME/conf/curvine-cluster.toml
因此,如果通过包装脚本启动后立即失败,优先检查 logs/master.out、logs/worker.out、logs/fuse.out。
日志配置
示例配置中的默认值如下。
Master
[master]
log = { level = "info", log_dir = "stdout", file_name = "master.log" }Worker
[worker]
log = { level = "info", log_dir = "stdout", file_name = "worker.log" }Client 与 FUSE
[log]
level = "info"
log_dir = "stdout"
file_name = "curvine.log"CLI
[cli]
log = { level = "warn", log_dir = "stdout", file_name = "cli.log" }当 log_dir = "stdout" 且组件通过包装脚本启动时,结构化日志最终会进入对应的 logs/*.out 文件,因为包装脚本把 stdout 重定向到了这些文件。若将 log_dir 改成目录路径,则需要直接查看该目录下的日志文件。
调试时建议将相关组件的日志级别提升到 debug 或 trace。
启动命令
| 组件 | 包装脚本命令 | 实际二进制 |
|---|---|---|
| Master | bin/curvine-master.sh start | lib/curvine-server --service master --conf $CURVINE_CONF_FILE |
| Worker | bin/curvine-worker.sh start | lib/curvine-server --service worker --conf $CURVINE_CONF_FILE |
| FUSE | bin/curvine-fuse.sh start | lib/curvine-fuse ... --conf $CURVINE_CONF_FILE |
| MDS | bin/curvine-mds.sh start | lib/curvine-server --service mds --conf $CURVINE_CONF_FILE |
| Transfer | bin/curvine-transfer.sh start | lib/curvine-server --service transfer --conf $CURVINE_CONF_FILE |
| 本地集群 | bin/local-cluster.sh start | 依次通过包装脚本启动 Master 与 Worker,启用时同时启动 Transfer |
| CLI | bin/cv ... | lib/curvine-cli |
bin/curvine-fuse.sh 默认挂载点为 /curvine-fuse,也支持通过 --mnt-path 传入自定义挂载点。
默认端口
这些默认值来自 crates/common/curvine-config/src/cluster_conf.rs 与示例配置:
| 服务 | 默认端口 | 来源 |
|---|---|---|
| Master RPC | 8995 | DEFAULT_MASTER_PORT |
| Raft / journal | 8996 | DEFAULT_RAFT_PORT |
| Worker RPC | 8997 | DEFAULT_WORKER_PORT |
| Master Web / metrics | 9010 | DEFAULT_MASTER_WEB_PORT |
| Web 控制台(curvine-web) | 9000 | [web].port |
| Worker Web / metrics | 9002 | DEFAULT_WORKER_WEB_PORT |
| FUSE Web / metrics | 9003 | DEFAULT_FUSE_WEB_PORT |
| MDS RPC | 8998 | [mds].rpc_port |
| MDS Web / metrics | 9004 | [mds].web_port |
| Transfer RPC | 9010 | [transfer].rpc_port |
| Transfer Web / metrics | 9011 | [transfer].web_port |
常见调试流程
服务启动失败
-
先查看包装脚本输出文件:
tail -n 100 build/dist/logs/master.out tail -n 100 build/dist/logs/worker.out tail -n 100 build/dist/logs/fuse.out -
确认配置路径:
echo "$CURVINE_CONF_FILE" -
检查 pid 文件是否陈旧:
ls build/dist/*.pid
Master / Worker 连通性问题
在客户端或其它节点上使用 nc 或 telnet:
nc -vz <master-host> 8995
nc -vz <worker-host> 8997然后检查集群配置与 hostname 覆盖:
CURVINE_MASTER_HOSTNAMECURVINE_WORKER_HOSTNAMEconf/curvine-cluster.toml中的 journal 和 client 地址
集群状态异常
优先使用脚本和 CLI:
cd build/dist
bin/local-cluster.sh status
bin/cv report
bin/cv node指标与性能分析
curl http://<master>:9010/metrics
curl http://<worker>:9002/metrics然后结合 htop、iostat -x 1、sar -n DEV 1、perf record -g 等系统工具继续分析。
FUSE 挂载问题
-
检查挂载是否存在:
mount | grep curvine -
如有需要,手动运行 FUSE:
build/dist/lib/curvine-fuse --conf build/dist/conf/curvine-cluster.toml --mnt-path /mnt/curvine -
检查 FUSE 权限:
ls -l /dev/fuse groups "$USER"
低层调试工具
gdb:本地调试和 core 分析strace -f -e trace=network ...:排查连接问题perf:CPU Profilingbin/cv fs ...:从 Curvine 客户端视角检查路径与元数据
Core Dump
ulimit -c unlimited
gdb build/dist/lib/curvine-server /tmp/core.curvine-server.12345进入 gdb 后优先执行 bt 和 info threads。
反馈问题时建议附带的信息
- 操作系统与架构
- Curvine 版本或 commit
- 精确的包装脚本命令或二进制命令
- 已脱敏的相关配置
- 对应的
logs/*.out或结构化日志片段 - 指标信息与复现步骤