Skip to content

getting-started.md

Latest commit

 

History

History
174 lines (122 loc) · 4.89 KB

getting-started.md

File metadata and controls

174 lines (122 loc) · 4.89 KB
Raw

layout: default title: "开始使用" description: "从 Docker 启动、首次安装到本地和远程访问的最短路径。" permalink: /getting-started/

1. 启动 SonnetDB

从仓库根目录使用 Compose 启动发布镜像：

docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps
curl --fail http://127.0.0.1:5080/healthz/live

sonnetdb 服务启动后，健康状态会从 starting 变为 healthy；若尚未通过检查，可稍后重试，或运行 docker compose -f docker-compose.yml logs --tail=100 sonnetdb 查看日志。这个存活检查只确认进程与 HTTP 管线响应，不代表已完成初始化或完整依赖就绪。

如果需要从仓库根目录构建镜像：

docker build -f src/SonnetDB/Dockerfile -t sonnetdb .

也可以直接运行构建后的容器：

docker run --rm -p 127.0.0.1:5080:5080 -v ./sonnetdb-data:/data sonnetdb

默认行为：

  • 容器内监听 http://0.0.0.0:5080
  • 主机映射仅接受本机连接，首次安装向导在此范围内完成
  • 数据根目录为 /data
  • 帮助文档会随镜像一起发布到 /help

如果直接从源码运行服务端，也会默认监听 5080，并使用 ./sonnetdb-data 作为数据根目录。

远程部署请先通过 SONNETDB_USER / SONNETDB_PASSWORD 引导并验证初始化，再显式开放所需接口，步骤见 Docker 首次初始化与远程部署。

2. 打开管理入口

浏览器访问：

http://127.0.0.1:5080/admin/

帮助文档入口：

http://127.0.0.1:5080/help/

3. 完成首次安装

当 <DataRoot>/.system 为空时，/admin/ 不会直接落到登录页，而是进入首次安装向导。

向导会预填：

  • 基于主机名与本机硬件指纹生成的稳定服务器 ID
  • 默认组织名称
  • 管理员用户名 admin
  • 自动生成的初始静态 Bearer Token

仅管理员密码必须手动输入；其余默认值均可在提交前修改。硬件原始标识只参与服务器 ID 的 SHA-256 短哈希计算，不会通过 API 或日志暴露。

初始化成功后，服务端会在 <DataRoot>/.system/ 下生成：

  • installation.json
  • users.json
  • grants.json

其中 Bearer Token 的元数据与哈希保存在 users.json 中，不会以明文再次落盘。

4. 创建数据库

完成首次安装并登录后，可以在管理界面中创建数据库，也可以直接调用 HTTP API：

curl -X POST "http://127.0.0.1:5080/v1/db" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"metrics\"}"

5. 写入第一批数据

通过 SQL：

curl -X POST "http://127.0.0.1:5080/v1/db/metrics/sql" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d "{\"sql\":\"CREATE MEASUREMENT cpu (host TAG, usage FIELD FLOAT)\"}"
curl -X POST "http://127.0.0.1:5080/v1/db/metrics/sql" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d "{\"sql\":\"INSERT INTO cpu (time, host, usage) VALUES (1713676800000, 'server-01', 0.71)\"}"

6. 验证查询

curl -X POST "http://127.0.0.1:5080/v1/db/metrics/sql" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d "{\"sql\":\"SELECT time, host, usage FROM cpu WHERE host = 'server-01'\"}"

服务端会以 ndjson 方式返回 meta、rows 和结束标记。

7. 本地嵌入式访问

如果你不需要 HTTP 服务端，可以直接在进程内打开数据库目录：

using SonnetDB.Engine;
using SonnetDB.Sql.Execution;

using var db = Tsdb.Open(new TsdbOptions
{
    RootDirectory = "./demo-data",
});

SqlExecutor.Execute(db, "CREATE MEASUREMENT cpu (host TAG, usage FIELD FLOAT)");

更完整的进程内示例见 [嵌入式与 in-proc API]({{ site.docs_baseurl | default: '/help' }}/embedded-api/)。

8. ADO.NET 与 CLI

本地 ADO.NET 连接：

Data Source=./demo-data

远程 ADO.NET 连接：

Data Source=sonnetdb+http://127.0.0.1:5080/metrics;Token=<your-token>

CLI 示例：

sndb sql --connection "Data Source=./demo-data" --command "SELECT count(*) FROM cpu"

详细用法分别见：

  • [ADO.NET 参考]({{ site.docs_baseurl | default: '/help' }}/ado-net/)
  • [CLI 参考]({{ site.docs_baseurl | default: '/help' }}/cli-reference/)

常用端点

地址 说明
/admin/ 产品首页、首次安装、登录和后台入口
/help/ 帮助文档站点
/healthz 健康检查
/metrics Prometheus 指标
/v1/setup/status 查询是否需要首次安装
/v1/setup/initialize 完成首次安装
/v1/db 数据库列表、创建、删除
/v1/db/{db}/sql 数据面 SQL 入口
/v1/sql 控制面 SQL 入口，仅 admin
/v1/events SSE 事件流