# 协同管理软件产品升级指导手册
PS：本文档适合于V5产品升级。如客户是A8 350升级，则建议参考关联手册 (opens new window)做升级。
# 升级关键动作放最前面
| 关键阶段 | 必做动作 | 作用 | （不做）可能影响 |
|---|---|---|---|
| 正式升级前 | 做一轮或多轮预升级测试验证 | 1、提前发现升级问题，有些问题还要打补丁包 2、预估升级时长，方便做正式升级时间规划 3、熟悉升级过程，以提高正式升级效率 | 某项目未做测试升级，直升报错，又尝试走弯路分阶段升级，结果依然失败。最后按照规范的测试修复问题再升级才解决问题。延期了2周才正式升级成功，伙伴被客户提出了延期赔偿。 |
| 正式升级前 | 备份注册表、备份数据库 | 备份是为了方便升级失败时做回滚 | 某项目未做升级前备份，升级失败，失败问题需要打补丁后还原数据库重新升级。由于没备份升级前的库，只能还原两周前的备份数据库，导致客户丢失了两周数据，扣了项目组的款。 |
| 程序升级刚结束 | 检查升级日志是否存在错误 | 需要分析错误信息，由研发判断是否要重新升级 | 某项目升级结束时，忽略了升级日志的一个错误，在投产后才发现有问题，由于忽略的错误需要回滚打补丁重新升级，导致2天返工，客户还丢了投产后的1天数据（升级后数据无法保留）。 |
| 程序升级后、启动OA前 | 备份数据库 | 如果是V7.1之前版本（不含7.1）升级上来的客户必须备份数据库，启动OA后还会做公文的二次升级 | 某5.6SP1项目升级结束后，忘记备份升级后的数据库，启动OA进行公文升级失败。问题原因是一条数据异常导致公文升了一半异常，必须回滚数据库修正数据后重新升级。因为项目组忘记备份升级后的库，导致需要重新从5.6SP1升级开始，此问题导致项目组一个通宵的投入白白浪费，打乱了后续所有计划。 |
| 投产前 | 环境检查工具扫描性能问题 | 投产前使用环境检查工具扫描下服务器配置，针对潜在性能问题进行调优，防止投产后出现卡慢问题 | 某项目升级后忽略了环境检查工具扫描，导致升级后第一个工作日上午反复出现无法登录、打开提交流程慢等性能问题，经过环境检查工具扫描发现JVM配置过低、缺失索引等严重问题，修正后问题后立刻消失。此问题导致客户信息中心当天投诉电话打爆了。 |
# Ⅰ 事前
# 一、先做测试升级
还原近期的生产数据到测试环境，做一次测试升级，确保提前发现升级过程问题：
- 使用生产数据库最近一次备份数据做测试，确保数据接近生产
- 不要拷贝生产的服务器配置，避免测试环境连接到生产数据库，造成事故
- 测试升级需要包含客户定制开发，确保升级后定制开发功能可用
- 测试升级过程中遇到的所有问题及解决方案全部在记录在案，确保生产规避风险
# 二、环境和工具准备
测试升级通过后，就可以着手准备正式升级信息。
（1）确保升级程序所在服务器硬件性能应尽量高：配置不得低于8c16g，磁盘读写良好（吞吐量100MB/s以上，qps大于600，io队列不高于1，单次io耗时不超过15ms）
（2）操作系统权限：建议管理员权限（或对应用目录有读写权限，注册表修改权限等）；数据库权限：dba权限或对oa库有全部操作权限
（3）提前准备好升级后的加密狗
（4）下载最新的升级安装程序等
（5）必须下载最新的环境检查工具 https://support.seeyon.com/cbo_cptjxx.html?id=1732642082402603010
（6）准备最新的部署手册，最好直接使用开放平台手册（实时性高） https://open.seeyoncloud.com/v5doc/34/
（7）（如存在客开）提前准备好升级后版本的开发补丁
环境基线配置检查-集中部署参考：https://open.seeyoncloud.com/#/faq/faq/v1/share?url=Z2JySmU+Mjg4 (opens new window)
环境基线配置检查-分离部署参考：https://open.seeyoncloud.com/#/faq/faq/v1/share?url=Z2JySmU+Mjg5 (opens new window)
（8）信创环境检查操作系统的JDK版本（通过java -version命令查询），建议使用不低于标准产品适配的OpenJDk小版本【各版本基础信息 (opens new window)】，如果发现java的version低于标准产品适配的版本，可以联系操作系统厂商提供一个较新的JDK。
检查JDK很关键，不推荐使用操作系统预装的，操作系统预装可能只是JRE，并且版本很低，会造成各种莫名问题！
# 三、升级计划
做好完整的升级计划，包括回归策略：
（1）确认升级路线，尽量先升级后转版转库，升级升迁转库转版参考 https://open.seeyoncloud.com/v5doc/142/331.html
（2）制定数据库、应用目录、附件、注册表等备份回滚策略
- 数据库备份恢复建议提前测试验证，保证方案没有问题，不要用navicat工具备份恢复
- 信创环境建议备份整个中间件目录及应用目录（日志无需备份）
- 附件备份可以使用rsync等工具进行同步，支持增量
（3）预估升级时间（参考测试升级耗时），尽量预留多一点时间，避免时间紧张导致无法升级完成
（4）确认升级方式，制定升级策略：非信创需要图形化升级、信创支持图形化工具或命令行升级
# 四、发起升级护航支持单
节假日、周末或晚上升级，提前2天发起技术服务支持单-升级护航流程，确保总部预留资源职守：
- （如发过支持单）升级阻塞，及时联系总部支持人员确认问题
- （如发过支持单）升级完成时安装程序界面提示升级可能存在问题，及时联系总部支持人员检查问题
总部不承接或有偿支持：
- 未发过支持单的升级紧急问题处理，占用非工作时间处理问题均结算支持成本
- 没有做升级日志检查、忽略异常提醒，直接投入生产，投入使用后才发现问题需要修补数据场景，此类场景请自行做回滚处理
人为升级失误导致的总部资源投入均结算支持成本
# 五、升级前生产环境检查
在执行升级前，必须做一次环境调优，因为配置不足导致升级失败或升级缓慢案例比比皆是：
（1）使用前面章节提前下载的“环境检查工具”，对生产环境做检查，按照推荐调整参数：
- 系统参数调优，最大打开文件数（/etc/security/limits.conf 65535）
- 物理内存:swap 等于 1:1+
- 内核参数vm.swappiness配置为10~30
- nfs挂载参数等等
（2）数据库配置调优，升级操作数据库压力较大，适当调大参数能提升效率：
- 参考升级部署手册或在线文档调整数据库参数 https://open.seeyoncloud.com/v5doc/142/1184/144.html
（3）参考安装部署手册备份升级前的数据库，不要用navicat工具备份
（4）参考安装部署手册备份升级前的注册表
# Ⅱ 事中
本阶段是执行安装程序阶段，升级程序会先备份现有OA目录、再执行数据升级，每个阶段如存在问题，需要及时分析排查。
# 1、升级前手动剪切走LOG日志
升级程序会先备份现有OA目录，该目录下的日志文件过大会影响备份速度，建议安装升级前，手动将日志文件夹拷贝到ApacheJetspeed目录之外：
- 可手动迁移日志文件夹一：ApacheJetspeed/logs_sy
- 可手动迁移日志文件夹二：ApacheJetspeed/logs
手动拷贝方式：Win使用剪切、Linux使用mv命令。
# 2、升级前杀毒软件白名单
Windows Server用户需要关注自己安装的杀毒软件情况，如有安装杀软，建议打开杀软配置，将OA安装程序目录加入白名单，避免误杀。
同样，升级后也需要关注杀毒软件情况，将安装后的目录文件放入杀软白名单，某些杀软会误将可执行程序当作木马给删除，导致不可用。
如果客户安装的是个人版的360杀毒软件，如发现存在误删的情况，建议卸载，更换为火绒杀毒等其它杀软。[【参考案例】](【启动问题】OA无法启动 ，启动窗口闪退 https://open.seeyoncloud.com/#/faq/faq/v1/share?url=Z2JySmU+MjE5Mw== "【参考案例】")
# 3、定期检查升级日志输出
以上图例就是正在升级过，执行过程中可以通过日志观察进度：
非信创工具安装升级过程中，升级日志存放于安装包目录data/libs下
信创部署工具，升级日志存放于信创部署工具目录下：upgrade.log、deploy.log
以非信创为例，查看升级进度方法：通过安装包目录data/libs/all.log日志，查看安装升级进度，Linux可通过tail -f all.log查看日志，如日志持续滚动输出则表示正常执行。
# 4、升级缓慢检查一：分析jstack
如果发现all.log长期卡在某个升级动作上，可以通过Java的jstack来检查程序执行到什么代码位置了：
Windows找到OA安装包jdk/bin目录，由如下命令导出线程dump：
jstack.exe [升级程序java进程pid] >> [线程dump文件名01].txt
# 间隔1分钟再执行一次，执行3~5次：
jstack.exe [升级程序java进程pid] >> [线程dump文件名02].txt
Linux找到OA安装包jdk/bin目录，由如下命令导出线程dump：
./jstack [升级程序java进程pid] >> [线程dump文件名01].txt
# 间隔1分钟再执行一次，执行3~5次：
./jstack [升级程序java进程pid] >> [线程dump文件名02].txt
# 5、升级缓慢检查二：数据库
-- 数据库工具连接OA数据库，执行如下语句检查进度
select * from update_data_log order by fdatetime desc;
查询数据库活动会话，sql执行状态，判断升级程序是否正常运行，参考在线文档：https://open.seeyoncloud.com/v5doc/142/1184/318.html
检查活动会话的sql语句是否长时间没有变化，或者没有活动sql执行，此时可能升级异常了
# 6、升级完成：检查升级日志
| 序号 | 分类 | 类别 | 检查项 | 检查要求及标准 |
|---|---|---|---|---|
| 1 | 高频问题 | 安装部署结果 | 安装程序日志检查（升级） | 禁止升级失败不还原数据重复升级同一数据库，此升级场景升级日志会记录大量对象已存在以及主键冲突错误，无法判断升级是否存在其它问题 ，日志位于初次升级完成以后，产品安装目录下Logs文件夹中。 |
| 2 | 高频问题 | 安装部署结果 | 安装程序最后提示语 | 要求安装升级提示成功，不能有警告或者错误，有则须要进行分析处理 。 |
| 3 | 高频问题 | 安装部署结果 | 安装程序日志检查 | all.log日志不能有关键字： ERROR: 若存在则须要分析处理 。 1、err.log日志需要关注错误堆栈信息，如果是无法连接service.seeyon.com可以忽略 2、协同管理软件_Vxx安装*.log日志中警告以及错误数量不为0，则须要分析处理 3、 V8.0SP2版本存在output.log、mod_output.log、replace.log、mod_replace.log日志，记录安装升级部署统一修改html、css文件中的构建关键字STATIC_PATH、STATIC_SUFFIX；output为空，replace记录替换关键字修改的文件清单；若replace日志为空或者文件不存在则会导致功能异常。V8.0SP2版本安装程序20210530更新后已解决 |
| 4 | 高频问题 | 安装部署结果 | 公文升级注意事项 | 1、协同服务低版本升级成功以后，必须备份升级后数据再安排进行公文升级； 2、检查ctp_partition表附件分区信息，确认无误再启动协同服务进行公文升级；需要包含2006-01-01至今时间段分区启用； 3、公文升级需要读取upload，测试升级要求根据提示复制生产环境部分upload文件； 4、公文升级日志记录于当时的ApacheJetspeed/logs_sy/ctp.log；搜索关键字： EdocUpgradeManagerImpl 。若存在错误须要公文开发分析处理 ERROR: EdocUpgradeManagerImpl |
以上图示是升级完成效果，如提示框中存在“升级期间出现了一些错误”字样，则必须及时联系总部支持人员分析是否。
非信创安装程序点击“完成”后，升级日志存放于应用部署目录：A8/Logs下。信创部署工具，升级日志存放于信创部署工具目录下upgrade.log、deploy.log。
1、检查产品安装目录cfgHome/log/年月日_时分秒的xml文件，如D:\Seeyon\A8\cfgHome\log\20210516_073024.xml，其中的所有项状态都是status="success"视为升级程序升级成功；
2、检查A8\Logs\all.log日志，不存在关键字"ERROR:"视为安装升级部署无异常。
检查进程插件Error，可以忽略，不影响本次升级数据：
创建索引已存在Error，可以忽略，说明老版本已经创建过，不影响本次升级数据：
增加字段已存在，说明老版本已经创建过，不影响本次升级数据：
3、err.log，不能存在明显的堆栈信息或者异常信息；
4、STDERR_MSG.LOG，分模块7z文件解压错误日志；除了一行星号没有其它可读的信息视为无异常；
5、STDOUT_MSG.LOG，分模块7z文件解压详细日志，关键字"Extract OK Done Without Errors"和"install sequence SiiBin"数量一致视为无异常；
存在错误的日志案例：
6、协同管理软件_V8.0SP2_安装_05_16_2021_07_37_36.log类似这样文件名的日志，其中有部署各项动作处理结果，以下案例安装部署表示成功无异常：
安装：成功.
215 成功
0 警告
0 无致命错误
0 致命错误
# Ⅲ 异常回滚
如升级失败，不具备上线条件，需要执行回滚动作，回滚事项如下：
1、回滚：还原数据库
还原升级前的数据库，注意检查与升级前数据是否一致，且保证完整没有缺失
2、回滚：还原注册表
标准产品升级需要依赖注册表，因此升级回滚需要将注册表还原：
windows注册表路径 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432NODE\SEEYON
linux注册表路径 /root/.config/seeyoninstall_A8.info
回滚版本与注册表ID映射关系参考在线文档 https://open.seeyoncloud.com/v5doc/142/189.html
3、回滚：还原应用目录
备份的应用文件存放于ApacheJetspeed同级名为Backup的文件夹下。
# Ⅳ 事后
在检查升级日志无误后，可以开始做启动系统前准备及启动验证工作。
# 1、备份升级后的数据库
参考部署手册中的备份数据库方法，备份升级后的数据库，此步大有作用！
备份升级后的数据库！
备份升级后的数据库！
备份升级后的数据库！
# 2、执行环境检查工具
使用前面章节提前下载的“环境检查工具”，再次对升级后的生产环境做检查，按照检查报告做相应调整可以避免升级后系统性能问题。
# 3、做好中间件配置
非信创环境，通过SeeyonConfig应用配置器检查相关参数是否配置正确。
信创环境，通过信创中间件做服务部署。
# 4、打综合补丁包
（如发过支持单）总部会给一个当前升级版本的“综合补丁包”，此包解决升级后常见BUG，打综合补丁包能极大降低生产上线后的问题数量。
# 5、基本安全基线防护
此场景需要根据客户安全基线要求进行防护，如客户对安全有高要求，可以参考发版文档-安全加固-致远安全部署手册进行配置。
# 6、启动系统进行表单样式升级、公文升级
请务必确保参考“备份升级后的数据库”进行了备份，备份数据库之后再做此步升级操作，如果此步操作失败也方便回滚重新升级。
首先检查ctp_partition表附件分区信息，确认无误再启动服务升级公文；
公文升级日志记录于当时的ApacheJetspeed/logs_sy/ctp.log；搜索关键字：EdocUpgradeManagerImpl
若存在错误须要公文开发分析处理，错误关键字： ERROR: EdocUpgradeManagerImpl
# 7、启动升级后服务器并验证
以上完成后，启动协同服务，并进行功能验证。
# 高频环境问题处置办法
| 序号 | 分类 | 类别 | 检查项 | 检查要求及标准 |
|---|---|---|---|---|
| 1 | 高频问题 | 协同服务配置 | jvm参数调优 | 1、0-200在线，服务器内存16G，jvm配置8G 2、200-500在线，服务器内存32G，jvm配置16G 3、500-1000在线，服务器内存48G，jvm配置32G 4、1000-2000在线，服务器内存64G，jvm配置48G 5、2000-3000在线，服务器内存96G，jvm配置64G 6、3000以上在线，服务器内存128G，jvm配置96G 需要添加两项jvm参数位于-Xmx参数之后空格隔开 -XX:MaxMetaspaceSize=2G -XX:ReservedCodeCacheSize=1G 注意：以上配置为应用服务器独享内存资源，如果数据服务集中部署则必须给应用服务按以上要求留出足够的资源。 |
| 2 | 高频问题 | 协同服务配置 | 安全设置 | 安全设置：账号和密码明文传输安全检查， 推荐部署https访问 |
| 3 | 高频问题 | 协同服务配置 | 端口检查 | 1、协同服务访问端口不推荐设置为公认端口（WellKnownPorts，从0到1023）除了80以外的其它端口； 2、各服务端口推荐设置为注册端口（RegisteredPorts，从1024到49151）除了以下非安全端口以外的其它端口： 2049, // nfs 3659, // apple-sasl / PasswordServer 4045, // lockd 6000, // X11 6665, // Alternate IRC [Apple addition] 6666, // Alternate IRC [Apple addition] 6667, // Standard IRC [Apple addition] 6668, // Alternate IRC [Apple addition] 6669, // Alternate IRC [Apple addition] 各服务端口不推荐设置为动态/私有端口（Dynamicand/orPrivatePorts，从49152到65535）范围内的端口。 |
| 4 | 高频问题 | 协同服务配置 | 集群环境 防火墙配置 | V7.1系列集群，协同系统配置工具设置节点的 Locator、Cache 服务端口，并在防火墙中设置放行这两个端口，以及 9009~9020 之间端口（TCP、UDP协议均需要设置放行），节点间要求互通 ，未进行防火墙配置则会出现集群从节点启动卡住于同步主节点加密信息 |
| 5 | 重点问题 | 安装部署结果 | 集群环境 注意事项 | 集群主节点进行产品升级，从节点禁止再次进行产品升级 从节点只需复制升级后主节点整个部署目录并在各个节点修改集群配置 集群从节点不能放置加密，只有主节点放置加密 特别注意事项： 1、V8.0以及以上版本，测试环境禁止连接生产环境redis服务，特别注意克隆/复制生产环境作为测试环境 2、V8.0以及以上版本，集群redis缓存服务配置检查，各个节点需要保持一致，连接同一个redis服务或者同一个redis集群服务 3、V8.0以及以上版本，redis需要关闭rdb持久化 3.1、检查redis.conf文件，注释以下配置： # save 900 1 # save 300 10 # save 60 10000 # dbfilename dump.rdb dbfilename "" 3.2、停止OA服务。停止redis服务，删除dump.rdb，启动redis服务。启动OA服务。 4、集群主从节点插件配置不一致问题 问：集群从节点打开协同系统配置，很多配置项灰色无法修改，从节点具体插件配置不正确。 答：集群从节点插件配置存在历史配置项存留于配置文件，检查base/conf目录下 plugin.properties、systemCtp.properties两项配置文件，同步主节点其中内容至从节点，或者拷贝主节点此两个文件覆盖至从节点。 |
| 6 | 重点问题 | 协同服务配置 | 集群环境 公共资源目录 | 如果是迁移服务器（服务器变更、安装目录变更） 必须拷贝原部署目录下的base/resources目录 协同服务V8.0系列集群部署此目录必须统一为同一个物理存储地址 |
| 7 | 重点问题 | 协同服务配置 | 集群环境 附件目录 | 如果是迁移服务器（服务器变更、安装目录变更） 必须拷贝原部署目录下的base\upload目录，否则公文会升级失败或正文丢失 |
| 8 | 高频问题 | 协同服务配置 | 静态资源缓存大小 | ApacheJetspeed\webapps\seeyon\META-INF\context.xml 要求配置文件其中数值如下或者更高 cacheMaxSize="512000" |
| 9 | 重点问题 | 安装部署结果 | office转换分离部署注意事项 | 需要将启动参数中的hostname=127.0.0.1的IP地址修改成服务器实际的IP地址 |
| 10 | 高频问题 | 协同服务配置 | Oracle数据库 jvm参数配置 | 编辑ApacheJetspeed/bin/catalina_custom.bat以及catalina_custom.sh文件增加以下两项jvm参数： -Doracle.jdbc.useNio=false -Doracle.jdbc.javaNetNio=false |
| 11 | 高频问题 | 协同服务配置 | 线程池配置、连接池配置 | 线程池：总线程数4096，最小空闲数100 连接池：最小30，最大500 |
| 12 | 性能问题 | 内存溢出或者进程崩溃 | 内存溢出 | ApacheJetspeed/bin/目录下是否有 .bin 、.hprof、 hs_err_pid* 这三类文件，存在近期修改的文件联系技术支持分析 ， 检查服务器内存占用是否正常，多个服务运行总内存是否低于服务器总物理内存大小。 Windows：任务管理器详细信息或者rammap工具查看 ， Linux：通过top、free -g命令查看 |
| 13 | 高频问题 | web服务配置 | nginx-https部署需要修改Server.xml | 在 |
| 14 | 高频问题 | web服务配置 | nginx-http访问配置 | http访问配置，非80端口注释掉参数： proxy_set_header X-Forwarded-Proto $scheme; |
| 15 | 高频问题 | web服务配置 | nginx-upstream配置 | 举例： upstream seeyon_v5_cluster{ sticky; server 172.20.2.20:80 max_fails=300 fail_timeout=30s; server 172.20.2.19:80 max_fails=300 fail_timeout=30s; } 其中 server 172.20.2.20:80 、server 172.20.2.19:80 改成协同服务真实ip以及端口。 1、 V7.1系列集群限制最多部署两个节点。 2、max_fails=number设定Nginx与服务器通信的尝试失败的次数。在fail_timeout参数定义的时间段内，如果失败的次数达到此值，Nginx就认为服务器不可用。在下一个fail_timeout时间段，服务器不会再被尝试。 |
| 16 | 高频问题 | web服务配置 | Apache HTTP Server作为负载均衡以及反向代理服务之特殊配置 | 1、ApacheJetspeed/conf/server.xml启用ajp协议绑定ip并设置访问密钥 2、注释ApacheJetspeed\webapps\seeyon\WEB-INF\web.xml中spring-session内容 3、Apache/conf/workers.properties设置匹配的ip以及访问密钥 详见：V8.0SP2LTS集群部署手册 |
| 17 | 网络需求 | 网络访问需求 | 小致 | 小致通过云联开通后，需要重启OA服务器即可体验小致 如果用户是纯内网环境，请保证以下地址能被访问 访问百度外网： 1、https://aip.baidubce.com 2、http://yuyin.baidu.com 3、http://vop.baidu.com 4、https://openapi.baidu.com 5、http://tsn.baidu.com 6、https://tsn.baidu.com 7、http://153.3.236.19 8、https://153.3.236.19 9、https://153.3.236.16 10、http://153.3.236.20 11、https://aip.baidubce.com 访问云联认证的域名 12、https://mplus.seeyon.com |
| 18 | 网络需求 | 网络访问需求 | M3消息推送服务 | 如果用户是纯内网环境，请保证以下地址能被访问 https://msg.seeyon.com |
| 19 | 网络需求 | 网络访问需求 | 天气栏目 | https://restapi.amap.com/v3/weather/weatherInfo?key=303e24733ada73ca23760ac77f19701b https://restapi.amap.com/v3/ip?key=303e24733ada73ca23760ac77f19701b |
| 20 | 高频问题 | web服务配置 | nginx-location配置 | proxy_set_header Host $host:$server_port; 外网映射端口与nginx端口不一致时，以上配置会导致http访问异常，需要改为 proxy_set_header Host $http_host; http访问配置为非80端口，需要删除 proxy_set_header X-Forwarded-Proto $scheme; |
