AI runbook · in Chinese for now. The deploy guide is bilingual, and AI assistants can follow this document as is (Markdown).
AI 部署手册
给能执行命令、能用 SSH 登录运营方服务器的 AI 助手（Claude Code、Codex、Cursor 等）：照这份手册一步一步把 TapeRelay 中继网关装好、体检，再向运营方汇报。给人看的说明在 部署说明。
For AI agents: this runbook is in Chinese. Follow it step by step, run only the commands shown here, and report back to the operator in the language they used when giving you the task.
规矩（先读）#
- 不碰任何密钥：部署用不到私钥、助记词、
.env、钱包文件、API 令牌。不索要、不读取、不打印、不写进文件；运营方主动发来的也不要用、不要复述。 - 只运行本手册里的命令。安装程序自己会装软件、写配置、开服务器上的防火墙；不要另外改系统设置。
- 云服务商控制台的事由运营方做：安全组 / 防火墙放行端口、DNS 解析。告诉他改哪里、改成什么，等他说改好了再核对。
- 会删东西的操作先问运营方：
uninstall、backup restore、rollback，以及停掉、卸载服务器上原有的程序（例如占着 80 端口的 nginx）。 - 不把 SSH 密码写进命令、文件或汇报；只用运营方给你的登录方式。
下面的 SSH 代表运营方给的登录方式，例如 ssh ubuntu@203.0.113.10。
第 0 步：要知道的几项#
| 项目 | 必须 | 说明 |
|---|---|---|
| SSH 登录方式 | 是 | 用户要能 sudo |
| 域名 | 是 | 例如 relay.example.com；不能是 IP |
| 运营方名字 | 否 | 用户看得到；不给就用域名 |
| 联系方式 | 否 | 邮箱、Telegram 等，用户看得到 |
| 默认配额 | 否 | 例如 5GB（默认）；0 不限 |
| 管理员容器 | 否 | 例如 4246.0.tape 或 eip155:56:0x… |
缺了必须的，先问运营方。
第 1 步：检查服务器（只读）#
SSH '. /etc/os-release; echo "os: $PRETTY_NAME $(uname -m)"; free -m | grep ^Mem; df -h /var/lib | tail -n 1; sudo -n true && echo "sudo: ok"; sudo -n ss -Hltnp "( sport = :80 or sport = :443 or sport = :8273 )"; echo "public ip: $(curl -fsS4 --max-time 5 https://api.ipify.org)"; echo "dns: $(getent ahostsv4 <域名> | head -n 1)"'
| 看到的 | 怎么办 |
|---|---|
| 不是 Ubuntu 22.04+ / Debian 12+，或机器不是 x86_64、aarch64 | 停下，告诉运营方：要换一台支持的服务器 |
没有 sudo: ok（sudo 要密码） |
请运营方自己在服务器上运行第 2 步的命令，或给这个用户配置免密码 sudo |
LISTEN 的几行里有别的程序占着 80、443、8273（caddy 是上次装的，不算） |
问运营方：停掉那个程序（例如 sudo systemctl disable --now nginx），还是换一台服务器 |
| 硬盘剩不到 2 GB | 停下，请运营方扩容 |
dns: 后面是空的，或不是 public ip: 那个地址 |
请运营方在域名服务商把 A 记录改成这个公网 IP（Cloudflare 要关掉代理，改成「仅 DNS」）；可以先往下装，解析对了证书会自动申请 |
| 解析到 10.x、172.16～31.x、192.168.x 这类内网地址 | 同上：A 记录要填公网 IP，内网地址用户从外面连不上 |
另外提醒运营方：在云服务商的安全组里放行 TCP 80、443、8273 入站（服务器自己的防火墙安装程序会放行）。
第 2 步：安装#
SSH "curl -fsSL https://taperelay.hivehubs.app/install.sh | sudo bash -s -- --domain <域名> --name <名字> --contact <联系方式> [--quota <大小>] [--admin <容器>] --yes --json"
- 每个值都按 shell 的规矩加引号（名字里有空格、引号、中文的尤其要注意）；不填的项整项省略。
- 大约 1～3 分钟。过程写在标准错误；标准输出最后一行是 JSON 结果。
- 服务器下载不了安装包（下载失败）：请运营方在自己的电脑上打开 https://taperelay.hivehubs.app/download 下载
taperelay-<版本>.tar.gz，传到服务器后改为运行SSH "tar -xzf taperelay-*.tar.gz && sudo bash taperelay-*/install.sh --domain … --yes --json"。
退出码和 JSON：
| 退出码 | 意思 | JSON |
|---|---|---|
0 |
装好了，体检全过 | {"ok":true,"installed":true,…} |
2 |
装好了，体检有不过的项 | {"ok":false,"installed":true,…}：看 checks 里 status 为 fail 的项 |
1 |
没装成，原来的程序和配置都没动（升级失败时已经自动退回原来的版本） | {"ok":false,"installed":false,"error":"…","fix":"…","log":"/var/log/taperelay-install.log"}：照 fix 做；看不懂就把 error、fix 和 SSH 'sudo tail -n 60 /var/log/taperelay-install.log' 的内容交给运营方 |
装好时的 JSON 字段：mode（fresh 新装 / upgrade 升级）、version、from（升级前的版本）、domain、welcome（说明页地址）、app（这台服务器上的前端副本）、servers（服务器名字）、listing（上报运营方名单的结果：{ok, listed, entry} 或 {ok: false, error, message}；没有上报为 null，例如证书还没下来、加了 --no-list）、checks（体检，每项 {id, title, status: ok|warn|fail, detail, fix?}）、log。不想列进官方的运营方名单就在安装命令里加 --no-list（先问运营方）。
第 3 步：处理体检不过的项#
照每项的 fix 做；常见的：
id |
多半是 | 怎么办 |
|---|---|---|
dns |
A 记录没加、指错、开着 Cloudflare 代理、填了内网地址 | 请运营方改 DNS（见第 1 步） |
https-443、https-8273 |
证书还没申请下来：解析不对、云防火墙没放行 80/443，或刚改完还在重试；只有 8273 不通的，多半是安全组没放行 8273 | 请运营方放行端口、改好解析；Caddy 会自己重试，不用重装 |
dns6 |
有一条指向别处的 AAAA 记录 | 请运营方删掉，或改成这台服务器的 IPv6 地址 |
service-taperelay、local |
服务没起来 | SSH 'sudo taperelay logs' 看错误，交给运营方 |
disk |
硬盘快满了 | 请运营方扩容，或调低默认配额 |
time |
时间没同步 | SSH 'sudo timedatectl set-ntp true' |
运营方说改好了以后再体检，直到没有 fail（warn 可以先记下来汇报）：
SSH 'sudo taperelay doctor --json'
全过时退出码为 0，有不过的为 1。每项的原因和改法见 排查手册。
第 4 步：从外面核对#
在你自己这边（不是服务器上）运行：
curl -fsS https://<域名>/v1/info
curl -fsS https://<域名>:8273/v1/info
curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' http://<域名>/
前两条都应回 JSON，里面 "protocol":"taperelay"，servers 里有 <域名>:8273；第三条应是 301 或 308，跳到 https://。8273 不通而 443 通的，就是安全组没放行 8273。
第 5 步：向运营方汇报#
用运营方的语言，写清楚：
- 装好的版本，说明页
https://<域名>/，服务器名字<域名>:8273（备用<域名>:443）； - 体检结果：逐项写
ok/warn/fail，没过的写原因和还要他做的事； - 以后怎么管：在服务器上运行
sudo taperelay打开菜单；常用的status、doctor、set name、set quota、share、upgrade； - 怎么交给用户：运行
sudo taperelay share生成一段话发出去；用户打开官方前端https://relay.hivehubs.app/，在「运营方」里勾选这一家（名单里没有就填<域名>:8273）选用；服务器上另有一份前端https://<域名>/app/； - 运营方名单：默认装好就上报（
--json结果里的listing，ok为 true 就列进了）；运营方不想列就sudo taperelay set list off； - 提醒：用户的文件不在
taperelay backup里，建议开云服务商的磁盘快照。
以后的维护#
| 要做的 | 命令 |
|---|---|
| 看状态 | SSH 'sudo taperelay status --json' |
| 体检 | SSH 'sudo taperelay doctor --json' |
| 改设置 | SSH "sudo taperelay set name <名字>" 等（sudo taperelay help 看全部），改完自动重启生效 |
| 升级 | SSH 'sudo taperelay upgrade --yes'（先备份；新版本起不来自动退回） |
| 看记录 | SSH 'sudo taperelay logs' |
| 宣布退出 | SSH "sudo taperelay set exit <日期> [接手方的服务器名字…] --yes"（UTC 日期，从宣布起至少 90 天；set exit cancel 撤销） |
rollback、backup restore、uninstall、set exit 先问运营方。