Cheburcheck全栈部署教程：Docker Compose一键启动完整封锁检查服务

Cheburcheck 是一款开源的俄罗斯网站封锁检查工具，用于检测域名和 IP 地址是否出现在 Roskomnadzor（RKN）封锁列表及被屏蔽的 CDN 网段中。本教程将手把手带你用 Docker Compose 一键部署完整服务，包含 Rust 后端 API、SvelteKit 前端、Nginx 网关与 MQTT 探针服务，新手也能在 15 分钟内跑起来。

一、部署前认识系统架构

Cheburcheck 由四个核心组件组成，全部通过 Docker 容器编排运行：

请求路由规则（由 nginx.conf 定义）：

• /api/v1/*、/agency/*、/whitelist/*→ 转发到 Rust 后端（website:8000）
• 其余请求 → 转发到 SvelteKit SSR 前端（frontend:3000）
• /mqtt→ WebSocket 代理到 rmqtt，供探针实时通信

工作流很简单：用户在前端输入域名 → 后端通过 Quad9 DoH 解析 DNS → 用前缀树匹配封锁列表 → 返回检查结果。封锁列表（antifilter、CDN IP 段等）会自动定时下载并缓存到database-cache/卷中。

二、Docker Compose 一键部署步骤

1. 克隆仓库

git clone https://gitcode.com/gh_mirrors/ch/cheburcheck.git cd cheburcheck

2. 准备环境变量

后端依赖 PostgreSQL 与 ClickHouse 两套数据库，需在仓库根目录创建.env文件（Docker Compose 会自动加载）：

💡 PostgreSQL 和 ClickHouse 需自行准备。启动时后端会自动执行数据库迁移（见 website/src/main.rs），无需手工建表。

3. 构建并启动

docker compose up --build -d

首次构建需要编译 Rust 后端（website/Dockerfile 使用多阶段构建）和安装前端依赖（frontend/Dockerfile 基于 pnpm），耐心等待即可。

如果不想占用默认端口，可以这样启动：

HTTP_PORT=80 docker compose up --build -d

4. 访问验证

启动完成后，浏览器打开http://localhost:8080即可看到检查页面。还可用健康检查接口确认数据库是否加载完成：

curl http://localhost:8080/api/v1/healthcheck # 返回 OK 表示封锁列表已加载；返回 LOADING DATABASES 说明仍在首次下载

/api/v1/status接口会返回当前封锁域名数、IP 段数、最后更新时间和版本号，可用来确认数据是新鲜的。

三、常用配置参数

在 docker-compose.yaml 中可通过环境变量调整运行行为：

封锁列表缓存目录默认挂载在database-cache/命名卷中（容器内路径/var/cache/cheburcheck/databases），重启容器不会丢失已下载的数据。探针节点列表与 DPI 探测参数由 website/probe-hosts.toml 只读挂载进容器，可按需增删探测主机。

四、常见问题排查

Q1：页面能打开，但健康检查一直返回LOADING DATABASES？

首次启动需要联网下载封锁列表，大列表可能需要几分钟。若持续失败，检查服务器出网是否通畅，或调低DATABASE_RETRY_INTERVAL_SECONDS加快重试。

Q2：后端容器反复重启？

通常是.env中缺少必填变量导致启动失败。执行docker compose logs website查看具体报错。

Q3：忘记修改端口冲突？

宿主机 8080 被占用时，用HTTP_PORT=9000 docker compose up --build -d换个端口即可，无需改任何配置文件。

五、延伸：让检查数据更准

部署好站点只是第一步。Cheburcheck 还支持部署分布式探测组件：

• Probe：安装在各地节点上，通过 MQTT 与后端通信，实测本地网络下的封锁情况，见 probe/README.md
• Reporter：批量扫描 Top-100000 域名并上报结果，帮助维护白名单，见 reporter/README.md

至此，你已经拥有一套可对外提供服务的完整封锁检查平台。祝你部署顺利！🚀