部署 MoleSignal

MoleSignal 以一个二进制文件和一个容器镜像交付。配置决定进程运行哪些角色：单个进程可以运行全部角色，也可以把角色拆分到多个进程。每个部署都需要两个外部服务：PostgreSQL 与对象存储。

前置条件

组件	要求
PostgreSQL	存放元数据、身份、文件目录与产品资源。PostgreSQL 是唯一受支持的元数据库。Compose 沙箱与 Kubernetes 清单使用 PostgreSQL 17。
对象存储	存放 Parquet 文件、检索索引与 Profile 数据块。使用 `s3`（AWS S3，或 RustFS、Cloudflare R2、阿里云 OSS 等兼容 S3 的服务）、`azure` 或 `gcs`。`local` 后端仅用于单节点与开发。
计算资源	容器镜像支持 x86-64 与 arm64 的 Linux（`linux/amd64`、`linux/arm64`）。沙箱需要约 2 GB 内存。
Intake 磁盘	运行 `intake` 角色的每个节点都需要一块持久化的本地卷，用于预写日志（WAL）。

内存与磁盘用量取决于接入量、活跃数据流数量以及配置中的缓存设置。请根据实际用量规划容量：首页显示原始与压缩后的接入量，进程也在 /metrics 暴露 Prometheus 指标。参见生产检查清单。

容器镜像

镜像发布为 ghcr.io/molesignal/molesignal。每个版本发布一个版本标签（例如 26.1.0.0）和一个通道标签（例如 alpha）。生产环境请固定使用版本标签。

docker pull ghcr.io/molesignal/molesignal:26.1.0.0

所有角色使用同一个镜像。运行时变量 RELEASE_CHANNEL（alpha、beta、rc 或 stable）标记部署成熟度，不会改变二进制本身。网页界面内嵌在二进制中，由 HTTP 端口提供。

部署方式

Docker Compose
二进制与 systemd
Kubernetes

仓库提供 deploy/docker/docker-compose.yaml，包含两个 profile。两者都会启动 PostgreSQL 17 与 RustFS，并运行 ghcr.io/molesignal/molesignal 的 MoleSignal 镜像。

# 所有角色在一个进程内：提供完整产品
docker compose -f deploy/docker/docker-compose.yaml --profile standalone up

# 每个角色一个容器
docker compose -f deploy/docker/docker-compose.yaml --profile multirole up

multirole profile 每个角色部署一个容器。router 在 5080 发布网页界面与 HTTP API，在 4317 发布 OTLP gRPC 接收端，参见分角色部署。standalone 服务发布 5080 与 5082，不发布 OTLP gRPC 端口 4317。要从宿主机发送 OTLP gRPC，请为该服务添加 4317:4317 映射。Compose 文件只是沙箱：它使用默认凭据、开发用 cipher key，以及 multirole profile 使用的开发用 MS_SELF_TELEMETRY_CLUSTER_TOKEN。存放真实数据前必须替换，参见生产检查清单。沙箱的存储桶是私有的。

安装发布的二进制、配置文件和 GeoIP 数据库，再把 MoleSignal 作为 systemd 服务运行。

sudo useradd --system --home-dir /var/lib/molesignal \
  --shell /usr/sbin/nologin molesignal
sudo install -Dm755 bin/molesignal /usr/local/bin/molesignal
sudo install -d -o root -g molesignal -m 0750 /etc/molesignal
sudo install -o root -g molesignal -m 0640 \
  conf/config.toml /etc/molesignal/config.toml
sudo install -Dm644 deploy/systemd/molesignal.service \
  /etc/systemd/system/molesignal.service
sudo install -Dm644 mmdb/dbip-city-lite.mmdb \
  /usr/share/molesignal/mmdb/dbip-city-lite.mmdb

在 /etc/molesignal/molesignal.env 中设置运行时通道：

RELEASE_CHANNEL=alpha

按环境修改 /etc/molesignal/config.toml 中的 PostgreSQL、对象存储与密钥配置，然后启动服务：

sudo systemctl daemon-reload
sudo systemctl enable --now molesignal
sudo systemctl status molesignal

该 unit 使用 /var/lib/molesignal 作为状态目录，并授予 CAP_NET_BIND_SERVICE，使内置 TLS 监听器可以绑定 80 与 443 端口。

deploy/k8s/ 中的清单所有角色共用一个镜像，并引用占位镜像 molesignal:dev。请在每个工作负载中把它替换为 ghcr.io/molesignal/molesignal:<version>。清单不包含 PostgreSQL 与对象存储：请在服务名 postgresql 下提供 PostgreSQL 17（或修改 ConfigMap 中的 meta_database.dsn），并提供任意兼容 S3 的对象存储（修改 ConfigMap 中的 object_store）。这些清单部署的是分角色拓扑：router 工作负载提供网页界面与 HTTP API，其余工作负载运行数据角色与后台角色。要改为运行一个承担全部角色的进程，请以 40-intake.yaml（带 WAL 持久卷的 StatefulSet）为起点，把 MS_NODE_ROLES 设为 ["standalone"]，加上 Service 的 5080 端口，并用 /api/v1/healthz 做探针。

工作负载	类型	副本数	角色
`router`	Deployment	2	`router`：网页界面、HTTP API 与 OTLP gRPC
`intake`	StatefulSet	2	`intake`，每个副本一块 20 Gi 持久卷用于 WAL
`querier`	Deployment	2	`querier`
`compactor`	Deployment	1	`compactor`，可增加副本
`alert`	Deployment	1	`alert`，可以增加副本

分角色节点之间转发链路候选与自遥测时，用共享的 MS_SELF_TELEMETRY_CLUSTER_TOKEN 做认证。链路捕获默认开启，因此每个工作负载都从 molesignal-secret 的 self_telemetry_cluster_token 读取同一个值。创建命名空间、配置和密钥，然后应用各工作负载：

kubectl apply -f 00-namespace.yaml
kubectl apply -f 10-configmap.yaml
kubectl create secret generic molesignal-secret -n molesignal \
  --from-literal=object_store_access_key="<access-key>" \
  --from-literal=object_store_secret_key="<secret-key>" \
  --from-literal=cipher_key="$(openssl rand -base64 32)" \
  --from-literal=self_telemetry_cluster_token="$(openssl rand -base64 32)" \
  --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f 30-router.yaml -f 40-intake.yaml -f 50-querier.yaml \
              -f 60-compactor.yaml -f 70-alert.yaml

工作负载通过环境变量 MS_NODE_ROLES 选择角色。通过 router 检查集群：

kubectl -n molesignal port-forward svc/router 5080:5080
curl http://127.0.0.1:5080/api/v1/healthz

网页界面内嵌在二进制中，通过 Ingress 或负载均衡器暴露 router 工作负载的 5080 端口即可。router 工作负载在 5080 提供完整 API，它的就绪探针请求 GET /api/v1/healthz。其余工作负载都在 5080 提供健康、就绪与指标监听，并以 GET /api/v1/readyz 作为就绪探针。对 intake 来说，这个监听在 WAL replay 完成后才启动，所以就绪的 Pod 可以接收写入。

角色、扩缩容与高可用参见分角色部署。

端口

端口	用途	暴露范围
`5080`	网页界面、HTTP API、`/metrics` 与健康检查端点。除 `router` 与 `standalone` 外，其他角色上只有健康、就绪与指标。	`router` 与 `standalone` 公开并位于 TLS 之后，其他角色保持私有。
`4317`	OTLP gRPC 接收端。明文 gRPC，不含 TLS。	仅在终止 TLS 的代理之后，或在可信网络内公开。
`5082`	节点间的内部 gRPC：写入转发、查询转发与扫描分片	私有，切勿暴露。
`5083`	供数据库客户端使用的 Arrow Flight SQL，默认关闭。	可选，位于 TLS 之后。
`5084`、`5085`	拨测私有节点的 Probe Agent 注册与控制	仅当 Probe Agent 运行在节点之外时需要。
`80`、`443`	`[http.tls].enabled` 为 `true` 时的内置 TLS 监听器，支持自动证书	公开。

健康检查与指标

GET /api/v1/healthz 为公开端点。服务正常时返回 200 与 {"status":"ok"}；WAL 重放期间或对象存储不可达时返回 503 并附带 reason。容器与负载均衡器探针使用它。
GET /metrics 为公开端点，返回 Prometheus 指标。请在代理或网络层限制访问。
在 standalone 或 router 节点上，GET /api/v1/readyz 与 GET /api/v1/version 需要 Bearer Token。version 返回版本、commit、构建 id、发布通道与版本类型。
分角色集群中不提供完整 API 的节点，在同一端口上不经认证地响应 GET /api/v1/healthz、GET /api/v1/readyz 与 GET /metrics。

指标以及服务自身的内置遥测参见自身可观测性。

快速上手

数据

观察

查询与关联

可靠性

AI 运维

协作

管理

部署与运维

最佳实践

资源

前置条件

容器镜像

部署方式

端口

健康检查与指标

​前置条件

​容器镜像

​部署方式

​端口

​健康检查与指标

前置条件

容器镜像

部署方式

端口

健康检查与指标