# 部署中继网关

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

- 网页版的部署指南（新手指引、生成命令、查解析、从外面检查，中英两种语言）：<https://taperelay.hivehubs.app/>
- 让 AI 助手代你部署：见 [AI 部署手册](DEPLOY-FOR-AI.md)
- 出了问题：先在服务器上运行 `sudo taperelay doctor`，再看 [排查手册](TROUBLESHOOTING.md)

## 一、准备三样东西

| | 要求 |
|---|---|
| 云服务器 | Ubuntu 22.04 / 24.04 或 Debian 12（x86_64 或 ARM）；1 核、1 GB 内存起步（内存不到 2 GB、又没有交换空间时，安装程序加 1 GB 交换空间）；硬盘至少 2 GB，按要给用户的空间准备；有公网 IP、能用 sudo；要一台普通的云服务器（要 systemd，不能是 Docker 容器） |
| 域名 | 在域名服务商加一条 A 记录，指向服务器的**公网** IP（云控制台里叫「公网 IP」或「弹性 IP」，不是 10.x、172.16～31.x、192.168.x 这类内网地址）。用 Cloudflare 的要关掉代理（灰色云「仅 DNS」）：客户端按普通网站的规则直接校验证书 |
| 端口 | 在云服务商的安全组 / 防火墙里放行 TCP 80、443、8273 入站。8273 是协议的专用端口，443 备用（有的网络只放行 443），80 只用来申请证书、把不加密的请求跳到 HTTPS |

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

## 二、安装

用 SSH 登录服务器，运行：

```
curl -fsSL https://taperelay.hivehubs.app/install.sh | sudo bash
```

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

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

```
curl -fsSL https://taperelay.hivehubs.app/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 部署手册](DEPLOY-FOR-AI.md) |
| `--no-list` | 不列进官方的运营方名单（默认装好后服务器自己上报、列进去，官方前端的用户能看到你；以后 `sudo taperelay set list on\|off` 改） |
| `--local-ca` | 证书由 Caddy 自己签：只用于没有公网域名的测试机（不上报名单） |
| `--profile <配置名>` | `default`（默认）、`test-1`、`test-2`：官方的两台测试服务器用 |

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

### 服务器下载不了安装包

在自己的电脑上打开 <https://taperelay.hivehubs.app/download> 下载最新的 `taperelay-<版本>.tar.gz`（核对用的 SHA-256 在 <https://taperelay.hivehubs.app/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 从它的官方软件源（dl.cloudsmith.io）装。

### 安装程序做的事

1. 检查：系统和机器类型、内存、硬盘、三个端口空不空、公网 IP、域名解析到哪里；
2. 基础软件；内存小时加交换空间；
3. Node.js（核对 SHA-256）、Caddy；
4. 程序装到 `/opt/taperelay/current`（安装包自带 TapeKit 内核和依赖，不在服务器上运行 npm）；配置先生成，再用服务器自己的代码、`caddy validate` 核对，都通过才写；
5. systemd 服务：以系统用户 `taperelay` 运行，程序只读、只能写数据目录，出错自动重启；服务器自己的防火墙（ufw、iptables）放行三个端口；
6. 启动；Caddy 申请证书；体检（同 `sudo taperelay doctor`），打印结果和下一步。

再运行一次就是升级：设置和数据都保留，先备份，新版本起不来自动退回。

## 三、装好以后

- **说明页** `https://你的域名/`：给开发者看的这台的简介（2026-10-23 起，D-340）：你是谁、接口地址、配额、价格、支持的功能，两种做法、三步接入和常见问题，链到开发者指南；中英两种语言，内容从 `/v1/info` 读。
- **从外面检查**：部署指南网页里的「检查」，在浏览器里查解析、两个端口和 `/v1/info`。
- **菜单**：在服务器上运行 `sudo taperelay`，按数字选。也可以直接用命令（`sudo taperelay --help` 看全部）：

| 想做的事 | 命令（都以 `sudo taperelay` 开头） |
|---|---|
| 看状态、用量 | `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`：依次是没有容器再用的文件、欠费容器的文件、超出配额的容器（之后从最后传的删到不超出）、收件箱里的通知各保留几天；可以只写前几个 |
| 收不收加密文件 | `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 exit 2027-03-01`（有接手方就把它的服务器名字写在后面；`set exit cancel` 撤销），见第五节 |

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

**网页后台**：加了管理员容器以后，可以用这个容器在 TapeRelay 网页前端（官方的 `https://relay.hivehubs.app/`，或你服务器上的 `https://你的域名/app/`）的「后台」里看各容器的用量、改政策、下架、宣布退出，不用登录服务器；用上面的命令效果一样。

## 四、交给用户

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

1. 打开官方前端 `https://relay.hivehubs.app/`，连接钱包（持有他的 TapeOut 容器的那个），打开容器；
2. 到「运营方」里勾选你这一家（名单里没有就填 `你的域名:8273`；建议再勾一家，文件各存一份），点「选用」，在钱包里确认一笔交易（写进容器的链上记录，付一点手续费）；
3. 之后上传、分享、收发文件都经过你的服务器；想收加密文件，在「密钥」里生成一对密钥（再一笔交易），并导出备份。

> 你的服务器上也有一份同样的前端：`https://你的域名/app/`。浏览器按网址存加密私钥、「我的文件」这些本机记录，在副本里做的只存在你的网址下，你的服务器关了就找不回，所以副本顶部会提醒用户先导出备份、平时用官方前端；分享出去的链接一律以官方前端开头。

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

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

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

## 六、服务器上的布局

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

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

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