Deployment guide · in Chinese for now. The deploy guide is bilingual, and AI assistants can follow this document as is (Markdown).

部署中继网关

给运营方：一台云服务器、一个域名、一行命令，大约 10 分钟装好一台 TapeRelay 中继网关；装好以后用一个菜单管理。

一、准备三样东西

要求
云服务器 常见的 Linux 服务器系统（x86_64 或 ARM）：Ubuntu 22.04 以上、Debian 12 以上、红帽 9 一族（Rocky、AlmaLinux、CentOS Stream、RHEL、OpenCloudOS 9 等）、Fedora、Amazon Linux 2023 直接装；更旧的（Ubuntu 20.04、Debian 11、红帽 8 一族、CentOS 7 等）安装程序会改用 Docker 装（见下面「系统太旧时」）。1 核、1 GB 内存起步（服务本身最多用 512 MiB，I-362；内存不到 2 GB、又没有交换空间时，安装程序加 1 GB 交换空间）；硬盘至少空 3 GB，要加交换空间的至少 4 GB（服务器剩得不到 2 GB 就不收新的上传，I-309、I-316），按要给用户的空间准备；有公网 IP、能用 sudo；要一台普通的云服务器（不能在 Docker 容器里面装）
域名 在域名服务商加一条 A 记录，指向服务器的公网 IP（云控制台里叫「公网 IP」或「弹性 IP」，不是 10.x、172.16～31.x、192.168.x 这类内网地址）。用 Cloudflare 的要关掉代理（灰色云「仅 DNS」）：客户端按普通网站的规则直接校验证书
端口 在云服务商的安全组 / 防火墙里放行 TCP 80、443、4246 入站。4246 是协议的专用端口，443 备用（有的网络只放行 443），80 只用来申请证书、把不加密的请求跳到 HTTPS

TapeRelay 要独占这三个端口，用一台干净的服务器最省事。

二、安装

用 SSH 登录服务器，运行：

curl -fsSL https://taperelay.com/install.sh | sudo bash

它先检查服务器，再问 3 个问题（域名、运营方名字、联系方式；直接回车用括号里的），确认一次就开始装，大约 1 分钟。域名还没解析好的，可以先装着：解析对了以后证书会自动申请。想先看看脚本写了什么，用浏览器打开上面的网址就行。

不想回答问题，就把答案写在后面；给脚本、AI 用的再加 --yes（不问、不确认）：

curl -fsSL https://taperelay.com/install.sh | sudo bash -s -- \
  --domain relay.example.com --name '我的中继' --contact me@example.com --yes
选项 意思
--domain <域名> 例如 relay.example.com（不能是 IP）
--name <名字> 运营方名字，用户在说明页里看到（默认就是域名）
--contact <联系方式> 邮箱、Telegram 等，用户看得到；可以不填
--quota <大小> 每个容器默认的配额，例如 5GB（默认 5GB；0 表示不限）
--admin <容器> 管理员容器：名字（例如 4246.0.tape）或地址（eip155:56:0x…），可以写多次；用来在前端的运营方页管理
--yes 不问、不确认。没有终端时必须加；新装还要 --domain
--json 最后在标准输出打印一行 JSON 结果（过程写到标准错误），格式见 AI 部署手册
--no-list 不列进官方的运营方名单（默认装好后服务器自己上报、列进去，官方前端的用户能看到你；以后 sudo taperelay-node set list on|off 改）
--no-stats 不公开这台每天的请求数、访客数、发出的字节数（默认公开在 https://你的域名/v1/stats/gateway，只有合计、不存访客的地址；以后 sudo taperelay-node set stats on|off 改）。一步一步问的时候，名单、统计这两样都会直接问你
--local-ca 证书由 Caddy 自己签：只用于没有公网域名的测试机（不上报名单）
--profile <配置名> default（默认）、test-1、test-2：官方的两台测试服务器用
--docker 用 Docker 装（系统太旧、直接装不了时安装程序会自己问，不用加）
--registry-mirror <地址> Docker Hub 的镜像加速地址（例如阿里云「容器镜像服务」给的 https://xxxx.mirror.aliyuncs.com）；只在 Docker 是这次安装程序装的时候写进 Docker 的设置

退出码：0 装好了、体检全过；2 装好了、体检有不过的项（多半是域名解析或云防火墙：照提示改，不用重装）；1 没装成（原来的程序和配置都没动）。详细记录在 /var/log/taperelay-install.log。

服务器下载不了安装包

在自己的电脑上打开 https://taperelay.com/download 下载最新的 taperelay-<版本>.tar.gz（核对用的 SHA-256 在 https://taperelay.com/SHA256SUMS，部署指南的「离线包」里也写着），传到服务器上运行包里的安装程序：

scp taperelay-*.tar.gz ubuntu@<服务器>:~
ssh ubuntu@<服务器>
tar -xzf taperelay-*.tar.gz && sudo bash taperelay-*/install.sh

Node.js 先从 nodejs.org 下载，下不了换 npmmirror.com 的镜像，都按安装程序里写好的 SHA-256 核对；Caddy 一律用它在 GitHub 上发布的官方程序（固定版本，按安装程序里写好的 SHA-512 核对；2026-10-25 起 Ubuntu、Debian 也这样，原来从它的官方软件源 dl.cloudsmith.io 装，软件源的钥匙和配置都不核对，I-332）。出包时 Node.js 的 SHA-256 与仓库里钉住的（deploy/node-sums.json）对照，不同就不出包。

系统太旧时：用 Docker 装

Node.js 26 的官方程序要系统的 C 库（glibc）是 2.34 以上：Ubuntu 20.04、Debian 11、红帽 8 一族（Rocky 8、AlmaLinux 8、阿里云 Linux 3、OpenCloudOS 8、龙蜥 8 等）、CentOS 7、Amazon Linux 2 都太旧。在这些系统上运行同一行命令，安装程序会先说明，问过再改用 Docker 装同一个版本：

  1. 没有 Docker 的，说明要装什么、从哪里装，问过再装：Docker 的官方软件源 download.docker.com，连不上换阿里云的镜像 mirrors.aliyun.com/docker-ce（同一套签名的软件包；签名钥匙先按安装程序里写的 SHA-256 核对，对不上就不装）；装好开机自动启动。红帽 7 一族（CentOS 7、RHEL 7、Oracle Linux 7、阿里云 Linux 2、TencentOS 2 等）用 Docker 给 CentOS 7 的软件源、yum 装，系统自带的软件源要能用（CentOS 7 原来的地址已经关了，大多数云服务器换好了镜像，装不上时见 排查手册）；Amazon Linux 2 用 Amazon 自己的 docker 软件包，再从 GitHub 下载 docker compose、buildx 两个插件（版本和 SHA-256 写在安装程序里，对不上就不放；还没有在 Amazon Linux 2 上实测）。别的系统（openSUSE、Arch、Alpine 等）安装程序不替你装 Docker：照 Docker 的说明先装好，再加 --docker 运行。Debian 11 已经停止支持，它的安全更新搬到了 archive.debian.org，装不上时见 排查手册；
  2. 要从 Docker Hub 拉 Node.js、Caddy 的官方镜像。国内的服务器常常拉不到：加 --registry-mirror <加速地址>（阿里云控制台「容器镜像服务 › 镜像加速器」里给的专属地址）。拉不到时安装程序会提示怎么加；
  3. 镜像在服务器上就地构建，用的是安装程序已经核对过 SHA-256 的同一个安装包；
  4. 数据、配置、备份的位置与直接装的相同（/var/lib/taperelay、/etc/taperelay、/var/backups/taperelay），证书在 /var/lib/taperelay-caddy；
  5. 装好以后照样用 sudo taperelay-node，命令、菜单都相同：状态、体检、改设置、看记录、备份恢复、升级、退回、卸载。不同的只是背后：服务是三个容器（taperelay-net 占着网络和端口、taperelay-server 参考服务器、taperelay-caddy HTTPS），运维程序在一个用完就删的容器里跑；升级、退回、卸载在服务器上直接做（卸载不删 Docker 本身）。

系统新、也可以直接装的，想用 Docker 就加 --docker。已经用一种方式装了的，再运行安装程序（升级）照原来的方式。

已经过了官方常规维护期（一般收不到安全补丁了）的系统照样装：CentOS 7、8，RHEL、Oracle Linux 7，阿里云 Linux 2，Amazon Linux 2，Ubuntu 20.04 及更早，Debian 11 及更早（名单只列服务器上常见的；Ubuntu 的非长期支持版等过了期的也照样装，只是不提醒）。安装程序检查时写明，装完再醒目地提醒一次；服务器公开在网上，以后发现的系统漏洞多半不会再修（另外付费买了延长支持的除外），建议尽早换到还在维护的系统（例如 Ubuntu 24.04、Debian 13、Rocky Linux 9），装法相同（D-489）。Debian 12 的常规维护 2026-07-11 结束，之后由社区的长期支持（LTS，不收费）接着出补丁到 2028-06-30，所以不算；新装的话选 Debian 13。

安装程序做的事

  1. 检查：系统和机器类型、内存、硬盘、三个端口空不空、公网 IP、域名解析到哪里。端口被别的程序占着（包括别人在用的 Caddy）就停下，不接管、不覆盖别人的网站；这台原来装了 Caddy、但没占着这几个端口的，安装程序会用它，先把原来的配置另存为 /etc/caddy/Caddyfile.before-taperelay，卸载时放回去、照装之前的样子开着或停着（2026-10-24，I-302、I-308）。Caddyfile 里有 TapeRelay 的标记才算安装程序自己写的：运营方把它换成了自己的网站、Caddy 又占着端口的，升级时也停下；Caddy 没在占着端口的（例如卸载后运营方自己换了配置再装），照「装之前就有的」处理，卸载过再装的按这一次装之前的样子记（I-317）。硬盘：新装至少 3 GB（要加交换空间的 4 GB）；升级只要放得下升级前的备份、核对用的数据库副本和新程序（数据库的两倍加 500 MB），剩得不到 2 GB 只提醒（I-316）；
  2. 基础软件；内存小时加交换空间；
  3. Node.js（核对 SHA-256；只给 TapeRelay 用，链接在 /opt/taperelay/node，不换系统的 node）、Caddy；
  4. 程序装到 /opt/taperelay/current（安装包自带 TapeKit 内核和依赖，不在服务器上运行 npm）；配置先生成，再用服务器自己的代码、caddy validate 核对，都通过才写；
  5. systemd 服务：以系统用户 taperelay 运行，程序只读、只能写数据目录，出错自动重启；服务器自己的防火墙（ufw、firewalld、iptables）放行三个端口；
  6. 启动；Caddy 申请证书；体检（同 sudo taperelay-node doctor），打印结果和下一步。

再运行一次就是升级：设置和数据都保留，先备份，新版本先在数据库的副本上核对（读不了现在的数据就不换程序），新版本起不来自动退回。比装着的旧的版本不装（确实要装加 --allow-downgrade）。

发布有签名（2026-10-24 起）：每一版的 SHA256SUMS（列着安装包和 install.sh 的 SHA-256）由 TapeOut 的发布钥匙签名（SHA256SUMS.sig）。装好的服务器运行 sudo taperelay-node upgrade 时，先用自己装着的那一版里的公钥名单核对签名、核对 install.sh，核对不过就不升级：发布网站被人改了，也装不进你的服务器。第一次安装照旧靠发布网站的 HTTPS；要自己核对，发布公钥的编号是 a370ecb982de625e（公钥 fc43d3b7f24c3045883bf21e4dffeb36ccfd29a92fe8f85421b15d8728e9512e），下载解开安装包后运行 node taperelay-<版本>/TapeRelay/deploy/release-sign.mjs verify <放着 SHA256SUMS、SHA256SUMS.sig、install.sh 的目录>。

运维命令叫 taperelay-node（2026-10-23 起；以前叫 taperelay，升级时旧名字的入口自动删掉）；服务名、系统用户、目录照旧叫 taperelay。

三、装好以后

想做的事 命令（都以 sudo taperelay-node 开头）
看状态、用量 status
体检（出问题先跑它） doctor
看记录 logs（Caddy 的：logs caddy；加 -f 一直跟着看）
改名字、联系方式 set name '我的中继'、set contact me@example.com
默认配额 set quota 10GB（0 不限）
收费 / 免费 set price https://… '一句话说明'、set price free
保存期限（天） set retention 30 90 90 90 30：依次是没有容器再用的文件、欠费容器的文件、超出配额的容器（之后从最后传的删到不超出）、收件箱里的通知各保留几天，上传的文件至少留几天（不少于 7，不能比第 2、3 个大，只能改长、不能改短；改长时会再问一次）；可以只写前几个
收不收加密文件 set encrypted on、set encrypted off
管理员容器 admin add 4246.0.tape、admin remove …、admin list
给某个容器另定配额 quota <容器> 50GB（写 default 回到默认的）
下架 / 恢复一个对象 takedown <哈希>、untakedown <哈希>
存得最多的容器（超出配额的标出来） accounts
下载流量（每天的合计、流量最多的对象） traffic（默认最近 7 天；traffic 30 看 30 天）
换域名 set domain <新域名>（用户要重新选用，慎重）
列不列进官方的运营方名单 set list on、set list off（默认列进；官方大约每 10 分钟读一次你的 /v1/info，名字、联系方式跟着变）
公不公开每天的统计 set stats on、set stats off（默认公开在 https://你的域名/v1/stats/gateway：每天的请求数、访客数、发出的字节数，只有合计）
宣布退出 set exit 2027-03-01（有接手方就把它的服务器名字写在后面；set exit cancel 撤销），见第五节

改设置后自动重启服务（约 2 秒）生效。名字、配额、价格、保存期限这些政策写在数据目录的 policy.json 里，和前端运营方页改的是同一份；status 写明现在生效的是哪一份。

网页后台：加了管理员容器以后（一步一步装时第 ④ 问就能填，D-492；或以后 admin add），可以用这个容器在 TapeRelay 网页前端的运营方页（官方的 https://app.taperelay.com/TapeRelay/ui/app/operator.html；内测期间用内测网址 https://app.taperelay-test.duckdns.org/TapeRelay/ui/app/operator.html；放了前端副本（set app on）的服务器上另有 https://你的域名/TapeRelay/ui/app/operator.html，默认不放就没有；2026-10-23 起用户的应用里没有到这一页的入口；装完的总结里写着网址）里看各容器的用量、下载流量、改政策、下架、宣布退出，不用登录服务器；用上面的命令效果一样。

四、交给用户

sudo taperelay-node share 生成一段话（名字、说明页、服务器名字、配额、价格、联系方式、前端的网址），发到群里、网站上。开发者看说明页和开发者指南（https://taperelay.com/developers.html）；只想存文件的用户不用装任何东西：

  1. 打开官方前端 https://app.taperelay.com/，连接钱包（持有他的 TapeOut 容器的那个），打开容器；
  2. 第一次打开时有四步设置：第 ① 步选运营方时勾上你这一家（名单里没有就在「另外的服务器」里填 你的域名:4246；建议再勾一家，文件各存一份），之后设本机口令、生成加密密钥、备份，第 ④ 步在钱包里确认一笔交易（写进容器的链上记录，付一点手续费）；以后改选在「设置 › 运营方和套餐」；
  3. 之后上传、分享、收发文件都经过你的服务器。

前端的副本（2026-10-25 起默认不放，I-326、D-464）：https://你的域名/app/ 跳到官方前端。要放一份同样的前端（装的时候加 --app，或以后 sudo taperelay-node set app on）之前要知道：这份网页的代码在你的服务器上，用户在那里输入的本机口令、解开的加密私钥你都能拿到，也能请他们的钱包签名，所以副本顶部会写明这一点，用户要信得过你才会在那里用。浏览器按网址存加密私钥、「我的文件」这些本机记录，在副本里做的只存在你的网址下，你的服务器关了就找不回，副本顶部也会提醒用户先导出备份、平时用官方前端；分享出去的链接一律以官方前端开头。两台测试服务器（配置名 test-1、test-2）照旧放。

运营方名单：装好后服务器自己上报，官方读你的 /v1/info 核对连得上就列出，不用申请（D-328）；体检里的「运营方名单」一项写着在不在名单里。注册表上线后，官方前端只列出登记过、在保（交了押金、照常运营）的运营方，不能再手填名单外的服务器。登记的办法开放时公布在部署指南网站上。

五、升级、备份、退回、退出、卸载

命令（sudo taperelay-node …） 说明
升级 upgrade 从 taperelay.com 取最新版：先备份数据库和配置，换程序，新版本起不来自动退回；设置和数据都保留
备份 backup 数据库、policy.json、配置、Caddyfile，放在 /var/backups/taperelay（只有 root 能读；2026-10-23 之前的版本放在 /var/lib/taperelay/backups，以前的备份留在那里），只留最近 10 份。用户的文件本身很大，不在备份里：用云服务商的磁盘快照防硬盘坏
恢复 backup list、backup restore <名字> 备份之后的改动（新上传的记录等）会丢
退回 rollback 退回上一个版本，数据库和配置用升级前的备份
退出 set exit <日期> [接手方…] 宣布哪天（UTC）停止服务，从宣布起至少留 90 天：说明页顶部写明日期；有接手方的照常收新文件，没有的新上传一律拒绝、读取照常到那天；那天之前不得删用户的文件。set exit cancel 撤销。注册表上线后以注册表里的退出时间为准
卸载 uninstall 默认留着数据和配置；加 --purge 一起删（找不回来）。不想干了先宣布退出，到期再卸载。Caddy 是安装程序装的就停掉；装之前就有的放回原来的配置，装之前开着的照常运行、停着的停下，开不开机启动也照原样；装之前就有 Caddy、但没有配置文件的，删掉 TapeRelay 写的配置、停下 Caddy（I-308）

六、服务器上的布局

/opt/taperelay/current/TapeRelay/   程序（只有 root 能改）；上一版在 /opt/taperelay/old
/opt/taperelay/current/TapeKit/kernel/
/opt/node-v<版本>-linux-<机器>/      Node.js（/opt/taperelay/node 是链接，只给 TapeRelay 用；2026-10-24 之前的版本另链接成 /usr/local/bin/node，升级时不动它）
/usr/local/bin/taperelay-node      运维命令
/etc/taperelay/server.json         配置（root:taperelay 640，服务只能读）
/etc/taperelay/install.json        安装时选的配置名、证书来源、列不列进名单、Caddy 是不是装之前就有的
/etc/caddy/Caddyfile               Caddy：说明页、443 和 4246 两个端口、80 跳到 HTTPS
/var/lib/taperelay/data/           数据库、对象、policy.json（只有 taperelay 能读写）
/var/backups/taperelay/            备份（只有 root 能读）
/var/log/taperelay-install.log     安装、升级的详细记录

用 Docker 装的（「系统太旧时」）：配置、数据、备份、安装记录的位置相同；没有 /opt/taperelay/current 和 Node.js，程序在镜像 taperelay-node:<版本>、taperelay-caddy:<版本> 里；另有：

/opt/taperelay/docker/             compose.yaml、装着的版本（version）、上一个版本（previous）、升级 / 退回 / 卸载用的 host.sh
/usr/local/bin/taperelay-node      运维命令（在一个用完就删的容器里运行同一份运维程序）
/etc/taperelay/Caddyfile           Caddy 的配置（Caddy 的容器只读挂进去）
/var/lib/taperelay-caddy/          Caddy 的证书等（只有 root 能读）

服务器上不放任何密钥：正式模式用不到；证书的私钥由 Caddy 保管，我们的代码碰不到。

许可证：代码 MIT（安装包里的 TapeRelay/LICENSE），规范 CC0。