# 设备管理、流量额度与后台运维

状态：**代码已实现，部署结果以交付报告为准。** 本文说明实现、操作和验收边界，不代表已经完成公网切换、真实设备验证或自动监控配置。

## 管理员日常使用

当前管理入口为 `https://redraingame.duckdns.org/admin`，下载首页为 `https://redraingame.duckdns.org/`。管理员使用原有随机管理员密钥登录；不是设备激活码，也不与节点密钥共用。登录后使用最长 8 小时的独立会话，刷新页面自动恢复；点击“退出管理”、会话到期或管理进程重启后需要重新登录。浏览器不长期保存管理员密钥，仅持有 Secure、HttpOnly、SameSite=Strict 的主机限定会话 Cookie。不要将密钥放进 URL、公开日志、客户端 ZIP 或源代码。

域名 HTTPS 使用 Let's Encrypt 公信证书并自动续期，管理员应使用域名入口。旧 IP HTTPS 仍使用原自签名证书，专门兼容客户端固定证书校验；不要替换该证书，也不要忽略任意浏览器证书警告。域名接入和服务监听变化见 WEBSITE.md。

1. 点击“新建激活码”，填写设备备注、可用节点和流量策略。
2. 一台设备一个激活码，24 小时内激活。创建结果只展示一次，单独发给对应同事，不把同一码发给多人。
3. 同事在客户端激活后，后台可查看设备名称、授权状态、当月及历史代理流量。
4. “设置”可修改备注、节点、月额度、上传和下载限速。“停用”可恢复；“删除”不可恢复原激活身份，需要重新发码才能重新加入。
5. 删除后保留不可恢复的删除标记、流量和审计记录，不物理清除账本。节点尚未确认撤销时，界面显示“删除待生效”，不能仅因保存成功就当作连接已断开。

本轮部署范围仅台北。旧设备凭据继续保留，不要求已激活设备重新领码；日本不加入本轮管理迁移，也不自动授权给新同事。

设备绑定采用注册 UUID 与 Windows 当前用户 DPAPI 保护凭据，是软件身份绑定，不是不可复制的硬件证明。重装、换 Windows 用户、复制凭据的安全边界不能表述为硬件级防克隆。

## 额度、限速和统计口径

| 项目 | 行为 |
| --- | --- |
| 月度额度 | 每个设备按北京时间 UTC+8 自然月计算，代理上传与下载相加；留空不限，填写 0 禁止代理转发。 |
| 单位 | 当前界面“GB”按 `1024³` 字节换算，实际为 GiB；“Mbps”按每秒 `1,000,000` 位换算。 |
| 上传/下载限速 | 两个方向独立设置；留空不限，同一设备的全部并发连接共享节点限速。 |
| 多节点 | 中央额度共享，不能在每个节点重复领取整份额度；速率按已授权节点固定分摊，不会自动把空闲节点份额借给忙碌节点。当前正式迁移仅台北。 |
| 服务端流量 | 网关实际写入的 TCP 应用数据，包含已结束的短连接；不是 TLS/IP 开销、整机网卡计数或 AWS 账单。 |
| 国内直连 | 不经过代理网关，不扣代理额度；后台不能可信地统计客户端直连总量。客户端直连/代理分类与本地历史仅用于使用量展示。 |

额度由服务端执行，修改客户端或清除本地历史不能解除限制。增加额度或恢复设备后仍须等待节点应用策略。月底旧月份信用立即失效，迟到的最终上报仍归属原月份，不转入新月。

## 策略生效与故障行为

公开管理 API 与节点内部接口分开。节点接口仅监听 `http://127.0.0.1:8788`，使用独立节点 Bearer 密钥及进程 epoch；不得把该 HTTP 接口开放到公网。管理员密钥不能替代节点密钥，测试网关也不能复用生产节点密钥。

网关使用 Go 标准库 TLS 与严格 Trojan TCP 协议解析。它每秒获取策略快照；连续 5 秒没有成功应用有效策略时停止授权连接，而不是继续使用无限期缓存权限。节点正常应用新策略并回传确认（ACK）后，后台才能显示已生效。

停用、删除、取消节点授权或调整设备策略会关闭**目标设备**的旧连接，重新连接时使用新策略；其他设备的连接和限速状态保持。保存操作成功但节点断联时，后台应保持“策略待生效”，不得声称撤销已经完成。

节点启动先占用监听端口，再注册新 epoch、应用有效快照，之后才接收客户端。占用端口失败不会使原进程失效；但使用相同节点密钥在另一个端口运行第二个网关会使原 epoch 失效，因此测试必须使用隔离的控制库和节点身份。

## 预留信用、待结算与异常余额

网关先从中央账本预留信用再转发，每次最多 4 MiB；剩余额度不足时只授予剩余部分。同一设备的并发连接共享信用，不会各自得到一份完整额度。

上报采用每个信用租约（lease）的绝对累计上传和下载计数，重复上报幂等；正常运行每秒上报，信用用尽或正常关闭时再完成结算。管理界面区分实际已上报流量、待结算预留和异常待核对，不能把预留字节直接显示为已使用字节。

节点崩溃、旧 epoch 被替代或最终上报失败时，无法确认是否已经转发的余额会被保守冻结，标为 abandoned/异常待核对：

- 不因超时、重启或跨月自动退款，也不假设缺测等于 0。
- 一次未结算租约至多 4 MiB；但连续重启可产生多笔冻结，不能承诺设备累计最多只损失 4 MiB 额度。
- 冻结额不是已转发的证据。不能把它补写为实际使用量，也不能无依据地释放后重新发放。
- 额度不足时，已使用量加预留/冻结会影响继续授信；后台实际已用数字小于额度，不一定代表剩余额度仍可使用。

这是试用版的保守控制方式，不等于完整财务计费或自动对账系统。发生异常时应保留账本和节点记录，核对具体租约与进程状态后再决定处理方式。

## 存储容量和维护要求

服务端账本使用 SQLite，查询累计量通过 SQL 聚合执行；所有历史租约保留，没有自动清理或压缩归档策略。不能为了释放空间而直接删除租约、设备删除标记或冻结记录，否则可能破坏去重、额度和审计依据。

离线样本估算：充分用满 4 MiB 的租约约需 **128–256 MiB 账本空间 / 1 TiB 转发量**，尚未包括备份与数据库日志。频繁短租约、空租约及重启产生的记录会显著增加单位流量存储开销，该估算不是容量上限。

本轮已知台北磁盘可用空间约 3.6 GB，这只是检查时的快照；实际余量以交付报告及后续检查为准。第一版在增加设备、流量或保留周期前必须检查文件系统可用空间、数据库与日志大小、备份占用及增长速度，不能承诺永不写满。备份应使用 SQLite 一致性备份机制，且与认证文件一样限制读取权限。

本文没有配置定时磁盘检查、自动扩容或通知任务；若需要自动监控，须另行明确安排。

## 部署阶段和回滚界限

初次管理迁移脚本为 `deployment/install-management.py`，仅用于当时已准备好的台北服务器，不可用于重做域名接入。域名上线后，nginx 监听 80/443，管理服务已迁到 loopback 8787；不得用旧模板重新抢占 443。它继续使用 `teamtunnel-catalog.service` 与 `teamtunnel-tunnel.service` 两个服务名，不操作原 Tailscale，不修改客户端路由、DNS 或其他 VPN。

| 阶段 | 允许的变化与判断依据 |
| --- | --- |
| Stage，默认不带 `--switch` | 校验目标、备份当前文件及数据库，在数据库副本上迁移并执行配置检查；不启动/停止生产服务，也不运行测试网关。 |
| Private validation，显式 `--switch` 后 | 停止两个 TeamTunnel 服务并取得停写快照，迁移实际库，新服务先仅监听回环地址；会短暂中断 TeamTunnel。公网提交前失败可恢复停写快照和旧服务单元。 |
| Public commit | 写入 `PUBLIC_COMMIT` 后再开放公网监听。此后可能已经产生新的激活、管理和流量写入，失败时不自动恢复旧数据库。 |
| Commit 后恢复 | 必须人工核对当前服务、数据库和新写入，制定保留数据的恢复方案；不能简单覆盖旧快照。脚本不提供通用的一键回滚。 |

部署脚本完成标记仅表示本机固定证书 TLS 和服务就绪检查通过，不能替代公网客户端、持续转发或限额验收。具体发布时间、实网用例、备份位置和遗留问题由本轮交付报告记录。

## 验收范围

代码测试、回环集成测试、真实公网测试和同事备用 Windows 测试是不同证据。交付时应分别列出已完成结果，重点核对：单独激活、目标设备禁用/删除切断旧连接、另一设备不断流、月额度耗尽/增加、并发上下行限速、重复上报、异常冻结、跨月、节点断联以及旧凭据兼容。

客户端仍以 IPv4 TCP 为当前范围，服务器严格拒绝 UDP 与 IPv6 目标；不能因浏览器或 Codex 可用就声称游戏、语音和所有 UDP 软件已经支持。原有 TUN、管理员授权及其他 VPN 冲突限制继续适用。
