# 文档中台V7版本部署操作手册

# 免责声明

1、当前的金山V7-v7.1.2308版本,集群部署只分担负责压力,无法支持高可用场景。 2、如项目上有高可用场景需求,请单独咨询金山哪个版本支持高可用,最终已金山回复为准。

# 支持协同版本

OA 8.1sp2-12月修复包及以后的版本,才适配金山文档中台V6&V7版本。部署时一定要先确认OA版本!

# 部署说明

# 1.1 部署方式

通过执行命令方式进行文档中台服务部署;

# 1.2 环境要求

可参考金山weboffice文档资料:环境部署要求(适用于V6/V7) (wpseco.cn) (opens new window)

# 1.3 特别说明

**1、服务器CPU核数必须与授权文件CPU核数保存一致,否者无法进行安装.

2、Weboffice中台不支持在IPV6网络使用。

3、weboffice中台不支持直接克隆使用。会导致环境异常,慎重!!!!

4、Weboffice中台和OA需在使用https和http保持一致,换言之,OA使用https访问,则weboffice中台也需配置成https访问,若OA使用http访问方式,则weboffice也配置成http。

5、要使用Weboffice中台服务,必须确保:**

1)OA服务器和中台服务器之间能互相访问;

2)客户端(即用户登录OA的电脑端)能访问到中台地址,M3手机端、微协同也一样,参考第6节关于weboffice外网访问的方案。

5、务必保证中台服务器时间同OA服务器一致。

# 部署准备

# 2.1 下载部署包

下载地址:

Docker部署(x86版本):

链接:https://pan.baidu.com/s/1tGwOsWuW3Ra9IVls_KI2oA
提取码: kusm

根据实际部署版本要求,需要下载如下部署包文件:

  • docker部署包:release_kubewps_lite_v7.1.2308.20230823.381.tar.gz

  • md5值:9d79f9f03e9bffc205284bc08db0ab8e

  • 文档中台部署包:release_opendoc_lite_v7.1.2308.20230823.381.tar.gz

  • md5:b60a7fc1985e746b7e6f58ef24bea462

# 2.2 上传部署包

为避免权限类问题,请使用root用户操作!!!

将本地的部署包(已实际下载为准)通过xshell中自带的xftp,上传至服务器。

  • 进行md5校验,MD5值一样,才能进行部署操作。

  • 解压文件,放入对应目录。 默认数据盘为data目录,需将文件解压至data目录
 tar -zxf release_kubewps_lite_v7.1.2308.20230823.381.tar.gz -C /data/
 tar -zxf release_opendoc_lite_v7.1.2308.20230823.381.tar.gz -C /data/kubewps/apps/

# 2.3 部署环境检查

打开连接:环境检查指导 (wpseco.cn) (opens new window),按照金山文档步骤进行检查操作。

适用版本范围:V5 & V6 &V7 & xc & x86

注意:首次部署检查应为全部通过,才能进行后续部署安装。

# 部署安装

# 3.1 安装部署平台

在/data/kubewps目录下执行 bash install.sh /data ( /data是指配置的数据目录,默认为/data),并按要求输入yes/no。Yes为继续安装,如果数据目录不符合要求请输入no取消安装。出现以下界面表示部署平台安装成功:

选择部署方式:2,命令行部署

安装完部署平台后,在服务端执行docker ps 查看目前运行的容器实例,必须有kubewps容器。宿主机执行kubewps命令进入kubewps容器,命令执行完成后,显示如下界面表示进入kubewps容器成功。如下:

卸载容器化平台:

若要执行卸载,请确定应用中间件是未安装或已卸载状态。

在/data/kubewps目录下执行 bash uninstall.sh /data (/data是指配置的数据目录,默认为/data),完成卸载操作。

# 3.2 安装应用

# 3.2.1 基础服务配置文件

我们在部署包/data/kubewps/conf/templat/中提前准备部署模板文件,如部署单机1个节点:

#部署机执行
cd /data/kubewps/conf
\cp template/kubewps.1.conf kubewps.conf

编辑kubewps.conf配置文件,只需要修改填写其中的 hosts中的主机ssh连接信息

如部署集群3个节点:

#部署机执行
cd /data/kubewps/conf
\cp template/kubewps.3.conf kubewps.conf

编辑kubewps.conf配置文件,只需要修改填写其中的 hosts中的3台主机ssh连接信息

# 3.2.1 首次登录修改密码

修改密码可以执行wpscli任何命令,此处以wpscli host add为例,命令执行完成后出现下列截图为密码修改成功,第一次登录默认密码:Wps@123456

# 3.2.3 开始安装中间件

1.添加主机

#kubewps容器内执行
wpscli host add

2.执行环境检查(不执行无法进行下一步安装)

所有检查项的状态都必须显示通过或者警告,当检查结果出现警告时可以按照处理建议进行修复,如果已经提前预知并且接受此风险可以继续部署,当出现不通过时禁止执行后续步骤。

环境检查完成后会生成一个企业唯一码,请保存所有机器的企业唯一码(机器码)同步申请许可。

通过后根据输出的机器码提前去申请授权。若环境检查不通过则参考《环境修复》对部署环境进行修复。

#kubewps容器内执行
wpscli env check

3.安装paas平台

执行命令完成后,出现本次操作执行完成回显,表示执行成功,否则即为失败,禁止执行后续步骤

#kubewps容器内执行
wpscli paas install all

# 3.3 weboffice业务应用安装

注:安装应用前请提前规划好网络,注意是否需要将weboffice中台服务开通外网访问,取决于:客户端设备(、M3、微协同等)是否需要通过外网访问OA。

因为安装中台应用后,再更改app.conf配置,需卸载应用重新安装才能生效。

1、修改app.conf文件(必须做对应调整)

参照readme.app.conf模版,编辑/data/kubewps/apps/opendoc_lite.7.1.2308.381 /app.conf根据实际情况进行修改。一般来说只需调整,company_name和domains,若使用了Nginx代理访问金山,必须配置proxy_server为代理后的地址(具体Nginx配置见3.6说明),其余可默认。

特别说明:company_name的值与许可码授权相关,请申请许可码时注意保持一致。

参考配置:

图中配置为主机ip和域名同时生效(即可分别使用ip和域名访问),如果使用了Nginx做https会话卸载,必须app.conf里指定代理地址,若安装后修改了app.conf的配置则需要重新安装weboffice应用生效。

  1. 配置项:company_name <说明>:公司名称,前期要确定好,后期修改不方便;公司名称建议与销售报备的'客户名称'一致,且必须与申请授权表单的'项目单位名称'保持一致
  2. domains配置项: <说明>:
  • Scheme:访问协议是http;
  • domain:表示文档中台服务的域名;(支持IP、域名)
  • proxy_server: 如果前端有代理服务器,需要填写代理服务ip,比如http://www.baidu.com或者https://www.baidu.com:8080,如果没有代理,请留空;
  • port: 内网监听端口 (默认80);
  • path:配置path路径方式(留空即可)
  • encryption:网关层接口加密(默认配置false)

2、安装weboffice应用

安装应用时7.1.2308.20230823 需要按照实际的版本进行替换。 执行命令完成后,出现本次操作执行完成回显,表示执行成功,否则即为失败,禁止执行后续步骤

#kubewps容器内执行
安装:wpscli app install opendoc_lite 7.1.2308.381
#执行对照下图,如果状态一致,表示服务安装完成:
wpscli app show

# 3.4 ETCD配置调整

配置说明:解决OA调用金山中台不会主动触发下载文件、套红不显示/无法套红等问题。

操作步骤:

#进入kubewps容器
kubewps> etcdctl get /config/editserver --print-value-only > editserver.etcd
#编辑editserver.etcd文件,修改 CheckUpdateVersion = true
vim editserver.etcd 
#执行修改
kubewps> etcdctl put /config/editserver < editserver.etcd

如果是集群3个节点,其余2个节点也需要调整:

  1. 分别进入其余2个节点的etcd容器

查询etcd容器:docker ps |grep etcd

进入etcd容器:docker exec -it 容器id sh

#执行
etcdctl get /config/editserver --print-value-only > editserver.etcd
#执行:
sed -i '/^CheckUpdateVersion/s/false/true/g' editserver.etcd
#查询是否修改CheckUpdateVersion = true
#执行:
etcdctl put /config/editserver < editserver.etcd
#提示OK,执行成功。如图:

# 3.5 卸载服务

# 3.5.1卸载应用

卸载应用时7.1.2308.381需要按照实际的版本进行替换。执行命令完成后,出现本次操作执行完成回显,表示执行成功,否则即为失败,禁止执行后续步骤

#kubewps容器内执行
wpscli app remove opendoc_lite 7.1.2308.381

# 3.5.2卸载paas平台

执行命令完成后,出现本次操作执行完成回显,表示执行成功,否则即为失败,禁止执行后续步骤

#kubewps容器内执行
wpscli paas remove all

# 3.5.3卸载部署平台

#部署机执行
cd /data/kubewps
bash uninstall.sh

# 3.6 使用Nginx代理访问中台(非必要)

若使用Nginx做代理,配置https访问金山中台,做https证书卸载: a.基础环境说明: A:代理地址:https://test.open.wps.cn (以客户环境为准) B:中台服务内网地址:http://192.168.1.111 (以客户环境为准) 期望达到的目的是访问A时,代理到B,A到B做SSL证书卸载;

b.代理服务器需要做的配置:

#nginx.conf配置参考:
worker_processes auto; 
worker_rlimit_nofile 20960; 
error_log  logs/error.log  crit;
events {
	worker_connections  4096;
	multi_accept on;
	accept_mutex on;
	accept_mutex_delay 500ms;
}
http {
        server_tokens off;
        sendfile on;
        tcp_nopush on; 
        tcp_nodelay on;
        access_log off;
        include       mime.types;
        default_type  application/octet-stream;
        keepalive_timeout  300;
        client_max_body_size 10240M;
        # 开启gzip
        gzip on;
        # 1KB以下不进行gzip
        gzip_min_length 1k;
        # 设置gzip的buffer
        gzip_buffers 4 16k;
        # 设置gzip的等级,等级越高压缩比例越大,越消耗cpu
        gzip_comp_level 3;
        # 设置gzip的压缩类型
        gzip_types text/xml text/plain text/css text/javascript application/x-javascript application/javascript application/xml application/json;
        # ie6及以下版本浏览器不进行gzip
        gzip_disable "MSIE [1-6]\.";
        # 定义一个upstream,名称(docs_servers,可更改)、及其服务集(server,10.3.4.85为中台服务ip,80为服务端口,以实际情况进行修改)
        upstream docs_servers{
			    server 10.3.4.85:80;
        }
		# https配置
		server {
	        listen 443 ssl;
	        server_name webofficetest.seeyon.com;
	        ssl_certificate     /home/nginx/ssl/_.seeyon.com_bundle.crt;    #https证书文件路径
	        ssl_certificate_key /home/nginx/ssl/seeyon.com_RSA.key;         #https证书文件路径                   
	        # 控制ssl协议
	        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

	        # 设置字符集
	        charset utf-8;
		  # 设置location
	location / {
		proxy_pass http://docs_servers;
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-NG-PRX-Host $remote_addr;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";
		proxy_set_header X-Forwarded-Proto   "http";
		proxy_redirect     off;
		proxy_connect_timeout 300;
		proxy_read_timeout 300;
		proxy_send_timeout 300;							 
                     }

	location /weboffice/websocket/v2 {                      #要放开websoctet,否则页面无法正常编辑和预览
						proxy_pass http://docs_servers;
						proxy_redirect off;
						proxy_set_header X-Real-IP $remote_addr;
                     	proxy_set_header X-Forwarded-Proto   "http";
                     	proxy_set_header Host                $host;
                     	proxy_set_header X-NG-PRX-Host $remote_addr;
                     	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                     	proxy_http_version 1.1;
                     	proxy_set_header Upgrade $http_upgrade;
                     	proxy_set_header Connection "upgrade";
		}
			     error_page   500 502 503 504  /50x.html;
			     location = /50x.html {
			     root   html;
			     }
		           }
      }

c.中台服务配置,修改/app.conf文件,参考如下:

# 4 申请许可证

许可证是对应合同签约包含的套餐及权益信息,许可证文件不可手动修改,仅能通过系统申请。许可证构建服务仅限指定人员操作,获取许可证文件后,可以导入部署服务器中执行后即可生效。详细操作如下:

  1. 获取企业唯一码:

服务器上执行命令:

sudo cat /sys/devices/virtual/dmi/id/product_uuid

机器码获取工具分别在每台机器获取,以分号拼接作为企业唯一码;

  1. 申请许可码:试用许可码可直接找金山申请,填写相关信息由金山审核后发送到邮箱;正式许可码找公司商务提供。

试用许可码申请地址:https://f.wps.cn/w/X0W0Qv8a/ (opens new window)

  1. 导入许可证

访问ip+端口+/micsweb/sys/login,首次登录需默认账号密码: wpsadmin / Wps@123456

账号密码进入系统后台页面,并修改登录密码。

  1. 开启demo,验证中台服务预览/编辑功能是否正常 参考金山demo使用说明: https://p.wpseco.cn/wiki/doc/63423f2ad7c60f8bf1fd88e2

# 5 金山中台配置&OA配置

# 5.1 中台配置

# 5.1.1登录中台

首先登录金山中台管理界面,入口为http://ip:port/micsweb/sys/login, 账号密码以及服务器具体IP和端口需要向金山中台服务搭建人员既运维人员索要。

# 5.1.2配置应用

# 进入应用配置页面

点击左侧"集成应用"子菜单(图1中①处),并在弹出的集成应用界面中选择任意空应用或要修该的应用,点击"详细"操作按钮(图1中②处)。

图1

# 修改基础信息并记录应用包名和应用密钥

进入应用详细界面, 点击"基础信息"子菜单(图2中①处)可以编辑应用包名和应用描述。

同时该界面提供的应用包名(图2中②处)和应用密钥(图2中③处)需要记录下来方便后续配置。

*该两条数据之后在配置"OA环境配置"时"应用包名"对应"appId","应用密钥"对应"appKey",下文不再重复说明。*

图2

# 配置应用依赖

点击左侧"应用授权"子菜单(图3中①处),进入应用授权配置页面,点击"预览编辑配置"操作按钮以修改功能列表下的"在线编辑"(图3中②处)和"在线预览"(图3中③处)两个功能。

图3

点击"预览编辑配置"之后,会弹出"预览编辑回调配置"页面(如图4),由于"在线编辑"和"在线预览"配置一致,故本文只展示"在线编辑"配置,在线预览配置保持一致既可。

图4

其中的配置项从上至下依次配置为:

  1. 回调域名:http://ip:port/seeyon/webOffice/v6 (opens new window)

其中的ip:port为OA地址+端口,该地址必须保证OA服务器和中台服务器均能访问。v7版本回调地址中url也是配置v6。

  1. 获取文件元数据:/v1/3rd/file/info

  2. 获取用户信息:/v1/3rd/user/info

  3. 获取文件状态:/v1/3rd/file/online

  4. 上传文件新版本:/v1/3rd/file/save

  5. 获取指定版本信息:/v1/3rd/file/version

  6. 文件重命名:/v1/3rd/file/rename

  7. 获取所有版本信息:/v1/3rd/file/history

  8. 回调通知:/v1/3rd/onnotify

特别注意的是:拷贝时请勿含有任何空格

配置完成后,点击确认既可保存。

# 配置其他依赖

由于V6/V7版本强制要求部分接口的回调通知, 所以图中格式转换配置也需要配置回调地址和接口

配置步骤:点击其中一个"格式转换配置"进行修改。其他的会同步修改。(如下图):

配置其中:

1.回调域名:http://ip:port/seeyon/webOffice/v6 (opens new window)

其中的ip:port为OA地址+端口,该地址必须保证OA和中台服务器均能访问。v7版本回调地址中url也是配置v6。

  1. 回调通知:/v1/3rd/file/view/notify
# 配置应用回调

点击左侧"应用设置"子菜单并进入应用证书回调设置。配置回调地址。回调地址为致远OA服务器网络地址,配置为OA服务的IP:Port或域名。可以点击测试判断应用是否可以回调成功

# 配置跨域白名单

点击最左侧菜单的"配置管理"下"跨域白名单",将OA的访问ip或域名填写到对应位置。建议将OA和金山的访问ip和域名都加上。注意:若有微协同、致信也需要将域名地址添加;宁可多配,也不能漏配。跨域白名单不要带http/https和端口,只需要填ip或者域名,如图:

图5

# 5.2 OA环境配置

# 5.2.1 在线预览配置

配置文件为.../base/conf/systemCtp.properties。

#在线预览
officeTrans.type=wps
officeTrans.wps.appId=AK20210611GISDDJ(金山应用APPID,根据实际情况修改)
officeTrans.wps.appKey=0b22738e5c07fd2e2d1b829c12e536e7(金山应用APPKEY,根据实际情况修改)
officeTrans.wps.openServiceUrl=https://kdocs.seeyoncloud.com/open(金山预览服务地址,注意以地址open结尾,参考下述常见3种场景配置)
officeTrans.wps.callBackUrl=http://10.6.3.63(OA为集群请填写负载均衡地址)/seeyon/webOffice/v6

seeyonconfig可视化配置位置:

# 在线编辑配置

配置文件为.../base/conf/plugin.properties。

#在线编辑
weboffice.enable=true
weboffice.networkType=PRI
weboffice.url=https://kdocs.seeyoncloud.com/open(金山预览服务地址,注意以地址open结尾,参考下述常见3种场景配置)
weboffice.appId=AK20210611GISDDJ(金山应用APPID,根据实际情况修改)
weboffice.appKey=0b22738e5c07fd2e2d1b829c12e536e7(金山应用APPKEY,根据实际情况修改)
weboffice.callBackUrl=http://10.6.3.63(OA为集群请填写负载均衡地址)/seeyon/webOffice/v6

seeyonconfig可视化配置位置:

在线编辑/在线预览的配置,最需要注意的是:

OA在不同的客户端访问场景下,配置唯一的区别就是officeTrans.wps.openServiceUrl和weboffice.url 这2个中台地址的配置。

必须根据OA的部署和客户端(PC、M3、微协同等)访问场景(内网/外网,http/https),进行配置。

Weboffice服务和OA需在使用https和http保持一致,换言之,OA使用https访问,则weboffice服务也需配置成https访问,若OA使用http访问方式,则weboffice服务也配置成http。

注意点:OA服务器上必须要能访问通上面配置的中台地址

# 场景1:客户访问OA只通过内网IP访问(http)

客户访问OA只通过内网IP访问,包括:PC端、M3端、微协同等。 officeTrans.wps.openServiceUrl和weboffice.url 这2个配置weboffice的内网地址

# 场景2:客户访问OA通过外网IP/域名访问(http)

客户访问OA通过外网IP访问,包括:PC端、M3端、微协同等,其中之一。 officeTrans.wps.openServiceUrl和weboffice.url 这2个配置weboffice的外网地址(IP或域名)

还需要注意:OA服务器必须要能访问配置的weboffice外网IP或域名

如果不能访问,请客户调整网络。域名访问可通过配置内网DNS,或者OA主机添加hosts解析解决,linux服务器测试如下:

# 场景3:客户访问OA通过https访问

客户访问OA通过https访问,包括:PC端、M3端、微协同等,其中之一。

officeTrans.wps.openServiceUrl和weboffice.url 这2个配置weboffice的https地址。

还需要注意:OA服务器必须要能访问配置的weboffice外网IP或域名

如果不能访问,请客户调整网络。域名访问可通过配置内网DNS,或者OA主机添加hosts解析解决,linux服务器测试如下:

# 6. 部署常见问题

# 问题一 、环境检查不通过

download

检查不通过的请参照《操作系统环境修复FAQ》进行修复:

https://kdocs.cn/l/cfVHFxZiVAgi (opens new window)[金山文档] Centos 操作系统环境修复 FAQ.pdf

# 问题二、添加host主机时,提示需要输入密码

download

原因1:客户服务器配置了禁止使用密钥免密登录

解决方法:编辑SSH服务配置     vim /etc/ssh/sshd_config

重启SSH服务:service sshd restart

原因2:客户服务器免密ssh用户家目录权限错误

解决方法:sudo chown -R wps:wps /home/wps

原因3:添加host主机正常,但是env check环境检查时报错:

download

可通过查看系统日志:、

系统日志报错 userauth_pubkey: key type ssh-rsa not in PubkeyAcceptedAlgorithms [preauth]

这是因为 OpenSSH 7.x 以上默认关闭了 ssh-dss 了,可通过 ssh -V 查看版本。

解决方法:vim /etc/ssh/ssh_config
找到 # Host * 把注释去掉,然后下面添加一句:

PubkeyAcceptedKeyTypes=+ssh-dss

修改并保 即可。

# 问题三、外网访问金山地址,返回:result" :"Empty x_origin","msg" :"not find x_origin

原因分析:外网的IP/域名未配置到app.conf

解决方法: 1、修改app.conf,添加域名/外网IP的配置,参考配置如下:

2、卸载中台应用,重新安装

kubewps容器执行:
卸载:wpscli app remove opendoc_lite xx.xx.xx
安装:wpscli app install opendoc_lite xx.xx.xx

# 问题四、预览/编辑报错:code":40100001,msg":"sign check fail: x-auth mismatch"

原因分析:客户环境的appId和appKey在配置的时候是手动输入/截图后复制的内容,导致有肉眼无法看出的差别,导致截图报错:签名生成错误。

解决方法:从金山后台应用详情页面,鼠标右键选中直接复制,粘贴到OA配置项中,避免手动输入。

# 问题五、预览报错:参数错误,code:40000

问题分析:配置问题,OA环境配置和中台回调地址配置url中,小写的v6配置成大写V6

解决方法:调整配置,将回调地址url中V6改成v6。重启OA解决。

# 问题六、附件无预览按钮 {#问题六附件无预览按钮 .list-paragraph}

原因:

1、OA加密狗无officetrans插件 2、系统后台未开启Office转换

解决方法:重新申请加密狗。

# 问题七 预览编辑报错:文件转换失败,原因:配置错误

原因分析:此问题是相关配置错误导致,需要进行配置检查

1、检查中台应用包名和应用密钥,是否与OA上配置的appId和appKey一致。

  1. 检查预览编辑回调配置地址是否正确

3、检查OA环境配置,参考5.2章节

上述检查完,如果未发现问题,查看ctp.log日志,是否有相关报错

可以看到日志中有ERROR相关报错:code":40100001,"msg":"unregistered application info" 仔细看可以看出appid的值多了空格,说明OA环境上配置的appId值后面是有空格的,肉眼检查配置无法排查出。导致配置问题

解决方法:去掉OA环境配置中appid配置项后面的空格,检查其他项是否也存在空格问题。重启OA服务

# 问题八、预览编辑页面报错:csrf error

现象1:

原因分析:中台未配置跨域白名单

解决方法:检查跨域白名单是否配置:将OA地址加入白名单

现象2:

原因分析:OA的回调地址配置错误

解决方法:检查金山后台配置页面应用的回调地址是否正确

# 问题九、预览编辑报错:DriverNetError

原因分析:中台服务器访问不通OA回调地址,查看中台回调日志:docker logs -f --tail 100 docs-document-operate 接口报错:状态码500。

中台服务器上测试连通性,不通

解决方法:

1、检查OA回调地址是否正确

2、客户检查网络并调整,使中台服务器能访问OA地址

3、以上2点检查调整后,重启中台服务:systemctl restart docker

创建人:zhangshuang
修改人:zhangshuang

快速跳转