# 排查手册

中继网关出了问题，先在服务器上运行：

```
sudo taperelay doctor
```

它逐项检查配置、服务、证书、域名解析、硬盘、时间，没过的项写明原因和改法（`--json` 给脚本、AI 用；全过退出码 0，有不过的 1）。下面按它的项目、安装程序的报错、用户那边的现象分别写怎么办。安装和管理的说明在 [部署说明](DEPLOY.md)。

## 一、体检的各项

| 项目 | 没过时 | 怎么办 |
|---|---|---|
| 配置 `config` | `/etc/taperelay/server.json` 读不通过 | 照提示改正那一项；不知道改哪里的，重新运行安装程序（设置和数据都保留） |
| 政策 `policy` | `policy.json` 不合规矩，服务拒绝启动 | 照提示改正；或 `sudo taperelay backup list` 找一份备份、`backup restore <名字>` 恢复 |
| 中继服务 `service-taperelay` | 没在运行；或「出错自动重启过 N 次」 | `sudo taperelay logs` 看最后的错误。手动重启、改设置、退回、恢复以后计数清零，所以还在涨就是还在出错 |
| Caddy `service-caddy` | 没在运行 | `sudo taperelay logs caddy`；Caddyfile 被改坏的，重新运行安装程序会写回去 |
| 本机接口 `local` | 连不上 `127.0.0.1:18080` | 服务没起来：同「中继服务」 |
| HTTPS 443 / 8273 端口 | 证书还没申请下来 | 见下面「证书申请不下来」 |
| | 没有程序在听这个端口 | Caddy 没在运行：同「Caddy」 |
| | 证书对，但 `/v1/info` 不对、没有跨域头 | Caddyfile 被改过：重新运行安装程序会写回去 |
| | 证书快到期 | Caddy 本该在剩三分之一时自动续期：`sudo taperelay logs caddy` 看续期为什么失败，多半是 80 端口、域名解析变了 |
| 说明页 `welcome` | `https://域名/` 不是网页 | 重新运行安装程序会把 Caddy 的配置写回去 |
| 不加密的 HTTP `http` | 80 端口给出了正常回复 | 规范 §4 不许用不加密的 HTTP 提供服务：80 端口被别的程序占了，或 Caddyfile 被改过 |
| 域名解析 `dns` | 没有 A 记录 / 解析到别的地址 / 解析到内网地址 | 见下面「域名解析」 |
| IPv6 解析 `dns6` | 有一条 AAAA 记录不是这台服务器 | 用 IPv6 的用户会连错地方、证书续期也可能失败：删掉它，或改成这台服务器的 IPv6 地址 |
| 硬盘 `disk` | 剩不到 5 GB 提醒，剩不到 512 MB 算不过 | 扩容硬盘；或调低默认配额 `sudo taperelay set quota 2GB`、看谁存得最多 `sudo taperelay accounts` |
| 时间 `time` | 没有同步 | 签名要求时间误差在 5 分钟内：`sudo timedatectl set-ntp true` |

### 域名解析

- A 记录要指向服务器的**公网** IP（云控制台里叫「公网 IP」「弹性 IP」）。10.x、172.16～31.x、192.168.x、100.64～127.x 这类内网地址，用户从外面连不上。
- 用 Cloudflare 的：把这条记录的代理关掉（橙色云 → 灰色云「仅 DNS」）。经过代理时，客户端看到的是 Cloudflare 的证书，8273 端口也不通。
- 改了以后要等生效：通常几分钟，最长按原来记录的 TTL。部署指南网页里的「查解析」用公共 DNS 查，可以先看对不对。

### 证书申请不下来

Caddy 自动向 Let's Encrypt 申请，要同时满足：

1. 域名解析到这台服务器（上一节）；
2. 云服务商的安全组 / 防火墙放行了 TCP 80、443 入站（申请时 Let's Encrypt 从外面连进来核对）；8273 也要放行，用户才连得上；
3. 申请太频繁被限流的，等一小时左右。

`sudo taperelay logs caddy` 能看到申请的过程和失败原因（`timeout`、`connection refused` 多半是防火墙；`NXDOMAIN`、`no valid A records` 是解析）。改好以后不用重装，Caddy 会自己重试，过几分钟再运行 `sudo taperelay doctor`。

## 二、安装时的报错

安装程序在哪一步停下都会写明原因和改法；详细记录在 `/var/log/taperelay-install.log`。没装成时原来的程序和配置都没动，改好了重新运行就行。

| 报错 | 怎么办 |
|---|---|
| 要用 sudo 运行 | 命令里是 `… \| sudo bash`，不是 `… \| bash` |
| 没有终端，没法确认 / 问不了问题 | 脚本、AI 运行时加 `--yes`，新装还要 `--domain <域名>` |
| 不支持这个系统 / 版本太旧 / 不支持的机器类型 | 要 Ubuntu 22.04+ 或 Debian 12+，x86_64 或 arm64 |
| 这台机器没有用 systemd | 要一台普通的云服务器，不能在 Docker 容器里装 |
| 硬盘只剩 N GB | 至少 2 GB；用户的文件都存在这块硬盘上 |
| 端口被别的程序占着 | TapeRelay 要独占 80、443、8273：停掉那个程序（例如 `sudo systemctl disable --now nginx`），或换一台干净的服务器 |
| 「…」不是域名 | 写成 `relay.example.com` 这样，不能是 IP、不带 `https://` |
| 已经装在某个域名上了 | 换域名用 `sudo taperelay set domain <新域名>`，不是重新安装 |
| 基础软件装不上 | 软件源连不上：`sudo apt-get update` 看报什么错 |
| Node.js 装不上 | nodejs.org 和镜像都下载不了：过一会儿重新运行 |
| Caddy 装不上 | Caddy 的软件源（dl.cloudsmith.io）连不上：过一会儿重新运行 |
| 下载不了安装包（或 SHA-256 对不上） | 连不上 taperelay.hivehubs.app：过一会儿重新运行，或照 [部署说明](DEPLOY.md)「服务器下载不了安装包」手动传包。SHA-256 对不上的不要硬装：重新下载 |
| 没装成，原来的程序和配置都没动 | 新配置没通过核对：照上面的错误改 |
| 升级没成功，已经退回原来的版本 | 新版本起不来，已经自动退回，服务照常。把 `/var/log/taperelay-install.log` 发给开发者 |
| 升级没成功，自动退回也失败了 | 运行 `sudo taperelay rollback`；还不行把记录发给开发者 |

装好了但退出码是 `2`：服务装好了，体检有不过的项，多半是域名解析或云防火墙。照第一节改，不用重装。

## 三、用户那边的现象

| 现象 | 多半是 | 怎么办 |
|---|---|---|
| 填了服务器名字，客户端说连不上 | 名字填错，或 8273、443 都不通 | 名字是 `你的域名:8273`；在自己的电脑上打开 `https://你的域名:8273/v1/info` 看能不能打开 |
| 有的用户连得上、有的连不上 | 有的网络只放行 443 | 客户端选用 `域名:8273` 时自带 443 的后备，会自动换；都连不上的检查 443 |
| 上传失败，说配额满了 | 这个容器存满了默认配额 | `sudo taperelay set quota <更大的>`，或只给他加：`sudo taperelay quota <容器> 50GB` |
| 上传失败，服务器没空间了 | 硬盘满了 | 扩容硬盘（体检的「硬盘」一项） |
| 加密的文件传不上 | 设成了不收加密文件 | `sudo taperelay set encrypted on` |
| 说明页上的名字、价格不对 | 改的是另一份政策 | `sudo taperelay status` 写明生效的是配置里的还是 `policy.json` 里的；用 `set` 或网页后台改，两者改的是同一份 |
| 浏览器打开说明页提示证书不安全 | 证书还没申请下来，或装的时候用了 `--local-ca` | 见「证书申请不下来」；`--local-ca` 只用于测试，正式用重新装 |

## 四、找人帮忙时附上

```
sudo taperelay doctor --json
sudo taperelay status
sudo taperelay logs | tail -n 100
sudo tail -n 100 /var/log/taperelay-install.log
```

服务器上没有密钥，这些输出里也没有；发出去之前仍然自己看一眼。不要发 `.env`、钱包私钥、助记词，谁要都不给。