pixel-telo-mast-selfhost

README

Pixel Telo Mast Self-host

自己在家里或小服务器上跑的来电标记查询服务，给 Pixel Telo 用。

手机来电时，App 可以问这台服务：这个号码有没有被网页来源标记成骚扰。查询只发给你自己启用的来源（目前是搜狗、360），不会把号码转到 Pixel Telo 官方实时查询。

先看哪份说明

你想做什么	看哪里
不想懂原理，先在家里跑起来	下面的「快速开始」
域名证书、反代、限流、备份升级	DEPLOY.md

快速开始使用镜像标签 latest。需要钉死版本时，请到 Releases 选完整版本号。

你需要准备什么

• 一台几乎一直开着的电脑：家里的 Linux / Windows，或已安装 Docker 的 NAS。
• 手机和这台电脑在同一局域网（先别急着弄公网域名）。
• 电脑的局域网 IP，例如 192.168.1.8。Windows 可在终端运行 ipconfig，macOS / Linux 可运行 ipconfig getifaddr en0 或 hostname -I。
• 启用搜狗或 360 前，请自己确认其网页服务条款；公共发行版不会替你默认打开来源。

快速开始使用自动生成的自签名证书。手机第一次连接时可能会提示证书不受系统信任，需要按 App 的配对方式核对证书指纹。这是预期行为，不是装错了。

快速开始：Docker Compose（推荐）

适合已安装 Docker 的 Linux、macOS、Windows（Docker Desktop）或 NAS。把 192.168.1.8 换成这台电脑的局域网 IP。

Linux / macOS：

git clone https://github.com/Pixel-Tailor-CN/pixel-telo-mast-selfhost.git
cd pixel-telo-mast-selfhost
export MAST_PUBLIC_URL=https://192.168.1.8:8443
docker compose up -d

Windows PowerShell：

git clone https://github.com/Pixel-Tailor-CN/pixel-telo-mast-selfhost.git
cd pixel-telo-mast-selfhost
$env:MAST_PUBLIC_URL="https://192.168.1.8:8443"
docker compose up -d

镜像使用 latest。init 默认就是自动 HTTPS，只要带上手机能访问的 MAST_PUBLIC_URL，不用再改配置文件。

docker compose logs --tail 50

日志里会有 5 分钟有效的配对页面地址，用浏览器打开即可复制或扫码。

快速开始：Docker 命令

没有 compose 时也可以直接跑。容器里看到的网卡地址通常不是手机能用的，所以这里仍要填宿主机局域网 IP。

export MAST_IMAGE=mystery0/pixel-telo-mast-selfhost:latest
# 若 Docker Hub 拉不到，可改用：
# export MAST_IMAGE=ghcr.io/pixel-tailor-cn/pixel-telo-mast-selfhost:latest
export MAST_DATA="$HOME/mast-selfhost"
mkdir -p "$MAST_DATA"

docker run --rm \
  -v "${MAST_DATA}:/app/data" \
  "${MAST_IMAGE}" \
  init --dir /app/data \
  --listen 0.0.0.0:8443 \
  --public-url https://192.168.1.8:8443 \
  --provider-id sogou \
  --sync-on-start=false

docker run -d \
  --name mast-selfhost \
  --restart unless-stopped \
  -p 8443:8443 \
  -v "${MAST_DATA}:/app/data" \
  "${MAST_IMAGE}" \
  serve --dir /app/data

看是否起来：

docker logs --tail 50 mast-selfhost

日志里应出现 self-host server started。浏览器打开 https://192.168.1.8:8443/ ，可能会提示证书不受信任，继续访问后应看到「运行正常」。

健康检查（自签名证书需要 -k）：

curl -k --fail --show-error https://192.168.1.8:8443/api/health

应返回 {"status":"ok"}。

服务启动成功后，终端会打印一个限时 5 分钟的配对页面地址（用配置里的 public_url）。用电脑或手机浏览器打开，页面上有复制按钮和二维码，把内容填进 Pixel Telo。不要把页面或密钥发到群里。

超过 5 分钟后页面失效，可再执行 pairing 查看文字（不会刷新网页链接，需在有效期内打开启动时打印的地址，或重启 serve）：

docker run --rm \
  -v "${MAST_DATA}:/app/data" \
  "${MAST_IMAGE}" \
  pairing --dir /app/data

Windows Docker Desktop 把上面的 "$HOME/mast-selfhost" 换成例如 D:\mast-selfhost 即可。

快速开始：Windows 安装包

1. 打开 Releases，下载 mast-selfhost-windows-amd64.exe。
2. 新建文件夹，例如 D:\mast-selfhost，把 exe 放进去。
3. 在该文件夹打开终端：

mast-selfhost-windows-amd64.exe init --dir data --listen 0.0.0.0:8443 --provider-id sogou --sync-on-start=false

1. 没加 --public-url 时，命令会列出网卡地址让你选。选和手机同一 Wi-Fi 的那条，不要选 127.0.0.1。
2. 启动：

mast-selfhost-windows-amd64.exe serve --dir data

1. 保持这个窗口开着。启动成功后会打印配对页面地址，用浏览器打开即可复制或扫码，不必再开窗口。
2. 若 5 分钟内没打开，可另开终端执行 pairing 查看文字，或重启 serve 拿到新的页面链接：

mast-selfhost-windows-amd64.exe pairing --dir data

Windows 防火墙如果询问，允许专用网络访问。手机必须能访问配对页上的地址，不要用 127.0.0.1。

走不通时先看这里

现象	常见原因
init 提示 public URL is required	监听写成了 0.0.0.0，但没加 --public-url（或 compose 没设 MAST_PUBLIC_URL）
配对 URL 是 127.0.0.1	compose 第一次启动时没设 MAST_PUBLIC_URL。--if-missing 不会改已有配置，需要改 config.yaml 或清空数据后重来
启动失败，说至少要一个 provider	init 时没加 --provider-id，或后来把列表清空了
电脑浏览器能开，手机不行	public_url 写成了 127.0.0.1，或手机不在同一局域网，或防火墙挡住 8443
配对命令报 Token 不存在	还没成功启动过一次 serve。Token 是第一次成功启动时才生成的
查询很慢或 429	网页来源限流了。先等一等，不要狂点刷新

更多排错、域名证书、反代和备份见 DEPLOY.md。

这台服务不会做什么

• 不会把号码转发到官方实时查询。
• 没有网页管理后台，没有账号系统。家里人或手机共用同一个 Token。
• 没有查询反馈、没有 Prometheus、没有 /metrics。
• 公网不要用裸 HTTP。快速开始用的是自签名 HTTPS，只适合家庭局域网。要挂到公网，请按 DEPLOY.md 换可信证书或前置反代。

浏览器打开首页 https://你的地址:8443/ 和健康检查 /api/health 不需要 Token。其余接口都要 Token。

号码归属地数据

内嵌 phone.dat 来自 pangongzi/phone，固定 Commit a0076a7cdfb5b44c53e70fac0bc46ef3ebb8bd80，上游为 ls0f/phone。文件未修改，SHA-256 为 5858836c6a472a706a690a55419d589ccbcd9e72721852642280d9e10e379bc2。

该数据按 MIT 分发，不适用本仓库根目录的 Apache-2.0。完整文本见 THIRD_PARTY_NOTICES.md。号码段可能过时或有误差，不能作为紧急服务、身份验证、计费或人身安全的唯一依据。