Troubleshooting · in Chinese for now. The deploy guide is bilingual, and AI assistants can follow this document as is (Markdown).
排查手册
中继网关出了问题，先在服务器上运行：
sudo taperelay doctor
它逐项检查配置、服务、证书、域名解析、硬盘、时间，没过的项写明原因和改法（--json 给脚本、AI 用；全过退出码 0，有不过的 1）。下面按它的项目、安装程序的报错、用户那边的现象分别写怎么办。安装和管理的说明在 部署说明。
一、体检的各项#
| 项目 | 没过时 | 怎么办 |
|---|---|---|
配置 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 申请，要同时满足：
- 域名解析到这台服务器（上一节）；
- 云服务商的安全组 / 防火墙放行了 TCP 80、443 入站（申请时 Let's Encrypt 从外面连进来核对）；8273 也要放行，用户才连得上；
- 申请太频繁被限流的，等一小时左右。
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：过一会儿重新运行，或照 部署说明「服务器下载不了安装包」手动传包。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、钱包私钥、助记词，谁要都不给。