1. 問題本質(zhì)這不是OnlyOffice的錯是反向代理鏈路上的“信任斷點”“OnlyOffice插件打開文檔時提示下載失敗”——這句話在運維群、開發(fā)論壇和客戶支持工單里高頻出現(xiàn)但絕大多數(shù)人第一反應(yīng)是去查OnlyOffice日志、重裝鏡像、甚至懷疑Java版本不兼容。我踩過三次這個坑最后一次是在給一家律所部署合同在線協(xié)同系統(tǒng)時整整兩天卡在這個報錯上最后發(fā)現(xiàn)根子根本不在OnlyOffice本身而藏在Nginx配置文件里一個被忽略的proxy_pass指令背后。核心關(guān)鍵詞OnlyOffice、docker、nginx、proxy_pass、nginx.conf已經(jīng)精準(zhǔn)鎖定了技術(shù)棧Docker容器化部署的OnlyOffice服務(wù)通過Nginx做反向代理對外暴露前端插件比如集成在Nextcloud、Seafile或自研系統(tǒng)里的OnlyOffice插件發(fā)起文檔加載請求結(jié)果卡在“下載失敗”。這個報錯表面看是前端無法獲取文檔內(nèi)容實則是Nginx在轉(zhuǎn)發(fā)請求過程中因缺少關(guān)鍵頭信息、超時設(shè)置不當(dāng)或SSL上下文丟失導(dǎo)致OnlyOffice后端服務(wù)拒絕響應(yīng)或返回空體empty body前端插件收不到有效數(shù)據(jù)流自然判定為“下載失敗”。這個問題之所以高頻且難排查是因為它橫跨三層前端插件的請求構(gòu)造、Nginx的代理行為、OnlyOffice容器的響應(yīng)邏輯。三者之間只靠HTTP協(xié)議溝通任何一層的微小偏差都會在最終呈現(xiàn)上表現(xiàn)為一句模糊的“下載失敗”。更麻煩的是Docker環(huán)境讓網(wǎng)絡(luò)拓?fù)渥兊秒[性——你看到的是http://office.example.com/這個域名但實際流量路徑可能是瀏覽器 → 公網(wǎng)Nginx負(fù)載均衡→ 內(nèi)網(wǎng)Nginx反向代理→ Docker Bridge網(wǎng)絡(luò) → OnlyOffice容器。每一跳都可能成為故障點。我試過最典型的誤判場景客戶說“OnlyOffice裝好了能進(jìn)管理后臺但插件打不開文檔”我立刻登錄容器docker exec -it onlyoffice /bin/bash用curl -v http://localhost:8000/healthcheck確認(rèn)服務(wù)健康再curl -v http://localhost:8000/coauthoring/CommandService.ashx測試命令通道一切正常。于是自信滿滿地告訴客戶“服務(wù)沒問題”結(jié)果一小時后對方發(fā)來截圖插件彈窗還是“下載失敗”。后來抓包才發(fā)現(xiàn)問題出在公網(wǎng)Nginx到內(nèi)網(wǎng)Nginx這一跳——公網(wǎng)Nginx把Host頭改成了onlyoffice.internal而內(nèi)網(wǎng)Nginx的proxy_pass指向http://onlyoffice:8000時沒帶Host頭OnlyOffice容器內(nèi)部的Java服務(wù)根據(jù)缺失的Host頭拒絕了這個“來源不明”的請求。整個過程沒有錯誤日志只有靜默的403響應(yīng)前端插件只能報“下載失敗”。所以解決這個問題的第一步不是重裝OnlyOffice而是把Nginx當(dāng)成“透明代理調(diào)試器”來用。你要清楚知道每一次proxy_pass轉(zhuǎn)發(fā)Nginx默認(rèn)會刪掉哪些頭會加上哪些頭超時時間是多少SSL證書鏈?zhǔn)欠裢暾麄鬟f這些細(xì)節(jié)全寫在nginx.conf里而不是OnlyOffice的default.json里。接下來我會帶你一層層拆解從Nginx配置的每個字符開始還原這個“下載失敗”背后的完整鏈路。2. 核心細(xì)節(jié)解析Nginx反向代理的5個致命配置陷阱很多工程師以為proxy_pass就是一條簡單的轉(zhuǎn)發(fā)指令就像水管接頭一樣擰緊就行。但在OnlyOffice這種對實時性、頭信息完整性、SSL上下文極度敏感的服務(wù)面前Nginx的默認(rèn)配置幾乎全是“陷阱”。我整理了生產(chǎn)環(huán)境中最常觸發(fā)“下載失敗”的5個配置點每一個都附帶真實日志證據(jù)和參數(shù)推導(dǎo)邏輯。2.1proxy_set_header Host $host丟失原始Host頭的隱形殺手OnlyOffice后端服務(wù)基于Java的DocumentServer在啟動時會讀取Host頭來構(gòu)建內(nèi)部回調(diào)URL。當(dāng)插件發(fā)起/coauthoring/ConvertService.ashx請求時OnlyOffice需要知道“用戶是從哪個域名訪問我的”以便生成正確的WebSocket連接地址、預(yù)簽名URL和回調(diào)路徑。如果Nginx轉(zhuǎn)發(fā)時沒顯式設(shè)置Host頭它會用proxy_pass后指定的上游地址如onlyoffice:8000作為Host值這會導(dǎo)致OnlyOffice認(rèn)為請求來自一個不存在的內(nèi)部域名直接拒絕處理。實操驗證在Nginx配置中注釋掉這一行# proxy_set_header Host $host;然后用curl模擬插件請求curl -H Host: office.example.com http://localhost:8080/coauthoring/ConvertService.ashx返回403 Forbidden日志里出現(xiàn)Invalid host header。加上后返回200 OKBody里有{error:1}這是正常響應(yīng)表示服務(wù)就緒。提示$host變量取自客戶端請求的Host頭比$http_host更安全因為它不包含端口避免了office.example.com:8080這種非法Host值。2.2proxy_buffering off大文檔流式傳輸?shù)谋剡x項OnlyOffice打開文檔時后端會先返回一個輕量級HTML頁面含JS加載器再通過AJAX或WebSocket拉取實際文檔內(nèi)容。這個過程涉及大量小包、長連接和分塊傳輸chunked encoding。Nginx默認(rèn)開啟proxy_buffering on會把上游響應(yīng)緩存到內(nèi)存或磁盤等整個響應(yīng)結(jié)束才發(fā)給客戶端。對于OnlyOffice這種“邊生成邊發(fā)送”的流式響應(yīng)緩沖會導(dǎo)致前端插件長時間收不到首字節(jié)TTFB觸發(fā)超時報“下載失敗”。參數(shù)計算依據(jù)OnlyOffice官方文檔明確要求proxy_buffering off。實測中一個20MB的Word文檔在buffering on時前端等待首字節(jié)超過15秒關(guān)閉后首字節(jié)在200ms內(nèi)到達(dá)。這是因為Nginx的默認(rèn)proxy_buffer_size是4kproxy_buffers是8×4k對于OnlyOffice動輒幾十KB的初始JS包緩沖區(qū)根本不夠用必須等待更多數(shù)據(jù)填滿緩沖區(qū)或超時。2.3proxy_read_timeout與proxy_send_timeoutWebSocket心跳的生死線OnlyOffice協(xié)作編輯依賴WebSocket長連接維持實時同步。Nginx默認(rèn)proxy_read_timeout是60秒意味著如果60秒內(nèi)上游沒發(fā)任何數(shù)據(jù)Nginx會主動斷開連接。而OnlyOffice的WebSocket心跳包間隔默認(rèn)是30秒看似安全。但實際網(wǎng)絡(luò)中存在NAT超時、防火墻策略、中間設(shè)備干擾心跳包可能延遲。一旦Nginx在第61秒斷開OnlyOffice前端JS會收到WebSocket is closed before the connection is established插件立即報“下載失敗”。經(jīng)驗公式proxy_read_timeout應(yīng)設(shè)為WebSocket心跳間隔的3倍以上。OnlyOffice默認(rèn)心跳30秒所以至少設(shè)為90秒。同理proxy_send_timeout也要同步加大避免Nginx在發(fā)送響應(yīng)時因短暫阻塞而斷連。我在金融客戶環(huán)境里因read_timeout設(shè)為60秒導(dǎo)致交易合同編輯時每5分鐘斷連一次最終調(diào)到120秒徹底解決。2.4proxy_http_version 1.1與proxy_set_header Upgrade $http_upgradeWebSocket握手的通行證這是最容易被忽略的“協(xié)議級”配置。WebSocket升級請求Upgrade: websocket必須走HTTP/1.1且需要Nginx透傳Upgrade和Connection頭。默認(rèn)Nginx用HTTP/1.0代理會丟棄這些頭導(dǎo)致OnlyOffice后端收不到升級請求返回普通HTTP響應(yīng)前端插件無法建立WebSocket后續(xù)所有協(xié)作功能失效表現(xiàn)為“文檔打開后無法編輯”最終歸結(jié)為“下載失敗”。驗證方法用瀏覽器開發(fā)者工具Network面板過濾ws://看WebSocket連接狀態(tài)。如果顯示Failed to load resource: net::ERR_CONNECTION_REFUSED大概率是這里沒配。檢查Nginx配置必須同時存在proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;2.5 SSL/TLS配置中的proxy_ssl_verify off自簽名證書的妥協(xié)方案很多團(tuán)隊用Lets Encrypt免費證書沒問題。但測試環(huán)境常用OpenSSL自簽證書或者用內(nèi)網(wǎng)CA頒發(fā)的證書。Nginx默認(rèn)開啟proxy_ssl_verify on會校驗上游OnlyOffice容器的SSL證書。如果證書不被Nginx信任比如自簽、域名不匹配Nginx會拒絕代理返回502 Bad Gateway前端插件同樣報“下載失敗”。安全權(quán)衡生產(chǎn)環(huán)境必須開proxy_ssl_verify on并配置正確proxy_ssl_trusted_certificate測試環(huán)境可臨時關(guān)掉proxy_ssl_verify off;但這只是臨時方案。真正做法是在Docker Compose里把內(nèi)網(wǎng)CA證書掛載進(jìn)OnlyOffice容器的/etc/ssl/certs/并重啟服務(wù)讓OnlyOffice用可信證書。我見過最坑的案例測試環(huán)境Nginx關(guān)了SSL驗證上線時忘了開結(jié)果生產(chǎn)環(huán)境證書鏈不全所有用戶打開文檔都失敗回滾花了3小時。3. 實操過程從零構(gòu)建一個抗“下載失敗”的NginxOnlyOffice代理鏈現(xiàn)在我們把前面分析的所有陷阱整合成一套可直接復(fù)制粘貼的、經(jīng)過12個客戶環(huán)境驗證的Nginx配置。這不是網(wǎng)上抄來的模板而是我根據(jù)Docker網(wǎng)絡(luò)模型、OnlyOffice源碼邏輯和Nginx官方文檔逐行推演出來的最小可行配置。整個過程分為四步環(huán)境準(zhǔn)備、Docker部署、Nginx配置、聯(lián)調(diào)驗證。每一步都附帶命令、參數(shù)解釋和避坑心得。3.1 環(huán)境準(zhǔn)備明確網(wǎng)絡(luò)拓?fù)浔苊釪ocker網(wǎng)絡(luò)幻覺很多人失敗是因為沒搞清Docker的網(wǎng)絡(luò)模式。OnlyOffice官方鏡像onlyoffice/documentserver默認(rèn)監(jiān)聽0.0.0.0:8000但它在Docker里運行時有三種常見網(wǎng)絡(luò)模式bridge模式默認(rèn)容器獲得獨立IP如172.17.0.2通過Docker網(wǎng)橋與宿主機通信。Nginx在宿主機上proxy_pass必須指向這個容器IP或Docker服務(wù)名。host模式容器共享宿主機網(wǎng)絡(luò)proxy_pass http://localhost:8000即可。但會沖突宿主機端口不推薦。自定義網(wǎng)絡(luò)用docker network create onlyoffice-net創(chuàng)建然后docker run --network onlyoffice-net。這是最佳實踐因為可以固定服務(wù)名。我的選擇與理由用自定義網(wǎng)絡(luò)服務(wù)名。因為proxy_pass http://onlyoffice:8000比寫死IP更穩(wěn)定IP可能變服務(wù)名不會。而且Docker DNS會自動解析onlyoffice為容器IP無需額外配置。實操命令# 創(chuàng)建專用網(wǎng)絡(luò) docker network create onlyoffice-net # 啟動OnlyOffice容器加入網(wǎng)絡(luò)并暴露8000端口僅限內(nèi)部通信 docker run -i -t -d -p 8000:8000 \ --network onlyoffice-net \ --name onlyoffice \ -v /app/onlyoffice/logs:/var/log/onlyoffice \ -v /app/onlyoffice/data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/lib:/var/www/onlyoffice/DocumentServerData \ onlyoffice/documentserver注意這里沒映射80端口因為Nginx要接管所有外部流量。-p 8000:8000只是為了方便調(diào)試正式環(huán)境可去掉。3.2 Nginx配置一份可直接上線的nginx.conf詳解這是全文最核心的部分。我把所有關(guān)鍵配置濃縮在一個server塊里每行都加了注釋說明為什么這么寫以及不這么寫的后果。你可以直接保存為/etc/nginx/conf.d/onlyoffice.conf。upstream onlyoffice_backend { server onlyoffice:8000; # 指向Docker服務(wù)名非localhost } server { listen 80; server_name office.example.com; # 替換為你的域名 # 強制HTTPS重定向生產(chǎn)必備 return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name office.example.com; # SSL證書用certbot自動生成 ssl_certificate /etc/letsencrypt/live/office.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem; # SSL優(yōu)化提升TLS握手速度 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers off; # 關(guān)鍵反向代理通用設(shè)置 proxy_set_header Host $host; # 陷阱1必須透傳Host proxy_set_header X-Real-IP $remote_addr; # 透傳真實IP日志分析用 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 告訴OnlyOffice當(dāng)前是HTTPS # 關(guān)鍵OnlyOffice專用設(shè)置 proxy_http_version 1.1; # 陷阱4必須HTTP/1.1 proxy_set_header Upgrade $http_upgrade; # 透傳Upgrade頭 proxy_set_header Connection upgrade; # 透傳Connection頭 # 關(guān)鍵超時設(shè)置陷阱3 proxy_read_timeout 3600; # 1小時覆蓋WebSocket心跳 proxy_send_timeout 3600; proxy_connect_timeout 30; # 關(guān)鍵緩沖設(shè)置陷阱2 proxy_buffering off; # 必須關(guān)閉支持流式傳輸 proxy_buffer_size 128k; # 單個緩沖區(qū)大小 proxy_buffers 4 256k; # 總共4個緩沖區(qū)每個256k proxy_busy_buffers_size 256k; # 關(guān)鍵SSL上游設(shè)置陷阱5 proxy_ssl_verify on; # 生產(chǎn)必須開啟 proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; # 信任系統(tǒng)CA proxy_ssl_verify_depth 2; # 證書鏈深度 # 靜態(tài)資源直通提升性能 location ~ ^/(?:styles|js|images|fonts|favicon.ico) { proxy_pass http://onlyoffice_backend; expires 1y; add_header Cache-Control public, immutable; } # API和協(xié)作核心路徑 location / { proxy_pass http://onlyoffice_backend; # 所有關(guān)鍵proxy_*指令已在此server塊頂部統(tǒng)一設(shè)置無需重復(fù) } # WebSocket專用路徑增強健壯性 location /coauthoring/ { proxy_pass http://onlyoffice_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 健康檢查路徑供監(jiān)控系統(tǒng)調(diào)用 location /healthcheck { proxy_pass http://onlyoffice_backend; proxy_cache_bypass $http_upgrade; } }為什么這樣寫逐行解釋upstream onlyoffice_backend定義上游服務(wù)組便于擴展未來加多臺OnlyOffice可在這里加server。proxy_set_header X-Forwarded-Proto $schemeOnlyOffice需要知道原始請求是HTTP還是HTTPS否則生成的回調(diào)URL會是http://導(dǎo)致混合內(nèi)容錯誤。proxy_buffer_size 128kOnlyOffice初始HTML包約80KB128k足夠避免頻繁分配內(nèi)存。proxy_ssl_trusted_certificate指向系統(tǒng)CA證書包確保Nginx能驗證OnlyOffice的SSL證書如果OnlyOffice用了自簽證書需把CA.crt追加到此文件末尾。location /coauthoring/單獨配置因為這是WebSocket和協(xié)作API的核心路徑單獨強化能避免其他location規(guī)則干擾。3.3 聯(lián)調(diào)驗證用5個命令定位90%的問題配置寫完不是終點必須用命令逐層驗證。我總結(jié)了一套“五步驗證法”每步對應(yīng)一個命令覆蓋從DNS到OnlyOffice服務(wù)的全鏈路。第一步驗證DNS和Nginx監(jiān)聽# 檢查Nginx是否監(jiān)聽443端口 sudo ss -tlnp | grep :443 # 檢查域名解析是否正確指向本機 dig short office.example.com如果ss沒輸出說明Nginx沒啟動或配置語法錯誤dig返回空說明DNS沒配好。第二步驗證Nginx到OnlyOffice容器的連通性# 在Nginx宿主機上用curl直連容器服務(wù)名 curl -v -k https://onlyoffice:8000/healthcheck注意用-k忽略SSL證書錯誤因為容器內(nèi)是HTTP。如果返回{status:ok}說明網(wǎng)絡(luò)和Docker DNS正常如果報Could not resolve host: onlyoffice說明容器沒在onlyoffice-net網(wǎng)絡(luò)里或服務(wù)名不對。第三步驗證Nginx代理是否工作# 用curl模擬外部請求帶Host頭 curl -v -k -H Host: office.example.com https://127.0.0.1/healthcheck如果返回200 OK和{status:ok}說明Nginx代理鏈路通如果返回502 Bad Gateway檢查proxy_pass地址和upstream配置如果返回503 Service Temporarily Unavailable檢查upstream里server是否健康。第四步驗證WebSocket握手# 用wscat測試WebSocket需npm install -g wscat wscat -c wss://office.example.com/coauthoring/CommandService.ashx -H Origin: https://office.example.com如果連接成功并保持說明Upgrade頭透傳正確如果報Error: unexpected server response (400)檢查proxy_http_version和Connection頭。第五步驗證前端插件真實請求# 抓取瀏覽器發(fā)出的實際請求用Chrome DevTools Network面板 # 過濾XHR找/coauthoring/ConvertService.ashx請求 # 看Response Headers里是否有X-Proxy-Cache: MISS說明Nginx沒緩存直通OnlyOffice # 看Response Body是否為空空則OnlyOffice沒返回數(shù)據(jù)問題在OnlyOffice或上游3.4 Docker Compose一鍵部署整合所有組件為了徹底消滅手動配置的誤差我提供了一個完整的docker-compose.yml把Nginx和OnlyOffice打包在一起用Docker原生網(wǎng)絡(luò)管理避免宿主機Nginx配置的復(fù)雜性。這個方案適合中小團(tuán)隊快速落地。version: 3.8 services: nginx: image: nginx:alpine ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro - ./logs:/var/log/nginx depends_on: - onlyoffice networks: - onlyoffice-net onlyoffice: image: onlyoffice/documentserver:latest volumes: - ./logs:/var/log/onlyoffice - ./data:/var/www/onlyoffice/Data - ./lib:/var/www/onlyoffice/DocumentServerData networks: - onlyoffice-net # 關(guān)鍵禁用OnlyOffice內(nèi)置Nginx讓它只跑Java服務(wù) command: /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf networks: onlyoffice-net: driver: bridge關(guān)鍵點說明command覆蓋了OnlyOffice默認(rèn)啟動方式讓它只運行Java DocumentServer不啟動內(nèi)置Nginx避免端口沖突。volumes把配置和日志掛載出來方便修改和排查。depends_on確保OnlyOffice先啟動Nginx后啟動避免Nginx啟動時報upstream host not found。啟動命令docker-compose up -d。然后訪問https://office.example.com應(yīng)該能看到OnlyOffice歡迎頁。再集成插件就不會再報“下載失敗”了。4. 常見問題與排查技巧實錄那些讓我凌晨三點還在敲命令的坑即使你嚴(yán)格按照上面的配置做了依然可能遇到一些“玄學(xué)”問題。這些不是配置錯誤而是環(huán)境特異性導(dǎo)致的邊緣case。我把過去兩年幫客戶處理的27個真實案例濃縮成一張速查表并附上獨家排查技巧。這些技巧官方文檔里找不到只有在生產(chǎn)環(huán)境反復(fù)摔打才能總結(jié)出來。4.1 “下載失敗”但Nginx日志全是200時間不同步的幽靈現(xiàn)象Nginx access.log里所有請求都是200error.log空空如也但前端插件就是報“下載失敗”。用curl測試/healthcheck也返回200。根因OnlyOffice Java服務(wù)對系統(tǒng)時間極其敏感。它的JWT令牌、預(yù)簽名URL都有嚴(yán)格時效默認(rèn)5分鐘。如果宿主機時間比NTP服務(wù)器快/慢超過3分鐘OnlyOffice生成的令牌會被前端JS認(rèn)為已過期拒絕使用導(dǎo)致整個加載流程中斷。排查命令# 檢查宿主機時間 date # 檢查是否同步NTP timedatectl status # 檢查OnlyOffice容器內(nèi)時間 docker exec onlyoffice date解決方案宿主機執(zhí)行sudo timedatectl set-ntp true啟用NTP。如果是Docker Desktop for Windows/Mac檢查其虛擬機時間是否同步Windows上右鍵任務(wù)欄時間→調(diào)整日期和時間→Internet時間→立即更新。我遇到最離譜的一次客戶用VMware克隆了一臺服務(wù)器克隆后虛擬機時間沒重置比真實時間快了17分鐘OnlyOffice所有JWT都失效折騰了6小時才發(fā)現(xiàn)。4.2 插件打開文檔后白屏控制臺報Mixed ContentHTTPS混合內(nèi)容攔截現(xiàn)象文檔頁面加載出空白瀏覽器控制臺報Mixed Content: The page at https://... was loaded over HTTPS, but requested an insecure script http://...。根因OnlyOffice后端生成的HTML里硬編碼了http://開頭的JS/CSS鏈接。這是因為Nginx沒正確透傳X-Forwarded-Proto頭OnlyOffice誤以為自己跑在HTTP上。驗證方法在瀏覽器打開https://office.example.com查看頁面源碼搜索script srchttp://。如果存在就是這個問題。修復(fù)配置在Nginx的server塊里確保有proxy_set_header X-Forwarded-Proto $scheme;并且OnlyOffice容器的/etc/onlyoffice/documentserver/default.json里services.CoAuthoring.server.ssl.enable設(shè)為trueDocker鏡像默認(rèn)已設(shè)。4.3 只有大文檔失敗小文檔正常Nginx client_max_body_size限制現(xiàn)象打開1MB的Word文檔成功打開10MB的Excel就報“下載失敗”Nginx error.log里有client intended to send too large body。根因Nginx默認(rèn)client_max_body_size是1M而OnlyOffice上傳文檔時會先POST到/upload接口。如果文檔大于1MNginx直接拒絕返回413 Request Entity Too Large前端插件捕獲不到這個錯誤統(tǒng)一報“下載失敗”。解決方案在Nginxserver塊里添加client_max_body_size 100m; # 根據(jù)業(yè)務(wù)需求調(diào)整建議100M起步4.4 多語言切換后“下載失敗”Nginx緩存了語言包現(xiàn)象OnlyOffice界面語言切換后新語言的JS文件加載失敗控制臺報404最終導(dǎo)致文檔加載失敗。根因Nginx的location ~ ^/(?:styles|js|images|fonts|favicon.ico)緩存規(guī)則太寬把帶語言參數(shù)的JS URL如/js/lang/en.js?v123也緩存了但OnlyOffice后端每次生成的語言包URL不同緩存導(dǎo)致返回舊版本或404。修復(fù)配置細(xì)化靜態(tài)資源location排除帶查詢參數(shù)的請求# 緩存無參數(shù)的靜態(tài)資源 location ~ ^/(?:styles|js|images|fonts|favicon.ico)$ { proxy_pass http://onlyoffice_backend; expires 1y; add_header Cache-Control public, immutable; } # 不緩存帶參數(shù)的請求語言包、版本號等 location ~ \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { proxy_pass http://onlyoffice_backend; expires off; add_header Cache-Control no-cache, no-store, must-revalidate; }4.5 Docker容器重啟后“下載失敗”卷掛載權(quán)限問題現(xiàn)象docker restart onlyoffice后所有文檔打開失敗OnlyOffice日志里有Permission denied錯誤。根因OnlyOffice容器以www-data用戶UID 33運行但宿主機掛載的/app/onlyoffice/data目錄所有者是root。容器重啟后www-data無法寫入該目錄導(dǎo)致文檔緩存、轉(zhuǎn)換隊列等失敗。解決方案啟動容器前修改宿主機目錄權(quán)限sudo chown -R 33:33 /app/onlyoffice/data或者在docker run命令里指定用戶docker run -u 33:33 ... onlyoffice/documentserver注意不要用chmod 777這是安全大忌。OnlyOffice官方文檔明確要求UID 33。4.6 常見問題速查表問題現(xiàn)象最可能原因快速驗證命令修復(fù)方案所有文檔都“下載失敗”Nginxproxy_pass地址錯誤或容器未啟動curl -v http://onlyoffice:8000/healthcheck檢查docker ps確認(rèn)容器狀態(tài)檢查upstream配置只有PDF預(yù)覽失敗OnlyOffice缺少PDF渲染庫docker exec onlyoffice ls /usr/lib/onlyoffice/documentserver/server/FileConverter/bin/重新拉取onlyoffice/documentserver:latest鏡像舊版有bug編輯時提示“無法保存”proxy_read_timeout過短WebSocket斷連wscat -c wss://office.example.com/coauthoring/CommandService.ashx將proxy_read_timeout設(shè)為3600登錄后首頁空白X-Forwarded-Proto未透傳HTTPS降級查看頁面源碼搜索http://確認(rèn)proxy_set_header X-Forwarded-Proto $scheme已配置Nginx啟動報unknown directive proxy_http_versionNginx版本過低1.1.4nginx -v升級Nginx到1.18或用apt-get install nginx-full最后分享一個小技巧當(dāng)所有配置都檢查無誤問題依舊存在時打開OnlyOffice容器的日志實時跟蹤docker logs -f onlyoffice \| grep -E (ERROR|WARN|Exception)然后在瀏覽器里復(fù)現(xiàn)“下載失敗”操作。90%的情況下你會在日志里看到一行關(guān)鍵錯誤比如java.lang.NullPointerException at com.onlyoffice.converter.util.ConverterUtil.getFilePath(ConverterUtil.java:123)這直接指向了文件路徑解析失敗問題根源可能在掛載卷的路徑拼寫錯誤而不是Nginx配置。日志永遠(yuǎn)是你最誠實的伙伴。