LSP 部署与运维

配置 WebSocket、TLS、登录 Cookie 和 Redis,执行上线与续签验收。

本页目录

先确认要维护哪一层 #

LSP 是浏览器 Monaco 编辑器与 Go 后端之间的长连接服务。每个有权限且选了支持语言的编辑器独立走一次 WebSocket 握手,之后使用 JSON-RPC 交换初始化、文档打开、变更和语言功能请求。Go 后端通过 lls 分析当前文档,通过 Redis 协调连接额度。运行样例与提交评测走既有业务接口及判题机队列。

部署方式 页面和普通 API 编辑器连接
同源 评测站原域名 默认由页面协议转换成 WS 或 WSS,路径为 /api/lsp/<language>
独立子域 主站继续使用原域名和 CDN 前端按构建配置连接专用 WSS 域名,适合绕过不能稳定转发长连接的 CDN

YUOJ 公网部署采用第二种方式:评测站是 www.yuoj.top,语言服务用 lsp.yuoj.top 并通过 1Panel 与后续转发链路接入 Go 后端。文档域名 docs.yuoj.top 只提供文档内容。

同源部署与代理检查 #

  1. 在支持 CGO 的环境构建配套 Go 后端,准备 C 编译器和读取其依赖的权限。前端和后端按同一发布批次确认版本;仓库记录中的后端使用 lls v0.0.2。
  2. 本地开发环境使用 Vite 的 /api/lsp WebSocket 代理。生产同源部署不指定 VITE_LSP_WS_ORIGIN,由浏览器使用当前站点的地址。
  3. 在所有经过的代理层对 /api/lsp/ 开启 HTTP/1.1 升级,保留原始请求路径、Host、Origin 和 Cookie。确认规则优先于通用 API 代理和 SPA 的 HTML 回退。
  4. 检查上游可用性、TLS、长连接超时和负载均衡。示例适用于将原 URI 转给上游的 Nginx 或 OpenResty 站点,域名和端口应按环境修改。
  5. 对本项目的 HOJ 前端镜像,可将仓库 deploy/nginx/compose.lsp.yml 与原 Compose 配置共同应用,并设置 HOJ_LSP_NGINX_TEMPLATES_DIR 为模板目录的绝对路径。重建容器继续携带覆盖配置。
location ^~ /api/lsp/ {
    proxy_pass http://backend:6688;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_read_timeout 650s;
    proxy_send_timeout 650s;
    proxy_buffering off;
}

此示例沿用普通 Nginx 的原始 Cookie 和 Origin 转发。若外层代理另有缓存、请求头覆盖或限时规则,应逐层确认。代理允许长连接后,服务仍会按自身约 10 分钟的空闲策略结束无活动会话。

独立 WSS 域名的配置顺序 #

  1. 为专用子域设置 DNS,并为其签发有效的 TLS 证书。直接连接该子域时,应返回其自身的有效证书链。
  2. 在专用站的每层转发上应用同样的 WebSocket 升级规则。普通页面和 API 保留在原评测站。
  3. 后端将 HOJ_LSP_ALLOWED_ORIGIN 设置为浏览器访问的评测站完整 Origin,例如 https://www.example.com。协议、主机及非默认端口应匹配实际页面。
  4. 跨子域复用登录会话时,按架构设置 HOJ_JWT_COOKIE_DOMAIN,例如 example.com。这个 Cookie 承载完整会话,父域下相关子域必须是可信且由站点控制的服务。启用后让存量账号重新登录验证新 Cookie 范围。
  5. 构建前端时设置 VITE_LSP_WS_ORIGIN=https://lsp.example.com 并发布产物。该值只填写 Origin,末尾可保留根路径斜线。浏览器会拼接 /api/lsp/<language>,HTTPS 页面使用加密的 WSS。
  6. 先用测试账号验证一次实际补全操作,再观察普通登录、打开试卷、题库提交和 LSP 日志。若要回滚到同源,先确认原域名代理能承载 WebSocket,再回滚前端连接地址及与该部署匹配的认证配置。

更新 1Panel 证书时可先保留一条已有编辑器连接,执行配置检查并平滑重载,再另外开一个编辑器测试新握手。旧连接是否继续服务和新连接是否加载新证书,需要分别验证。

连接额度、Redis 和故障恢复 #

参数 当前规则
全站 / 同用户 50 / 5 条,由共享 Redis 原子检查
占用时点 握手升级前,初始化尚未完成也占用
续期与回收 每 5 秒续期。正常断开释放,异常退出按 30 秒租约回收
Redis 失联或额度状态不明 新连接可能被拒绝,无法确认租约的旧连接会关闭
保护窗口 Redis 实例代际变更或额度数据消失后,会等待一个租约周期再恢复准入

多实例必须使用同一权威 Redis 和数据库;遇到 Redis 恢复或切换,确认实例对同一主节点达成一致,再复测新建连接。单机部署可以使用 Redis 直连,多实例依据部署的高可用配置使用 Sentinel 等支持模式。ACL 需允许额度用到的 EVAL、INFO server、TIME 及相应键的读写。升级共享额度实现前,先排空并停止旧实例,避免新旧额度逻辑同时处理连接。

日常监控可分别看握手成功率、拒绝原因、现有连接数、Redis 可用性、重连频率、补全延迟和判题等待时间。排查时把同账号额度、全站额度、Redis 保护窗口分开核对。容量测试在隔离环境进行,连接数、源码长度、语言组合和判题负载都应接近实际使用。

检查握手与功能 #

在评测站登录一个测试账号。打开开发者工具的「网络 → WS」,保留请求列表,再打开题目并选择 C++17 或 Python 3。检查请求目标和响应,随后执行示例中的补全和重命名。成功建立连接还需通过 initialize 与当前文档的实际请求验证。

观察到的情况 核对点
登录后 101 Switching Protocols 协议升级完成。若无提示,检查初始化、当前文件及源码变更是否生效
未登录返回 401 符合认证要求。已登录仍为 401 时核对登录状态、Cookie 域和代理转发
403 核对 Origin 与后端允许值,再查看是否由边缘代理安全规则拒绝
400、426 或拿到 HTML 核对 Upgrade 请求头、HTTP/1.1、路由和 SPA 回退规则
404 核对编译语言对应的服务路由、代理转发路径,确认后端含相应语言端点
容量相关 503 先分别检查当前用户、全局额度和 Redis 健康及保护窗口
502、504 或 TLS 错误 检查证书、域名解析、上游健康及代理超时,先区分浏览器和源站的错误

发布与续签验收 #

  • 普通 API 请求正常,匿名访问语言服务被拒绝,登录后真实工作台可完成初始化与补全。使用独立测试账号观察退出后连接行为。
  • 同页选择当前语言时不新增连接。改选另一种受支持语言或不同 C++ 标准时,旧连接释放,新连接按新配置初始化。
  • 重开闲置编辑器可恢复补全和诊断。两个编辑器分别保留各自源码和请求结果。可在预发环境核对第 6 条单用户连接被拒绝,并在关闭多余编辑器后恢复。
  • TLS 证书更新后,检查外部握手实际返回的证书、域名和有效期,并从评测站新开编辑器实测。证书页面的签发成功、代理已重载、浏览器连接可用是三个检查点。
  • 日志和排障截图只保留时间、状态、语言及必要的连接事件。请求 Cookie、评测代码和 WebSocket 正文按站点的数据访问规则处理。

搜索文档