5.2 KiB
opsx-vpn 部署与升级
本文件根据服务器上的 /home/ubuntu/depoly.md 整理；以代码仓库中的步骤为准，实际主机、端口、访问凭据和安全组规则按环境调整。不要将管理员密码、SQLite 数据库、data/secret.key 或实例私钥提交到仓库。
服务器准备
- Ubuntu 24.04；安装 Git、Go、Node.js、npm 和项目所需的协议软件包。运行 OpenVPN 专线还需要
openvpn、easy-rsa、iproute2与iptables。OIDC 专线要求 OpenVPN 2.6.2+，另需安装openvpn-auth-oauth2到PATH或data/bin/。 - 在 VPN 网关上开启 IPv4 转发，按实际启用的协议开放 VPN 数据端口。管理端
18080应仅供可信网络或 SSH 隧道访问。运行账户需要管理 TUN 和防火墙的权限。 - 服务在仓库目录运行；默认数据目录为
./data。data/保存数据库、加密密钥和各实例配置，升级时不得删除或覆盖。
首次构建与启动
git clone https://gitee.com/opsx-tools/opsx-vpn.git
cd opsx-vpn
cd frontend && npm ci && npm run build && cd ..
go build -ldflags="-s -w" -o opsx-vpn ./backend
sudo sh -c 'VPN_LISTEN_ADDR=:18080 setsid nohup ./opsx-vpn > /tmp/opsx-vpn.log 2>&1 < /dev/null &'
curl --fail http://127.0.0.1:18080/api/health
前端资源在构建 Go 二进制时内嵌，修改前端后须重新执行 两个构建步骤。首次登录请立即修改初始密码并启用适当的管理端保护。
在现有服务器上升级
先确认服务器工作树干净且仓库地址、分支符合预期。以下操作以 /home/ubuntu/opsx-vpn 和管理端口 18080 为例；升级前记录已有 VPN 实例进程与健康状态。
cd /home/ubuntu/opsx-vpn
git status --short
curl --fail http://127.0.0.1:18080/api/health
sudo cp -p opsx-vpn "opsx-vpn.bak-$(date +%Y%m%d-%H%M%S)"
git pull --ff-only origin master
cd frontend && npm run build && cd ..
go build -ldflags="-s -w" -o opsx-vpn.new ./backend
编译通过后，按监听端口核对管理程序 PID，精确停止该进程；不要停止仍在运行的 OpenVPN 实例。确认端口释放后替换并启动：
sudo ss -tlnp | grep ':18080'
# 确认 PID 确实属于 opsx-vpn 后：sudo kill <管理程序PID>
sudo mv opsx-vpn.new opsx-vpn
sudo chmod 755 opsx-vpn
sudo sh -c 'cd /home/ubuntu/opsx-vpn && VPN_LISTEN_ADDR=:18080 setsid nohup ./opsx-vpn > /tmp/opsx-vpn.log 2>&1 < /dev/null &'
curl --fail http://127.0.0.1:18080/api/health
sudo ss -tlnp | grep ':18080'
再检查页面静态资源、/tmp/opsx-vpn.log 和原有 VPN 实例状态。若新版本无法启动，停掉新管理进程，复制最近的 opsx-vpn.bak-* 到 opsx-vpn 并按上面的方式启动；如涉及数据模型变更，先依据对应变更的迁移说明处理数据库，不能直接覆盖 data/。
飞书 / OIDC 登录入口
http://121.4.111.208:18080 是当前管理界面示例，既不是 OIDC issuer，也不是 OAuth 回调地址。当前项目在 OpenVPN OIDC 配置中要求 oidc_issuer 和 oidc_base_url 均为 HTTPS。issuer 指向提供标准 OIDC discovery 和 ID Token 的身份提供方（飞书若不支持，需使用 Keycloak / Authentik 等身份代理）。
认证入口另设可供 VPN 客户端在连接前访问的 HTTPS 地址，例如 https://vpn-login.example.com。它可以与 opsx-vpn 管理后台部署在同一台服务器上：反向代理依据域名把管理站点送往 :18080，把认证站点的所有路径送往同机 127.0.0.1:19090（按专线配置调整）。两者是同一台服务器上的不同 Web 服务，并非管理后台不允许提供其他页面；当前实现由平台启动和管理认证组件，回调实际由 openvpn-auth-oauth2 处理。最终在 OIDC 身份提供方登记 https://vpn-login.example.com/oauth2/callback。不要把本地认证端口或 OpenVPN 管理 socket 暴露到公网。详见 接入说明。
该域名须由你控制并解析到反向代理公网地址。可以在已有反向代理面板申请 Let's Encrypt 免费证书：HTTP-01 需要公网 TCP 80 能访问验证路径 /.well-known/acme-challenge/，续期时也要保留该路径；443 为认证入口提供 HTTPS。无需上传已有证书，也无需在 opsx-vpn 内再开发证书申请功能。若代理与 VPN 主机分离，代理上的 127.0.0.1 指代理主机自身，应改用受限的私网地址，并评估认证流量在私网链路上的保护。
/.well-known/openid-configuration 属于发行者域名，不是认证入口上的 VPN 回调。不要只放行 /oauth2/callback：认证组件还需要发起登录等路由。认证入口使用独立域名，只反代给认证组件；如需按路径白名单返回 Nginx 444，须先核对实际安装版本的完整路由，并保障 HTTP-01 验证路径。认证端口默认 19090，仅监听回环；新增 OIDC 专线自动递增并跳过已配置或已监听的端口，仍以启动时冲突检测为准。
启用飞书认证前，需安装并验证 openvpn-auth-oauth2、准备身份提供方凭据、配置 HTTPS 反代，并用支持 WebAuth 的客户端联调。现有 LDAP 拨号用户不会自动绑定飞书用户。