系统运维

# 文档通安装维护手册（Linux及信创系统）

适用Linux系统、信创系统

2024年12月修订

# 修订记录

修订内容 修订时间
增加服务组合要求的说明 2025-3-12
文档通升级为1.6.36-1版本，修复若干BUG 2025-1-9
增加不同网络环境配置方案章节，供运维参考配置 2024-12-27
调整https配置方法一和二的顺序，让最推荐的方案放在前面 2024-12-27
申请Lic时需要提交Linux系统下硬盘信息，增加操作说明 2024-12-27
增加卸载麒麟系统podman的说明 2024-11-25
文档通升级为1.6.23-1版本，同步更新部署手册 2024-11-8
文档通1.5.99.1升级为1.6.11.1版本，同步更新部署手册 2024-10-10
增加完全卸载文档通的章节 2024-10-10
增加预装tar等常用命令的提醒 2024-10-18
增加首次启动Docker失败的解决方案 2024-10-30

# 在线化资料支持

手册存在不定期更新，为了方便您获取最新资料，本部署手册在致远开放平台也放置了一份，建议您收藏以下地址，并尽量使用在线手册以获得更优的部署体验：https://open.seeyoncloud.com/v5doc/142/1883/2038.html (opens new window)

# 安装前准备

# 适用协同版本

文档通在线编辑集成适用于致远协同办公管理软件（A6+、A8+、A8-N、G6、G6-N）9.0SP1 Next系列版本。

推荐程度 适用OA版本 BuildID 备注
★★★★★ V9.0SP1（1101版本） B241101.175800.CTP173960069 OA最新版本，支持集成当前文档通版本，强烈推荐
★★ V9.0SP1（930版本） B240930.182959.CTP170787930 OA版本过期，支持集成当前文档通版本，但不推荐
★ V9.0SP1（730版本） B240731.121211.CTP165889688 OA版本过期，支持集成当前文档通版本，但不推荐

# 环境部署要求

部署人员需要掌握基本的Linux部署知识，如部署过程中遇到了命令不支持不会使用的问题，请优先通过百度AI搜索、GPT-4等AI工具来获得答案。

1725931236467.png

文档通阶梯资源要求：

不同用户数对文档通服务器配置要求不同，建设初期请按照OA同时在线人数申请与之匹配的服务器资源，后续再根据运行情况做灵活调配。

1725931264578.png

文档通更详细的系统环境兼容、阶梯资源要求参考在线文档： https://docs.qq.com/sheet/DRk9sd0hhWmRzeVNx?tab=000001 (opens new window)

信创系统环境兼容、阶梯资源要求参考在线文档： https://docs.qq.com/sheet/DRkNYWHpVTW1Wd3pn?tab=000001 (opens new window)

检查服务器字体是否满足用户要求：安装包不提供任何字体包文件，所有付费/免费字体都需要由客户根据自身使用情况准备。文档通编辑器的字体是从服务器读取，无需在每台客户端电脑上安装，所以需要将用户用到的各种字体文件放在服务器上。

# 服务组合要求

文档通是在线编辑服务，可以结合其它在线预览产品实现编辑和预览一体在线化办公。组合要求如下：

组合模式 是否支持 备注
文档通+数科预览/数科签章 支持 功能最全
文档通+Aspose在线预览 支持 公文场景不可用
文档通+金山WebOffice在线预览 不支持 此组合存在功能缺陷，标准产品不支持

关于与数科共用一台服务注意事项：

1、数科是在线预览服务，与文档通没有强关联，如项目上不涉及数科服务，可忽略本注意事项

2、两者都依赖Docker容器部署，原则上不允许两者安装在一起，有如下风险：

  • 两者对Docker最低版本要求不同，文档通依赖23，数科依赖26，如果一定要安装在一起，必须先安装数科，再安装文档通！
  • 做Docker容器维护时容易误操作：如卸载数科服务时，一不注意可能把文档通也卸载了。此风险，项目上需要承担！
  • 服务器配置需要足够支撑两者的共存，如服务器资源过低，会存在抢占资源问题，继而引发宕机。此风险，项目上需要承担！

# 网络互通要求

使用文档通功能，需要实现如下网络要求：

1、文档通服务要与协同OA 服务网络互通，协同OA需要能访问到文档通内网IP和必要的端口（见默认端口章节），文档通服务需要能访问到协同OA内网IP和端口

2、客户终端（使用文档通在线编辑的电脑）需要能同时访问协同OA服务地址和文档通服务地址。

3、如果客户端连接协同OA协议是https，则文档通协议也必须是https，否则会出现文档通功能不可用。

4、如启用https，证书需要客户采购，且证书不能绑定到任何IP上，证书需要绑定给指定域名，不保证自签名证书可用！

由于不同客户的网络环境不同（有的只用PC内网；有的PC和移动都放外网；有的M3和微协同都分开网络管理），不同场景的网络配置会有不同，产品提供了不同客户网络环境下的解决方案，请务必参考在线文档做网络配置：https://docs.qq.com/doc/DYUF2d2FuV214Y3Rl (opens new window)

# 默认端口

以下是文档通安装时的默认端口及参数信息，如安装过程未做个性化调整，则可以参考如下默认安装参数去做网络策略：

端口服务 http默认端口 https默认端口（默认未开启） 操作
文档通服务 80 443 可被协同OA连接、可被客户端连接
因端口冲突，不建议与协同OA安装在同一服务器

1730993448629.png

如部署完成后，怀疑网络不通，可在协同OA（仅V9.0SP1 1104及以上版本支持）配置文档通地址的页面进行网络连接测试。

也可以通过telnet命令检查IP端口连通性，示例telnet 192.168.10.20 80。

# 安装包下载地址

链接：https://pan.baidu.com/s/1tGwOsWuW3Ra9IVls_KI2oA (opens new window)

提取码: kusm

网盘具体路径：第三方应用-中标慧康在线文档编辑(文档通)-安装包

Windows环境选择：window_amd64

Linux_x86环境选择：docker_amd64（适用于X86、C86芯片架构系统）

Linux_arm环境选择：docker_arm64（适用于Arm芯片架构系统）

如果客户Linux（含信创）环境没有预装docker，可以安装文档通提供的离线docker安装程序：docker_offline_install-23.0.1.zip

# 软件要求

文档通在线编辑服务依赖Docker容器，所有相关服务均安装在Docker下，要求：

  • docker23.0.1及以上

  • docker-compose

信创麒麟系统自带的docker有兼容性问题，需要卸载其内置的docker，详见安装docker章节。

# 安装步骤(操作前务必通读本节)

特别提醒：自2024年11月起，文档通安装包更新到1.6.23.1版本，最新版本解决了近期多个问题，如您发现安装程序是旧版本，请务必参考本手册“安装包下载地址”下载最新版本安装程序。

Linxu系统或信创系统下操作，需要以管理员（root）权限操作。

安装部署前，先确保当前系统已经安装了最基础的命令，（能连接互联网服务器）可执行如下语句做预装：

如服务器无法连接互联网，请要求操作系统厂商预装必要的命令组件

# Red Hat系列，使用yum命令安装，如当前系统提示yum不可用，则尝试使用apt
yum update
yum install tar curl telnet vim -y

# 基于Debian的系统（如Ubuntu）使用apt预装组件
sudo apt update
sudo apt install tar curl telnet vim -y

# 基于欧拉openEuler、龙蜥Anolis OS等系统使用dnf安装
sudo dnf update
sudo dnf install tar curl telnet vim -y

# 安装docker

# 检查是否安装docker（必做）

通过docker -v命令来确认版本，文档通要求docker版本在23.0.1及以上。如当前操作系统已经确认安装了文档通要求的Docker组件，则本步可忽略。

如果您是麒麟系统，即使出厂预装了docker，也必须卸载预装的docker，安装文档通推荐的docker，否则文档通会部署启动失败！

1730995898378.png

# 卸载麒麟系统预装的docker（麒麟系统必做）

信创麒麟系统自带的docker有兼容性问题，需要先卸载其内置的docker。

执行yum remove docker或apt remove docker 然后重启操作系统，如果不重启可能导致新装的docker不能运行。

卸载后还有问题，从本手册常见问题章节寻找是否有解决方案。

# 卸载podman（麒麟系统必做）

麒麟系统自带的podman模块需要卸载，执行apt remove podman或yum remove podman即可，不做本步骤，后续部署会失败！

1732527775989.png

# 安装离线包（无docker必做）

如当前操作系统已经确认安装了文档通要求的Docker组件，则本步可忽略。

首先，通过文档通安装包下载地址，下载Docker离线安装包docker_offline_install-23.0.1.zip，然后上传到/data/wdt目录（不存在就新建），执行解压：

# 在data目录下初始化一个wdt目录，方便管理
mkdir -p /data/wdt
cd /data/wdt/
unzip docker_offline_install-23.0.1.zip

然后，执行安装操作：

cd docker_offline_install-23.0.1
# X86环境执行脚本
./install.sh x86_64
# Arm环境执行脚本
./install.sh aarch64

安装完成后可以查询版本号，有版本号就表示docker环境安装好了：

docker -v
docker-compose -v

显示如下信息，则说明安装成功：

# 修改docker路径（可选）

本步操作目的是将docker放到/data/wdt目录下，统一管理，并且此空间较大，不容易造成docker空间占满等问题。

修改文件/etc/docker/daemon.json 配置，没有文件就新增：

mkdir -p /etc/docker/
vim /etc/docker/daemon.json

以vi或vim命令在/etc/docker/daemon.json文件中录入如下格式的内容并保存：

{
    "data-root": "/data/wdt/docker"
}

以上完成后，执行如下操作：

# 备份原来文件
cp -a /var/lib/docker/ /var/lib/docker_backup/

# 将docker移动到/data/wdt/docker/路径下
mv /var/lib/docker /data/wdt/

# 重启docker
systemctl daemon-reload
systemctl restart docker

# 核对安装包完整性（可选）

参考本手册安装包下载地址下载符合当前系统的安装包，可以通过命令核对安装包完整性，值不一致需要重新下载安装包。

sha256sum iwebeditor_documentsystem_1.6.23-1.tar.gz

1730994863882.png

# 环境初始化

# 上传安装包（必做）

按照服务器要求准备一台给文档通单独使用的服务器，数据磁盘空间大于200G，然后新建一个/data/wdt目录（已有的可以忽略，至少200G预留给文档通）。

首先，创建/data/wdt，存在则忽略：

mkdir -p /data/wdt

然后，把安装包目录上传到/data/wdt路径下。本示例是将下载好的完整包拷贝到/data/wdt下：

1730995115183.png

# 重命名版本号目录（必做）

为了方便按版本管理文档通，我们统一建议对文档通的目录按版本进行命名，将文档通安装文件夹上传到/data/wdt之后，将文件夹直接更名为文档通版本号，最终层级目录结构应该是/data/wdt/版本号目录/安装文件：

1730997258669.png

# 继续回到/data/wdt目录下
cd /data/wdt

# 找到文档通的部署包，将其重命名为下载的文档通版本号
mv docker_x64/ 1.6.23-1
cd 1.6.23-1/

注：以上命令中的1.6.23-1为当前安装包版本，如果后续部署更新高版本可以修改为相应版本号。

如果您当前的文档通安装包比1.6.36-1要老，请务必下载最新的文档通安装包部署，新版本稳定性会更高。

1730997461721.png

# 开启内核ipv4转发（必做）

以下操作必须，请按命令示例执行：

复制/etc/sysctl.conf一份命名为/etc/sysctl.conf.1，方便出问题恢复。

使用vi或vim命令编辑/etc/sysctl.conf文件，修改或添加如下配置：

cp -r /etc/sysctl.conf /etc/sysctl.conf.1
vim /etc/sysctl.conf

net.bridge.bridge-nf-call-iptables = 1
net.ipv4.conf.default.rp_filter = 0
net.ipv4.conf.all.rp_filter = 0
net.ipv4.ip_forward=1

# 保存后（如不会使用vim请自行网上搜索），执行 sysctl -p 使修改生效（有的系统需要执行 service network restart）
sysctl -p
# 如果已经部署了服务，还需要重启docker引擎：
systemctl daemon-reload
systemctl restart docker

如果出现sysctl: cannot stat /proc/sys/net/bridge/bridge-nf-call-iptables: No such file or directory错误，则表示"net.bridge.bridge-nf-call-iptables = 1"参数未生效。

可以执行命令手动加载模块到内核：

# 先加载模块到内核
modprobe br_netfilter
# 再执行sysctl -p使修改生效
sysctl -p

# 开启内核ipv6转发（可选）

仅使用ipv6 场景才使用，正常情况下无需此步操作。

复制/etc/sysctl.conf一份命名为/etc/sysctl.conf.2，方便出问题恢复。

cp -r /etc/sysctl.conf /etc/sysctl.conf.2
vim /etc/sysctl.conf

编辑/etc/sysctl.conf文件，修改或添加如下配置：

net.bridge.bridge-nf-call-ip6tables = 1
net.ipv6.conf.default.accept_ra = 0
net.ipv6.conf.all.accept_ra = 0
net.ipv6.conf.all.forwarding = 1

# 保存后，执行sysctl -p使修改生效（有的系统需要执行 service network restart）
sysctl -p
# 如果已经部署了服务，还需要重启docker引擎：
systemctl daemon-reload
systemctl restart docker

# 导入文档通镜像（必做）

进入安装包目录，将iwebeditor_documentsystem镜像包导入：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1
# 执行导入镜像
docker load < iwebeditor_documentsystem_1.6.23-1.tar.gz

注：这个iwebeditor_documentsystem_1.6.23-1.tar.gz是编写本手册时的版本，后续文档通安装包可能会更新，更新后文件名会变化，请根据实际情况执行对应文件名的load操作。

1730997725273.png

# docker-compose.yml配置

# 挂载卷（必做）

本步必须，否则后面某些操作会受影响：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

# vi或vim命令修改docker-compose.yml
vim docker-compose.yml

在vi或vim模式下，找到“volumes”模块，单击键盘i进入编辑模式，将其下每一个路径前都增加一个“/data”，添加后保存docker-compose.yml文件（单击Esc退出编辑模式，随后录入:wq回车强制保存，如不会使用vim请自行网上搜索）。

此步操作表示把挂载卷放在/data目录下，挂此目录下的原因是统一管理，以及/data空间较大，不容易造成磁盘空间满问题。建议按手册挂载，后续字体等添加也会使用此目录。

1728571920521.png

挂载卷解读：冒号前为主机上的路径，也是操作的对象。冒号后为容器内路径，不需要操作。

# 修改文档通端口（可选）

文档通服务器默认占用80端口，如环境存在端口冲突或端口管控，可以调整默认端口。

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

# vi或vim命令修改docker-compose.yml
vim docker-compose.yml

通过vi或vim修改docker-compose.yml，找到ports模块，默认格式如下

    ports:
      - '80:80'

其中左侧的80表示外部访问服务器的端口号（只需要修改左侧这个端口号），右侧的80表示服务器内默认占用的端口号（不要修改右侧的80端口）

参考ports模块(HOST:CONTAINER)标准，如果想让外部访问当前文档通服务器端口调整为8018，则按如下图所示修改即可（其它依葫芦画瓢）：

# 配置JWT认证（必做）

JWT认证是协同OA服务连接文档通服务时身份认证使用，是必做操作：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

# vi或vim命令修改docker-compose.yml
vim docker-compose.yml

继续通过vi或vim修改docker-compose.yml，找到environment模块，单击键盘i进入编辑模式，将如下三个参数的#号删除掉：

#- JWT_ENABLED=true
#- JWT_SECRET=secret
#- JWT_HEADER=Authorization

以下是修改后的效果：

下一步是自定义设置JWT_SECRET参数值，找到上一步去掉#号的JWT_SECRET参数，将secret去掉，改成一个你觉得更加安全的密码，这个完全自定义，无特殊要求：

# 自定义JWT_SECRET的密钥值：
- JWT_SECRET=这里自定义密钥字符串

设置自定义密钥操作，修改前后的效果：

如果为了安全性，也可以通过命令生成随机密钥，命令行中执行：

cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 20 | head -n 1

将生成的密钥填入docker-compose.yml文件中的JWT_SECRET，并记录好这个密钥串，在后续章节协同OA侧也填入这个随机密钥。

以上文本修改后，保存docker-compose.yml（单击Esc退出编辑模式，随后录入:wq回车强制保存，如不会使用vim请自行网上搜索）。

# 初始启动验证（必做）

以上完成后，可以启动文档通服务：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

docker-compose up -d

正常执行效果如下：

1730998513171.png

如首次启动容器出现如下错误：

docker: Error response from daemon: failed to create shim task: OCI runtime create failed: container_linux.go:318: starting container process caused "permission denied": unknown.

可能是系统安装了podman，需要将其卸载，执行apt remove podman 或 yum remove podman，随后再重新启动文档通试试：

1730260814713.png

如果出现 WARNING: IPv4 forwarding is disabled. Networking will not work 错误提示，则可能是未开启内核ipv4转发或未重启docker，参照“开启内核ipv4转发”章节，检查配置，并且必须重启一次docker自身服务！

启动服务两分钟后（初始化工作需要花费点时间）测试服务可用性。

浏览器访问http://文档通ip:端口/healthcheck，显示true表明服务正常启动。如未调整配置，文档通默认端口为80。

# 授权申请和注册（必做）

# 申请授权步骤

文档通服务部署完成后，才能进行文档通授权文件申请。部署人员按照本章节操作将申请授权所需的硬件信息全部获取，并交给客户经理，由客户经理通过商务流程申请文档通授权和协同OA加密狗授权。

待实施部署人员按照本章节方法提供服务器网卡等信息，客户经理拿着网卡Mac信息去申请授权。正式授权文件需发起销售订单获取，试用授权文件需发起《客户产品申请单》流程，在表单中插件信息部分选择或填写"文档通在线编辑"。

类型 申请内容 申请通路
协同OA加密狗授权 申请“在线编辑集成插件” 试用和正式授权均走致远总部商务通路
文档通授权 拿着机器网卡信息申请文档通nso授权文件 试用和正式授权均走致远总部商务通路

# 获取服务器网卡主板硬盘信息

在确保文档通部署完成，并且访问验证服务有效，则可以开始获取服务器主板、硬盘、默认网卡信息给客户经理。

Linux和信创服务器客户，需要提供两份信息申请注册码：

第一份信息：访问文档通服务地址查询硬件信息：http://文档通ip:端口/ServerHardwareInfo （默认端口号80），将下图信息拷贝出来，以文本的形式发给申请授权的客户经理：

Linux下也可能只能拿到网卡信息：

1735286146132.png

第二份信息：在终端中执行sudo lsblk -o NAME,SERIAL|grep -v loop，在输出中查找s开头、或者n开头的设备，将硬盘序列号全部复制出来，以文本的形式发给申请授权的客户经理（如果客户经理不知道填写到表单哪个位置，就直接将内容回复或附言到流程上）：

1735286165941.png

将以上两部分获取到的服务器主板、硬盘、默认网卡信息给客户经理，客户经理按前面章节给出的通路去申请授权。

注：获取硬件信息时可能出现"无主板信息"、"无默认网卡"等情况，这些也能下单订货，只需要客户经理根据不同场景将信息填写到对应位置即可。

客户经理收到文档通订货单流程后按如下规则填写内容：

"服务器硬盘序列号"字段填写前面"硬盘"双引号中的信息，若无"硬盘"信息，则填入"默认网卡"双引号中的信息。

"服务器网卡MAC地址"字段填写前面"默认网卡"双引号中的信息，若无"默认网卡"信息，则填入"主板"或"硬盘"任意一个双引号中的信息。

"主板编号"字段填写前面"主板"双引号中的信息，若无"主板"信息，则填入"默认网卡"双引号中的信息。

# 注册授权

客户经理申请到文档通授权文件后，交给实施部署人员。

授权文件名字必须为NsoWebAuthority.nso，实施部署将授权文件放置在/data/vol/iwebeditor/Data目录下（注：这个/data/vol对应前面挂载卷操作，如未做正确挂载，会存在找不到目录的问题）。

授权文件需要可读取权限，在授权文件所在目录下执行命令 chmod 744 NsoWebAuthority.nso

# 查询授权有效性

上一步放置好授权nso文件后，不需要重启文档通服务，通过浏览器查询授权信息是否生效：http://文档通ip:端口/UserAuInfo 默认端口号80

如下是授权正常的状态：

# 协同OA侧配置文档通在线编辑（必做）

部署完成、验证服务可用性通过、完成了文档通授权认证，下一步就是在协同OA侧配置文档通相关参数信息，配置完成后，协同OA侧就可以使用文档通功能。本章节非常重要，新人实施部署时容易忽略本章内容。

# 文档通侧再次检查JWT配置

参考"配置JWT认证"章节，在文档通服务器做好JWT的开启和自定义密钥设置。如果改了docker-compose.yml配置文件，都需要参考本手册先关闭服务再启动重复！

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

cat docker-compose.yml

如下图是一个正确的JWT配置：

1728573725828.png

# 协同OA侧配置文档通连接

登录协同OA系统管理员-系统设置-流版签系统设置-设置文档通在线编辑信息。

如未显示"流版签系统设置"菜单或"在线编辑"页签，则说明协同OA加密狗没有"在线编辑集成插件"，需要按照文档通授权申请和部署章节申请加密狗插件。

1729574702445.png

文档通在线编辑服务器地址（内网）：对应文档通的内网地址，格式 http://文档通IP:端口 文档通默认端口是80，IP地址不能配置127.0.0.1

文档通在线编辑服务器地址（外网）：面向互联网访问系统的客户，外网用户通过此地址访问文档通服务，一般是域名或外网IP地址，外网地址需要与文档通内网地址做映射（映射IP端口参考文档通在线编辑服务器地址（内网）配置）。

文档通在线编辑密钥：对应"JWT认证"章节中的JWT_SECRET的值，把JWT_SECRET的值拷贝到这里。

文档通在线编辑回调地址（内网）：对应内网协同OA的地址，端口后追加/seeyon，不要以/结尾，IP地址不能配置127.0.0.1

文档通在线编辑微信域名：面向独立域名访问微协同H5的客户，文档通在线编辑服务器地址（内网）IP和端口需要映射给M3外网（一般是域名），否则M3无法在线编辑。

文档通在线编辑M3域名：面向独立域名访问M3的客户，文档通在线编辑服务器地址（内网）IP和端口需要映射给微协同外网（一般是域名），否则微协同无法预览文件。

由于不同客户的网络环境不同，可参考本手册“不同网络环境配置方案”章节，根据客户实际网络情况做部署的准备和配置调整。

文档通在线编辑密钥配置示例：

1731055930488.png

自协同OA V9.0SP1 1101版本开始，点击修改后会进行配置检测，确保结果是如下显示效果，如果出现不通，请先自查网络请求：

1731053812060.png

# 多网段设置（外网场景）

如果客户协同OA开通了外网PC、外网M3、外网微协同一个或多个访问地址，必须进行“多网段设置”，否则会出现访问异常。

“多网段设置”的是协同OA的外网与内网映射关系：

协同内网IP/域名： 配置协同OA内网IP，不带http协议头，不带端口。如果是OA集群环境，对应负载均衡服务器（如Nginx）的IP。

协同外网IP/域名： 配置协同OA外网域名，不带http协议头，不带端口，如果存在多个外网地址则以半角逗号,隔开

1731341469339.png

# 验证功能有效性

以上配置完成后，协同OA侧不用重启，可以直接验证功能可用性。通过用户新建自由协同，切换正文类型为Word正文，如果出现如下界面，则说明功能基本配通：

# 不同网络环境配置方案（必做）

由于不同客户的网络环境不同，本章节列举了常见的网络场景和配置方案，项目上可参考方案做配置调整。

很多方案都涉及做HTTPS和前置代理，正常情况都推荐Nginx做管理，本章节会先提供常见的Nginx配置代码，再提供不同的网络场景部署示意图，以供项目上根据实际情况做参考调整。

# Nginx代理到文档通（http）

如果特定网络条件下需要使用http访问Nginx再代理给文档通，则可以参考如下nginx代码块做代理转发：

其中带#注释部分可以根据项目实际情况做调整

 server {
        server_name localhost;
        charset utf-8;
        # 监听端口，可自定义，访问NG此端口后转发给内部文档通
        listen 81;

        location / {
        # 转发地址：配置文档通内网访问地址
        proxy_pass http://192.168.188.134:80;
        proxy_redirect off;
        client_max_body_size 100m;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        }

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
        root   html;
        }
}

# Nginx代理到文档通（https）

如果特定网络条件下需要使用https访问Nginx再代理给文档通，则可以参考如下nginx代码块做SSL管理以及代理转发：

其中带#注释部分可以根据项目实际情况做调整

server {
        # server_name后的域名对应外网地址去掉协议头和端口
        server_name wdt.seeyoncloud.com;
        charset utf-8;
        # 监听端口，暴露给外网映射的端口
        listen 443 ssl;
        # crt、key为证书路径，默认放在当前配置文件同级目录ssl目录下（如果没有则新建），请按实际名称修改
        ssl_certificate ssl/wdt.crt;
        ssl_certificate_key ssl/wdt.key;
        # 支持的tls协议版本
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

        location / {
        # 转发地址：配置文档通内网访问地址
        proxy_pass http://192.168.188.134:80;
        proxy_redirect off;
        client_max_body_size 100m;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        }

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
        root   html;
        }
}

# 纯内网http访问协同OA单机

此场景是最简单的形态，参照下图所示案例部署即可：

1735295281405.png

# 纯内网http访问协同OA集群

此场景由于OA是集群多节点，故必须有负载均衡服务，故此方案客户端、OA、文档通的访问通信均走负载均衡代理服务。

1735295347134.png

# 纯内网https访问协同OA单机或集群

此方案也是纯内网“万精油”方案，主要是提供一个前置Nginx服务用来管理SSL、集群、代理，后续所有网络变化都通过NG调整，（纯内网）此方案兼容性最广。

注意访问OA使用https，则文档通也必须采用https。

1735295511193.png

# 纯外网http访问协同OA单机

此场景适用于客户端在外网，OA和文档通服务器在内网（常见的云服务器就是这种形态），参照下图所示案例部署即可：

1735296253067.png

# 纯外网https访问协同OA单机或集群

此场景适用于客户端在外网，OA和文档通服务器在内网（常见的云服务器就是这种形态），并且外网需要通过https访问系统场景。

对于纯外网访问客户，使用https是最推荐也最安全的形式，访问OA使用https，则文档通也必须采用https，下图是推荐的部署方案：

1735296819454.png

# 内外网并存http访问协同OA单机

此方案适用于内网和外网均可以访问协同OA，并且访问地址均是http的客户，只需要外网提供外网域名/地址，做好与内网对应服务器的映射即可：

1735297230258.png

# 内网http外网https访问协同OA单机

内网http+外网https访问协同OA单机是比较常见的一种场景，即保证了外网访问的安全性，内部网络管理也比较简单。此场景推荐部署前置Nginx来管理SSL，以及与外网客户端的连接，部署方案参考如下示意图：

1735297598295.png

# 内网http外网https访问协同OA集群

内网http+外网https访问协同OA集群也是比较常见的一种场景，即保证了外网访问的安全性，内部网络管理也比较简单。此场景推荐部署前置Nginx来管理OA集群负载、SSL证书以及与内外部客户端的连接，部署方案参考如下示意图：

1735298041809.png

# 内网外网均https访问协同OA单机或集群

对于安全性要求较高的客户，内外网均要求https管理，则可以参照此方案。

此场景推荐部署前置Nginx来管理OA集群负载、SSL证书以及与内外部客户端的连接，部署方案参考如下示意图：

1735298208062.png

# 安装字体（必做）

字体安装是初期部署后必须做的事项！

关于字体文件的说明：

1、如果要让在线编辑的文字样式与本地编辑时一样，就需要确保文档通服务内有与之匹配的所有字体，否则就会出现显示混乱、错版、套红跑版等问题（实际其它在线编辑预览产品初始安装时也存在类似问题）。

2、如果项目已经上线，随后更新了字体，需要关闭服务5分钟后再启动服务。因为相关资源设定了5分钟失效时间，不关闭服务，使用端会使用旧数据处理文档，这会导致错误的处理过程。更新字体最好选择无人使用的时段。

3、编辑器使用的字体文件是安装在服务器端的，无需在每台客户端电脑上安装，所以需要将用户用到的各种字放到文档通服务指定目录。

4、如果文档中使用的字体在系统中没有，那么编辑器会使用替代字体去排版，这就是引起错版跑版的原因之一。

5、大多数中文字体都涉及版权（比如微软雅黑、方正小标宋等），文档通无法免费内置，需要客户方准备。

6、项目上根据客户实际情况提取.ttf和.otf字体文件放置到文档通服务字体目录下。

7、已经存在的字体，不要重复添加，这样反而会引发跑版、乱码。

8、不要（因为感觉字体太多）删除程序预制的字体，这样会导致各种莫名问题。

字体安装步骤：

将要引入的外部字体压缩打包放在/data/vol/iwebeditor/includefonts目录下，然后进行解压。增减字体文件后需要重启Docker容器！

注：这个/data/vol对应前面挂载卷操作，如未做正确挂载，会存在找不到目录的问题。

# 字体压缩包上传到要求的目录，随后解压
cd /data/vol/iwebeditor/includefonts/
unzip extfonts.zip

# 放置字体后，需要重启文档通服务
# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1
# 如果修改过配置项，需要通过如下方式重启服务：
docker-compose down
docker-compose up -d

1731141275300.png

以下是部分比较常见的中文字体，请根据客户实际使用情况与客户一起配齐必要的字体：

1731037384905.png

如果工具拖动过来的字体是如下显示格式，可能会引发错误，建议参考上面的操作：将字体打包传送，再解压。

1731141288401.png

扩展资料：

  • Windows系统级字体存放于：C:\Windows\Fonts目录下
  • Linux和信创系统级字体存放于：/usr/share/fonts目录下
  • MacOS系统级字体存放于：/System/Library/Fonts和/Library/Fonts目录下

# 日常运维（可选）

执行此步操作的前提是：前面章节安装部署操作已经全部完成！

# 启动服务

如项目上需要启动文档通服务，终端进入包目录，执行命令启动docker下的文档通服务：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

docker-compose up -d

正常执行效果如下：

1730998513171.png

如首次启动容器出现如下错误：

docker: Error response from daemon: failed to create shim task: OCI runtime create failed: container_linux.go:318: starting container process caused "permission denied": unknown.

可能是系统安装了podman，需要将其卸载，执行apt remove podman 或 yum remove podman，随后再重新启动文档通试试：

1730260814713.png

如果出现 WARNING: IPv4 forwarding is disabled. Networking will not work 错误提示，则可能是未开启内核ipv4转发或未重启docker，参照“开启内核ipv4转发”章节，检查配置，并且必须重启一次docker自身服务！

# 停止服务

如项目上需要停止文档通服务，则按此操作：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1

docker-compose stop

# 重启服务

如项目上需要重启文档通服务，则按此操作：

# 回到文档通目录下，这个1.6.23-1来自于前面章节重名的版本号
cd /data/wdt/1.6.23-1
# 执行重启命令
docker-compose restart

# 如果修改过配置项，需要通过如下方式重启服务：
docker-compose down
docker-compose up -d

# 查看服务状态

在服务器上通过命令docker ps查看服务状态，如果STATUS是Up则表示运行中。

# 查看容器下所有的服务
docker ps
# 如当前服务器进程过多，可以过滤只查看文档通的进程
docker ps | grep iwebeditor

# 浏览器验证服务状态

在开启服务两分钟后（初始化工作需要花费点时间）测试服务可用性。

浏览器访问http://文档通ip:端口/healthcheck，显示true表明服务正常启动。如未调整配置，文档通默认端口为80。

# 添加SSL（https配置）

如果协同OA外网是https，则文档通也必须是https，给文档通开放https主要推荐两种方法：

  • 第一种是在前置代理转发服务器（如Nginx）上统一管理SSL，强烈推荐此方案

  • 第二种是在文档通服务器放置SSL证书，由文档通内部的Nginx管理https，由于此方案后续扩展性一般，正常情况下不推荐

# 方法一：前置代理配置https（推荐）

如果协同OA通过Nginx部署了https，为了方便统一管理SSL，也可以把文档通的https配置到同一个Nginx代理服务上。

Nginx配置SSL很简单，相关配置代码可以直接参考“Nginx代理到文档通（https）”章节。

配置完成后，再根据用户不同网络场景进行产品侧的URL配置，相关配置方法可以直接参考“不同网络环境配置方案”章节。

前置代理的一个常见的网络部署关系如下图所示：

1731515633862.png

# 方法二:文档通内部配置https（方法一条件不具备时）

只有方法一“前置代理配置https”行不通的情况下，才推荐本方案。

1、必须将SSL证书文件重命名为tls.crt和tls.key，放入/data/vol/iwebeditor/Data/certs目录下（没有目录就自行创建）

2、在docker-compose.yml中ports节添加443:443，暴露服务的443端口给https

# 这里1.6.11-1是本示例的版本，项目上根据实际情况确认版本位置
cd /data/wdt/1.6.11-1/
# 编辑文件，添加端口
vim docker-compose.yml

1731469624813.png

增加SSL的端口后，文档通默认只能用HTTPS访问，如果期望HTTP和HTTPS并行需要同步调整docker-compose.yml中的一个参数，删除-DISABLE_HTTP_TO_HTTPS=true前面的#（注释符号）：

1736003966585.png

重启docker服务，验证功能：

docker-compose down
docker-compose up -d

如下是https网络部署示意图：

1731515195834.png

# 卸载删除文档通

如需要对当前文档通进行完整卸载、删除，可以使用本章节操作。

停用文档通服务：

先明确文档通的版本（可以通过docker ps -a查看iwebeditor版本），然后到版本目录下去停用服务：

# 这里1.6.11-1是本示例的版本，项目上根据实际情况确认版本位置
cd /data/wdt/1.6.11-1/
# 执行停用操作
docker-compose down

1728574417516.png

删除镜像：

找到所有文档通的images并逐个卸载：

# 通过docker images找到所有iwebeditor相关的镜像ID，逐个删除
docker images | grep iwebeditor
# 根据上一步查出来的IMAGE_ID执行删除操作
docker rmi image_id

下图是load了两个版本的文档通，逐个删除的示例：

1728574432698.png

删除挂载卷：

参考docker-compose.yml中的"volumes"模块配置，删除配置中的挂载卷文件

# 这里1.6.11-1是本示例的版本，项目上根据实际情况确认版本位置
cd /data/wdt/1.6.11-1/
# 查看docker-compose.yml中的"volumes"模块配置找挂载卷位置
cat docker-compose.yml

如下是挂载卷配置示例，可以看到文件放在/data/vol下：

1728574558926.png

1728574566507.png

# 根据挂载卷位置，删除整个iwebeditor挂载文件：
cd /data/vol/
rm -rf ./iwebeditor/

1728574575081.png

删除文档通文件目录（慎重）：

以上完成后可以清理掉文档通文件目录，但此步操作务必慎重！

一般文档通文件目录存放于/data/wdt，如果按照本手册操作，此目录下还存放了docker数据文件，千万千万别误删除了docker目录！docker之外的文件，一般可以删除。

删除前备份文档通版本的配置文件（主要是docker-compose.yml），对于再次配置服务，需要其中的数据。

1728574599724.png

# 文档通环境基本排查方法

如果按照文档完成了操作，文档通依然无法使用，请按如下方式排查问题并截图记录：

1、阅读命令查看服务状态章节，（如条件允许）重启下文档通服务，截图文档通服务状态：

2、阅读浏览器验证服务状态章节，通过访问浏览器返回的信息判断文档通是否正常运行，截图浏览器访问的状态：

3、阅读文档通授权章节，确保协同OA和文档通授权已经正确放置并生效，截图文档通授权文件的存放位置

4、阅读查询授权有效性章节，通过访问浏览器返回的信息判断授权是否生效，截图浏览器访问授权的状态：

5、阅读协同OA侧配置文档通在线编辑章节，确保配置信息已经全部录入，协同OA侧截图完整的文档通在线编辑配置信息，文档通侧截图JWT认证密钥信息

1728573844618.png

6、检查网络互通性，再次阅读"网络互通要求"章节，做详细的网络检查和配置！截图说明客户采用的是哪套方案。

7、查看本手册常见问题，寻找答案

8、参考文档通日志章节，将发生问题当天的日志提取出来，备注问题产生时间。

9、以上都未检查出问题，将所有截图信息、日志打包提供给致远支持人员分析。

# 更新升级（可选）

本章节适用于已安装文档通客户，需要升级文档通更高版本，按照本手册进行更新。

# 升级包检查

本步以文档通1.5.99.1升级为1.6.11.1版本为例。

首先需要将文档通最新版本的安装包拷贝到/data/wdt目录，以下示例是将最新的docker_amd64文件夹拷贝到/data/wdt目录的示例：

1728545281721.png

拷贝之后，可以参考“核对安装包完整性”章节，检查安装包完整性，相同则表示正常：

1728545379539.png

为了方便按版本管理文档通，我们统一建议对文档通的目录按版本进行命名：

# 继续回到/data/wdt目录下
cd /data/wdt
# 找到文档通的部署包，将其重命名为当前最新版本号名称（1.6.11-1是当前最新版本，后续程序如有更新，请使用最新版本号）
mv docker_amd64 1.6.11-1
cd 1.6.11-1/

注：以上命令中的1.6.11-1为最新安装包版本，如果后续部署更新高版本可以修改为相应版本号。

1728546230347.png

# 导入新的镜像包

上一步完成后，进入最新版本的安装包目录，将文档通最新程序导入镜像包，导入需要一定时间，耐心等待：

# 1.6.11-1是当前最新版本，后续程序如有更新，请使用最新版本号
cd /data/wdt/1.6.11-1
# 1.6.11-1是当前最新版本，后续程序如有更新，请使用最新版本号
docker load < iwebeditor_documentsystem_1.6.11-1.tar.gz

1728546875946.png

# 确定前一个版本的情况

  • 查看之前运行或配置的版本

docker ps -a

1728547097483.png

根据红框标注，可以知道之前版本的版本号为1.5.99-1，当前处于Up运行状态，对外的端口号为80。知道版本信息后，需要找到前一个版本的配置文件，主要是docker-compose.yml。

如果前一个版本是按照本手册做的部署，则配置文件应该位于/data/wdt/旧版本号/docker-compose.yml，更新新版本时，就要参照这个旧版本的配置文件做配置：

1728547839981.png

# 新版本文件docker-compose.yml调整

找到新版本的文档通docker-compose.yml文件，参考旧版本的修改记录进行调整：

# 1.6.11-1是当前最新版本，后续程序如有更新，请使用最新版本号
cd /data/wdt/1.6.11-1
# vi或vim命令修改当前最新版本的docker-compose.yml
vim docker-compose.yml

主要修改点参考前方安装部署章节中的“配置文件docker-compose.yml调整”，大概修改点有：

1、找到"volumes"模块，将旗下每一个路径前都增加一个"/data"（必做）

2、修改文档通端口（可选），参考旧版本配置，如未修改则忽略本步

3、配置JWT认证（必做），参考旧版本配置做调整

volumes模块的调整示例：

1728550952807.png

JWT的调整示例：

1728550935350.png

# 关闭前一个版本的服务

以上步骤完成后，进入旧版本的目录，终端执行停止旧版本服务的操作：

# 这里1.5.99-1是旧版本目录，项目上根据实际情况确认旧版本位置
cd /data/wdt/1.5.99-1/
docker-compose down

确认前一个版本已经关闭：

docker ps -a |grep iwebeditor

没有结果表示已正常关闭完成，可直接进入下一章节进行新版本的发布启动。

1728552533065.png

如果找不到前一版本的配置，可以结合docker stop和docker rm来移除容器，结合docker network list和docker network rm来移除网络，比如（f6d0715dd78d为docker ps -a 查到的容器ID）：

  • 移除容器
docker stop f6d0715dd78d
docker rm f6d0715dd78d
  • 检查网络,并移除未清理的网络（包含wisemedical-documentsystem-network名的相关网络，a2f0c3ebef0d为查到的网络ID）
docker network list
docker network rm a2f0c3ebef0d

# 开启新版本的服务

进入新版本的配置文件目录，终端执行启动新版本的文档通服务：

# 1.6.11-1是当前最新版本，后续程序如有更新，请使用最新版本号
cd /data/wdt/1.6.11-1
docker-compose up -d

1728553586443.png

# 验证新服务

验证新服务（服务有些初始化工作，启动后需要等大概一两分钟）

浏览器访问http://ip:端口/healthcheck ，显示true表明服务正常启动。如未调整默认配置，文档通默认内外部端口为80。

1728553774432.png

终端执行docker ps -a |grep iwebeditor可以看到文档通已经变成了新版本：

1728553868226.png

# 常见问题

# 初次部署不通过怎么办

1、通读本手册全部内容，尤其是部署、授权、协同OA配置相关内容，不要错过任何说明点，确保所有信息都按照手册要求做了部署配置。

2、按照"文档通问题固定排查方法"章节做完整排查，将排查过程截图，如果还未解决，将排查截图打包发给致远技术分析。

# 服务启动后连接不上服务

在服务器终端执行curl http://127.0.0.1/healthcheck 显示 Connection reset by peer

a. 可能容器配的ip段192.168.15.0/26和网络中的机器重复了

终端中执行

docker-compose down

修改docker-compose.yml中的网络，换一个不重复的

启动服务后再次测试

b. 可能机器异常关机导致

解决方法服务器终端执行

systemctl daemon-reload
systemctl restart docker.socket

如果提示Failed to restart docker.socket: Unit not found.请使用systemctl restart docker.service）,再次测试服务。

c. 可能docker版本过低

先执行docker ps -a|grep iwebeditor查出当前运行的容器id

再docker logs -f container_id，如果输出的都是不正常的运行，可能当前的docker不兼容，按组合键ctrl + c结束日志查看。

可以更新系统docker版本或用商务网盘提供的docker离线包安装，再次启动，如果还有问题，重新导入镜像，再次启动。

# 卸载麒麟内置docker重新安装后无法启动

卸载麒麟操作系统内置docker，安装离线包docker后，docker无法启用。

执行 systemctl status docker

执行journalctl -xe

没有有效的错误信息。

可以执行命令卸载：./uninstall.sh

重启操作系统，执行对应平台安装。

./install.sh 平台

平台表示如：x86_64 或者 aarch64，例如：./install.sh x86_64

# docker 网段与环境冲突

修改docker-compose.yml文件里的网段配置（iwebeditor-documentsystem-network）改成不冲突的网段和网关，然后重启docker-compose

docker-compose down
docker-compose up -d

# 镜像导入后，启动服务报错

docker: Error response from daemon: failed to create shim task: OCI runtime create failed: container_linux.go:318: starting container process caused "permission denied": unknown.

可能是系统中安装了podman，将其卸载，执行如下命令：

apt remove podman 或 yum remove podman

# WARNING: IPv4 forwarding is disabled. Networking will not work

重启docker服务

sudo systemctl restart docker

# 本地域名导致编辑服务失败

在有些网络配置了本地域名，有时并没有让docker容器感知，比如:通过修改的本机hosts文件,这样编辑服务不知道这个情况，导致浏览器打开文档中长时间转圈，最终下载文件失败，如下图：

那么可以修改启动配置文件docker-compose.yml，有两种方式修改：

1、将dns节前的注释去掉（井号），然后在其下添加dns服务地址，然后重启服务

2、给extra_hosts添加一项自定义的域名到 IP 地址映射，然后重启编辑器的服务（参考2.6章节）。

# 有些网络只启用了IPv6，导致服务失败

编辑 /etc/docker/daemon.json(没有就创建一个)，添加启用IPv6的配置：

{
  "ipv6": true,
  "fixed-cidr-v6": "fd00::/80",
  "experimental": true,
  "ip6tables": true
}

终端中执行：sudo systemctl restart docker

然后修改启动配置文件docker-compose.yml，将iwebeditor-documentsystem-IPv6-network下的enable_ipv6注释去掉，最后重启编辑器的服务。

# 容器启动后文档通服务不正常

容器启动后，连接不上服务，docker logs查看容器启动过程，看到各个服务都不正常，比如：

1725968024627.png

先按文档检查配置是否存在问题，如果不行，换docker离线包安装再试。

如果不行，可能是系统有的软件不兼容，可以按如下排查：

运行docker info，查看输出是否有报错。

如果没有报错，和文档通离线包的输出比对，如下：

amd64

1725968067974.png

arm64

1725968133481.png

系统中如果有旧的runc（容器的一种运行时）没有清理，优先运行了导致问题。

本案例中执行：

  • 查看runc版本，与上图runc版本是否一致，一致则正常

runc --version

  • 查看runc路径，如果有旧版本可尝试按以下操作处理。

which runc

其runc位于/usr/local/bin/下面，正常应该位于/usr/bin，位置不重要，重要的是runc的版本不能旧。（如果是正常版本位于/usr/bin下不要执行下面的mv操作，执行后docker服务可能无法启动。）

执行：

systemctl stop docker
mv /usr/local/bin/runc /usr/local/bin/runc-bak
systemctl start docker

然后启动文档通服务，检查服务是否正常。

# 容器内文件成了可执行导致服务启动不了

问题现象：docker logs -f 容器id查看到报错信息如下

1725968311346.png

docker迁移存储时，执行了不该有的操作 chmod 777 等操作（正常按手册操作没有此操作），和这个镜像包的权限有关，文件不能有执行权限，导入的文件变成可执行权限导致报错

解决方法：

1、chmod -x 文件名，去除文件名，例如：

chmod -x iwebeditor_documentsystem_1.5.99-1.tar.gz

2、参考2.6章节关闭服务

3、docker image list 查看镜像列表，删除iwebeditor镜像

1725968171693.png

执行:docker rmi 0c4f94e16da9 （0c4f94e16da9 为上图中的image id）

4、参考2.4章节导入镜像按文档重新操作

# 启动文档服务报错：services.iwebeditor-documentsystem.environment must be a mapping

docker-compose up -d 执行后保如下截图错误:

1726028713621.png

编辑docker-compose.yml文件时，内容格式有问题导致

如图少了减号和空格：

1726028793275.png

解决方法：编辑时按手册说明及截图操作，保证格式正确无误。

编撰人：het、shenlq

快速跳转

← 文档通安装维护手册（Windows） →