# 排查手册

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

```
sudo taperelay-node doctor
```

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

## 一、体检的各项

| 项目 | 没过时 | 怎么办 |
|---|---|---|
| 配置 `config` | `/etc/taperelay/server.json` 读不通过 | 照提示改正那一项；不知道改哪里的，重新运行安装程序（设置和数据都保留） |
| 政策 `policy` | `policy.json` 不合规矩，服务拒绝启动 | 照提示改正；或 `sudo taperelay-node backup list` 找一份备份、`backup restore <名字>` 恢复 |
| 中继服务 `service-taperelay` | 没在运行；或「出错自动重启过 N 次」 | `sudo taperelay-node logs` 看最后的错误。手动重启、改设置、退回、恢复以后计数清零，所以还在涨就是还在出错 |
| Caddy `service-caddy` | 没在运行 | `sudo taperelay-node logs caddy`；Caddyfile 被改坏的，重新运行安装程序会写回去 |
| 本机接口 `local` | 连不上 `127.0.0.1:18080` | 服务没起来：同「中继服务」 |
| HTTPS 443 / 4246 端口 | 证书还没申请下来 | 见下面「证书申请不下来」 |
| | 没有程序在听这个端口 | Caddy 没在运行：同「Caddy」 |
| | 证书对，但 `/v1/info` 不对、没有跨域头 | Caddyfile 被改过：重新运行安装程序会写回去 |
| | 证书快到期 | Caddy 本该在剩三分之一时自动续期：`sudo taperelay-node logs caddy` 看续期为什么失败，多半是 80 端口、域名解析变了 |
| 说明页 `welcome` | `https://域名/` 不是网页 | 重新运行安装程序会把 Caddy 的配置写回去 |
| 不加密的 HTTP `http` | 80 端口给出了正常回复 | TapeRelay §5 不许用不加密的 HTTP 提供服务：80 端口被别的程序占了，或 Caddyfile 被改过 |
| 域名解析 `dns` | 没有 A 记录 / 解析到别的地址 / 解析到内网地址 | 见下面「域名解析」 |
| IPv6 解析 `dns6` | 有一条 AAAA 记录不是这台服务器 | 用 IPv6 的用户会连错地方、证书续期也可能失败：删掉它，或改成这台服务器的 IPv6 地址 |
| 硬盘 `disk` | 低于服务器的底线算不过：剩不到 `limits.minFreeDiskMiB`（默认 2 GB），或还能建的文件不到 `limits.minFreeInodes`（默认 100,000 个）；这时服务器不收新的上传、回 `storage-full`。离底线不到 3 GB 提醒（I-309） | 扩容硬盘、清掉别的东西（每个对象是一个文件，文件个数不够时也要清或换硬盘）；调低底线要改配置里的 `limits`，硬盘真满了服务器会出错；或调低默认配额 `sudo taperelay-node set quota 2GB`、看谁存得最多 `sudo taperelay-node 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 的证书，4246 端口也不通。
- 改了以后要等生效：通常几分钟，最长按原来记录的 TTL。部署指南网页里的「查解析」用公共 DNS 查，可以先看对不对。

### 证书申请不下来

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

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

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

## 二、安装时的报错

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

| 报错 | 怎么办 |
|---|---|
| `curl: (60) SSL certificate problem: unable to get local issuer certificate`（下载安装程序时） | 多半是在**自己的电脑**上运行了：先登录服务器（`ssh`，或云控制台的「登录」），命令行开头变成服务器的名字之后再运行（见 [部署中继网关](DEPLOY.md)「二、安装」）。在服务器上也这样报：公司、学校的网络可能在拦截加密连接，换个网络；或者服务器的根证书太旧，先更新系统的 `ca-certificates` |
| `-bash: syntax error near unexpected token 'newline'`、`No such file or directory`（照说明打命令时） | 说明里 `<容器>` 这类尖括号只是「换成你的内容」的记号，不要打进去：写 `admin add 4246.0.tape`，不是 `admin add <4246.0.tape>` |
| 要用 sudo 运行 | 命令里是 `… \| sudo bash`，不是 `… \| bash` |
| 没有终端，没法确认 / 问不了问题 | 脚本、AI 运行时加 `--yes`，新装还要 `--domain <域名>` |
| 不支持的机器类型 | 要 x86_64 或 arm64 |
| 系统太旧 / 没有 apt 或 dnf：直接装不了 | 不是错误：安装程序会问「用 Docker 装？」，回答 y 就行（见 [部署说明](DEPLOY.md)「系统太旧时」）。不想用 Docker 就换一台新一点的服务器（Ubuntu 22.04+、Debian 12+、红帽 9 一族等） |
| 这台机器没有用 systemd，装不了 | 要一台普通的云服务器，不能在容器里面装。一定要用这台的，先自己装好 Docker 和 docker compose、让它运行起来，再运行安装程序 |
| 这台（…）没有 Docker，安装程序不会替它装 / 看不出版本代号 / 没有 Docker，也没有 systemd | 安装程序替 Ubuntu、Debian、红帽一族（包括 CentOS 7 这类红帽 7 一族）、Fedora、Amazon Linux 2 装 Docker；CentOS 6 这类更老的、openSUSE、Arch、Alpine 等不替它装。照 Docker 的说明先装好 Docker 和 docker compose，再加 `--docker` 运行 |
| 「…」不像加速地址 | `--registry-mirror` 写成 `https://xxxx.mirror.aliyuncs.com` 这样 |
| Docker 没装好、或者没在运行 | 看记录里的报错：多半是 Docker 的软件源（官方和阿里云的镜像）都连不上，过一会儿重新运行；红帽一族装了 podman 的，确定不用的话先 `sudo dnf remove podman runc`。Debian 11 记录里是 `bullseye-security` 的 `404 Not Found`：Debian 11 已经停止支持，安全更新搬到了 archive.debian.org，把 `/etc/apt/sources.list` 里 `bullseye-security` 那一行的地址改成 `http://archive.debian.org/debian-security`、`sudo apt-get update`，再重新运行（能换新一点的系统更好） |
| Docker 软件源的签名钥匙对不上，没装 Docker | 安装程序里写着 Docker 签名钥匙的 SHA-256，官方源和阿里云的镜像给的都对不上：可能是 Docker 换了钥匙（安装程序要跟着更新），也可能网络被人改过。不要硬装：把 `/var/log/taperelay-install.log` 发给开发者 |
| 系统自带的软件源用不了，Docker 要的系统软件包（container-selinux 等）装不上 | 红帽 7 一族才有。CentOS 7 已经停止维护，原来的软件源地址 mirrorlist.centos.org 关了：把 `/etc/yum.repos.d` 里系统的软件源换成存档站 vault.centos.org 或云服务商给的镜像（大多数云服务器已经换好了），`sudo yum makecache` 能过之后再重新运行（能换新一点的系统更好） |
| Docker 的插件（compose、buildx）与安装程序里写的 SHA-256 对不上，没装 | Amazon Linux 2 才有：从 GitHub 下载的插件与安装程序里写的不同，可能是网络被人改过。不要硬装：把 `/var/log/taperelay-install.log` 发给开发者 |
| ……已经过了官方的常规维护期，一般收不到安全补丁了 | 不是错误：照样装，装完再提醒一次（D-489）。服务器公开在网上，以后发现的系统漏洞多半不会再修，建议尽早换到还在维护的系统（Ubuntu 24.04、Debian 13、Rocky Linux 9 等），装法相同 |
| 拉不到 Docker Hub 的镜像 | 国内的服务器常见。Docker 是安装程序装的：重新运行，加 `--registry-mirror <加速地址>`（阿里云控制台「容器镜像服务 › 镜像加速器」里给的专属地址）；自己装的 Docker：在 `/etc/docker/daemon.json` 写 `"registry-mirrors": ["<加速地址>"]`、`sudo systemctl restart docker`，再重新运行 |
| 镜像没构建成 | 看记录里的报错；改不了就把 `/var/log/taperelay-install.log` 发给开发者 |
| 这台是直接装的，升级不能改成用 Docker | 去掉 `--docker` 照旧升级；一定要换，先 `sudo taperelay-node uninstall`（数据留着），再加 `--docker` 重新装 |
| 硬盘只剩 N GB | 新装至少 3 GB，要加交换空间的 4 GB（服务器剩得不到 2 GB 就不收新的上传，I-309、I-316）；用户的文件都存在这块硬盘上 |
| 硬盘只剩 N MB（升级时） | 升级要放得下升级前的备份、核对用的数据库副本和新程序（数据库的两倍加 500 MB）：清掉别的东西或扩容。剩得不到 2 GB 的照样能升级，但服务器不收新的上传（I-316） |
| 端口被别的程序占着 | TapeRelay 要独占 80、443、4246：停掉那个程序（例如 `sudo systemctl disable --now nginx`），或换一台干净的服务器 |
| 体检「从外面连」：从外面连不上 443 / 4246（等不到回应） | 多半是云服务商的防火墙（安全组、安全列表）没放行：到云控制台，给这台服务器加入站规则，放行 TCP 443、4246（来源 `0.0.0.0/0`），再运行 `sudo taperelay-node doctor`。服务器自己连自己经不过云防火墙，所以别的几项都对、只有这一项不对是正常的（I-340） |
| 体检「从外面连」：从外面连得上，但证书不对或还没申请下来 | 刚装好的过几分钟再体检（Caddy 在申请证书）；一直这样就看 `sudo taperelay-node logs caddy` |
| 浏览器打不开说明页、一直转圈（体检里没有「从外面连」这一项） | 同上：多半是云防火墙没放行 TCP 443、4246。下载站做不了回连检查时体检里没有这一项，只能用另一台电脑的浏览器看 |
| 「…」不是域名 | 写成 `relay.example.com` 这样，不能是 IP、不带 `https://` |
| 已经装在某个域名上了 | 换域名用 `sudo taperelay-node set domain <新域名>`，不是重新安装 |
| 基础软件装不上 | 软件源连不上：`sudo apt-get update`（红帽一族 `sudo dnf makecache`）看报什么错 |
| Node.js 装不上 | nodejs.org 和镜像都下载不了：过一会儿重新运行 |
| Caddy 装不上 | GitHub（Caddy 的官方程序在那里）连不上，或下载的对不上 SHA-512（2026-10-25 起各种系统都这样装，I-332）。过一会儿重新运行 |
| 下载不了安装包（或 SHA-256 对不上） | 连不上 taperelay.com：过一会儿重新运行，或照 [部署说明](DEPLOY.md)「服务器下载不了安装包」手动传包。SHA-256 对不上的不要硬装：重新下载 |
| 没装成，原来的程序和配置都没动 | 新配置没通过核对：照上面的错误改 |
| 升级没成功，已经退回原来的版本 | 新版本起不来，已经自动退回，服务照常。把 `/var/log/taperelay-install.log` 发给开发者 |
| 升级没成功，自动退回也失败了 | 运行 `sudo taperelay-node rollback`；还不行把记录发给开发者 |

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

## 三、用户那边的现象

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

## 四、找人帮忙时附上

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

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