01 · HOW IT WORKS
先看懂 OpenVLAN 的组网原理
OpenVLAN 将“管理配置”和“传输流量”分开。控制台负责租户、网络、成员、注册码与签名配置；真正的业务流量通过 AmneziaWG 2.0 数据面传输，不绕行网页控制台。
用户 · 租户 · 签名配置 · 审计虚拟地址 10.20.0.1例如 10.20.0.0/24。同一网络内的终端获得唯一地址，不同租户相互隔离。
默认使用网络的 .1 地址，通过 Agent 验证并应用签名 Peer 配置。
Windows、Linux、OpenWrt 等设备从 .2 开始分配地址，私钥保留在本机。
02 · REAL WORLD EXAMPLE
天津和美国两台 Windows 电脑如何组网
真实终端只有天津和美国两台 Windows 电脑，它们通常都在路由器后面，没有独立公网 IP。当前技术预览版最稳妥的方案，是让两台电脑都主动连接一台具有公网 IP 的 Linux Hub；Hub 是网络中转基础设施，不是第三台用户电脑。
10.20.0.1 · UDP 5188810.20.0.2在 NAT 后主动连接 Hub10.20.0.3远程桌面/文件访问目标一台公网 Hub，两台 Windows 装客户端
适合“天津一台用户电脑、美国一台办公电脑”的真实场景。部署快、端口少、故障边界清晰。
- 只需 Hub 开放一个 UDP 端口
- 两台 Windows 电脑都不需要公网 IP
- 天津通过美国电脑的虚拟 IP 使用 RDP 或业务系统
再升级为美国分支网关
如果美国办公室以后有多台设备，不希望逐台安装客户端，再由分支路由器承载整个美国 LAN 网段。
- 当前只有一台美国电脑，无需部署分支网关
- 升级时需要规划不重复的 LAN 网段
- 多网关路由仍属于后续正式版本验收项
示例地址规划
10.20.0.1两台 Windows 的接入点10.20.0.2主动连接 Hub10.20.0.3天津通过虚拟 IP 访问因为主要目标是从天津访问美国办公电脑，优先选择美国或对中美 UDP 链路质量较好的公网 Linux 节点。最终位置应通过实际延迟、丢包、UDP 可用性和合规要求测试决定。
03 · BEFORE YOU START
准备工作
登录后可见“创建网络”按钮Ubuntu 22.04/24.04 或兼容发行版能够访问控制面 HTTPS推荐 10.20.0.0/24 等私网段timedatectl status当前官网已经开放控制台和 Linux 网关 Agent 能力；Windows 一键安装客户端与代码签名仍在商业发布验收阶段。演示环境可使用管理员预装的 Windows 测试客户端，不能把尚未签名的测试程序当作正式客户端分发。
04 · STEP BY STEP
完整组网操作演示
注册账号、登录并确认租户
访问 www.openvlan.com。新用户选择“注册新账号”，已有账号直接登录。
- 新用户填写组织名称、英文组织标识、姓名、邮箱和至少 12 位密码。
- 注册成功后系统自动创建独立租户，并把首个账号设为 Owner。
- 进入工作台后查看右上角“当前租户”；多租户账号先选择本次组网的租户。
- 工作台会显示网络、终端、网关和待确认配置数量。
正确结果工作台显示“网络控制面在线”，右上角能看到你的账号和租户。
创建虚拟网络
虚拟网络是所有网关和终端的地址分配边界。
- 左侧进入“虚拟网络”，点击“创建网络”。
- 网络名称填写业务含义，例如“总部与分支互联”。
- IPv4 CIDR 建议填写未使用的私网段，例如
10.20.0.0/24。 - 填写说明并保存。系统会检查同一租户内的 CIDR 是否重叠。
10.20.0.1 预留给主网关，第一台终端从 10.20.0.2 开始分配；网络地址和广播地址不会分配。
部署并注册 Linux 网关
网关承载 AWG 2.0 数据面，并通过受限 Agent 接收签名配置。
- 生成注册码：进入“网关节点”→“生成网关注册码”，选择承载网络。
- 填写网关信息：名称建议包含位置；区域例如
Tokyo；公网端点例如gateway.example.com:51888。 - 复制注册码：注册码只显示一次。不要粘贴到聊天群、工单或公开日志。
- 执行注册：在已安装 AWG 2.0 与 OpenVLAN Agent 的 Linux 网关上完成注册。
高级管理员查看技术预览版 API 注册示例
以下命令用于已获得 Agent 安装包的技术预览环境。请先安装 awg、curl 与 jq，并以 root 执行。
# 1. 在网关本地生成私钥和公钥
umask 077
awg genkey | tee /etc/openvlan/gateway.key | awg pubkey \
> /etc/openvlan/gateway.pub
# 2. 安全读取控制台生成的一次性注册码
read -rsp "粘贴网关注册码: " OPENVLAN_ENROLL_TOKEN; echo
GATEWAY_PUBLIC_KEY=$(cat /etc/openvlan/gateway.pub)
# 3. 向控制面登记网关
curl --fail --silent --show-error \
-H 'Content-Type: application/json' \
--data "$(jq -n --arg token "$OPENVLAN_ENROLL_TOKEN" \
--arg key "$GATEWAY_PUBLIC_KEY" \
'{token:$token,public_key:$key}')" \
https://api.openvlan.com/v1/enroll/gateway
unset OPENVLAN_ENROLL_TOKEN返回的 agent_token 和 config_signing.public_key 只应写入网关受限配置文件，不要输出到日志。Agent 必须先以 observe 验证，再经授权切换为 apply。
添加 Windows 终端
每台设备使用独立身份和独立密钥，不要多人共用同一个注册码。
- 进入“终端设备”，点击“生成设备注册码”。
- 选择刚创建的虚拟网络。
- 设备名称建议包含用户或资产编号，例如
sales-laptop-01。 - 平台选择 Windows，点击“生成”。
- 在管理员提供的 OpenVLAN 测试客户端中输入注册码并完成注册。
- 回到控制台刷新，设备应显示为
active并获得虚拟地址。
设备必须在本机生成 AWG 密钥。控制面只接收公钥，永远不需要你上传私钥。
••••••••••••••••剩余 09:42分配 10.20.0.2- ✓ 注册码使用后失效
- ✓ 私钥不离开设备
- ✓ 地址由控制面事务分配
在组网拓扑中确认状态
拓扑页把数据库记录、网关确认状态和终端地址放到同一张图中。
10.20.0.0/24网关数量正确至少有一个活动网关
状态为 applied说明配置已真实应用
终端状态 active设备没有被撤销
地址不重复每台终端拥有唯一 /32
04 · VERIFY
验证终端是否真正互通
控制台显示正常只是配置层面的结果，还要从终端发送真实数据包，才能完成端到端验收。
# 测试到网关
ping 10.20.0.1
# 测试到另一台终端
ping 10.20.0.3
# 查看路径
tracert 10.20.0.3# 查看 AWG 接口
awg show ovawg0
# 测试两台终端
ping -c 4 10.20.0.2
ping -c 4 10.20.0.3基础验收标准
- ✓网关与终端存在最近握手
- ✓网关配置状态为 applied
- ✓双向 Ping 无持续丢包
- ✓重启客户端后能够自动恢复
- ✓撤销设备后对应 Peer 被移除
- ✓审计日志能看到相关操作
05 · OPERATIONS
日常管理怎么做
设备离职或丢失
进入“终端设备”点击撤销。控制面生成新修订，网关应用后移除对应 Peer。
不要只卸载客户端邀请运维成员
进入“成员与权限”生成邀请，并按职责分配 Admin、Member 或 Viewer。
Owner 数量保持至少一人追踪配置变更
审计日志记录操作者、动作、结果、来源地址和时间，可用于排查误操作。
重点关注 failed 记录网关升级维护
先确认最后可用配置和备份，再升级 Agent；数据面与控制面独立，避免同时变更。
升级后重新验证 Peer06 · TROUBLESHOOTING
常见问题与排查顺序
01注册码提示无效或过期
一次性注册码默认 10 分钟失效，并且只能成功使用一次。
- 回到控制台重新生成注册码。
- 确认复制时没有前后空格或换行。
- 检查设备系统时间是否准确。
- 不要重复提交已经成功使用的注册码。
02网关一直显示 pending
说明 Agent 尚未确认当前配置修订。
- 检查
openvlan-gateway-agent.service是否运行。 - 确认网关能够访问
https://api.openvlan.com。 - 检查 Agent Token 和签名公钥是否写入受限配置。
- 查看 Agent 日志中的脱敏错误，不要把凭据粘贴到工单。
03状态是 observed，但终端不通
observed 只表示配置已经验签和观察，并不代表 Peer 已写入 AWG 接口。经授权切换 Agent 到 apply，成功后必须显示 applied。
04状态 applied，但 Ping 不通
- 确认客户端隧道已经启动。
- 检查系统防火墙是否允许 ICMP 或目标业务端口。
- 检查公网 UDP 端口是否开放。
- 确认虚拟网段没有与本地 LAN、其他 VPN 重叠。
- 检查握手时间、AllowedIPs 和 MTU。
05创建网络提示 CIDR 冲突
同一租户中的虚拟网络禁止重叠。改用未占用网段，例如从 10.20.0.0/24 调整为 10.21.0.0/24，同时避免和办公室 LAN 网段重复。
06浏览器提示会话失效
重新登录即可。OpenVLAN 会话保存在 Secure、HttpOnly、SameSite=Strict Cookie 中，不写入浏览器本地存储；修改密码后其他会话会被撤销。
07 · SECURITY
正式使用前的安全建议
网关和终端私钥只保存在本机受限目录，控制台只接收公钥。
通过端到端安全渠道发送；使用后立即失效，禁止写入脚本和日志。
日常查看使用 Viewer；只有必要成员拥有 Admin 或 Owner。
网关 Agent 应保存最后可用配置，应用核对失败时自动恢复。
检查 failed、撤销、权限调整和异常来源地址记录。
完成 72 小时稳定性、吞吐、MTU、重启恢复和容量验收。
READY TO CONNECT
现在可以开始创建第一张网络
登录控制台后，工作台会自动显示四步组网进度；遇到问题时按本页故障排查顺序检查。