先确认要维护哪一层 #
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 只提供文档内容。
同源部署与代理检查 #
- 在支持 CGO 的环境构建配套 Go 后端,准备 C 编译器和读取其依赖的权限。前端和后端按同一发布批次确认版本;仓库记录中的后端使用
lls v0.0.2。 - 本地开发环境使用 Vite 的
/api/lspWebSocket 代理。生产同源部署不指定VITE_LSP_WS_ORIGIN,由浏览器使用当前站点的地址。 - 在所有经过的代理层对
/api/lsp/开启 HTTP/1.1 升级,保留原始请求路径、Host、Origin 和 Cookie。确认规则优先于通用 API 代理和 SPA 的 HTML 回退。 - 检查上游可用性、TLS、长连接超时和负载均衡。示例适用于将原 URI 转给上游的 Nginx 或 OpenResty 站点,域名和端口应按环境修改。
- 对本项目的 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 域名的配置顺序 #
- 为专用子域设置 DNS,并为其签发有效的 TLS 证书。直接连接该子域时,应返回其自身的有效证书链。
- 在专用站的每层转发上应用同样的 WebSocket 升级规则。普通页面和 API 保留在原评测站。
- 后端将
HOJ_LSP_ALLOWED_ORIGIN设置为浏览器访问的评测站完整 Origin,例如https://www.example.com。协议、主机及非默认端口应匹配实际页面。 - 跨子域复用登录会话时,按架构设置
HOJ_JWT_COOKIE_DOMAIN,例如example.com。这个 Cookie 承载完整会话,父域下相关子域必须是可信且由站点控制的服务。启用后让存量账号重新登录验证新 Cookie 范围。 - 构建前端时设置
VITE_LSP_WS_ORIGIN=https://lsp.example.com并发布产物。该值只填写 Origin,末尾可保留根路径斜线。浏览器会拼接/api/lsp/<language>,HTTPS 页面使用加密的 WSS。 - 先用测试账号验证一次实际补全操作,再观察普通登录、打开试卷、题库提交和 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 正文按站点的数据访问规则处理。