晚安の静谧小屋

2.1 服务组成#

Private Location Probe 不属于上述核心 Compose 服务，需要另外部署。

2.2 数据流向#

1
                  用户浏览器
2
                      |
3
                      v
4
              Nginx 反向代理
5
                      |
6
            +---------+---------+
7
            |                   |
8
            v                   v
9
       Dashboard             Status Page
10
        :3002                   :3003
11
            |
12
            v
13
         API Server
14
          :3001
15
            |
16
       +----+----+
17
       |         |
18
       v         v
19
    Workflows   libSQL
20
     :3000      :8080
21
       ^
22
       |
23
       | 状态更新
24
       |
25
Private Location Ingest
26
       :8081
27
       ^
28
       |
29
       | HTTP 数据上报
30
       |
31
Private Location Probe
32
       |
33
       v
34
  被监控的目标服务
35

36
Probe / Ingest
37
       |
38
       v
39
 Tinybird Local
40
    :7181
41
       |
42
       v
43
  ClickHouse 分析数据
44
       |
45
       v
46
 Dashboard 图表统计

2.3 推荐域名规划#

以下使用示例域名，实际部署时替换成自己的域名。

8081 是探针数据接收入口，不应误配置成 API Server 的 3001 端口。

7181、8080、5001 等内部服务不需要公开到互联网。

3.1 基础环境要求#

建议配置：

实际资源消耗取决于监控数量、数据保留时间及查询频率。

3.2 检查 Docker#

1
docker --version
2
docker compose version
3
git --version

确保能够正常执行。

3.3 安装 Python 3.12 环境#

Tinybird Classic CLI 的官方安装文档列出的 Python 支持版本为 3.8～3.12。

建议使用独立虚拟环境，避免污染系统 Python。

1
apt update
2

3
apt install -y \
4
  python3 \
5
  python3-venv \
6
  python3-pip \
7
  git \
8
  curl \
9
  ca-certificates

创建虚拟环境：

1
python3 -m venv /opt/tinybird-venv
2

3
source /opt/tinybird-venv/bin/activate

安装 CLI：

1
pip install --upgrade pip
2
pip install --upgrade tinybird

检查：

1
tb --version
2
tb --help

后续部署 Tinybird 时，需要在这个虚拟环境中执行 tb 命令。

注意：OpenStatus 官方部署流程使用 tb --local，不要将其替换成普通的 Tinybird Cloud 登录部署流程。

5.1 必须配置的变量#

官方文档要求设置以下四项：

生成随机密钥：

1
openssl rand -base64 48

再生成一个独立的 CRON_SECRET：

1
openssl rand -hex 32

将对应值填写到配置文件：

1
AUTH_SECRET=替换为生成的随机密钥
2

3
RESEND_API_KEY=替换为自己的Resend_API_Key
4

5
SELF_HOST=true
6

7
NEXT_PUBLIC_URL=https://status.example.com
8

9
CRON_SECRET=替换为生成的随机字符串

其中：

• AUTH_SECRET 不要使用简单字符串。
• RESEND_API_KEY 用于邮件发送，Magic Link 登录依赖邮件服务。
• NEXT_PUBLIC_URL 应填写实际 Dashboard 地址。
• CRON_SECRET 后面还会用于 Ingest 和 Workflows 之间的身份验证。

5.2 配置本地 Tinybird#

这是整个部署过程中非常重要的配置。

在 .env.docker 中添加：

1
TINYBIRD_URL=http://tinybird-local:7181

这样 OpenStatus 的应用服务就会访问 Docker 网络内的 Tinybird，而不是默认查询 Tinybird Cloud。

如果没有正确设置，Dashboard 中的统计图表可能出现：

1
The pipe 'endpoint__http_metrics_1d__v1' does not exist

5.3 检查配置#

1
grep -E '^(AUTH_SECRET|RESEND_API_KEY|SELF_HOST|NEXT_PUBLIC_URL|CRON_SECRET|TINYBIRD_URL)=' .env.docker

不要将包含真实密钥的 .env.docker 上传到 GitHub。

建议：

1
chmod 600 .env.docker

6.1 使用 Docker Compose 构建#

进入项目目录：

1
cd /home/openstatus

开启 BuildKit：

1
export DOCKER_BUILDKIT=1

启动服务：

1
docker compose up -d

首次启动需要拉取镜像、构建服务以及执行数据库迁移，等待一段时间即可。

官方 Compose 会自动执行 db-migrate，其他应用服务会等待数据库迁移完成。

6.2 查看容器状态#

1
docker compose ps

查看全部容器：

1
docker ps

查看启动日志：

1
docker compose logs -f

如果某个服务没有正常启动，可以单独查看：

1
docker compose logs --tail=100 dashboard
2
docker compose logs --tail=100 server
3
docker compose logs --tail=100 workflows
4
docker compose logs --tail=100 private-location

6.3 使用预构建镜像（可选）#

如果不想在本机编译项目，可以使用官方 GHCR 预构建镜像：

1
docker compose -f docker-compose.github-packages.yaml up -d

建议二选一，不要在没有确认 Compose 配置差异的情况下混合使用两种启动方式。

7.1 进入 Tinybird 项目目录#

1
source /opt/tinybird-venv/bin/activate
2

3
cd /home/openstatus/packages/tinybird

确认项目文件：

1
ls -lah

这里包含 OpenStatus 使用的 Tinybird Datasources、Pipes 和 Endpoints。

7.2 部署 Tinybird 数据结构#

确认 Docker 中的 tinybird-local 已经启动：

1
docker ps | grep tinybird

修改默认数据结构

1
python3 <<'PY'
2
from pathlib import Path
3
import re
4

5
directory = Path("/home/openstatus/packages/tinybird/datasources")
6

7
changed = []
8

9
for file in directory.glob("*.datasource"):
10
    content = file.read_text()
11
    updated = content
12

13
    def replace_ttl(match):
14
        days = int(match.group(1))
15

16
        if days <= 30:
17
            return 'ENGINE_TTL "time + toIntervalMonth(1)"'
18

19
        return match.group(0)
20

21
    updated = re.sub(
22
        r'ENGINE_TTL "time \+ toIntervalDay\((\d+)\)"',
23
        replace_ttl,
24
        updated
25
    )
26

27
    if updated != content:
28
        file.write_text(updated)
29
        changed.append(file.name)
30

31
print(f"修改完成，共修改 {len(changed)} 个文件：")
32

33
for name in changed:
34
    print(f"  - {name}")
35
PY

1
cd /home/openstatus/packages/tinybird
2

3
for f in datasources/*.datasource; do
4
    if grep -qE 'toIntervalDay\((45|46|47)\)' "$f"; then
5
        echo "========== $f =========="
6
        grep -nE 'ENGINE_PARTITION_KEY|ENGINE_TTL' "$f"
7
    fi
8
done

执行本地部署：

1
tb --local deploy

这个命令会将 OpenStatus 所需的数据结构部署到本地 Tinybird。

部署内容包括：

• Datasources：数据源。
• Pipes：数据处理管道。
• Endpoints：数据查询接口。

等待部署完成。

7.3 检查部署状态#

执行：

1
tb --local deployment ls

正常情况下可以看到：

1
-------------------------------------
2
| ID | Status | Created at          |
3
-------------------------------------
4
|  1 | Live   | 2026-10-30 ...      |
5
-------------------------------------

这里需要特别注意：

Status 必须为：

1
Live

如果显示：

1
Staging

则需要执行：

1
tb --local deployment promote

再次检查：

1
tb --local deployment ls

确保部署状态已经变成 Live。

注意：Staging 状态下，Pipe 虽然可能已经存在，但实际查询仍可能返回 404。

7.4 获取 Tinybird Token#

执行：

1
tb --local info

在输出中找到：

1
Tinybird Local

复制其中的：

1
token

也可以通过命令直接提取：

1
tb --local info | grep '^token:' | awk '{print $2}'

保存这个 Token，后面需要使用。

特别注意：不要使用下面的方式获取 Token：

1
curl http://localhost:7181/tokens

官方文档明确指出，这个接口返回的 Token 可能属于另一个 Workspace。

即使 Ingest 看起来已经成功，Dashboard 查询也可能因为 Pipe 不存在而失败。

必须使用：

1
tb --local info

7.5 配置 Tinybird Token#

回到项目根目录：

1
cd /home/openstatus

编辑：

1
nano .env.docker

添加以下两个配置：

1
# Dashboard、Status Page、Server、Workflows 使用
2
TINY_BIRD_API_KEY=替换为刚刚获取的Token
3

4
# Private Location Ingest 使用
5
TINYBIRD_TOKEN=替换为刚刚获取的Token

两个变量必须使用完全相同的 Token。

这里是最容易出错的地方：

只配置其中一个是不够的。

如果没有配置 TINYBIRD_TOKEN，Ingest 服务可能返回：

1
unexpected status code: 403

7.6 重启服务#

保存配置后执行：

1
docker compose up -d

等待容器重新加载环境变量。

检查：

1
docker compose ps

至此，Tinybird Analytics 的基础配置完成。

8.1 获取 Token#

在项目目录下执行：

1
cd /home/openstatus/packages/tinybird
2

3
TOKEN=$(tb --local info | grep '^token:' | awk '{print $2}')

检查：

1
echo "$TOKEN"

8.2 测试 HTTP Metrics Pipe#

执行：

1
curl -s -o /dev/null -w '%{http_code}\n' \
2
  -H "Authorization: Bearer $TOKEN" \
3
  "http://localhost:7181/v0/pipes/endpoint__http_metrics_1d__v1.json?monitorId=1"

预期结果：

1
200

返回状态说明：

注意：该测试只验证 Pipe 的可查询性，并不代表已经存在实际监控数据。

8.3 检查 Ingest 服务#

1
docker compose logs -f private-location

后面部署探针并产生监控数据后，应关注日志中的：

1
tinybird.success=true

如果出现：

1
tinybird.success=false

优先检查：

1. TINYBIRD_TOKEN 是否正确。
2. TINY_BIRD_API_KEY 和 TINYBIRD_TOKEN 是否一致。
3. Tinybird 是否已经完成 Live 部署。

9.1 访问 Dashboard#

默认地址：

1
http://服务器IP:3002

公开状态页：

1
http://服务器IP:3003

如果使用了 Nginx 反向代理，则通过配置好的 HTTPS 域名访问。

9.2 注册账号#

首次访问 Dashboard：

1. 创建账号。
2. 通过邮件完成 Magic Link 登录。
3. 创建 Workspace。
4. 进入工作空间管理页面。

邮件登录依赖前面配置的 Resend API Key。

9.3 工作空间功能限制#

官方指南指出，自托管 Workspace 的功能限制需要根据需求进行调整。

默认限制并不意味着所有功能无限制开放。

如果需要更多监控数量、区域、状态页组件、数据保留时间等，需要检查工作空间的 limits 配置。

可以先查询 Workspace：

1
curl -sS -X POST http://localhost:8080/ \
2
  -H "Content-Type: application/json" \
3
  -d '{"statements":["SELECT id, name FROM workspace"]}'

根据实际 Workspace ID 决定是否调整功能限制。

官方文档提供了完整的 limits Schema 配置示例：

https://www.openstatus.dev/docs/guides/self-hosting-openstatus#part-3-application-configuration

建议先使用默认配置完成部署，再根据实际需求调整，不建议直接修改套餐或绕过付费授权机制。

10.1 理解两个不同的组件#

OpenStatus 有两个名称相似的 Private Location 组件：

其中：

• Ingest Server 负责接收探针数据。
• Probe 负责实际检测目标服务。

官方 Compose 已经包含 Ingest Server，因此这里只需要额外部署 Probe。

10.2 创建 Private Location#

进入 OpenStatus Dashboard：

1
Settings
2
  └── Private Locations
3
        └── Create Private Location

创建一个新的 Private Location。

例如：

1
名称：VPS-HK

创建成功后，复制系统生成的 Key。

这个 Key 后面需要配置到探针容器中。

10.3 部署 Probe#

在需要执行监控的服务器上执行：

1
docker run -d \
2
  --name openstatus-probe \
3
  --restart unless-stopped \
4
  -e OPENSTATUS_KEY=替换为PrivateLocation生成的Key \
5
  -e OPENSTATUS_INGEST_URL=http://你的OpenStatus服务器IP:8081 \
6
  ghcr.io/openstatushq/private-location:latest

注意：

OPENSTATUS_INGEST_URL 必须指向 Ingest Server 的 8081 端口，而不是 API Server 的 3001 端口。

如果 Probe 和 OpenStatus 位于同一个 Docker 网络中，可以使用：

1
http://private-location:8080

10.4 查看探针运行状态#

1
docker logs -f openstatus-probe

正常情况下会出现类似日志：

1
Launching openstatus private location checker
2

3
Starting job for monitor 1 (https://google.com)
4

5
Monitor check for 1 (https://google.com)
6
ingested with status "success" (code 200)

如果出现上述日志，说明探针已经开始执行监控任务。

10.5 创建第一个监控任务#

在 Dashboard 中：

1. 进入 Monitors。
2. 创建新的监控任务。
3. 填写需要检测的目标 URL。
4. 选择刚刚创建的 Private Location。
5. 保存监控任务。

Probe 默认每 10 分钟刷新一次监控任务列表。

因此，创建或修改监控任务后，可能需要等待最多 10 分钟才能看到变化。

11.1 定时任务的作用#

private-location-health 主要负责：

• 检查 Private Location 是否定期上报。
• 判断探针是否离线。
• 将异常状态从 active 更新为 error。
• 在探针恢复后将状态从 error 更新为 active。
• 向 Workspace 成员发送状态变化通知。
• 记录状态变化审计日志。

官方建议每 5 分钟执行一次。

11.2 创建 Docker Cron 服务#

进入 OpenStatus 项目目录：

1
cd /home/openstatus

创建目录：

1
mkdir -p cron

11.3 创建 Dockerfile#

1
nano cron/Dockerfile

填写：

1
FROM alpine:latest
2

3
RUN apk add --no-cache curl
4

5
COPY crontab /etc/crontabs/root
6

7
CMD ["crond", "-f", "-l", "2"]

11.4 创建 Crontab#

1
nano cron/crontab

填写：

1
*/5 * * * * curl -sS -H "Authorization: ${CRON_SECRET}" http://workflows:3000/cron/private-location-health

这里使用 Docker 内部服务名称：

1
workflows:3000

不需要通过公网域名访问。

11.5 修改 Docker Compose#

打开：

1
nano docker-compose.yaml

在 services 下添加：

1
cron:
2
  build: ./cron
3
  container_name: openstatus-cron
4
  env_file:
5
    - .env.docker
6
  networks:
7
    - openstatus
8
  restart: unless-stopped

注意：

这里的 openstatus 网络名称需要与你当前 Compose 文件实际定义的网络名称一致。

如果你的 Compose 网络名称不同，请使用实际网络名称。

11.6 启动 Cron#

执行：

1
docker compose up -d

检查：

1
docker compose ps cron

查看日志：

1
docker compose logs -f cron

检查 Workflows 日志：

1
docker compose logs workflows | grep "private-location-health"

正常情况下，每 5 分钟可以看到类似：

1
private-location-health complete:
2
checked=2 toError=0 toActive=0

至此，定时健康检查配置完成。