seekdb 部署与排障（WSL2 / Linux）

本技能把 seekdb 单机版的「安装 → 启动 → 连接 → 遥测文件 → 故障定位」固化为一套可复用流程，重点覆盖 WSL2 下三个高频坑：systemd 未作为 1 号进程、被误判为容器导致遥测 UUID 生成失败、配置文件缺失后盲目重装。

何时使用

要在 Ubuntu/WSL2 上装一个 seekdb 实例并跑通 SQL。
systemctl status seekdb 报 System has not been booted with systemd as init system (PID 1)。
服务是 active (running)，但 /var/lib/seekdb/run/telemetry.json 不存在。
需要从 telemetry.json 取出 content.id（UUID）用于竞赛/平台登记。
需要判断该重启、该重建实例，还是只是客户端没装。

不要在本技能里做：多节点集群、OBProxy、租户资源规格规划。

目录约定（先确认，再动手）

| 项目 | 默认值 | | --- | --- | | 服务名 | seekdb.service | | 程序 | /usr/bin/seekdb | | 配置 | /etc/seekdb/seekdb.cnf | | 数据根 | /var/lib/seekdb | | 运行目录 | /var/lib/seekdb/run（seekdb.pid、sql.sock、telemetry.json） | | 端口 | 2881 |

不同安装包可能改写这些路径，先读实际值再操作：

systemctl cat seekdb          # 看 ExecStart / Environment / User
systemctl show seekdb -p Environment -p ExecStart
sudo ls -la /etc/seekdb /var/lib/seekdb

首次部署（标准路径）

# 1) 安装（官方脚本，需 sudo）
curl -fsSL https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/download-center/opensource/seekdb/seekdb_install.sh | sudo bash

# 2) 启动并设自启动
sudo systemctl enable --now seekdb

# 3) 三项验收
systemctl --no-pager --full status seekdb   # 期望 active (running) 且含 "seekdb is ready and running"
ss -ltn | grep 2881                          # 期望监听 127.0.0.1:2881
mysql -h127.0.0.1 -uroot -P2881 -e 'show databases;'

mysql 不存在时：sudo apt update && sudo apt install -y mysql-client。

故障 → 处理（按现象查表）

| 现象 | 根因 | 处理 | | --- | --- | --- | | System has not been booted with systemd、Failed to connect to bus: Host is down | WSL 未启用 systemd | /etc/wsl.conf 写 [boot]\nsystemd=true，然后 PowerShell 执行 wsl --shutdown 再进入 | | Configuration file /etc/seekdb/seekdb.cnf not found | 配置被删或安装不完整 | 先 systemctl cat seekdb + journalctl -u seekdb -n 100 确认期望路径，再按模板恢复；不要无条件覆盖现有 cnf | | 服务 running，但 run/telemetry.json 缺失 | WSL 有 /run/systemd/container，被识别为容器；主机名非 12/64 位十六进制 → UUID 生成失败 | 见下节「遥测 ID」 | | Command 'mysql' not found | 只装了服务端 | apt install -y mysql-client | | 端口未监听 | 启动即失败或配置端口不同 | sudo journalctl -u seekdb -n 200 --no-pager，核对 cnf 中 port |

遥测 ID（WSL2 高发问题）

判断链：/.dockerenv、/run/.containerenv、/run/systemd/container、container 环境变量、 KUBERNETES_SERVICE_HOST 任一命中即视为容器；没有容器运行时 ID 时改用主机名派生作用域，主机名必须是 12 位或 64 位十六进制文本，否则 UUID 生成失败、文件不写。

关键约束：遥测只在首次 bootstrap 执行。旧实例已经 bootstrap 过，事后加环境变量再重启不会补写文件，必须让一个全新数据目录首次启动。

正确顺序（缺一不可）：

生成并记录固定 UUID：cat /proc/sys/kernel/random/uuid
在启动之前把 UUID 注入服务环境： /etc/systemd/system/seekdb.service.d/10-telemetry.conf → Environment=SEEKDB_TELEMETRY_INSTANCE_ID=<uuid>
systemctl daemon-reload 并确认 systemctl show seekdb -p Environment 里能看到该变量
停止服务、把旧 /var/lib/seekdb 改名备份（不要 rm -rf）、重建 run 目录
systemctl reset-failed seekdb && systemctl start seekdb，等文件出现
读取：sudo python3 -c 'import json;print(json.load(open("/var/lib/seekdb/run/telemetry.json"))["content"]["id"])'

完整命令见 references/telemetry.md；故障细节与日志关键字见 references/troubleshooting.md。

一键体检

bash scripts/diagnose.sh

只读检查：systemd 是否就位、服务状态、端口、配置、遥测文件、日志关键字，并给出下一步建议。

硬性约束

不要手工伪造 telemetry.json；要的是本实例真实生成的值。
不要用 rm -rf /var/lib/seekdb /etc/seekdb、wsl --unregister <发行版>、递归删 WSL 安装目录来「重装」。
重建实例前先备份数据目录，并把备份路径打印出来记下。
任何破坏性命令执行前，先确认目标路径与实例名，服务已停止，数据已备份。

使用示例

「我 WSL2 里的 seekdb 起来了，但 /var/lib/seekdb/run/telemetry.json 一直不生成，帮我查。」 → 先跑 scripts/diagnose.sh 确认 systemd 是否接管、日志是否出现 Container runtime ID is unavailable；确认后按「遥测 ID」六步重建实例并读取 content.id。

作品验证