3.4 KiB
通过管理 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 只包含测试隧道网段，不会默认接管所有客户端流量。
{
"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。