● 由 Leon 开发 · ONLYOFFICE Docs · Docker · JWT · Nginx 反代

OnlyOffice 在线文档服务

私有化部署的在线文档服务,容器化跑在 Leon-Docker 节点(192.168.11.64:8090,Docs 9.4.0.129)。与 MemKV 记忆库深度联动:库里的 docx / xlsx / pptx / pdf 附件点开即编辑,保存实时回写——原来下载改完再上传覆盖、版本一多就乱的日子结束了。编辑器按 LZ-Studio 品牌全量定制,内置长图 / PDF 导出插件;招聘系统侧经同源反代跑通公网在线编辑,Playwright 实测正常渲染、回归 156/156 通过。

全格式在线编辑MemKV 联动回写LZ-Studio 品牌定制长图 · PDF 一键导出私有化部署公网可用链路
自上而下通读即可
01 / 概括

把文档编辑,装进自己的机房

定位、难点、技术框架——30 秒建立全貌。

定位记忆库的附件,要点开就能改

记忆库里沉淀了大量 docx / xlsx / pptx / pdf 附件。原来要看,先下载到本地,改完再上传覆盖——版本一多就乱,谁是最新的全靠猜。需求很直接:点开即编辑,保存即回写,全程不出内网。

本平台的做法:ONLYOFFICE Docs 容器化部署于 192.168.11.64:8090(版本 9.4.0.129,GET /healthcheck 自检为 true);招聘系统侧用「同源反代 + URL 改写 + JWT」让公网浏览器正常打开和保存,不动 DS 容器配置一行——DS 以为一切如常,浏览器以为全站同源。全程下来,DS 容器零改动,代价全收敛在招聘系统一侧。

难点五个真问题

框架技术栈与运行形态

编辑核心
ONLYOFFICE Docs 9.4.0.129 · Docker 容器(Leon-Docker 192.168.11.64:8090,GET /healthcheck 自检)
联动层
FastAPI + SQLite + Jinja2(招聘系统 5101)· httpx 同源反代 /oo-proxy/ · JWT HS256 整包签名
导出
leon-office-helper(127.0.0.1:8091,共享 DS 网络命名空间)· ConvertService → PyMuPDF 150dpi → Pillow 纵向拼接
品牌
LZ-Studio 全量定制(欢迎页 / header logo / favicon / 编辑页标题与浏览器 tab)
鉴权
view_key 唯一文档钥 + 源文件 / 回调双 token;回调验 token、验主机名,只处理 status 2/6
数据
文档存 UPLOAD_DIR 同名覆盖,file_size / updated_at 随保存刷新
部署
/vol1/1000/Leon-Office/(compose / local.json / nginx / plugins / helper / brand 只读挂载)
02 / 架构

三条链路,各守一个硬约束

数据怎么流,难点压在哪一层。

链路 A在线编辑:浏览器 → 同源反代 → DS → 回连落盘

公网浏览器
只访问同源地址
→ /oo-proxy/ 反代
httpx 转发 · URL 改写 · 注入补丁
→ DS :8090
文档渲染 / 协作
→ DS 回连拉源 / 调回调
内网直达 · token 鉴权
→ 回写落盘

浏览器侧零私网地址;DS 回连走内网(源文件 token + 回调 token 双鉴权);回调只处理 status 2/6,其余直接回 error 0;Socket.IO 降级 HTTP 轮询可用,多人实时协同需另做 WS 透传。

链路 B导出:插件 → helper → ConvertService → 成品

编辑器插件
Leon 长图/PDF 导出
→ /leon-helper/
nginx 反代 · POST /api/convert
→ ConvertService
docx → pdf 直出
→ PDF / 纵向长图 PNG

插件 API 取不到文档地址,地址手填或复用最近记录,另选页码范围与 DPI;服务端密钥须成对配置,对不上结果下载 403。

链路 C品牌:brand/ → 只读挂载 → 重建生效

brand/ 素材
欢迎页 · logo · favicon · 补丁
→ 30+ 条 :ro 挂载
覆盖容器内对应路径
→ 容器重建
--force-recreate 即换

欢迎页真身是 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 不同步
03 / 代码

四段核心代码

按已上线实现转写(招聘系统 main.py + 编辑页 document_view.html,流程与判定一一对应),按调用链排序:签名 → 反代 → 补丁 → 回调。

C1JWT 整包签名:三处错一处,DS 就报 error 6

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。

C2同源反代:转发、改写、注入,一次完成

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 健康接口确认。

C3前端猴补丁:三层防线,缺一不可

补丁必须在 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 拦截。

C4回调保存:验 token、验主机、只收 2 和 6

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 重试风暴比一次丢保存更贵。

04 / 优化

主要优化

每条都是攻坚现场真实发生的:现象 → 根因 → 解法。密钥与口令只讲机制、不记值。

技术难点现象与根因解决法
DS 报 error 6JWT 整包签名三处(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,素材传一半。素材改走文件中转站拉取;远端脚本变量本地展开,只转义真正的运行时变量。
📖 说明书📐 说明文档🕘 日志