私有化部署的在线文档服务,容器化跑在 Leon-Docker 节点(192.168.11.64:8090,Docs 9.4.0.129)。与 MemKV 记忆库深度联动:库里的 docx / xlsx / pptx / pdf 附件点开即编辑,保存实时回写——原来下载改完再上传覆盖、版本一多就乱的日子结束了。编辑器按 LZ-Studio 品牌全量定制,内置长图 / PDF 导出插件;招聘系统侧经同源反代跑通公网在线编辑,Playwright 实测正常渲染、回归 156/156 通过。
定位、难点、技术框架——30 秒建立全貌。
记忆库里沉淀了大量 docx / xlsx / pptx / pdf 附件。原来要看,先下载到本地,改完再上传覆盖——版本一多就乱,谁是最新的全靠猜。需求很直接:点开即编辑,保存即回写,全程不出内网。
本平台的做法:ONLYOFFICE Docs 容器化部署于 192.168.11.64:8090(版本 9.4.0.129,GET /healthcheck 自检为 true);招聘系统侧用「同源反代 + URL 改写 + JWT」让公网浏览器正常打开和保存,不动 DS 容器配置一行——DS 以为一切如常,浏览器以为全站同源。全程下来,DS 容器零改动,代价全收敛在招聘系统一侧。
数据怎么流,难点压在哪一层。
浏览器侧零私网地址;DS 回连走内网(源文件 token + 回调 token 双鉴权);回调只处理 status 2/6,其余直接回 error 0;Socket.IO 降级 HTTP 轮询可用,多人实时协同需另做 WS 透传。
插件 API 取不到文档地址,地址手填或复用最近记录,另选页码范围与 DPI;服务端密钥须成对配置,对不上结果下载 403。
欢迎页真身是 documentserver-example/welcome/docker.html;.gz 须与原文件同步(nginx gzip_static 优先);挂载权限统一 dir 755 / file 644,否则 ds 用户读到 403。
| 模块 | 职责 | 难点所在 |
|---|---|---|
| DS 容器 | 文档渲染与协作、私网下载放行 | JWT error 6、版本化资源 immutable 缓存 |
| oo-proxy | 同源转发、URL 改写、补丁注入 | 门禁放行、iframe 内部请求改写 |
| 回调保存 | token 与主机名校验、状态过滤、落盘 | 异常吞错防重试风暴 |
| helper 导出 | ConvertService 转码、分页渲染、拼长图 | 密钥对齐 403、插件无地址 API |
| brand 挂载 | 欢迎页、logo、标题与 tab 补丁 | 挂载权限 403、.gz 不同步 |
按已上线实现转写(招聘系统 main.py + 编辑页 document_view.html,流程与判定一一对应),按调用链排序:签名 → 反代 → 补丁 → 回调。
DS 要的是整包 HS256 签名:header 固定 {"alg":"HS256","typ":"JWT"} 再 base64url,JSON 分隔符必须是英文逗号冒号、无空格,密钥为服务端配置。生产联调时把能试的组合试了个遍——不对就是 {"error":6},签对当场回 error 0,泾渭分明。
# header / payload / 签名三段,全部 base64url 且去 "=" 补齐 def b64u(data: bytes) -> str: return base64.urlsafe_b64encode(data).decode().rstrip("=") def _oo_sign(cfg: dict, secret: str) -> str: header = b64u(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode()) payload = b64u(json.dumps(cfg, separators=(",", ":")).encode()) signing_input = f"{header}.{payload}" sig = b64u(hmac.new(secret.encode(), signing_input.encode(), hashlib.sha256).digest()) return f"{signing_input}.{sig}" # 被签名的是整包配置:文档四件套 + 编辑器四件套 cfg = {"document": {"fileType": ext, "key": view_key, "title": fname, "url": src_url}, "documentType": doc_type, # doc 系→word / xls 系→cell / ppt 系→slide "editorConfig": {"callbackUrl": cb_url, "mode": "edit", "lang": "zh-CN", "customization": {"autosave": True, "forcesave": False}}} token = _oo_sign(cfg, ONLYOFFICE_SECRET) # 密钥只存服务端
分隔符里多一个空格,签名即错 —— DS 只认 error 0。
FastAPI 里用 httpx 把 /oo-proxy/ 之后的一切原样转发给 DS:去 host / content-length / connection / accept-encoding 头,超时 120 秒,跟随跳转。回包分两类处理——文本回包(text / json / javascript / xml)把两个内网前缀全换成 /oo-proxy/,含 </head> 的再注入 C3 那份补丁;Location 头同理改写,其余字节原样回吐。
# 去 sensitive 头 + 120 秒超时 + 跟随跳转 STRIP_REQ = {"host", "content-length", "connection", "accept-encoding"} async def oo_proxy(path: str, request: Request): headers = {k: v for k, v in request.headers.items() if k.lower() not in STRIP_REQ} async with httpx.AsyncClient(follow_redirects=True) as client: resp = await client.request(request.method, f"{ONLYOFFICE_URL}/{path}", params=request.query_params, content=await request.body(), headers=headers, timeout=120) text = resp.text ctype = resp.headers.get("content-type", "") if ctype.startswith(("text/", "application/json", "application/javascript", "application/xml")): text = text.replace(ONLYOFFICE_URL, "/oo-proxy/") text = text.replace("http://192.168.11.64:8090", "/oo-proxy/") if "</head>" in text: # iframe 出生就带补丁 text = text.replace("</head>", MONKEY_PATCH + "</head>") return Response(text, headers=stripped(resp.headers))
远端缺 httpx 即 500 —— 先装依赖再重启,curl 健康接口确认。
补丁必须在 api.js 之前执行。第一层改 fetch(只动字符串入参)与 XMLHttpRequest.open;第二层 WebSocket 同理改写;第三层给 img / script / link / iframe / a 打 src/href setter 补丁,再加 MutationObserver 捕获动态加入的节点。父页一份、iframe 内一份——父页的补丁管不到 iframe 内部,这是 C2 要注入的全部理由。
(function () { var PREFIX = "http://192.168.11.64:8090"; var PROXY = "/oo-proxy"; function rewrite(u) { return (typeof u === "string" && u.indexOf(PREFIX) === 0) ? PROXY + u.slice(PREFIX.length) : u; } // fetch:只改字符串入参,Request 对象不动 var _fetch = window.fetch; window.fetch = function (input, init) { if (typeof input === "string") input = rewrite(input); return _fetch.call(this, input, init); }; // XHR:open 时改写 var _open = XMLHttpRequest.prototype.open; XMLHttpRequest.prototype.open = function (m, u) { arguments[1] = rewrite(u); return _open.apply(this, arguments); }; // WebSocket + setter 补丁 + MutationObserver(同模式) var _WS = window.WebSocket; window.WebSocket = function (u, p) { return new _WS(rewrite(u), p); }; })();
api.js 必须走同源 /oo-proxy/ 加载 —— 直引私网地址即被 more-private 拦截。
DS 调回调先验 token(不符回 403 {"error":1});读 JSON 的 status,只有 2(可保存)与 6(强制保存)才处理,其余直接回 error 0。再验回传 url 的主机名必须等于 DS 主机名(防止被指去别处),通过后把远端文件拉回 UPLOAD_DIR 覆盖同名文件,刷新 file_size / updated_at。异常一律吞掉但仍回 error 0——让 DS 反复重试,比丢一次保存贵得多。
async def oo_callback(did: int, token: str, req: Request): if token != expected_token(did): # token 不符 return {"error": 1} try: body = await req.json() if body.get("status") not in (2, 6): return {"error": 0} url = body["url"] assert urlparse(url).hostname == urlparse(ONLYOFFICE_URL).hostname pull_and_replace(url, did) # 覆盖 + 刷新元数据 except Exception: pass # 吞错,但仍回 0 return {"error": 0}
异常吞错是故意的 —— DS 重试风暴比一次丢保存更贵。
每条都是攻坚现场真实发生的:现象 → 根因 → 解法。密钥与口令只讲机制、不记值。
| 技术难点 | 现象与根因 | 解决法 |
|---|---|---|
| DS 报 error 6 | JWT 整包签名三处(header / 分隔符 / 密钥)错一处就拒收;联调时把能试的组合试了个遍,不对就是 {"error":6}。 | 三处逐项对齐,DS 回 error 0 方为通过;密钥只存服务端,页与库里都不记值。 |
| 代理 500 缺 httpx | 远端没装 httpx,反代一调就 ModuleNotFoundError: No module named 'httpx'。 | PEP-668 环境用带 --break-system-packages 的方式安装,重启后先过代理自检再谈别的。 |
| iframe 空白、回包是登录页 | 门禁中间件把 /oo-proxy/ 当陌生请求拦下,回包只有约 2.5KB、开头是登录页标题,编辑器 iframe 一片空白。 | SKIP_PREFIX 加上 /oo-proxy/;认准「2.5KB + 登录标题」这个体征,秒定位。 |
| CORS 与 more-private 报错 | 某层改写漏了,浏览器直连私网 IP,被 Private Network Access 策略拦截,Firefox / Chrome 表现一致。 | 按「反代改写 → 前端补丁」顺序排查;验收标准:发往 192.168.11.64 的请求数为 0。 |
| 品牌改了「没生效」 | 版本化 URL 带一年 immutable 缓存:633KB 真 logo、容器 md5 与宿主一致,浏览器就是不换——首次看到的版本粘住一年,普通 F5 点到手酸也没用。 | 硬刷 / 无痕 / 清站点数据;先排除缓存,再怀疑服务端。 |
| bind 挂载 403 | 挂载文件在容器内属 root、权限 0660/0600,nginx(ds 用户)读不到;sudo tee 逐文件创建会继承 umask 077 的坑。 | brand 下统一 dir 755 / file 644,别逐文件 sudo tee;权限实时生效无需重建。 |
| 大 base64 内联传输截断 | 多重 SSH 内联传大 base64 偶发截断,远端 gzip 报 stdin unexpected EOF,素材传一半。 | 素材改走文件中转站拉取;远端脚本变量本地展开,只转义真正的运行时变量。 |