seekdb local operations

Use this skill when someone needs to run seekdb (the OceanBase AI-native database) on a single Linux host: installing the official package, starting the service, proving it answers SQL, finding the deployment telemetry ID, or explaining why an instance refuses to start or cannot report telemetry.

1. Install the official package

Always prefer the release package that matches the host distribution; the .deb builds are published per Ubuntu/Debian release and per architecture.

Resolve the release asset for the running distribution (Ubuntu 24.04 uses the ubuntu24.04_amd64.deb asset, Debian 12 uses debian12_amd64.deb).
Install it with sudo dpkg -i seekdb_<version>_<distro>_amd64.deb.
The package provides /usr/bin/seekdb, /etc/seekdb/seekdb.cnf, /usr/lib/seekdb/, /usr/libexec/seekdb/scripts/ and a seekdb.service systemd unit.

If the host cannot reach the file host that serves the release download page, the GitHub API asset endpoint usually still works: GET https://api.github.com/repos/oceanbase/seekdb/releases lists assets with their ids, and GET .../releases/assets/<id> with header Accept: application/octet-stream follows a redirect to the storage host.

2. Start and persist the instance

sudo systemctl enable --now seekdb
sudo systemctl is-active seekdb     # expect: active

Configuration lives in /etc/seekdb/seekdb.cnf (base-dir, data-dir, redo-dir, port, cpu_count). The unit runs /usr/libexec/seekdb/scripts/seekdb_systemd_start, which passes every unknown key as --parameter key=value. It only replays the full parameter set for a fresh database; for an existing one it starts with --base-dir alone.

3. Prove it answers SQL

The MySQL protocol port defaults to 2881 and root starts without a password:

mysql -h127.0.0.1 -P2881 -uroot -e 'select 1, version()'
# 5.7.25-OceanBase seekdb-v<version>

A local client is often missing; mariadb-client from the distribution is enough. Treat "port open" as insufficient: always run one real statement.

4. Read the deployment telemetry ID

The server writes run/telemetry.json under the base directory on bootstrap:

sudo cat /var/lib/seekdb/run/telemetry.json

content.id is the deployment UUID (a 36-character hyphenated string). It is derived from the stable machine id and the base directory, so it survives restarts and package upgrades of the same instance — but a different base directory produces a different id.

5. Troubleshoot a missing telemetry record

If a dashboard says the deployment id has no report:

Confirm content.id is the id that was submitted.
Confirm the host can reach https://openwebapi.oceanbase.com/api/web/oceanbase/report (TLS, not DNS).
The server posts a bootstraped event through libcurl on bootstrap. A network change between install and first start can lose that single attempt; restarting the service re-runs bootstrap and re-reports.
Re-posting the exact payload is a safe retry: curl -X POST -H 'Content-Type: application/json' --data-binary @run/telemetry.json <report url>. A {"code":200,"message":"操作成功"} response means the record was accepted.
Only after a successful re-post retry the dashboard submission; sync is not instantaneous.

6. Troubleshoot a refused start

server_start N/14 in log/seekdb.log tells how far initialization got.

log block mgr init failed with There are several files in the log directory that are not generated by OceanBase means an unexpected directory exists under the redo path (commonly a leftover meta directory from an aborted experiment). Inspect the redo directory before deleting anything.
A binary that dies before server_start 2/14 with no ERROR line usually means the process was replaced while running (Text file busy when copying) or the data directory belongs to another build.
Never point a freshly built development binary at a production data directory just to smoke-test it; use a new --base-dir with explicit --data-dir and --redo-dir.

7. Sanity checklist before claiming a deployment works

[ ] systemctl is-active seekdb prints active
[ ] systemctl is-enabled seekdb prints enabled
[ ] select 1 and select version() both return rows
[ ] run/telemetry.json exists and content.id is recorded
[ ] the report endpoint accepted the payload for that id