37 lines
3.4 KiB
Markdown
37 lines
3.4 KiB
Markdown
# 通过管理 API 创建 WireGuard 专线
|
||
|
||
当前后端已经提供 `POST /api/tunnels`，管理后台的“创建专线”向导也调用这个接口；只有 `admin` / `operator` 管理会话有权创建。该接口用于**管理员配置网关**，桌面客户端不能持有管理令牌或直接调用它。创建专线不等于完成终端用户认证、设备授权或桌面拨号。
|
||
|
||
## 已创建的停止状态测试专线
|
||
|
||
2026-10-21 经用户明确授权，通过 SSH 登录服务器本机管理 API，按下列请求创建测试专线 `opsx-client-pilot`（ID `4`）。创建后再次读取 API 确认 `state: stopped`、`auto_start: false`、监听端口 `51820`、公网端点 `121.4.111.208:51820`，并生成托管测试 Peer `client-1`（`10.88.0.2/32`）。只读系统检查显示 UDP `51820` 未监听、`10.88.0.0/24` 未进入路由表；**没有启动专线，也没有完成云安全组或真实客户端握手测试**。启用前需确认云安全组、业务网段路由和服务器网络策略。`allowed_ips` 只包含测试隧道网段，不会默认接管所有客户端流量。
|
||
|
||
```json
|
||
{
|
||
"name": "opsx-client-pilot",
|
||
"protocol": "wireguard",
|
||
"remark": "桌面客户端标准 WireGuard 测试专线",
|
||
"auto_start": false,
|
||
"config": {
|
||
"address": "10.88.0.1/24",
|
||
"client_address": "10.88.0.2/32",
|
||
"listen_port": 51820,
|
||
"public_endpoint": "121.4.111.208:51820",
|
||
"allowed_ips": "10.88.0.0/24",
|
||
"dns": "223.5.5.5",
|
||
"enable_nat": false,
|
||
"keepalive": 25
|
||
}
|
||
}
|
||
```
|
||
|
||
`POST /api/tunnels` 成功返回专线记录（含 `id`、`state`）；设为 `auto_start: false` 时返回 `state: stopped`，不会启动网卡。响应含配置但不应含服务器私钥。失败会返回 `error`，例如地址不合法或端口被占用。服务端创建时会生成首个托管 Peer；这是管理端旧流程，下载的客户端配置包含服务端生成的私钥，**不得分发给未来的桌面设备自注册接口**。创建后公开配置中的旧 `client_address` 字段迁移到 `config.peers[0].client_address`，其值为 `10.88.0.2/32`。
|
||
|
||
## 认证、验证与启动边界
|
||
|
||
管理 API 登录使用 `POST /api/login`，请求体为 `username`、`password`、按配置需要的 `mfa_code`；返回的 Bearer token 在 `Authorization` 请求头中发送。只通过可信 HTTPS 或已明确授权的加密管理通道提交凭据，不把密码、token 写入仓库、客户端前端代码或命令示例。`http://121.4.111.208:18080` 是明文 HTTP，**不要向公网该地址发送管理员密码或 token**。
|
||
|
||
创建前，以管理账号调用 `GET /api/tunnels?protocol=wireguard` 核对既有配置与实际 UDP 端口，并检查网段、系统路由及公网 UDP 放行。创建后用 `GET /api/tunnels/:id` 确认 `state`、`public_endpoint` 和 Peer；需要启用时由管理员单独调用 `POST /api/tunnels/:id/start`，再检查 `GET /api/tunnels/:id/status`、系统 WireGuard 握手和业务路由。`POST /api/tunnels/:id/wireguard/peers` 也是 operator 以上权限，当前实现更新运行中 Peer 会停止再启动隧道，不适合作为桌面设备自动注册接口。
|
||
|
||
桌面客户端后续应使用单独的短期用户/设备令牌和客户端生成的公钥，通过专用 API 领取地址、网关公钥、端点与路由；服务器只追加对应 Peer 的公钥，不回传服务器或其他 Peer 的私钥。具体身份映射、撤销和在线更新设计见 [SDD-002](specs/SDD-002-desktop-wireguard-client.md)。
|