seekdb 部署与启动排障助手

1. 用途

帮助用户把 seekdb 从"装好但跑不起来"推进到"能连上并执行 SQL"。覆盖官方二进制包（deb/rpm/tar）在 Linux 上的常见部署问题，不涉及内核代码修改。

适用场景：

seekdb 进程启动后立刻退出，或卡在 server_start x/14；
客户端连 2881 失败（Can't connect to MySQL server）；
日志出现 error while loading shared libraries；
找不到 run/telemetry.json，或启动日志出现 -4007 / OB_NOT_SUPPORTED；
端口冲突、数据目录不可写、内存不足导致的启动失败。

2. 标准排查顺序

必须先收集信息，再下结论。按以下顺序执行（脚本见 scripts/diagnose.sh）：

步骤 1：确认进程与端口

ps -ef | grep -v grep | grep seekdb
ss -lntp | grep 2881

进程不存在 → 说明启动即失败，看日志（步骤 2）；
进程存在但端口没监听 → 还在初始化，或初始化卡住；
端口被别的进程占用 → 换端口或停掉旧实例。

步骤 2：看启动日志与启动输出

ls -l <base-dir>/log/
tail -100 <base-dir>/log/seekdb.log
tail -50 <base-dir>/stdout.log   # 若用 nohup 启动

重点搜索关键字：

| 日志关键字 | 含义 | |---|---| | error while loading shared libraries | 缺少动态库（最常见是 libaio） | | can not get mac address / init uuid node failed | 拿不到网卡 MAC，UUID 初始化失败 | | Container runtime ID is unavailable | 非容器环境下遥测拿不到容器 ID | | OB_ERR_UNEXPECTED + -4016 | 初始化失败（需结合上下文） | | No space left on device | 磁盘不足 | | Permission denied | 目录权限或文件属主问题 | | Address already in use | 端口冲突 |

步骤 3：确认动态库依赖

ldd <seekdb-binary> | grep -i "not found"

若输出 libaio.so.1t64 => not found 或 libaio.so.1 => not found：

# Debian/Ubuntu
apt-get install -y libaio1 || apt-get install -y libaio1t64
# RHEL/CentOS
yum install -y libaio

# 若系统里已有 libaio 但 SONAME 不匹配，可建软链（临时方案）：
LIB=$(find /usr/lib /lib -name "libaio.so.1*" | head -1)
ln -sf "$LIB" /usr/local/lib/libaio.so.1t64
ldconfig

修复后用 LD_LIBRARY_PATH 或 ldconfig 让动态链接器找到它，再执行 seekdb --version 验证。

步骤 4：确认数据目录

ls -ld <base-dir> <base-dir>/store <base-dir>/log <base-dir>/run
df -h <base-dir>

目录属主必须与运行用户一致；
剩余空间建议 ≥ 参数 datafile_size + log_disk_size 的 2 倍；
首次启动需要能写 store/、log/、run/。

步骤 5：确认启动参数

最小可用启动：

cd <base-dir>
LD_LIBRARY_PATH=<libdir> nohup <seekdb-binary> \
  --base-dir=<base-dir> --port=2881 \
  --parameter memory_limit=4G --parameter cpu_count=4 \
  > stdout.log 2>&1 &

memory_limit 不能超过物理内存（建议 ≤ 机器内存的 70%）；
磁盘紧张时显式给 --parameter datafile_size=1G --parameter log_disk_size=1G；
--base-dir 必须是绝对路径，且目录已存在。

步骤 6：确认遥测（仅当需要 telemetry ID 时）

ls -l <base-dir>/run/telemetry.json
python3 -c 'import json;print(json.load(open("<base-dir>/run/telemetry.json"))["content"]["id"])'

若日志出现 Container runtime ID is unavailable; configure a telemetry instance ID：

该实例运行在非容器环境，seekdb 无法从 cgroup 推导容器 ID；

解决：启动时显式指定实例 ID 环境变量：

SEEKDB_TELEMETRY_INSTANCE_ID=$(python3 -c 'import uuid;print(uuid.uuid4())') \
  nohup <seekdb-binary> --base-dir=<base-dir> --port=2881 ... &

验证：等待 10~60 秒后检查 run/telemetry.json 是否生成。

3. 故障速查表

| 现象 | 最可能原因 | 处理 | |---|---|---| | 进程秒退，无端口 | 缺 libaio / 目录不可写 / 参数越界 | 依次查 ldd、目录权限、参数 | | 卡在 server_start 4/14 | UUID 节点初始化失败（无 MAC） | 查日志关键字，必要时指定 SEEKDB_TELEMETRY_INSTANCE_ID 或升级版本 | | 端口 2881 被占用 | 旧实例没退 | pkill -x seekdb 后重启，或换 --port | | telemetry.json 不生成 | 非容器环境 + 无实例 ID | 用环境变量指定实例 ID | | 客户端连不上 | 只监听 127.0.0.1 或防火墙 | 确认 ss -lntp、--port、云安全组 | | 启动后很快 OOM | memory_limit 过大 | 降到物理内存 50%~70% |

4. 回答规范

先给结论（最可能的原因），再给排查命令，最后给修复步骤；
每条命令都要说明预期输出，方便用户判断；
不确定时明确说"需要看日志中的 X 行"，不要猜测；
不编造 seekdb 参数名或错误码；不确定的错误码让用户提供完整日志行；
涉及删除数据目录、改端口等破坏性操作前，提醒用户先备份。

5. 参考

references/common-failures.md：常见错误码与日志样例对照；
scripts/diagnose.sh：一键收集环境、进程、端口、日志摘要。