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