核心概念
控制台里的每个词都对应一个具体的东西。这一页只说你需要知道的：它们是什么、谁拥有它、出问题时该看哪一个。
一、四个词
| 概念 | 它是什么 | 谁拥有 / 在哪 |
|---|---|---|
| 租户 | 一个隔离单元，也就是「一个客户」。成员、设备、Agent、审计日志都归属某个租户，租户之间互相看不见。 | 注册时创建，创建者自动成为该租户的管理员。 |
| 成员 | 使用控制台的人。角色有管理员与成员两类；成员用邮箱验证码登录，没有密码。 | 属于租户。成员可以添加自己的设备。 |
| 设备 | 要访问内网的那一端：笔记本、手机、平板。它使用官方 WireGuard 客户端，配置由控制台在浏览器本地生成后扫码导入。 | 属于某个成员。密钥对在你的浏览器里生成，只有公钥会上传。 |
| Agent | 装在内网机器上的服务。它是控制面伸进你内网的那只手：接受并校验控制面下发的签名指令，把它们落到本地 WireGuard 上，再把状态报回去。 | 属于租户，跑在你的机器上。 |
Agent 与 wg-server 通常在同一台机器上。Agent 负责「听指令、改配置、报状态」，真正承载隧道的是那台机器上的 WireGuard。你把 Agent 装在别处也没问题，只要它能管理到 wg-server。
二、状态是什么意思
两类状态容易混淆，分开看：
设备（你批准的那一端）
- 待批准：公钥已提交，但还没有一条由你签名的授权。这个状态下设备连不上任何东西。
- 已激活：已授权。设备是否能真的连上，还要看 Agent 在线、端点可达。
- 已吊销：授权被撤销。Agent 在下一次状态同步内应用变更并断开该设备。
Agent（内网那一端）
- 注册中：已完成首次注册，正在建立稳定连接。
- 在线 / 离线：Agent 会周期性上报状态（默认 30 秒一次），因此「离线」意味着这段时间内没有收到它的上报——不是我们「检测到它在做别的事」。
- 已吊销：该 Agent 的资格被撤销。
三、两种远端访问模式
两种模式的差别只在「设备怎么知道该连哪个地址」，数据面在两种模式下都是设备与 wg-server 之间的 WireGuard 直连，都不经过我们。
打洞辅助（默认）
适合公网 IP 会变的场景。你在路由器上把 wg-server 的 UDP 端口映射到内网主机，然后 Agent 主动向端点发现服务发一个探测包，服务把从它那一侧观察到的源公网地址回送回来——仅此而已。Agent 把「公网地址 + 本机端口」作为可达端点上报，设备据此直连，公网 IP 变了也不需要你改任何配置。
端点发现服务不解析、不缓存、不转发任何 WireGuard 报文，也不保留会话状态。它看到的元数据范围，逐条列在隐私政策里。
直连
适合已经有稳定公网地址的场景（固定公网 IP、自建多入口等）。你直接告诉控制面 wg-server 的公网地址，不经过端点发现。少一个环节，也就少一份需要解释的元数据。
两种模式都不会替你穿透网络。如果只有对称 NAT、并且你没有做端口映射，那就没有任何设备能直达的端点，连接建立不起来：设备端会明确说「当前网络环境暂不支持」。我们不提供流量转发兜底，也不会承诺「不需要公网 IP、不需要端口映射、任何网络都能穿透」。
四、授权为什么必须由你签名
批准一台设备，本质上是你签一条授权，而不是「我们在数据库里把某个字段改成 true」。
- 你第一次进控制台时，浏览器在本地生成一对授权密钥；私钥留在浏览器里，只有公钥会上传。
- 批准与吊销都由这把私钥签名。我们只验签，不发签——即使我们的数据库整体失守，攻击者也无法凭空造出一条「把某台设备接进你的内网」的授权。
- 每条授权都有有效期，吊销同样需要签名，所以被吊销的设备也不能被「复活」。
- 开启高安全模式后，批准前还需要把设备端展示的指纹逐段核对一致。
代价是明确的：私钥丢了就没了，我们找不回来；换设备要重新添加一次。
五、一条指令的一生
- 你在控制台做一个动作。需要签名的那些——批准设备、吊销设备、冻结或解冻租户——会走下面这条链路；而成员管理、接入模式这类租户设置不需要签名，它们由你的登录会话直接改，因为它们本身不构成一条「接入授权」。
- 控制面把它变成一条带签名的指令，带着唯一的指令编号下发。重复下发同一条指令不会产生第二次副作用。
- Agent 收到后先验证签名与格式，不合法就拒绝并如实上报——不猜测、不「尽力而为」。
- 验证通过才落到本地 WireGuard，然后把执行结果与设备状态报回控制面。
- 控制台显示的是 Agent 的回报，不是我们的猜测。所以「指令已下发」和「已经生效」在界面上是两个不同的东西。
这也是为什么吊销之后要等一下：生效时间取决于 Agent 的同步周期，默认 30 秒内。
管理员还可以冻结整个租户：Agent 收到后进入冻结态，切断现有路由、只放行解冻指令；恢复需要一条新的签名解冻指令，不支持自助恢复。
六、审计记录了什么
控制面的操作会留下审计记录：时间、操作者、操作类型、资源、结果、来源地址。例如「某管理员批准了某设备」「某管理员切换了接入模式」。
审计里没有业务数据，也没有私钥。它不是流量日志——我们本来就不在业务流量的路径上。租户可以导出审计记录。