在ARM架构服务器上部署OnlyOffice文档预览服务时，很多开发者都会遇到“端口映射失效”“内网IP拦截”“图片无法预览”等问题，尤其是结合Docker部署时，ARM架构的镜像兼容性、端口配置、内网访问等坑更易出现。
本文结合ARM架构专属场景，把从部署到调试的全流程踩坑点、解决方案一次性讲透，新手也能跟着操作，彻底解决ARM服务器上OnlyOffice的所有部署难题。

一、部署背景与初始需求（ARM架构专属）

本次部署基于ARM架构服务器，核心需求如下，贴合企业内网实际使用场景：

• 不使用–net=host网络模式（避免端口冲突，保持标准Docker部署）；

• 对外通过9090端口访问OnlyOffice（避免80端口被占用）；

• 能正常访问内网文件服务（192.168.1.100:6115，替换原真实IP，适配ARM内网）；

• 关闭JWT鉴权，避免额外认证麻烦；

• 支持Office文档（doc、docx）和图片预览，无401、超时等报错。

部署镜像：8b22d991c215（ARM架构兼容版，实际部署时替换为自己的OnlyOffice ARM镜像即可）

二、全流程踩坑与解决方案（ARM架构专属，按报错顺序）

坑1：使用–net=host后，9090端口无法访问

「问题现象」：启动容器时添加–net=host（初衷解决内网访问超时），但启动后http://服务器IP:9090/welcome/无法打开，报错“网页解析失败”。

「核心原因」：ARM架构下，–net=host会让容器直接占用宿主机80端口，导致原有的-p 9090:80端口映射失效，无法通过9090端口访问。

「ARM专属解决方案」：放弃–net=host，采用ARM架构标准Docker部署，使用端口映射实现9090端口访问，命令如下：

# 1. 删除旧容器（若有残留）
docker rm -f onlyoffice

# 2. ARM架构专属启动命令（适配镜像兼容性）
docker run -d \
  --name onlyoffice \
  --privileged \
  -p 9090:80 \
  -e JWT_ENABLED=false \
  -e ALLOW_PRIVATE_IP_ADDRESS=true \
  --restart=always \
  8b22d991c215

坑2：内网IP访问被拦截，报错“private IP address not allowed”
「问题现象」：容器启动正常，但预览文档时，OnlyOffice提示内网IP访问被禁止，后台报错“private IP not allowed”。

「核心原因」：ARM架构下，OnlyOffice默认禁止访问内网私有IP，即使添加环境变量，也可能因镜像兼容性问题未生效，配置文件中allowPrivateIPAddress仍为false。

「ARM专属解决方案」：直接修改配置文件，强制开启内网访问，命令如下：

坑3：文档能预览，图片无法查看（报401认证失败）
「问题现象」：doc、docx文档能正常预览，但图片（png、jpg）无法显示，后台报错“请求访问认证失败”。

「核心原因」：图片和文档走同一个下载接口/api/doc/downloadPrjFileNoVerify，后端未放开该接口的匿名访问权限，导致图片请求被拦截。

「ARM专属解决方案」：

# 1. 后端接口放行（ARM架构适配）
docker exec -it onlyoffice sed -i 's/"allowMetaIP": false/"allowMetaIP": true/g' /etc/onlyoffice/documentserver/default.json
# 2. 重启容器，确保配置生效
docker restart onlyoffice

三、ARM架构部署关键注意事项（重点！）

1. 镜像选择：必须使用ARM架构兼容版OnlyOffice镜像，避免x86镜像在ARM服务器上运行报错（核心坑点）；

• 2. 端口映射：ARM服务器端口建议避开1024以下特权端口，优先使用9090、8080等非特权端口，避免权限冲突；
• 3. 配置验证：修改配置后，执行docker exec -it onlyoffice cat /etc/onlyoffice/documentserver/default.json | grep “allowPrivateIPAddress”，返回true即生效；
• 4. 图片预览：确保后端接口/api/doc/downloadPrjFileNoVerify放开匿名访问，避免401拦截。

四、最终完美部署命令（ARM架构一键复制可用）

# 1. 彻底清理旧容器
docker rm -f onlyoffice

# 2. ARM架构专属启动（适配镜像+内网放行+无JWT）
docker run -d \
  --name onlyoffice \
  --privileged \
  -p 9090:80 \
  -e JWT_ENABLED=false \
  -e ALLOW_PRIVATE_IP_ADDRESS=true \
  --restart=always \
  8b22d991c215

# 3. 补充图片预览配置（ARM专属，防止图片拦截）
docker exec -it onlyoffice sed -i 's/"allowMetaIPAddress": false/"allowMetaIPAddress": true/g' /etc/onlyoffice/documentserver/default.json
docker restart onlyoffice

# 4. 验证服务（ARM架构适配）
docker exec -it onlyoffice curl -I http://192.168.1.100:6115/api/doc/downloadPrjFileNoVerify/xxx.doc

五、ARM架构常见坑总结（避坑关键）

1. 镜像兼容：必须用ARM版本OnlyOffice镜像，x86镜像在ARM服务器上会出现“无法解析”“启动失败”；

• 2. 端口权限：ARM服务器1024以下端口可能需要额外授权，优先使用9090、8080等非特权端口；
• 3. 配置生效：修改default.json后必须重启容器，ARM架构下配置生效速度略慢，建议重启后等待30秒再测试；
• 4. 图片预览：ARM架构下图片直拉无需转码，需确保接口匿名访问权限打开，避免401拦截。

总结：ARM架构下的OnlyOffice部署，核心是“镜像兼容+配置生效+接口放行”，按照上述步骤操作，文档预览、图片查看、内网访问均可正常实现，彻底解决所有报错！