快速开始

本指南启动本地 MoleSignal 沙箱，发送一条日志事件，并通过网页界面和查询 API 找到这条事件。沙箱仅用于评估。

前置条件

Docker 与 Docker Compose v2。
约 2 GB 空闲内存。
本机空闲端口：5080（网页界面与 API）、5082、5432（PostgreSQL）、9000 与 9001（RustFS）。

启动沙箱

克隆仓库并启动

git clone https://github.com/molesignal/molesignal
cd molesignal
docker compose -f deploy/docker/docker-compose.yaml --profile standalone up

首次启动需要下载或构建镜像，可能耗时数分钟。沙箱包含用于存放元数据的 PostgreSQL 17、兼容 S3 的对象存储 RustFS，以及一个运行全部角色并提供网页界面的 MoleSignal 进程。确认服务已就绪：

curl http://localhost:5080/api/v1/healthz

服务健康时返回 {"status":"ok"}。

登录网页界面

打开 http://localhost:5080，使用以下账号登录：

邮箱： [email protected]
密码： admin

沙箱配置只会在首次启动时创建这个 root 账号。用于本地评估之外的任何场景前，必须替换该账号，参见生产检查清单。

RustFS 控制台位于 http://localhost:9001，账号为 rustfsadmin / rustfsadmin。这些沙箱凭据并不安全。

获取访问 Token

API 使用 Bearer Token。通过 API 登录，获得登录 Token（默认有效期 24 小时）和组织 id：

RESP=$(curl -s -X POST http://localhost:5080/api/v1/auth/signin \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]","password":"admin"}')

export MS_JWT=$(echo "$RESP" | jq -r .token)
export MS_ORG=$(echo "$RESP" | jq -r .org_id)

没有 jq 时，从响应中复制 token 与 org_id 并手工导出。

运行时间超过登录 Token 有效期的发送端，请使用 API token 或接入 Token，参见数据源。

发送一条日志事件

原生 HTTP JSON 接入接收一个记录数组。_timestamp 是自 Unix 纪元起的微秒数。数据流 app 会在首次写入时创建。

curl -X POST http://localhost:5080/api/v1/intake/logs/app \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "[{\"_timestamp\":$(date +%s)000000,\"level\":\"error\",\"msg\":\"db pool exhausted\",\"trace_id\":\"abc123\"}]"

响应会给出已接收的记录数：

{"accepted":1,"rejected":0,"errors":[]}

在网页界面中找到这条事件

打开日志。
在数据流选择器中选择 app。
时间范围保持 近 1 小时，选择查询。

结果表会显示这条事件。选择该行即可查看其原始字段。

用 API 查询这条事件

通过查询 API 执行同样的查找。始终传入有界的微秒 time_range；时间范围过宽时，规划器会把查询转成异步搜索任务。

NOW=$(date +%s)000000

curl -X POST http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
       \"statement\":\"SELECT level, msg, trace_id FROM app WHERE trace_id = 'abc123'\",
       \"time_range\":{\"start\":$((NOW - 3600000000)),\"end\":$((NOW + 60000000))},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"

响应包含 columns、rows、scanned_rows 与 took_ms：

{"columns":["level","msg","trace_id"],"rows":[["error","db pool exhausted","abc123"]],"scanned_rows":1,"took_ms":120}

加载示例数据

没有数据的工作区会显示空页面。加载一组小型的关联示例数据（日志、指标与链路共享 trace_id），即可体验跨信号调查：

curl -X POST http://localhost:5080/api/v1/onboarding/sample-data \
  -H "authorization: Bearer $MS_JWT"

该请求会创建数据流 sample_app_logs、sample_app_metrics 与 sample_app_traces。网页界面中也可以执行同样的操作：在首页的设置横幅中选择 完成设置，再选择 加载示例数据 旁的加载。所有设置步骤完成后，横幅会消失。

发送 OpenTelemetry 数据

任何 OpenTelemetry SDK 或 Collector 都可以通过 HTTP 发送 OTLP 数据。把导出端指向 /api 基础路径，导出端会自动追加 /v1/logs、/v1/metrics 与 /v1/traces：

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5080/api
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $MS_JWT"
export OTEL_SERVICE_NAME=checkout

除非用 stream-name 请求头指定其他数据流，遥测会写入各信号类型下名为 default 的数据流。Collector、Vector、Fluent Bit、Prometheus 与 SDK 的配置参见数据源和集成指南。

停止沙箱

# 停止容器并保留数据
docker compose -f deploy/docker/docker-compose.yaml --profile standalone down

# 停止容器并删除全部沙箱数据
docker compose -f deploy/docker/docker-compose.yaml --profile standalone down -v

故障排查

现象	原因与处理
`healthz` 返回 `503` 与 `"status":"degraded"`	某个子系统不健康，例如对象存储探测失败。查看 `reason` 字段，并检查 `rustfs` 容器。
登录返回 `401`	root 账号只在首次启动时创建，早先运行遗留的数据库卷会保留旧密码。执行 `down -v` 重置沙箱。
查询返回 `202` 与 `job_id`	时间范围过宽（默认配置下约 13.9 小时或更长），规划器启动了异步搜索任务。缩小范围，发送 `Prefer: respond-sync`，或轮询 `GET /api/v1/query/jobs/{id}`，参见查询。
查询返回 `422 missing field org_id` 或 `400 query.stream hint is required`	同时传入 `org_id` 与 `stream` 对象。
端口已被占用	停止占用端口的其他进程，或修改 `deploy/docker/docker-compose.yaml` 中发布的端口。
宿主机无法访问 `4317` 上的 OTLP gRPC	沙箱 Compose 文件没有发布 `4317`。在 `molesignal` 服务中添加 `4317:4317` 端口映射。

下一步

接入自己的数据

使用数据源页面、接入 Token 和兼容协议。

集成指南

配置 OpenTelemetry Collector、Vector、Fluent Bit、Filebeat 与 Prometheus。

核心概念

了解信号、数据流、工作区与权限。

正式部署

从沙箱迁移到生产部署。

快速上手

数据

观察

查询与关联

可靠性

AI 运维

协作

管理

部署与运维

最佳实践

资源

前置条件

启动沙箱

加载示例数据

发送 OpenTelemetry 数据

停止沙箱

故障排查

下一步

接入自己的数据

集成指南

核心概念

正式部署

​前置条件

​启动沙箱

​加载示例数据

​发送 OpenTelemetry 数据

​停止沙箱

​故障排查

​下一步

接入自己的数据

集成指南

核心概念

正式部署

前置条件

启动沙箱

加载示例数据

发送 OpenTelemetry 数据

停止沙箱

故障排查

下一步